# 患者搜索 API 文档

## 概述

新增了患者搜索 API 端点，用于在创建订单等场景中快速搜索患者信息。该 API 从诊单表（tcm_diagnosis）中搜索患者。

## API 端点

### 搜索患者

**请求**
```
GET /tcm.diagnosis/searchPatient
```

**参数**
```json
{
  "keyword": "张三",           // 搜索关键词（必填）
  "page_no": 1,               // 页码（可选，默认1）
  "page_size": 10             // 每页数量（可选，默认10）
}
```

**搜索字段**
- `patient_name` - 患者姓名
- `patient_phone` - 患者手机号
- `patient_id_card` - 患者身份证号

**响应**
```json
{
  "code": 1,
  "msg": "success",
  "data": {
    "lists": [
      {
        "id": 1,
        "patient_name": "张三",
        "patient_phone": "13800138000",
        "patient_id_card": "110101199001011234",
        "gender": 1,
        "age": 34
      }
    ],
    "count": 1,
    "page_no": 1,
    "page_size": 10
  }
}
```

## 实现细节

### 后端实现

**文件**: `server/app/adminapi/controller/tcm/DiagnosisController.php`

```php
/**
 * @notes 搜索患者（用于创建订单等场景）
 * @return \think\response\Json
 */
public function searchPatient()
{
    $keyword = $this->request->get('keyword', '');
    $page_no = $this->request->get('page_no', 1);
    $page_size = $this->request->get('page_size', 10);

    if (empty($keyword)) {
        return $this->success('', ['lists' => [], 'count' => 0]);
    }

    $offset = ($page_no - 1) * $page_size;
    
    $lists = \app\common\model\tcm\Diagnosis::where('patient_name|patient_phone|patient_id_card', 'like', '%' . $keyword . '%')
        ->field(['id', 'patient_name', 'patient_phone', 'patient_id_card', 'gender', 'age'])
        ->limit($offset, $page_size)
        ->order('id desc')
        ->select()
        ->toArray();

    $count = \app\common\model\tcm\Diagnosis::where('patient_name|patient_phone|patient_id_card', 'like', '%' . $keyword . '%')
        ->count();

    return $this->success('', [
        'lists' => $lists,
        'count' => $count,
        'page_no' => $page_no,
        'page_size' => $page_size
    ]);
}
```

### 前端实现

**文件**: `admin/src/api/order.ts`

```typescript
// 搜索患者（从诊单表）
export function searchPatients(params: any) {
    return request.get({ url: '/tcm.diagnosis/searchPatient', params })
}
```

**使用示例**:

```typescript
import { searchPatients } from '@/api/order'

const res = await searchPatients({
    keyword: '张三',
    page_no: 1,
    page_size: 10
})
```

## 使用场景

### 创建订单时搜索患者

在订单创建弹窗中，患者输入框使用远程搜索：

```vue
<el-select
    v-model="createForm.patient_id"
    placeholder="请选择患者"
    filterable
    remote
    :remote-method="searchPatients"
    :loading="patientLoading"
>
    <el-option
        v-for="item in patientList"
        :key="item.id"
        :label="`${item.patient_name} (${item.patient_phone})`"
        :value="item.id"
    />
</el-select>
```

### 组件中的使用

```typescript
const patientLoading = ref(false)
const patientList = ref<any[]>([])

const searchPatients = async (query: string) => {
    if (!query) {
        patientList.value = []
        return
    }
    try {
        patientLoading.value = true
        const res = await searchPatientsAPI({
            keyword: query,
            page_no: 1,
            page_size: 10
        })
        patientList.value = res?.lists || []
    } finally {
        patientLoading.value = false
    }
}
```

## 特性

✅ **多字段搜索** - 支持按姓名、手机号、身份证号搜索
✅ **分页支持** - 支持分页查询
✅ **性能优化** - 只返回必要字段
✅ **模糊匹配** - 支持模糊搜索
✅ **排序** - 按 ID 倒序排列

## 返回字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 诊单ID |
| patient_name | string | 患者姓名 |
| patient_phone | string | 患者手机号 |
| patient_id_card | string | 患者身份证号 |
| gender | int | 性别（1=男，2=女） |
| age | int | 年龄 |

## 权限

此 API 端点需要管理员权限，受后端权限系统控制。

## 相关文件

- `server/app/adminapi/controller/tcm/DiagnosisController.php` - 后端控制器（已更新）
- `admin/src/api/order.ts` - 前端 API（已更新）
- `admin/src/views/order/index.vue` - 订单列表页面（已更新）

## 示例请求

### 搜索姓名为"张三"的患者

```bash
curl -X GET "http://localhost:8000/tcm.diagnosis/searchPatient?keyword=张三&page_no=1&page_size=10" \
  -H "token: your_admin_token"
```

### 搜索手机号为"138"开头的患者

```bash
curl -X GET "http://localhost:8000/tcm.diagnosis/searchPatient?keyword=138&page_no=1&page_size=10" \
  -H "token: your_admin_token"
```

### 搜索身份证号为"110101"的患者

```bash
curl -X GET "http://localhost:8000/tcm.diagnosis/searchPatient?keyword=110101&page_no=1&page_size=10" \
  -H "token: your_admin_token"
```

## 响应示例

### 成功响应

```json
{
  "code": 1,
  "msg": "success",
  "data": {
    "lists": [
      {
        "id": 1,
        "patient_name": "张三",
        "patient_phone": "13800138000",
        "patient_id_card": "110101199001011234",
        "gender": 1,
        "age": 34
      },
      {
        "id": 2,
        "patient_name": "张四",
        "patient_phone": "13800138001",
        "patient_id_card": "110101199001011235",
        "gender": 2,
        "age": 32
      }
    ],
    "count": 2,
    "page_no": 1,
    "page_size": 10
  }
}
```

### 空结果响应

```json
{
  "code": 1,
  "msg": "success",
  "data": {
    "lists": [],
    "count": 0,
    "page_no": 1,
    "page_size": 10
  }
}
```

### 无关键词响应

```json
{
  "code": 1,
  "msg": "success",
  "data": {
    "lists": [],
    "count": 0
  }
}
```

## 注意事项

1. **关键词必填** - 必须提供搜索关键词，否则返回空列表
2. **最少一个字符** - 建议在用户输入至少一个字符后才发起搜索
3. **分页参数** - page_no 和 page_size 为可选参数，有默认值
4. **性能考虑** - 搜索结果默认返回 10 条，可根据需要调整 page_size
5. **数据来源** - 搜索的是诊单表（tcm_diagnosis）中的患者信息

---

**创建日期**: 2024-03-10
**版本**: 1.0.0
**状态**: ✅ 完成