# realname-trigger-priority-enhancement 执行计划

## TL;DR

> **快速摘要**：修复手动触发去重TTL不对齐、日限制过低两个Bug，并在C端实名链接接口中异步触发优先级检查，减少用户等待时间。
>
> **交付物**：
> - `pkg/config/` 新增 PollingAutoTriggerConfig 配置结构
> - `internal/service/polling/manual_trigger_service.go` 修复3处日限制(100→500)、2处TTL(1h→24h)、提取权限检查公共函数、增强错误日志
> - `internal/handler/app/client_realname.go` 新增异步触发逻辑（含2个辅助方法提取）
> - `internal/bootstrap/handlers.go`、`cmd/api/docs.go`、`cmd/gendocs/main.go` 依赖注入接线
> - `pkg/constants/redis.go` 注释同步更新
>
> **预计工作量**：60-90 分钟
> **关键路径**：配置 → ManualTriggerService修复 → Handler集成 → 依赖注入接线 → 手动验证

---

## 上下文

### 原始需求

用户在C端主动获取实名跳转链接后，需等待轮询系统定时检查（30秒-5分钟间隔）才能检测到实名状态变化。同时手动触发功能存在两个Bug：去重key TTL（1小时）与日限制周期（24小时）不对齐，以及日限制次数（100次）过低导致正常使用受限。

### 代码库现状（已验证）

| 项目 | 状态 |
|------|------|
| `constants.TaskTypePollingRealname` | ✅ 已存在：`"polling:realname"`（constants.go:55） |
| `svc.PollingManualTrigger` in bootstrap | ✅ 已初始化（services.go:210） |
| 日限制 `>= 100` 位置 | **3处**：manual_trigger_service.go:58, 129, 238 |
| `Expire(..., time.Hour)` 位置 | **2处**：manual_trigger_service.go:72（TriggerSingle）和 :192（processBatchTrigger） |
| `NewClientRealnameHandler` 当前参数数 | 7个 → 改后8个 |
| docs.go / gendocs/main.go 调用处 | 各1处，7个nil → 8个nil |
| `GetRealnameLink` 当前行数 | **127行**（已超100行限制，需提取辅助方法） |
| 系统用户 | 暂用 SuperAdmin ID=1，使用 UserTypePlatform 身份 |

### 关键设计决策

1. **goroutine 异步触发**：使用 `context.WithTimeout(context.Background(), 3s)` 独立 context，**禁止**复用 `c.UserContext()`（Fiber 请求 context 在 handler 返回后失效）
2. **系统用户身份**：`UserTypePlatform`（非 UserTypeSuperAdmin），既绕过卡归属权限检查，又仍受500次/天限制约束
3. **goroutine 参数**：只传标量值（uint、string），**绝对不捕获 `c *fiber.Ctx` 或任何指针**
4. **GetRealnameLink 行数**：当前127行已超限，需在 Task 4 中额外提取两个 helper（已批准）
5. **processBatchTrigger TTL**：两处都修（已确认）
6. **Commit 3 临时编译失败**：Task 4 修改构造函数后、Task 5 接线前，全量编译会报错，只做文件级 LSP 检查

---

## Phase 0 — 现状分析

### Task 1.1 — LSP 基线诊断

**操作**：对以下两个文件运行 `lsp_diagnostics`：
- `internal/handler/app/client_realname.go`
- `internal/service/polling/manual_trigger_service.go`

**目的**：建立干净基线，区分预存问题与本次引入的问题

**验收**：记录所有预存 warning，确认无预存 error

---

### Task 1.2 — 依赖关系确认

**操作**：
- 确认 `handler/app → service/polling` 无循环依赖（polling service 不导入 handler 包）
- 确认 `internal/bootstrap/handlers.go` 已有 `pollingSvcPkg` import alias

**验收**：无循环依赖，`svc.PollingManualTrigger` 在 bootstrap 中可访问

---

## Phase 1 — 配置管理

### Task 2.1 — 新增配置结构体和字段

**文件**：`pkg/config/config.go`

