完善公共基础接入与全局审计闭环
This commit is contained in:
@@ -18,6 +18,8 @@ Access Log 当前只递归脱敏请求体，响应体仍原样记录，登录 To
|
||||
|
||||
本次切换覆盖全部现有敏感写操作：新旧业务统一使用 Audit Writer，旧账号、资产和手动轮询审计表停止新增，不双写；历史数据保留原表并通过 Query 只读投影到新审计中心。切换准备或验证失败则本次版本整体不放量，不能以局部模块继续写旧表作为中间态。
|
||||
|
||||
“全部现有敏感写操作”以仓库级《审计覆盖基线》为可验收证据，不以七月迭代需求清单代替。基线必须覆盖所有状态变更、敏感读取、关键拒绝和失败入口，并对 Audit Event、Domain Ledger、Integration Log、Outbox 或 N/A 作出逐入口决定。
|
||||
|
||||
## User Stories
|
||||
|
||||
1. 作为审计人员，我希望回答谁在什么入口对哪些资源做了什么，结果、风险和前后变化是什么。
|
||||
@@ -53,6 +55,7 @@ Access Log 当前只递归脱敏请求体，响应体仍原样记录，登录 To
|
||||
|
||||
### 动作注册表与写入可靠性
|
||||
|
||||
- 实现 Writer 前先完成全仓审计面盘点。每个 Handler、Application、Service、Worker、定时任务和回调入口都必须登记业务所有者、动作、资源、事务边界、失败策略和确认测试；N/A 必须写明理由并经评审。
|
||||
- 建立 Action Registry，定义稳定动作编码、中文名称、类别、默认风险、允许的资源类型和敏感字段规则；DTO 枚举说明、筛选项和前端名称都从同一注册表生成。
|
||||
- 至少覆盖账号/角色/权限、店铺、资产、套餐、钱包/资金、订单/退款/充值、企微、支付与系统配置、数据同步、导入导出及登录安全的本期动作。未经注册的动作不得写入生产审计。
|
||||
- 钱包余额、人工退款结果、代理钱包回退、线下充值入账、账号角色/权限、支付/企微/关键系统配置、人工卡状态、敏感店铺业务员归属及手工绑定企微审批号等成功事件必须与业务变更同事务 `AppendWithTx`；审计失败则业务事务回滚。
|
||||
@@ -61,6 +64,7 @@ Access Log 当前只递归脱敏请求体，响应体仍原样记录，登录 To
|
||||
- 异步系统事件与状态变化通过原业务事务或 Outbox 可靠关联，不使用 `go func()`。Asynq/Outbox 载荷必须传递 `event_id/request_id/correlation_id/parent_event_id`。
|
||||
- `request_id` 由现有中间件生成并贯穿同一 HTTP 请求；`correlation_id` 在退款、充值、审批、钱包、卡状态等跨请求业务起点生成并贯穿 Outbox/Asynq/Integration Log；`parent_event_id` 表示直接因果，不用于替代 correlation。
|
||||
- 对全部旧审计调用建立切换清单和自动检查。发布产物中禁止继续调用旧 `account_audit/asset_audit` 写服务或直接 Create 旧日志模型；启动装配不再注入旧 Writer。
|
||||
- 系统配置更新和 Outbox 人工恢复必须在各自 Application 组合根注入正式 Audit Writer：业务事实与审计同事务，未装配或审计失败时失败关闭；不得回退到空 Adapter、临时表或裸 goroutine。
|
||||
|
||||
### Integration Log
|
||||
|
||||
@@ -131,6 +135,8 @@ Access Log 当前只递归脱敏请求体，响应体仍原样记录，登录 To
|
||||
- 领域/Application 测试覆盖事件不可变、多资源至少一个 primary、动作注册、风险默认值、内容哈希稳定、16KB 截断和禁止字段删除。
|
||||
- PostgreSQL 集成测试验证唯一/查询索引、关键业务与 Audit Event 同事务、审计写入失败回滚、失败/拒绝短事务、重复事件幂等和资源时间线。
|
||||
- 对账号、角色权限、资产、套餐、钱包、退款、充值、配置、导入导出、登录安全和手动同步建立切换清单；自动测试或静态检查证明生产装配不再调用旧 Writer，旧三表发布后无新增。
|
||||
- 覆盖基线测试或静态检查证明仓库内全部状态变更、敏感读取、关键拒绝和失败入口均已分类；新增敏感入口未登记、动作未注册或 N/A 缺少理由时门禁失败。
|
||||
- 公共基础 Adapter 集成测试覆盖系统配置更新和 Outbox 人工恢复的成功同事务、审计失败整体回滚、敏感值不落库、恢复原因与批次留痕以及生产组合根装配。
|
||||
- 历史投影测试使用旧账号/资产/手动轮询样本，验证 `UNION ALL` 的字段映射、确定性历史键、分页排序、`record_source` 和新旧交界时间无重复/漏项。
|
||||
- Integration 测试覆盖 outbound 成功/失败/响应未知、inbound 回调、未发送的 merged/rate_limited/completed、同序列 0/3/5、状态变化关联 Audit Event 和重复回调。
|
||||
- Access Log 测试覆盖嵌套 JSON、数组、非 JSON、登录/Token、支付/企微/运营商回调、上传下载和响应体，证明 Token、Secret、操作密码、签名 URL、Authorization、Cookie 等不落盘且 50KB 生效。
|
||||
@@ -154,6 +160,7 @@ Access Log 当前只递归脱敏请求体，响应体仍原样记录，登录 To
|
||||
## Further Notes
|
||||
|
||||
- 用户已明确确认一次性全局切换，覆盖标准稿中的“旧写停止、不双写、历史只读投影”口径；这不是可由实现阶段改回渐进双写的建议项。
|
||||
- 全系统覆盖由 `00-full-audit-surface-inventory.md` 建立基线，系统配置由 `20-system-config-audit-adapter.md` 接入，Outbox 恢复由 `21-outbox-recovery-audit-adapter.md` 接入，最终统一由 19 号票验收；后续业务 PRD 也必须增量维护该基线，不能把“公共审计已完成”理解为新业务自动获得审计。
|
||||
- 当前已核实旧账号/资产审计使用裸 goroutine，Access Log 响应体未脱敏；这两项是发布前必须消除的现存缺陷。
|
||||
- 当前手动轮询日志兼做进度存储，切断旧表时必须先由公共异步任务状态承接，不得违反 UR#94“轮询管理外部行为保持现状”的确认结论。
|
||||
- 本需求较大，进入实现前应依据本 Spec 拆成可独立验证的纵向切片，但不得按“先建表、再 Service、再 Handler”的水平层级拆分，也不得改变一次停机切换这一最终发布门禁。
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
# 00 — 建立全系统审计面与公共能力决策基线
|
||||
|
||||
**What to build:** 对整个现有系统而非仅七月迭代执行一次可复核的审计面盘点，形成动作注册表输入和机器可检查的覆盖基线。每个状态变更、敏感读取、关键拒绝或失败入口都必须明确 Audit Event、Domain Ledger、Integration Log、Outbox 的使用决策或给出不适用理由，后续需求以此基线增量维护。
|
||||
|
||||
**Blocked by:** None — can start immediately
|
||||
|
||||
**Status:** ready-for-agent
|
||||
|
||||
**架构通道:** 主通道为 Infrastructure 治理，辅助通道为 Query 验证。
|
||||
|
||||
**完整业务边界:** 本票收口 Handler、Application、Domain、Service、Worker 和回调入口的全仓审计分类、动作编码、事务策略、资源关系、失败策略和测试责任人。明确不迁移任何业务代码、不改变已评审业务规则、不把 Access Log、Audit Event、Domain Ledger 和 Integration Log 合并。
|
||||
|
||||
- [ ] 盘点全部 HTTP/Worker/定时任务/回调入口，至少覆盖创建、修改、删除、状态流转、资金、权限、关键配置、导入导出、人工恢复、敏感读取、拒绝和关键失败；记录代码入口与业务所有者。
|
||||
- [ ] 每个入口明确 `Audit Event / Domain Ledger / Integration Log / Outbox / N/A` 决策；选择 N/A 必须写明原因，禁止空白或“以后处理”。
|
||||
- [ ] 对需要审计的入口填写稳定动作编码、中文名称、风险、主要及受影响资源、操作者与来源、前后数据、事务边界、失败策略和自动化测试接缝。
|
||||
- [ ] 建立可被静态检查或测试读取的动作注册与覆盖基线，未经登记的新敏感操作不能通过发布门禁。
|
||||
- [ ] 对旧账号、资产、手动轮询 Writer 及全部直接写旧日志表的位置建立准确清单，作为 04～09 迁移票和 19 号切换票的输入。
|
||||
- [ ] 更新《审计覆盖基线》，经业务、研发和安全评审确认不存在未分类入口；评审只确认覆盖与分类，不借机扩大各业务 PRD 范围。
|
||||
@@ -2,7 +2,10 @@
|
||||
|
||||
**What to build:** 业务用例可以通过统一 Audit Writer 写入不可变、多资源、可串联且默认脱敏的审计事件。成功事件能够与业务事实共用事务，失败或拒绝事件使用独立短事务保留；未注册动作、缺少主要资源或审计写入失败时按明确策略阻止错误事实落地。
|
||||
|
||||
**Blocked by:** `.scratch/tech-public-foundation/issues/01-public-migration-ownership-and-gates.md` — 01 — 建立公共迁移所有权与检查门禁
|
||||
**Blocked by:**
|
||||
|
||||
- 00 — 建立全系统审计面与公共能力决策基线
|
||||
- `.scratch/tech-public-foundation/issues/01-public-migration-ownership-and-gates.md` — 01 — 建立公共迁移所有权与检查门禁
|
||||
|
||||
**Status:** ready-for-agent
|
||||
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
|
||||
**Blocked by:**
|
||||
|
||||
- 00 — 建立全系统审计面与公共能力决策基线
|
||||
- 03 — 完成 Access Log 全路由敏感信息防泄漏
|
||||
- 04 — 迁移账号、角色与权限敏感操作到统一审计
|
||||
- 05 — 迁移卡资产生命周期操作到统一审计
|
||||
@@ -20,6 +21,8 @@
|
||||
- 16 — 交付审计导出与字段授权快照
|
||||
- 17 — 交付审计保留、清理和运行监控
|
||||
- 18 — 冻结审计中心跨仓前端契约与验收包
|
||||
- 20 — 接入公共系统配置正式审计 Adapter
|
||||
- 21 — 接入 Outbox 人工恢复正式审计 Adapter
|
||||
- `.scratch/tech-public-foundation/issues/12-foundation-release-gate-and-integration-contract.md` — 12 — 建立公共基础发布门禁和下游接入契约
|
||||
|
||||
**Status:** ready-for-agent
|
||||
@@ -30,6 +33,7 @@
|
||||
|
||||
- [ ] 停机顺序明确覆盖暂停流量与 Worker、前置检查、增量迁移、权限初始化、新 Writer 装配、旧写护栏、历史对账、Worker 恢复和开放流量。
|
||||
- [ ] 自动切换清单证明生产产物不再调用旧账号/资产审计 Writer、不再直接 Create 旧三表、启动装配不再注入旧 Writer；旧表意外新增会立即告警或失败。
|
||||
- [ ] 《审计覆盖基线》的全部入口均已分类且无空白项；所有 Audit Event 动作已注册，所有 N/A 均有评审理由，系统配置更新和 Outbox 人工恢复已装配正式 Audit Writer。
|
||||
- [ ] 门禁覆盖关键业务与审计同事务、审计失败回滚、失败短事务、Integration 结果未知、历史新旧交界、Access Log 敏感矩阵和权限隔离。
|
||||
- [ ] Query 性能验证常用过滤使用索引、无 JSONB 全表模糊扫描、无资源/操作者 N+1，并满足项目 P95/P99 目标。
|
||||
- [ ] 任一迁移、旧写清单、样本对账、事务、安全、权限、性能、监控或跨仓验收失败均在开放流量前整体终止发布，不能让局部模块继续写旧表。
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
# 20 — 接入公共系统配置正式审计 Adapter
|
||||
|
||||
**What to build:** 在系统配置更新的 Application 组合根注入正式 Audit Writer Adapter，使关键配置变更进入统一 Audit Event，并按公共基础已经确认的事务边界失败关闭。由真实全局审计替换公共基础的未装配占位，不创建临时审计表或旁路 goroutine。
|
||||
|
||||
**Blocked by:**
|
||||
|
||||
- 01 — 交付不可变 Audit Event 写入闭环
|
||||
- `.scratch/tech-public-foundation/issues/08-controlled-system-config-update.md` — 08 — 交付系统配置更新、权限和审计闭环
|
||||
|
||||
**Status:** ready-for-agent
|
||||
|
||||
**架构通道:** 主通道为 Application + Port/Adapter，辅助通道为 Infrastructure。
|
||||
|
||||
**完整业务边界:** 本票仅收口公共系统配置更新既有用例的正式审计装配、事务一致性、脱敏和测试。明确不新增配置 Key、不建设配置前端页面、不迁移其他业务审计。
|
||||
|
||||
- [ ] 注册系统配置更新的稳定动作编码、中文名称、风险等级及允许资源类型，并写入全系统审计覆盖基线。
|
||||
- [ ] 系统配置更新的业务事实与 Audit Event 使用同一 GORM 事务；审计失败时配置更新回滚，敏感配置只记录“是否配置”和安全摘要，不记录原值。
|
||||
- [ ] 组合根显式注入正式 Audit Writer Adapter；未装配时失败关闭，禁止回退到空实现、旧审计表或裸 goroutine。
|
||||
- [ ] PostgreSQL 集成测试覆盖成功同事务、审计失败整体回滚、敏感值不落库和未装配失败关闭。
|
||||
- [ ] 发布检查能证明生产组合根已装配正式 Adapter，并由 19 号一次性切换门禁纳入停机演练。
|
||||
@@ -0,0 +1,20 @@
|
||||
# 21 — 接入 Outbox 人工恢复正式审计 Adapter
|
||||
|
||||
**What to build:** 在 Outbox 人工恢复的 Application 组合根注入正式 Audit Writer Adapter，使每次受控恢复完整记录操作者、原因、批次和状态变化，并与恢复事实同事务失败关闭。由真实全局审计替换公共基础的未装配占位，不创建临时审计表或旁路 goroutine。
|
||||
|
||||
**Blocked by:**
|
||||
|
||||
- 01 — 交付不可变 Audit Event 写入闭环
|
||||
- `.scratch/tech-public-foundation/issues/04-outbox-observability-and-recovery.md` — 04 — 提供 Outbox 监控和受控恢复能力
|
||||
|
||||
**Status:** ready-for-agent
|
||||
|
||||
**架构通道:** 主通道为 Application + Port/Adapter，辅助通道为 Infrastructure。
|
||||
|
||||
**完整业务边界:** 本票仅收口 Outbox 人工恢复既有用例的正式审计装配、事务一致性和测试。明确不改变恢复资格与租约规则、不建设 Outbox 前端页面、不迁移其他业务审计。
|
||||
|
||||
- [ ] 注册 Outbox 人工恢复的稳定动作编码、中文名称、风险等级及允许资源类型，并写入全系统审计覆盖基线。
|
||||
- [ ] Outbox 状态变更与 Audit Event 使用同一 GORM 事务；记录操作者、中文原因、恢复批次、事件标识及恢复前后状态，审计失败时恢复回滚。
|
||||
- [ ] 组合根显式注入正式 Audit Writer Adapter；未装配时失败关闭，禁止回退到空实现、旧审计表或裸 goroutine。
|
||||
- [ ] PostgreSQL 集成测试覆盖成功同事务、审计失败整体回滚、重复恢复裁决、有效租约不可恢复和未装配失败关闭。
|
||||
- [ ] 发布检查能证明生产组合根已装配正式 Adapter，并由 19 号一次性切换门禁纳入停机演练。
|
||||
33
.scratch/tech-global-audit/审计覆盖基线.md
Normal file
33
.scratch/tech-global-audit/审计覆盖基线.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# 全系统审计覆盖基线
|
||||
|
||||
状态：待 00 号票完成全仓扫描与评审
|
||||
|
||||
## 使用规则
|
||||
|
||||
本基线覆盖整个系统，不限于七月迭代。任何新增或修改的状态变更、敏感读取、关键拒绝或失败，在进入实现前都必须登记审计分类；选择不审计必须填写可评审的 N/A 理由。实现和发布评审不得只检查“是否调用了日志”，还要检查动作编码、操作者、资源、前后变化、事务边界、失败策略和测试接缝。
|
||||
|
||||
| 业务面 | 当前迁移责任票 | Audit Event | Domain Ledger | Integration Log | Outbox | 当前状态 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 账号、角色、权限 | 04 | 必须 | N/A | N/A | 按业务事件决定 | 待盘点 |
|
||||
| 卡与资产生命周期 | 05 | 必须 | 既有资产事实 | 按外部调用决定 | 按业务事件决定 | 待盘点 |
|
||||
| 设备与资产导入 | 06 | 必须 | 导入任务/明细 | 按外部调用决定 | 按业务事件决定 | 待盘点 |
|
||||
| 店铺、套餐、关键配置 | 07 | 必须 | 既有业务事实 | N/A | 按业务事件决定 | 待盘点 |
|
||||
| 资金、订单、退款、充值 | 08 | 必须 | 必须，以领域流水为准 | 按支付交互决定 | 按业务事件决定 | 待盘点 |
|
||||
| 手动轮询与同步 | 09 | 状态变化、人工触发和异常必须 | 任务状态 | 必须 | 按可靠投递决定 | 待盘点 |
|
||||
| 系统配置更新 | 20 | 必须、同事务 | 配置事实 | N/A | N/A | 待接入 |
|
||||
| Outbox 人工恢复 | 21 | 必须、同事务 | Outbox 状态事实 | N/A | 自身为投递事实 | 待接入 |
|
||||
| 敏感值二次查看 | 15 | 必须 | N/A | N/A | N/A | 待接入 |
|
||||
| 审计导出 | 16 | 必须 | 导出任务/制品 | N/A | 按任务通知决定 | 待接入 |
|
||||
|
||||
## 00 号票必须补齐的逐入口字段
|
||||
|
||||
- 代码入口与业务所有者；
|
||||
- 动作编码、中文名称、类别和风险；
|
||||
- 操作者、来源、主要资源、受影响资源；
|
||||
- 前后数据、敏感字段策略和内容上限；
|
||||
- 成功同事务、失败短事务或 N/A 的理由；
|
||||
- Domain Ledger、Integration Log、Outbox 的关联标识；
|
||||
- 单元、PostgreSQL、HTTP 或静态检查的确认测试接缝；
|
||||
- 对应迁移票、发布门禁和评审结论。
|
||||
|
||||
在逐入口清单完成并评审前，本文件不能作为“全系统已覆盖”的证明。
|
||||
@@ -99,6 +99,11 @@ Status: ready-for-agent
|
||||
- 未来短信或企微消息使用独立 Delivery 消费同一业务事件；不得在 Notification Handler/Worker 写完站内消息后同步循环调用外部渠道。
|
||||
- 新增管理端和 C 端 Handler 后同步注册路由和两个 OpenAPI 文档生成器；公共通知能力先于 UR#33、UR#97 和企微结果通知启用。
|
||||
|
||||
## 公共能力发布依赖
|
||||
|
||||
- 实现阶段复用公共 Outbox 与异步任务，不自行复制表或状态机；最终 08 号发布票必须阻塞于公共基础 12 号票和全局审计 19 号票。
|
||||
- 每个下游通知生产者仍须登记事件类型、载荷版本、消费者幂等键、接收人、失败明细和通知策略；“通知基础完成”不代表业务生产者已经接入。
|
||||
|
||||
## Testing Decisions
|
||||
|
||||
- Application/Worker 测试覆盖重复事件、多个接收人、接收人去重、停用/删除接收人、无接收人、模板字段缺失、Outbox/Asynq 重试和过期时间。
|
||||
|
||||
@@ -10,6 +10,8 @@
|
||||
- 05 — 交付通知受控目标解析与权限复核
|
||||
- 06 — 交付通知保留清理与失败可观测闭环
|
||||
- 07 — 冻结后台与 C 端通知前端契约及验收包
|
||||
- `.scratch/tech-public-foundation/issues/12-foundation-release-gate-and-integration-contract.md` — 12 — 建立公共基础发布门禁和下游接入契约
|
||||
- `.scratch/tech-global-audit/issues/19-one-time-audit-cutover-gate.md` — 19 — 执行一次性审计切换与停机发布门禁
|
||||
|
||||
**Status:** ready-for-agent
|
||||
|
||||
|
||||
@@ -208,6 +208,12 @@ Status: ready-for-agent
|
||||
- 列表和详情按 `approval_source` 展示：`none` 审批列为“-”；`wecom` 展示只读企微状态；`legacy` 展示“历史审批”且无操作按钮。代理界面不展示审批人列或内部意见。
|
||||
- 加载、空、网络失败、支付方式为空、支付创建失败、支付已成功但入账失败、企微提交中/失败、审批拒绝和异常撤销均有独立展示，不由前端自行推导或改写服务端状态。
|
||||
|
||||
## 公共能力发布依赖
|
||||
|
||||
- 最终发布票必须明确阻塞于公共基础 12 号票、全局审计 19 号票、公共通知 08 号票、UR#37 企微发布 14 号票和 UR#38 钱包切换 10 号票。
|
||||
- 充值事件必须登记载荷版本、消费者幂等键、失败明细和通知策略；资金结论以 Domain Ledger 为准，Audit Event 记录操作者与前后变化，企微/支付外部事实进入 Integration Log。
|
||||
- 当前 PRD 尚未拆票；生成 tickets 时必须把上述依赖落到最终发布门禁，不得只写“依赖公共基础”。
|
||||
|
||||
## Testing Decisions
|
||||
|
||||
### 最高公共测试接缝
|
||||
|
||||
@@ -203,6 +203,11 @@ Status: ready-for-agent
|
||||
- 回滚时先关闭前端入口和任务创建，等待或人工处置已领取任务，再回滚应用。已经创建的标准订单、钱包流水、套餐使用、任务和审计均作为业务事实保留，不做反向删除。
|
||||
- 不在仍有待处理或处理中任务时删除新表或上传用途；数据库降级迁移不是常规应用回滚步骤。
|
||||
|
||||
## 公共能力发布依赖
|
||||
|
||||
- 最终 11 号发布票阻塞于公共基础 12 号票、全局审计 19 号票和 UR#38 钱包切换 10 号票；公共能力未完成不阻止独立切片开发，但阻止生产放量。
|
||||
- 批量任务必须登记事件类型、载荷版本、Worker 幂等键和逐行失败明细；订单与钱包仍以各自 Domain Ledger 为权威，任务创建、终态及人工操作进入 Audit Event。
|
||||
|
||||
## Testing Decisions
|
||||
|
||||
### 可复用 Agent 集成测试规范与工具
|
||||
|
||||
@@ -6,6 +6,9 @@
|
||||
|
||||
- `.scratch/ur36-bulk-package-purchase/issues/03-real-dependency-integration-harness.md` — 03 — 建立批量任务真实依赖的集成测试 Harness
|
||||
- `.scratch/ur36-bulk-package-purchase/issues/10-bulk-purchase-task-queries.md` — 10 — 提供任务汇总与逐行明细查询
|
||||
- `.scratch/tech-public-foundation/issues/12-foundation-release-gate-and-integration-contract.md` — 12 — 建立公共基础发布门禁和下游接入契约
|
||||
- `.scratch/tech-global-audit/issues/19-one-time-audit-cutover-gate.md` — 19 — 执行一次性审计切换与停机发布门禁
|
||||
- `.scratch/ur38-agent-main-wallet-credit/issues/10-credit-wallet-cutover-gate.md` — 10 — 完成信用钱包停机切换与发布门禁
|
||||
|
||||
**Status:** ready-for-agent
|
||||
|
||||
|
||||
@@ -214,6 +214,11 @@ Status: ready-for-agent
|
||||
- 已结束的历史本地审批保留为 `legacy` 只读事实，不伪造企微实例。发布时仍未结束的退款/线下充值按创建人类型形成真实企微审批；缺少平台绑定、固定代理身份或创建人事实的记录进入迁移待处理清单，不能继续使用旧本地审批接口。
|
||||
- 回滚应用时保留已经形成的企微实例、提交人/身份快照、Integration Log 和 Audit Event。已有企微申请进入运行后不得恢复旧本地审批动作，只能继续同步或人工处置。
|
||||
|
||||
## 公共能力发布依赖
|
||||
|
||||
- 最终 14 号真实企微发布票阻塞于公共基础 12 号票、全局审计 19 号票和公共通知 08 号票；退款业务消费者还必须替换为 UR#35 的具体纵向 Ticket。
|
||||
- 审批终态事件必须登记版本和消费者幂等键；审批实例是领域事实，企微请求/回调进入 Integration Log，提交、人工同步和状态变化进入 Audit Event。
|
||||
|
||||
## Testing Decisions
|
||||
|
||||
- 主要自动化接缝采用最高公共行为边界：Fiber HTTP 路由与认证 → Application/Domain/Query → GORM → 开发 PostgreSQL、Redis 和 Asynq 可控队列；企业微信网络统一替换为可编程 WeCom Adapter。测试不直接断言私有函数或目录结构。
|
||||
|
||||
@@ -18,6 +18,8 @@
|
||||
- 12 — 交付历史审批与待处理数据迁移接缝
|
||||
- 13 — 冻结企微后台与个人中心前端契约
|
||||
- `.scratch/tech-public-foundation/issues/12-foundation-release-gate-and-integration-contract.md` — 12 — 建立公共基础发布门禁和下游接入契约
|
||||
- `.scratch/tech-global-audit/issues/19-one-time-audit-cutover-gate.md` — 19 — 执行一次性审计切换与停机发布门禁
|
||||
- `.scratch/tech-inapp-notifications/issues/08-notification-release-gate.md` — 08 — 完成公共通知发布门禁与下游接入契约
|
||||
- UR#35 退款企微审批的“退款创建接入公共审批并消费终态事件”纵向 Ticket；UR#35 拆票后必须在本票实施前替换为其具体文件引用
|
||||
|
||||
**Status:** ready-for-agent
|
||||
|
||||
@@ -154,6 +154,11 @@ GET /api/admin/shops/fund-summary
|
||||
- 开放普通访问前，保持历史钱包信用关闭，验证普通现金支付、信用扣款、冻结、回充、调额和并发场景。之后再由授权平台人员配置角色模板和既有代理额度。
|
||||
- 尚未启用信用且未产生负余额时可以回滚应用和可逆字段；一旦出现负余额，不得回滚到不理解信用额度的旧写入逻辑，也不得删除字段或强制关闭信用，必须先清偿欠款或继续保留新资金逻辑。
|
||||
|
||||
## 公共能力发布依赖
|
||||
|
||||
- 最终 10 号切换票阻塞于公共基础 12 号票和全局审计 19 号票，不能只以 Outbox Relay 可用替代业务事件消费者、审计 Adapter 和停机验收。
|
||||
- 余额、冻结与信用额度以钱包 Domain Ledger 为权威；高风险资金变更必须同事务写 Audit Event，可靠事件必须登记类型、版本、消费者和业务幂等键。
|
||||
|
||||
## Testing Decisions
|
||||
|
||||
- 领域测试覆盖关闭/0、开启/正数、负额度、开启/0、关闭/非0、普通现金、使用部分信用、用尽信用、超过信用以及每个算术溢出边界。
|
||||
|
||||
@@ -12,7 +12,8 @@
|
||||
- `.scratch/ur38-agent-main-wallet-credit/issues/07-unified-agent-wallet-credit-posting.md` — 07 — 统一代理主钱包充值入账与人工调整
|
||||
- `.scratch/ur38-agent-main-wallet-credit/issues/08-unified-agent-wallet-refund.md` — 08 — 统一代理订单退款回充
|
||||
- `.scratch/ur38-agent-main-wallet-credit/issues/09-fund-summary-credit-query.md` — 09 — 资金概况返回信用、总可用金额与欠款
|
||||
- `.scratch/tech-public-foundation/issues/03-outbox-at-least-once-delivery.md` — 03 — 完成 Outbox 到 Asynq 的至少一次投递闭环
|
||||
- `.scratch/tech-public-foundation/issues/12-foundation-release-gate-and-integration-contract.md` — 12 — 建立公共基础发布门禁和下游接入契约
|
||||
- `.scratch/tech-global-audit/issues/19-one-time-audit-cutover-gate.md` — 19 — 执行一次性审计切换与停机发布门禁
|
||||
|
||||
**Status:** ready-for-agent
|
||||
|
||||
|
||||
@@ -245,6 +245,12 @@ POST /api/admin/export-tasks
|
||||
- 恢复服务后监控权限解析失败、零字段拒绝、各 Scene 任务失败、附件本地化缺失及 Count/Fetch 行数差异。
|
||||
- 回滚时先停止新任务，处理新版本未完成任务，再回滚 Worker/API/前端和数据库；已经生成的导出文件仍按附件落地页的当前鉴权访问。
|
||||
|
||||
## 公共能力发布依赖
|
||||
|
||||
- 最终发布票必须明确阻塞于公共基础 12 号票和全局审计 19 号票；涉及企微审批导出时还必须引用 UR#37 14 号发布票。
|
||||
- 导出任务复用公共五态并保留业务失败明细；敏感字段查看和导出均进入 Audit Event，导出文件与任务是业务事实，不把明细塞入审计 JSON。
|
||||
- 当前 PRD 尚未拆票；生成 tickets 时必须把上述依赖落到最终发布门禁，不得只写“依赖公共基础”。
|
||||
|
||||
## Testing Decisions
|
||||
|
||||
- 字段权限单元/集成测试覆盖超级管理员全目录、单角色、多角色并集、账号角色与店铺角色既有解析规则、软删除/禁用角色关联、空授权、陈旧字段 key 和权限存储异常。
|
||||
|
||||
@@ -136,6 +136,11 @@ Status: ready-for-agent
|
||||
- 前后端同批切换 `/orders/create` 必填字段和 `/pay` 不可换方式契约。发布窗口应阻断旧前端继续创建缺少方式的新订单。
|
||||
- 回滚应用时保留系统配置、订单快照、支付记录和审计事实；不得通过回滚迁移删除已产生数据。
|
||||
|
||||
## 公共能力发布依赖
|
||||
|
||||
- 新增 05 号发布票，阻塞于公共基础 12 号票、全局审计 20 号系统配置 Adapter 接入票和全局审计 19 号切换票。
|
||||
- UR#48 负责注册正式支付配置 Key；系统配置更新的 Audit Event 与配置事实同事务，支付方式以订单快照为业务事实。公共配置接口存在不等于前端现在就新增配置页面。
|
||||
|
||||
## Testing Decisions
|
||||
|
||||
- 配置单元测试覆盖卡/设备默认集合、合法自定义、钱包不可移除、空数组、未知值、重复值、非法 JSON、缺失记录和未知资产类型。
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
# 05 — 完成资产支付方式公共能力接入与发布门禁
|
||||
|
||||
**What to build:** 发布负责人可以验证 UR#48 的支付方式配置已通过公共受控系统配置注册、正式审计 Adapter 和订单快照链路接入生产组合根，并在接口、权限、缓存、审计或回滚检查失败时阻止放量。
|
||||
|
||||
**Blocked by:**
|
||||
|
||||
- 04 — 订单按支付方式快照完成支付与取消闭环
|
||||
- `.scratch/tech-public-foundation/issues/12-foundation-release-gate-and-integration-contract.md` — 12 — 建立公共基础发布门禁和下游接入契约
|
||||
- `.scratch/tech-global-audit/issues/20-system-config-audit-adapter.md` — 20 — 接入公共系统配置正式审计 Adapter
|
||||
- `.scratch/tech-global-audit/issues/19-one-time-audit-cutover-gate.md` — 19 — 执行一次性审计切换与停机发布门禁
|
||||
|
||||
**Status:** ready-for-agent
|
||||
|
||||
**架构通道:** 主通道为 Infrastructure 发布验收，辅助通道为 Application 与 Query 验收。
|
||||
|
||||
**完整业务边界:** 本票只收口 UR#48 正式配置 Key、支付方式策略、订单快照、审计装配、接口契约和发布回滚。明确不新增公共配置页面、不改变已评审支付规则、不建设 Outbox 运维前端、不迁移其他支付模块。
|
||||
|
||||
- [ ] UR#48 拥有的配置 Key 已在代码注册表声明类型、默认值、值域、只读和敏感策略，未注册 Key 不可写。
|
||||
- [ ] 系统配置更新通过正式 Audit Writer 与配置事实同事务，能追踪操作者、动作和前后变化且不记录敏感原值；未装配或审计失败时更新回滚。
|
||||
- [ ] `GET /api/admin/system-configs` 与 `PUT /api/admin/system-configs/{key}` 的权限、缓存失效、错误语义和 OpenAPI 与真实路由一致；前端只消费 UR#48 注册的配置项。
|
||||
- [ ] 真实 Fiber、PostgreSQL 和 Redis 验收覆盖按资产类型读取、配置更新、订单方式快照、支付、取消、并发和回滚边界。
|
||||
- [ ] 发布顺序为公共迁移与门禁、全局审计及 Adapter、UR#48 后端、前端；任一正式装配或审计样本失败均阻止放量。
|
||||
@@ -149,6 +149,11 @@ Status: ready-for-agent
|
||||
- 发布前核查重复 IMEI，并验证平台、代理、直属下级和系列授权的数据范围；不自动修改历史设备数据。
|
||||
- 回滚应用时保留已经产生的任务、资产分配记录与审计事实；不得通过回滚删除已经完成的设备归属或系列变更。
|
||||
|
||||
## 公共能力发布依赖
|
||||
|
||||
- 最终 05 号发布票阻塞于公共基础 12 号票和全局审计 19 号票；Worker、监控和消费者未就绪前不得开放前端入口。
|
||||
- 批量分配任务复用公共五态，逐行失败留在业务任务明细；任务创建、人工操作和资产归属变化进入 Audit Event，可靠事件登记版本与消费者幂等键。
|
||||
|
||||
## Testing Decisions
|
||||
|
||||
- CSV 解析测试覆盖 UTF-8、UTF-8 BOM、LF、CRLF、中文表头、引号、空行、空值、额外列、非法引号、非 UTF-8、控制字符、公式前缀、科学计数法、超长标识、1000/1001 行和 10MB 边界。
|
||||
|
||||
@@ -6,6 +6,8 @@
|
||||
|
||||
- 04 — 交付设备管理页 CSV 双入口与任务结果交互
|
||||
- [.scratch/ur36-bulk-package-purchase/issues/03-real-dependency-integration-harness.md](../../ur36-bulk-package-purchase/issues/03-real-dependency-integration-harness.md) — 03 — 建立批量任务真实依赖的集成测试 Harness
|
||||
- [.scratch/tech-public-foundation/issues/12-foundation-release-gate-and-integration-contract.md](../../tech-public-foundation/issues/12-foundation-release-gate-and-integration-contract.md) — 12 — 建立公共基础发布门禁和下游接入契约
|
||||
- [.scratch/tech-global-audit/issues/19-one-time-audit-cutover-gate.md](../../tech-global-audit/issues/19-one-time-audit-cutover-gate.md) — 19 — 执行一次性审计切换与停机发布门禁
|
||||
|
||||
**Status:** ready-for-agent
|
||||
|
||||
|
||||
@@ -102,6 +102,11 @@ Status: ready-for-agent
|
||||
- 发布前记录并对比当前启用的轮询配置、队列深度、卡级开关和监控结果；发布后这些调度事实应保持一致。
|
||||
- 回调 URL 需在测试环境用运营商原始样例验证后再配置到运营商平台；正式启用顺序按运营商逐个灰度，单个 Adapter 可独立关闭而不影响事件和轮询兜底。
|
||||
|
||||
## 公共能力发布依赖
|
||||
|
||||
- 最终 13 号发布票阻塞于公共基础 12 号票和全局审计 19 号票；生产者放量前必须确认事件消费者、Integration Log、Audit Writer 和监控同时装配。
|
||||
- 每个卡状态事件登记稳定类型、载荷版本和消费者幂等键；卡状态是领域事实，运营商请求/回调进入 Integration Log，状态变化、人工触发及连续失败进入 Audit Event。
|
||||
|
||||
## Testing Decisions
|
||||
|
||||
- 领域单元测试覆盖实名首次成功/重复成功/逆转确认、流量正增量/跨月/运营商重置/异常下降、网络状态映射/未知状态/运营商停机原因，以及每类观测不变时不重复发布副作用。
|
||||
|
||||
@@ -11,6 +11,8 @@
|
||||
- 10 — 接入电信实名回调
|
||||
- 11 — 接入移动实名成功回调
|
||||
- 12 — 接入联通解除实名留痕回调
|
||||
- `.scratch/tech-public-foundation/issues/12-foundation-release-gate-and-integration-contract.md` — 12 — 建立公共基础发布门禁和下游接入契约
|
||||
- `.scratch/tech-global-audit/issues/19-one-time-audit-cutover-gate.md` — 19 — 执行一次性审计切换与停机发布门禁
|
||||
|
||||
**Status:** ready-for-agent
|
||||
|
||||
|
||||
@@ -73,6 +73,12 @@ Status: ready-for-agent
|
||||
- 发布依赖统一钱包变更边界、公共 Outbox、公共站内通知和 UR#96 业务员关系；依赖尚未完成时可以先完成领域事件，但不得另建临时通知表或直接发消息。
|
||||
- 存量低余额钱包不批量补发，避免上线瞬间产生大量无业务变更通知；上线后只监听新提交的跨阈值事务。
|
||||
|
||||
## 公共能力发布依赖
|
||||
|
||||
- 最终发布票必须明确阻塞于公共基础 12 号票、全局审计 19 号票、公共通知 08 号票和 UR#38 钱包切换 10 号票。
|
||||
- 低余额事件必须登记载荷版本、消费者幂等键、通知接收人和防重策略；钱包 Domain Ledger 是余额权威，通知事实不替代资金审计。
|
||||
- 当前 PRD 尚未拆票；生成 tickets 时必须把上述依赖落到最终发布门禁，不得只写“依赖公共基础”。
|
||||
|
||||
## Testing Decisions
|
||||
|
||||
- 领域单元测试覆盖 `10100→10000`、`10001→10000`、`10000→9999`、`9000→8000`、`9000→10100→10000`，验证只在严格跨越时发事件。
|
||||
|
||||
13
AGENTS.md
13
AGENTS.md
@@ -321,13 +321,14 @@ queueClient.EnqueueTask(ctx, constants.TaskTypeXxx, payloadBytes)
|
||||
|
||||
### 审计日志规范
|
||||
|
||||
**适用场景**：任何敏感操作（账号管理、权限变更、数据删除等）
|
||||
**适用场景**：整个系统中的状态变更、敏感读取以及关键拒绝和失败，不限于七月迭代。实现前必须查阅并增量维护 `.scratch/tech-global-audit/审计覆盖基线.md`；选择不审计必须登记 N/A 理由，禁止留空。
|
||||
|
||||
- 旧模块在 Service 层、新 DDD 模块在 Application UseCase 中注入审计能力，操作成功后调用 `LogOperation()`
|
||||
- 必填字段：`OperatorID`、`OperationType`、`OperationDesc`、`BeforeData`、`AfterData`
|
||||
- 异步写入（Goroutine），写入失败不影响业务，失败时记录 Error 日志
|
||||
|
||||
**示例参考**：`internal/service/account/service.go`
|
||||
- Access Log 只负责 HTTP 调试，Audit Event 负责业务审计，Domain Ledger 负责金额和状态等领域事实，Integration Log 负责外部交互；四者不得混用或合并。
|
||||
- 旧模块在 Service/Application 事务脚本中、新 DDD 模块在 Application UseCase 中通过统一 Audit Writer Port/Adapter 接入；禁止新增裸 goroutine 审计写入。
|
||||
- 成功的资金、权限、关键配置、人工状态变更和其他高风险操作必须与业务事实同一 GORM 事务，审计失败则业务回滚。
|
||||
- 业务已回滚后的 `failed/denied` 审计使用独立短事务；二次失败保留原业务错误，并记录 critical 日志和指标。
|
||||
- Audit Event 至少记录稳定动作编码、操作者、来源、主要资源、前后数据、结果、风险及 request/correlation 标识；敏感值按统一 Sanitizer 删除或摘要化。
|
||||
- 新增或修改 PRD、Ticket 时必须明确 Audit Event、Domain Ledger、Integration Log、Outbox 的使用决定或 N/A 理由，并在最终发布门禁引用具体公共基础票。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -199,7 +199,7 @@ default:
|
||||
|
||||
### 公共技术基础
|
||||
|
||||
公共 Outbox、命令幂等、统一异步任务、受控系统配置、迁移门禁和 Access Log 安全策略的能力边界、发布顺序与下游接入方式见[公共技术基础功能总结](docs/tech-public-foundation/功能总结.md)。
|
||||
公共 Outbox、命令幂等、统一异步任务、受控系统配置、迁移门禁和 Access Log 安全策略的能力边界、发布顺序与下游接入方式见[公共技术基础功能总结](docs/tech-public-foundation/功能总结.md)；前端当前需要处理的接口字段和页面规则见[公共技术基础前端即时接口交接](docs/tech-public-foundation/前端即时接口交接.md)。
|
||||
|
||||
### 账号管理重构（2025-02）
|
||||
|
||||
|
||||
@@ -201,7 +201,7 @@ FE/BE 研发需求开发完成
|
||||
| INT-05 | 支付、代理钱包、信用和余额预警联调 | #48、#38、#34、#36、#96、#97 | FE 1～1.5h / BE 1～1.5h，已含 | 支付配置、钱包领域和业务员接口完成 | 支付方式限制、扫码充值、信用扣款、角色默认额度、店铺调额、100元预警 |
|
||||
| INT-06 | 企业微信审批、退款和线下充值联调 | #37、#35、#34、#44 | FE 1.5～2h / BE 1.5～2h，已含 | 企微模板、绑定、回调、轮询和业务详情完成 | 扫码绑定、发起审批、意见附件、通过/驳回/撤销、退款/充值终态和列表摘要 |
|
||||
| INT-07 | Gateway卡限速联调 | #47 | FE 0.5～1h / BE 0.5～1h，已含 | Gateway联调配置和卡/设备入口完成 | 单卡限速、设备解析当前卡、取消限速、无当前卡、失败审计 |
|
||||
| INT-08 | 七月迭代全链路与停机发布验收 | 全部激活需求 | FE 3～4h / BE 4～5h，额外 | INT-01～07完成 | 权限、通知、审计、历史数据、旧入口关闭、Worker恢复和发布检查 |
|
||||
| INT-08 | 七月迭代全链路与停机发布验收 | 全部激活需求及三项公共技术需求 | FE 3～4h / BE 4～5h，额外 | INT-01～07、公共基础12、全局审计19、公共通知08及各业务发布门禁完成 | 权限、通知、全系统审计覆盖、正式Adapter、事件消费者、历史数据、旧入口关闭、Worker恢复、生产阈值和发布检查 |
|
||||
|
||||
## 七、联调任务责任方式
|
||||
|
||||
@@ -231,7 +231,7 @@ FE/BE 研发需求开发完成
|
||||
再分别拆分：
|
||||
|
||||
```text
|
||||
[FE] 七月迭代公共状态与异步任务交互
|
||||
[FE][TECH] 七月迭代公共状态与异步任务交互（当前先调整导出任务列表/详情的统一字段、五态、轮询与恢复；系统配置和 Outbox 运维页面不在本票）
|
||||
[BE] 七月迭代公共迁移幂等与异步任务基础
|
||||
[FE] 顶部通知铃铛与站内通知中心
|
||||
[BE] 站内通知基础设施与受控跳转
|
||||
|
||||
@@ -1598,17 +1598,22 @@
|
||||
**描述**
|
||||
|
||||
```markdown
|
||||
目标：为批量分配、批量订购、导出等页面提供一致的加载、错误和异步任务交互。
|
||||
目标：先统一现有导出任务接口与批量任务页面的加载、错误和异步任务交互；系统配置和 Outbox 运维页面不在本研发需求范围。
|
||||
|
||||
预计工时：前端1～2小时。
|
||||
|
||||
交付内容：
|
||||
1. 统一加载、空数据、权限不足、接口失败和重试状态。
|
||||
2. 统一异步任务进度结构：状态固定为1待处理、2处理中、3已完成、4已失败、5已取消；总数、成功数、失败数和失败明细独立返回，部分成功只由计数表达，不占状态码。
|
||||
3. 创建任务后按2秒、3秒、5秒递增轮询，最大间隔10秒；页面不可见暂停，恢复后立即刷新。
|
||||
4. 页面刷新后通过task_id恢复任务详情。
|
||||
2. `GET /api/admin/export-tasks` 兼容新增或统一 `task_id`、`total_count`、`success_count`、`failed_count`、`error_code`、`error_summary`、`updated_at`，原字段不删除、不改名。
|
||||
3. `GET /api/admin/export-tasks/{id}` 同步新增或统一上述字段，字段语义与列表一致。
|
||||
4. 统一异步任务进度结构：状态固定为1待处理、2处理中、3已完成、4已失败、5已取消；部分成功仍为已完成，只通过总数、成功数和失败数表达。
|
||||
5. 创建任务后保存 `task_id`；刷新或重新进入页面查询原任务，不得重新创建。
|
||||
6. 按2秒、3秒、5秒递增轮询，最大间隔10秒；终态停止，页面不可见暂停，恢复后立即刷新。
|
||||
7. 403显示无权限且不重试；瞬时失败保留已有数据和输入并提供重试；用户错误文案展示安全的 `error_summary`。
|
||||
|
||||
完成标准：设备批量分配、批量订购和导出页面复用同一交互规则，不各自实现不同状态语义。
|
||||
不包含：`GET /api/admin/system-configs`、`PUT /api/admin/system-configs/{key}` 的新页面，以及 Outbox 监控/人工恢复页面。支付配置页面继续归 UR#48，待正式配置 Key 和审计 Adapter 就绪后联调。
|
||||
|
||||
完成标准：导出页面先完成上述兼容字段和交互规则；设备批量分配、批量订购在对应业务接口落地后复用同一状态语义。
|
||||
```
|
||||
|
||||
### 后端研发需求
|
||||
@@ -1925,13 +1930,13 @@
|
||||
**描述**
|
||||
|
||||
```markdown
|
||||
关联需求：全部激活用户需求及全局审计技术需求。
|
||||
关联需求：全部激活用户需求、七月迭代公共开发基础、全局审计和公共站内通知技术需求。
|
||||
|
||||
预计工时：前端3～4小时、后端4～5小时，本项为额外发布工时并计入总工时。
|
||||
|
||||
进入条件：INT-01至INT-07完成，迁移脚本、配置、Worker和发布清单已准备。
|
||||
进入条件：INT-01至INT-07完成；公共基础12号票、全局审计19号票、公共站内通知08号票及各业务最终发布门禁完成；迁移脚本、配置、Worker和发布清单已准备。
|
||||
|
||||
验收范围：权限与越权、通知跳转、审计多视角、历史数据兼容、旧审批接口下线、旧审计停止写入、异步任务恢复、停机迁移、配置校验和回滚边界。
|
||||
验收范围：权限与越权、通知跳转、审计多视角、历史数据兼容、旧审批接口下线、旧审计停止写入、异步任务恢复、停机迁移、配置校验和回滚边界；全系统审计覆盖基线无未分类入口，系统配置更新和 Outbox 人工恢复已注入正式 Audit Writer；每个实际投递事件已登记事件类型、载荷版本、消费者、幂等键、业务失败明细和通知策略；告警阈值已填写具体数值与责任人。
|
||||
|
||||
完成标准：前端和后端使用冻结接口契约，核心链路人工验收通过，发布检查项和已知风险已记录。
|
||||
完成标准：前端和后端使用冻结接口契约，能从样本回答谁在什么入口、对什么资源、如何操作、前后变化和关联请求/业务链路；旧 Writer 无新增，消费者先于生产者就绪，核心链路人工验收通过。任何审计覆盖空白、正式 Adapter 未装配、事件无消费者或阈值未确定都阻止放量。
|
||||
```
|
||||
|
||||
@@ -43,7 +43,9 @@
|
||||
2. PRD 已完成评审，没有尚未决定的业务问题。
|
||||
3. 工作区没有来源不明的未提交修改。
|
||||
4. 当前需求的跨 PRD 前置能力已经发布为具体 Issue；不能只写“依赖公共基础”。
|
||||
5. 记录拆票前或实现前的 commit，供后续双轴评审使用：
|
||||
5. 当前完整用例已经明确 Audit Event、Domain Ledger、Integration Log、Outbox 的使用决定或 N/A 理由；涉及审计时已增量维护全系统审计覆盖基线。
|
||||
6. 最终发布门禁已经引用具体公共基础 Ticket；需要事件时已确认事件类型、载荷版本、消费者幂等键、业务失败明细和通知策略。
|
||||
7. 记录拆票前或实现前的 commit，供后续双轴评审使用：
|
||||
|
||||
```bash
|
||||
git status --short --branch
|
||||
@@ -74,6 +76,8 @@ git rev-parse HEAD
|
||||
- 适用的 DDD 架构通道；
|
||||
- 当前票收口的完整业务边界；
|
||||
- 明确不迁移的旧代码范围。
|
||||
- Audit Event、Domain Ledger、Integration Log、Outbox 的逐项决定或 N/A 理由；
|
||||
- 依赖公共能力时引用具体 Ticket，并在本 PRD 最终发布票中收口装配和验收。
|
||||
|
||||
出现以下拆法时应要求重拆：
|
||||
|
||||
@@ -82,6 +86,7 @@ git rev-parse HEAD
|
||||
- 阻塞项只写“公共基础设施”而没有具体 Issue；
|
||||
- 为简单 Query 或单表写操作强行创建聚合、工厂或多层接口；
|
||||
- 在拆票阶段改变已评审 PRD 的业务或架构决定。
|
||||
- 把“公共能力已经实现”当作业务组合根已经装配，遗漏正式 Adapter、事件消费者、监控或审计覆盖基线。
|
||||
|
||||
确认草稿后回复：
|
||||
|
||||
@@ -337,6 +342,7 @@ go test ./...
|
||||
- 验收条件有行为或测试证据；
|
||||
- 没有擅自改变架构或扩大迁移范围；
|
||||
- 相关测试通过，或存量/环境失败已准确记录。
|
||||
- 本票涉及的审计、领域流水、外部集成和可靠事件决定已经实现或按评审理由标记 N/A，覆盖基线同步更新。
|
||||
|
||||
### 9.2 PRD 完成
|
||||
|
||||
@@ -345,6 +351,7 @@ go test ./...
|
||||
- 累计 diff 通过 Standards + Spec 双轴 review；
|
||||
- 最终代码已经完成约定的全量测试；
|
||||
- 文档、迁移和人工验收项按 PRD 处理。
|
||||
- 最终发布票已验证正式 Adapter/消费者在生产组合根装配，事件版本与幂等键已登记，监控阈值有具体数值和责任人。
|
||||
|
||||
### 9.3 七月迭代完成
|
||||
|
||||
@@ -361,6 +368,8 @@ INT-07 Gateway 卡限速
|
||||
INT-08 七月迭代全链路与停机发布验收
|
||||
```
|
||||
|
||||
INT-08 还必须汇总验证：全系统审计覆盖基线无空白、旧 Writer 停写、系统配置与 Outbox 恢复使用正式审计 Adapter；所有实际生产的 Outbox 事件均已有消费者、版本和幂等键；生产告警阈值已经依据容量基线填写。任一项未闭环均不能用“公共基础已完成”代替。
|
||||
|
||||
最终结论必须区分：
|
||||
|
||||
- 本地自动化完成；
|
||||
|
||||
@@ -302,7 +302,7 @@ func (e WalletDebitedEvent) OccurredAt() time.Time { return e.occurredAt }
|
||||
```text
|
||||
数据库事务
|
||||
├── 保存聚合
|
||||
├── 保存操作日志
|
||||
├── 保存 Audit Event（该动作需要审计时）
|
||||
└── 保存 Outbox 事件
|
||||
提交事务
|
||||
↓
|
||||
@@ -330,9 +330,20 @@ func (uc *DebitWalletUseCase) Execute(ctx context.Context, cmd DebitCommand) err
|
||||
```
|
||||
|
||||
- Outbox 写入失败：事务回滚，避免“业务成功但关键事件永久丢失”。
|
||||
- 高风险成功操作的 Audit Event 写入失败：事务回滚，避免“业务事实存在但无法回答谁做了什么”。业务已回滚后的失败或拒绝审计使用独立短事务，禁止裸 goroutine。
|
||||
- Asynq 暂时不可用：不回滚已提交业务，Relay 后续重试。
|
||||
- 消费者必须幂等；涉及余额、退款、充值时使用业务键或状态条件更新。
|
||||
|
||||
### 公共能力决策
|
||||
|
||||
每个新增或修改的完整用例都必须在 PRD/Ticket 中明确以下决定，不能只写“接入公共基础”：
|
||||
|
||||
- 是否写 Audit Event；若否，写明 N/A 理由，并增量维护全系统审计覆盖基线；
|
||||
- 是否已有 Domain Ledger 作为金额、订单或状态事实，Audit Event 不得替代它；
|
||||
- 是否存在外部请求或回调，需要 Integration Log；
|
||||
- 是否存在提交后可靠副作用，需要同事务 Outbox，并明确事件类型、版本和消费者幂等键；
|
||||
- 最终发布门禁所依赖的具体公共 Ticket，不得使用无法判断完成状态的模糊依赖。
|
||||
|
||||
---
|
||||
|
||||
## 八、仓储接口
|
||||
|
||||
49
docs/tech-public-foundation/前端即时接口交接.md
Normal file
49
docs/tech-public-foundation/前端即时接口交接.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# 公共技术基础前端即时接口交接
|
||||
|
||||
## 禅道归属
|
||||
|
||||
现在需要前端处理的内容统一填写到技术用户需求“七月迭代公共开发基础”下的研发需求：
|
||||
|
||||
`[FE][TECH] 七月迭代公共状态与异步任务交互`
|
||||
|
||||
不要把本次改动拆到全局审计或各业务需求下。支付方式与系统配置页面仍归 UR#48；全局审计中心页面归“全局多视角审计”技术用户需求。
|
||||
|
||||
## 现在需要调整的接口
|
||||
|
||||
### GET /api/admin/export-tasks
|
||||
|
||||
变更类型：兼容性新增字段，原字段不删除、不改名。
|
||||
|
||||
每条任务新增或统一以下字段：
|
||||
|
||||
| 字段 | 含义 | 前端用途 |
|
||||
|---|---|---|
|
||||
| `task_id` | 稳定任务标识 | 保存并用于恢复任务查询 |
|
||||
| `total_count` | 总条数 | 展示整体进度 |
|
||||
| `success_count` | 成功条数 | 展示成功结果 |
|
||||
| `failed_count` | 失败条数 | 展示失败结果 |
|
||||
| `error_code` | 稳定错误码 | 决定错误类型，不直接展示底层错误 |
|
||||
| `error_summary` | 安全中文错误摘要 | 展示任务失败原因 |
|
||||
| `updated_at` | 最近更新时间 | 判断任务是否仍有进展 |
|
||||
|
||||
### GET /api/admin/export-tasks/{id}
|
||||
|
||||
变更类型：兼容性新增字段，原字段不删除、不改名。
|
||||
|
||||
任务详情新增或统一 `task_id`、`total_count`、`success_count`、`failed_count`、`error_code`、`error_summary`、`updated_at`，字段语义与列表一致。
|
||||
|
||||
## 页面与业务逻辑调整
|
||||
|
||||
- 所有异步任务统一使用五态：`1=待处理、2=处理中、3=已完成、4=已失败、5=已取消`。
|
||||
- “部分成功”不是新的状态。只要任务执行结束，状态就是已完成，页面通过总数、成功数、失败数表达部分成功。
|
||||
- 创建任务成功后保存 `task_id`；刷新页面或重新进入页面时查询原任务，不得再次创建任务。
|
||||
- 待处理和处理中按 2 秒、3 秒、5 秒递增轮询，之后最长保持 10 秒；进入终态立即停止。
|
||||
- 页面不可见时暂停轮询，恢复可见后立即刷新一次。
|
||||
- 403 显示无权限且不自动重试；瞬时失败保留已有数据和用户输入，并提供明确重试入口。
|
||||
- 任务失败优先展示 `error_summary`；不要把 `error_code` 或底层技术错误直接作为用户文案。
|
||||
|
||||
## 现在不需要调整的内容
|
||||
|
||||
`GET /api/admin/system-configs` 和 `PUT /api/admin/system-configs/{key}` 当前只是公共受控配置接缝，不代表前端现在要新增系统配置页面。UR#48 注册正式支付配置 Key、全局审计正式 Adapter 接入并通过发布门禁后，再按 UR#48 的页面范围联调。
|
||||
|
||||
Outbox 监控和人工恢复也不在本次前端范围内；公共基础只提供后端运维接缝，未来如需运营页面必须另行评审。
|
||||
@@ -60,10 +60,12 @@ Access Log 对 query、请求 JSON 和响应 JSON 复用大小写不敏感的递
|
||||
- 异步任务所有者：保留业务任务表和失败明细，把公共五态投影到 API，并采用租约或等价 PostgreSQL 恢复事实。
|
||||
- 发布负责人：运行前后置门禁，确认 Relay、消费者、监控和前端依次就绪后再放量。
|
||||
|
||||
## 待决策项
|
||||
## 已登记的后续闭环项
|
||||
|
||||
- Audit Event 公共实现完成后，需要在系统配置更新和 Outbox 人工恢复的组合根注入正式审计 Adapter。
|
||||
- 各下游 PRD 需要分别确认事件类型、载荷版本、消费者幂等键、业务失败明细和通知策略；公共基础不预先注册这些内容。
|
||||
- 生产阈值需结合容量基线确定待投递年龄、积压量、过期租约比例和成功率告警值；当前公共 Query 提供指标与阈值计算接缝，不固化业务容量数字。
|
||||
- 系统配置更新的正式审计 Adapter 由[全局审计 20 号票](../../.scratch/tech-global-audit/issues/20-system-config-audit-adapter.md)接入，Outbox 人工恢复由[全局审计 21 号票](../../.scratch/tech-global-audit/issues/21-outbox-recovery-audit-adapter.md)接入，并统一由[全局审计 19 号发布门禁](../../.scratch/tech-global-audit/issues/19-one-time-audit-cutover-gate.md)验证；不再作为无负责人的待决策项。
|
||||
- 各下游 PRD 必须在自己的最终发布门禁中确认事件类型、载荷版本、消费者幂等键、业务失败明细和通知策略，并引用具体公共票；[INT-08](../7月迭代/7月迭代禅道研发需求逐条录入稿.md#int-08-全链路与停机发布验收) 汇总检查，公共基础仍不猜测业务事件定义。
|
||||
- Outbox 待投递年龄、积压量、过期租约比例和成功率的生产告警值由发布负责人依据容量基线填写到 INT-08 发布清单。没有数值、负责人和验证记录时不得放量。
|
||||
|
||||
前端现在需要处理的接口字段与页面规则见[前端即时接口交接](前端即时接口交接.md)。
|
||||
|
||||
只有真实 PostgreSQL、Redis、Asynq、Fiber 接缝测试、全量 Go 测试和累计差异评审全部通过后，才可把本基础标记为可供下游接入。
|
||||
|
||||
Reference in New Issue
Block a user