issues提交

.scratch/tech-public-foundation/issues/01-public-migration-ownership-and-gates.md

@@ -0,0 +1,19 @@
+# 01 — 建立公共迁移所有权与检查门禁
+
+**What to build:** 发布负责人能够通过统一清单确认公共数据库对象的唯一迁移所有者，并在迁移前后运行可重入检查。对象定义冲突、唯一键冲突、非法状态、必填字段空值、未完成任务、未投递事件、长租约或依赖版本不满足时，检查以中文安全摘要和非零状态阻断发布；正常结果给出可核对的计数与安全标识。
+
+**Blocked by:** None — can start immediately
+
+**Status:** ready-for-agent
+
+**架构通道:** Infrastructure。
+
+**完整业务边界:** 本票收口公共数据库对象的所有权登记、迁移前置检查、后置检查、失败退出、可重入和安全输出契约。明确不创建下游业务表，不迁移历史业务数据，不接管审计、通知或业务 PRD 拥有的迁移。
+
+- [ ] 公共 Outbox、系统配置及其公共索引、约束和初始化数据均有唯一迁移所有者，下游只能声明依赖，不能复制公共 DDL。
+- [ ] 检查能够发现目标对象定义不一致、唯一键冲突、必填字段空值、非法枚举、未完成任务、未投递事件、长租约和依赖版本问题，并以非零状态阻断发布。
+- [ ] 前置和后置检查可以重复运行；重复执行不产生新业务事实，`IF NOT EXISTS` 不会掩盖已有对象定义不一致。
+- [ ] 后置检查验证约束、关键索引、异常计数和读写冒烟，输出仅包含计数、错误码与安全标识，不泄露敏感值。
+- [ ] 发布说明明确哪些结构可安全回滚、哪些已有事实只能停止生产者后向前修复，以及迁移异常时的停止条件。
+- [ ] 自动化验证覆盖空数据库、兼容存量数据库、异常数据和重复执行场景，不执行全库清理。
+

.scratch/tech-public-foundation/issues/02-transactional-public-outbox-write.md

@@ -0,0 +1,19 @@
+# 02 — 在业务事务中可靠写入公共 Outbox
+
+**What to build:** 业务开发者可以沿用现有 GORM 显式事务，在提交业务事实的同一事务中写入权威公共 Outbox 事件。事件身份和关联标识在事务内稳定持久化，业务写入或 Outbox 写入任一步失败都会整体回滚，事务中不会调用 Redis、Asynq 或外部系统。
+
+**Blocked by:** 01 — 建立公共迁移所有权与检查门禁
+
+**Status:** ready-for-agent
+
+**架构通道:** Application + Port/Adapter。
+
+**完整业务边界:** 本票收口公共 Outbox 模型、事件信封、事务内追加 Port 和一个可观察的示例写入链路。明确不定义下游业务事件含义，不实现业务消费者，不引入 UnitOfWork、事务工厂或全仓事务重构。
+
+- [ ] 公共 Outbox 具有稳定唯一的事件 ID、事件类型、载荷版本、聚合与资源定位、请求与关联标识、结构化载荷、投递生命周期、重试、租约和安全错误摘要字段。
+- [ ] Outbox 内部状态固定为 `1=待投递、2=投递中、3=已投递、4=投递失败`，常量、模型注释和公开说明保持一致。
+- [ ] 业务事实和 Outbox 使用同一 GORM 事务句柄；任一写入失败时二者均不可见，未提交事件不会被投递侧读取。
+- [ ] 事件 ID、业务键及必要快照在事务内生成并持久化，重试过程中不会重新生成事件身份。
+- [ ] 事务内不执行 Redis、Asynq、HTTP、对象存储或其他外部调用，Domain 不依赖 GORM。
+- [ ] PostgreSQL 集成测试覆盖事务成功、业务写入失败、Outbox 写入失败、事件 ID 唯一约束和回滚行为。
+

.scratch/tech-public-foundation/issues/03-outbox-at-least-once-delivery.md

