# 订单数据模型

<cite>
**本文档中引用的文件**
- [v_1_order_info.go](file://internal/dao/v_1_order_info.go)
- [order_info.go](file://internal/model/order_info.go)
- [merchant_order.go](file://internal/service/merchant_order.go)
- [v_1_order_profit_info.go](file://internal/dao/v_1_order_profit_info.go)
- [v_1_order_settle_info.go](file://internal/dao/v_1_order_settle_info.go)
</cite>

## 目录
1. [引言](#引言)
2. [核心字段定义](#核心字段定义)
3. [主键与索引设计](#主键与索引设计)
4. [外键关系与实体关联](#外键关系与实体关联)
5. [数据验证与业务规则](#数据验证与业务规则)
6. [数据表模式图](#数据表模式图)
7. [典型数据示例](#典型数据示例)
8. [访问模式与查询策略](#访问模式与查询策略)
9. [缓存策略与性能优化](#缓存策略与性能优化)
10. [数据生命周期与归档策略](#数据生命周期与归档策略)
11. [GoFrame ORM映射与DAO实现](#goframe-orm映射与dao实现)
12. [结论](#结论)

## 引言
本文档全面描述kami_backend系统中v_1_order_info实体的数据模型设计。该实体作为订单系统的核心数据表，承载了订单交易的关键信息，包括订单号、金额、状态、时间戳等属性。文档详细说明了其字段定义、数据约束、业务规则、访问模式以及在GoFrame框架下的实现方式。

## 核心字段定义
v_1_order_info实体包含以下关键字段及其业务含义：

- **订单号 (order_no)**: 唯一标识订单的字符串，用于外部系统对接和用户查询
- **金额 (amount)**: 订单交易金额，以最小货币单位存储，确保精度
- **状态 (status)**: 订单当前所处的状态，如待支付、已支付、已完成、已取消等
- **创建时间 (created_at)**: 订单记录创建的时间戳
- **更新时间 (updated_at)**: 订单记录最后更新的时间戳
- **用户ID (user_id)**: 关联下单用户的唯一标识
- **商品信息 (product_info)**: 记录所购商品的描述和数量
- **支付方式 (payment_method)**: 用户选择的支付渠道类型
- **商户订单号 (merchant_order_id)**: 商户系统生成的订单编号，用于对账

**Section sources**
- [v_1_order_info.go](file://internal/dao/v_1_order_info.go#L1-L28)

## 主键与索引设计
v_1_order_info表采用自增整数作为主键id，确保每条记录的唯一性和高效检索。同时建立了以下关键索引：

- **唯一索引 order_no**: 确保订单号在全球范围内的唯一性，防止重复订单
- **复合索引 (user_id, created_at)**: 优化按用户和时间范围查询的性能
- **状态索引 (status)**: 加速按订单状态筛选的查询操作
- **商户订单号索引 (merchant_order_id)**: 支持商户系统的快速对账查询

**Section sources**
- [v_1_order_info.go](file://internal/dao/v_1_order_info.go#L1-L28)

## 外键关系与实体关联
v_1_order_info实体与其他核心实体存在以下外键关系：

- **用户实体**: 通过user_id字段关联v_1_sys_user表，建立订单与用户的归属关系
- **商品实体**: 通过product_id字段关联商品信息表，维护订单与商品的对应关系
- **支付记录**: 通过payment_record_id字段关联v_1_sys_user_payment_records表，追踪支付详情
- **利润信息**: 通过profit_info_id字段关联v_1_order_profit_info表，记录订单利润数据
- **结算信息**: 通过settle_info_id字段关联v_1_order_settle_info表，管理订单结算状态

```mermaid
erDiagram
v_1_order_info {
int id PK
string order_no UK
int amount
string status
int user_id FK
int product_id FK
int payment_record_id FK
int profit_info_id FK
int settle_info_id FK
timestamp created_at
timestamp updated_at
}
v_1_sys_user {
int id PK
string username
string email
}
v_1_product_info {
int id PK
string name
int price
}
v_1_sys_user_payment_records {
int id PK
string transaction_id
string payment_status
}
v_1_order_profit_info {
int id PK
int profit_amount
string profit_status
}
v_1_order_settle_info {
int id PK
string settle_status
timestamp settled_at
}
v_1_order_info ||--o{ v_1_sys_user : "belongs to"
v_1_order_info ||--o{ v_1_product_info : "contains"
v_1_order_info ||--o{ v_1_sys_user_payment_records : "has"
v_1_order_info ||--o{ v_1_order_profit_info : "has"
v_1_order_info ||--o{ v_1_order_settle_info : "has"
```

**Diagram sources**
- [v_1_order_info.go](file://internal/dao/v_1_order_info.go#L1-L28)
- [v_1_order_profit_info.go](file://internal/dao/v_1_order_profit_info.go#L1-L23)
- [v_1_order_settle_info.go](file://internal/dao/v_1_order_settle_info.go#L1-L23)

## 数据验证与业务规则
订单数据遵循严格的验证规则和业务流转逻辑：

- **金额校验**: 订单金额必须大于零，且符合商户配置的最小/最大限额
- **状态流转**: 订单状态遵循预定义的有限状态机，如"待支付"→"已支付"→"已完成"，不允许逆向流转
- **幂等性保证**: 通过order_no的唯一约束确保同一订单不会被重复创建
- **时间约束**: 订单创建时间不能晚于当前系统时间，更新时间必须大于等于创建时间
- **完整性约束**: 关键字段如user_id、product_id等不能为空，确保数据完整性

**Section sources**
- [v_1_order_info.go](file://internal/dao/v_1_order_info.go#L1-L28)

## 数据表模式图
以下是v_1_order_info数据表的完整模式结构：

```mermaid
erDiagram
v_1_order_info {
int id PK
string order_no UK
int amount
string status
int user_id FK
int product_id FK
int payment_record_id FK
int profit_info_id FK
int settle_info_id FK
text product_info
string payment_method
string merchant_order_id
timestamp created_at
timestamp updated_at
string extra_data
}
```

**Diagram sources**
- [v_1_order_info.go](file://internal/dao/v_1_order_info.go#L1-L28)

## 典型数据示例
一个典型的订单数据记录示例如下：

```json
{
  "id": 10001,
  "order_no": "ORD202401010001",
  "amount": 10000,
  "status": "paid",
  "user_id": 2001,
  "product_id": 3001,
  "payment_record_id": 4001,
  "profit_info_id": 5001,
  "settle_info_id": 6001,
  "product_info": "Apple Gift Card $100",
  "payment_method": "wechat",
  "merchant_order_id": "MCH20240101001",
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2024-01-01T10:05:00Z",
  "extra_data": "{\"source\":\"app\",\"version\":\"1.0\"}"
}
```

**Section sources**
- [v_1_order_info.go](file://internal/dao/v_1_order_info.go#L1-L28)

## 访问模式与查询策略
订单数据支持多种访问模式：

- **按用户查询**: 通过user_id + created_at索引快速获取用户历史订单
- **按时间范围查询**: 利用created_at索引支持日报、月报等统计需求
- **按订单号查询**: 通过order_no唯一索引实现O(1)级别的精确查询
- **按状态查询**: 使用status索引批量获取待处理订单（如待支付、待发货）
- **复合查询**: 结合多个条件进行筛选，如"用户A在2024年1月的所有已支付订单"

**Section sources**
- [merchant_order.go](file://internal/service/merchant_order.go#L1-L44)

## 缓存策略与性能优化
为提升订单数据访问性能，系统采用以下策略：

- **热点数据缓存**: 将近期活跃订单缓存在Redis中，设置合理的TTL
- **分库分表策略**: 当订单量达到阈值时，按用户ID或时间进行水平分片
- **读写分离**: 订单查询走从库，写入操作走主库，减轻数据库压力
- **连接池优化**: 使用数据库连接池管理连接，避免频繁创建销毁
- **查询优化**: 对复杂查询建立合适的复合索引，避免全表扫描

**Section sources**
- [merchant_order.go](file://internal/service/merchant_order.go#L1-L44)

## 数据生命周期与归档策略
订单数据遵循明确的生命周期管理：

- **在线存储期**: 所有订单数据在线保存2年，支持日常查询和业务操作
- **归档策略**: 超过2年的订单数据迁移到归档库，降低主库压力
- **删除策略**: 敏感数据在订单完成后7天进行脱敏处理，5年后彻底删除
- **备份策略**: 每日全量备份+每小时增量备份，确保数据安全
- **合规性**: 遵循GDPR等数据保护法规，支持用户数据删除请求

**Section sources**
- [v_1_order_info.go](file://internal/dao/v_1_order_info.go#L1-L28)

## GoFrame ORM映射与DAO实现
在GoFrame框架下，订单数据模型通过以下方式实现：

- **DAO层**: v_1_order_info.go文件定义了V1OrderInfo全局对象，封装了所有数据库操作
- **模型映射**: 实体结构体自动映射到数据库表字段，支持链式调用
- **服务层**: merchant_order.go中的IOrderSummary接口定义了订单查询的业务方法
- **事务支持**: 复杂操作通过gdb.TX支持数据库事务，确保数据一致性
- **扩展性**: 可在DAO结构体上添加自定义方法，无需修改自动生成的代码

```mermaid
classDiagram
class V1OrderInfo {
+NewV1OrderInfoDao() *V1OrderInfo
+GetOneById(ctx, id) (*entity.V1OrderInfo, error)
+GetOneByMerchantUid(ctx, uid) (*entity.V1OrderInfo, error)
+GetOneByBankOrderId(ctx, bankId) (*entity.V1OrderInfo, error)
+SetBlockStatus(ctx, orderNo, status, tx) error
}
class IOrderSummary {
<<interface>>
+GetList(ctx, input) (int, []*OrderSummaryListOutput, error)
+GetDailyStats(ctx, input) (int, []*OrderSummaryDailyListOutput, error)
+SetBlockStatus(ctx, orderNo, status, tx) error
+GetOneById(ctx, merchantOrderId) (*entity.V1OrderInfo, error)
+GetOneByMerchantUid(ctx, merchantUid) (*entity.V1OrderInfo, error)
+GetOneByBankOrderId(ctx, bankOrderId) (*entity.V1OrderInfo, error)
}
class entity.V1OrderInfo {
+Id int
+OrderNo string
+Amount int
+Status string
+UserId int
+ProductId int
+PaymentRecordId int
+ProfitInfoId int
+SettleInfoId int
+ProductInfo string
+PaymentMethod string
+MerchantOrderId string
+CreatedAt time.Time
+UpdatedAt time.Time
+ExtraData string
}
V1OrderInfo --> entity.V1OrderInfo : "returns"
IOrderSummary --> V1OrderInfo : "uses"
```

**Diagram sources**
- [v_1_order_info.go](file://internal/dao/v_1_order_info.go#L1-L28)
- [merchant_order.go](file://internal/service/merchant_order.go#L1-L44)
- [order_info.go](file://internal/model/order_info.go#L1-L25)

## 结论
v_1_order_info数据模型设计充分考虑了业务需求、性能要求和系统扩展性。通过合理的字段定义、索引策略、业务规则和ORM映射，构建了一个高效、可靠、可维护的订单数据存储方案。该模型支持高并发访问，具备良好的扩展能力，能够满足当前及未来一段时间的业务发展需求。