kami_backend/.qoder/quests/order-processing-module.md

骆驼加油订单处理模块设计

模块概述

骆驼加油订单处理模块用于从骆驼加油平台获取订单并返回支付宝支付链接。该模块包含账号登录管理、订单下单、状态追踪和后台自动登录任务等功能。

业务流程

整体业务流程

sequenceDiagram
    participant User as 商户
    participant API as API接口
    participant Logic as 业务逻辑层
    participant Account as 账号管理
    participant CamelOil as 骆驼加油平台
    participant Pig as 接码平台
    participant DB as 数据库
    participant Cron as 定时任务

    User->>API: 提交下单请求
    API->>Logic: 处理订单请求
    Logic->>Account: 获取可用账号
    Account->>DB: 查询在线账号（已下单<10）
    
    alt 无可用在线账号
        Account-->>Logic: 无可用账号
        Logic-->>API: 返回系统繁忙
    else 有可用账号
        Account-->>Logic: 返回可用账号
        Logic->>CamelOil: 调用下单接口
        CamelOil-->>Logic: 返回支付宝链接
        Logic->>DB: 保存订单记录
        Logic->>DB: 账号使用次数+1
        Logic-->>API: 返回支付链接
        API-->>User: 返回结果
    end
    
    Note over Cron,CamelOil: 订单支付状态检测任务
    Cron->>DB: 查询待支付订单
    Cron->>CamelOil: 查询支付状态
    CamelOil-->>Cron: 返回支付状态
    alt 支付成功
        Cron->>DB: 更新订单状态为已支付
        Cron->>User: 回调商户接口
        Cron->>DB: 记录回调结果
        Cron->>DB: 账号已下单订单数+1
        alt 账号订单数达到10
            Cron->>DB: 更新账号状态为暂停
            Cron->>DB: 记录账号历史
        end
    end
    
    Note over Account,Pig: 后台登录任务（一次性接码）
    Account->>DB: 查询待登录账号
    Account->>Pig: 请求接码
    Pig-->>Account: 返回手机号
    Account->>CamelOil: 发送验证码
    Account->>Pig: 获取验证码
    Pig-->>Account: 返回验证码
    Account->>CamelOil: 登录
    alt 登录成功
        CamelOil-->>Account: 返回Token
        Account->>DB: 更新账号状态为在线
        Account->>DB: 记录手机号（不再重复使用）
    else 登录失败或掉线
        Account->>DB: 标记账号为失败
        Account->>DB: 不再重新登录此账号
    end

账号登录流程

stateDiagram-v2
    [*] --> 待登录
    待登录 --> 接码中: 获取手机号
    接码中 --> 发送验证码: 接码成功
    接码中 --> 登录失败: 接码失败
    发送验证码 --> 等待验证码: 发送成功
    等待验证码 --> 登录中: 获取验证码
    等待验证码 --> 登录失败: 验证码超时
    登录中 --> 在线: 登录成功
    登录中 --> 登录失败: 登录失败
    在线 --> 使用中: 开始下单
    使用中 --> 暂停: 已下单10个
    使用中 --> 已失效: 检测到掉线
    暂停 --> 在线: 订单完成后重置
    已失效 --> [*]: 不再重新登录
    登录失败 --> [*]: 不再重新登录

数据库设计

账号表（camel_oil_account）

字段名	类型	说明	索引
id	BIGINT	主键ID，自增	PRIMARY
account_id	VARCHAR(64)	账号唯一标识	UNIQUE
account_name	VARCHAR(128)	账号名称（备注）	-
phone	VARCHAR(20)	手机号（登录后记录，不可重复）	UNIQUE
token	TEXT	登录Token	-
status	TINYINT	状态：1待登录 2在线 3暂停 4已失效 5登录失败	INDEX
token_expire_at	DATETIME	Token过期时间	INDEX
last_login_at	DATETIME	最后登录时间	-
last_used_at	DATETIME	最后使用时间	-
daily_order_count	INT	当日已下单数量	-
daily_order_date	DATE	当日订单日期	INDEX
total_order_count	INT	累计下单数量	-
failure_reason	TEXT	失败原因	-
remark	TEXT	备注信息	-
created_at	DATETIME	创建时间	-
updated_at	DATETIME	更新时间	-
deleted_at	DATETIME	删除时间（软删除）	-

