docs: create roadmap (6 phases)

.planning/REQUIREMENTS.md

@@ -116,8 +116,53 @@
 
 ## Traceability
 
-*（由 roadmapper 在创建 ROADMAP.md 时填充）*
+*（由 roadmapper 在创建 ROADMAP.md 时填充 — 2026-03-27）*
 
-| REQ-ID | Phase |
-|--------|-------|
-| — | — |
+| REQ-ID | Phase | Status |
+|--------|-------|--------|
+| CRITICAL-01 | Phase 1 | Pending |
+| CRITICAL-02 | Phase 1 | Pending |
+| CRITICAL-03 | Phase 1 | Pending |
+| CRITICAL-04 | Phase 1 | Pending |
+| CRITICAL-05 | Phase 1 | Pending |
+| CRITICAL-06 | Phase 1 | Pending |
+| CRITICAL-07 | Phase 1 | Pending |
+| CRITICAL-08 | Phase 1 | Pending |
+| PERM-01 | Phase 2 | Pending |
+| PERM-02 | Phase 2 | Pending |
+| FIN-01 | Phase 2 | Pending |
+| FIN-02 | Phase 2 | Pending |
+| FIN-03 | Phase 2 | Pending |
+| REALNAME-01 | Phase 2 | Pending |
+| REALNAME-02 | Phase 2 | Pending |
+| REALNAME-03 | Phase 2 | Pending |
+| REALNAME-04 | Phase 2 | Pending |
+| REALNAME-05 | Phase 2 | Pending |
+| POLL-01 | Phase 2 | Pending |
+| POLL-02 | Phase 2 | Pending |
+| POLL-03 | Phase 2 | Pending |
+| POLL-04 | Phase 2 | Pending |
+| DEVICE-01 | Phase 3 | Pending |
+| DEVICE-02 | Phase 3 | Pending |
+| DEVICE-03 | Phase 3 | Pending |
+| DEVICE-04 | Phase 3 | Pending |
+| REFUND-01 | Phase 4 | Pending |
+| REFUND-02 | Phase 4 | Pending |
+| REFUND-03 | Phase 4 | Pending |
+| PAY-01 | Phase 4 | Pending |
+| PAY-02 | Phase 4 | Pending |
+| PAY-03 | Phase 4 | Pending |
+| PAY-04 | Phase 4 | Pending |
+| OPS-01 | Phase 4 | Pending |
+| OPS-02 | Phase 4 | Pending |
+| CLEAN-01 | Phase 5 | Pending |
+| CLEAN-02 | Phase 5 | Pending |
+| CLEAN-03 | Phase 5 | Pending |
+| CLEAN-04 | Phase 5 | Pending |
+| CLEAN-05 | Phase 5 | Pending |
+| CLEAN-06 | Phase 5 | Pending |
+| TRAFFIC-01 | Phase 6 | Pending |
+| TRAFFIC-02 | Phase 6 | Pending |
+| TRAFFIC-03 | Phase 6 | Pending |
+| TRAFFIC-04 | Phase 6 | Pending |
+| TRAFFIC-05 | Phase 6 | Pending |

.planning/ROADMAP.md

