# 订单操作记录系统 - 使用说明

## 概述

订单操作记录系统是一个用于记录和追踪订单操作历史的完整解决方案。本系统采用现代化的架构设计，区分前端用户操作和后台管理员操作，支持AOP（面向切面编程）模式，提供丰富的查询和统计功能。

## 架构设计

### 分层架构

本系统采用分层架构设计，明确各层职责：

1. **模型层 (OrderAction.php)**
   - 负责数据访问和基本数据处理
   - 提供基础的数据查询方法
   - 属性转换和数据格式化

2. **服务层 (OrderActionService.php)**
   - 包含所有业务逻辑
   - 数据验证和处理
   - 复杂的业务规则和流程

3. **枚举层 (OrderActionEnum.php)**
   - 提供类型安全的常量定义
   - 类型验证和转换方法

4. **装饰器层 (OrderActionDecorator.php)**
   - AOP模式的自动记录功能
   - 非侵入式的操作记录

## 核心组件

### 1. OrderActionEnum 枚举类

提供完整的类型定义和验证：

```php
use app\common\Enum\OrderActionEnum;

// 操作类型
OrderActionEnum::ACTION_CREATE    // 创建订单
OrderActionEnum::ACTION_PAY       // 支付订单
OrderActionEnum::ACTION_SHIP      // 发货
OrderActionEnum::ACTION_RECEIVE   // 确认收货
OrderActionEnum::ACTION_CANCEL    // 取消订单
OrderActionEnum::ACTION_REFUND    // 退款
OrderActionEnum::ACTION_RETURN    // 退货
OrderActionEnum::ACTION_COMPLETE  // 完成订单
OrderActionEnum::ACTION_COMMENT   // 评价
OrderActionEnum::ACTION_MODIFY    // 修改订单
OrderActionEnum::ACTION_REMIND    // 催单
OrderActionEnum::ACTION_ADMIN_CANCEL   // 管理员取消
OrderActionEnum::ACTION_AUTO_CANCEL    // 系统自动取消
OrderActionEnum::ACTION_AUTO_CONFIRM   // 系统自动确认收货

// 用户类型
OrderActionEnum::USER_TYPE_CUSTOMER    // 前端用户
OrderActionEnum::USER_TYPE_ADMIN       // 后台管理员
OrderActionEnum::USER_TYPE_SYSTEM      // 系统操作

// 操作员类型
OrderActionEnum::OPERATOR_TYPE_USER    // 用户操作
OrderActionEnum::OPERATOR_TYPE_ADMIN   // 管理员操作
OrderActionEnum::OPERATOR_TYPE_SYSTEM  // 系统操作

// 优先级
OrderActionEnum::PRIORITY_LOW      // 低优先级
OrderActionEnum::PRIORITY_NORMAL   // 普通优先级
OrderActionEnum::PRIORITY_HIGH     // 高优先级
OrderActionEnum::PRIORITY_URGENT   // 紧急优先级
```

### 2. OrderAction 模型类

负责数据访问和基本数据处理：

```php
use app\common\model\OrderAction;

// 基础查询方法
$actions = OrderAction::getByOrderSn('ORDER001');
$lastAction = OrderAction::getLatestByOrderSn('ORDER001');
$hasAction = OrderAction::hasActionType('ORDER001', OrderActionEnum::ACTION_PAY);
$stats = OrderAction::getStatsData('ORDER001');

// 批量插入
OrderAction::insertBatch($data);

// 兼容性方法（已废弃，建议使用服务类）
OrderAction::push('ORDER001', 'admin', '修改订单');
```

### 3. OrderActionService 服务类

**主要业务逻辑类，所有业务操作都应该通过服务类进行：**

#### 基本操作记录

```php
use app\common\Service\OrderActionService;

// 通用添加方法
OrderActionService::addAction([
    'order_sn' => 'ORDER001',
    'action_type' => OrderActionEnum::ACTION_PAY,
    'operator' => 'user123',
    'memo' => '支付成功',
    'user_type' => OrderActionEnum::USER_TYPE_CUSTOMER,
    'user_id' => 123,
    'extra_data' => ['payment_method' => 'alipay']
]);

// 用户操作记录
OrderActionService::addUserAction(
    'ORDER001',
    OrderActionEnum::ACTION_PAY,
    'user123',
    '支付成功',
    123,
    ['payment_method' => 'alipay']
);

// 管理员操作记录
OrderActionService::addAdminAction(
    'ORDER001',
    OrderActionEnum::ACTION_SHIP,
    'admin001',
    '订单发货',
    1,
    ['tracking_number' => 'SF123456']
);

// 系统操作记录
OrderActionService::addSystemAction(
    'ORDER001',
    OrderActionEnum::ACTION_AUTO_CANCEL,
    '订单超时自动取消',
    ['timeout_minutes' => 30]
);

// 兼容老接口
OrderActionService::push('ORDER001', 'admin', '修改订单');
```