@@ -0,0 +1,19 @@
+# 03 — 完成 Outbox 到 Asynq 的至少一次投递闭环
+
+**What to build:** 多个 Relay 实例可以并发领取到期 Outbox 事件，并通过有期限租约把公共事件信封可靠投递到 Asynq。瞬时失败会退避重试，进程崩溃后过期租约可恢复；入队成功但数据库标记前崩溃时允许重复投递，但始终传播原事件 ID 和关联标识。
+
+**Blocked by:** 02 — 在业务事务中可靠写入公共 Outbox
+
+**Status:** ready-for-agent
+
+**架构通道:** Infrastructure。
+
+**完整业务边界:** 本票收口 Relay 的领取、租约、续租、投递、完成、失败、退避与恢复闭环，并通过公开 Asynq Handler 验证结构化信封。明确不实现业务消费者副作用，不承诺精确一次，不迁移未触碰的旧队列生产者。
+
+- [ ] Relay 以小批量条件领取或跳锁方式取得处理权，领取、续租、完成和失败均校验当前状态与租约所有者。
+- [ ] Relay 调用统一队列客户端时传 struct 或 map；传入 `[]byte` 被明确拒绝并有回归测试防止二次序列化为 Base64。
+- [ ] 入队成功后事件标记为已投递；模拟入队成功但标记前崩溃时，恢复投递仍使用原事件 ID、载荷和关联标识。
+- [ ] 瞬时失败按有上限的指数退避安排下次领取，达到最大重试或永久失败时保留记录并产生中文安全告警。
+- [ ] 多 Relay 并发时同一时刻只有租约所有者能够完成事件；Worker 崩溃后其他实例可在租约过期后恢复领取。
+- [ ] 真实 PostgreSQL、Redis 和 Asynq 链路测试覆盖事务写入、Relay、公开 Handler 与可观察消费结果，不依赖 Relay 私有函数断言。
+

.scratch/tech-public-foundation/issues/04-outbox-observability-and-recovery.md

@@ -0,0 +1,19 @@
+# 04 — 提供 Outbox 监控和受控恢复能力
+
+**What to build:** 运维人员可以查看 Outbox 待投递量、最老积压、处理中和过期租约、成功率、重试分布、最终失败及按事件类型聚合的状态，并能对明确选择的失败或滞留事件执行受控重放或租约释放。恢复操作保留原事件内容和身份，并通过统一审计接缝记录操作者与原因。
+
+**Blocked by:** 03 — 完成 Outbox 到 Asynq 的至少一次投递闭环
+
+**Status:** ready-for-agent
+
+**架构通道:** 主通道为 Query，辅助通道为 Infrastructure。
+
+**完整业务边界:** 本票收口 Outbox 运行状态查询、指标、告警和受控恢复用例。明确不实现 Audit Event 模型或查询，不删除 Outbox，不修改已投递事件内容，不跳过消费者幂等检查。
+
+- [ ] 查询和指标覆盖待投递量、最老待投递年龄、处理中、过期租约、成功率、重试分布、最终失败和按事件类型的积压。
+- [ ] 日志、指标和告警使用事件 ID、关联 ID 与安全资源标识串联，不把完整载荷或敏感值作为日志字段或指标标签。
+- [ ] 受控重放只接受明确选择的失败或滞留事件，保留原事件 ID、载荷和关联标识，并记录操作者、原因和恢复批次。
+- [ ] 租约释放只作用于符合状态与过期条件的事件，不能越过当前租约所有者直接修改正在有效处理的事件。
+- [ ] 人工恢复通过统一审计 Port 记录；审计不可用时遵循明确的失败策略，但本票不创建独立审计表。
+- [ ] 测试覆盖积压统计、阈值告警、最终失败、选择性重放、租约释放和越权/非法状态拒绝。
+

.scratch/tech-public-foundation/issues/05-command-idempotency-contract.md

