# 订单系统实现文档

## 功能概述

完整的订单管理系统，支持订单创建、支付、取消、退款等操作。订单关联患者和创建人（推广ID），支持多种订单类型（挂号费、问诊费、药品费用）。

## 系统架构

### 前端结构
```
admin/
├── src/
│   ├── api/
│   │   └── order.ts                    # 订单API接口
│   └── views/
│       └── order/
│           └── index.vue               # 订单列表页面
├── order.sql                           # 数据库表定义
└── ORDER_SYSTEM_GUIDE.md              # 本文档
```

### 后端结构
```
server/
├── app/
│   ├── common/
│   │   └── model/
│   │       ├── Order.php               # 订单模型
│   │       └── OrderDetail.php         # 订单详情模型
│   └── adminapi/
│       ├── controller/
│       │   └── order/
│       │       └── OrderController.php # 订单控制器
│       ├── logic/
│       │   └── order/
│       │       └── OrderLogic.php      # 订单业务逻辑
│       ├── validate/
│       │   └── order/
│       │       └── OrderValidate.php   # 订单验证规则
│       └── lists/
│           └── order/
│               └── OrderLists.php      # 订单列表类
├── database/
│   └── migrations/
│       └── 2024_03_10_create_order_tables.php  # 数据库迁移
└── order.sql                           # SQL脚本
```

## 数据库设计

### 订单表 (zyt_order)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 主键 |
| order_no | varchar(50) | 订单号（唯一） |
| patient_id | int | 患者ID |
| creator_id | int | 创建人ID（推广ID） |
| order_type | tinyint | 订单类型：1=挂号费，2=问诊费，3=药品费用 |
| amount | decimal(10,2) | 订单金额 |
| status | tinyint | 订单状态：1=待支付，2=已支付，3=已取消，4=已退款 |
| payment_method | varchar(20) | 支付方式：alipay/wechat/bank |
| payment_time | datetime | 支付时间 |
| remark | varchar(500) | 备注 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |
| delete_time | datetime | 删除时间（软删除） |

### 订单详情表 (zyt_order_detail)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 主键 |
| order_id | int | 订单ID |
| related_type | varchar(20) | 关联类型：appointment/diagnosis/medicine |
| related_id | int | 关联ID |
| quantity | int | 数量 |
| unit_price | decimal(10,2) | 单价 |
| total_price | decimal(10,2) | 总价 |
| create_time | datetime | 创建时间 |

## API接口文档

### 1. 获取订单列表

**请求**
```
GET /order.order/lists
```

**参数**
```json
{
  "page_no": 1,
  "page_size": 15,
  "order_no": "",                    // 订单号（可选）
  "patient_keyword": "",             // 患者关键词（可选）
  "order_type": "",                  // 订单类型（可选）
  "status": "",                      // 订单状态（可选）
  "create_time_start": "",           // 创建时间开始（可选）
  "create_time_end": ""              // 创建时间结束（可选）
}
```

**响应**
```json
{
  "code": 1,
  "msg": "success",
  "data": {
    "lists": [
      {
        "id": 1,
        "order_no": "ORD20240310120000123456",
        "patient_id": 1,
        "patient_name": "张三",
        "patient_phone": "13800138000",
        "creator_id": 1,
        "creator_name": "李四",
        "order_type": 1,
        "order_type_desc": "挂号费",
        "amount": "100.00",
        "status": 1,
        "status_desc": "待支付",
        "payment_method": null,
        "payment_time": null,
        "remark": "",
        "create_time": "2024-03-10 12:00:00",
        "update_time": "2024-03-10 12:00:00"
      }
    ],
    "count": 100,
    "page_no": 1,
    "page_size": 15
  }
}
```

### 2. 获取订单详情

**请求**
```
GET /order.order/detail
```

**参数**
```json
{
  "id": 1
}
```

**响应**
```json
{
  "code": 1,
  "msg": "success",
  "data": {
    "id": 1,
    "order_no": "ORD20240310120000123456",
    "patient_id": 1,
    "patient_name": "张三",
    "patient_phone": "13800138000",
    "creator_id": 1,
    "creator_name": "李四",
    "order_type": 1,
    "order_type_desc": "挂号费",
    "amount": "100.00",
    "status": 1,
    "status_desc": "待支付",
    "payment_method": null,
    "payment_time": null,
    "remark": "备注信息",
    "create_time": "2024-03-10 12:00:00",
    "update_time": "2024-03-10 12:00:00",
    "details": [
      {
        "id": 1,
        "order_id": 1,
        "related_type": "appointment",
        "related_type_desc": "挂号",
        "related_id": 1,
        "quantity": 1,
        "unit_price": "100.00",
        "total_price": "100.00",
        "create_time": "2024-03-10 12:00:00"
      }
    ]
  }
}
```

### 3. 创建订单

**请求**
```
POST /order.order/create
```

**参数**
```json
{
  "patient_id": 1,
  "order_type": 1,
  "amount": "100.00",
  "remark": "备注信息",
  "details": [
    {
      "related_type": "appointment",
      "related_id": 1,
      "quantity": 1,
      "unit_price": "100.00",
      "total_price": "100.00"
    }
  ]
}
```

**响应**
```json
{
  "code": 1,
  "msg": "创建成功",
  "data": {
    "id": 1,
    "order_no": "ORD20240310120000123456",
    "patient_id": 1,
    "creator_id": 1,
    "order_type": 1,
    "amount": "100.00",
    "status": 1,
    "payment_method": null,
    "payment_time": null,
    "remark": "备注信息",
    "create_time": "2024-03-10 12:00:00",
    "update_time": "2024-03-10 12:00:00"
  }
}
```

### 4. 编辑订单

