junhong_cmp_fiber/openspec/changes/complete-july-iteration-test-release/design.md

Context

当前状态

七月标准评审稿覆盖 28 条技术/业务线，但实施信息分散在 28 份相关 PRD、121 张七月业务/公共基础 Tickets、22 张全局审计 Tickets、代码、迁移、文档和提交记录中。现有状态存在四类偏差：

1. 完成状态漂移：TECH 公共基础 12/12 与 UR55 5/5 已完成；UR45 代码已落地但两张 Ticket 仍为 ready-for-agent；UR46 四张票仅标记“后端 done”；UR60、UR86 后端已完成但仍有人工作与历史抽样；顶层 PRD 状态普遍未同步。
2. 依赖不可执行：公共通知、UR37、UR48、UR49 存在不存在文件、尚未拆票占位符或标题漂移；多个需求仍把未完成的全局 Audit Event 发布门禁作为 blocker。
3. 跨文档冲突：openspec/config.yaml 仍描述旧 Handler → Service → Store → Model 单一路径、{code,message,...} 和强制 TDD，而当前 AGENTS.md、DDD 规范及用户本次决策已经明确三通道、{code,msg,...} 和测试环境临时豁免。
4. 发布目标改变：目标是 2026-07-27 前部署测试环境，不是生产验收。全局审计提交 ff44305 只完成 Integration Log 基础、Access Log 加固和离线覆盖门禁；integrationlog.Repository 未装配生产组合根，cmd/audit-coverage 不在运行时，现有代码可安全冻结。

权威来源与利益相关方

• 用户本次确认决定是审计/测试/里程碑范围的最高优先级。
• 七月标准评审稿是业务冲突裁决来源；冻结 PRD 保留详细不变量、API、状态机和异常闭环；既有 Ticket 保留已评审纵向切片；代码和提交只证明完成状态。
• 利益相关方包括后端、前端、产品、测试环境验收负责人、运维，以及企微、支付、Gateway、运营商与对象存储配置负责人。

约束

• 技术栈固定为 Go 1.25.4、Fiber v2、GORM、PostgreSQL、Redis、Asynq、Viper、Zap、sonic、Validator，不新增替代依赖。
• 数据库不使用外键或 GORM 关联标签；金额以分为单位；生命周期状态用 int，类型/方式用 string。
• API 使用 {code,msg,data,timestamp}、pkg/errors、后端权限与数据范围、默认 20/最大 100 分页。
• 触碰式迁移以完整用例为单位，禁止顺手重构未触碰旧代码。
• 本 Change 只写 OpenSpec 规划产物；不修改业务代码、不运行测试、不提交 Git。

Goals / Non-Goals

Goals:

• 建立唯一、稳定、可勾选的 28 线总台账和后续唯一实施入口。
• 真实表达后端、前端、验证、发布四个维度，不把代码存在等同验收完成。
• 保留冻结业务规则，将全部未完成工作组织为三批可执行纵向切片，并消除悬空和模糊依赖。
• 在不削弱资金、审批、异步与外部调用可靠性的前提下，形成测试环境快速交付顺序。
• 冻结现有审计代码并解除 Audit Event 对测试环境的阻塞，同时明确生产前恢复清单。
• 统一前后端契约、停机部署、回滚和延期验证边界。

Non-Goals:

• 不重写、废弃或回填全部原 PRD/Tickets，也不再创建一批 .scratch/issues。
• 不实施任何七月业务代码、迁移、前端页面或运行时配置。
• 不加入需求16，不创建 distribution 领域或任何分销/提现能力。
• 不继续开发 Audit Event Writer、审计中心、历史投影、审计导出、保留清理或一次性审计切换。
• 不删除 ff44305、pkg/sanitizer、tb_integration_log 迁移或其他已有可靠性代码。
• 不新增/运行自动化测试，不执行真实外部验收；这些只作为生产前延期项。

Decisions

1. 使用三个总控 capability，而不是复制 28 份业务规格

本 Change 使用 july-iteration-master-ledger、july-iteration-delivery-contract、july-iteration-test-release-gate 三个新能力。业务细节继续引用标准评审稿与冻结 PRD，tasks.md 则把每条线落实为具体纵向任务。

理由：统一 Change 的职责是建立权威台账、执行依赖和发布契约；完整复制 28 份 PRD 会制造第二套易漂移业务真相。

否决方案：为每个 UR 建一个重复 spec。该方案文件数量大、易与冻结 PRD 不一致，也违背“不重写原 PRD”的定位。