#### 批量操作

```php
// 批量添加操作记录
$batch_data = [
    [
        'order_sn' => 'ORDER001',
        'action_type' => OrderActionEnum::ACTION_CREATE,
        'operator' => 'user123',
        'memo' => '创建订单',
        'user_type' => OrderActionEnum::USER_TYPE_CUSTOMER,
        'user_id' => 123
    ],
    [
        'order_sn' => 'ORDER002',
        'action_type' => OrderActionEnum::ACTION_CREATE,
        'operator' => 'user456',
        'memo' => '创建订单',
        'user_type' => OrderActionEnum::USER_TYPE_CUSTOMER,
        'user_id' => 456
    ]
];

OrderActionService::addBatchActions($batch_data);
```

#### 查询操作

```php
// 获取订单所有操作记录
$actions = OrderActionService::getOrderActions('ORDER001');

// 获取特定类型的操作记录
$payActions = OrderActionService::getOrderActions('ORDER001', OrderActionEnum::ACTION_PAY);

// 获取管理员操作记录
$adminActions = OrderActionService::getOrderActions('ORDER001', '', OrderActionEnum::USER_TYPE_ADMIN);

// 获取最后一次操作
$lastAction = OrderActionService::getLastAction('ORDER001');

// 检查是否存在某个操作
$hasPaid = OrderActionService::hasAction('ORDER001', OrderActionEnum::ACTION_PAY);

// 获取操作统计
$stats = OrderActionService::getActionStats('ORDER001');

// 获取操作时间线
$timeline = OrderActionService::getActionTimeline('ORDER001');
$timelineNoSystem = OrderActionService::getActionTimeline('ORDER001', false);
```

#### 高级功能

```php
// 记录状态变化
OrderActionService::recordStatusChange(
    'ORDER001',
    'created',
    'paid',
    'user123',
    OrderActionEnum::USER_TYPE_CUSTOMER,
    123,
    '支付完成'
);

// 获取操作次数统计
$payCount = OrderActionService::getActionCount('ORDER001', OrderActionEnum::ACTION_PAY);

// 获取用户操作历史
$userHistory = OrderActionService::getUserActionHistory(123, OrderActionEnum::USER_TYPE_CUSTOMER, 10);

// 获取高优先级操作
$highPriorityActions = OrderActionService::getHighPriorityActions('ORDER001');

// 数据验证
list($isValid, $error) = OrderActionService::validateActionData([
    'order_sn' => 'ORDER001',
    'action_type' => OrderActionEnum::ACTION_PAY,
    'user_type' => OrderActionEnum::USER_TYPE_CUSTOMER
]);

// 清理过期记录
OrderActionService::cleanExpiredActions(90); // 清理90天前的记录
```

### 4. OrderActionDecorator 装饰器类

提供AOP模式的自动记录功能：

```php
use app\common\library\OrderActionDecorator;

// 为服务类添加自动记录功能
$orderService = new OrderService();

// 用户操作装饰器
$decoratedService = OrderActionDecorator::forUser($orderService, 'user123', 123);
$decoratedService->createOrder($orderData); // 自动记录创建订单操作

// 管理员操作装饰器
$decoratedService = OrderActionDecorator::forAdmin($orderService, 'admin001', 1);
$decoratedService->cancelOrder('ORDER001'); // 自动记录取消订单操作

// 系统操作装饰器
$decoratedService = OrderActionDecorator::forSystem($orderService);
$decoratedService->processExpiredOrders(); // 自动记录系统处理操作
```

## 使用场景

### 1. 订单创建

```php
// 用户创建订单
OrderActionService::addUserAction(
    $order_sn,
    OrderActionEnum::ACTION_CREATE,
    $user_name,
    '用户创建订单',
    $user_id,
    ['channel' => 'web']
);
```

### 2. 订单支付

```php
// 用户支付订单
OrderActionService::addUserAction(
    $order_sn,
    OrderActionEnum::ACTION_PAY,
    $user_name,
    '订单支付成功',
    $user_id,
    [
        'payment_method' => 'alipay',
        'amount' => 99.99,
        'transaction_id' => 'TXN123456'
    ]
);
```

### 3. 管理员发货

```php
// 管理员发货
OrderActionService::addAdminAction(
    $order_sn,
    OrderActionEnum::ACTION_SHIP,
    $admin_name,
    '订单已发货',
    $admin_id,
    [
        'courier' => 'SF Express',
        'tracking_number' => 'SF123456789',
        'estimated_delivery' => '2024-01-15'
    ]
);
```

