csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
d2e08dbbec6661dc3eea77d62ffb4f8d52be7934
junhong_cmp_fiber/.planning/PROJECT.md

12 KiB
Raw Blame History

君鸿卡管系统

What This Is

物联网卡（IoT SIM）+ 号卡 + 设备全生命周期管理平台，支持多级代理商体系和分佣结算。平台以 B 端代理商为核心分销渠道，兼顾 C 端个人客户和企业客户，覆盖从卡/设备采购、分配、激活、套餐购买到佣金结算的完整业务链路。当前处于 MVP 阶段，核心功能模块已完成，目标是修复所有已知业务链路断点、补全缺失功能，将系统调整至可生产上线状态。

Core Value

业务链路完整可用——代理能采购分配卡/设备，C端客户能充值购包激活套餐，佣金能正确计算并可提现。这条主链路必须端到端跑通。

Requirements

Validated

以下功能已在代码库中实现，视为已验证的基础能力：

Validated in Phase 03.1: 设备 sync-info 读取链路修复

  • ✓ 设备管理列表/详情返回 online_status/last_online_time/software_version/switch_mode/last_gateway_sync_at — DEVICE-02/03
  • ✓ 设备绑卡列表（ListBindings）返回 is_current 字段 — DEVICE-03
  • ✓ 资产 Resolve/Refresh BoundCardInfo 包含 is_current（isCurrentMap 模式） — DEVICE-03
  • ✓ admin 资产解析接口（AssetResolveResponse）返回 5 个 DB 缓存字段 — DEVICE-02/03
  • ✓ GetRealtimeStatus device 类型实时调用 Gateway sync-info，返回 DeviceGatewayInfo — DEVICE-04
  • ✓ C 端 GetAssetInfo device_realtime 从真实 Gateway 数据填充（删除 buildMockDeviceRealtime）— DEVICE-04
  • ✓ Gateway 失败降级：IMEI 为空不发起调用，失败只记 Warn，device_realtime 返回 null — DEVICE-04

Validated in Phase 2: PERM/FIN/REALNAME/POLL 修复

  • ✓ 企业账号 Resolve 接口移除错误拦截，Refresh 接口新增拦截（只读）— PERM-01/02
  • ✓ 提现审批人字段补全（approved_by/approved_at）— FIN-01
  • ✓ 提现拒绝 remark 必填校验（Reject 补 Validate 调用）— FIN-02
  • ✓ 激活配置并发行锁保护（clause.Locking FOR UPDATE）— FIN-03
  • ✓ enable_realname_activation → expiry_base 全链路重构，三维激活决策（卡类型+购买路径+expiry_base）— REALNAME-01~05
  • ✓ polling:protect 接入调度器（processManualQueue + processTimedQueue）— POLL-01
  • ✓ gatewayClient=nil 时停复机返回业务错误而非 nil — POLL-02
  • ✓ GetPackages 接口支持分页（page/pageSize/total）— POLL-03
  • ✓ PackageSeries 删除前检查关联套餐（CountBySeriesID）— POLL-04

Validated in Phase 1: P0 紧急修复

  • ✓ 实名状态常量统一（DB 写入值统一为 constants.RealNameStatusVerified=1）— CRITICAL-01

  • ✓ C 端实名校验修复（依赖常量统一）— CRITICAL-02

  • ✓ 实名激活任务断链修复（PollingHandler 注入 asynqClient，RPush 降级方案删除）— CRITICAL-03

  • ✓ 充值回调触发自动购包（TaskTypeAutoPurchaseAfterRecharge 入队）— CRITICAL-04

  • ✓ 自动购包后佣金链补全（TaskTypeCommission 正确触发）— CRITICAL-05

  • ✓ 代购订单 sellerCostPrice 修正（场景5使用 operatorCostPrice，6处全部审查）— CRITICAL-06

  • ✓ 设备导入补充 IMEI 字段（DeviceRow.IMEI + buildDeviceColumnIndex 多别名）— CRITICAL-07

  • ✓ 提现冻结并发校验（RowsAffected==0 检查，防止重复提现单）— CRITICAL-08

  • ✓ IoT 卡全生命周期管理（开卡/激活/停复机/销户）— 已实现

  • ✓ 设备管理（绑卡/解绑/批量导入 Excel）— 已实现

  • ✓ 代理商多级体系（最多 7 层层级，parent_id 维护）— 已实现

  • ✓ RBAC 权限系统（角色/权限/菜单，基于店铺层级数据过滤）— 已实现

  • ✓ B 端认证（Admin JWT + Redis Token，SuperAdmin/Platform/Agent/Enterprise）— 已实现

  • ✓ C 端认证（微信 OAuth + 手机号绑定，JWT 单独中间件）— 已实现

  • ✓ 套餐系统（主套餐/加油包/排队激活/囤货待实名激活/流量计费）— 已实现

  • ✓ 订单系统（五种购买场景，钱包/微信/富友支付）— 已实现

  • ✓ 微信支付（JSAPI + H5，PowerWeChat v3 SDK）— 已实现

  • ✓ 资产钱包（绑定卡/设备，转手后钱包跟着走）— 已实现

  • ✓ 代理佣金钱包（差价佣金 + 一次性佣金，多级分链）— 已实现

  • ✓ 代理佣金提现申请流程（申请/审批/拒绝）— 已实现（待修复）

  • ✓ 轮询系统（实名状态/流量/套餐余额，Asynq + Redis Sorted Set）— 已实现

  • ✓ 标签系统（平台/企业/店铺三级隔离）— 已实现

  • ✓ 对象存储（联通云 OSS，S3 兼容，批量导入/导出）— 已实现

  • ✓ 审计日志（账号操作：create/update/delete/assign_roles）— 已实现

  • ✓ 企业账号管理（B 端大客户，被分配卡/设备，无钱包）— 已实现（待修复权限）

  • ✓ 订单超时自动取消（Asynq Scheduler，30 分钟）— 已实现

  • ✓ 富友支付 SDK（pkg/fuiou/ 完整实现 + 回调已实现）— SDK 已实现，接口留桩待补全

