kami_backend/docs/camel_oil_development_summary.md

骆驼加油订单处理模块开发总结

🎯 模块概述

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

✅ 已完成功能

1. 数据库设计 ✓

• ✅ 4张核心表：账号表、订单表、账号历史表、订单历史表
• ✅ 支持分布式部署的索引设计
• ✅ 账号轮询策略的索引优化（idx_status_daily）

2. API接口层 ✓

订单相关接口：

• ✅ POST /camelOil/order/submit - 提交订单
• ✅ GET /camelOil/order/list - 订单列表
• ✅ GET /camelOil/order/detail - 订单详情
• ✅ GET /camelOil/order/history - 订单历史
• ✅ GET /camelOil/order/accountOrders - 账号订单列表
• ✅ POST /camelOil/order/callback - 手动触发回调

账号管理接口：

• ✅ POST /camelOil/account/create - 创建账号
• ✅ GET /camelOil/account/list - 账号列表
• ✅ PUT /camelOil/account/update - 更新账号
• ✅ DELETE /camelOil/account/delete - 删除账号
• ✅ POST /camelOil/account/check - 检测账号状态
• ✅ GET /camelOil/account/history - 账号历史
• ✅ GET /camelOil/account/statistics - 账号统计

3. Logic层 ✓

账号管理：

• ✅ account.go - 账号CRUD基础操作
• ✅ account_login.go - 账号登录逻辑（假数据）
• ✅ account_rotation.go - 账号轮询策略
• ✅ account_capacity.go - 可用订单容量管理
• ✅ account_history.go - 账号历史记录查询
• ✅ account_statistics.go - 账号统计信息

订单管理：

• ✅ order.go - 订单提交核心逻辑
• ✅ order_query.go - 订单查询
• ✅ order_history.go - 订单历史和账号订单列表
• ✅ order_callback.go - 订单回调逻辑

4. 定时任务 ✓

• ✅ 账号登录任务（每5分钟执行）
• ✅ 账号状态检测任务（每30分钟执行）
• ✅ 订单支付状态检测任务（每1分钟执行）
• ✅ 账号日重置任务（每日00:05执行）
• ✅ 已在 utility/cron/cron.go 中注册

5. Controller层 ✓

• ✅ 通过 gf gen ctrl 生成所有Controller文件
• ✅ Controller方法调用Service接口

6. 路由注册 ✓

• ✅ 在 internal/cmd/cmd.go 中添加路由绑定

🔧 核心业务逻辑

账号轮询策略

// 轮询条件：
// 1. status = 2 (在线)
// 2. daily_order_count < 10 (当日未达10单)
// 3. daily_order_date = 今日
// 排序：last_used_at ASC (最早使用的优先，实现轮询)

account := dao.V1CamelOilAccount.Ctx(ctx).
    Where("status", consts.CamelOilAccountStatusOnline).
    Where("daily_order_count < ?", 10).
    Where("daily_order_date", gtime.Now().Format("Y-m-d")).
    OrderAsc("last_used_at").
    Limit(1).
    Scan(&account)

可用订单容量管理

// 容量计算公式
可用容量 = SELECT SUM(10 - daily_order_count)
          FROM v1camel_oil_account
          WHERE status = 2
            AND daily_order_date = CURDATE()

// 容量阈值检测
IF 可用容量 < 50 THEN
    触发账号登录任务
END IF

账号日重置逻辑

// 每日00:05执行
1. 查询所有暂停账号 (status=3)
2. 检查daily_order_date是否为昨日
3. 如果daily_order_count >= 10:
   - 重置为在线状态
   - 重置daily_order_count为0
   - 更新daily_order_date为今日
4. 如果daily_order_count < 10:
   - 标记为失效状态
   - 不再重新登录

📊 数据库表结构

v1camel_oil_account (账号表)

字段名	类型	说明
id	BIGINT	主键
account_id	VARCHAR(64)	账号唯一标识
phone	VARCHAR(20)	手机号（唯一，防重复）
token	TEXT	登录Token
status	TINYINT	状态：0待登录 1登录中 2在线 3暂停 4已失效
daily_order_count	INT	当日已下单数量
daily_order_date	DATE	当日订单日期
last_used_at	DATETIME	最后使用时间（轮询关键字段）

关键索引：

• idx_status_daily (status, daily_order_date, daily_order_count, last_used_at) - 支持高效轮询

v1camel_oil_order (订单表)

字段名	类型	说明
id	BIGINT	主键
order_no	VARCHAR(64)	系统订单号（唯一）
account_id	VARCHAR(64)	使用的账号ID
amount	DECIMAL(10,2)	订单金额
alipay_url	TEXT	支付宝支付链接
status	TINYINT	订单状态
pay_status	TINYINT	支付状态
notify_status	TINYINT	回调状态

✅ 模块状态

