huang
129a38f942
- 新增 03-02-SUMMARY.md，记录 updateDeviceFromSyncInfo 实现细节 - STATE.md：Phase 3 完成标记，追加 DEVICE-04 决策，Next Action 更新为 Phase 4 - ROADMAP.md：Phase 3 进度更新为 Complete（2/2 plans） - REQUIREMENTS.md：DEVICE-04 标记完成
159 lines
9.7 KiB
Markdown
159 lines
9.7 KiB
Markdown
# 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 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*
|