# 京东Cookie订单支付状态自动监控设计

## 概述

在现有京东Cookie管理模块的基础上，新增后台任务自动监控订单支付状态的功能。当用户创建订单并获取微信支付链接后，系统将自动检查订单支付状态，及时更新数据库记录并处理相关业务逻辑。

## 架构设计

### 系统交互流程

```mermaid
sequenceDiagram
participant User as 用户
participant API as API层
participant Service as 服务层
participant Task as 后台任务
participant JD as 京东接口
participant DB as 数据库

User->>API: 创建订单获取支付链接
API->>Service: 调用创建订单服务
Service->>DB: 创建订单记录
Service-->>API: 返回支付链接
API-->>User: 返回支付链接

Task->>DB: 查询待支付订单
Task->>Service: 检查订单支付状态
Service->>JD: 调用支付状态检查接口
JD-->>Service: 返回支付状态
alt 订单已支付
    Service->>DB: 更新京东订单状态为已支付
    Service->>JD: 获取卡密信息
    JD-->>Service: 返回卡号卡密
    Service->>DB: 保存卡密信息
    Service->>DB: 记录变更历史
else 订单未支付
    Service->>Service: 无需处理
end
```

### 核心组件设计

#### 1. 定时任务调度器

扩展现有cron.go模块，新增支付状态检查任务：

| 组件名称 | 描述 | 实现方式 |
|---------|------|----------|
| 定时任务 | 支付状态检查任务 | 在cron.Register()中新增"@every 1m"任务 |
| 任务管理 | 管理待检查的订单队列 | 通过service.JdCookie().CheckPaymentStatus()方法 |
| 缓存支持 | 避免重复检查同一订单 | 使用现有cache.go模块缓存检查状态 |

#### 2. 支付状态检查服务

| 功能模块 | 描述 | 实现策略 |
|---------|------|----------|
| 状态查询 | 调用@originalJd服务检查支付状态 | 扩展现有CheckJdOrderPayment方法 |
| 状态对比 | 比较本地状态与远程状态 | 识别状态变化，触发相应处理流程 |
| 缓存管理 | 记录最后检查时间 | 使用cache.PrefixEnum扩展新的缓存前缀 |

#### 3. 卡密提取服务

| 功能模块 | 描述 | 触发条件 |
|---------|------|----------|
| 卡密获取 | 调用@originalJd服务GetCardInfo获取卡号卡密 | 订单状态为"待使用"或"等待发码" |
| 数据存储 | 明文保存卡密信息到京东订单表 | 直接更新现有订单记录 |
| 历史记录 | 记录卡密提取操作历史 | 调用现有RecordJdOrderHistory方法 |

## 数据模型扩展

### 京东订单表字段扩展

京东订单表(`jd_cookie_jd_order`)需要新增以下字段来支持卡密信息存储和状态跟踪：

| 新增字段 | 类型 | 说明 | 约束 | 用途 |
|---------|------|------|------|------|
| paid_at | datetime | 支付完成时间 | NULL | 记录订单实际支付时间 |
| card_no | varchar(100) | 卡号 | NULL | 明文存储提取的卡号信息 |
| card_password | varchar(100) | 卡密 | NULL | 明文存储提取的卡密信息 |
| card_extracted_at | datetime | 卡密提取时间 | NULL | 记录卡密提取完成时间 |

### 缓存模块扩展

在现有cache.go中新增京东支付检查相关的缓存前缀：

```go
const (
    PrefixJdPaymentCheck PrefixEnum = "jd_payment_check" // 支付状态检查缓存
    PrefixJdCardExtract  PrefixEnum = "jd_card_extract"  // 卡密提取锁定缓存
)
```

## 业务流程设计

### 支付状态监控流程