@@ -0,0 +1,19 @@
+# 05 — 提供创建命令幂等与并发职责契约
+
+**What to build:** 创建类用例可以使用调用主体、操作类型和稳定请求 ID 建立幂等作用域，并对影响业务结果的规范化字段计算带版本的请求指纹。相同请求返回原结果，同一请求 ID 携带不同业务内容时返回明确冲突，并发首写最终由 PostgreSQL 唯一约束裁决；Redis 故障不会制造重复业务事实。
+
+**Blocked by:** None — can start immediately
+
+**Status:** ready-for-agent
+
+**架构通道:** Application + Port/Adapter。
+
+**完整业务边界:** 本票收口请求指纹、幂等作用域、冲突分类和并发职责的可复用构件与公开示例。明确不建立万能幂等表，不迁移未触碰的旧订单、钱包或状态机，不用 Redis 替代数据库事实。
+
+- [ ] 请求指纹只包含影响业务结果的规范化字段，排除时间戳、签名、Token 等易变传输字段，并携带算法版本。
+- [ ] 同一作用域内相同请求 ID 和相同指纹返回原结果；不同指纹返回统一幂等冲突且不覆盖既有事实。
+- [ ] 作用域至少区分调用主体与操作类型；不同主体使用相同请求 ID 不会相互污染。
+- [ ] 并发首次提交由 PostgreSQL 唯一约束裁决，应用层预查仅用于友好返回；Redis 不可用、过期或主从切换不影响最终正确性。
+- [ ] 文档和测试明确区分请求 ID、事件 ID、业务唯一键、状态条件更新、钱包版本、Worker 租约和 Redis 防并发的职责。
+- [ ] 集成测试覆盖相同请求重放、指纹冲突、不同主体、并发首写和 Redis 故障，不修改未触碰业务模块。
+

.scratch/tech-public-foundation/issues/06-unified-async-task-contract.md

@@ -0,0 +1,19 @@
+# 06 — 冻结统一异步任务五态和查询契约
+
+**What to build:** 新接入的业务任务和前端可以复用固定五态、中文状态名、进度、结果计数、失败摘要、时间信息、租约恢复和轮询语义。任务到达业务处理终点时即为已完成，部分成功或全部业务项失败通过计数表达；只有整体无法执行时才进入已失败。
+
+**Blocked by:** None — can start immediately
+
+**Status:** ready-for-agent
+
+**架构通道:** 主通道为 Application，辅助通道为 Query。
+
+**完整业务边界:** 本票收口公共任务状态、公开投影、领取与终态更新、结构化队列载荷及前端轮询契约，并以现有导出任务作为兼容基准。明确不创建万能任务表，不迁移批量订购、设备分配、导入任务或其他未触碰业务任务。
+
+- [ ] 公共状态固定为 `1=待处理、2=处理中、3=已完成、4=已失败、5=已取消`，响应同时返回对应中文状态名。
+- [ ] 公开查询契约至少包含任务 ID、状态与名称、总数、成功数、失败数、进度、安全失败摘要、开始、完成和更新时间。
+- [ ] 业务项处理完成后满足 `total_count = success_count + failed_count`；部分成功和全部业务项失败均为已完成，不增加“部分成功”状态。
+- [ ] 待处理领取、终态进入和取消均使用预期状态条件更新；重复 Handler 遇到终态不会重新制造业务副作用。
+- [ ] 处理中任务具有租约或等价恢复记录，进程重启或重复投递后能从 PostgreSQL 事实恢复；队列载荷只包含最小结构化标识且禁止 `[]byte`。
+- [ ] 契约测试覆盖全成功、部分成功、全部业务项失败、整体失败、取消、重复消费和过期任务恢复，并记录跨仓轮询、隐藏暂停与刷新恢复语义。
+

.scratch/tech-public-foundation/issues/07-controlled-system-config-read.md

