junhong_cmp_fiber/.planning/ROADMAP.md

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，使充值→购包→佣金→实名激活全链路可跑通 (completed 2026-03-27)
• Phase 2: 权限/财务/实名/轮询修复 — 补全企业权限、提现财务流程、实名激活架构重构、轮询系统小修 (completed 2026-03-28)
• 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:

• 01-01-PLAN.md — CRITICAL-01/02：实名状态常量统一 + C 端实名校验修复（Wave 1）
• 01-02-PLAN.md — CRITICAL-03：实名激活任务断链（PollingHandler 注入 asynqClient）（Wave 2）
• 01-03-PLAN.md — CRITICAL-04/05：充值回调触发自动购包 + 佣金链补全（Wave 2，parallel）
• 01-04-PLAN.md — CRITICAL-06：代购订单 sellerCostPrice 6 处语义审查修正（Wave 1，parallel）
• 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:

• 02-01-PLAN.md — PERM-01/02 + FIN-01/02/03 + POLL-01/02/03/04：权限/财务/轮询小修合并（Wave 1）
• 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:

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

---

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