```mermaid
flowchart TD
    Start([定时任务启动]) --> Query[查询待支付京东订单]
    Query --> Filter{过滤条件检查}
    Filter -->|符合条件| Check[调用京东接口检查支付状态]
    Filter -->|不符合条件| End([结束])
    
    Check --> Compare{状态是否变化}
    Compare -->|无变化| UpdateTime[更新最后检查时间]
    Compare -->|有变化| StatusCheck{支付状态判断}
    
    StatusCheck -->|已支付| UpdatePaid[更新订单为已支付状态]
    StatusCheck -->|未支付| UpdateTime
    StatusCheck -->|已过期| UpdateExpired[更新订单为过期状态]
    
    UpdatePaid --> CardCheck{是否需要提取卡密}
    CardCheck -->|是| ExtractCard[调用接口提取卡密]
    CardCheck -->|否| RecordHistory1[记录状态变更历史]
    
    ExtractCard --> SaveCard[保存卡密到数据库]
    SaveCard --> RecordHistory1
    
    UpdateExpired --> RecordHistory2[记录过期历史]
    RecordHistory1 --> UpdateTime
    RecordHistory2 --> UpdateTime
    UpdateTime --> End
```

### 任务调度策略

#### 筛选条件设计

| 筛选条件 | 描述 | 目的 |
|---------|------|------|
| 状态筛选 | 仅检查状态为"待支付"的京东订单 | 减少不必要的接口调用 |
| 时间筛选 | 优先检查创建时间较早的订单 | 确保及时处理用户支付 |
| 频率控制 | 最近5分钟内已检查的订单延后处理 | 避免过度频繁的接口调用 |
| 批量处理 | 每次任务最多处理50个订单 | 控制单次任务执行时间 |

#### 异常处理机制

| 异常类型 | 处理策略 | 重试机制 |
|---------|---------|---------|
| 网络超时 | 记录错误日志，跳过当前订单 | 下次任务周期重试 |
| 接口错误 | 根据错误码判断是否重试 | 最多重试3次，间隔递增 |
| 数据库错误 | 事务回滚，记录错误日志 | 立即重试1次 |
| Cookie失效 | 更新Cookie状态，暂停使用 | 不重试，等待人工处理 |

### 卡密提取业务逻辑

#### 提取触发条件

```mermaid
graph TD
    PaymentPaid[订单已支付] --> OrderStatus{京东订单状态}
    OrderStatus -->|待使用| Extract[提取卡密]
    OrderStatus -->|等待发码| Extract
    OrderStatus -->|其他状态| Wait[等待状态变更]
    
    Extract --> CallAPI[调用GetCardInfo接口]
    CallAPI --> Success{接口调用成功}
    Success -->|成功| SaveData[保存卡密数据]
    Success -->|失败| RetryCheck{是否需要重试}
    
    RetryCheck -->|是| Delay[延迟重试]
    RetryCheck -->|否| LogError[记录错误日志]
    
    Delay --> CallAPI
    SaveData --> UpdateFlag[标记卡密已提取]
    UpdateFlag --> RecordHistory[记录提取历史]
    LogError --> End([结束])
    RecordHistory --> End
```

## 日志与监控

### 日志记录策略

基于GoFrame的glog组件实现统一日志管理：

| 日志类型 | 记录内容 | GoFrame实现 |
|---------|---------|-------------|
| 操作日志 | 任务执行开始/结束 | glog.Info记录任务执行情况 |
| 业务日志 | 支付状态变更、卡密提取 | glog.Info记录关键业务节点 |
| 错误日志 | 接口调用失败、数据库操作异常 | glog.Error记录异常信息 |
| 调试日志 | 详细的处理流程信息 | glog.Debug记录调试信息 |

### 异常处理机制

| 异常类型 | 处理策略 | GoFrame实现方式 |
|---------|----------|-----------------|
| 网络超时 | 记录错误日志，跳过当前订单 | 使用glog.Error记录，下次任务周期重试 |
| 接口错误 | 根据错误码判断是否重试 | 使用gerror包装错误信息 |
| 数据库错误 | 事务回滚，记录错误日志 | 使用gdb事务功能，glog记录错误 |
| Cookie失效 | 调用现有handleCookieFailure方法 | 复用现有Cookie失败处理逻辑 |

### 关键指标监控

| 指标类型 | 指标名称 | 阈值设置 | 告警级别 |
|---------|---------|---------|---------|
| 成功率 | 支付状态检查成功率 | < 95% | 警告 |
| 延迟 | 订单支付到状态更新的延迟 | > 5分钟 | 警告 |
| 错误率 | 接口调用错误率 | > 5% | 严重 |
| 处理量 | 每分钟处理订单数量 | < 10个 | 提醒 |

### 异常告警机制