@@ -0,0 +1,143 @@
+# ROADMAP — 君鸿卡管系统 v1.0
+
+**Project:** 君鸿卡管系统  
+**Milestone:** v1.0 — MVP 上线准备  
+**Created:** 2026-03-27  
+**Granularity:** Standard (6 phases)  
+**Coverage:** 46/46 requirements mapped ✓  
+
+---
+
+## Phases
+
+- [ ] **Phase 1: P0 紧急修复** — 修复所有阻塞主链路的 P0 Bug，使充值→购包→佣金→实名激活全链路可跑通
+- [ ] **Phase 2: 权限/财务/实名/轮询修复** — 补全企业权限、提现财务流程、实名激活架构重构、轮询系统小修
+- [ ] **Phase 3: 设备体系完善** — 扩展设备模型字段、对接 Gateway sync-info、完善绑卡标识
+- [ ] **Phase 4: 退款 + 支付 + 运营修复** — 实现退款完整流程、补全富友支付接口、修复运营逻辑
+- [ ] **Phase 5: 代码质量清理** — 消除技术债务：佣金断链可观测、删废弃代码、修复权限不一致、迁移分层
+- [ ] **Phase 6: 流量体系改革（低峰期）** — 破坏性变更：日粒度流量表 + Redis 增量缓存 + 每日落盘任务
+
+---
+
+## Phase Details
+
+### Phase 1: P0 紧急修复
+**Goal**: 修复所有已知的主链路断点，使"充值→自动购包→佣金计算→实名激活"的完整业务链路可端到端跑通，消除数据写入混乱（实名状态常量）和并发安全漏洞（提现重复创建）  
+**Depends on**: 无（基础）  
+**Requirements**: CRITICAL-01, CRITICAL-02, CRITICAL-03, CRITICAL-04, CRITICAL-05, CRITICAL-06, CRITICAL-07, CRITICAL-08  
+**Success Criteria** (what must be TRUE):
+  1. C 端用户完成实名后，实名状态正确写入 DB（值为常量 1，不再是 2），实名激活任务正确触发
+  2. C 端用户钱包充值成功后，自动购包任务入队并被消费，佣金计算任务被正确触发
+  3. 代理代购下级场景（场景 5）的订单金额正确使用 operatorCostPrice，佣金链计算正常
+  4. 批量导入设备 Excel 后，设备记录中含 IMEI 字段，Gateway 调用不再因 IMEI 缺失而失败
+  5. 并发提交提现申请时，RowsAffected 检查生效，不会创建重复提现单
+**Plans**: TBD
+
+---
+
+### Phase 2: 权限/财务/实名/轮询修复
+**Goal**: 补全企业账号权限边界（可查但不可刷新）、修复提现流程数据完整性（审批人字段/remark 必填/激活配置并发锁）、重构实名激活判断架构（从布尔字段改为 expiry_base 枚举）、修复轮询调度和安全漏洞  
+**Depends on**: Phase 1（CRITICAL-01 先统一实名常量，REALNAME 重构再依此展开）  
+**Requirements**: PERM-01, PERM-02, FIN-01, FIN-02, FIN-03, REALNAME-01, REALNAME-02, REALNAME-03, REALNAME-04, REALNAME-05, POLL-01, POLL-02, POLL-03, POLL-04  
+**Success Criteria** (what must be TRUE):
+  1. 企业账号可以调用 Resolve 接口查询被授权资产，但无法触发 Refresh 刷新运营商数据
+  2. 提现审批通过后，approved_by 和 approved_at 字段正确填充；拒绝时若 remark 为空则返回校验错误
+  3. 同时激活两个提现配置时，数据库行锁生效，不会出现两条 active=true 的记录
+  4. 数据库中 tb_package 表不再有 enable_realname_activation 字段，改为 expiry_base 字段（值为 from_activation 或 from_purchase）
+  5. C 端购买普通号卡套餐时，实名检查按卡类型（card_category == "normal"）判断，逻辑简洁正确
+  6. polling:protect 任务正确进入调度器，停复机时若 gatewayClient 为 nil 返回业务错误而非静默成功
+**Plans**: TBD
+
+---
+
+### Phase 3: 设备体系完善
+**Goal**: 扩展设备数据模型，对接 Gateway sync-info 接口实现设备在线状态/固件版本实时同步，建立"当前使用卡"标识，使设备详情页展示真实状态  
+**Depends on**: Phase 1（设备导入 IMEI 修复在 CRITICAL-07 完成）  
+**Requirements**: DEVICE-01, DEVICE-02, DEVICE-03, DEVICE-04  
+**Success Criteria** (what must be TRUE):
+  1. tb_device 表含 online_status / last_online_time / software_version / switch_mode / last_gateway_sync_at 字段（DB 迁移已执行）
+  2. 调用设备刷新接口后，设备的在线状态、固件版本、当前使用卡（is_current）从 Gateway 实时更新
+  3. tb_device_sim_binding 表含 is_current 字段，同一设备同一时刻只有一条 is_current=true 的绑定记录
+  4. 设备详情接口返回数据包含 online_status、software_version 等字段，值与 Gateway 同步结果一致
+**Plans**: TBD
+
+---
+
+### Phase 4: 退款 + 支付 + 运营修复
+**Goal**: 实现完整退款流程（申请→审批→佣金回扣），补全富友支付 JSAPI/小程序接口（替换留桩），修复运营逻辑断点（卡状态 3/4 触发、payment_status 枚举统一）  
+**Depends on**: Phase 2（佣金链路稳定后再做退款佣金回扣）  
+**Requirements**: REFUND-01, REFUND-02, REFUND-03, PAY-01, PAY-02, PAY-03, PAY-04, OPS-01, OPS-02  
+**Success Criteria** (what must be TRUE):
+  1. tb_refund_request 表存在，退款申请/列表/详情/审批/拒绝/退回/重提共 7 个接口可正常调用
+  2. 退款审批通过后，代理佣金钱包按比例扣减（使用整数算术，无 float64 精度误差），负向交易流水写入
+  3. 富友支付 JSAPI 和小程序接口可正常发起支付，返回前端所需调起参数（FuiouPayJSAPIResponse DTO）
+  4. 平台代理使用钱包代购资产时，正确使用资产所属代理成本价，绕过代理身份检查
+  5. IoT 卡/设备在套餐激活成功后 status 更新为 3，最后一个 active 套餐到期后 status 更新为 4
+  6. C 端和管理端 payment_status 枚举值一致（1/2/3/4），不再存在独立的 C 端映射函数
+**Plans**: TBD
+
+---
+
+### Phase 5: 代码质量清理
+**Goal**: 消除技术债务：使佣金断链可观测（创建零额待审记录），删除废弃的 sim:status:sync 任务代码，修复错误被吞、分层违规、权限不一致等问题，确保 bootstrap 完整注入所有回调  
+**Depends on**: Phase 4（所有业务功能稳定后集中清理）  
+**Requirements**: CLEAN-01, CLEAN-02, CLEAN-03, CLEAN-04, CLEAN-05, CLEAN-06  
+**Success Criteria** (what must be TRUE):
+  1. 佣金链计算遇到断链时，创建 status=99（amount=0）的待审记录，日志可见，不再静默跳过
+  2. 代码库中不再有 sim:status:sync 任务相关代码（注册行、常量、sim.go、sync/service.go）
+  3. asset/service.go 中的 cards 错误被记录为 Warn 日志，不再被 `_` 吞掉
+  4. client_order Handler 订单查询通过 Service 层调用，不再直接访问 DB
+  5. 停复机回调（StopResumeCallback / ResumeCallback）在 bootstrap 中正确注入，套餐联动触发正常
+**Plans**: TBD
+
+---
+
+### Phase 6: 流量体系改革（低峰期）
+**Goal**: 重构流量统计架构为"日粒度 DB 落盘 + Redis 增量缓存"模式，解决运营商自然月归零覆盖问题，提供今日 Redis + 历史 DB 两段数据的统一查询层  
+**Depends on**: Phase 5（代码清理完成，系统稳定，降低破坏性变更风险）  
+**Requirements**: TRAFFIC-01, TRAFFIC-02, TRAFFIC-03, TRAFFIC-04, TRAFFIC-05  
+**Success Criteria** (what must be TRUE):
+  1. tb_card_daily_usage 表存在，含唯一约束 (iot_card_id, date)（DB 迁移已执行）
+  2. 流量轮询写入时，仅在有增量时写 Redis，不再直接覆盖 current_month_usage_mb
+  3. 每日凌晨 2 点 Asynq Scheduler 任务执行：SCAN Redis Key → UPSERT tb_card_daily_usage → 删 Key，日志可验证
+  4. current_month_usage_mb 使用增量累加而非覆盖，运营商自然月归零不会影响 DB 中的历史累计值
+  5. GetDailyUsage 接口返回"今日 Redis 数据 + 历史 DB 日粒度数据"合并结果，兼容两段数据
+**Plans**: TBD
+**⚠️ 部署警告**: 此 Phase 涉及 DB 迁移 + Redis 架构变更，必须在低峰期（凌晨 2~5 点）独立部署
+
+---
+
+## Progress
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. P0 紧急修复 | 0/1 | Not started | - |
+| 2. 权限/财务/实名/轮询修复 | 0/1 | Not started | - |
+| 3. 设备体系完善 | 0/1 | Not started | - |
+| 4. 退款 + 支付 + 运营修复 | 0/1 | Not started | - |
+| 5. 代码质量清理 | 0/1 | Not started | - |
+| 6. 流量体系改革（低峰期）| 0/1 | Not started | - |
+
+---
+
+## Requirement Coverage
+
+**Total v1 requirements:** 46  
+**Mapped:** 46 ✓  
+
+| Category | Count | Phase |
+|----------|-------|-------|
+| CRITICAL | 8 | Phase 1 |
+| PERM | 2 | Phase 2 |
+| FIN | 3 | Phase 2 |
+| REALNAME | 5 | Phase 2 |
+| POLL | 4 | Phase 2 |
+| DEVICE | 4 | Phase 3 |
+| REFUND | 3 | Phase 4 |
+| PAY | 4 | Phase 4 |
+| OPS | 2 | Phase 4 |
+| CLEAN | 6 | Phase 5 |
+| TRAFFIC | 5 | Phase 6 |
+
+---
+*Roadmap created: 2026-03-27*

