# ROADMAP — 君鸿卡管系统 v1.0

**Project:** 君鸿卡管系统  
**Milestone:** v1.0 — MVP 上线准备  
**Created:** 2026-03-27  
**Granularity:** Standard (6 phases)  
**Coverage:** 46/46 requirements mapped ✓  

---

## Phases

- [x] **Phase 1: P0 紧急修复** — 修复所有阻塞主链路的 P0 Bug，使充值→购包→佣金→实名激活全链路可跑通 (completed 2026-03-27)
- [x] **Phase 2: 权限/财务/实名/轮询修复** — 补全企业权限、提现财务流程、实名激活架构重构、轮询系统小修 (completed 2026-03-28)
- [x] **Phase 3: 设备体系完善** — 扩展设备模型字段、对接 Gateway sync-info、完善绑卡标识 (completed 2026-03-28)
- [ ] **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**: 5 plans

Plans:
- [x] 01-01-PLAN.md — CRITICAL-01/02：实名状态常量统一 + C 端实名校验修复（Wave 1）
- [x] 01-02-PLAN.md — CRITICAL-03：实名激活任务断链（PollingHandler 注入 asynqClient）（Wave 2）
- [x] 01-03-PLAN.md — CRITICAL-04/05：充值回调触发自动购包 + 佣金链补全（Wave 2，parallel）
- [x] 01-04-PLAN.md — CRITICAL-06：代购订单 sellerCostPrice 6 处语义审查修正（Wave 1，parallel）
- [x] 01-05-PLAN.md — CRITICAL-07/08：设备导入 IMEI + 提现冻结并发校验（Wave 1，parallel）

---

### 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**: 2 plans

Plans:
- [x] 02-01-PLAN.md — PERM-01/02 + FIN-01/02/03 + POLL-01/02/03/04：权限/财务/轮询小修合并（Wave 1）
- [x] 02-02-PLAN.md — REALNAME-01~05：实名激活架构重构，原子执行（Wave 1，parallel）

---

### 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**: 2 plans

Plans:
- [x] 03-01-PLAN.md — DEVICE-01/02/03：DB 迁移 + 模型扩展 + Gateway SyncDeviceInfo + DTO 字段（Wave 1）
- [x] 03-02-PLAN.md — DEVICE-04：Asset Service 接入 sync-info，Refresh 追加设备状态同步（Wave 2）

---

### Phase 03.1: 设备 sync-info 读取链路修复：补全 Phase 3 新增字段在查询接口的 DTO 映射缺口 (INSERTED)

**Goal:** 补全 Phase 3 完成的设备数据写入链路在读取侧的缺口：修复 DTO 字段映射遗漏（5个 DB 缓存字段 + 2处 IsCurrent）+ 建立设备实时状态的 Gateway 查询链路（替换 mock → 真实 Gateway 数据）
**Requirements**: DEVICE-02, DEVICE-03, DEVICE-04
**Depends on:** Phase 3
**Plans:** 1/1 plans complete

Plans:
- [ ] 03.1-01-PLAN.md — 补全静态 DTO 映射缺口 + 建立 GetRealtimeStatus Gateway 实时调用 + C 端 stub 替换（Wave 1）

### 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 紧急修复 | 5/5 | Complete   | 2026-03-27 |
| 2. 权限/财务/实名/轮询修复 | 2/2 | Complete    | 2026-03-28 |
| 3. 设备体系完善 | 2/2 | Complete   | 2026-03-28 |
| 4. 退款 + 支付 + 运营修复 | 0/TBD | Not started | - |
| 5. 代码质量清理 | 0/TBD | Not started | - |
| 6. 流量体系改革（低峰期）| 0/TBD | 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*