新增代理注册申请管理

openspec/changes/archive/2026-09-21-add-agent-registration-management/specs/agent-distribution-withdrawal/spec.md

@@ -0,0 +1,65 @@
+## ADDED Requirements
+
+### Requirement: 代理注册申请后台可查询
+系统 SHALL 提供 `GET /api/admin/agent-distribution-registrations` 和 `GET /api/admin/agent-distribution-registrations/{id}`，使超级管理员和平台用户查看全部代理扫码注册申请，使代理账号只查看 `parent_shop_id` 等于其当前所属店铺的直接下级申请。代理范围 MUST 仅按注册时冻结的直接上级店铺判定，不得包含更深层下级、其他店铺申请，也不得因后续店铺层级变化重新推导；无有效所属店铺的代理列表 MUST 为空，详情 MUST 与不存在不可区分。企业账号 MUST 被拒绝。
+
+列表 SHALL 支持按注册业务状态、申请时间闭区间、决定时间闭区间、手机号精确值及店铺名称、店铺编号、代理用户名、联系人关键字筛选，并支持筛选审批提交失败或结果未知。上级店铺筛选仅对超级管理员和平台用户开放。结果默认按申请时间和申请标识倒序分页。
+
+列表与详情 SHALL 返回注册申请标识、业务状态及名称、申请店铺和账号资料、联系人、完整手机号、完整省市区及详细地址、直接上级店铺标识与名称、分销码快照、申请与决定时间、驳回原因、审批实例与审批状态、审批提交状态、安全失败摘要、可恢复标记和最近恢复时间。系统 MUST NOT 返回密码哈希、短信验证码、企业微信原始响应、内部事件键或租约字段。查询 MUST 批量投影上级店铺和审批状态，列表查询次数不得随当页申请数量线性增长。
+
+#### Scenario: 平台查看全部注册申请
+- **WHEN** 超级管理员或平台用户查询代理注册申请列表
+- **THEN** 系统返回全部符合筛选条件的申请及其业务、审批和提交状态
+
+#### Scenario: 代理查看直接下级申请
+- **GIVEN** 当前代理店铺既有直接使用其分销码提交的申请，也有更深层级或其他店铺的申请
+- **WHEN** 代理查询列表或详情
+- **THEN** 系统只返回 `parent_shop_id` 等于当前店铺的申请，不返回更深层级或其他店铺申请
+
+#### Scenario: 无店铺代理查询
+- **WHEN** 未关联有效店铺的代理查询注册申请
+- **THEN** 列表返回空结果，详情与申请不存在不可区分
+
+#### Scenario: 查看完整联系资料但不返回凭证
+- **WHEN** 有权平台账号或代理查看注册申请列表或详情
+- **THEN** 响应包含完整手机号和完整注册地址，但不包含密码哈希、短信验证码、企微原始响应或内部事件字段
+
+#### Scenario: 区分业务待审批与提交异常
+- **GIVEN** 两条注册记录均为业务待审批，其中一条已进入企业微信审批，另一条提交失败或结果未知
+- **WHEN** 授权账号查询列表
+- **THEN** 系统分别返回其审批提交状态和可恢复标记，不把两条记录展示为相同的审批状态
+
+### Requirement: 代理注册原审批可受控恢复
+系统 SHALL 提供 `POST /api/admin/agent-distribution-registrations/{id}/recover-approval`，允许超级管理员、平台用户以及申请直接上级店铺的代理恢复仍处于待审批的注册申请。恢复 MUST 校验注册记录已关联唯一通用审批实例，且实例业务类型为 `agent_distribution_approval`、业务标识等于注册记录标识。无权操作与申请不存在 MUST 不可区分；上级店铺已停用时历史申请仍可查询，但待审批申请 MUST NOT 恢复。
+
+恢复 MUST 复用原审批实例和同一稳定提交事实，不得修改注册资料或密码哈希，不得新建注册记录、审批实例或第二张企业微信审批单，不得创建店铺、账号、钱包或上下级关系，也不得在本地通过或驳回申请。明确提交失败且可确认企业微信未受理时，系统 SHALL 恢复同一提交事实；提交结果未知时 MUST 优先确认原提交结果；已有企业微信审批单号时 MUST 查询同步原审批单；正常重试或已进入企业微信审批中 SHALL 幂等返回当前状态；注册记录或审批已经终态时 MUST 拒绝恢复。
+
+恢复操作 MUST 写入脱敏审计，记录注册申请、审批实例、操作者、操作者店铺、恢复前提交状态、选择的恢复动作与结果，但不得复制完整手机号、详细地址、密码哈希、企业微信原始响应或内部队列键。
+
+#### Scenario: 明确提交失败后恢复原审批
+- **GIVEN** 注册记录仍待审批，原审批提交明确失败且可确认企业微信未受理，上级店铺仍启用
+- **WHEN** 授权账号请求恢复
+- **THEN** 系统恢复同一稳定提交事实，不新增注册记录或审批实例，不创建店铺、账号或钱包
+
+#### Scenario: 提交结果未知时禁止重提
+- **GIVEN** 原审批实例提交结果未知
+- **WHEN** 授权账号请求恢复
+- **THEN** 系统进入原提交结果确认流程，在无法证明未受理前不再次创建审批
+
+#### Scenario: 已有企微审批单号时查询同步
+- **GIVEN** 原审批实例已有企业微信审批单号但本地状态未确认
+- **WHEN** 授权账号请求恢复
+- **THEN** 系统查询同步原审批单，不恢复创建提交且不生成新审批实例
+
+#### Scenario: 重复或并发恢复保持幂等
+- **WHEN** 平台账号和直接上级代理重复或并发恢复同一注册申请
+- **THEN** 系统至多一次改变原提交事实，其余请求返回相同当前状态，注册记录数和审批实例数不增加
+
+#### Scenario: 停用上级店铺不可恢复
+- **GIVEN** 注册申请的直接上级店铺已停用
+- **WHEN** 授权账号查看或恢复该待审批申请
+- **THEN** 系统允许查看历史申请但拒绝恢复，不创建任何下级实体
+
+#### Scenario: 终态申请不可恢复
+- **WHEN** 已通过或已驳回注册申请请求恢复
+- **THEN** 系统返回状态冲突，不改变注册记录、已创建实体或审批事实