新增结构体（放在其他 Config 结构体附近）：
```go
// PollingAutoTriggerConfig 轮询自动触发配置
type PollingAutoTriggerConfig struct {
    // EnableAutoTrigger 是否启用C端实名自动触发
    // 环境变量：JUNHONG_POLLING_AUTO_TRIGGER_ENABLE_AUTO_TRIGGER
    EnableAutoTrigger bool `mapstructure:"enable_auto_trigger"`
    // AutoTriggerSystemUserID 自动触发使用的系统用户ID（暂用 SuperAdmin ID=1）
    // 环境变量：JUNHONG_POLLING_AUTO_TRIGGER_AUTO_TRIGGER_SYSTEM_USER_ID
    AutoTriggerSystemUserID int `mapstructure:"auto_trigger_system_user_id"`
}
```

在 `Config` struct 中添加字段（位置：Gateway 字段之后）：
```go
PollingAutoTrigger PollingAutoTriggerConfig `mapstructure:"polling_auto_trigger"`
```

**陷阱**：不要在 `Validate()` 中添加校验——零值（false/0）是合法默认值

**验收**：结构体定义正确，mapstructure tag 与 yaml key 对应

---

### Task 2.2 — 更新默认配置 YAML

**文件**：`pkg/config/defaults/config.yaml`

在文件末尾添加（保留尾部换行）：
```yaml
# 轮询自动触发配置
polling_auto_trigger:
  enable_auto_trigger: true
  auto_trigger_system_user_id: 1  # 暂用 SuperAdmin，生产环境建议创建专用平台账号并更新此值
```

对应环境变量：
- `JUNHONG_POLLING_AUTO_TRIGGER_ENABLE_AUTO_TRIGGER`
- `JUNHONG_POLLING_AUTO_TRIGGER_AUTO_TRIGGER_SYSTEM_USER_ID`

**验收**：config.Get().PollingAutoTrigger.EnableAutoTrigger 默认为 true

---

### Task 2.3 — LSP 检查配置

**操作**：`lsp_diagnostics` 对 `pkg/config/config.go`

**验收**：0 error

---

## Phase 2 — 手动触发服务 Bug 修复

### Task 3.1 — 日限制 100 → 500（3处）

**文件**：`internal/service/polling/manual_trigger_service.go`

| 行号 | 修改内容 |
|------|---------|
| 58 | `todayCount >= 100` → `todayCount >= 500`，同步更新行内注释 `// 每日最多触发100次` → `// 每日最多触发500次` |
| 129 | `todayCount >= 100` → `todayCount >= 500`，补充注释 `// 每日最多触发500次` |
| 238 | `todayCount >= 100` → `todayCount >= 500`，补充注释 `// 每日最多触发500次` |

**验收**：`grep -n "100" manual_trigger_service.go` 无日限制相关残留

---

### Task 3.2 — 去重 TTL 1h → 24h（2处）

**文件**：`internal/service/polling/manual_trigger_service.go`

| 行号 | 修改内容 |
|------|---------|
| 71-72 | 注释改为 `// 设置去重 key 过期时间（24小时，与日限制周期对齐）`；`time.Hour` → `24*time.Hour` |
| 191-192 | 同上（processBatchTrigger 中，存在相同 Bug，一并修复） |

**验收**：`grep -n "time.Hour" manual_trigger_service.go` 无残留

---

### Task 3.3 — 同步 Redis 常量注释

**文件**：`pkg/constants/redis.go`

找到 `RedisPollingManualDedupeKey` 函数注释，将：
```
// 过期时间：1小时
```
改为：
```
// 过期时间：24小时（与日限制周期对齐）
```

**验收**：注释与实际 TTL 一致

---

### Task 3.4 — 提取公共权限检查函数

**文件**：`internal/service/polling/manual_trigger_service.go`

从 `canManageCard`、`canManageCards`、`applyShopPermissionFilter` 三处提取重复的用户类型检查，新增私有方法：