索引设计：

• PRIMARY KEY (id)
• UNIQUE INDEX uk_account_id (account_id)
• UNIQUE INDEX uk_phone (phone) - 手机号唯一，防止重复接码
• INDEX idx_status (status)
• INDEX idx_token_expire (token_expire_at)
• INDEX idx_daily_order (daily_order_date, daily_order_count) - 用于快速查找可用账号和日期检查

订单表（camel_oil_order）

字段名	类型	说明	索引
id	BIGINT	主键ID，自增	PRIMARY
order_no	VARCHAR(64)	系统订单号	UNIQUE
merchant_order_id	VARCHAR(128)	商户订单号	INDEX
account_id	VARCHAR(64)	使用的账号ID	INDEX
account_name	VARCHAR(128)	账号名称	-
platform_order_no	VARCHAR(128)	骆驼平台订单号	INDEX
amount	DECIMAL(10,2)	订单金额	-
alipay_url	TEXT	支付宝支付链接	-
status	TINYINT	状态：1待支付 2已支付 3支付超时 4下单失败	INDEX
pay_status	TINYINT	支付状态：0未支付 1已支付 2超时	INDEX
notify_url	VARCHAR(512)	回调地址	-
notify_status	TINYINT	回调状态：0未回调 1已回调 2回调失败	INDEX
notify_count	INT	回调次数	-
last_check_at	DATETIME	最后检测支付时间	-
paid_at	DATETIME	支付完成时间	-
attach	TEXT	附加信息	-
failure_reason	TEXT	失败原因	-
created_at	DATETIME	创建时间	INDEX
updated_at	DATETIME	更新时间	-
deleted_at	DATETIME	删除时间（软删除）	-

索引设计：

• PRIMARY KEY (id)
• UNIQUE INDEX uk_order_no (order_no)
• INDEX idx_merchant_order_id (merchant_order_id)
• INDEX idx_account_id (account_id) - 用于查询账号历史订单
• INDEX idx_platform_order_no (platform_order_no)
• INDEX idx_status (status)
• INDEX idx_pay_status (pay_status) - 用于定时任务查询待支付订单
• INDEX idx_notify_status (notify_status)
• INDEX idx_created_at (created_at)
• COMPOSITE INDEX idx_account_status (account_id, status) - 优化账号订单查询

账号历史表（camel_oil_account_history）

字段名	类型	说明	索引
id	BIGINT	主键ID，自增	PRIMARY
account_id	VARCHAR(64)	账号ID	INDEX
change_type	VARCHAR(32)	变更类型：create/login/logout/expire/check_online/check_offline/login_fail	-
status_before	TINYINT	变更前状态	-
status_after	TINYINT	变更后状态	-
failure_count	INT	失败次数	-
remark	TEXT	备注	-
created_at	DATETIME	创建时间	INDEX

索引设计：

• PRIMARY KEY (id)
• INDEX idx_account_id (account_id)
• INDEX idx_created_at (created_at)

订单历史表（camel_oil_order_history）

字段名	类型	说明	索引
id	BIGINT	主键ID，自增	PRIMARY
order_no	VARCHAR(64)	订单号	INDEX
change_type	VARCHAR(32)	变更类型：create/submit/success/fail/callback	-
account_id	VARCHAR(64)	关联账号ID	-
account_name	VARCHAR(128)	账号名称	-
raw_data	TEXT	原始响应数据	-
remark	TEXT	备注	-
created_at	DATETIME	创建时间	INDEX

索引设计：

• PRIMARY KEY (id)
• INDEX idx_order_no (order_no)
• INDEX idx_created_at (created_at)

模块结构

API层

位置：api/camel_oil/v1/

需要定义的请求结构体：

接口	路径	方法	说明
SubmitOrderReq	/camelOil/order/submit	POST	提交订单
ListOrderReq	/camelOil/order/list	GET	订单列表
OrderDetailReq	/camelOil/order/detail	GET	订单详情
OrderHistoryReq	/camelOil/order/history	GET	订单历史记录
AccountOrderListReq	/camelOil/order/accountOrders	GET	查询账号绑定的历史订单
CreateAccountReq	/camelOil/account/create	POST	创建账号
ListAccountReq	/camelOil/account/list	GET	账号列表
UpdateAccountReq	/camelOil/account/update	POST	更新账号
DeleteAccountReq	/camelOil/account/delete	POST	删除账号
CheckAccountReq	/camelOil/account/check	POST	检测账号状态
AccountHistoryReq	/camelOil/account/history	GET	账号历史记录
AccountStatisticsReq	/camelOil/account/statistics	GET	账号统计信息

