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

## 🎯 模块概述

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

## ✅ 已完成功能

### 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` 中添加路由绑定

## 🔧 核心业务逻辑

### 账号轮询策略

```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)
```

### 可用订单容量管理

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

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

### 账号日重置逻辑

```go
// 每日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. 数据库初始化

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

### 2. 生成DAO

```bash
gf gen dao
```

### 3. 启动服务

```bash
go run main.go
```

### 4. API调用示例

**提交订单**：
```bash
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": "附加信息"
  }'
```

**查询订单列表**：
```bash
curl http://localhost:8000/api/camelOil/order/list?current=1&pageSize=10
```

**创建账号**：
```bash
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  
**开发状态**：✅ 核心功能完成，编译通过，可部署测试