### 4. 系统自动处理

```php
// 系统自动取消超时订单
OrderActionService::addSystemAction(
    $order_sn,
    OrderActionEnum::ACTION_AUTO_CANCEL,
    '订单超时自动取消',
    [
        'timeout_minutes' => 30,
        'original_create_time' => $create_time
    ]
);
```

### 5. 状态变更记录

```php
// 记录订单状态变化
OrderActionService::recordStatusChange(
    $order_sn,
    'pending',
    'paid',
    $operator,
    $user_type,
    $user_id,
    '支付完成，状态更新'
);
```

## 数据查询

### 1. 基础查询

```php
// 获取订单所有操作记录
$actions = OrderActionService::getOrderActions('ORDER001');

// 获取支付相关操作
$payActions = OrderActionService::getOrderActions(
    'ORDER001',
    OrderActionEnum::ACTION_PAY
);

// 获取管理员操作
$adminActions = OrderActionService::getOrderActions(
    'ORDER001',
    '',
    OrderActionEnum::USER_TYPE_ADMIN
);

// 限制返回数量
$recentActions = OrderActionService::getOrderActions('ORDER001', '', '', 5);
```

### 2. 统计查询

```php
// 获取操作统计
$stats = OrderActionService::getActionStats('ORDER001');
/*
返回格式：
{
    "total_count": 5,
    "user_count": 3,
    "admin_count": 2,
    "system_count": 0,
    "action_types": {
        "create": 1,
        "pay": 1,
        "ship": 1,
        "receive": 1,
        "complete": 1
    },
    "actions_data": [...]
}
*/

// 获取操作次数
$payCount = OrderActionService::getActionCount('ORDER001', OrderActionEnum::ACTION_PAY);
```

### 3. 时间线查询

```php
// 获取完整时间线
$timeline = OrderActionService::getActionTimeline('ORDER001');

// 排除系统操作
$userTimeline = OrderActionService::getActionTimeline('ORDER001', false);

// 时间线数据结构
/*
[
    {
        "id": 1,
        "time": 1704038400,
        "time_text": "2024-01-01 00:00:00",
        "operator": "user123",
        "action_type": "create",
        "action_text": "创建订单",
        "user_type": "customer",
        "user_text": "前端用户",
        "memo": "用户创建订单",
        "priority": 2,
        "priority_text": "普通优先级",
        "extra_data": "{\"channel\":\"web\"}"
    }
]
*/
```

### 4. 高级查询

```php
// 获取用户操作历史
$userHistory = OrderActionService::getUserActionHistory(
    123,
    OrderActionEnum::USER_TYPE_CUSTOMER,
    10
);

// 获取高优先级操作
$urgentActions = OrderActionService::getHighPriorityActions('ORDER001');

// 检查特定操作是否存在
$hasBeenPaid = OrderActionService::hasAction('ORDER001', OrderActionEnum::ACTION_PAY);
$hasBeenShipped = OrderActionService::hasAction('ORDER001', OrderActionEnum::ACTION_SHIP);
```

## 数据验证

```php
// 验证操作数据
list($isValid, $error) = OrderActionService::validateActionData([
    'order_sn' => 'ORDER001',
    'action_type' => OrderActionEnum::ACTION_PAY,
    'user_type' => OrderActionEnum::USER_TYPE_CUSTOMER,
    'priority' => OrderActionEnum::PRIORITY_HIGH
]);

if (!$isValid) {
    echo "验证失败: " . $error;
}
```

## 数据库设计

### 表结构

```sql
CREATE TABLE `fa_shop_order_action` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `order_sn` varchar(50) NOT NULL COMMENT '订单编号',
    `operator` varchar(100) NOT NULL COMMENT '操作人',
    `memo` text COMMENT '备注',
    `action_type` varchar(20) NOT NULL DEFAULT 'modify' COMMENT '操作类型',
    `user_type` varchar(20) NOT NULL DEFAULT 'admin' COMMENT '用户类型',
    `operator_type` varchar(20) NOT NULL DEFAULT 'admin' COMMENT '操作员类型',
    `priority` tinyint(1) NOT NULL DEFAULT 2 COMMENT '优先级',
    `user_id` int(11) NOT NULL DEFAULT 0 COMMENT '用户ID',
    `ip` varchar(50) NOT NULL DEFAULT '' COMMENT 'IP地址',
    `user_agent` varchar(500) NOT NULL DEFAULT '' COMMENT '用户代理',
    `extra_data` text COMMENT '额外数据',
    `createtime` int(11) NOT NULL DEFAULT 0 COMMENT '创建时间',
    PRIMARY KEY (`id`),
    KEY `idx_order_sn` (`order_sn`),
    KEY `idx_action_type` (`action_type`),
    KEY `idx_user_type` (`user_type`),
    KEY `idx_user_id` (`user_id`),
    KEY `idx_createtime` (`createtime`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单操作记录表';
```