```go
// checkUserTypePermission 检查用户类型是否有手动触发权限
// 返回 skip=true 表示超级管理员/平台用户直接放行
// 返回 err!=nil 表示企业账号无权限
// 返回 skip=false, err=nil 表示代理账号需继续细粒度检查
func (s *ManualTriggerService) checkUserTypePermission(ctx context.Context) (skip bool, err error) {
    userType := middleware.GetUserTypeFromContext(ctx)
    if userType == constants.UserTypeSuperAdmin || userType == constants.UserTypePlatform {
        return true, nil
    }
    if userType == constants.UserTypeEnterprise {
        return false, errors.New(errors.CodeForbidden, "企业账号无权限手动触发轮询")
    }
    return false, nil
}
```

三个调用方改为：
```go
skip, err := s.checkUserTypePermission(ctx)
if err != nil || skip {
    return err  // canManageCard 签名
}
```

**陷阱**：`applyShopPermissionFilter` 中超管分支有 filter 对象逻辑，只提取类型检查部分，不删除 filter 修改逻辑

**验收**：三个函数各减少约5行重复代码，行为不变

---

### Task 3.5 — 改进 TriggerSingle 错误日志

**文件**：`internal/service/polling/manual_trigger_service.go`

在 `TriggerSingle` 每条 `return err` 路径前补充结构化日志，字段要求：

| 错误场景 | 必须包含字段 |
|---------|------------|
| 查询今日触发次数失败 | `triggered_by`、`task_type`、`error` |
| Redis去重操作失败 | `card_id`、`task_type`、`error` |
| 创建触发日志失败 | `card_id`、`triggered_by`、`error` |
| 写入队列失败 | `card_id`、`task_type`、`error` |

**验收**：每条 return err 路径有对应日志，级别为 Error

---

### Task 3.6 — LSP 检查

**操作**：`lsp_diagnostics` 对 `internal/service/polling/manual_trigger_service.go`

**验收**：0 error，0 新增 warning

---

### Task 3.7 — 手动验证去重 + 限制

**操作**（通过 Redis CLI 或 PostgreSQL MCP）：

```bash
# 1. 触发某张卡，验证 TTL 为 24小时
redis-cli TTL polling:manual:dedupe:polling:realname
# 期望：≈ 86400

# 2. 再次触发同一张卡，验证被拒绝
# 期望返回："该卡已在手动触发队列中"

# 3. 删除 dedupe key 后重新触发，验证成功
redis-cli DEL polling:manual:dedupe:polling:realname
```

```sql
-- 验证今日触发次数计数正确
SELECT COUNT(*) as today_count
FROM tb_polling_manual_trigger_log
WHERE DATE(triggered_at) = CURRENT_DATE;
```

**验收**：TTL ≈ 86400，重复触发被拒绝，DB 计数正确

---

## Phase 3 — Handler 集成

### Task 4.1 — 结构体新增字段

**文件**：`internal/handler/app/client_realname.go`

添加 import（注意区分 `internal/service/polling` 与 `internal/polling` 是不同包）：
```go
pollingSvc "github.com/xxx/junhong_cmp_fiber/internal/service/polling"
```

在 `ClientRealnameHandler` 结构体新增字段：
```go
manualTriggerSvc *pollingSvc.ManualTriggerService // 手动触发服务（可为nil，nil时跳过自动触发）
```

**验收**：结构体字段添加正确，import 路径正确

---

### Task 4.2 — 修改构造函数（第8个参数）

**文件**：`internal/handler/app/client_realname.go`

在 `NewClientRealnameHandler` 末尾新增参数：
```go
func NewClientRealnameHandler(
    // ...现有7个参数保持不变...
    manualTriggerSvc *pollingSvc.ManualTriggerService, // 可为nil
) *ClientRealnameHandler {
    return &ClientRealnameHandler{
        // ...现有字段初始化...
        manualTriggerSvc: manualTriggerSvc,
    }
}
```

**陷阱**：修改后 `docs.go`、`gendocs/main.go`、`bootstrap/handlers.go` 会出现编译错误（构造函数参数不一致），待 Task 5 修复。此阶段**只做文件级** LSP 检查，不跑全量 build

**验收**：`client_realname.go` 本身 LSP 0 error

---

### Task 4.3 — 提取辅助方法（解决 GetRealnameLink 行数超限问题）

**文件**：`internal/handler/app/client_realname.go`

**背景**：当前 `GetRealnameLink` 127行，加 goroutine 代码约133行，违反 ≤100行规范。需提取两个私有方法。

