归档

.sisyphus/notepads/realname-trigger-priority-enhancement/decisions.md

@@ -0,0 +1,27 @@
+# 架构决策记录
+
+## goroutine context 设计（已确认）
+- 必须使用 `context.WithTimeout(context.Background(), 3*time.Second)` 创建独立 context
+- 禁止复用 `c.UserContext()`（Fiber 请求 context 在 handler 返回后立即失效）
+- goroutine 只接受标量参数（uint、string），不捕获 *fiber.Ctx 或任何指针
+
+## 系统用户身份（已确认）
+- 使用 `UserTypePlatform` 而非 `UserTypeSuperAdmin`
+- Platform 用户仍受 500次/天日限制约束
+- SuperAdmin 不受日限制约束（不符合要求）
+
+## 配置结构体命名（已确认）
+- 新增 `PollingAutoTriggerConfig` 结构体
+- Config 中字段名：`PollingAutoTrigger PollingAutoTriggerConfig`
+- YAML key: `polling_auto_trigger`
+- 环境变量前缀：`JUNHONG_POLLING_AUTO_TRIGGER_`
+
+## 配置验证（已确认）
+- 不在 Validate() 中添加校验
+- 零值（false/0）是合法默认值
+
+## 原子提交策略（已确认）
+- Commit 1: config 文件
+- Commit 2: service bug fix + redis 注释
+- Commit 3: handler 集成（此时全量 build 暂时报错）
+- Commit 4: DI 接线（修复全量 build）

.sisyphus/notepads/realname-trigger-priority-enhancement/issues.md

@@ -0,0 +1,22 @@
+# 已知问题和注意事项
+
+## assetService.ResolvedAsset 类型名已确认（重要修正）
+- 计划中写的 `assetService.ResolvedAsset` 是错误的
+- 实际类型：`*dto.AssetResolveResponse`（在 `internal/model/dto/asset_dto.go` 定义）
+- `h.assetService.Resolve()` 返回 `(*dto.AssetResolveResponse, error)`
+- 字段：`.AssetType` (string), `.AssetID` (uint), `.VirtualNo` (string)
+- `resolveTargetCard` 函数签名应为：
+  `func (h *ClientRealnameHandler) resolveTargetCard(c *fiber.Ctx, asset *dto.AssetResolveResponse, iccid string) (*model.IotCard, error)`
+
+## import 别名冲突
+- client_realname.go 已导入 `internal/middleware` (for GetCustomerID)
+- 需要额外导入 `pkg/middleware` (for SetUserContext) 时需使用别名
+- 建议: `pkgMiddleware "github.com/break/junhong_cmp_fiber/pkg/middleware"`
+
+## processBatchTrigger 中也有 TTL Bug
+- 不仅 TriggerSingle (行72)，processBatchTrigger (行192) 也有相同 Bug
+- 两处都需修复，不能漏
+
+## 功能开关检查逻辑
+- `config.Get().PollingAutoTrigger.EnableAutoTrigger` 为 false 时跳过 goroutine 启动
+- 零值（false/0）是合法默认值，不需要在 Validate() 中校验

.sisyphus/notepads/realname-trigger-priority-enhancement/learnings.md

@@ -0,0 +1,37 @@
+# 项目约定和模式
+
+## 模块路径
+- 项目模块路径：`github.com/break/junhong_cmp_fiber`
+
+## 关键包路径（区分 pkg vs internal）
+- `pkg/middleware` - 包含 `SetUserContext`, `UserContextInfo`, `GetUserTypeFromContext`
+- `internal/middleware` - 包含 `GetCustomerID(c *fiber.Ctx)` (C端个人客户认证)
+- `internal/service/polling` - ManualTriggerService 所在包
+- `pkg/constants` - UserTypePlatform, TaskTypePollingRealname 等常量
+
+## 重要发现
+- `SetUserContext` 在 `pkg/middleware` 包，不在 `internal/middleware`
+- `UserContextInfo` 字段：UserID(uint), UserType(int), ShopID(uint), EnterpriseID(uint), CustomerID(uint)
+- `GetCustomerID(c *fiber.Ctx)` 在 `internal/middleware/personal_auth.go`，返回 (uint, bool)
+- manual_trigger_service.go 当前 469 行，进行重构
+
+## 当前待修复 Bug
+- `todayCount >= 100` 在 3 处（行58, 129, 238）需改为 `>= 500`
+- `time.Hour` TTL 在 2 处（行72, 192）需改为 `24*time.Hour`
+- `RedisPollingManualDedupeKey` 注释写的"1小时"需改为"24小时"
+
+## client_realname.go 重构要点
+- 当前 `GetRealnameLink` 函数 127 行，加新代码会超 100 行限制
+- 需提取 `resolveTargetCard(c *fiber.Ctx, asset, iccid)` - 资产类型 switch
+- 需提取 `buildRealnameResponse(ctx, card, carrier)` - 运营商 URL 调度
+- 注意：`findCardInDeviceBindings` 和 `findFirstBoundCard` 已存在，可从 resolveTargetCard 调用
+- goroutine 传标量值（uint, string），不能捕获 `c *fiber.Ctx`
+
+## 依赖注入
+- `handlers.go` 第 66 行：`ClientRealname: app.NewClientRealnameHandler(...)` 需加第8个参数
+- `docs.go` 和 `gendocs/main.go` 各有一处 `NewClientRealnameHandler(nil*7)` 需改为 8个nil
+- `svc.PollingManualTrigger` 已在 services.go:210 初始化，可直接使用
+
+## Commit 3 后临时编译失败
+- Task 4 修改构造函数后、Task 5 接线前，全量编译报错是预期行为
+- 只做文件级 LSP 检查，不跑全量 build