junhong_cmp_fiber/openspec/changes/archive/2026-04-13-realname-trigger-priority-enhancement/tasks.md

1. 现状分析

• 1.1 使用 lsp_diagnostics 检查 client_realname.go、manual_trigger_service.go 的语法和类型错误
• 1.2 分析现有 ClientRealnameHandler 和 ManualTriggerService 的依赖关系，确认无循环依赖风险

2. 配置管理和常量定义

• 2.1 在 pkg/config/ 中新增 AutoTriggerSystemUserID int 和 EnableAutoTrigger bool（默认 true）配置字段，通过环境变量 JUNHONG_AUTO_TRIGGER_SYSTEM_USER_ID 和 JUNHONG_ENABLE_AUTO_TRIGGER 注入
• 2.2 更新 pkg/config/defaults/config.yaml，添加 auto_trigger_system_user_id 和 enable_auto_trigger 默认值
• 2.3 运行 lsp_diagnostics 检查配置相关代码无错误

3. 手动触发服务 Bug 修复和优化

• 3.1 在 internal/service/polling/manual_trigger_service.go 的 TriggerSingle、TriggerBatch、TriggerByCondition 三处将 todayCount >= 100 改为 todayCount >= 500
• 3.2 在 internal/service/polling/manual_trigger_service.go 的 TriggerSingle 中将 s.redis.Expire(ctx, dedupeKey, time.Hour) 改为 s.redis.Expire(ctx, dedupeKey, 24*time.Hour)
• 3.3 同步更新 pkg/constants/redis.go 中 RedisPollingManualDedupeKey 函数的注释，将 // 过期时间：1小时 改为 // 过期时间：24小时
• 3.4 优化 canManageCard 和 canManageCards 权限检查函数，提取公共逻辑减少重复代码
• 3.5 改进 TriggerSingle 的错误日志，增加 triggeredBy、cardID 等上下文字段
• 3.6 运行 lsp_diagnostics 检查 ManualTriggerService 相关代码无错误
• 3.7 使用 PostgreSQL MCP 和 Redis CLI 手动验证：触发同一张卡后 24 小时内重复触发被拒绝，24 小时后允许重复触发

4. ClientRealnameHandler 集成自动触发功能

• 4.1 在 ClientRealnameHandler 结构体中新增 manualTriggerSvc *polling.ManualTriggerService 字段
• 4.2 修改 NewClientRealnameHandler 构造函数，新增 manualTriggerSvc *polling.ManualTriggerService 参数（可为 nil，nil 时跳过自动触发）
• 4.3 在 GetRealnameLink 成功返回实名链接前，若 h.manualTriggerSvc != nil 且配置 EnableAutoTrigger=true，则启动 goroutine 异步触发实名检查
• 4.4 goroutine 内部必须使用 context.WithTimeout(context.Background(), 3*time.Second) 创建独立 context，禁止复用 c.UserContext()（请求 context 在 handler 返回后失效）
• 4.5 goroutine 内部构造系统用户 context（注入 UserTypePlatform 和配置的 AutoTriggerSystemUserID），调用 manualTriggerSvc.TriggerSingle(sysCtx, targetCard.ID, constants.TaskTypePollingRealname, systemUserID)
• 4.6 goroutine 执行失败时记录 WARN 日志（含 customerID、ICCID、error），成功时记录 INFO 日志（含 customerID、ICCID）；失败不影响主流程
• 4.7 运行 lsp_diagnostics 检查 ClientRealnameHandler 相关代码无错误

5. 依赖注入配置更新

• 5.1 在 internal/bootstrap/handlers.go 中更新 ClientRealname handler 的初始化，传入 ManualTriggerService
• 5.2 确认 ManualTriggerService 在 bootstrap/services.go 中已初始化（检查是否已存在，若不存在则补充）
• 5.3 更新 cmd/api/docs.go 和 cmd/gendocs/main.go 中 NewClientRealnameHandler 的调用，补充新增的 manualTriggerSvc 参数（传 nil 即可）
• 5.4 运行 lsp_diagnostics 检查 bootstrap 和 docs.go 相关代码无编译错误

6. 手动验证

• 6.1 使用 curl 调用 GET /api/c/v1/realname/link 接口，通过日志确认异步触发 goroutine 被启动
• 6.2 通过 PostgreSQL MCP 查询 tb_polling_manual_trigger_log，确认自动触发记录的 triggered_by 为配置的系统用户 ID
• 6.3 通过 Redis CLI 检查 polling:manual:realname 队列，确认 cardID 已写入
• 6.4 使用 PostgreSQL MCP 查询 tb_polling_manual_trigger_log，验证今日触发次数计数正确（不超过 500 次限制）
• 6.5 使用 Redis CLI 确认 dedup key TTL 为 24 小时（TTL polling:manual:dedupe:realname）
• 6.6 模拟 manualTriggerSvc 不可用场景（临时将 EnableAutoTrigger 设为 false），确认接口正常返回实名链接，日志无 panic

7. 最终验收

• 7.1 运行 lsp_diagnostics 对所有修改过的文件做最终检查，确认无错误和警告
• 7.2 确认环境变量 JUNHONG_AUTO_TRIGGER_SYSTEM_USER_ID 和 JUNHONG_ENABLE_AUTO_TRIGGER 已在部署文档中记录
• 7.3 确认 GetRealnameLink handler 函数长度不超过 100 行（满足项目规范）