.planning/STATE.md

@@ -0,0 +1,95 @@
+# Project State — 君鸿卡管系统
+
+**Project:** 君鸿卡管系统 v1.0  
+**Milestone:** v1.0 — MVP 上线准备  
+**Last Updated:** 2026-03-27  
+
+---
+
+## Current Position
+
+| Field | Value |
+|-------|-------|
+| **Current Phase** | 1 — P0 紧急修复 |
+| **Current Plan** | None (planning phase) |
+| **Status** | Planning |
+| **Phase Progress** | 0/8 requirements complete |
+
+```
+Progress: [ 1 ]──[ 2 ]──[ 3 ]──[ 4 ]──[ 5 ]──[ 6 ]
+           ▲
+           Planning
+```
+
+---
+
+## Project Reference
+
+**Core Value:** 业务链路完整可用——代理能采购分配卡/设备，C端客户能充值购包激活套餐，佣金能正确计算并可提现。这条主链路必须端到端跑通。
+
+**Current Focus:** Phase 1 — 修复 8 个阻塞主链路的 P0 Bug（实名常量、自动购包、佣金链、设备导入、提现并发）
+
+---
+
+## Phase Summary
+
+| Phase | Name | Requirements | Status |
+|-------|------|--------------|--------|
+| 1 | P0 紧急修复 | CRITICAL-01~08（8项） | Not started |
+| 2 | 权限/财务/实名/轮询修复 | PERM-01~02, FIN-01~03, REALNAME-01~05, POLL-01~04（14项） | Not started |
+| 3 | 设备体系完善 | DEVICE-01~04（4项） | Not started |
+| 4 | 退款 + 支付 + 运营修复 | REFUND-01~03, PAY-01~04, OPS-01~02（9项） | Not started |
+| 5 | 代码质量清理 | CLEAN-01~06（6项） | Not started |
+| 6 | 流量体系改革（低峰期）| TRAFFIC-01~05（5项） | Not started |
+
+---
+
+## Performance Metrics
+
+| Metric | Value |
+|--------|-------|
+| Phases total | 6 |
+| Requirements v1 | 46 |
+| Requirements mapped | 46/46 (100%) |
+| Plans created | 0 |
+| Plans complete | 0 |
+| Phases complete | 0/6 |
+
+---
+
+## Accumulated Context
+
+### Key Decisions
+- TRAFFIC（Phase 6）必须独立部署，低峰期（凌晨 2~5 点），涉及 DB 迁移 + Redis 架构变更
+- REALNAME-01~05 是原子重构，必须在一个 plan 内完整执行，不可拆分
+- REFUND 退款佣金回扣（REFUND-03）必须使用整数算术，禁用 float64
+- CRITICAL-02 依赖 CRITICAL-01，CRITICAL-05 依赖 CRITICAL-04
+- DEVICE-02/03/04 依赖 DEVICE-01（字段扩展先行）
+- REFUND-02/03 依赖 REFUND-01（数据模型先行）
+
+### Architecture Notes
+- 双进程（API + Worker），依赖集中在 bootstrap 装配
+- PollingHandler 缺 asynqClient（CRITICAL-03 修复），AutoPurchaseHandler 未注册（CRITICAL-04 修复）
+- StopResumeCallback / ResumeCallback 未注入（CLEAN-06 修复）
+- 流量体系当前用直接覆盖写，Phase 6 改为增量累加 + 日粒度 DB
+
+### Known Risks
+- sellerCostPrice 错误赋值可能不止场景 5（CRITICAL-06 需逐一检查 6 处）
+- 分佣树形遍历无循环检测（不在当前 scope，v2 考量）
+- 店铺软删除无级联检查（v2 考量）
+
+---
+
+## Session Continuity
+
+**Next Action:** Run `/gsd-plan-phase 1` to create detailed plan for Phase 1 (P0 紧急修复)
+
+**Context Files:**
+- `.planning/ROADMAP.md` — 完整路线图和成功标准
+- `.planning/REQUIREMENTS.md` — 46 个 v1 需求（含 Traceability 表）
+- `.planning/PROJECT.md` — 项目背景和约束
+- `.planning/research/SUMMARY.md` — 技术研究和陷阱分析
+- `.sisyphus/plans/修正业务-完整方案.md` — 每个 Bug 的完整修复规格（含代码片段）
+
+---
+*State initialized: 2026-03-27*

CLAUDE.md

@@ -624,3 +624,327 @@ func RedisOrderCreateLockKey(carrierType string, carrierID uint) string
   big deal of it.
 
   4. **Never interrupt the flow** to give grammar lessons. Corrections are silent and brief — the user's focus is on the task, not the language.
