组织支付记录数据范围修复项目文档 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. 数据范围规则

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. 目录结构与核心文件

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

4.3 KiB Raw Blame History Unescape Escape