Active

当前阶段需要完成的工作，来自修正业务完整方案（.sisyphus/plans/修正业务-完整方案.md）：

方案 A — 紧急 Bug 修复（P0） ✅ Validated in Phase 1

  • A-1：实名状态常量统一（DB 写入值 2 vs 常量 1，所有链路断裂）
  • A-2：C 端实名校验修复（依赖 A-1）
  • A-3：实名激活任务断链修复（PollingHandler 缺少 asynqClient，RPush 降级）
  • A-4：充值回调后自动购包触发 + 佣金补全（两个断点：无调用 + 佣金不计算）
  • A-5：代购订单金额修正（场景 5 sellerCostPrice 用错字段，佣金链归零）
  • A-6：设备导入补充 IMEI 字段（DeviceRow 缺 IMEI，导入后 Gateway 无法调用）
  • A-7：提现冻结并发校验（只检查 Error 不检查 RowsAffected，并发创建重复提现单）

方案 B — 企业端权限完善 ✅ Validated in Phase 2

  • B-1：Resolve 接口错误拦截企业账号（应可查，需移除拦截）
  • B-2：Refresh 接口缺少企业账号拦截（应只读）

方案 C — 提现/佣金流程完善 ✅ Validated in Phase 2

  • C-1：审批人字段补全（approved_by/approved_at 永远为空）
  • C-2：提现拒绝 remark 必填校验（Reject 缺少 Validate 调用）
  • C-3：激活配置并发保护（两步 UPDATE 无锁，可出现两条 active=true）

方案 D — 设备体系完善 ✅ Validated in Phase 3 + Phase 03.1

  • D-0：设备模型字段扩展（online_status / last_online_time / software_version 等）
  • D-1：Gateway sync-info 同步接口对接（CurrentIccid 预留结构待填充）
  • D-2：device_sim_binding 新增 is_current 字段（当前使用卡标识）
  • D-3：设备 Refresh + 详情接入 sync-info（在线状态/固件版本/当前卡实时更新）
  • D-读取侧：DTO 字段映射补全（5个DB缓存字段 + 2处IsCurrent）+ GetRealtimeStatus Gateway 实时调用 + C端 mock 替换

方案 E — 流量体系改革（破坏性，低峰期）

  • E-1：流量详单改为日粒度缓冲（新建 tb_card_daily_usage，Redis 增量缓存）
  • E-2：current_month_usage_mb 改增量累加（不再被上游自然月归零覆盖）
  • E-3：流量查询层适配（兼容 Redis 今日 + DB 历史两段数据）

方案 F — 代码质量清理

  • F-1：佣金链断裂改为零额待审记录（status=99，不再静默跳过）
  • F-2：废弃 sim:status:sync 任务代码删除
  • F-3：错误不应被吞（cards, _ := 改为记日志）
  • F-4：C 端 Handler 迁移到 Service 层（直接 DB 访问改回分层）
  • F-5：Handler/Service 权限不一致修复
  • F-6：StopResumeCallback / ResumeCallback 注入（bootstrap 未调用）

方案 G — 实名激活架构重构 ✅ Validated in Phase 2

  • G：enable_realname_activation 字段拆分为 expiry_base（from_activation/from_purchase）