2. 多维状态替代单一完成状态

每条线记录后端、前端、验证、发布四维状态，并允许“元数据待收口”。初始证据如下：

稳定编号	初始后端状态	前端/验证状态	证据结论
JULY-TECH-FOUNDATION	已完成	本仓交付完成	PRD completed、12/12 Tickets、提交 17782d5/7e0171a
JULY-UR55	已完成	跨仓状态不可独立证明	5/5 Tickets、提交 9818537 等；PRD 顶层滞后
JULY-UR45	后端完成	前端/人工待确认	提交 55bdc3a；2 张 Ticket 元数据未收口
JULY-UR46	后端完成	前端/人工未完成	4/4 done（后端）、提交 8d65b26 等
JULY-UR60	后端完成	前端联调/人工未完成	2 completed + 1 ready-for-human
JULY-UR86	后端完成	前端/历史抽样未完成	1 completed + 1 blocked、提交 c58773e
其余 22 条	未开始	未开始	PRD/Tickets 均未形成业务实现证据

理由：防止把“代码已存在”“测试曾写过”“Ticket 元数据完成”“测试环境部署”混为同一事实。

否决方案：只使用 [x]/[ ] 标记整条需求。它无法表达后端完成但前端、人工或生产门禁未完成。

3. 按当前 DDD 三通道覆盖旧配置中的单一路径

任务采用：复杂写 Handler → Application → Domain → Repository/Infrastructure；简单写 Handler → Application 事务脚本 → Persistence；读取 Handler → Query → GORM/DTO。旧 Handler → Service → Store → Model 只保留给未触碰旧用例。

依赖注入继续使用结构体字段/构造器显式注入 Application、Query、Repository、Adapter、Outbox、Integration Log 与配置；Domain 不依赖 Fiber/GORM/Redis。常量进入 pkg/constants，Redis Key 由函数生成。

理由：这是当前 AGENTS.md 和 DDD 规范的触碰式演进合同，比 openspec/config.yaml 的旧上下文更新且更具体。

否决方案：强制所有新需求继续堆入旧 Service，或全仓一次性 DDD 重构；前者扩大旧 Service，后者超出当前完整用例边界。

4. 三批实施与稳定依赖图

flowchart TD
    PF[JULY-TECH-FOUNDATION 已完成]
    N[B1-01 公共通知]
    W[B1-02 UR37 企微]
    C[B1-03 UR38 信用钱包]
    S[B1-04 UR94 卡状态]
    G[B1-05 UR43 系列授权]
    L[B1-06 UR47 限速]
    P[B1-07 UR48 支付方式]
    O[B1-08 UR96 业务员]
    X[B1-09 UR98 换货继承]
    R40[B2-01 UR40 可售策略]
    R73[B2-02 UR73 复机]
    R53[B2-03 UR53 实名筛选]
    R62[B2-04 UR62 H5 顺序]
    R97[B2-05 UR97 余额预警]
    R36[B2-06 UR36 批量订购]
    R49[B2-07 UR49 设备批量]
    R34[B3-01 UR34 充值]
    R35[B3-02 UR35 退款]
    R57[B3-03 UR57 禁止换货]
    R33[B3-04 UR33 临期]
    R44[B3-05 UR44 摘要]
    R42[B3-06 UR42 导出]
    PF --> N & W & C & S & G & L & P & O & X
    S --> R73 & R53 & R62
    C --> R97 & R36 & R34 & R35
    O --> R97 & R33
    N --> R97 & R34 & R35 & R33
    R40 --> R36 & R33
    R36 --> R49
    W --> R34 & R35 & R44
    R35 --> R57 & R44
    R34 --> R44
    R33 --> R42
    R44 --> R42

UR46 已完成后端并作为 B3-04/B3-06 的已满足后端依赖；UR55 已满足 UR46。UR45、UR46、UR60、UR86 只进入最终前端/人工/元数据收口，不重复实现后端。

理由：先交付公共写入、资金和外部系统边界，再交付依赖它们的业务，最后组合复杂业务，可消除原 .scratch 的悬空引用。

否决方案：按数据库、Service、Handler 水平排期，或让下游先各自复制公共能力；两者都会制造重复实现和不可验证中间态。

5. 原 Tickets 保留业务粒度，但统一移除测试与 Audit Event 阻塞

已有 Tickets 的业务切片 SHALL 在对应总任务内逐项映射；原本纯自动化 Harness、验收测试、真实外部门禁或 Audit Event 写入子项不在本测试环境实施。它们移动到“延期验证与生产门禁”，而不是被标记完成。不存在路径和占位符改为本 Change 的稳定任务号：