**请求**
```
POST /order.order/edit
```

**参数**
```json
{
  "id": 1,
  "remark": "更新后的备注"
}
```

**响应**
```json
{
  "code": 1,
  "msg": "编辑成功"
}
```

### 5. 支付订单

**请求**
```
POST /order.order/pay
```

**参数**
```json
{
  "id": 1,
  "payment_method": "alipay"
}
```

**响应**
```json
{
  "code": 1,
  "msg": "支付成功"
}
```

### 6. 取消订单

**请求**
```
POST /order.order/cancel
```

**参数**
```json
{
  "id": 1
}
```

**响应**
```json
{
  "code": 1,
  "msg": "取消成功"
}
```

### 7. 退款订单

**请求**
```
POST /order.order/refund
```

**参数**
```json
{
  "id": 1
}
```

**响应**
```json
{
  "code": 1,
  "msg": "退款成功"
}
```

### 8. 删除订单

**请求**
```
POST /order.order/delete
```

**参数**
```json
{
  "id": 1
}
```

**响应**
```json
{
  "code": 1,
  "msg": "删除成功"
}
```

### 9. 导出订单

**请求**
```
GET /order.order/export
```

**参数**
```json
{
  "page_no": 1,
  "page_size": 15,
  "order_no": "",
  "patient_keyword": "",
  "order_type": "",
  "status": "",
  "create_time_start": "",
  "create_time_end": ""
}
```

## 前端使用指南

### 1. 导入API

```typescript
import { 
  orderLists, 
  orderDetail, 
  orderCreate, 
  orderEdit, 
  orderPay, 
  orderCancel, 
  orderRefund, 
  orderDelete, 
  orderExport 
} from '@/api/order'
```

### 2. 使用列表页面

```vue
<template>
  <order-list />
</template>

<script setup>
import OrderList from '@/views/order/index.vue'
</script>
```

### 3. 搜索和筛选

```typescript
// 搜索订单
const queryParams = {
  order_no: 'ORD20240310',
  patient_keyword: '张三',
  order_type: 1,
  status: 1,
  create_time_start: '2024-03-01',
  create_time_end: '2024-03-31'
}

const { pager, getLists } = usePaging({
  fetchFun: orderLists,
  params: queryParams
})

// 执行搜索
getLists()
```

## 后端使用指南

### 1. 创建订单

```php
use app\adminapi\logic\OrderLogic;

$params = [
    'patient_id' => 1,
    'creator_id' => 1,
    'order_type' => 1,
    'amount' => 100.00,
    'remark' => '备注',
    'details' => [
        [
            'related_type' => 'appointment',
            'related_id' => 1,
            'quantity' => 1,
            'unit_price' => 100.00,
            'total_price' => 100.00
        ]
    ]
];

$result = OrderLogic::create($params);
if (!$result) {
    echo OrderLogic::getError();
}
```

### 2. 支付订单

```php
$result = OrderLogic::pay(1, 'alipay');
if (!$result) {
    echo OrderLogic::getError();
}
```

### 3. 获取订单详情

```php
$order = OrderLogic::detail(1);
```

## 权限配置

需要在后端权限系统中添加以下权限节点：

```
order.order/lists      - 订单列表
order.order/detail     - 订单详情
order.order/create     - 创建订单
order.order/edit       - 编辑订单
order.order/pay        - 支付订单
order.order/cancel     - 取消订单
order.order/refund     - 退款订单
order.order/delete     - 删除订单
order.order/export     - 导出订单
```

## 安装步骤

### 1. 执行数据库迁移

```bash
# 使用迁移文件
php think migrate:run

# 或直接执行SQL
mysql -u root -p database_name < admin/order.sql
```

### 2. 前端集成

- 将 `admin/src/api/order.ts` 复制到项目
- 将 `admin/src/views/order/index.vue` 复制到项目
- 在路由中添加订单页面

### 3. 后端集成

- 将 `server/app/common/model/Order.php` 复制到项目
- 将 `server/app/common/model/OrderDetail.php` 复制到项目
- 将 `server/app/adminapi/controller/order/OrderController.php` 复制到项目
- 将 `server/app/adminapi/logic/order/OrderLogic.php` 复制到项目
- 将 `server/app/adminapi/validate/order/OrderValidate.php` 复制到项目
- 将 `server/app/adminapi/lists/order/OrderLists.php` 复制到项目

### 4. 权限配置

在后端权限管理中添加订单相关权限节点。

## 业务流程

### 订单生命周期

```
创建订单 (status=1)
    ↓
支付订单 (status=2) 或 取消订单 (status=3)
    ↓
如果已支付，可以退款 (status=4)
    ↓
删除订单
```

### 订单类型

- **1 - 挂号费**: 关联医生排班和患者预约
- **2 - 问诊费**: 关联诊断记录
- **3 - 药品费用**: 关联药品订单

## 注意事项

1. **订单号生成**: 自动生成唯一订单号，格式为 `ORD + 时间戳 + 随机数`
2. **软删除**: 订单支持软删除，不会真正删除数据
3. **关联关系**: 订单详情记录了订单与其他模块的关联关系
4. **支付方式**: 支持支付宝、微信、银行卡三种支付方式
5. **状态转换**: 订单状态转换有严格的业务规则限制

## 扩展建议

1. **支付集成**: 集成第三方支付接口（支付宝、微信等）
2. **发票管理**: 支持订单发票申请和管理
3. **订单统计**: 添加订单统计和报表功能
4. **自动对账**: 定期与支付平台对账
5. **订单提醒**: 支付超时提醒、订单状态变更通知
6. **退款流程**: 完善退款审核和处理流程
7. **订单模板**: 支持不同类型订单的模板配置