## 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: 审批业务必须与具体渠道解耦
退款、线下充值及未来审批业务 MUST 只依赖渠道无关的 Approval Port、标准审批实例、标准决策和终态事件，不得在业务 Domain/Application 中引用企微、钉钉等渠道 SDK、DTO、回调状态码、模板控件 ID 或外部审批编号字段。审批实例 MUST 使用 `provider` 与通用 `external_ref` 标识渠道和外部实例；企微 `sp_no` 等渠道字段只能由对应 Adapter 转换或保存在渠道专属配置/安全快照中。

#### Scenario: 先实现退款业务核心
- **WHEN** 企微 Adapter 尚未实现但退款金额、状态机和整单终结规则开始开发
- **THEN** 退款业务 MUST 能围绕 Approval Port 和标准 `approved/rejected/cancelled/deleted/revoked_after_approved` 决策完成构建，不得依赖企微包或 `sp_no`

#### Scenario: 接入企微首个 Adapter
- **WHEN** 企微提交、回调或轮询取得渠道状态
- **THEN** WeCom Adapter MUST 将其翻译为标准审批引用与决策，再调用渠道无关 Application 用例；业务模块不得解析企微状态

#### Scenario: 未来接入其他审批渠道
- **WHEN** 后续新增钉钉或其他审批平台
- **THEN** 实施 MUST 新增对应 Adapter 和渠道配置，不得修改退款、充值、钱包、佣金、套餐或换货业务不变量

### Requirement: 审批抽象不得演变为本地流程引擎
渠道无关审批层 MUST 仅管理业务引用、真实提交人快照、`provider/external_ref`、标准状态、提交与同步 Port、标准终态事件及幂等。系统不得在本期实现审批节点编排、审批人解析、组织模型、会签/或签、审批动作页面或 BPMN；这些能力继续由外部审批平台负责。

#### Scenario: 外部渠道未就绪
- **WHEN** 业务代码已经完成但当前环境没有可用审批 Adapter 或场景配置
- **THEN** 新审批提交入口 MUST 在写入业务单、审批实例和 Outbox 前失败关闭，已存在实例仍按其原 provider 继续同步和处理

### 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 已移出范围而被删除
