实现七月迭代公共技术基础

docs/tech-public-foundation/功能总结.md

@@ -0,0 +1,69 @@
+# 公共技术基础功能总结
+
+## 交付边界
+
+本能力提供公共 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、消费者、监控和前端依次就绪后再放量。
+
+## 待决策项
+
+- Audit Event 公共实现完成后，需要在系统配置更新和 Outbox 人工恢复的组合根注入正式审计 Adapter。
+- 各下游 PRD 需要分别确认事件类型、载荷版本、消费者幂等键、业务失败明细和通知策略；公共基础不预先注册这些内容。
+- 生产阈值需结合容量基线确定待投递年龄、积压量、过期租约比例和成功率告警值；当前公共 Query 提供指标与阈值计算接缝，不固化业务容量数字。
+
+只有真实 PostgreSQL、Redis、Asynq、Fiber 接缝测试、全量 Go 测试和累计差异评审全部通过后，才可把本基础标记为可供下游接入。