platforms/docs/操作日志_组织支付记录数据范围修复_20260819.md

组织支付记录数据范围修复操作日志

操作时间：2026-08-19 21:16:03

操作类型：修改、扩展

影响模块：后端 API、气站管理端财务、配送点管理端财务、需求文档

操作前状态

• 气站与配送点支付记录沿用旧钱包子表查询，执行 payment_order.wallet_basic_id 关联。
• 统一支付模型没有 wallet_basic_id，列表与详情请求触发 PostgreSQL SQLSTATE 42703。
• 气站需求把统一支付单描述为钱包范围，配送点需求仍使用已删除的 wallet_payment、wallet_refund 名称。
• 缺少统一支付记录的组织数据范围回归测试。

具体操作

1. 新增公共支付范围过滤器，分别通过燃气配送订单、商城订单和组织自有充值单验证气站或配送点归属。
2. 未知业务类型、孤立业务对象和无法证明组织归属的充值记录按失败关闭处理。
3. 气站与配送点支付列表、详情改为复用同一过滤器，删除对支付单钱包主键的错误依赖。
4. 增加 PostgreSQL SQL 回归测试，覆盖三类业务、两类组织、详情边界和未知主体。
5. 修正气站与配送点需求文档的统一支付事实、组织归属和钱包余额支付边界。
6. 新增项目文档，记录问题根因、查询结构、兼容性和后续维护规则。

行为变化

• 修改前：进入气站或配送点“支付记录”页面后，查询不存在的字段并返回数据库错误。
• 修改后：支付记录按关联业务对象验证当前组织归属，列表与详情可正常查询。
• 修改后：跨组织、未知类型、业务对象缺失、用户或工作人员充值不会进入组织端结果集。
• 保持不变：接口路径、分页、排序、响应结构、支付模型、支付创建、渠道回调、余额支付、退款和数据库结构。

代码变更

• backend/api/internal/logic/common/payment_scope.go
  • 新增 ScopePaymentOrdersByOwner，统一追加气站或配送点支付数据范围。
  • 使用三组 EXISTS 验证 gasorder、ec_order、recharge 业务对象。
• backend/api/internal/logic/common/payment_scope_test.go
  • 新增气站、配送点、失败关闭及详情一致性测试。
• backend/api/internal/logic/gas/finance.go
  • 新增 paymentOrderQuery；修改 ListPaymentOrder、GetPaymentOrder。
• backend/api/internal/logic/delivery/finance.go
  • 新增 paymentOrderQuery；修改 ListPayment、GetPayment。
• docs/06-气站管理系统需求.md
  • 将支付记录从钱包直接归属修正为业务对象验证归属。
• docs/07-配送点管理系统需求.md
  • 修正统一支付与退款资源名称及组织归属口径。
• docs/项目文档_组织支付记录数据范围修复_v1.0.md
  • 新增完整项目说明、目录结构、兼容性和维护指南。

验证结果

• go test ./internal/logic/common ./internal/logic/gas ./internal/logic/delivery：通过。
• go test ./...：通过。
• go vet ./...：通过。
• go build ./cmd/main/main.go：通过。
• 平台总后台 pnpm contract:check：通过，共 48 个资源。
• 气站管理端 pnpm contract:check：通过，共 20 个资源。
• 配送点管理端 pnpm contract:check：通过，共 18 个资源。
• git diff --check：通过，无空白错误。
• 定向搜索确认生产代码不再包含 payment_order.wallet_basic_id 或对应错误关联。

边界案例

• 归档业务对象仍可凭现存业务标识验证组织归属，不因业务状态归档丢失支付事实。
• 未完成的燃气配送支付尝试跟随订单当前配送点；成功支付后订单不可重新分配，成功事实归属稳定。
• 充值记录同时校验充值单主体和钱包主体，避免仅凭可伪造或漂移的单一字段放行。
• 详情接口必须同时满足支付单标识和组织范围，不允许通过猜测 UUID 越权。

风险评估

• 查询新增关联子查询，依赖现有业务标识和组织字段索引；数据量增长后应关注执行计划和慢查询指标。
• 钱包余额支付当前只形成 wallet_record，仍不会显示为 payment_order；统一建单属于后续资金链路设计，不在本次修复范围。
• 支付创建入口尚未增加业务类型白名单；本次查询已对未知类型失败关闭，写入侧加固应独立评审。
• 本次不涉及数据库迁移，回滚只需恢复查询代码和文档，不影响既有支付事实。