break
5ee8e3cb4a
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 1m30s
- 新增 OpenSpec Change fix-employee-collection-route-prefix，承载已落地的 ff1362d 路由前缀修复（无规格 delta，skip_specs）
- 记录根因（Register 的 basePath 只服务文档）、影响面（7 条根级残留、15 条同层抢占）、修复方式与验证方式
- AUG26-017 全局健康门禁实际通过后勾选 5.7（tasks 27/27）
42 lines
7.7 KiB
Markdown
42 lines
7.7 KiB
Markdown
## 1. 允许范围与交集
|
||
|
||
- [x] 1.1 在 `pkg/constants/system_config.go` 新增代理在线自充允许方式的配置 Key 与三个稳定取值常量，默认值为同时支持；在 `internal/bootstrap` 按既有支付方式配置注册该 Key，使用 `ValueType=string` 与 `EnumValues` 约束取值。
|
||
- [x] 1.2 实现允许范围的读取封装：以 `systemconfig.Reader.GetStrict` 读取并把取值映射为允许的 `wechat`/`alipay` 集合，配置未落库时使用代码注册默认值，配置非法时失败关闭。
|
||
- [x] 1.3 在 `internal/application/agentrecharge/online_creation.go` 的 `AvailablePaymentMethods` 中把可见角色从仅代理放开为代理与平台账号，并将返回方式改为"允许范围 ∩ 商户池可用方式"的有序列表；交集为空时返回空列表而不报错。
|
||
- [x] 1.4 在 `OnlineCreationService.Execute` 的域校验之后、读取店铺事实之前加入允许范围校验，拒绝不在交集内的支付方式，且不新建充值单或支付单；确认无可用商户时既有 `CodeNoPaymentConfig` 失败路径保持不回退历史支付配置。
|
||
- [x] 1.5 新增 `GET /agent-self-recharge-payment-methods`（代理与平台账号可查实际可用方式）与 `PUT /agent-self-recharge-payment-methods`（仅超级管理员，复用受控配置写服务以获得前后值审计），注册为 `/api/admin` 下的独立单段路由组并在组内显式声明读写角色门禁（需求路径与既有 `/api/admin/agent-recharges` 前缀不同，无法继承该组的企业账号门禁），并确保响应不包含允许范围、商户身份或凭证。
|
||
|
||
## 2. 线下预存款审批字段与 Schema
|
||
|
||
- [x] 2.1 新增成对迁移为 `tb_agent_recharge_record` 增加 `external_transaction_no`、`offline_payment_method_id`、`offline_payment_method_code`、`offline_payment_method_name` 与 `other_voucher_keys` 列（含注释与查询索引），保持可空以兼容历史行；不修改任何既有迁移，不新增唯一约束，不改动既有 `payment_transaction_id` 的定义与写入方。
|
||
- [x] 2.2 扩展 `OfflineCreationCommand` 与线下创建用例：接收并校验启用的线下收款方式字典项（不存在或已停用即拒绝）、必填的交易流水号（取值来自识别支付单号并经人工确认）与可选其他凭证，在同一事务保存收款方式三列快照、交易流水号与其他凭证对象键，并保持既有审批实例关联与审计不变；交易流水号不得参与去重或入账前置判定。
|
||
- [x] 2.3 确认交易流水号写入路径与在线渠道事实隔离：`external_transaction_no` 的写入 MUST NOT 触碰 `payment_transaction_id`、`payment_channel`、支付状态与钱包，且不影响 Outbox 入账消费者的对账判定。
|
||
- [x] 2.4 扩展 `internal/application/wecom/scene.go` 中 `offline_recharge_approval` 的可映射业务字段白名单，加入线下收款方式与其他凭证字段，并在审批请求快照中带入对应值；不修改其他场景的字段定义与业务类型 CHECK。
|
||
- [x] 2.5 扩展线下收款方式字典的"被引用"判定，使已被代理充值申请引用的字典项不可物理删除且编码不可修改，仅可停用；不改变员工账单建账、核销申请、分摊与退款冲销逻辑。
|
||
- [x] 2.6 在代理充值详情与列表投影中返回收款方式快照、交易流水号与其他凭证对象键引用，且不返回凭证内容。
|
||
|
||
## 3. 付款凭证识别预填
|
||
|
||
- [x] 3.1 在 `internal/gateway` 新增付款凭证识别能力，封装识别接口并按需传入 `image_base64`；不使用会打印完整响应体的泛型入口，改为自行反序列化并只记录路径、耗时与结果摘要。
|
||
- [x] 3.2 实现应用层识别用例：按附件对象键读取对象存储、校验对象存在非空且为图片类型、编码为 base64 后调用 Gateway，只将 `order_number` 返回为交易流水号预填值；`amount`、`remark`、`payment_method`、`payee` 与 `payment_time` 均不返回、不预填、不写入任何业务字段。识别结果不落库、不写入任何资金事实字段。
|
||
- [x] 3.3 新增 `POST /agent-recharges/payment-voucher-ocr` 路由与 Handler，复用既有代理充值组门禁，成功响应只含交易流水号预填值；非图片、对象不存在或识别服务失败时返回明确失败且不阻断人工填写。
|
||
- [x] 3.4 确认识别调用路径的日志、审计与错误不包含凭证内容、base64 载荷或识别原始结果。
|
||
|
||
## 4. 路由、文档与装配
|
||
|
||
- [x] 4.1 为新增的两个端点补齐可执行路由注册、`cmd/api/docs.go` 与 `cmd/gendocs/main.go` 的占位装配，以及 `pkg/openapi/handlers.go`、`internal/bootstrap/types.go`、`internal/bootstrap/handlers.go` 的 Handler 装配（沿用既有代理充值 Handler 时确认无需新增装配点）。
|
||
- [x] 4.2 按 ENG-DTO-001 补齐请求与响应 DTO 的中文 description、枚举与 `pkg/constants` 一致，金额使用分，时间使用带时区 RFC3339。
|
||
- [x] 4.3 更新 `docs/integrations/gateway/README.md` 的当前实际使用范围与核验证据，纳入付款凭证识别能力；不得写入凭证、密钥或识别样本。
|
||
- [x] 4.4 为允许范围修改复用既有受控配置审计动作并在 Change 内确认审计覆盖；新增的申请创建与识别调用按 ENG-AUDIT-001 归入既有事实类型，不新增重复事实。
|
||
|
||
## 5. 验证
|
||
|
||
- [x] 5.1 按 ENG-TEST-001 在维护者指定的 `junhong_cmp_test` PostgreSQL 与 Redis DB 6 上验证：迁移从本地工作区以显式 `DB_*` 执行 `scripts/migrate.sh`，只创建、删除本 Change 自己的 fixture，禁止重置整库。
|
||
- [x] 5.2 验证允许范围：三态取值可维护并留痕、非法取值被拒、未配置时使用默认值、非超级管理员不可读不可写。
|
||
- [x] 5.3 验证交集：允许范围收窄后查询只返回被允许方式；允许方式无可用商户池成员时查询返回空列表且创建被拒绝、不新建充值单或支付单；配置变更后已创建未支付单的支付方式与商户快照不变。
|
||
- [x] 5.4 验证线下字段：引用不存在或已停用收款方式被拒、收款方式快照在改名与停用后保持冻结、缺少交易流水号被拒、重复交易流水号不阻断线下申请、企业微信审批或钱包入账，且不改变 `payment_transaction_id`、`payment_channel`、支付状态、钱包或 Outbox 入账消费者的对账判定；支付凭证与其他凭证分别留存并可在审批详情取得。
|
||
- [x] 5.5 验证识别预填：图片凭证识别成功后返回预填值且未创建申请、人工更正值生效、非图片与识别失败不阻断人工填写、日志与审计不含凭证内容或识别原始结果。
|
||
- [x] 5.6 验证字典引用保护：被代理充值引用的字典项不可删除、编码不可修改、仅可停用。
|
||
- [x] 5.7 执行 `gofmt -w`、`go build ./cmd/api ./cmd/worker`、`go run cmd/gendocs/main.go`、`./scripts/context-health.sh`、`openspec validate add-agent-self-recharge-payment-methods --strict` 与 `openspec doctor --json`；上述全局健康门禁必须一并通过，自动化测试按项目决策为 N/A。验证：六项全部通过——`gofmt -l` 无输出、`go build` 退出码 0、gendocs 成功生成、`context-health.sh` 输出「Context 健康检查通过」退出码 0、`validate --strict` 输出 `Change 'add-agent-self-recharge-payment-methods' is valid`、`doctor --json` 为 `healthy = true`。
|
||
- [x] 5.8 仅在本 Change fixture 已清理、且维护者确认新增收款方式、交易流水号与凭证快照没有留存需求时验证迁移 up/down/up；down 可以删除新增列，但不得影响既有充值记录读取。存在仍需保留的真实新增列数据时不得将 down 视为正常可执行场景，MUST NOT 重置整个 `junhong_cmp_test`。
|