docs: initialize project

.planning/PROJECT.md

@@ -0,0 +1,156 @@
+# 君鸿卡管系统
+
+## What This Is
+
+物联网卡（IoT SIM）+ 号卡 + 设备全生命周期管理平台，支持多级代理商体系和分佣结算。平台以 B 端代理商为核心分销渠道，兼顾 C 端个人客户和企业客户，覆盖从卡/设备采购、分配、激活、套餐购买到佣金结算的完整业务链路。当前处于 MVP 阶段，核心功能模块已完成，目标是修复所有已知业务链路断点、补全缺失功能，将系统调整至可生产上线状态。
+
+## Core Value
+
+**业务链路完整可用**——代理能采购分配卡/设备，C端客户能充值购包激活套餐，佣金能正确计算并可提现。这条主链路必须端到端跑通。
+
+## Requirements
+
+### Validated
+
+*以下功能已在代码库中实现，视为已验证的基础能力：*
+
+- ✓ 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）**
+- [ ] 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 — 企业端权限完善**
+- [ ] B-1：Resolve 接口错误拦截企业账号（应可查，需移除拦截）
+- [ ] B-2：Refresh 接口缺少企业账号拦截（应只读）
+
+**方案 C — 提现/佣金流程完善**
+- [ ] C-1：审批人字段补全（approved_by/approved_at 永远为空）
+- [ ] C-2：提现拒绝 remark 必填校验（Reject 缺少 Validate 调用）
+- [ ] C-3：激活配置并发保护（两步 UPDATE 无锁，可出现两条 active=true）
+
+**方案 D — 设备体系完善**
+- [ ] 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（在线状态/固件版本/当前卡实时更新）
+
+**方案 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 — 实名激活架构重构**
+- [ ] G：enable_realname_activation 字段拆分为 expiry_base（from_activation/from_purchase）
+
+**方案 H — 轮询系统小修**
+- [ ] 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-27 after initialization*
+
+## 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