junhong_cmp_fiber/openspec/changes/archive/2026-09-21-add-agent-registration-management/tasks.md

1. 注册申请查询模型

• 1.1 新增代理注册列表、详情、分页与筛选 DTO，字段覆盖注册业务状态、完整联系资料、直接上级店铺、审批状态、提交状态、失败摘要、可恢复标记和最近恢复时间，明确排除密码哈希及内部集成字段。
• 1.2 在 distributionwithdrawal Query 中实现注册列表：支持状态、申请与决定时间闭区间、手机号精确值、资料关键字、上级店铺和提交异常筛选，默认按 created_at DESC, id DESC 分页。
• 1.3 实现注册详情并与列表复用同一数据范围和投影口径；按页批量读取上级店铺、审批实例和企微上下文，避免 N+1。
• 1.4 明确三层状态投影：注册业务状态、通用审批状态和企微提交状态；由服务端计算安全失败摘要及可恢复标记。

2. 权限、范围与隐私

• 2.1 超级管理员和平台用户查询全部申请；代理强制 parent_shop_id = 当前店铺 ID，不使用 SubordinateShopIDs，无有效店铺时列表为空、详情不可见；企业账号拒绝。
• 2.2 上级店铺筛选只对超级管理员和平台用户开放；代理请求不得通过筛选参数扩大直属范围，越权与不存在保持不可区分。
• 2.3 平台和有权代理返回完整手机号与完整注册地址；响应、日志和业务审计不得包含密码哈希、验证码、企微原文、内部事件键或租约字段，审计中的手机号必须脱敏。

3. 原审批恢复用例

• 3.1 在通用审批 Application/Infrastructure 边界提供原实例查询同步、结果未知确认和稳定提交事件恢复接缝，复用 approval:{instance_id}:submission，活动事件幂等返回。
• 3.2 实现代理注册恢复用例：锁定注册记录，校验仍待审批、审批实例非空、业务类型与业务 ID 一致、调用方范围正确且上级店铺仍启用。
• 3.3 按固定优先级处理已有 sp_no、结果未知、明确未受理失败、正常重试和审批中；恢复不修改注册资料或密码哈希，不创建注册记录、审批实例、店铺、账号、钱包或层级。
• 3.4 保证平台与代理重复或并发恢复至多一次改变原提交事实；终态申请、停用上级店铺和实例关联异常返回稳定冲突。
• 3.5 为人工恢复写脱敏审计，记录注册申请、审批实例、操作者及店铺、前置提交状态、恢复动作与结果。

4. HTTP 入口与文档

• 4.1 新增后台注册申请 Handler，接入列表、详情和恢复用例；边界只做参数绑定与统一响应，权限和状态规则留在 Query/Application。
• 4.2 注册 GET /api/admin/agent-distribution-registrations、GET /api/admin/agent-distribution-registrations/{id} 和 POST /api/admin/agent-distribution-registrations/{id}/recover-approval RouteSpec。
• 4.3 同步 internal/bootstrap 装配、cmd/api/docs.go、cmd/gendocs/main.go 与 OpenAPI 描述，标明接口包含授权业务处理所需的完整手机号和地址。验证：pkg/openapi/handlers.go、cmd/api/docs.go、cmd/gendocs/main.go 已装配 AgentDistributionRegistrationHandler；重新生成的 docs/admin-openapi.yaml 包含列表、详情和恢复接口及完整资料说明。

5. 验证与规格同步

• 5.1 在维护者指定测试环境验证平台全量、代理直属、非直属与更深层不可见、无店铺代理空列表及企业账号拒绝。
• 5.2 验证状态、时间、手机号、关键字、上级店铺和提交异常筛选，核对完整联系资料可见且密码哈希、验证码与内部集成字段不泄露。
• 5.3 验证明失败、结果未知、已有 sp_no、正常重试、重复和并发恢复；核对注册记录数、审批实例数及店铺、账号、钱包数量不因恢复增加。
• 5.4 验证上级店铺停用后历史仍可查询但不能恢复，终态申请不可恢复，列表状态投影批量读取无 N+1。
• 5.5 运行 gofmt -w、go build ./cmd/api ./cmd/worker、go run cmd/gendocs/main.go，同步主 Spec 可达操作索引和证据矩阵。验证：gofmt/build/gendocs 成功；主 Spec 与 entry-capability-requirement-matrix.json、requirement-evidence.json 已加入三条后台入口。
• 5.6 运行 openspec validate add-agent-registration-management --strict、openspec doctor --json、openspec validate --all 与 ./scripts/context-health.sh。验证：目标 Change strict、doctor、context-health 通过；全量校验在主 Spec 场景修复后重跑。