# 骆驼加油数据库模式

<cite>
**本文档中引用的文件**   
- [camel_oil_tables.sql](file://sql/camel_oil_tables.sql)
- [v_1_camel_oil_account.go](file://internal/model/entity/v_1_camel_oil_account.go)
- [v_1_camel_oil_order.go](file://internal/model/entity/v_1_camel_oil_order.go)
- [v_1_camel_oil_account_history.go](file://internal/model/entity/v_1_camel_oil_account_history.go)
- [v_1_camel_oil_order_history.go](file://internal/model/entity/v_1_camel_oil_order_history.go)
- [camel_oil_v1_submit_order.go](file://internal/controller/camel_oil/camel_oil_v1_submit_order.go)
- [camel_oil_v1_order_callback.go](file://internal/controller/camel_oil/camel_oil_v1_order_callback.go)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介
本文档详细描述了骆驼加油平台的数据库模式，包括账号管理、订单处理和历史记录等核心功能。该系统主要用于管理骆驼加油平台的账号登录状态、订单生命周期以及相关的历史变更记录。

## 项目结构
骆驼加油模块的代码结构遵循分层设计原则，主要包含API接口、控制器、数据访问对象（DAO）和实体模型等组件。数据库表结构定义在SQL文件中，而对应的Go语言模型则分布在model目录下。

```mermaid
graph TB
subgraph "API层"
API[api/camel_oil/v1]
end
subgraph "控制器层"
Controller[internal/controller/camel_oil]
end
subgraph "服务层"
Service[internal/service/camel_oil.go]
end
subgraph "逻辑层"
Logic[internal/logic/camel_oil]
end
subgraph "数据访问层"
DAO[internal/dao]
end
subgraph "模型层"
Model[internal/model/entity]
end
subgraph "数据库"
DB[sql/camel_oil_tables.sql]
end
API --> Controller
Controller --> Service
Service --> Logic
Logic --> DAO
DAO --> Model
Model --> DB
```

**图示来源**
- [camel_oil.go](file://api/camel_oil/camel_oil.go)
- [camel_oil_v1_submit_order.go](file://internal/controller/camel_oil/camel_oil_v1_submit_order.go)
- [service.go](file://internal/service/camel_oil.go)
- [v_1_camel_oil_account.go](file://internal/model/entity/v_1_camel_oil_account.go)
- [camel_oil_tables.sql](file://sql/camel_oil_tables.sql)

**节来源**
- [camel_oil.go](file://api/camel_oil/camel_oil.go)
- [camel_oil_v1_submit_order.go](file://internal/controller/camel_oil/camel_oil_v1_submit_order.go)

## 核心组件
骆驼加油系统的核心组件包括四个主要数据库表：账号表、订单表、账号历史表和订单历史表。这些表共同构成了系统的数据基础，支持账号管理、订单处理和操作审计等功能。

**节来源**
- [camel_oil_tables.sql](file://sql/camel_oil_tables.sql)
- [v_1_camel_oil_account.go](file://internal/model/entity/v_1_camel_oil_account.go)
- [v_1_camel_oil_order.go](file://internal/model/entity/v_1_camel_oil_order.go)

## 架构概述
骆驼加油系统的数据架构采用标准的分层设计，通过实体-关系模型来管理平台的核心业务数据。系统通过外键约束确保数据完整性，并使用软删除机制保留历史数据。

```mermaid
erDiagram
CAMEL_OIL_ACCOUNT {
bigint id PK
varchar(128) account_name
varchar(20) phone UK
text token
tinyint status
datetime token_expire_at
datetime last_login_at
datetime last_used_at
int daily_order_count
date daily_order_date
int total_order_count
text failure_reason
text remark
datetime created_at
datetime updated_at
datetime deleted_at
}
CAMEL_OIL_ORDER {
bigint id PK
varchar(64) order_no UK
varchar(128) merchant_order_id
bigint account_id FK
varchar(128) account_name
varchar(128) platform_order_no
decimal(10,2) amount
text alipay_url
tinyint status
tinyint pay_status
tinyint notify_status
int notify_count
datetime last_check_at
datetime paid_at
text attach
text failure_reason
datetime created_at
datetime updated_at
datetime deleted_at
}
CAMEL_OIL_ACCOUNT_HISTORY {
bigint id PK
varchar(36) history_uuid UK
bigint account_id FK
varchar(32) change_type
tinyint status_before
tinyint status_after
int failure_count
text remark
datetime created_at
datetime updated_at
datetime deleted_at
}
CAMEL_OIL_ORDER_HISTORY {
bigint id PK
varchar(36) history_uuid UK
varchar(64) order_no FK
varchar(32) change_type
bigint account_id FK
varchar(128) account_name
text raw_data
text remark
datetime created_at
datetime updated_at
datetime deleted_at
}
CAMEL_OIL_ACCOUNT ||--o{ CAMEL_OIL_ORDER : "拥有"
CAMEL_OIL_ACCOUNT ||--o{ CAMEL_OIL_ACCOUNT_HISTORY : "产生"
CAMEL_OIL_ORDER ||--o{ CAMEL_OIL_ORDER_HISTORY : "产生"
```

**图示来源**
- [camel_oil_tables.sql](file://sql/camel_oil_tables.sql)
- [v_1_camel_oil_account.go](file://internal/model/entity/v_1_camel_oil_account.go)
- [v_1_camel_oil_order.go](file://internal/model/entity/v_1_camel_oil_order.go)

## 详细组件分析

### 账号管理组件分析
骆驼加油账号管理组件负责维护平台账号的生命周期，包括登录状态、Token管理和使用统计等功能。

#### 账号实体类图
```mermaid
classDiagram
class V1CamelOilAccount {
+int64 id
+string accountName
+string phone
+string token
+int status
+gtime.Time tokenExpireAt
+gtime.Time lastLoginAt
+gtime.Time lastUsedAt
+int dailyOrderCount
+gtime.Time dailyOrderDate
+int totalOrderCount
+string failureReason
+string remark
+gtime.Time createdAt
+gtime.Time updatedAt
+gtime.Time deletedAt
}
class V1CamelOilAccountHistory {
+int64 id
+string historyUuid
+int64 accountId
+string changeType
+int statusBefore
+int statusAfter
+int failureCount
+string remark
+gtime.Time createdAt
+gtime.Time updatedAt
+gtime.Time deletedAt
}
V1CamelOilAccount --> V1CamelOilAccountHistory : "生成"
```

**图示来源**
- [v_1_camel_oil_account.go](file://internal/model/entity/v_1_camel_oil_account.go)
- [v_1_camel_oil_account_history.go](file://internal/model/entity/v_1_camel_oil_account_history.go)

**节来源**
- [v_1_camel_oil_account.go](file://internal/model/entity/v_1_camel_oil_account.go)
- [v_1_camel_oil_account_history.go](file://internal/model/entity/v_1_camel_oil_account_history.go)

### 订单处理组件分析
订单处理组件负责管理骆驼加油平台的订单生命周期，从创建到支付完成或失败的全过程。

#### 订单实体类图
```mermaid
classDiagram
class V1CamelOilOrder {
+int64 id
+string orderNo
+string merchantOrderId
+int64 accountId
+string accountName
+string platformOrderNo
+decimal amount
+string alipayUrl
+int status
+int payStatus
+int notifyStatus
+int notifyCount
+gtime.Time lastCheckAt
+gtime.Time paidAt
+string attach
+string failureReason
+gtime.Time createdAt
+gtime.Time updatedAt
+gtime.Time deletedAt
}
class V1CamelOilOrderHistory {
+int64 id
+string historyUuid
+string orderNo
+string changeType
+int64 accountId
+string accountName
+string rawData
+string remark
+gtime.Time createdAt
+gtime.Time updatedAt
+gtime.Time deletedAt
}
V1CamelOilOrder --> V1CamelOilOrderHistory : "生成"
```

**图示来源**
- [v_1_camel_oil_order.go](file://internal/model/entity/v_1_camel_oil_order.go)
- [v_1_camel_oil_order_history.go](file://internal/model/entity/v_1_camel_oil_order_history.go)

**节来源**
- [v_1_camel_oil_order.go](file://internal/model/entity/v_1_camel_oil_order.go)
- [v_1_camel_oil_order_history.go](file://internal/model/entity/v_1_camel_oil_order_history.go)

### API流程分析
骆驼加油系统的API流程展示了订单提交和回调处理的核心业务流程。

#### 订单提交流程序列图
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "ControllerV1"
participant Service as "CamelOil Service"
Client->>Controller : SubmitOrder请求
Controller->>Service : 调用SubmitOrder方法
Service-->>Controller : 返回结果
Controller-->>Client : 返回响应
```

**图示来源**
- [camel_oil_v1_submit_order.go](file://internal/controller/camel_oil/camel_oil_v1_submit_order.go)

#### 回调处理流程序列图
```mermaid
sequenceDiagram
participant Client as "第三方平台"
participant Controller as "ControllerV1"
Client->>Controller : OrderCallback请求
Controller-->>Client : 返回未实现错误
```

**图示来源**
- [camel_oil_v1_order_callback.go](file://internal/controller/camel_oil/camel_oil_v1_order_callback.go)

**节来源**
- [camel_oil_v1_submit_order.go](file://internal/controller/camel_oil/camel_oil_v1_submit_order.go)
- [camel_oil_v1_order_callback.go](file://internal/controller/camel_oil/camel_oil_v1_order_callback.go)

## 依赖分析
骆驼加油模块与其他系统组件存在明确的依赖关系，主要通过服务层进行交互。

```mermaid
graph TD
CamelOil[骆驼加油模块] --> GoFrame[GoFrame框架]
CamelOil --> Database[MySQL数据库]
CamelOil --> Utility[工具库]
CamelOil --> Internal[内部其他模块]
subgraph "内部依赖"
Internal --> Service[service模块]
Internal --> Model[model模块]
Internal --> DAO[dao模块]
Internal --> Logic[logic模块]
end
subgraph "外部依赖"
Utility --> Cache[缓存]
Utility --> Notify[通知服务]
Utility --> Monitor[监控服务]
end
```

**图示来源**
- [go.mod](file://go.mod)
- [camel_oil.go](file://internal/service/camel_oil.go)

**节来源**
- [go.mod](file://go.mod)
- [camel_oil.go](file://internal/service/camel_oil.go)

## 性能考虑
骆驼加油系统的数据库设计考虑了性能优化，主要体现在以下几个方面：
- 在关键字段上创建了适当的索引以提高查询效率
- 使用软删除而非物理删除来保留历史数据
- 对时间敏感的字段建立了复合索引
- 通过外键约束确保数据完整性的同时考虑了查询性能

## 故障排除指南
在使用骆驼加油系统时可能遇到的常见问题及解决方案：

1. **账号登录失败**：检查账号状态是否为"待登录"，确认Token是否过期
2. **订单创建失败**：验证商户订单号是否唯一，检查账号状态是否正常
3. **回调处理异常**：当前回调功能尚未实现，需要开发相应的处理逻辑
4. **数据查询缓慢**：检查相关字段的索引是否存在，优化查询条件

**节来源**
- [camel_oil_tables.sql](file://sql/camel_oil_tables.sql)
- [camel_oil_v1_order_callback.go](file://internal/controller/camel_oil/camel_oil_v1_order_callback.go)

## 结论
骆驼加油系统的数据库模式设计合理，通过四个核心表实现了账号管理、订单处理和历史记录的完整功能。系统采用分层架构，代码结构清晰，便于维护和扩展。建议尽快实现订单回调功能，并进一步完善错误处理机制。