**提取1：`resolveTargetCard`**（资产类型 switch 分支，约26行）：
```go
// resolveTargetCard 根据资产类型和ICCID定位目标卡
// 支持三条路径：直接卡资产、设备+指定ICCID、设备取第一张绑定卡
func (h *ClientRealnameHandler) resolveTargetCard(c *fiber.Ctx, asset *assetService.ResolvedAsset, iccid string) (*model.IotCard, error) {
    switch {
    case asset.AssetType == "card":
        // ...
    case asset.AssetType == "device" && iccid != "":
        // ...
    case asset.AssetType == "device":
        // ...
    default:
        return nil, errors.New(errors.CodeInvalidParam, "不支持的资产类型")
    }
}
```

**提取2：`buildRealnameResponse`**（运营商 URL 调度，约32行）：
```go
// buildRealnameResponse 根据运营商实名链接类型构建响应
func (h *ClientRealnameHandler) buildRealnameResponse(ctx context.Context, card *model.IotCard, carrier *model.Carrier) (*dto.RealnimeLinkResponse, error) {
    // switch carrier.RealnameLinkType { ... }
}
```

提取后 `GetRealnameLink` ≈70行，加 goroutine 后 ≈76行 ✅

**陷阱**：
- `resolveTargetCard` 需要 `c *fiber.Ctx`（子函数调用需要 Fiber context）
- `buildRealnameResponse` 用 `ctx context.Context`（只调 gatewayClient）
- 确认 `assetService.ResolvedAsset` 的实际类型名称（读文件确认后再写）

**验收**：`GetRealnameLink` 函数体 ≤100行，两个新方法编译正常，逻辑不变

---

### Task 4.4 — 添加异步触发调用

**文件**：`internal/handler/app/client_realname.go`

添加 import：`"github.com/xxx/junhong_cmp_fiber/pkg/config"`

在 `GetRealnameLink` 中，成功构建响应之后、`response.Success(c, resp)` 之前插入：
```go
// 异步触发实名检查，提升检测优先级；失败不影响主流程
if h.manualTriggerSvc != nil && config.Get().PollingAutoTrigger.EnableAutoTrigger {
    systemUserID := uint(config.Get().PollingAutoTrigger.AutoTriggerSystemUserID)
    go h.triggerRealnameCheck(targetCard.ID, customerID, targetCard.ICCID, systemUserID)
}
```

**强制约束**：goroutine 只传标量值（uint、string），**绝对不捕获 `c *fiber.Ctx` 或任何指针类型**

**验收**：goroutine 启动代码不捕获 Fiber context 相关变量

---

### Task 4.5 — 实现 triggerRealnameCheck 私有方法

**文件**：`internal/handler/app/client_realname.go`

添加 imports：`"context"`、`"time"`、`"github.com/xxx/junhong_cmp_fiber/pkg/middleware"`

```go
// triggerRealnameCheck 异步触发单卡实名检查
// 在独立 goroutine 中调用，使用独立 context 避免 Fiber 请求 context 失效问题
// 参数全部为值类型，不捕获请求相关指针
func (h *ClientRealnameHandler) triggerRealnameCheck(cardID, customerID uint, iccid string, systemUserID uint) {
    // 必须使用独立 context，禁止复用 Fiber 请求 context（请求返回后即失效）
    ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
    defer cancel()

    // 使用平台用户身份构建 context，绕过卡归属权限检查
    // 注意：使用 UserTypePlatform 而非 UserTypeSuperAdmin，SuperAdmin 不受日限制约束
    sysCtx := middleware.SetUserContext(ctx, &middleware.UserContextInfo{
        UserID:   systemUserID,
        UserType: constants.UserTypePlatform,
    })

    err := h.manualTriggerSvc.TriggerSingle(sysCtx, cardID, constants.TaskTypePollingRealname, systemUserID)
    if err != nil {
        h.logger.Warn("自动触发实名检查失败",
            zap.Uint("customer_id", customerID),
            zap.String("iccid", iccid),
            zap.Uint("card_id", cardID),
            zap.Error(err))
        return
    }
    h.logger.Info("自动触发实名检查成功",
        zap.Uint("customer_id", customerID),
        zap.String("iccid", iccid),
        zap.Uint("card_id", cardID))
}
```

