# 君鸿卡管系统

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

**方案 B — 企业端权限完善** ✅ *Validated in Phase 2*
- [x] B-1：Resolve 接口错误拦截企业账号（应可查，需移除拦截）
- [x] B-2：Refresh 接口缺少企业账号拦截（应只读）

**方案 C — 提现/佣金流程完善** ✅ *Validated in Phase 2*
- [x] C-1：审批人字段补全（approved_by/approved_at 永远为空）
- [x] C-2：提现拒绝 remark 必填校验（Reject 缺少 Validate 调用）
- [x] C-3：激活配置并发保护（两步 UPDATE 无锁，可出现两条 active=true）

**方案 D — 设备体系完善** ✅ *Validated in Phase 3 + Phase 03.1*
- [x] D-0：设备模型字段扩展（online_status / last_online_time / software_version 等）
- [x] D-1：Gateway sync-info 同步接口对接（CurrentIccid 预留结构待填充）
- [x] D-2：device_sim_binding 新增 is_current 字段（当前使用卡标识）
- [x] D-3：设备 Refresh + 详情接入 sync-info（在线状态/固件版本/当前卡实时更新）
- [x] 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*
- [x] G：enable_realname_activation 字段拆分为 expiry_base（from_activation/from_purchase）

**方案 H — 轮询系统小修** ✅ *Validated in Phase 2*
- [x] H-1：polling:protect 接入调度（已注册未调度）
- [x] H-2：gatewayClient=nil 时停复机应返回错误（而非假装成功）
- [x] H-3：packages 接口加分页
- [x] 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