```mermaid
graph LR
    Monitor[监控系统] --> Threshold{阈值检查}
    Threshold -->|超过阈值| Alert[触发告警]
    Threshold -->|正常| Continue[继续监控]
    
    Alert --> Classify{告警分类}
    Classify -->|严重| Immediate[立即通知]
    Classify -->|警告| Batch[批量通知]
    Classify -->|提醒| Daily[日报汇总]
    
    Immediate --> SMS[短信通知]
    Immediate --> Email[邮件通知]
    Batch --> Email
    Daily --> Report[生成报告]
```

## 实现细节

### 业务逻辑处理

#### 批量检查支付状态

```go
// 硬编码配置参数
const (
    BatchSize = 20                    // 单次处理订单数量
    CheckInterval = 5 * time.Minute   // 检查间隔时间
)

// 筛选待检查订单
// 1. 状态为待支付(status=1)
// 2. 创建时间在24小时内
// 3. 未被缓存锁定(5分钟内未检查过)
```

#### 卡密提取流程

```go
// 触发条件判断
// 1. 支付状态已变更为已支付(status=2) 
// 2. 卡密字段为空(card_no IS NULL)
// 3. 未被提取锁定缓存
```

### 历史记录策略

| 变更类型 | 记录时机 | change_type值 | 说明 |
|---------|----------|---------------|------|
| 支付成功 | 检测到订单已支付 | "payment_success" | 记录支付完成 |
| 卡密提取 | 成功提取卡密信息 | "card_extracted" | 记录卡密提取完成 |
| 状态检查 | 每次状态检查 | "status_checked" | 记录检查操作(可选) |

## 测试策略

### 单元测试覆盖

| 测试模块 | 测试重点 | 覆盖目标 |
|---------|---------|---------|
| 状态检查服务 | 接口调用和状态解析 | 90%+ |
| 卡密提取服务 | 数据提取和加密存储 | 95%+ |
| 任务调度器 | 定时任务和异常处理 | 85%+ |
| 数据访问层 | CRUD操作和事务处理 | 100% |

### 集成测试场景

```mermaid
graph TD
    Setup[测试环境准备] --> MockJD[模拟京东接口]
    MockJD --> CreateOrder[创建测试订单]
    CreateOrder --> RunTask[执行后台任务]
    
    RunTask --> Scenario1[场景1：订单已支付]
    RunTask --> Scenario2[场景2：订单未支付]
    RunTask --> Scenario3[场景3：订单过期]
    RunTask --> Scenario4[场景4：接口异常]
    
    Scenario1 --> ValidatePaid[验证支付状态更新]
    Scenario2 --> ValidateUnpaid[验证无状态变更]
    Scenario3 --> ValidateExpired[验证过期状态]
    Scenario4 --> ValidateError[验证异常处理]
    
    ValidatePaid --> CheckCard[验证卡密提取]
    CheckCard --> Cleanup[清理测试数据]
    ValidateUnpaid --> Cleanup
    ValidateExpired --> Cleanup
    ValidateError --> Cleanup
```

## 部署配置

### 配置参数设计

使用GoFrame的配置管理功能，在hack/config.yaml中添加相关配置：

| 配置项 | 默认值 | 说明 | GoFrame获取方式 |
|-------|--------|------|----------------|
| paymentCheck.interval | "0 */1* ** *" | 任务执行间隔(cron表达式) | g.Cfg().MustGet("paymentCheck.interval") |
| paymentCheck.batchSize | 50 | 单次处理订单数量 | g.Cfg().MustGetInt("paymentCheck.batchSize") |
| paymentCheck.timeout | 30 | 接口调用超时时间(秒) | g.Cfg().MustGetInt("paymentCheck.timeout") |
| paymentCheck.poolSize | 10 | 协程池大小 | g.Cfg().MustGetInt("paymentCheck.poolSize") |

### 环境依赖

基于现有GoFrame项目架构，无需额外依赖：

| 依赖项 | 版本要求 | 作用 | GoFrame支持 |
|-------|---------|------|------------|
| MySQL | 5.7+ | 数据存储 | gdb原生支持 |
| Redis | 6.0+ | 缓存支持(可选) | gcache/gredis支持 |
| 定时任务 | - | 任务调度 | gcron原生支持 |
| 京东API | - | 外部接口依赖 | 复用现有@originalJd服务 |
