6.4 KiB
ADDED Requirements
Requirement: 每个未完成需求必须按纵向业务切片实施
每个未完成需求 MUST 形成可独立交付的纵向任务或任务组，覆盖该切片所需的数据、Application/Domain/Query、Infrastructure、Handler/API、Worker、文档、前端契约和装配，不得按“先建表、再 Service、再 Handler”拆成相互不可验证的水平任务。每个任务 MUST 标注完整业务边界和明确不迁移的旧代码范围。
Scenario: 实施复杂资金需求
- WHEN 任务涉及钱包、充值、退款、佣金、审批或并发状态机
- THEN 同一纵向切片 MUST 收口相关不变量、事务、幂等、可靠事件、API/Worker 与异常恢复，不得把核心规则分散留在旧 Service 和新 Domain 两处
Scenario: 实施局部查询需求
- WHEN 任务仅增加列表筛选、详情投影、统计或导出读取
- THEN 任务 MUST 使用 Query 或保留现有简单读取结构，不得为形式完整创建聚合根或迁移未触碰写逻辑
Requirement: 实施必须遵守触碰式 DDD 三通道
复杂写 MUST 采用 Handler → Application UseCase → Domain → Repository/Infrastructure；简单写 MUST 采用 Handler → Application 事务脚本 → Persistence；读取 MUST 采用 Handler → Query → GORM/DTO。尚未触碰的旧用例 MAY 保持 Handler → Service → Store → Model，但不得借本期需求扩大全仓迁移。
Scenario: 选择架构通道
- WHEN 实施人员领取任一未完成纵向任务
- THEN 任务中的主/辅助通道 MUST 与其状态机、金额、并发、外部副作用或纯读取性质一致，并按任务声明限制迁移范围
Requirement: API 必须使用项目统一契约
所有新增或修改 API MUST 使用 Fiber v2、Validator、pkg/response 和 {code,msg,data,timestamp} 响应包络；不得使用 {message} 替代 msg。错误 MUST 在 pkg/errors 中定义或复用，Handler 参数校验失败统一返回 CodeInvalidParam，资源不存在与越权使用不泄露存在性的 CodeForbidden 语义，禁止向客户端拼接底层错误。
Scenario: 参数校验失败
- WHEN 调用方提交格式或范围无效的请求
- THEN API MUST 返回统一包络与
CodeInvalidParam，日志可记录详细原因但响应不得暴露 Validator、GORM 或外部 SDK 错误
Scenario: 新增 Handler
- WHEN 某纵向任务新增 Handler 或路由
- THEN 实施 MUST 同步真实路由、HTTP 方法注释、
cmd/api/docs.go和cmd/gendocs/main.go的文档生成器装配
Requirement: 查询必须保持数据权限、分页和性能边界
所有列表、详情、附件、导出和异步任务查询 MUST 以后端用户类型、店铺层级、企业范围与业务权限执行数据过滤；前端隐藏按钮不得作为授权边界。列表 MUST 默认分页 20、最大 100，并采用批量查询避免 N+1；目标性能仍为 API P95 < 200ms、P99 < 500ms、数据库查询 < 50ms。
Scenario: 越权访问资源
- WHEN 用户请求不在其店铺、企业或业务权限范围内的资源
- THEN 后端 MUST 拒绝访问且不得区分资源不存在与无权限，也不得通过通知跳转、附件引用或历史导出绕过当前权限
Scenario: 查询本页审批摘要
- WHEN 列表需要同时展示提交人、审批摘要或关联资源
- THEN Query MUST 按本页 ID 批量投影，不得逐行访问数据库或外部系统
Requirement: 数据与常量必须遵守项目基础约束
持久化 MUST 使用 GORM 与 PostgreSQL，不得直接使用 database/sql；表关联 MUST 通过 ID 显式维护，不得建立外键约束或 GORM 关联标签。常量 MUST 定义在 pkg/constants 并使用中文注释；Redis Key MUST 由 Redis{Module}{Purpose}Key(params...) 函数生成。状态类字段 MUST 使用 int，类型/方式类字段 MUST 使用 string，响应状态 MUST 提供对应中文名称字段。
Scenario: 新增迁移与状态字段
- WHEN 纵向任务需要新表、索引或状态字段
- THEN 迁移 MUST 增量、无外键、可按停机顺序执行，DTO 枚举说明 MUST 从常量原文同步且状态响应包含中文名称
Requirement: 业务可靠性设施必须保持完整
涉及跨事务副作用或外部系统的用例 MUST 保留事务、幂等、Outbox、Asynq 至少一次投递、Integration Log 和外部调用恢复能力。关键事件 MUST 与业务事实同事务写入 Outbox；消费者 MUST 使用状态条件、唯一业务键、处理租约或乐观锁保证幂等；EnqueueTask 载荷 MUST 传 struct 或 map，不得传预序列化 []byte。
Scenario: 外部调用结果未知
- WHEN 企微、支付、Gateway 或其他具有副作用的请求已经发出但结果未知
- THEN 系统 MUST 保存可恢复的 Integration Log 和业务状态，不得伪装为明确失败后盲目重试或重复资金动作
Scenario: 可靠事件投递失败
- WHEN Asynq 暂时不可用但业务事务与 Outbox 已提交
- THEN 业务事实 MUST 保留，由 Relay/Worker 后续重试；不得删除 Outbox 或改用裸 goroutine
Requirement: 前后端契约必须随纵向切片共同冻结
每条涉及页面或跨仓交互的任务 MUST 定义端别、页面入口、字段、枚举、金额/时间口径、权限、加载/空态/失败/重试/部分成功状态、轮询或刷新策略和人工验收点。当前仓库不含前端源码时 MUST 交付框架无关契约，不得虚构前端目录、组件库或状态管理方案。
Scenario: 后端完成但前端未实现
- WHEN 后端 API 和字段已交付而前端仓库尚未完成页面
- THEN 后端子项 MAY 标记完成，但前端状态、联调状态和发布状态 MUST 保持待完成
Requirement: 冻结 PRD 的异常闭环必须保留
资金、审批、异步批量、支付、Gateway 与运营商回调的正常、拒绝、失败、重复、并发、结果未知、迟到回调、部分成功和人工恢复规则 MUST 继续采用标准评审稿和对应冻结 PRD 的完整定义。本总 Change 不得以“快速测试环境交付”为由删除 Integration Log、Domain Ledger、Outbox、幂等、事务或补偿边界。
Scenario: 快速交付遇到复杂异常分支
- WHEN 某异常分支实现成本高但已被冻结 PRD 定义为资金或外部调用安全边界
- THEN 该分支 MUST 留在本轮业务实现范围，不能与自动化测试和 Audit Event 一起延期