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