**验收**：方法 ≤30行，使用 `context.Background()`，context 注入 UserTypePlatform，日志字段完整

---

### Task 4.6 — 日志字段核查

**检查清单**：
- [x] WARN 路径包含：`customer_id`、`iccid`、`card_id`、`error`
- [x] INFO 路径包含：`customer_id`、`iccid`、`card_id`
- [x] 无 nil panic 风险（err 已检查）
- [x] goroutine 无 panic 风险（manualTriggerSvc 已在调用前检查非 nil）

**验收**：所有字段齐全，无潜在 panic

---

### Task 4.7 — LSP 检查 Handler 文件

**操作**：`lsp_diagnostics` 对 `internal/handler/app/client_realname.go`

**注意**：此时 `bootstrap/handlers.go`、`docs.go`、`gendocs/main.go` 仍有编译错误（待 Task 5），只关注 `client_realname.go` 自身

**验收**：`client_realname.go` 自身 0 error

---

## Phase 4 — 依赖注入接线

### Task 5.1 — 更新 bootstrap/handlers.go

**文件**：`internal/bootstrap/handlers.go`

找到 `ClientRealname` 初始化行，在末尾补充 `svc.PollingManualTrigger` 参数：

```go
// 修改前（7个参数）
ClientRealname: app.NewClientRealnameHandler(
    svc.Asset, personalCustomerDeviceStore, iotCardStore,
    deviceSimBindingStore, carrierStore, deps.GatewayClient, deps.Logger,
),

// 修改后（8个参数）
ClientRealname: app.NewClientRealnameHandler(
    svc.Asset, personalCustomerDeviceStore, iotCardStore,
    deviceSimBindingStore, carrierStore, deps.GatewayClient, deps.Logger,
    svc.PollingManualTrigger,
),
```

**验收**：`svc.PollingManualTrigger` 类型匹配（已在 services.go:210 初始化）

---

### Task 5.2 — 确认 ManualTriggerService 初始化（只读）

**操作**：确认 `internal/bootstrap/services.go:210` 已有：
```go
PollingManualTrigger: pollingSvc.NewManualTriggerService(...)
```

**无需变更**，仅确认

**验收**：`svc.PollingManualTrigger` 非 nil

---

### Task 5.3 — 更新 docs.go 和 gendocs/main.go

**文件**：`cmd/api/docs.go` 和 `cmd/gendocs/main.go`

两处均将 `NewClientRealnameHandler` 调用从 7个nil 改为 8个nil：

```go
// 修改前
handlers.ClientRealname = apphandler.NewClientRealnameHandler(nil, nil, nil, nil, nil, nil, nil)

// 修改后
handlers.ClientRealname = apphandler.NewClientRealnameHandler(nil, nil, nil, nil, nil, nil, nil, nil)
```

**验收**：两个文件均编译通过

---

### Task 5.4 — LSP 检查依赖注入相关文件

**操作**：`lsp_diagnostics` 对以下3个文件：
- `internal/bootstrap/handlers.go`
- `cmd/api/docs.go`
- `cmd/gendocs/main.go`

**验收**：全部 0 error

---

## Phase 5 — 手动验证

### Task 6.1 — 接口调用验证 goroutine 启动

```bash
curl -H "Authorization: Bearer <token>" \
  "http://localhost:3000/api/c/v1/realname/link?identifier=<iccid>"
```

**查看 app.log** 确认出现：
```json
{"level":"info","msg":"自动触发实名检查成功","customer_id":...,"iccid":"...","card_id":...}
```

**验收**：响应正常返回实名链接，日志在响应后3秒内出现

---

### Task 6.2 — DB 验证触发记录

```sql
SELECT triggered_by, task_type, total_count, status, created_at
FROM tb_polling_manual_trigger_log
WHERE triggered_by = 1
ORDER BY id DESC LIMIT 5;
```

**期望**：`triggered_by = 1`（SuperAdmin），`task_type = 'polling:realname'`，`total_count = 1`