@@ -0,0 +1,19 @@
+# 07 — 交付受控系统配置注册与查询闭环
+
+**What to build:** 超级管理员可以按模块查询系统注册的配置 Key，并获得脱敏值、类型、值域提示、中文说明、只读状态和更新时间。业务模块只需注册自己拥有的 Key、类型、默认值和校验规则；公共壳层负责注册冲突检查、持久化读取、Redis 缓存与 PostgreSQL 回退，未注册数据库记录最多只读展示。
+
+**Blocked by:** 01 — 建立公共迁移所有权与检查门禁
+
+**Status:** ready-for-agent
+
+**架构通道:** 主通道为 Query，辅助通道为 Infrastructure。
+
+**完整业务边界:** 本票收口系统配置表、代码注册表、启动校验、缓存读取和超级管理员列表 API。明确不注册支付等具体业务 Key，不允许创建任意 Key，不提供原始 JSON 自由编辑器；新增 Handler 必须同步文档生成器。
+
+- [ ] 配置存储支持唯一 Key、字符串化值、`string/int/bool/json` 类型、模块、中文说明、只读与敏感属性、创建更新人与时间，且无外键或 GORM 关联标签。
+- [ ] 注册表定义稳定 Key、模块、类型、值域或枚举、默认值、只读、敏感和控件提示；重复 Key、类型冲突或非法默认值在启动或验证阶段失败。
+- [ ] 只有已认证超级管理员可按模块分页查询配置；权限不足返回统一 403，不伪装为空数据。
+- [ ] 未注册数据库 Key 默认不可写，最多按只读、可诊断方式展示；敏感配置值按注册策略脱敏。
+- [ ] PostgreSQL 是唯一事实来源；Redis 未命中、超时或不可用时回退数据库并尝试回填，缓存 Key 和默认 TTL 遵循公共常量。
+- [ ] 真实 Fiber、认证、GORM 和 Redis 测试覆盖模块过滤、四种类型、缓存命中与回退、未注册 Key、敏感值和权限边界；OpenAPI 文档生成器同步更新。
+

.scratch/tech-public-foundation/issues/08-controlled-system-config-update.md

@@ -0,0 +1,19 @@
+# 08 — 交付系统配置更新、权限和审计闭环
+
+**What to build:** 超级管理员可以按 Key 更新单个已注册且允许修改的配置。系统依次完成授权、注册检查、类型解析和值域校验，在 GORM 事务中保存事实并通过统一审计接缝记录变更；提交成功后立即失效对应缓存，缓存失效失败不会回滚数据库事实但会产生可操作告警。
+
+**Blocked by:** 07 — 交付受控系统配置注册与查询闭环
+
+**Status:** ready-for-agent
+
+**架构通道:** 主通道为简单写 Application 事务脚本，辅助通道为 Port/Adapter。
+
+**完整业务边界:** 本票收口单 Key 更新、权限、类型和值域校验、事务写入、缓存失效和审计 Port。明确不实现全局 Audit Event 模型，不提供无约束批量覆盖，不接管各业务模块的具体值域或生效规则；新增 Handler 必须同步文档生成器。
+
+- [ ] 只有超级管理员可以更新配置；未注册、只读、类型错误、非法 JSON、越界或枚举外值均返回统一中文错误且不修改事实。
+- [ ] 配置更新使用现有 GORM 显式事务完成事实写入和审计接缝调用；任一步事务内写入失败时整体回滚。
+- [ ] 审计信息包含操作者、操作类型、中文描述、变更前后事实和请求关联标识，但本票不创建独立配置审计表。
+- [ ] 提交成功后失效对应 Redis 缓存；失效失败不回滚 PostgreSQL，产生包含组件、错误码、时间窗口和安全标识的中文告警。
+- [ ] 数据库值不可解析或越界时不能静默使用错误值，按注册策略返回最后验证值或安全默认值并告警。
+- [ ] 真实 Fiber、认证、GORM 和 Redis 测试覆盖更新成功、并发更新、权限、未注册、只读、四种类型、事务回滚、缓存失效失败和审计事实；OpenAPI 文档生成器同步更新。
+

.scratch/tech-public-foundation/issues/09-access-log-recursive-redaction.md

