# 组织支付记录数据范围修复项目文档 v1.0

## 1. 项目概述

- 项目名称：气站与配送点支付记录数据范围修复。
- 实施范围：`backend/api` 的气站、配送点财务只读接口及对应需求文档。
- 修复目标：移除统一支付单对不存在钱包主键的错误依赖，恢复支付记录列表与详情查询，并保持组织数据隔离。
- 技术栈：Go、Gin、GORM、PostgreSQL。
- 数据库影响：不新增字段、不执行迁移、不修改既有支付事实。

## 2. 问题与根因

`payment_order` 是全项目统一支付尝试事实，通过 `business_type` 和 `business_identity` 关联具体业务。气站与配送点财务查询沿用了旧钱包支付表的通用关联方式，尝试访问不存在的 `payment_order.wallet_basic_id`，导致 PostgreSQL 返回 `SQLSTATE 42703`。

该错误同时影响气站与配送点的支付记录列表和详情接口。数据库结构与统一支付模型一致，不应通过补充钱包主键掩盖查询模型错误。

## 3. 数据范围规则

```text
payment_order
├── business_type = gasorder
│   └── gasorder_basic.identity = business_identity
├── business_type = ec_order
│   └── ec_order.identity = business_identity
└── business_type = recharge
    └── wallet_recharge_order.identity = business_identity
        └── wallet_basic.id = wallet_basic_id
```

- 气站范围分别校验 `gasorder_basic.gas_basic_id`、`ec_order.gas_station_id`，或气站自有充值单及钱包归属。
- 配送点范围分别校验 `gasorder_basic.delivery_basic_id`、`ec_order.delivery_point_id`，或配送点自有充值单及钱包归属。
- 查询使用 `EXISTS`，同时匹配业务类型和业务标识，避免不同业务表的标识偶撞。
- 未知业务类型、业务对象缺失及无法证明组织归属的记录按失败关闭处理。
- 列表和详情复用同一范围过滤器；详情增加支付单 `identity` 条件，不放宽组织校验。
- 关联业务记录归档后，只要事实仍存在且可验证归属，支付记录仍可读取。

## 4. 目录结构与核心文件

```text
platforms/
├── backend/api/internal/logic/
│   ├── common/
│   │   ├── payment_scope.go             # 统一支付组织范围过滤器
│   │   └── payment_scope_test.go        # PostgreSQL 查询边界回归测试
│   ├── gas/finance.go                   # 气站支付列表与详情接入
│   └── delivery/finance.go              # 配送点支付列表与详情接入
└── docs/
    ├── 06-气站管理系统需求.md
    └── 07-配送点管理系统需求.md
```

`ScopePaymentOrdersByOwner` 只接受 `gas` 和 `delivery` 两种主体类型。其他类型统一追加 `1 = 0`，避免调用方参数错误导致越权。

## 5. 接口兼容性

- 保持既有 API 路径、分页参数、响应结构和排序不变。
- 不修改 `PaymentOrder` 模型、支付创建、渠道回调、余额扣款和退款流程。
- 钱包余额支付目前直接写入 `wallet_record`，本次不将其拼装为虚拟 `payment_order`。
- 当前用户和工作人员充值不属于气站或配送点支付范围；未来只有组织自有充值单且钱包归属一致时才会被查询。

## 6. 测试与维护

- 回归测试覆盖燃气配送订单、商城订单、组织自有充值三类归属路径。
- 分别断言气站和配送点字段，防止跨组织字段混用。
- 断言未知主体失败关闭、详情保留组织边界，且 SQL 不再引用 `payment_order.wallet_basic_id`。
- 后续新增支付业务类型时，必须先明确其组织归属链路，再扩展公共过滤器和对应测试；不得通过付款用户反推组织。

## 7. 已知边界

- 未完成的燃气配送支付尝试跟随订单当前配送点；成功支付后订单状态不允许再次分配，因此成功支付事实归属稳定。
- 钱包余额支付统一创建 `payment_order` 属于后续资金链路设计事项，不纳入本次缺陷修复。
- 支付创建入口的业务类型白名单属于独立安全加固事项，本次查询只负责对未知类型失败关闭。

## 8. 变更记录

- v1.0：修复气站与配送点统一支付记录错误关联钱包主键的问题，补齐组织范围测试和需求口径。