完善公共基础接入与全局审计闭环
This commit is contained in:
@@ -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