@@ -0,0 +1,19 @@
+# 09 — 统一 Access Log 请求与响应递归脱敏
+
+**What to build:** Access Log 对 query、请求体和响应体使用同一套大小写不敏感的递归脱敏能力，覆盖嵌套对象和数组。日志先脱敏再执行 50KB 截断，并继续保留请求 ID、方法、路径、安全 query、状态、耗时、用户与终端信息及明确截断标志，方便排障而不泄露可复用凭证。
+
+**Blocked by:** None — can start immediately
+
+**Status:** ready-for-agent
+
+**架构通道:** Infrastructure。
+
+**完整业务边界:** 本票收口公共敏感字段注册、query/请求/响应 JSON 脱敏、截断与访问日志元数据。明确不修改 Audit Event 或 Integration Log 模型、Writer 与查询，不改变业务响应内容。
+
+- [ ] 公共敏感字段至少覆盖密码、口令、Token、Authorization、Cookie、密钥、Secret、签名、Nonce、验证码、支付凭证和私密 URL，匹配大小写不敏感。
+- [ ] query、请求 JSON 和响应 JSON 复用同一递归规则，嵌套对象、数组、非字符串敏感字段均被不可逆替换。
+- [ ] 请求体和响应体分别先脱敏后按 50KB 截断，并输出可机器识别的截断状态，不因序列化失败回退记录未脱敏 JSON。
+- [ ] 脱敏后仍保留方法、路径、安全 query、状态、耗时、请求 ID、IP、User-Agent、用户标识及请求/响应摘要。
+- [ ] 日志、注释和告警均使用中文，用户可见响应继续使用统一错误与响应格式。
+- [ ] 真实 Fiber 测试捕获最终 JSON 日志，覆盖嵌套结构、数组、大小写变体、query、请求与响应、超长 body 和无法序列化场景。
+

.scratch/tech-public-foundation/issues/10-sensitive-route-safe-summaries.md

@@ -0,0 +1,19 @@
+# 10 — 为敏感接口提供安全摘要策略
+
+**What to build:** 登录与 Token、支付、企微回调、文件上传下载和导出等敏感接口按路由策略记录安全摘要。无论载荷是 JSON、表单、XML、multipart、二进制还是解析失败，都不会回退记录原文，只保留事件类型、安全资源标识、大小、内容类型、摘要哈希、处理结果和截断信息等排障字段。
+
+**Blocked by:** 09 — 统一 Access Log 请求与响应递归脱敏
+
+**Status:** ready-for-agent
+
+**架构通道:** Infrastructure。
+
+**完整业务边界:** 本票收口路由级敏感策略、非 JSON 安全降级和固定回归矩阵。明确不实现登录、支付、企微、文件或导出业务逻辑，不记录完整回调正文、文件内容或临时访问能力。
+
+- [ ] 登录和 Token 接口不记录密码、验证码、访问令牌、刷新令牌或会话标识，只保留成功状态和必要主体标识。
+- [ ] 支付接口不记录支付凭证、银行卡敏感信息、二维码原文、跳转链接、渠道密钥或完整签名，只保留安全订单号、渠道类型、结果码和金额摘要。
+- [ ] 企微回调不记录加密包、解密正文、签名、Nonce、通讯录敏感字段或完整响应，只保留事件类型、安全标识、大小、哈希和处理结果。
+- [ ] 文件与导出接口不记录 multipart、二进制、Base64、文件字节、临时凭证或签名下载地址，只保留脱敏文件名、类型、大小、数量、任务标识和结果。
+- [ ] 敏感路由解析失败时只记录字段存在性、长度、内容类型、安全哈希和截断标志；普通非敏感文本也必须经过明确路由策略才可记录。
+- [ ] 真实 Fiber 回归矩阵覆盖 JSON、XML、表单、multipart、二进制、超长和不可解析载荷，并断言日志中不存在测试凭证、签名、回调原文或文件字节。
+

.scratch/tech-public-foundation/issues/11-public-migration-and-rollback-validation.md