**验收**：记录存在且字段正确

---

### Task 6.3 — Redis 队列验证

```bash
redis-cli LRANGE polling:manual:polling:realname 0 -1
```

**期望**：卡 ID 存在于队列中

**验收**：队列条目可见

---

### Task 6.4 — 日限制计数验证

```sql
SELECT COUNT(*) as today_count
FROM tb_polling_manual_trigger_log
WHERE triggered_by = 1
  AND DATE(triggered_at) = CURRENT_DATE;
```

**期望**：计数正确，未超过500

**验收**：计数准确

---

### Task 6.5 — Redis 去重 TTL 验证

```bash
redis-cli TTL polling:manual:dedupe:polling:realname
```

**期望**：≈ 86400（24小时）

**验收**：TTL 约等于 86400

---

### Task 6.6 — 功能开关验证

设置 `JUNHONG_POLLING_AUTO_TRIGGER_ENABLE_AUTO_TRIGGER=false` 后重启服务，调用接口：

**期望**：正常返回实名链接，app.log 无自动触发相关日志，DB 无新增触发记录，无 panic

**验收**：功能开关有效，主流程不受影响

---

## Phase 6 — 最终验收

### Task 7.1 — 全文件 LSP 最终扫描

对所有修改过的文件运行 `lsp_diagnostics`：
- `internal/handler/app/client_realname.go`
- `internal/service/polling/manual_trigger_service.go`
- `internal/bootstrap/handlers.go`
- `pkg/constants/redis.go`
- `pkg/config/config.go`
- `cmd/api/docs.go`
- `cmd/gendocs/main.go`

**验收**：全部 0 error，0 新增 warning

---

### Task 7.2 — 环境变量文档记录

确认以下环境变量已在部署文档中记录：

| 环境变量 | 默认值 | 说明 |
|---------|-------|------|
| `JUNHONG_POLLING_AUTO_TRIGGER_ENABLE_AUTO_TRIGGER` | `true` | 自动触发开关，可临时关闭 |
| `JUNHONG_POLLING_AUTO_TRIGGER_AUTO_TRIGGER_SYSTEM_USER_ID` | `1` | 暂用 SuperAdmin。**生产环境建议创建专用平台账号（user_type=Platform）并更新此值** |

**验收**：文档中有上述两个环境变量的说明

---

### Task 7.3 — GetRealnameLink 行数确认

统计 `GetRealnameLink` 函数体行数（从 `func` 到最后一个 `}`）：

**验收**：≤ 100 行

---

## 原子提交策略

| 提交顺序 | 涵盖文件 | Commit Message |
|---------|---------|---------------|
| Commit 1 | `pkg/config/config.go`、`pkg/config/defaults/config.yaml` | `feat: 新增轮询自动触发配置（EnableAutoTrigger、AutoTriggerSystemUserID）` |
| Commit 2 | `internal/service/polling/manual_trigger_service.go`、`pkg/constants/redis.go` | `fix: 修复手动触发去重TTL和日限制次数，优化权限检查和错误日志` |
| Commit 3 | `internal/handler/app/client_realname.go` | `feat: ClientRealnameHandler 集成异步触发实名检查` |
| Commit 4 | `internal/bootstrap/handlers.go`、`cmd/api/docs.go`、`cmd/gendocs/main.go` | `feat: 更新依赖注入，传入 ManualTriggerService` |

> ⚠️ Commit 3 之后、Commit 4 完成之前，全量编译会报错（构造函数参数不一致）。只做文件级 LSP 检查，不跑全量 build。

---

## 风险清单

| 风险 | 级别 | 对策 |
|------|------|------|
| goroutine 捕获 `c *fiber.Ctx` 导致 use-after-free | **致命** | `triggerRealnameCheck` 只接受标量参数（uint、string） |
| GetRealnameLink 超 100 行 | 高 | Task 4.3 提取两个 helper（已批准） |
| processBatchTrigger TTL 漏修 | 中 | Task 3.2 明确修复两处（已确认） |
| SuperAdmin(ID=1) 与其他系统进程共享日限额 | 低 | 生产环境创建专用账号后更新配置 |
| Commit 3 后临时全量编译失败 | 预期行为 | 文件级 LSP 即可，Task 5 完成后全量恢复 |
| `assetService.ResolvedAsset` 实际类型名称不确定 | 低 | Task 4.3 执行前先读文件确认类型名 |

