## Context

当前君鸿CMP系统存在两个独立的模块：
1. **客户端实名跳转功能**（`internal/handler/app/client_realname.go`）：提供实名链接获取接口
2. **轮询系统手动触发功能**（`internal/service/polling/manual_trigger_service.go`）：支持手动触发卡状态检查

两个模块功能完整但相互独立，导致用户主动实名时无法享受优先级检查的好处。同时手动触发功能存在技术债务需要修复。

**现有架构**：
```
客户端 → ClientRealnameHandler.GetRealnameLink() → 返回实名链接
         （独立运行，无后续动作）

管理员 → PollingManualTriggerHandler → ManualTriggerService.TriggerSingle()
        （仅管理员可用，客户端无法触发）
```

## Goals / Non-Goals

**Goals:**
- 在用户主动获取实名链接时自动触发该ICCID的实名检查优先级提升
- 修复手动触发功能的去重机制时间不对齐问题  
- 优化手动触发的频次限制和权限检查逻辑
- 保持现有API接口的响应时间和兼容性
- 确保新功能的稳定性和可观测性

**Non-Goals:**
- 不修改客户端实名跳转的核心流程和响应格式
- 不改变手动触发API的对外接口
- 不增加新的权限管理复杂性
- 不引入新的外部依赖或中间件

## Decisions

### 决策1：异步触发设计
**选择**：使用 goroutine 异步调用手动触发服务  
**理由**：
- 避免影响实名链接API的响应时间（目标 < 5ms 影响）
- 手动触发失败不应阻断主流程
- 用户无需等待触发结果，实名链接获取成功即可

**实现要点（强制）**：
- goroutine 内部必须使用 `context.WithTimeout(context.Background(), 3*time.Second)` 创建独立 context
- **禁止**在 goroutine 内复用 `c.UserContext()`：Fiber 请求 context 在 handler 返回后即失效，goroutine 中使用会导致操作失败或 context canceled 错误

**备选方案**：
- 同步调用：会影响响应时间，用户体验下降
- 异步任务队列：过度设计，增加系统复杂性

### 决策2：权限适配策略  
**选择**：使用系统用户身份调用手动触发服务  
**理由**：
- 个人客户无管理员权限，无法直接调用手动触发
- 系统用户身份可绕过权限检查但保留操作记录
- 通过配置管理系统用户ID，便于维护

**备选方案**：
- 修改权限检查：破坏现有权限模型
- 创建专用接口：增加代码重复

### 决策3：去重机制修复
**选择**：去重key TTL调整为24小时，与日限制周期对齐  
**理由**：
- 解决当前1小时TTL与24小时限制不匹配的问题
- 确保同一卡在同一天内不会重复触发相同检查
- Redis内存消耗增加可控（估计 < 10MB）

### 决策4：频次限制优化
**选择**：将每日限制从100次调整为500次  
**理由**：
- 当前100次限制过低，客户端自动触发会快速消耗额度
- 500次既满足自动化需求，又能防止滥用
- 保留1000张卡的单次限制不变

### 决策5：依赖注入方式
**选择**：在ClientRealnameHandler中新增ManualTriggerService字段  
**理由**：
- 遵循项目既有的结构体字段注入模式
- 在bootstrap/services.go中统一管理依赖
- 避免循环依赖问题

## Risks / Trade-offs

### 风险1：异步调用失败无感知
**影响**：用户获取实名链接成功，但优先级触发失败，仍需等待定时轮询  
**缓解措施**：
- 增加详细的错误日志记录，便于运维监控
- 设置合理的超时时间，避免goroutine泄露
- 考虑增加Prometheus指标监控异步调用成功率

### 风险2：Redis内存使用增加
**影响**：去重key TTL延长至24小时，Redis内存使用量增加  
**缓解措施**：
- 预估增加量：约10MB（假设每日1000次触发）
- 定期清理过期key，确保Redis稳定运行
- 监控Redis内存使用情况

### 风险3：频次限制调整可能被滥用
**影响**：500次限制仍可能被恶意用户快速消耗  
**缓解措施**：
- 保留现有的权限检查和日志记录
- 增加基于IP的限流保护
- 必要时可通过配置动态调整限制值

### 风险4：系统用户身份权限过高
**影响**：系统用户可触发任意ICCID的检查，存在潜在安全风险  
**缓解措施**：
- 仅在客户端实名场景使用，且ICCID已通过归属权限验证
- 记录详细操作日志，包含原始客户ID
- 系统用户ID通过配置管理，不硬编码

## Migration Plan

### 阶段1：代码实现和测试
1. 修复手动触发服务的去重机制和频次限制
2. 在ClientRealnameHandler中集成异步调用
3. 更新依赖注入配置
4. 编写单元测试和集成测试

### 阶段2：部署和监控
1. 在测试环境验证功能正确性
2. 配置生产环境的系统用户ID
3. 部署到生产环境
4. 监控异步调用成功率和系统性能

### 回滚策略
- **代码回滚**：移除异步调用代码，恢复原有逻辑
- **配置回滚**：调整频次限制和去重TTL到原有值  
- **数据清理**：清理测试期间产生的触发日志

## Open Questions

1. **系统用户ID配置方式**：是否使用环境变量还是数据库配置？
2. **监控指标选择**：是否需要添加Prometheus指标监控？
3. **异步调用超时时间**：设置为多少秒比较合理？（建议3秒）
4. **是否需要熔断机制**：当手动触发服务频繁失败时是否需要暂停自动触发？