# 公共技术基础功能总结

## 交付边界

本能力提供公共 Outbox 与 Relay、创建命令幂等原语、统一异步任务五态、受控系统配置、数据库发布门禁，以及 Access Log 递归脱敏和敏感路由安全摘要。公共基础只定义稳定接缝和基础设施语义，不拥有 Audit Event、Integration Log、站内通知、业务模型、业务状态机、业务唯一键、任务失败明细或业务事件消费者。

各业务 PRD 必须自行实现消费者副作用幂等，并决定使用事件 ID、业务唯一键、状态条件更新或版本号裁决重复消费。审计和通知由对应公共能力实现后注入现有 Port；系统配置更新在审计 Port 不可用时失败关闭，不另建临时审计表。

## 关键流程

### 事务事件与至少一次投递

业务 Application 在同一 GORM 事务中写入业务事实和公共 Outbox，事务内不调用 Redis、Asynq、HTTP 或对象存储。Relay 使用行锁跳过竞争记录并写入租约，再通过统一队列客户端把结构化信封交给 Asynq。公开 Handler 按稳定事件类型分发给业务消费者；入队成功但状态未落库时允许使用原事件 ID、载荷和关联标识重复投递。

瞬时错误采用有上限的指数退避；达到最大次数或收到明确永久错误后保留最终失败事实。租约过期后其他实例可以恢复领取，有效租约不能被人工释放或其他实例完成。

### 幂等与异步任务

创建命令指纹只包含影响业务结果的规范化字段，并携带算法版本。PostgreSQL 唯一约束是并发首次提交的最终裁决；Redis 只用于减少并发和改善体验。请求 ID、事件 ID、业务唯一键、状态条件、数值版本和 Worker 租约不得互相替代。

异步任务固定为 `1=待处理、2=处理中、3=已完成、4=已失败、5=已取消`。任务表由各业务拥有，公共 Adapter 通过可配置列映射执行条件领取、租约恢复、完成和取消，不建设万能任务表。部分成功或业务项全部失败仍为已完成，并满足总数等于成功数加失败数。

### 受控系统配置

业务模块在代码注册表中声明稳定 Key、类型、默认值、值域、只读和敏感策略。PostgreSQL 是唯一事实来源，Redis 仅作短缓存；缓存异常会回退数据库并产生不含配置值的安全告警。只有超级管理员可以分页查询或更新，未注册 Key 强制只读，敏感值只返回“已配置”。更新事实和审计接缝处于同一事务，提交后只失效对应缓存 Key。

### 日志安全

Access Log 对 query、请求 JSON 和响应 JSON 复用大小写不敏感的递归脱敏规则，并在脱敏后执行 50KB 截断。登录、支付、企微回调、文件和导出路由只记录白名单安全摘要；JSON、XML、表单、multipart、二进制和无法解析载荷均不得回退记录原文。

## 异常闭环与运行监控

发布和运行监控至少包含 Outbox 待投递量、最老待投递年龄、处理中数量、过期租约、成功率、重试分布、最终失败和按事件类型积压。日志和指标只使用事件 ID、关联 ID、安全资源标识、错误码和计数，禁止把完整载荷或敏感值作为标签。

人工恢复只接受显式选中的失败或过期租约事件。重放保留原事件身份与内容，记录操作者、中文原因和恢复批次；审计写入失败时整个恢复事务回滚。持续积压、租约大量过期、配置读写不一致、脱敏回归失败或关键任务无法恢复时停止放量并保持事实不变。

## 发布与回滚

发布顺序固定如下：

1. 执行只读前置检查，部署 165/166 迁移，再执行后置检查。
2. 部署兼容 API。
3. 部署 Relay/Worker 并确认指标、日志和告警可用。
4. 部署依赖消费者并验证消费者幂等和可观察结果。
5. 最后允许前端和业务生产者放量；消费者和监控就绪前禁止制造新积压。

新增表为空时可以执行 down 迁移。已有 Outbox 或配置事实后必须停止生产者和 Relay、保留事实、回滚无数据风险的应用版本并向前修复，禁止删表或清空数据降级。详细命令、停止条件和测试隔离方式见[迁移发布与数据安全回滚](迁移发布与数据安全回滚.md)。

## 前端跨仓契约

首次加载显示占位，成功且真实无数据时才显示空态，筛选无结果时提供清除入口。403 显示无权限且不重试；瞬时错误保留已有数据和输入并提供显式重试。创建成功后保存任务 ID，刷新或重新进入页面后恢复查询，不得重新创建任务。

待处理或处理中按 2 秒、3 秒、5 秒退避轮询，最长间隔 10 秒；终态停止。页面隐藏时暂停，恢复可见后立即刷新一次。字段和状态语义见[统一异步任务与前端轮询契约](统一异步任务与前端轮询契约.md)。

## 下游接入清单

- 生产者：在 Application 的既有 GORM 事务中调用 Outbox Repository，保存稳定事件类型、版本、事件 ID、业务键和关联标识。
- 消费者：在 Worker 组合根注册稳定事件类型，实现重复投递无副作用的 `EventConsumer`，并提供业务结果的可观察断言。
- 配置所有者：注册本模块拥有的配置定义；不得复制公共表 DDL，也不得由公共基础猜测业务 Key。
- 异步任务所有者：保留业务任务表和失败明细，把公共五态投影到 API，并采用租约或等价 PostgreSQL 恢复事实。
- 发布负责人：运行前后置门禁，确认 Relay、消费者、监控和前端依次就绪后再放量。

## 已登记的后续闭环项

- 系统配置更新的正式审计 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 测试和累计差异评审全部通过后，才可把本基础标记为可供下游接入。