### 索引优化

- `idx_order_sn`: 订单编号索引（最常用）
- `idx_action_type`: 操作类型索引
- `idx_user_type`: 用户类型索引
- `idx_user_id`: 用户ID索引
- `idx_createtime`: 创建时间索引

## 性能优化

### 1. 批量操作

```php
// 批量插入多个订单的操作记录
$batch_data = [];
foreach ($orders as $order) {
    $batch_data[] = [
        'order_sn' => $order['order_sn'],
        'action_type' => OrderActionEnum::ACTION_CREATE,
        'operator' => $order['user_name'],
        'user_type' => OrderActionEnum::USER_TYPE_CUSTOMER,
        'user_id' => $order['user_id'],
        'memo' => '批量创建订单'
    ];
}
OrderActionService::addBatchActions($batch_data);
```

### 2. 数据清理

```php
// 定期清理过期记录
OrderActionService::cleanExpiredActions(90); // 保留90天
```

### 3. 查询优化

```php
// 使用限制减少数据量
$recentActions = OrderActionService::getOrderActions('ORDER001', '', '', 10);

// 只查询必要的字段
$actions = OrderAction::getByOrderSn('ORDER001')->field('id,action_type,operator,createtime');
```

## 最佳实践

### 1. 使用服务类

**✅ 推荐：始终使用服务类**
```php
// 好的做法
OrderActionService::addUserAction($order_sn, $action_type, $operator, $memo, $user_id);
```

**❌ 不推荐：直接操作模型**
```php
// 不好的做法
OrderAction::create($data);
```

### 2. 类型安全

**✅ 推荐：使用枚举常量**
```php
// 好的做法
OrderActionService::addUserAction(
    'ORDER001',
    OrderActionEnum::ACTION_PAY,
    'user123',
    '支付成功',
    123
);
```

**❌ 不推荐：硬编码字符串**
```php
// 不好的做法
OrderActionService::addUserAction('ORDER001', 'pay', 'user123', '支付成功', 123);
```

### 3. 数据验证

**✅ 推荐：数据验证**
```php
// 好的做法
list($isValid, $error) = OrderActionService::validateActionData($data);
if ($isValid) {
    OrderActionService::addAction($data);
}
```

### 4. 异常处理

**✅ 推荐：适当的异常处理**
```php
// 好的做法
try {
    $result = OrderActionService::addUserAction($order_sn, $action_type, $operator, $memo, $user_id);
    if (!$result) {
        // 处理失败情况
        Log::error("订单操作记录失败: {$order_sn}");
    }
} catch (Exception $e) {
    // 处理异常
    Log::error("订单操作记录异常: " . $e->getMessage());
}
```

### 5. 性能考虑

**✅ 推荐：批量操作**
```php
// 好的做法：批量处理
OrderActionService::addBatchActions($batch_data);
```

**❌ 不推荐：循环单个操作**
```php
// 不好的做法：循环单个插入
foreach ($orders as $order) {
    OrderActionService::addUserAction(...);
}
```

## 常见问题

### Q1: 如何区分用户操作和管理员操作？

使用不同的方法：
- 用户操作：`OrderActionService::addUserAction()`
- 管理员操作：`OrderActionService::addAdminAction()`
- 系统操作：`OrderActionService::addSystemAction()`

### Q2: 如何记录状态变化？

使用专门的状态变化记录方法：
```php
OrderActionService::recordStatusChange($order_sn, $old_status, $new_status, $operator, $user_type, $user_id);
```

### Q3: 如何实现自动记录？

使用装饰器模式：
```php
$decoratedService = OrderActionDecorator::forUser($orderService, 'user123', 123);
$decoratedService->createOrder($data); // 自动记录操作
```

### Q4: 如何查询特定类型的操作？

使用枚举常量进行查询：
```php
$payActions = OrderActionService::getOrderActions('ORDER001', OrderActionEnum::ACTION_PAY);
```

### Q5: 如何处理大量数据？

使用批量操作和分页查询：
```php
// 批量插入
OrderActionService::addBatchActions($batch_data);

// 分页查询
$actions = OrderActionService::getOrderActions('ORDER001', '', '', 20);
```

## 总结

订单操作记录系统提供了完整的订单操作追踪功能，采用现代化的架构设计，分离了数据访问层和业务逻辑层，确保代码的可维护性和可扩展性。通过合理使用服务类、枚举常量和装饰器模式，可以构建一个高效、可靠的订单操作记录系统。