From 7f2e978288a6863aae958c90e1f4d014ddca7cfb Mon Sep 17 00:00:00 2001 From: huang Date: Fri, 27 Mar 2026 19:07:58 +0800 Subject: [PATCH] docs: define v1 requirements --- .planning/REQUIREMENTS.md | 123 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 .planning/REQUIREMENTS.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..529d0cc --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,123 @@ +# Requirements + +**Project:** 君鸿卡管系统 +**Milestone:** v1.0 — MVP 上线准备 +**Date:** 2026-03-27 + +--- + +## v1 Requirements + +### CRITICAL — P0 紧急 Bug 修复（方案 A） + +- [ ] **CRITICAL-01**: 实名状态常量统一 — `parseRealnameStatus` 写入值 2 改为常量 1，Model 注释统一，全链路使用 `constants.RealNameStatusVerified` +- [ ] **CRITICAL-02**: C 端实名校验修复 — `client_order/service.go` 实名判断改用 `constants.RealNameStatusVerified`（依赖 CRITICAL-01） +- [ ] **CRITICAL-03**: 实名激活任务断链修复 — `PollingHandler` 注入 `asynq.Client`，删除 RPush 降级方案，改用 `asynq.Client.EnqueueContext()` +- [ ] **CRITICAL-04**: 充值回调后自动购包触发 — `recharge/service.go` 在 HandlePaymentCallback 成功后入队 `TaskTypeAutoPurchaseAfterRecharge`；注册 `AutoPurchaseHandler` +- [ ] **CRITICAL-05**: 自动购包佣金链补全 — `AutoPurchaseHandler.ProcessTask()` 事务提交成功后入队 `TaskTypeCommission` +- [ ] **CRITICAL-06**: 代购订单金额修正 — 场景 5（代理代购下级）`sellerCostPrice` 全部 6 处逐一审查，确保使用 `operatorCostPrice`（非 `buyerCostPrice`） +- [ ] **CRITICAL-07**: 设备导入补充 IMEI 字段 — `DeviceRow` 新增 IMEI，`ParseDeviceExcel` 列名映射新增 IMEI，`device_import.go` 导入时填充 +- [ ] **CRITICAL-08**: 提现冻结并发校验 — `my_commission/service.go` 冻结余额后检查 `RowsAffected == 0`，余额不足并发场景返回错误而非静默继续 + +### PERM — 企业端权限完善（方案 B） + +- [ ] **PERM-01**: 移除 Resolve 接口对企业账号的错误拦截 — 企业账号应能查询被授权的资产 +- [ ] **PERM-02**: Refresh 接口新增企业账号拦截 — 企业只读，不允许主动触发运营商刷新 + +### FIN — 财务/提现流程完善（方案 C） + +- [ ] **FIN-01**: 提现审批人字段补全 — `Approve()` 写入 `approved_by` / `approved_at`（当前永远为空） +- [ ] **FIN-02**: 提现拒绝 remark 必填校验 — `Reject()` 在 BodyParser 后补充 `validator.Validate()` +- [ ] **FIN-03**: 激活配置并发保护 — 提现配置和微信配置激活时，两步 UPDATE 前加 `FOR UPDATE` 行锁 + +### REALNAME — 实名激活架构重构（方案 G） + +- [ ] **REALNAME-01**: 移除 `tb_package.enable_realname_activation` 字段，新增 `expiry_base VARCHAR(30)` 字段（`from_activation` / `from_purchase`） +- [ ] **REALNAME-02**: `activateMainPackage` 改写激活决策逻辑 — 按卡类型（industry/normal）+ 购买路径（C端/后台囤货）+ `expiry_base` 三维决策 +- [ ] **REALNAME-03**: `client_order/service.go` 实名检查改为按卡类型判断（`card_category == "normal"`），删除 `packagesNeedRealname()` 函数 +- [ ] **REALNAME-04**: `ActivateByRealname()` 按 `ExpiryBase` 选择激活时间基准（`from_purchase` 用 CreatedAt，`from_activation` 用当前时刻） +- [ ] **REALNAME-05**: 套餐管理 API DTO 更新 — 移除 `enable_realname_activation`，新增 `expiry_base` 枚举字段 + +### POLL — 轮询系统小修（方案 H） + +- [ ] **POLL-01**: `polling:protect` 接入调度 — `scheduler.go` 补充 processManualQueue + processTimedQueue 对 protect 任务的调度 +- [ ] **POLL-02**: gatewayClient=nil 时停复机返回错误 — `stopCardWithRetry` 和 `resumeCardWithRetry` 两处改为返回业务错误而非 nil +- [ ] **POLL-03**: packages 接口新增分页 — `GetPackages()` 默认 page=1, pageSize=50，最大 100 +- [ ] **POLL-04**: Series 删除前检查关联套餐 — `package_series/service.go:Delete()` 前置 `CountBySeriesID()` 检查 + +### DEVICE — 设备体系完善（方案 D） + +- [ ] **DEVICE-01**: 设备模型字段扩展 — DB 迁移新增 `online_status / last_online_time / software_version / switch_mode / last_gateway_sync_at` +- [ ] **DEVICE-02**: Gateway sync-info 同步接口对接 — `internal/gateway/device.go` 新增 `SyncDeviceInfo()` 方法 +- [ ] **DEVICE-03**: `tb_device_sim_binding` 新增 `is_current` 字段 — DB 迁移 + Model + 更新逻辑 +- [ ] **DEVICE-04**: 设备 Refresh + 详情接入 sync-info — `RefreshDevice()` 在刷新卡数据后调用 `SyncDeviceInfo()`，更新设备在线状态/固件版本/当前卡标识 + +### REFUND — 退款完整功能（方案 I） + +- [ ] **REFUND-01**: 新建 `tb_refund_request` 数据模型 — DB 迁移 + GORM Model +- [ ] **REFUND-02**: 退款接口实现 — Handler + Service + Store + 路由注册（Create / List / Get / Approve / Reject / Return / Resubmit 共 7 个接口） +- [ ] **REFUND-03**: 审批通过后按比例扣减代理佣金钱包 — 使用整数算术（`amount * approvedRefund / actualReceived`），禁用 float64，写负向交易流水 + +### PAY — 支付功能补全（方案 J-1 + J-2） + +- [ ] **PAY-01**: 富友支付 JSAPI 接口实现 — 替换留桩，实现预下单 + 返回前端调起支付参数 +- [ ] **PAY-02**: 富友支付小程序接口实现 — 与 JSAPI 相同逻辑，tradeType 改为 `LETPAY` +- [ ] **PAY-03**: 新增 `FuiouPayJSAPIResponse` DTO，字段与微信官方 `wx.requestPayment()` 参数对齐 +- [ ] **PAY-04**: 平台代理钱包代购 — `CreateLegacy` 支持 `buyerType="" && resourceShopID != nil` 场景，使用资产所属代理的成本价和钱包 + +### OPS — 运营逻辑修复（方案 J-3 + J-4） + +- [ ] **OPS-01**: IoT 卡/设备 status 字段 3/4 业务触发 — 套餐激活成功后更新为 3，最后一个 active 套餐到期后更新为 4 +- [ ] **OPS-02**: payment_status 枚举统一 — 删除 C 端 `orderStatusToClientStatus()` 映射函数，C 端直接输出与管理端一致的 1/2/3/4 枚举 + +### CLEAN — 代码质量清理（方案 F） + +- [ ] **CLEAN-01**: 佣金链断裂改为零额待审记录 — 新增 `CommissionStatusPendingReview = 99`，断链时创建 amount=0 的待审记录，不再静默 break +- [ ] **CLEAN-02**: 废弃 sim:status:sync 任务代码删除 — 移除注册行 + 常量 + `internal/task/sim.go` + `internal/service/sync/service.go` +- [ ] **CLEAN-03**: 错误不应被吞 — `asset/service.go` 中 `cards, _ :=` 改为记录 Warn 日志 +- [ ] **CLEAN-04**: C 端 Handler 迁移到 Service 层 — `handler/app/client_order.go` 订单查询改为调用 `client_order/service.go`，删除直接 DB 访问 +- [ ] **CLEAN-05**: Handler/Service 权限不一致修复 — `handler/admin/order.go` 创建订单时补充钱包支付仅允许代理账号的前置校验 +- [ ] **CLEAN-06**: StopResumeCallback / ResumeCallback 注入 — `internal/bootstrap/services.go` 中初始化后调用 `SetStopResumeCallback` 和 `SetResumeCallback` + +### TRAFFIC — 流量体系改革（方案 E，破坏性变更） + +- [ ] **TRAFFIC-01**: 新建 `tb_card_daily_usage` 日粒度流量表 — DB 迁移 + 唯一约束 `(iot_card_id, date)` +- [ ] **TRAFFIC-02**: 轮询流量写入改为 Redis 增量缓存 — `insertDataUsageRecord()` 仅在有增量时写 `RedisCardDailyTrafficKey` +- [ ] **TRAFFIC-03**: 每日落盘定时任务 — Asynq Scheduler 凌晨 2 点 SCAN Redis Key → UPSERT `tb_card_daily_usage` → 删 Key +- [ ] **TRAFFIC-04**: 流量增量累加 — `calculateFlowUpdates()` 改为 `current_month_usage_mb += increment`，检测运营商重置日，新增 `tb_carrier.data_reset_day` 和 `tb_iot_card.last_gateway_reading_mb` +- [ ] **TRAFFIC-05**: 流量查询层适配 — 新建 `TrafficQueryService.GetDailyUsage()` 兼容"今日 Redis + 历史 DB"两段数据 + +--- + +## v2 Requirements（延后） + +- 卡/资产批量操作（停/复/注销）— 运营场景必须，当前仅有单卡接口 +- 卡/订单批量导出（Excel/CSV）— 财务对账标配，已有导入缺导出 +- 套餐到期前微信模板消息提醒 — 用户体验，竞品标配 +- 代理商完整资金流水账单（按时间倒序，标注来源类型） +- 下级代理业绩报表（订单数/金额/活跃卡数） +- 卡状态变更历史记录（溯源谁什么时候停了哪张卡） +- SaaS 多租户架构 — v2+ 规划 + +--- + +## Out of Scope + +- 自动化测试（unit/integration/e2e）— 项目明确不做 +- 设备定期轮询（P1-9）— 伪需求，改为按需实时拉取 +- P1-2 企业认证中间件 — 复用 AdminAuth，无需新中间件 +- P1-3 提现"已到账"确认接口 — 线下打款，系统无法感知 +- P2-6 告警通知渠道 — 优先级低，暂不做 +- P2-9 asset_type 校验 — Service 层已有兜底 +- P2-24 Carrier→Series 强绑定 — 系列可跨运营商 +- P2-30 轮询配置通用化 — 设备轮询取消后此问题不存在 + +--- + +## Traceability + +*（由 roadmapper 在创建 ROADMAP.md 时填充）* + +| REQ-ID | Phase | +|--------|-------| +| — | — |