• 公共通知 04 改依赖 B1-08.6，不再引用不存在的 UR96 文件名。
• UR37-01～13 形成可供 UR35 使用的公共能力；原 UR37-14“退款首个真实企微门禁”改映射到生产前 6.2，不再保留“UR35 拆票后替换”的占位符，也不反向阻塞 UR35 代码实现。
• UR48/UR49 发布依赖使用本 Change 任务号，不依赖漂移标题。
• 所有 .scratch/tech-global-audit/issues/01、19、20、21 等 Audit Event 阻塞边在测试环境路径删除，转入生产前 6.* 延期清单。

理由：用户已明确授权测试和审计范围调整；保留旧 blocker 会让测试环境目标不可执行。

否决方案：修改原 Tickets。原 Tickets 需要保留评审历史，本 Change 只提供新的执行映射。

6. 前后端契约以“冻结字段 + 状态矩阵 + 人工验收点”管理

每条涉及 API 的纵向任务记录 Endpoint、请求字段、完整 data、用户类型、资源所有权、分页/排序/过滤、错误码、状态/枚举、前端页面与异常状态。响应包络一律为 {code,msg,data,timestamp}，参数错误使用 CodeInvalidParam，资源不存在/越权使用 CodeForbidden 统一语义。

当前仓库无前端源码，因此后端任务只交付 OpenAPI、样例、字段和框架无关交互；前端完成必须由外部仓库或人工证据单独勾选。新增 Handler 同步 cmd/api/docs.go 与 cmd/gendocs/main.go。

理由：可以防止后端代码完成被误记为全链路完成，同时给前端明确实现输入。

7. 资金、审批、异步与外部调用保留完整异常闭环

• 资金：钱包余额/版本/流水是 Domain Ledger；扣款、冻结、入账、退款按唯一业务键、乐观锁/条件更新和同事务事实保证；支付成功与钱包入账分阶段，已收款不得因后续失败丢失。
• 审批：企微负责节点/审批人/意见/附件；本地保存业务快照、实例和终态处理。提交结果未知不盲重试；回调与轮询进入同一同步用例；通过后撤销按是否已产生资金事实分流。
• 异步：关键副作用同事务写 Outbox，Relay 投递 Asynq，消费者按至少一次与处理租约设计；任务五态和业务成功/失败计数分离。
• 外部调用：Integration Log 在请求/回调边界记录脱敏尝试、结果未知和恢复事实；支付、企微、Gateway、运营商状态不得由日志替代业务表。
• 错误：Application/Domain/Query 使用 pkg/errors，客户端不接收底层 SDK/GORM/Validator 错误；关键错误使用中文日志并携带稳定关联 ID。

Audit Event 在本测试里程碑不接入新业务，以上 Domain Ledger、Integration Log、Outbox、事务和幂等均不得延期。

8. 审计冻结对运行时无新增影响

边界保持：Access Log 负责 HTTP 调试；Audit Event 负责操作者治理但本轮冻结；Domain Ledger 负责金额/状态事实；Integration Log 负责外部交互；Outbox 负责可靠投递。

ff44305 的运行时分析为：

• integrationlog.Repository 当前仅在自身测试实例化，未注入 API/Worker 生产组合根；冻结不会改变现行业务写路径。
• cmd/audit-coverage 扫描仓库并生成离线基线，不属于运行时请求或 Worker。
• pkg/sanitizer 已被 Access Log 复用敏感字段判定，递归遍历、路由策略、摘要和 50KB 截断仍由 logger 包执行，必须保留。
• 000167_create_audit_integration_log 只建独立表与索引，audit_event_id 为普通 bigint，无外键，可保留而不要求启用审计中心。

理由：保留已提交安全和可靠性能力，同时避免半成品 Audit Event 门禁阻塞业务。

否决方案：回滚 ff44305 或删除审计迁移；没有必要且会丢失 Access Log 加固和未来恢复基线。

9. 测试配置冲突由用户本次里程碑决策覆盖

本测试环境里程碑不生成/运行自动化测试。每个批次只执行 gofmt、必要生成、go build ./...、迁移/路由/Worker/配置部署检查。状态使用“代码完成、验证延期”，不写“PASS”。

openspec/config.yaml 的 TDD、覆盖率与 {message} 规则属于通用旧配置；本次用户明确决策、AGENTS.md 和本 Change 的 {msg} 契约优先。生产前必须重新恢复自动化、真实依赖、性能、安全、权限和人工验收。

