docs: create roadmap (6 phases)

2026-03-27 20:18:06 +08:00
parent 7f2e978288
commit dc9bf0c9b7
4 changed files with 611 additions and 4 deletions
--- 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 |
--- a/.planning/ROADMAP.md
+++ 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*
--- a/.planning/STATE.md
+++ 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*