diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 529d0cc..cb15e1c 100644 --- a/.planning/REQUIREMENTS.md +++ b/.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 | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..e3260f5 --- /dev/null +++ b/.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* diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..840ed69 --- /dev/null +++ b/.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* diff --git a/CLAUDE.md b/CLAUDE.md index 8769946..a52bb78 100644 --- a/CLAUDE.md +++ b/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. + + +## 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 架构，必须低峰期发布，单独规划 + + + +## 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` + + + +## 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` 中的测试/覆盖率描述当成当前执行标准。 + + + +## 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 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. + + + +## 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. +