+
+<!-- GSD:project-start source:PROJECT.md -->
+## Project
+
+**君鸿卡管系统**
+
+物联网卡（IoT SIM）+ 号卡 + 设备全生命周期管理平台，支持多级代理商体系和分佣结算。平台以 B 端代理商为核心分销渠道，兼顾 C 端个人客户和企业客户，覆盖从卡/设备采购、分配、激活、套餐购买到佣金结算的完整业务链路。当前处于 MVP 阶段，核心功能模块已完成，目标是修复所有已知业务链路断点、补全缺失功能，将系统调整至可生产上线状态。
+
+**Core Value:** **业务链路完整可用**——代理能采购分配卡/设备，C端客户能充值购包激活套餐，佣金能正确计算并可提现。这条主链路必须端到端跑通。
+
+### Constraints
+
+- **Tech Stack**: 严格使用 Fiber v2 + GORM + Asynq + PostgreSQL + Redis，不引入替代框架
+- **No Tests**: 项目不写自动化测试，人工验收（rg + go build + DBHub + 日志）
+- **Language**: 所有注释/日志/错误消息/文档使用中文，变量/函数名使用英文
+- **No Foreign Keys**: 禁止数据库外键约束，关联通过 ID 字段在代码层维护
+- **方案 E 风险**: 流量体系改革涉及 DB 迁移 + Redis 架构，必须低峰期发布，单独规划
+<!-- GSD:project-end -->
+
+<!-- GSD:stack-start source:codebase/STACK.md -->
+## Technology Stack
+
+## Languages
+- Go 1.25.x - 应用代码、API、Worker、OpenAPI 生成和基础设施脚本，依据 `go.mod`、`cmd/api/main.go`、`cmd/worker/main.go`、`cmd/gendocs/main.go`
+- YAML - 配置与部署编排，见 `pkg/config/defaults/config.yaml`、`docker-compose.prod.yml`、`.gitea/workflows/deploy.yaml`
+- Dockerfile - API/Worker 容器构建，见 `Dockerfile.api`、`Dockerfile.worker`
+- Makefile - 本地构建、文档生成、迁移命令，见 `Makefile`
+## Runtime
+- Go runtime；API 服务基于 Fiber HTTP 服务器，见 `cmd/api/main.go`
+- 独立 Worker 进程处理异步任务与调度，见 `cmd/worker/main.go`
+- 生产容器基础镜像为 Alpine，构建镜像使用 Go 1.25.6 Alpine，见 `Dockerfile.api`、`Dockerfile.worker`
+- Go Modules，见 `go.mod`
+- Lockfile: `go.sum` present
+## Frameworks
+- Fiber v2.52.9 - HTTP 框架与路由宿主，见 `go.mod`、`cmd/api/main.go`
+- GORM v1.31.1 + `gorm.io/driver/postgres` v1.6.0 - PostgreSQL ORM 与连接层，见 `go.mod`、`pkg/database/postgres.go`
+- Viper v1.21.0 - 嵌入式默认配置 + 环境变量覆盖，见 `go.mod`、`pkg/config/loader.go`
+- Asynq v0.25.1 - 任务提交、Worker 消费、定时任务，见 `go.mod`、`pkg/queue/client.go`、`pkg/queue/server.go`、`cmd/worker/main.go`
+- sonic v1.14.2 - Fiber JSON 编解码与任务载荷序列化，见 `go.mod`、`cmd/api/main.go`、`pkg/queue/client.go`
+- validator/v10 v10.28.0 - DTO 校验依赖，见 `go.mod`
+- zap v1.27.1 - 应用日志与 SQL 日志，见 `go.mod`、`pkg/logger/logger.go`、`pkg/database/postgres.go`
+- lumberjack.v2 v2.2.1 - 日志轮转，见 `go.mod`、`pkg/logger/logger.go`
+- swaggest/openapi-go v0.2.60 - OpenAPI 3.0.3 文档生成，见 `go.mod`、`pkg/openapi/generator.go`
+## Build / Dev / Deploy
+- `Makefile` 定义 `build`、`run`、`run-worker`、`docs`、`migrate-*` 目标，见 `Makefile`
+- API 与 Worker 使用多阶段 Docker 构建，编译产物分别来自 `./cmd/api` 与 `./cmd/worker`，见 `Dockerfile.api`、`Dockerfile.worker`
+- 生产编排使用 Docker Compose，运行 `api` 与 `worker` 两个服务，见 `docker-compose.prod.yml`
+- Gitea Actions 工作流构建镜像、推送私有镜像仓库并在主分支执行 `docker compose up -d`，见 `.gitea/workflows/deploy.yaml`
+- API 启动时会生成 `logs/openapi.yaml`，见 `cmd/api/main.go`、`cmd/api/docs.go`
+- 手动文档命令 `make docs` 运行 `cmd/gendocs/main.go`，输出 `docs/admin-openapi.yaml`，见 `Makefile`、`cmd/gendocs/main.go`
+## Storage, Data, Messaging
+- PostgreSQL 是唯一检测到的主数据库；连接、连接池、GORM logger、Ping 校验位于 `pkg/database/postgres.go`
+- Redis 用于认证、缓存、队列后端、限流存储和配置缓存，见 `pkg/database/redis.go`、`cmd/api/main.go`、`internal/service/wechat_config/service.go`
+- Asynq 直接复用 Redis 连接配置作为消息后端，见 `pkg/queue/client.go`、`pkg/queue/server.go`
+- Worker 内注册订单超时、告警检查、数据清理等调度任务，见 `cmd/worker/main.go`
+- S3 兼容对象存储通过 AWS SDK v1 实现，支持上传、下载、预签名 URL、临时文件下载，见 `pkg/storage/s3.go`、`pkg/storage/service.go`
+## Configuration
+- 默认配置从嵌入文件 `pkg/config/defaults/config.yaml` 读取，见 `pkg/config/embedded.go`
+- 运行时使用 `JUNHONG_` 前缀环境变量覆盖，见 `pkg/config/loader.go`
+- 必填配置校验包括数据库、Redis、JWT，见 `pkg/config/config.go`
+- 服务与超时：`server.*`，见 `pkg/config/config.go`
+- PostgreSQL：`database.*`，见 `pkg/config/config.go`
+- Redis：`redis.*`，见 `pkg/config/config.go`
+- Asynq：`queue.*`，见 `pkg/config/config.go`
+- 日志：`logging.*`，见 `pkg/config/config.go`
+- 短信：`sms.*`，见 `pkg/config/config.go`
+- 对象存储：`storage.*`，见 `pkg/config/config.go`
+- 外部 Gateway：`gateway.*`，见 `pkg/config/config.go`
+- 微信公众号/小程序/支付配置不走 Viper 主配置，业务侧从数据库表 `tb_wechat_config` 读取并缓存到 Redis，见 `internal/model/wechat_config.go`、`internal/service/wechat_config/service.go`、`pkg/wechat/config.go`
+## Logging & Observability
+- `pkg/logger/logger.go` 初始化 app/access 双 logger；生产模式写 JSON，开发模式 app logger 同时输出控制台
+- `pkg/logger/middleware.go` 记录 method、path、query、status、duration、request_id、ip、user_agent、user_id、请求/响应 body
+- `pkg/database/postgres.go` 自定义 GORM logger，记录错误、慢查询和普通 SQL trace
+- `Dockerfile.api` 与 `docker-compose.prod.yml` 均通过 `GET /health` 做容器健康检查
+## Notable Dependencies
+- `github.com/gofiber/fiber/v2` - API 服务核心框架，见 `go.mod`、`cmd/api/main.go`
+- `github.com/google/uuid` - 请求 ID 生成，见 `cmd/api/main.go`
+- `gorm.io/gorm`、`gorm.io/driver/postgres` - ORM 与 PostgreSQL 驱动，见 `go.mod`、`pkg/database/postgres.go`
+- `github.com/redis/go-redis/v9` - Redis 客户端，见 `go.mod`、`pkg/database/redis.go`
+- `github.com/hibiken/asynq` - 队列与调度器，见 `go.mod`、`pkg/queue/*.go`、`cmd/worker/main.go`
+- `github.com/bytedance/sonic` - JSON 编解码，见 `cmd/api/main.go`、`pkg/queue/client.go`
+- `github.com/xuri/excelize/v2` - Excel 导入处理依赖，见 `go.mod`; 任务消费方在 `internal/task/iot_card_import.go`、`internal/task/device_import.go` 调用 Excel 解析
+- `github.com/ArtisanCloud/PowerWeChat/v3` - 微信公众号与微信支付 SDK，见 `go.mod`、`pkg/wechat/official_account.go`、`pkg/wechat/payment.go`
+- `github.com/aws/aws-sdk-go` - S3 兼容对象存储客户端，见 `go.mod`、`pkg/storage/s3.go`
+## Platform Requirements
+- 需要 PostgreSQL、Redis、JWT 密钥与 `JUNHONG_` 环境变量；`config.Load()` 在启动时强校验，见 `pkg/config/config.go`
+- `make docs` 需要 Go 环境；`migrate-*` 目标需要系统安装 `migrate` 命令，见 `Makefile`
+- 目标运行形态是 Docker 化 API + Worker 双进程部署，见 `Dockerfile.api`、`Dockerfile.worker`、`docker-compose.prod.yml`
+- 镜像发布到私有仓库 `registry.boss160.cn`，见 `.gitea/workflows/deploy.yaml`
+## Evidence
+- `go.mod`
+- `README.md`
+- `cmd/api/main.go`
+- `cmd/api/docs.go`
+- `cmd/worker/main.go`
+- `cmd/gendocs/main.go`
+- `pkg/config/config.go`
+- `pkg/config/loader.go`
+- `pkg/config/embedded.go`
+- `pkg/config/defaults/config.yaml`
+- `pkg/database/postgres.go`
+- `pkg/database/redis.go`
+- `pkg/queue/client.go`
+- `pkg/queue/server.go`
+- `pkg/queue/handler.go`
+- `pkg/logger/logger.go`
+- `pkg/logger/middleware.go`
+- `pkg/openapi/generator.go`
+- `pkg/openapi/handlers.go`
+- `pkg/storage/s3.go`
+- `pkg/storage/service.go`
+- `pkg/wechat/config.go`
+- `pkg/wechat/official_account.go`
+- `pkg/wechat/payment.go`
+- `pkg/sms/client.go`
+- `internal/gateway/client.go`
+- `Makefile`
+- `Dockerfile.api`
+- `Dockerfile.worker`
+- `docker-compose.prod.yml`
+- `.gitea/workflows/deploy.yaml`
+<!-- GSD:stack-end -->
+
+<!-- GSD:conventions-start source:CONVENTIONS.md -->
+## Conventions
+
+## Naming Patterns
+- Go 源码使用 `snake_case.go` 或按领域拆分的普通小写命名；路由文件按模块命名放在 `internal/routes/*.go`，Handler 按域放在 `internal/handler/admin/*.go`、`internal/handler/auth/*.go`、`internal/handler/app/*.go`。
+- OpenAPI 与规范文档使用明确用途命名，例如 `docs/api-documentation-guide.md`、`docs/admin-openapi.yaml`、`cmd/api/docs.go`、`cmd/gendocs/main.go`。
+- 规范脚本使用动词前缀命名，例如 `scripts/check-all.sh`、`scripts/check-service-errors.sh`、`scripts/check-comment-paths.sh`、`scripts/verify_migration/main.go`。
+- 导出函数/方法使用 Go 的 `PascalCase`，例如 `NewAccountHandler()`、`Create()`、`Success()`、`RedisOrderIdempotencyKey()`，证据见 `internal/handler/admin/account.go`、`pkg/response/response.go`、`pkg/constants/redis.go`。
+- 未导出帮助函数使用 `camelCase`，例如 `generateOpenAPIDocs()`、`generateAdminDocs()`、`handleError()`、`safeLogWithLevel()`，证据见 `cmd/api/docs.go`、`cmd/gendocs/main.go`、`pkg/errors/handler.go`。
+- 局部变量使用英文 `camelCase`，例如 `outputPath`、`httpStatus`、`roleID`、`groupPath`，证据见 `cmd/api/docs.go`、`pkg/errors/handler.go`、`internal/handler/admin/account.go`。
+- 错误变量统一使用 `err`，成功返回数据常用业务名，例如 `account`、`accounts`、`roles`，证据见 `internal/handler/admin/account.go`。
+- 结构体和接口使用 `PascalCase`，接口语义化命名，配合 `-er` 后缀规则；项目规范明确要求接口名使用 `-er`，见 `AGENTS.md`。
+- 路由文档元数据类型使用语义名，如 `RouteSpec`、`FileUploadField`，证据见 `internal/routes/registry.go`。
+## Code Style
+- 使用 `gofmt`；项目在 `AGENTS.md` 明确要求“使用 gofmt 格式化”。
+- 代码风格遵循 Go 惯用法，避免 Java 式过度抽象；证据见 `AGENTS.md` 的“Go 惯用法 vs Java 风格”。
+- 仓库未检测到 `.golangci.yml`、`golangci-lint`、`eslint`、`prettier` 之类自动 lint 配置；当前质量门主要依赖 shell 脚本和人工审查。
+- `scripts/check-service-errors.sh`：扫描 `internal/service/**/*.go` 中的 `fmt.Errorf`，要求改用 `errors.New()` / `errors.Wrap()`。
+- `scripts/check-comment-paths.sh`：扫描 `internal/handler/` 中残留的 `/api/v1` 注释，要求改成真实路径 `/api/admin`、`/api/h5`、`/api/c/v1`。
+- `scripts/check-all.sh`：串行执行以上两个检查。
+- 当前仓库与脚本规则存在冲突：`internal/service/polling/alert_service.go` 仍存在 4 处 `fmt.Errorf(...)`，按 `scripts/check-service-errors.sh` 的规则属于违规现状。
+## Language & Comment Requirements
+- 用户可见内容、日志、注释、文档、提交信息都使用中文；变量名、函数名、类型名使用英文，证据见 `AGENTS.md` 的“语言要求”。
+- 导出包、结构体、接口、函数、方法、常量、变量必须有中文文档注释，证据见 `AGENTS.md`。
+- Handler 方法注释必须包含 HTTP 方法与真实路径；实际示例见 `internal/handler/admin/account.go`、`internal/handler/callback/payment.go`。
+- 注释解释“为什么”，不要复述代码；复杂逻辑必须有实现注释，证据见 `AGENTS.md`。
+- 常量必须带中文注释；实际示例见 `pkg/constants/constants.go`、`pkg/constants/redis.go`。
+## Import Organization
+- 多数组件按“标准库 → 项目包/第三方包”分组，并保留空行分隔，证据见 `internal/handler/admin/account.go`、`pkg/errors/handler.go`、`cmd/gendocs/main.go`。
+- 项目使用完整 module import path，未体现短别名路径；必要时用语义别名，例如 `apphandler`、`accountService`，证据见 `cmd/gendocs/main.go`、`internal/handler/admin/account.go`。
+- 未检测到 TS/JS 式路径别名；Go 代码通过 module path `github.com/break/junhong_cmp_fiber/...` 引用。
+## Layering Rules
+- 必须遵循 `Handler → Service → Store → Model`，证据见 `AGENTS.md` 与 `README.md`。
+- Handler 只做参数解析、上下文读取、调用 service、返回统一响应；示例见 `internal/handler/admin/account.go`。
+- Service 承载业务逻辑，并向下调用 Store；项目规范在 `AGENTS.md` 明确禁止在 Handler 中写业务逻辑。
+- Store 负责数据访问和事务；规范说明见 `AGENTS.md`、`README.md`。
+- Model/DTO 定义请求、响应和持久化结构；OpenAPI 文档也依赖 DTO 元数据，证据见 `docs/api-documentation-guide.md`。
+## Error Handling
+- 所有错误码与应用错误类型集中在 `pkg/errors/`，证据见 `pkg/errors/codes.go`、`pkg/errors/errors.go`、`pkg/errors/handler.go`、`AGENTS.md`。
+- Handler 层不要把底层错误直接暴露给客户端；参数校验失败统一返回 `errors.New(errors.CodeInvalidParam)` 或其中文变体，证据见 `AGENTS.md`、`internal/handler/admin/account.go`。
+- Service 层对外不要返回 `fmt.Errorf(...)`，要返回 `errors.New(...)` 或 `errors.Wrap(...)`；脚本 `scripts/check-service-errors.sh` 专门检查这一点。
+- 全局错误处理使用 `pkg/errors/handler.go` 的 `SafeErrorHandler()` / `handleError()`，统一输出 `{code, data, msg, timestamp}`，并按错误码映射 HTTP 状态码与日志级别。
+- 5xx 响应统一走通用中文消息，避免泄露敏感信息，证据见 `pkg/errors/handler.go`。
+- `pkg/errors/codes.go` 定义 1000-1999 客户端错误、2000-2999 服务端错误。
+- `pkg/errors/codes.go` 在 `init()` 校验全部错误码都必须映射消息，新增错误码时要同步维护 `allErrorCodes` 和 `errorMessages`。
+## Response Format
+- 所有 API 成功响应统一使用 `pkg/response/response.go`：`{code, data, msg, timestamp}`。
+- `Success()` 返回 `msg: "success"`；`SuccessWithMessage()` 允许覆盖消息；`SuccessWithPagination()` 将分页数据包进 `PaginationData`。
+- Handler 成功路径直接调用 `response.Success()` / `response.SuccessWithPagination()`；实际示例见 `internal/handler/admin/account.go`、`internal/handler/admin/iot_card.go`、`internal/handler/admin/shop.go`。
+- 错误路径直接 `return err` 交给全局 ErrorHandler，不在 Handler 内手动拼接 JSON，证据见 `internal/handler/admin/account.go`、`pkg/errors/handler.go`。
+## Constant Management
+- 所有常量统一放在 `pkg/constants/`，证据见 `AGENTS.md` 与 `pkg/constants/constants.go`、`pkg/constants/redis.go`。
+- 禁止硬编码字符串与 magic numbers；公共业务值放进 `pkg/constants/constants.go`。
+- Redis Key 必须通过函数生成，而不是手写字符串，命名格式使用 `Redis{Module}{Purpose}Key(...)`，证据见 `pkg/constants/redis.go` 与 `AGENTS.md`。
+- 常量要配中文注释；`pkg/constants/constants.go` 中的用户类型、任务类型、分页上限、默认管理员信息都按此方式组织。
+## API / OpenAPI Conventions
+- 所有 HTTP 路由都应在 `internal/routes/*.go` 中通过 `Register()` 注册，不要直接 `router.Get/Post/...`，证据见 `docs/api-documentation-guide.md`、`internal/routes/registry.go`。
+- `Register()` 同时负责 Fiber 路由注册和 OpenAPI 生成；当 `doc != nil` 时，会把 `/:id` 转为 OpenAPI 的 `/{id}`，证据见 `internal/routes/registry.go`。
+- 每个接口需要提供中文 `Summary`，可选 Markdown `Description`，并声明 `Input`、`Output`、`Tags`、`Auth`；证据见 `internal/routes/registry.go`、`docs/api-documentation-guide.md`。
+- DTO 字段必须使用 `description` 标签，不依赖行尾注释；枚举字段要在 `description` 中列出可选值，证据见 `docs/api-documentation-guide.md`。
+- 新增 Handler 时，除业务接线外，还必须同步更新 `internal/bootstrap/types.go`、`internal/bootstrap/handlers.go`、`internal/routes/admin.go`、`cmd/api/docs.go`、`cmd/gendocs/main.go`，证据见 `docs/api-documentation-guide.md` 与 `AGENTS.md`。
+- 文档生成命令使用 `go run cmd/gendocs/main.go` 或 `make docs`；代码证据见 `cmd/gendocs/main.go`、`Makefile`。
+## Documentation Expectations
+- 每个功能应在 `docs/{feature-id}/` 创建总结文档，并同步更新 `README.md`，证据见 `AGENTS.md`。
+- 文档和说明统一使用中文。
+- API 文档规范集中在 `docs/api-documentation-guide.md`；开发总规范集中在 `AGENTS.md`。
+- `README.md` 仍保留旧的自动化测试与覆盖率章节、旧项目结构中的 `tests/` 目录描述、以及“CI/CD 自动执行检查”的表述。
+- 当前仓库未发现任何 `*_test.go` 文件，也未发现 `tests/` 目录内容；因此后续文档和执行应优先遵循 `AGENTS.md` 的现行规则，而不是 `README.md` 中这些过期段落。
+## Operational Scripts
+- `bash scripts/check-service-errors.sh`：检查 Service 层是否违规使用 `fmt.Errorf`。
+- `bash scripts/check-comment-paths.sh`：检查 Handler 注释路径是否残留 `/api/v1`。
+- `bash scripts/check-all.sh`：运行上述两个检查。
+- `make docs` → `go run cmd/gendocs/main.go`，用于生成 `docs/admin-openapi.yaml`，证据见 `Makefile`、`cmd/gendocs/main.go`。
+- `go run scripts/verify_migration/main.go`：这是一个面向数据库迁移结果的人工验证脚本，会直接连接数据库并查询字段，不是自动测试框架，证据见 `scripts/verify_migration/main.go`。
+- `Makefile` 的 `test` 目标仍定义为 `go test -v ./...`，但这反映的是旧工具入口，不代表当前团队允许自动化测试。
+## Module Design
+- 构造函数使用 `NewXxx...`，例如 `NewAccountHandler()`、`NewGenerator()`。
+- Handler、response、errors、constants 都以小包单职责方式导出少量明确入口，证据见 `internal/handler/admin/account.go`、`pkg/response/response.go`、`pkg/errors/errors.go`。
+- 未检测到 JS/TS 式 barrel file；Go 通过包目录与导出符号组织模块。
+## Prescriptive Summary
+- 写新 Handler 时：在 `internal/handler/...` 保持中文注释 + 英文标识符，只解析请求并调用 Service，成功统一走 `pkg/response/response.go`，失败直接返回 `error`。
+- 写新业务错误时：先在 `pkg/errors/codes.go` 注册错误码与中文消息，再用 `errors.New()` / `errors.Wrap()`。
+- 写新常量或 Redis Key 时：放入 `pkg/constants/`，并补中文注释与 Key 生成函数。
+- 写新 API 时：在 `internal/routes/*.go` 用 `Register()` + `RouteSpec` 注册，并同步更新 `cmd/api/docs.go` 与 `cmd/gendocs/main.go` 的文档 Handler 装配。
+- 运行规范检查时：优先使用 `scripts/check-*.sh` 与 `make docs`；不要把 `README.md` 中的测试/覆盖率描述当成当前执行标准。
+<!-- GSD:conventions-end -->
+
+<!-- GSD:architecture-start source:ARCHITECTURE.md -->
+## Architecture
+
+## Pattern Overview
+- HTTP 入口与异步任务入口分离：`cmd/api/main.go` 负责 Fiber API，`cmd/worker/main.go` 负责 Asynq Worker 与轮询调度。
+- 依赖集中在 `internal/bootstrap/` 组装，再分发给 `internal/routes/`、`internal/handler/`、`internal/task/`。
+- 数据访问主要走 `internal/store/postgres/*.go`，模型与 DTO 分别位于 `internal/model/*.go` 与 `internal/model/dto/*.go`。
+- 路由注册统一经过 `internal/routes/registry.go` 的 `Register()`，同时驱动 Fiber 路由与 OpenAPI 元数据。
+- 多租户与权限控制主要依赖认证上下文 + Store 层显式过滤函数，而不是数据库外键或 ORM 关联。
+## Layers
+- Purpose: 进程启动、基础设施初始化、依赖装配、生命周期管理。
+- Location: `cmd/api/main.go`, `cmd/worker/main.go`, `internal/bootstrap/*.go`
+- Contains: 配置加载、日志、数据库、Redis、队列、对象存储、Gateway 客户端、Bootstrap 编排。
+- Depends on: `pkg/config`, `pkg/database`, `pkg/logger`, `pkg/queue`, `pkg/storage`, `internal/bootstrap`
+- Used by: 整个应用进程。
+- Purpose: 路由域划分、认证挂载、HTTP 入参与响应封装、OpenAPI 文档注册。
+- Location: `internal/routes/*.go`, `internal/handler/**/*.go`
+- Contains: `RegisterRoutesWithDoc()` 总入口、Admin/Auth/Personal 域路由、Fiber Handler。
+- Depends on: `internal/bootstrap.Handlers`, `internal/bootstrap.Middlewares`, `pkg/openapi`, `pkg/response`
+- Used by: `cmd/api/main.go`
+- Purpose: 业务规则、权限判断、事务编排、幂等、异步任务提交、跨模块协作。
+- Location: `internal/service/**/*.go`
+- Contains: 账号、订单、套餐、轮询、设备、卡、认证、充值、佣金等服务。
+- Depends on: `internal/store/postgres`, `pkg/errors`, `pkg/middleware`, `pkg/queue`, `pkg/wechat`, `gorm.DB`, `redis.Client`
+- Used by: Handler 层、Worker Bootstrap、Task Handler。
+- Purpose: SQL 查询、分页、显式数据权限过滤、缓存辅助、事务基础能力。
+- Location: `internal/store/store.go`, `internal/store/options.go`, `internal/store/postgres/*.go`
+- Contains: 每个聚合的 PostgreSQL Store，例如 `internal/store/postgres/account_store.go`, `internal/store/postgres/order_store.go`。
+- Depends on: `gorm`, `redis`, `pkg/middleware/data_scope.go`
+- Used by: Service 层、部分 Handler 组装期专用读模型。
+- Purpose: 持久化模型、DTO、常量化状态值、表名映射。
+- Location: `internal/model/*.go`, `internal/model/dto/*.go`
+- Contains: `model.Account`, `model.Order`, `model.Shop`, `model.PollingConfig` 以及请求/响应 DTO。
+- Depends on: GORM tags、标准库类型。
+- Used by: Store、Service、Handler、OpenAPI 生成。
+- Purpose: Asynq 任务处理、轮询调度、定时任务、批处理导入。
+- Location: `internal/task/*.go`, `internal/polling/*.go`, `pkg/queue/*.go`
+- Contains: `pkg/queue/handler.go` 任务注册器、`internal/task/polling_handler.go`、`internal/task/order_expire.go`、`internal/polling/scheduler.go`。
+- Depends on: Worker bootstrap 产出的 stores/services、Redis、Asynq、Gateway。
+- Used by: `cmd/worker/main.go`
+## Data Flow
+- HTTP 侧状态主要放在 PostgreSQL；请求态身份与数据权限范围放在 `context.Context`。
+- 高速状态、Token、轮询队列、并发信号量、下级店铺缓存放在 Redis，如 `pkg/auth/token.go`、`internal/polling/scheduler.go`、`internal/store/postgres/shop_store.go`。
+- 异步处理采用 Redis-backed Asynq 队列，由 `pkg/queue/client.go` 提交、`pkg/queue/server.go` 消费。
+## Key Abstractions
+- Purpose: 启动期依赖编排结果。
+- Examples: `internal/bootstrap/bootstrap.go`, `internal/bootstrap/worker.go`
+- Pattern: 显式依赖注入，不使用外部 DI 框架。
+- Purpose: 路由注册时的装配清单。
+- Examples: `internal/bootstrap/types.go`, `internal/bootstrap/handlers.go`, `internal/bootstrap/middlewares.go`
+- Pattern: 结构体聚合所有已构造的 Handler 与 Middleware。
+- Purpose: 单次声明同时完成真实路由注册和 OpenAPI 元数据注册。
+- Examples: `internal/routes/registry.go`, `internal/routes/account.go`, `internal/routes/personal.go`
+- Pattern: 代码即文档，DTO 驱动文档生成。
+- Purpose: Store 通用分页与排序选项。
+- Examples: `internal/store/options.go`, `internal/service/account/service.go`, `internal/service/order/service.go`
+- Pattern: Service 先构造查询选项，再下传到 Store。
+- Purpose: 承载用户身份与可管理店铺范围，并在 Store 查询时执行过滤。
+- Examples: `pkg/middleware/auth.go`, `pkg/middleware/data_scope.go`, `internal/store/postgres/shop_store.go`
+- Pattern: 中间件预计算 `SubordinateShopIDs`，Store 按字段类型显式调用 `ApplyShopFilter` / `ApplyEnterpriseFilter` / `ApplySellerShopFilter`。
+## Entry Points
+- Location: `cmd/api/main.go`
+- Triggers: `go run cmd/api/main.go`、API 容器启动。
+- Responsibilities: 加载配置、初始化基础设施、执行 `bootstrap.Bootstrap()`、创建 Fiber、注册中间件和路由、生成运行时 OpenAPI 文件 `logs/openapi.yaml`。
+- Location: `cmd/worker/main.go`
+- Triggers: `go run cmd/worker/main.go`、Worker 容器启动。
+- Responsibilities: 初始化 Worker 依赖、执行 `bootstrap.BootstrapWorker()`、启动 Asynq Worker、启动轮询调度器和 Asynq Scheduler、优雅关闭。
+- Location: `cmd/gendocs/main.go`
+- Triggers: 手动执行文档生成。
+- Responsibilities: 通过 `openapi.BuildDocHandlers()` + `routes.RegisterRoutesWithDoc()` 输出 `docs/admin-openapi.yaml`。
+## Routing Strategy
+- `/api/auth`：统一后台/H5 认证，见 `internal/routes/auth.go`
+- `/api/admin`：管理后台业务域，见 `internal/routes/admin.go`
+- `/api/c/v1`：个人客户端域，见 `internal/routes/personal.go`
+- `/api/callback`：支付回调，无认证，见 `internal/routes/order.go` 与 `internal/handler/callback/payment.go`
+- 所有 HTTP 接口使用 `internal/routes/registry.go` 的 `Register()`，文档规范见 `docs/api-documentation-guide.md`。
+- `internal/routes/admin.go` 以 handler 是否为 `nil` 决定是否挂载模块，便于文档生成和裁剪。
+- `internal/routes/personal.go` 明确区分公开路由与认证路由，并依赖注册顺序确保公开接口不被 `Use()` 拦截。
+## Error Handling
+- Handler 层只做参数解析与转发，返回 `pkg/errors` 中的 `AppError`，如 `internal/handler/admin/account.go`。
+- Service 层封装业务错误，不直接向外泄露底层错误文本，如 `internal/service/account/service.go`、`internal/service/order/service.go`。
+- Worker 任务记录结构化日志，并将可重试与不可重试逻辑写在处理器内部，如 `internal/task/order_expire.go`、`internal/task/polling_handler.go`。
+## Cross-Cutting Concerns
+- `pkg/logger/logger.go` 初始化 App/Access 日志；`pkg/logger/middleware.go` 记录完整请求/响应摘要。
+- Fiber `BodyParser` / `QueryParser` + `validator.v10`，示例见 `internal/handler/auth/handler.go`。
+- 后台/H5 使用 Redis Token + `pkg/middleware/auth.go`；个人客户使用单独中间件，由 `internal/bootstrap/middlewares.go` 创建。
+- 路由元数据写在 `RouteSpec`；文档生成器依赖 `cmd/api/docs.go`、`cmd/gendocs/main.go`、`pkg/openapi/handlers.go` 三处手工维护 Handler 清单。
+- 模型显式声明 `TableName()` 与字段列名，如 `internal/model/account.go`, `internal/model/order.go`, `internal/model/shop.go`。
+- 数据库结构通过 `migrations/*.sql` 管理，`pkg/database/postgres.go` 明确禁用自动建表。
+## Architectural Deviations
+- `README.md` 与 `openspec/config.yaml` 多处描述“GORM Callback 自动注入数据权限过滤”，但当前 `internal/bootstrap/bootstrap.go` 第 67 行明确写明“数据权限过滤已移至 Store 层显式调用 ApplyXxxFilter 函数”。当前保留的 GORM Callback 只有 `pkg/gorm/callback.go` 中的创建人/更新人自动填充。
+- `internal/bootstrap/handlers.go` 为客户端场景直接新建多个 Store 和一个 `client_order` Service，而不是完全只消费 `services` 聚合；这说明 Handler 装配阶段存在读模型/适配层级的额外拼装。
+- `internal/task/polling_handler.go` 在首次实名激活流程中先构造 Asynq 任务，但实际通过 Redis List `RPush` 提交，文件内注释明确写出“实际应该通过依赖注入 asynq.Client”；这是 Worker 流程中的特殊机制与待收敛点。
+<!-- GSD:architecture-end -->
+
+<!-- GSD:workflow-start source:GSD defaults -->
+## GSD Workflow Enforcement
+
+Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.
+
+Use these entry points:
+- `/gsd:quick` for small fixes, doc updates, and ad-hoc tasks
+- `/gsd:debug` for investigation and bug fixing
+- `/gsd:execute-phase` for planned phase work
+
+Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.
+<!-- GSD:workflow-end -->
+
+<!-- GSD:profile-start -->
+## Developer Profile
+
+> Profile not yet configured. Run `/gsd:profile-user` to generate your developer profile.
+> This section is managed by `generate-claude-profile` -- do not edit manually.
+<!-- GSD:profile-end -->