294 lines
6.2 KiB
Markdown
294 lines
6.2 KiB
Markdown
# 患者搜索 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
|
||
**状态**: ✅ 完成
|