---

## 提案 tasks.md 更新规则

**文件**：`openspec/changes/realname-trigger-priority-enhancement/tasks.md`

每完成一个 Phase 后，必须将对应条目从 `- [ ]` 改为 `- [x]`。对应关系如下：

| 本计划 Phase/Task | 提案 tasks.md 条目 |
|-----------------|------------------|
| Task 1.1 完成 | `1.1 使用 lsp_diagnostics 检查...` |
| Task 1.2 完成 | `1.2 分析现有 ClientRealnameHandler...` |
| Task 2.1 完成 | `2.1 在 pkg/config/ 中新增...` |
| Task 2.2 完成 | `2.2 更新 pkg/config/defaults/config.yaml...` |
| Task 2.3 完成 | `2.3 运行 lsp_diagnostics 检查配置...` |
| Task 3.1 完成 | `3.1 ...三处将 todayCount >= 100 改为...` |
| Task 3.2 完成 | `3.2 ...将 s.redis.Expire(ctx, dedupeKey, time.Hour) 改为...` |
| Task 3.3 完成 | `3.3 同步更新 pkg/constants/redis.go...` |
| Task 3.4 完成 | `3.4 优化 canManageCard 和 canManageCards...` |
| Task 3.5 完成 | `3.5 改进 TriggerSingle 的错误日志...` |
| Task 3.6 完成 | `3.6 运行 lsp_diagnostics 检查 ManualTriggerService...` |
| Task 3.7 完成 | `3.7 使用 PostgreSQL MCP 和 Redis CLI 手动验证...` |
| Task 4.1–4.2 完成 | `4.1 在 ClientRealnameHandler 结构体中新增...` + `4.2 修改 NewClientRealnameHandler...` |
| Task 4.3 完成（提取 helper） | — （本计划新增步骤，提案无对应条目） |
| Task 4.4–4.5 完成 | `4.3 在 GetRealnameLink 成功返回...` + `4.4 goroutine 内部必须使用...` + `4.5 goroutine 内部构造系统用户 context...` |
| Task 4.6 完成 | `4.6 goroutine 执行失败时记录 WARN 日志...` |
| Task 4.7 完成 | `4.7 运行 lsp_diagnostics 检查 ClientRealnameHandler...` |
| Task 5.1 完成 | `5.1 在 internal/bootstrap/handlers.go 中更新...` |
| Task 5.2 完成 | `5.2 确认 ManualTriggerService 在 bootstrap/services.go 中已初始化...` |
| Task 5.3 完成 | `5.3 更新 cmd/api/docs.go 和 cmd/gendocs/main.go...` |
| Task 5.4 完成 | `5.4 运行 lsp_diagnostics 检查 bootstrap 和 docs.go...` |
| Task 6.1 完成 | `6.1 使用 curl 调用...` |
| Task 6.2 完成 | `6.2 通过 PostgreSQL MCP 查询 tb_polling_manual_trigger_log...` |
| Task 6.3 完成 | `6.3 通过 Redis CLI 检查 polling:manual:realname 队列...` |
| Task 6.4 完成 | `6.4 使用 PostgreSQL MCP 查询今日触发次数...` |
| Task 6.5 完成 | `6.5 使用 Redis CLI 确认 dedup key TTL 为 24 小时...` |
| Task 6.6 完成 | `6.6 模拟 manualTriggerSvc 不可用场景...` |
| Task 7.1 完成 | `7.1 运行 lsp_diagnostics 对所有修改过的文件...` |
| Task 7.2 完成 | `7.2 确认环境变量...已在部署文档中记录` |
| Task 7.3 完成 | `7.3 确认 GetRealnameLink handler 函数长度不超过 100 行` |

**更新方式**：直接编辑 `tasks.md`，将对应行的 `- [ ]` 替换为 `- [x]`。每个 Phase 执行完毕后集中更新该 Phase 所有条目，不要跨 Phase 提前勾选。