Controller层

位置：internal/controller/camel_oil/

通过 gf gen ctrl 生成Controller文件，主要包含：

• 订单控制器：处理订单相关请求
• 账号控制器：处理账号管理请求

Logic层

位置：internal/logic/camel_oil/

业务逻辑文件规划：

文件名	说明
index.go	服务注册和结构体定义
account.go	账号管理逻辑（创建、查询、更新、删除）
account_login.go	账号登录逻辑
account_rotation.go	账号轮询策略（轮流选择账号）
account_capacity.go	可用订单容量统计和检测
account_history.go	账号历史记录
account_statistics.go	账号统计信息
order.go	订单创建和查询逻辑
order_submit.go	订单提交到骆驼平台
order_query.go	查询订单支付状态
order_account.go	查询账号关联订单
order_history.go	订单历史记录
order_callback.go	订单回调逻辑

Service层

位置：internal/service/

通过 gf gen service 生成Service接口文件

DAO层

位置：internal/dao/

通过 gf gen dao 生成DAO文件

Integration层

位置：utility/integration/camel_oil/

扩展现有的骆驼加油平台集成客户端：

方法	说明
SendCaptcha	发送验证码（已有）
LoginWithCaptcha	验证码登录（已有）
SubmitOrder	提交订单，返回支付宝链接
QueryOrderPayStatus	查询订单支付状态
CheckTokenValid	检测Token有效性

接码平台集成客户端：

位置：utility/integration/pig/

方法	说明
GetPhone	获取手机号
GetCode	获取验证码
ReleasePhone	释放手机号

核心业务逻辑

账号管理

账号创建

• 生成唯一的账号ID
• 初始状态为"待登录"
• 记录创建历史

账号登录（后台任务）

登录策略：

1. 查询状态为"待登录"的账号（不再重新登录已失效账号）
2. 调用接码平台获取手机号
3. 检查手机号是否已被使用（查询数据库phone字段）
4. 调用骆驼平台发送验证码
5. 等待3-5秒
6. 从接码平台获取验证码
7. 调用骆驼平台登录接口
8. 保存Token、过期时间和手机号
9. 更新账号状态为"在线"
10. 记录登录历史

失败处理：

• 任何失败（接码失败、登录失败、掉线）都标记为"已失效"
• 不再重新登录此账号
• 记录详细失败原因
• 释放接码平台资源

手机号防重复机制：

• 登录成功后将手机号存入数据库
• phone字段设置唯一索引
• 后续登录前检查手机号是否已存在
• 如已存在则释放手机号并重新获取

账号轮询策略

账号使用规则:

1. 每个账号每日最多下10个订单
2. 每日首次使用账号时,重置daily_order_count为0,更新daily_order_date为当日
3. 每次下单成功后,daily_order_count加1
4. 当daily_order_count达到10时,账号状态更新为"暂停"
5. 次日凌晨,定时任务检查所有暂停账号的daily_order_date
6. 如果暂停账号的daily_order_date为昨日,重置daily_order_count为0,更新daily_order_date为今日,恢复为"在线"
7. 如果暂停账号的daily_order_date为昨日且daily_order_count < 10,说明账号失效,标记为"已失效"

账号选择策略(轮询机制):

1. 查询所有状态为"在线"的账号(daily_order_count < 10)
2. 检查每个账号的daily_order_date,如果不是今日则重置计数
3. 按last_used_at升序排序(最久未使用的优先)
4. 选择排序后的第一个账号(确保轮流使用,而不是一个账号用到10单)
5. 下单成功后,更新账号的daily_order_count和last_used_at
6. 如果账号在下单过程中检测到掉线,立即标记为"已失效",选择下一个账号

可用订单容量检测:

1. 每次下单前,统计当日可用订单总容量
2. 可用订单容量 = 所有在线账号的剩余可下单数之和
3. 计算公式: SUM(10 - daily_order_count) WHERE status=在线 AND daily_order_date=今日
4. 如果可用订单容量 < 50,触发新账号登录任务
5. 新账号登录成功后,可用容量增加10个订单

后台账号池维护:

1. 系统启动时统计在线账号数量和可用订单容量
2. 定时任务检测,确保可用订单容量充足(>=50)
3. 可用订单容量不足50时,触发登录任务补充账号
4. 优先登录待登录状态的账号
5. 每日凌晨执行账号状态重置任务
6. 记录账号池状态日志和容量变化

账号状态枚举

状态值	状态名	说明
1	待登录	新创建的账号
2	在线	登录成功且可用（daily_order_count < 10）
3	暂停	当日已下单10个，等待次日重置
4	已失效	掉线、失败或单日下单不足10个
5	登录失败	登录过程失败

账号变更类型枚举

变更类型	说明
create	创建账号
login	登录成功
offline	检测到掉线
login_fail	登录失败
pause	订单数达到10，暂停使用
resume	次日重置，恢复使用
invalidate	单日下单不足10个，账号失效
order_bind	绑定订单
order_complete	订单完成
update	更新账号信息
delete	删除账号

订单处理

订单提交

订单提交流程:

1. 接收商户请求(金额、回调地址、附加信息)
2. 生成系统订单号
3. 统计当日可用订单容量(所有在线账号剩余可下单数之和)
4. 如果可用订单容量 < 50,触发异步登录任务补充账号
5. 查询所有可用账号(状态=在线 且 daily_order_count < 10)
6. 检查每个账号daily_order_date,如非今日则重置计数和日期
7. 按last_used_at升序排序,选择最久未使用的账号(轮询)
8. 调用骆驼平台下单接口,获取支付宝链接
9. 保存订单信息(状态=待支付)
10. 更新账号的daily_order_count(+1)、daily_order_date(今日)和last_used_at
11. 检查账号daily_order_count是否达到10
12. 如达到10,更新账号状态为"暂停",记录历史
13. 记录订单历史
14. 返回支付宝支付链接

下单失败处理：

• 检测到账号掉线：标记账号为"已失效"，重新选择账号
• 平台接口异常：记录错误，订单状态更新为"下单失败"
• 无可用账号：返回系统繁忙

账号选择策略(轮询机制):

• 状态必须为"在线"
• 检查daily_order_date,如非今日则先重置计数
• daily_order_count必须小于10
• 按last_used_at升序排序,选择最久未使用的账号
• 每次下单只使用一个账号,确保账号轮流使用
• 不会出现一个账号连续使用到10单的情况

可用订单容量计算:

• 实时统计所有在线账号的剩余订单容量
• 容量计算: SUM(10 - daily_order_count) WHERE status=在线
• 容量阈值: 50个订单
• 低于阈值时自动触发账号补充

订单支付状态检测

检测任务流程：

1. 定时任务每分钟执行一次
2. 查询状态为"待支付"的订单
3. 过滤出创建时间在24小时内的订单
4. 批量调用骆驼平台接口查询支付状态
5. 根据查询结果更新订单状态
6. 记录订单变更历史

支付成功处理流程:

1. 更新订单状态为"已支付"
2. 记录支付时间(paid_at)
3. 更新账号的total_order_count(+1)
4. 记录账号历史
5. 触发异步回调商户

支付超时处理:

1. 订单创建超过24小时仍未支付
2. 更新订单状态为"支付超时"
3. 记录订单历史

订单状态枚举

状态值	状态名	说明
1	待支付	已获取支付链接，等待支付
2	已支付	用户支付成功
3	支付超时	超过有效期未支付
4	下单失败	下单失败

订单变更类型枚举

变更类型	说明
create	创建订单
submit	提交到骆驼平台
get_pay_url	获取支付链接
check_pay	检测支付状态
paid	支付成功
timeout	支付超时
fail	下单失败
callback_success	回调商户成功
callback_fail	回调商户失败

订单回调

回调策略：

• 支付成功后异步回调商户接口
• 回调失败重试3次（间隔1分钟、5分钟、10分钟）
• 记录每次回调结果和响应数据
• 更新回调状态和回调次数
• 3次失败后不再重试，人工介入