@@ -0,0 +1,19 @@
+# 11 — 验证公共对象迁移与数据安全回滚边界
+
+**What to build:** 发布负责人可以在空数据库和带兼容存量数据的数据库上执行公共 Outbox 与系统配置的正向迁移、后置校验及允许的回滚。公共对象只创建一次且定义一致；存在重复身份、非法配置、处理中任务、未投递事件或长租约时，流程明确失败且不执行破坏性写入。
+
+**Blocked by:** 02 — 在业务事务中可靠写入公共 Outbox；07 — 交付受控系统配置注册与查询闭环
+
+**Status:** ready-for-agent
+
+**架构通道:** Infrastructure。
+
+**完整业务边界:** 本票收口公共 Outbox 和系统配置对象的迁移链路、兼容数据验证、可重入回填、后置校验和回滚边界。明确不迁移下游业务表，不删除已产生的业务事实、Outbox、审计、通知或任务结果。
+
+- [ ] 空数据库和兼容存量数据库均可执行正向迁移，公共表、索引、约束和初始化数据只创建一次且定义符合契约。
+- [ ] 构造重复事件 ID、非法配置、唯一键冲突、处理中任务、未投递事件和长租约时，前置检查以非零状态失败且不执行破坏性写入。
+- [ ] 需要回填时按稳定主键分批、记录进度并可中断重跑；重复执行不生成重复事实，最终行数守恒。
+- [ ] 后置校验覆盖约束生效、异常计数归零、关键索引可用和读写冒烟，输出不包含敏感数据。
+- [ ] 未产生业务数据的新增结构可在验证后回滚；已有 Outbox 或配置事实后，回滚流程停止生产者和 Relay、保留事实并向前修复，禁止删表清理。
+- [ ] 迁移说明记录发布顺序、停止条件、恢复步骤和测试数据隔离策略，并通过相关迁移与集成测试。
+

.scratch/tech-public-foundation/issues/12-foundation-release-gate-and-integration-contract.md

@@ -0,0 +1,19 @@
+# 12 — 建立公共基础发布门禁和下游接入契约
+
+**What to build:** 发布负责人可以通过一套公共基础整体验收判断是否允许下游接入和放量。验收使用真实 Fiber、GORM、PostgreSQL、Redis、Relay 和 Asynq 接缝，覆盖事务可靠性、至少一次投递、幂等职责、任务恢复、配置读写和 Access Log 安全，并给出下游接入顺序、运行监控、故障恢复和前端交互契约。
+
+**Blocked by:** 03 — 完成 Outbox 到 Asynq 的至少一次投递闭环；04 — 提供 Outbox 监控和受控恢复能力；05 — 提供创建命令幂等与并发职责契约；06 — 冻结统一异步任务五态和查询契约；08 — 交付系统配置更新、权限和审计闭环；10 — 为敏感接口提供安全摘要策略；11 — 验证公共对象迁移与数据安全回滚边界
+
+**Status:** ready-for-agent
+
+**架构通道:** 主通道为 Infrastructure，辅助通道为 Application 与 Query 契约。
+
+**完整业务边界:** 本票收口公共能力的端到端发布门禁、运行手册、跨仓前端契约和下游接入说明。明确不实现前端代码、Audit Event、Integration Log、站内通知、业务事件消费者或任何下游领域规则，不借验收迁移未触碰旧模块。
+
+- [ ] 整体验收通过公开接缝验证业务事务写入、Outbox Relay、Asynq Handler、重复投递、租约恢复和可观察消费结果。
+- [ ] PostgreSQL、Redis 和 Asynq 测试使用隔离数据与唯一前缀，只清理本次创建的数据，不执行全库或全缓存清空。
+- [ ] 发布顺序明确为迁移与检查、兼容 API、Relay/Worker、依赖消费者、前端；生产者不得在消费者和监控就绪前制造不可见积压。
+- [ ] 停止条件覆盖迁移异常、Outbox 持续积压或租约大量过期、配置读写不一致、脱敏回归失败和关键任务无法恢复。
+- [ ] 下游接入说明明确公共基础提供与不提供的能力，以及审计、通知和各业务 PRD 自行拥有的模型、状态机、业务唯一键、失败明细和消费者幂等。
+- [ ] 前端跨仓契约记录加载、真实空态、筛选空态、403、失败重试、任务 ID 恢复、2/3/5 秒退避、最长 10 秒、页面隐藏暂停和恢复立即刷新。
+- [ ] 中文功能总结覆盖关键流程、异常闭环、发布回滚、监控恢复和待决策项，README 增加索引；所有公共外部行为测试通过后方可标记基础就绪。