方案 H — 轮询系统小修 ✅ Validated in Phase 2

  • H-1：polling:protect 接入调度（已注册未调度）
  • H-2：gatewayClient=nil 时停复机应返回错误（而非假装成功）
  • H-3：packages 接口加分页
  • H-4：Series 删除前检查关联套餐

方案 I — 退款完整功能（新功能）

  • I-1：新建 tb_refund_request 数据模型
  • I-2：7 个退款接口（申请/列表/详情/审批/拒绝/退回/重提）
  • I-3：审批通过后按比例扣减代理佣金钱包

方案 J — 其他修复

  • J-1：富友支付 JSAPI + 小程序接口实现（替换留桩）
  • J-2：平台代理钱包代购支持（platform buyerType 绕过代理检查）
  • J-3：status 3/4 业务触发逻辑（激活→3，最后套餐到期→4）
  • J-4：payment_status 枚举统一（删除 C 端映射函数，与管理端统一）

Out of Scope

  • SaaS 多租户架构 — 当前阶段不影响，v2+ 规划
  • 自动化测试（unit/integration/e2e） — 项目明确不做，人工验收
  • 设备定期轮询（P1-9） — 确认为伪需求，改为按需实时拉取
  • P1-2 企业认证中间件 — 企业账号复用 AdminAuth，不需要新中间件
  • P1-3 提现"已到账"接口 — 线下打款，系统无法感知
  • P2-6 告警通知渠道 — 无关紧要，暂不做
  • P2-9 asset_type 校验 — Service 层已有兜底，非问题
  • P2-24 Carrier→Series 绑定 — 系列可跨运营商，不需要强绑定
  • P2-30 轮询配置通用化 — 设备轮询取消后此问题不存在

Context

  • 技术栈：Go + Fiber v2 + GORM + Asynq + PostgreSQL + Redis + sonic JSON + Viper + Zap
  • 架构分层：Handler → Service → Store → Model，双进程（API + Worker），依赖集中在 bootstrap 装配
  • 路由注册：统一经过 internal/routes/registry.go 的 Register()，同时驱动 OpenAPI 文档
  • 数据权限：Store 层显式调用 ApplyShopFilter / ApplyEnterpriseFilter，不依赖 GORM Callback（README 描述已过时）
  • 支付体系：微信（PowerWeChat v3 JSAPI/H5）+ 富友（自研 SDK，SDK 完整但主调接口留桩）+ 钱包余额
  • 修复文档：完整规格书位于 .sisyphus/plans/修正业务-完整方案.md，包含每个 Bug 的文件路径和修改代码片段
  • 代码库地图：.planning/codebase/ 包含 ARCHITECTURE.md / STACK.md / STRUCTURE.md 等

Constraints

  • Tech Stack: 严格使用 Fiber v2 + GORM + Asynq + PostgreSQL + Redis，不引入替代框架
  • No Tests: 项目不写自动化测试，人工验收（rg + go build + DBHub + 日志）
  • Language: 所有注释/日志/错误消息/文档使用中文，变量/函数名使用英文
  • No Foreign Keys: 禁止数据库外键约束，关联通过 ID 字段在代码层维护
  • 方案 E 风险: 流量体系改革涉及 DB 迁移 + Redis 架构，必须低峰期发布，单独规划

Key Decisions

Decision Rationale Outcome
不新建企业认证中间件 企业账号 user_type=4 已可复用 AdminAuth JWT — Pending
SaaS 方向不影响当前阶段 先把 MVP 跑通上线，SaaS 是 v2+ 的事 — Pending
修正业务文档为完整范围 文档覆盖所有已知断点和缺失功能，无额外遗漏 — Pending
设备体系不做定期轮询 按需实时拉取（sync-info）取代定期后台轮询 — Pending
流量体系改革独立发布 破坏性变更（DB 迁移 + Redis 架构），风险隔离 — Pending

Last updated: 2026-03-28 after Phase 03.1 (sync-info-phase-3-dto) completion — device reading-side gap fully closed

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition (via /gsd-transition):

  1. Requirements invalidated? → Move to Out of Scope with reason
  2. Requirements validated? → Move to Validated with phase reference
  3. New requirements emerged? → Add to Active
  4. Decisions to log? → Add to Key Decisions
  5. "What This Is" still accurate? → Update if drifted

After each milestone (via /gsd-complete-milestone):

  1. Full review of all sections
  2. Core Value check — still the right priority?
  3. Audit Out of Scope — reasons still valid?
  4. Update Context with current state
Reference in New Issue View Git Blame Copy Permalink