定时任务设计

账号登录任务

位置：utility/cron/camel_oil_login.go

执行频率：每5分钟

任务流程:

1. 统计当日可用订单容量(所有在线账号剩余订单数之和)
2. 如果可用订单容量>=50,跳过本次执行
3. 计算需要登录的账号数量: CEIL((50 - 当前容量) / 10)
4. 查询待登录账号(状态=待登录)
5. 限制并发数量(最多3个同时登录)
6. 逐个执行登录流程
7. 登录成功后再次检查可用订单容量
8. 达到50个容量后停止登录
9. 记录执行结果、账号池状态和容量变化

注意事项：

• 不再重新登录"已失效"或"登录失败"的账号
• 手机号必须唯一，不能重复使用
• 任何失败都标记为"已失效"
• 确保始终维持足够的可用订单容量(>=50)

订单支付状态检测任务

位置：utility/cron/camel_oil_order_check.go

执行频率：每1分钟

任务流程：

1. 查询状态为"待支付"的订单
2. 过滤创建时间在24小时内的订单
3. 批量调用骆驼平台接口查询支付状态
4. 处理支付成功的订单:
   • 更新订单状态为"已支付"
   • 更新账号total_order_count
   • 触发商户回调
5. 处理超时订单(创建超过24小时):
   • 更新订单状态为"支付超时"
6. 记录所有变更历史
7. 统计执行结果

并发控制：

• 使用分布式锁防止重复执行
• 限制单次处理订单数量（如50个）
• 批量查询，减少API调用

账号池维护任务

位置:utility/cron/camel_oil_pool.go

执行频率:每10分钟

任务流程:

1. 统计当前账号池状态
2. 统计各状态账号数量
3. 检查在线账号是否足够(>=5)
4. 如不足,触发登录任务补充
5. 记录账号池状态日志

账号日重置任务

位置:utility/cron/camel_oil_daily_reset.go

执行频率:每日凌晨00:05

任务流程:

1. 查询所有状态为"暂停"的账号
2. 检查账号的daily_order_date和daily_order_count
3. 如果daily_order_date为昨日:
   • 如果daily_order_count >= 10,说明正常完成,重置daily_order_count为0,更新daily_order_date为今日,状态改为"在线"
   • 如果daily_order_count < 10,说明账号失效,标记状态为"已失效"
4. 记录账号状态变更历史
5. 统计重置结果

任务注册

在 utility/cron/cron.go 中注册任务：

注册账号登录任务（每5分钟）：

• 检查在线账号数量
• 不足5个时自动登录补充
• 维持账号池稳定

注册订单检测任务（每1分钟）：

• 查询待支付订单
• 检测支付状态
• 处理支付成功和超时
• 触发商户回调

注册账号池维护任务(每10分钟):

• 统计账号池状态
• 生成监控数据

注册账号日重置任务(每日凌晨00:05):

• 重置已完成的账号
• 淘汰失效账号
• 记录状态变更

错误处理

错误码定义

位置：internal/consts/camel_oil.go

错误码	说明
ErrNoAvailableAccount	无可用账号
ErrAccountNotFound	账号不存在
ErrAccountLoginFailed	账号登录失败
ErrAccountOffline	账号掉线
ErrAccountReachLimit	账号订单数已达上限
ErrOrderSubmitFailed	订单提交失败
ErrOrderNotFound	订单不存在
ErrOrderPayTimeout	订单支付超时
ErrPhoneGetFailed	获取手机号失败
ErrPhoneDuplicate	手机号重复
ErrCodeGetFailed	获取验证码失败
ErrCallbackFailed	回调商户失败

异常处理策略

账号登录异常：

• 接码失败：释放资源，记录失败次数
• 验证码超时：释放手机号，记录失败
• 登录接口异常：记录详细错误信息

订单提交异常：

• 无可用账号：返回系统繁忙提示
• 平台接口异常：记录错误，更新订单状态
• 网络超时：记录异常，支持重试

分布式部署支持

任务分布式锁

使用Redis分布式锁确保定时任务在多实例环境下只执行一次：

• 登录任务锁：camel_oil:login:lock（锁定5分钟）
• 检测任务锁：camel_oil:check:lock（锁定30分钟）

