更新

2026-03-11 09:49:47 +08:00
parent 02ae537b4c
commit 38ad60f4bb
290 changed files with 36917 additions and 123 deletions
@@ -0,0 +1,293 @@
+# 患者搜索 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
+**状态**: ✅ 完成