# 骆驼加油订单处理模块 - 开发进度

## 已完成的工作

### 1. 数据库设计 (100%)
- ✅ SQL文件已创建: `/Users/sunxiaolong/Documents/kami/kami_backend/sql/camel_oil_tables.sql`
- ✅ 包含4张表:
  - camel_oil_account - 账号表
  - camel_oil_order - 订单表  
  - camel_oil_account_history - 账号历史表
  - camel_oil_order_history - 订单历史表
- ✅ 索引设计完整，支持高性能查询
- ⚠️ **需要注意**: 实际生成的表名有`v_1_`前缀

### 2. 常量定义 (100%)
- ✅ 文件路径: `/Users/sunxiaolong/Documents/kami/kami_backend/internal/consts/camel_oil.go`
- ✅ 账号状态枚举已定义
- ✅ 订单状态枚举已定义
- ✅ 支付状态枚举已定义
- ✅ 回调状态枚举已定义

### 3. API接口定义 (100%)
- ✅ 订单API: `/Users/sunxiaolong/Documents/kami/kami_backend/api/camel_oil/v1/order.go`
- ✅ 账号API: `/Users/sunxiaolong/Documents/kami/kami_backend/api/camel_oil/v1/account.go`
- ✅ 包含所有必要的请求和响应结构

### 4. DAO层 (100%)
- ✅ 已执行`gf gen dao`命令
- ✅ 生成的DAO对象:
  - dao.V1CamelOilAccount
  - dao.V1CamelOilOrder
  - dao.V1CamelOilAccountHistory
  - dao.V1CamelOilOrderHistory
- ✅ Entity结构已生成

### 5. Logic层 (60%)

#### 已完成的Logic文件:
1. ✅ `index.go` - 服务注册 (100%)
2. ✅ `account.go` - 账号CRUD操作 (100%)
3. ✅ `account_capacity.go` - 可用订单容量管理 (100%)
4. ✅ `account_rotation.go` - 账号轮询策略 (100%)
5. ✅ `order.go` - 订单基础操作 (100%)
6. ✅ `order_submit.go` - 订单提交逻辑 (80% - TODO: 集成真实API)

#### 待创建的Logic文件:
- ❌ `account_login.go` - 账号登录逻辑
- ❌ `order_query.go` - 订单支付状态查询
- ❌ `order_callback.go` - 商户回调逻辑

### 6. Service层 (已生成接口)
- ✅ 已执行`gf gen service`命令
- ✅ 文件路径: `/Users/sunxiaolong/Documents/kami/kami_backend/internal/service/camel_oil.go`
- ⚠️ 当前为空接口，需要在Logic层方法完成后重新生成

### 7. Controller层 (0%)
- ❌ 尚未执行`gf gen ctrl`命令
- ❌ 需要在Service层完成后执行

### 8. 定时任务 (0%)
- ❌ 账号登录任务 - `utility/cron/camel_oil_login.go`
- ❌ 订单支付状态检测任务 - `utility/cron/camel_oil_order_check.go`
- ❌ 账号日重置任务 - `utility/cron/camel_oil_daily_reset.go`
- ❌ 账号池维护任务 - `utility/cron/camel_oil_pool.go`

### 9. Integration层 (0%)
- ❌ 需要扩展现有的骆驼加油平台API客户端
- ❌ 需要实现订单提交、支付状态查询等方法
- ❌ 接码平台集成已存在,需要在登录逻辑中使用

## 核心设计要点

### 账号轮询机制
- ✅ 按`last_used_at`升序排序
- ✅ 选择最久未使用的在线账号
- ✅ 每次下单更新`last_used_at`
- ✅ 真正实现轮询,不会一个账号连续使用

### 可用订单容量管理
- ✅ 公式: `SUM(10 - daily_order_count) WHERE status=在线`
- ✅ 阈值: 50个订单
- ✅ 容量不足时触发异步登录任务

### 按日计数机制
- ✅ `daily_order_count` - 当日订单计数
- ✅ `daily_order_date` - 订单日期
- ✅ 跨日自动重置逻辑
- ✅ 单日10单限制

### 账号状态流转
- ✅ 待登录(0) → 登录中(1) → 在线(2) → 已暂停(3) → 已失效(4)
- ✅ 失效条件: 单日下单不足10个
- ✅ 不重复登录已失效账号

## 待办事项清单

### 高优先级
1. **完善订单提交逻辑** (order_submit.go)
   - TODO: 集成真实的骆驼加油API
   - TODO: 处理下单失败和账号掉线的情况

2. **创建账号登录逻辑** (account_login.go)
   - 实现完整的登录流程
   - 集成接码平台API
   - 手机号去重检查
   - 登录失败处理

3. **创建订单查询逻辑** (order_query.go)
   - 查询支付状态
   - 更新订单信息
   - 触发回调

4. **创建商户回调逻辑** (order_callback.go)
   - 支持3次重试
   - 记录回调结果

5. **创建定时任务**
   - 账号登录任务(每5分钟)
   - 订单检测任务(每1分钟)
   - 日重置任务(每日00:05)
   - 账号池维护任务(每10分钟)

### 中优先级
6. **重新生成Service接口**
   - 在Logic层方法完善后执行`gf gen service`

7. **生成Controller**
   - 执行`gf gen ctrl`生成Controller

8. **扩展Integration层**
   - 完善骆驼加油API客户端
   - 实现所需的API方法

### 低优先级
9. **单元测试**
   - Logic层测试
   - Integration层测试

10. **文档完善**
    - API文档
    - 部署文档

## 技术债务

### 类型不匹配问题
- ⚠️ `account_id`字段在SQL中定义为`varchar(64)`,但在账号表中`id`是`bigint`
- 解决方案:
  1. 在订单中存储账号ID时转换为字符串: `fmt.Sprintf("%d", account.Id)`
  2. 后续如需关联查询,需要进行类型转换

### 表名前缀问题
- ⚠️ 实际表名有`v_1_`前缀,导致entity和dao也有前缀
- 影响: 所有DAO访问都需要使用`dao.V1Camel Oil*`格式
- 状态: 已在代码中适配

## 下一步行动

### 立即执行
1. 创建 `account_login.go` - 实现账号登录逻辑
2. 创建 `order_query.go` - 实现订单状态查询
3. 创建 `order_callback.go` - 实现商户回调
4. 完善 `order_submit.go` - 集成真实API

### 随后执行
5. 创建定时任务文件
6. 扩展Integration层
7. 重新生成Service和Controller
8. 编写单元测试

## 风险和注意事项

1. **账号安全**
   - 手机号必须唯一,防止重复接码
   - Token需要安全存储
   - 登录凭证加密

2. **并发控制**
   - 账号选择需要使用分布式锁
   - 防止同一账号被多次分配

3. **错误处理**
   - 所有外部API调用需要完善的错误处理
   - 失败重试机制
   - 降级策略

4. **性能优化**
   - 索引优化
   - 批量操作
   - 缓存策略

5. **监控告警**
   - 账号池状态监控
   - 订单处理监控
   - API调用监控

## 开发建议

### 编码规范
- 多写注释,少生成文档
- 参考现有模块的代码风格
- 保持代码简洁清晰

### 测试策略
- 先完成核心逻辑
- 后补充单元测试
- 集成测试覆盖关键流程

### 部署注意
- 支持分布式部署
- 使用Redis分布式锁
- 数据库连接池配置

---

**最后更新时间**: 2025-11-18
**当前进度**: 约40%完成
**预计完成时间**: 需要继续开发剩余60%的功能