账号分配策略

使用数据库行锁或Redis锁确保同一时刻一个账号只能被一个实例使用：

• 订单提交时锁定账号
• 提交完成释放锁
• 支持超时自动释放

监控指标

账号监控

• 在线账号数量(实时)
• 暂停账号数量(实时)
• 已失效账号数量(累计)
• 待登录账号数量(实时)
• 可用订单容量(实时) - 核心指标
• 账号池健康度(可用容量/阈值)
• 平均登录成功率
• 账号平均使用次数
• 手机号使用情况
• 每日订单完成情况
• 账号失效率
• 账号轮询均衡度(每个账号使用次数方差)

订单监控

• 订单提交成功率
• 订单下单平均耗时
• 支付链接获取成功率
• 回调成功率
• 每小时订单处理量
• 当日订单总量

数据安全

敏感信息处理

• Token加密存储
• 手机号脱敏显示
• 日志中屏蔽敏感字段
• API返回数据脱敏

访问控制

• 账号管理接口需要管理员权限
• 订单查询支持按商户隔离
• 操作日志完整记录

依赖关系

内部依赖

• 依赖现有的 utility/config 配置模块
• 依赖现有的 utility/cron 定时任务框架
• 依赖现有的 utility/pool 线程池
• 复用现有的认证中间件

外部依赖

• 骆驼加油平台API
• 接码平台API
• Redis缓存
• MySQL数据库

三方库需求

GoFrame框架内置依赖已满足需求，无需新增三方库

接口设计

订单提交接口

请求参数：

• amount：订单金额（必填）
• merchantOrderId：商户订单号（必填）
• notifyUrl：回调地址（必填）
• attach：附加信息（选填）

响应数据：

• orderNo：系统订单号
• alipayUrl：支付宝支付链接
• platformOrderNo：骆驼平台订单号

订单列表接口

请求参数：

• merchantOrderId：商户订单号（选填）
• accountId：账号ID（选填）
• status：订单状态（选填）
• payStatus：支付状态（选填）
• dateRange：时间范围（选填）
• current：当前页（必填）
• pageSize：每页大小（必填）

响应数据：

• 分页列表数据
• 每条包含订单详细信息

账号订单列表接口

请求参数：

• accountId：账号ID（必填）
• status：订单状态（选填）
• payStatus：支付状态（选填）
• dateRange：时间范围（选填）
• current：当前页（必填）
• pageSize：每页大小（必填）

响应数据：

• 账号基本信息
• 订单统计（总数、已支付、待支付）
• 订单分页列表
• 每条包含订单详细信息和时间线

账号管理接口

创建账号请求：

• accountName：账号名称（必填）
• remark：备注（选填）

账号列表请求：

• status：状态筛选（选填）
• keyword：关键词搜索（选填）
• current：当前页（必填）
• pageSize：每页大小（必填）

更新账号请求：

• accountId：账号ID（必填）
• accountName：账号名称（选填）
• status：状态（选填，仅支持手动启用/禁用）
• remark：备注（选填）

账号统计接口：

• accountId：账号ID（必填）

响应数据:

• 账号基本信息
• 订单统计(总数、已支付数、待支付数、超时数)
• 使用情况(当日下单数、累计下单数)
• 状态信息(在线时长、最后使用时间)
• 近期订单趋势

开发顺序

第一阶段：数据库和基础结构

1. 创建数据库表结构
2. 执行 gf gen dao 生成DAO文件
3. 定义常量和枚举（consts/camel_oil.go）
4. 创建Service接口定义

第二阶段：Integration层

1. 完善骆驼加油平台客户端
2. 实现接码平台客户端
3. 编写集成测试

第三阶段：Logic层

1. 实现账号管理逻辑
2. 实现账号登录逻辑
3. 实现订单处理逻辑
4. 实现历史记录逻辑

第四阶段：API和Controller层

1. 定义API请求结构体
2. 执行 gf gen service 生成Service
3. 执行 gf gen ctrl 生成Controller
4. 实现Controller业务绑定

第五阶段：定时任务

1. 实现账号自动登录任务
2. 实现账号状态检测任务
3. 注册定时任务

第六阶段：测试和优化

1. 单元测试
2. 集成测试
3. 性能优化
4. 监控接入