理由：满足明确交期决定，同时用状态和延期清单控制风险，不伪造证据。

Risks / Trade-offs

• [无自动化回归导致状态机、资金与权限缺陷更晚暴露] → 每批强制构建和部署检查；测试环境限制访问与资金；所有未执行验证进入生产阻塞清单，禁止沿用豁免。
• [三批范围仍大，2026-07-27 前无法全部完成] → 依赖 frontier 可并行，但下游只在具体上游完成后启动；状态台账实时反映未开始和代码完成/验证延期，不通过改状态掩盖延期。
• [原 Tickets 中审计与测试子项被误认为删除] → 在任务映射中标注“测试环境豁免，转 D-*”，生产前必须恢复；原文件不修改。
• [Audit Event 未接入导致测试环境缺少操作者治理证据] → 保留 Access Log、Domain Ledger、Integration Log 和关联 ID；限制为测试环境，生产前完成审计专项。
• [Integration Log Repository 未生产装配但下游以为已可用] → 每个真正需要外部交互的业务纵向任务显式完成 Adapter/组合根装配；不能把迁移存在等同运行时接入。
• [前端仓库不在当前工作区导致后端状态被过度声明] → 前端契约和人工验收独立复选框，后端无法代勾。
• [停机迁移后存在不可逆审批/支付/资金事实] → 开放访问前验证失败可回退；产生事实后暂停生产者、保留流水/Outbox/Integration Log并前向修复，不清表、不恢复旧 Writer。
• [原 PRD 的依赖环阻塞执行] → UR33 先交付临期 Query/通知，UR42 后接导出 Scene；UR34/35 先交付状态模型，UR44 再投影摘要，UR42 最后接 Scene。
• [旧配置与当前规范继续漂移] → 本 Change 明确优先级；不在本次顺手修改 openspec/config.yaml，另行治理。

Migration Plan

规划到实施

1. 冻结本 Change 的 proposal/design/specs/tasks，后续不从分散 .scratch 目录直接启动七月新工作。
2. 按 B1 → B2 → B3 的具体编号领取任务；同批无依赖项可并行，有依赖项顺序执行。
3. 每个需求先完成冻结 PRD 的业务纵向切片，再执行该批 gofmt、必要生成、go build ./... 和部署检查。
4. 完成 F1 已落地需求的元数据/前端/人工收口，再执行 F2 测试环境装配与停机部署。
5. 测试环境运行期间保留 D 组延期项未勾选；生产发布另开恢复窗口逐项完成。

测试环境停机发布顺序

flowchart LR
    Freeze[冻结版本与配置] --> Stop[维护模式/停止相关写入和 Worker]
    Stop --> Migrate[执行增量迁移与前置数据检查]
    Migrate --> Backend[发布 API、Relay、Worker]
    Backend --> Frontend[发布匹配的前端版本]
    Frontend --> Configure[装配企微/支付/Gateway/运营商/对象存储配置]
    Configure --> Check[构建、路由、Worker、迁移、版本一致性部署检查]
    Check --> Resume[恢复 Worker 与访问]

回滚

• 开放访问前：可回滚应用和确认可逆的迁移；未通过检查时保持维护模式。
• 开放访问后：已产生的审批、支付、钱包流水、订单、退款、充值、通知、Outbox、Integration Log 与部分成功批量任务不得删除；暂停异常入口并前向修复。
• 支付成功未入账、审批终态未处理、Outbox 积压必须由恢复 Worker 幂等完成，不能要求用户重复提交或重复付款。
• 信用额度一旦产生负余额，不得回退到忽略信用边界的旧扣款逻辑。

生产发布前恢复门禁

• 自动化测试与完整构建、真实 PostgreSQL/Redis/Asynq 验证。
• 真实企微模板/绑定/附件/回调/轮询，微信/支付宝预下单/查单/回调，Gateway 限速与运营商回调验收。
• 前后端全链路、历史数据抽样、存量迁移和停机演练。
• 权限、分页、N+1、性能、安全、Access Log 敏感矩阵与回滚演练。
• 恢复 Audit Event Writer、业务覆盖、审计中心/历史投影和一次性发布门禁的评审与实施；不得沿用本测试豁免。

Open Questions

无阻塞性业务问题。实现期仍需由部署负责人提供企微、支付、Gateway、运营商、对象存储和前端仓库的测试环境配置与版本，但这些属于执行输入，不改变本 Change 的范围或架构决定。