• 开发进度: 100%
• 编译状态: ✅ 无错误 (已验证)
• 代码质量: ✅ 已优化
• 待实现: Integration层(用户明确暂不实现)

⚠️ 已修复问题

编译错误 (已修复 ✅)

1. account_statistics.go - 辅助函数重复定义 ✅ 已删除重复定义
2. order_history.go - 辅助函数重复定义 ✅ 已删除重复定义
3. order_history.go - OrderStats结构体不匹配 ✅ 已修复类型匹配
4. account_login.go - 字段名不匹配和方法签名错误 ✅ 已全部修复
5. account_statistics.go / order_history.go - 缺少fmt导入和调用不存在的函数 ✅ 已修复

修复说明:

• 辅助函数统一在 order_query.go 中定义(maskPhone, getOrderStatusText, getPayStatusText, getNotifyStatusText, getAccountStatusText)
• account_statistics.go 和 order_history.go 调用 order_query.go 中的函数
• 修复了 getOrderStats 返回类型,与API定义的OrderStats结构体匹配
• 重新生成DAO，使用正确的字段名(Phone、Token、FailureReason)
• 修复account_login.go中的RecordAccountHistory方法调用，使用account.go中的定义
• 修复所有辅助函数调用，使用正确的函数名
• 添加缺少的fmt导入

🚀 使用说明

1. 数据库初始化

# 执行SQL文件
mysql -u your_user -p your_database < sql/camel_oil_tables.sql

2. 生成DAO

gf gen dao

3. 启动服务

go run main.go

4. API调用示例

提交订单：

curl -X POST http://localhost:8000/api/camelOil/order/submit \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "merchantOrderId": "M202401010001",
    "notifyUrl": "https://merchant.com/callback",
    "attach": "附加信息"
  }'

查询订单列表：

curl http://localhost:8000/api/camelOil/order/list?current=1&pageSize=10

创建账号：

curl -X POST http://localhost:8000/api/camelOil/account/create \
  -H "Content-Type: application/json" \
  -d '{
    "accountName": "测试账号1",
    "remark": "用于测试"
  }'

📈 监控指标

账号监控

• 在线账号数量
• 可用订单容量（核心指标，阈值：50）
• 账号池健康度
• 账号轮询均衡度

订单监控

• 订单提交成功率
• 支付链接获取成功率
• 回调成功率
• 每小时订单处理量

🔒 数据安全

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

📝 后续优化建议

代码质量

• 添加单元测试
• 补充详细的API文档
• Token加密存储
• 日志脱敏处理
• 完善错误处理

Integration层(用户明确暂不实现)

• ❌ 骆驼加油平台API对接
• ❌ 接码平台API对接

性能优化

• 分布式锁优化
• 批量查询优化
• 缓存策略

🏗️ 项目结构

kami_backend/
├── api/camel_oil/v1/          # API接口定义
│   ├── account.go              # 账号管理接口
│   ├── order.go                # 订单接口
│   └── camel_oil.go            # 通用定义
├── internal/
│   ├── controller/camel_oil/   # Controller层
│   ├── logic/camel_oil/        # Logic层（核心业务）
│   │   ├── account.go
│   │   ├── account_login.go
│   │   ├── account_rotation.go
│   │   ├── account_capacity.go
│   │   ├── account_history.go
│   │   ├── account_statistics.go
│   │   ├── order.go
│   │   ├── order_query.go
│   │   ├── order_history.go
│   │   └── order_callback.go
│   ├── cron/                   # 定时任务
│   │   └── camel_oil_tasks.go
│   ├── service/                # Service接口
│   │   └── camel_oil.go
│   ├── dao/                    # DAO层（自动生成）
│   ├── model/                  # Model层（自动生成）
│   ├── consts/                 # 常量定义
│   │   └── camel_oil.go
│   └── cmd/cmd.go              # 路由注册
├── utility/
│   └── cron/cron.go            # 定时任务注册
└── sql/
    └── camel_oil_tables.sql    # 数据库表结构

📖 技术栈

• 框架：GoFrame v2
• 数据库：MySQL 8.0+
• 缓存：Redis（分布式锁）
• 定时任务：gcron
• HTTP客户端：gclient

🙏 开发说明

1. 当前状态：核心功能已100%完成，使用假数据模拟,编译无错误
2. Integration层：用户明确暂不实现，使用假数据完成开发流程
3. 生产环境: 建议先在测试环境验证后再部署
4. 性能考虑：已支持分布式部署，索引设计合理
5. 扩展性：接口预留，Integration层可随时补充

📞 后续支持

如需完成Integration层对接或其他优化，可参考以下文件：

• utility/integration/camel_oil/ - 骆驼加油平台对接（待实现）
• utility/integration/pig/ - 接码平台对接（待实现）

---

开发时间：2025年1月18日
当前版本：v1.0.0
开发状态：✅ 核心功能完成，编译通过，可部署测试