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

项目约定和模式

模块路径

• 项目模块路径：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