diff --git a/接口文档.md b/接口文档.md index 5ece054..af2f24f 100644 --- a/接口文档.md +++ b/接口文档.md @@ -1,528 +1,695 @@ # 突眼日记接口文档 -## 一、接口概览 +## 一、接口规范 -### 1.1 基本信息 - -- **模块名称**: 突眼日记 -- **控制器路径**: modules\xd_frontend\controllers\ProtrusionController -- **接口前缀**: ?r=xd/protrusion -- **请求方式**: 需要登录（Header中传入loginState） - -### 1.2 响应格式 +### 1.1 基本规范 +- **接口路径格式**: `/?r=xd/xxx` (Yii2路由格式) +- **请求方式**: GET / POST +- **返回格式**: JSON +- **字符编码**: UTF-8 +- **用户认证**: 通过Session/Token获取用户ID，接口内部逻辑处理 +### 1.2 返回格式 ```json -// 成功响应 { "code": 0, - "data": { - // 业务数据 - } -} - -// 失败响应 -{ - "code": 1, - "msg": "错误信息" + "msg": "success", + "data": {} } ``` +### 1.3 错误码说明 +| 错误码 | 说明 | +|--------|------| +| 0 | 成功 | +| 400 | 参数错误 | +| 401 | 未授权 | +| 403 | 禁止访问 | +| 404 | 资源不存在 | +| 500 | 服务器内部错误 | + --- -## 二、接口详情 +## 二、患者端接口 -### 2.1 获取基准照状态 +### 2.1 获取基准照设置状态 -| 项目 | 内容 | -| ---------------- | -------------------------------- | -| **接口路径** | ?r=xd/protrusion/baseline-status | -| **请求方式** | GET | -| **是否需要登录** | 是 | +#### 接口信息 +- **接口路径**: `/?r=xd/proptosis/baseline-status` +- **请求方式**: GET +- **代码位置**: `shop/modules/xd_frontend/controllers/ProptosisController.php` +- **认证方式**: 内部获取当前登录用户ID -#### 响应示例 +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| hasBaseline | bool | 是否已设置基准照 | +| baselineRecordId | string | 基准照记录ID(如果有) | -```json -{ - "code": 0, - "data": { - "hasBaseline": true, - "baselineRecordId": 1 - } -} -``` +--- -#### 返回字段说明 +### 2.2 获取突眼记录列表 -| 字段名 | 类型 | 说明 | -| ---------------- | ---- | --------------------- | -| hasBaseline | bool | 是否已设置基准照 | -| baselineRecordId | int | 基准照记录ID(无则为0) | +#### 接口信息 +- **接口路径**: `/?r=xd/proptosis/record-list` +- **请求方式**: GET +- **代码位置**: `shop/modules/xd_frontend/controllers/ProptosisController.php` +- **认证方式**: 内部获取当前登录用户ID + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| page | int | 否 | 页码(默认1) | +| pageSize | int | 否 | 每页数量(默认10) | + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| list[].recordId | string | 记录ID | +| list[].recordDate | string | 记录日期 | +| list[].isBaseline | int | 是否基准照(0-否,1-是) | +| list[].photoCount | int | 已上传照片数量 | +| list[].firstPhotoUrl | string | 第一张角度图片 | +| list[].treatmentCount | int | 替妥尤单抗使用次数 | +| list[].leftEye | decimal | 左眼凸眼度(mm) | +| list[].rightEye | decimal | 右眼凸眼度(mm) | +| list[].interorbitalDistance | decimal | 框间距(mm) | +| list[].uploadCompleted | int | 上传是否完成(0-未完成,1-已完成) | +| pagination.total | int | 总记录数 | +| pagination.page | int | 当前页码 | +| pagination.pageSize | int | 每页数量 | --- -### 2.2 获取记录列表 +### 2.3 获取突眼记录详情 -| 项目 | 内容 | -| ---------------- | ---------------------------- | -| **接口路径** | ?r=xd/protrusion/record-list | -| **请求方式** | GET | -| **是否需要登录** | 是 | +#### 接口信息 +- **接口路径**: `/?r=xd/proptosis/record-detail` +- **请求方式**: GET +- **代码位置**: `shop/modules/xd_frontend/controllers/ProptosisController.php` +- **认证方式**: 内部获取当前登录用户ID #### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| recordId | string | 是 | 记录ID | + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| recordId | string | 记录ID | +| recordDate | string | 记录日期 | +| treatmentCount | int | 替妥尤单抗使用次数 | +| isBaseline | int | 是否基准照(0-否,1-是) | +| leftEye | decimal | 左眼凸眼度(mm) | +| rightEye | decimal | 右眼凸眼度(mm) | +| interorbitalDistance | decimal | 框间距(mm) | +| uploadCompleted | int | 上传是否完成(0-未完成,1-已完成) | +| photos[] | array | 照片列表 | +| photos[].photoId | string | 照片ID | +| photos[].photoAngle | string | 照片角度 | +| photos[].photoAngleName | string | 照片角度名称 | +| photos[].photoUrl | string | 照片链接 | +| photos[].uploadTime | string | 上传时间 | -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---- | ---- | ---------------- | -| page | int | 否 | 页码，默认1 | -| pageSize | int | 否 | 每页数量，默认10 | +--- -#### 响应示例 +### 2.4 创建/更新突眼记录（含图片ID列表） + +#### 接口信息 +- **接口路径**: `/?r=xd/proptosis/record-save` +- **请求方式**: POST +- **代码位置**: `shop/modules/xd_frontend/controllers/ProptosisController.php` +- **认证方式**: 内部获取当前登录用户ID +- **Content-Type**: application/json + +#### 请求参数（修订） +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| recordId | string | 否 | 记录ID(更新时必填) | +| recordDate | string | 是 | 记录日期(YYYY-MM-DD) | +| treatmentCount | int | 是 | 替妥尤单抗使用次数(0-9,9表示大于8) | +| isBaseline | int | 是 | 是否基准照(0-否,1-是) | +| leftEye | decimal | 否 | 左眼凸眼度(mm) | +| rightEye | decimal | 否 | 右眼凸眼度(mm) | +| interorbitalDistance | decimal | 否 | 框间距(mm) | +| photoIds | string | 否 | 图片ID列表(多个用逗号分隔，photoUpload返回的photoId) | + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| recordId | string | 记录ID | + +#### 业务流程（修订后） +1. 前端：点击保存按钮时，先调用 photo-upload 上传照片（此时没有recordId，返回临时photoId） +2. 前端：然后调用 record-save 保存基本信息（含photoIds），将照片关联到记录 +3. 这样设计是因为只有一个保存按钮，需要先创建记录，再上传照片 + +#### 业务规则 +- 同一天只能创建一条记录，若已存在返回错误提示："该日期已有记录，同一天不可重复记录" -```json -{ - "code": 0, - "data": { - "list": [ - { - "recordId": 1, - "recordDate": "2026-04-10", - "isBaseline": 1, - "treatmentCount": 3, - "leftEye": 18.5, - "rightEye": 19.0, - "interorbitalDistance": 95.0, - "photoCount": 8, - "firstPhoto": "http://example.com/photo1.jpg", - "uploadCompleted": 0 - } - ], - "pages": 2, - "count": 15, - "page": 1 - } -} -``` +--- + +### 2.5 上传照片(含图片安全校验) -#### 返回字段说明 - -| 字段名 | 类型 | 说明 | -| -------------------- | ------ | ----------------------------- | -| recordId | int | 记录ID | -| recordDate | string | 记录日期 | -| isBaseline | int | 是否为基准照(0-否 1-是) | -| treatmentCount | int | 替妥尤单抗使用次数 | -| leftEye | float | 左眼凸眼度(mm) | -| rightEye | float | 右眼凸眼度(mm) | -| interorbitalDistance | float | 框间距(mm) | -| photoCount | int | 已上传照片数量 | -| firstPhoto | string | 第一张图片URL | -| uploadCompleted | int | 记录完整性(0-未完成 1-已完成) | -| pages | int | 总页数 | -| count | int | 总记录数 | -| page | int | 当前页码 | +#### 接口信息 +- **接口路径**: `/?r=xd/proptosis/photo-upload` +- **请求方式**: POST +- **代码位置**: `shop/modules/xd_frontend/controllers/ProptosisController.php` +- **认证方式**: 内部获取当前登录用户ID +- **Content-Type**: application/json + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| recordId | string | 否 | 记录ID(创建记录后可传，用于关联记录) | +| sessionId | string | 否 | 会话ID | +| photoAngle | string | 是 | 照片角度 | +| photoUrl | string | 是 | 照片链接 | + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| photoId | string | 照片ID(用于后续关联到记录) | +| checkStatus | int | 审核状态(1-机审通过,2-机审不通过,3-人工审核不通过) | +| isContinue | bool | 是否允许继续(不合规时根据配置决定) | +| message | string | 提示信息 | + +#### 业务流程（调整后） +1. 前端：先调用 photo-upload 上传照片，返回 photoId +2. 前端：再调用 record-save，传入 photoIds 关联照片和记录 + +#### 同步保存数据 +- userId（内部获取） +- sessionId（可能不存在） +- photoUrl +- uploadTime +- recordId（创建记录后传入） --- -### 2.3 新增记录 +### 2.6 删除突眼记录 -| 项目 | 内容 | -| ---------------- | --------------------------- | -| **接口路径** | ?r=xd/protrusion/record-add | -| **请求方式** | POST | -| **是否需要登录** | 是 | +#### 接口信息 +- **接口路径**: `/?r=xd/proptosis/record-delete` +- **请求方式**: POST +- **代码位置**: `shop/modules/xd_frontend/controllers/ProptosisController.php` +- **认证方式**: 内部获取当前登录用户ID +- **Content-Type**: application/json #### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| recordId | string | 是 | 记录ID | -| 参数名 | 类型 | 必填 | 说明 | -| -------------------- | ------ | ---- | ------------------------------ | -| recordDate | string | 是 | 记录日期，格式YYYY-MM-DD | -| isBaseline | int | 否 | 是否为基准照(0-否 1-是)，默认0 | -| treatmentCount | int | 否 | 替妥尤单抗使用次数(0-9)，默认0 | -| leftEye | float | 否 | 左眼凸眼度(mm) | -| rightEye | float | 否 | 右眼凸眼度(mm) | -| interorbitalDistance | float | 否 | 框间距(mm) | -| frontOpen | string | 否 | 正面睁眼照片URL | -| frontClose | string | 否 | 正面闭眼照片URL | -| frontUp | string | 否 | 正面仰头照片URL | -| sideLeft90 | string | 否 | 90°左侧照片URL | -| sideRight90 | string | 否 | 90°右侧照片URL | -| sideLeft45 | string | 否 | 45°左侧照片URL | -| sideRight45 | string | 否 | 45°右侧照片URL | -| eyeUpLeft | string | 否 | 左上眼球照片URL | -| eyeUp | string | 否 | 向上眼球照片URL | -| eyeUpRight | string | 否 | 右上眼球照片URL | -| eyeLeft | string | 否 | 向左眼球照片URL | -| eyeRight | string | 否 | 向右眼球照片URL | -| eyeDownLeft | string | 否 | 左下眼球照片URL | -| eyeDown | string | 否 | 向下眼球照片URL | -| eyeDownRight | string | 否 | 右下眼球照片URL | - -#### 响应示例 +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| success | bool | 是否成功 | -```json -{ - "code": 0, - "data": { - "recordId": 1 - } -} -``` +--- + +### 2.7 获取对比照片可用日期 -#### 返回字段说明 +#### 接口信息 +- **接口路径**: `/?r=xd/proptosis/compare-dates` +- **请求方式**: GET +- **代码位置**: `shop/modules/xd_frontend/controllers/ProptosisController.php` +- **认证方式**: 内部获取当前登录用户ID -| 字段名 | 类型 | 说明 | -| -------- | ---- | ------------ | -| recordId | int | 新增记录的ID | +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| photoAngle | string | 是 | 照片角度 | + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| baseline | object | 基准照信息 | +| baseline.recordId | string | 记录ID | +| baseline.recordDate | string | 记录日期 | +| nonBaselineList[] | array | 非基准照日期列表 | +| nonBaselineList[].recordId | string | 记录ID | +| nonBaselineList[].recordDate | string | 记录日期 | --- -### 2.4 更新记录 +### 2.8 根据角度和日期列表获取照片 -| 项目 | 内容 | -| ---------------- | ------------------------------ | -| **接口路径** | ?r=xd/protrusion/record-update | -| **请求方式** | POST | -| **是否需要登录** | 是 | +#### 接口信息 +- **接口路径**: `/?r=xd/proptosis/compare-photos` +- **请求方式**: GET +- **代码位置**: `shop/modules/xd_frontend/controllers/ProptosisController.php` +- **认证方式**: 内部获取当前登录用户ID #### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| photoAngle | string | 是 | 照片角度 | +| recordIds | string | 是 | 记录ID列表(多个用逗号分隔) | + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| photos[] | array | 照片列表 | +| photos[].recordId | string | 记录ID | +| photos[].recordDate | string | 记录日期 | +| photos[].isBaseline | int | 是否基准照 | +| photos[].photoUrl | string | 照片链接 | +| photos[].leftEye | decimal | 左眼凸眼度 | +| photos[].rightEye | decimal | 右眼凸眼度 | +| photos[].interorbitalDistance | decimal | 框间距 | +| photos[].treatmentCount | int | 替妥尤使用次数 | -| 参数名 | 类型 | 必填 | 说明 | -| -------------------- | ------ | ---- | ------------------------ | -| recordId | int | 是 | 记录ID | -| recordDate | string | 否 | 记录日期，格式YYYY-MM-DD | -| isBaseline | int | 否 | 是否为基准照(0-否 1-是) | -| treatmentCount | int | 否 | 替妥尤单抗使用次数(0-9) | -| leftEye | float | 否 | 左眼凸眼度(mm) | -| rightEye | float | 否 | 右眼凸眼度(mm) | -| interorbitalDistance | float | 否 | 框间距(mm) | -| frontOpen | string | 否 | 正面睁眼照片URL | -| frontClose | string | 否 | 正面闭眼照片URL | -| frontUp | string | 否 | 正面仰头照片URL | -| sideLeft90 | string | 否 | 90°左侧照片URL | -| sideRight90 | string | 否 | 90°右侧照片URL | -| sideLeft45 | string | 否 | 45°左侧照片URL | -| sideRight45 | string | 否 | 45°右侧照片URL | -| eyeUpLeft | string | 否 | 左上眼球照片URL | -| eyeUp | string | 否 | 向上眼球照片URL | -| eyeUpRight | string | 否 | 右上眼球照片URL | -| eyeLeft | string | 否 | 向左眼球照片URL | -| eyeRight | string | 否 | 向右眼球照片URL | -| eyeDownLeft | string | 否 | 左下眼球照片URL | -| eyeDown | string | 否 | 向下眼球照片URL | -| eyeDownRight | string | 否 | 右下眼球照片URL | - -#### 响应示例 +--- -```json -{ - "code": 0, - "data": { - "success": true - } -} -``` +### 2.9 获取对比角度列表 + +#### 接口信息 +- **接口路径**: `/?r=xd/proptosis/get-compare-angle` +- **请求方式**: GET +- **代码位置**: `shop/modules/xd_frontend/controllers/ProptosisController.php` +- **认证方式**: 内部获取当前登录用户ID + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| photoAngle | object | 对比角度列表 | +| photoAngle.front_open | string | 正面睁眼 | +| photoAngle.front_closed | string | 正面闭眼 | +| photoAngle.front_looking_up | string | 正面仰头 | +| photoAngle.side_left_90 | string | 90°左侧 | +| photoAngle.side_right_90 | string | 90°右侧 | +| photoAngle.side_left_45 | string | 45°左侧 | +| photoAngle.side_right_45 | string | 45°右侧 | +| photoAngle.eye_up_left | string | 左上 | +| photoAngle.eye_up | string | 向上 | +| photoAngle.eye_up_right | string | 右上 | +| photoAngle.eye_left | string | 向左 | +| photoAngle.eye_right | string | 向右 | +| photoAngle.eye_down_left | string | 左下 | +| photoAngle.eye_down | string | 向下 | +| photoAngle.eye_down_right | string | 右下 | --- -### 2.5 获取记录详情 +### 2.10 获取唯一标识 -| 项目 | 内容 | -| ---------------- | ------------------------------ | -| **接口路径** | ?r=xd/protrusion/record-detail | -| **请求方式** | GET | -| **是否需要登录** | 是 | +#### 接口信息 +- **接口路径**: `/?r=xd/proptosis/get-session-id` +- **请求方式**: GET +- **代码位置**: `shop/modules/xd_frontend/controllers/ProptosisController.php` +- **认证方式**: 内部获取当前登录用户ID #### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---- | ---- | ------ | -| recordId | int | 是 | 记录ID | +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| sessionId | string | 唯一标识 | -#### 响应示例 +--- -```json -{ - "code": 0, - "data": { - "recordId": 1, - "recordDate": "2026-04-10", - "isBaseline": 1, - "treatmentCount": 3, - "leftEye": 18.5, - "rightEye": 19.0, - "interorbitalDistance": 95.0, - "photoCount": 15, - "uploadCompleted": 1, - "frontOpen": "http://example.com/photo1.jpg", - "frontClose": "http://example.com/photo2.jpg", - "frontUp": "http://example.com/photo3.jpg", - "sideLeft90": "http://example.com/photo4.jpg", - "sideRight90": "http://example.com/photo5.jpg", - "sideLeft45": "http://example.com/photo6.jpg", - "sideRight45": "http://example.com/photo7.jpg", - "eyeUpLeft": "http://example.com/photo8.jpg", - "eyeUp": "http://example.com/photo9.jpg", - "eyeUpRight": "http://example.com/photo10.jpg", - "eyeLeft": "http://example.com/photo11.jpg", - "eyeRight": "http://example.com/photo12.jpg", - "eyeDownLeft": "http://example.com/photo13.jpg", - "eyeDown": "http://example.com/photo14.jpg", - "eyeDownRight": "http://example.com/photo15.jpg", - "frontOpenName": "正面睁眼", - "frontCloseName": "正面闭眼", - "frontUpName": "正面仰头", - "sideLeft90Name": "90°左侧", - "sideRight90Name": "90°右侧", - "sideLeft45Name": "45°左侧", - "sideRight45Name": "45°右侧", - "eyeUpLeftName": "左上", - "eyeUpName": "向上", - "eyeUpRightName": "右上", - "eyeLeftName": "向左", - "eyeRightName": "向右", - "eyeDownLeftName": "左下", - "eyeDownName": "向下", - "eyeDownRightName": "右下", - "createdAt": "2026-04-10 10:00:00" - } -} -``` +## 三、医生端接口 + +### 3.1 获取患者最近的突眼记录 + +#### 接口信息 +- **接口路径**: `/?r=xd/doctor/proptosis/latest` +- **请求方式**: GET +- **代码位置**: `shop/modules/xd_frontend/controllers/doctor/ProptosisController.php` +- **认证方式**: 内部获取当前登录医生ID + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| patientId | string | 是 | 患者ID | + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| recordId | string | 记录ID | +| photoAngle.side_right_45 | string | 45°右侧 | +| photoAngle.eye_up_left | string | 左上 | +| photoAngle.eye_up | string | 向上 | +| photoAngle.eye_up_right | string | 右上 | +| photoAngle.eye_left | string | 向左 | +| photoAngle.eye_right | string | 向右 | +| photoAngle.eye_down_left | string | 左下 | +| photoAngle.eye_down | string | 向下 | +| photoAngle.eye_down_right | string | 右下 | + +--- + +## 三、医生端接口 + +### 3.1 获取患者最近的突眼记录 + +#### 接口信息 +- **接口路径**: `/?r=xd/doctor/proptosis/latest` +- **请求方式**: GET +- **代码位置**: `shop/modules/xd_frontend/controllers/doctor/ProptosisController.php` +- **认证方式**: 内部获取当前登录医生ID -#### 返回字段说明 - -| 字段名 | 类型 | 说明 | -| -------------------- | ------ | ------------------ | -| recordId | int | 记录ID | -| recordDate | string | 记录日期 | -| isBaseline | int | 是否为基准照 | -| treatmentCount | int | 替妥尤单抗使用次数 | -| leftEye | float | 左眼凸眼度 | -| rightEye | float | 右眼凸眼度 | -| interorbitalDistance | float | 框间距 | -| photoCount | int | 已上传照片数量 | -| uploadCompleted | int | 记录完整性 | -| frontOpen | string | 正面睁眼照片URL | -| frontClose | string | 正面闭眼照片URL | -| frontUp | string | 正面仰头照片URL | -| sideLeft90 | string | 90°左侧照片URL | -| sideRight90 | string | 90°右侧照片URL | -| sideLeft45 | string | 45°左侧照片URL | -| sideRight45 | string | 45°右侧照片URL | -| eyeUpLeft | string | 左上眼球照片URL | -| eyeUp | string | 向上眼球照片URL | -| eyeUpRight | string | 右上眼球照片URL | -| eyeLeft | string | 向左眼球照片URL | -| eyeRight | string | 向右眼球照片URL | -| eyeDownLeft | string | 左下眼球照片URL | -| eyeDown | string | 向下眼球照片URL | -| eyeDownRight | string | 右下眼球照片URL | -| frontOpenName | string | 正面睁眼名称 | -| frontCloseName | string | 正面闭眼名称 | -| frontUpName | string | 正面仰头名称 | -| sideLeft90Name | string | 90°左侧名称 | -| sideRight90Name | string | 90°右侧名称 | -| sideLeft45Name | string | 45°左侧名称 | -| sideRight45Name | string | 45°右侧名称 | -| eyeUpLeftName | string | 左上名称 | -| eyeUpName | string | 向上名称 | -| eyeUpRightName | string | 右上名称 | -| eyeLeftName | string | 向左名称 | -| eyeRightName | string | 向右名称 | -| eyeDownLeftName | string | 左下名称 | -| eyeDownName | string | 向下名称 | -| eyeDownRightName | string | 右下名称 | -| createdAt | string | 创建时间 | +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| patientId | string | 是 | 患者ID | + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| recordId | string | 记录ID | +| recordDate | string | 记录日期 | +| treatmentCount | int | 替妥尤单抗使用次数 | +| leftEye | decimal | 左眼凸眼度(mm) | +| rightEye | decimal | 右眼凸眼度(mm) | +| interorbitalDistance | decimal | 框间距(mm) | +| isBaseline | int | 是否基准照(0-否,1-是) | +| photoCount | int | 照片数量 | +| firstPhotoUrl | string | 第一张角度图片 | --- -### 2.6 删除记录 +### 3.2 获取患者所有突眼记录列表 -| 项目 | 内容 | -| ---------------- | ------------------------------ | -| **接口路径** | ?r=xd/protrusion/record-delete | -| **请求方式** | POST | -| **是否需要登录** | 是 | +#### 接口信息 +- **接口路径**: `/?r=xd/doctor/proptosis/list` +- **请求方式**: GET +- **代码位置**: `shop/modules/xd_frontend/controllers/doctor/ProptosisController.php` +- **认证方式**: 内部获取当前登录医生ID #### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| patientId | string | 是 | 患者ID | +| page | int | 否 | 页码(默认1) | +| pageSize | int | 否 | 每页数量(默认10) | + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| list[].recordId | string | 记录ID | +| list[].recordDate | string | 记录日期 | +| list[].treatmentCount | int | 替妥尤单抗使用次数 | +| list[].leftEye | decimal | 左眼凸眼度(mm) | +| list[].rightEye | decimal | 右眼凸眼度(mm) | +| list[].interorbitalDistance | decimal | 框间距(mm) | +| list[].isBaseline | int | 是否基准照(0-否,1-是) | +| list[].photoCount | int | 照片数量 | +| list[].firstPhotoUrl | string | 第一张角度图片 | +| list[].uploadCompleted | int | 上传是否完成 | +| pagination.total | int | 总记录数 | -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---- | ---- | ------ | -| recordId | int | 是 | 记录ID | +--- -#### 响应示例 +### 3.3 获取患者某条突眼记录详情 -```json -{ - "code": 0, - "data": { - "success": true - } -} -``` +#### 接口信息 +- **接口路径**: `/?r=xd/doctor/proptosis/detail` +- **请求方式**: GET +- **代码位置**: `shop/modules/xd_frontend/controllers/doctor/ProptosisController.php` +- **认证方式**: 内部获取当前登录医生ID -> **注意**: 删除为软删除，仅更新状态，不实际删除数据 +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| recordId | string | 是 | 记录ID | + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| recordId | string | 记录ID | +| userId | string | 用户ID | +| patientId | string | 患者ID | +| recordDate | string | 记录日期 | +| treatmentCount | int | 替妥尤单抗使用次数 | +| isBaseline | int | 是否基准照(0-否,1-是) | +| leftEye | decimal | 左眼凸眼度(mm) | +| rightEye | decimal | 右眼凸眼度(mm) | +| interorbitalDistance | decimal | 框间距(mm) | +| uploadCompleted | int | 上传是否完成(0-未完成,1-已完成) | +| photos[] | array | 照片列表 | +| photos[].photoId | string | 照片ID | +| photos[].photoAngle | string | 照片角度 | +| photos[].photoAngleName | string | 照片角度名称 | +| photos[].photoUrl | string | 照片链接 | +| photos[].uploadTime | string | 上传时间 | --- -### 2.7 获取可对比记录列表 +### 3.4 获取患者凸眼度对比(Excel导出) -| 项目 | 内容 | -| ---------------- | ---------------------------------- | -| **接口路径** | ?r=xd/protrusion/compare-date-list | -| **请求方式** | GET | -| **是否需要登录** | 是 | +#### 接口信息 +- **接口路径**: `/?r=xd/doctor/proptosis/export` +- **请求方式**: GET +- **代码位置**: `shop/modules/xd_frontend/controllers/doctor/ProptosisController.php` +- **认证方式**: 内部获取当前登录医生ID #### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| patientId | string | 是 | 患者ID | + +#### 返回格式 +- **Content-Type**: application/vnd.ms-excel +- **Content-Disposition**: attachment; filename="凸眼度对比_日期.xlsx" + +#### Excel数据格式 +| 列名 | 说明 | +|------|------| +| 日期 | 记录日期 | +| 替妥尤输入次数 | 替妥尤单抗使用次数 | +| 左眼度 | 左眼凸眼度(mm) | +| 右眼度 | 右眼凸眼度(mm) | +| 框间距 | 框间距(mm) | -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ------------ | -| angle | string | 是 | 照片角度标识 | +--- -#### 响应示例 +### 3.5 获取患者凸眼照对比数据（统一使用recordIds） + +#### 接口信息 +- **接口路径**: `/?r=xd/doctor/proptosis/compare` +- **请求方式**: GET +- **代码位置**: `shop/modules/xd_frontend/controllers/doctor/ProptosisController.php` +- **认证方式**: 内部获取当前登录医生ID + +#### 请求参数（修订） +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| patientId | string | 是 | 患者ID | +| photoAngle | string | 是 | 照片角度 | +| recordIds | string | 否 | 需对比的记录ID列表(多个用逗号分隔，与患者端一致) | + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| baseline | object | 基准照信息 | +| baseline.recordId | string | 记录ID | +| baseline.recordDate | string | 记录日期 | +| baseline.photoUrl | string | 照片链接 | +| baseline.leftEye | decimal | 左眼凸眼度(mm) | +| baseline.rightEye | decimal | 右眼凸眼度(mm) | +| baseline.interorbitalDistance | decimal | 框间距(mm) | +| baseline.treatmentCount | int | 替妥尤使用次数 | +| compareList[] | array | 对比记录列表 | +| compareList[].recordId | string | 记录ID | +| compareList[].recordDate | string | 记录日期 | +| compareList[].photoUrl | string | 照片链接 | +| compareList[].leftEye | decimal | 左眼凸眼度(mm) | +| compareList[].rightEye | decimal | 右眼凸眼度(mm) | +| compareList[].interorbitalDistance | decimal | 框间距(mm) | +| compareList[].treatmentCount | int | 替妥尤使用次数 | -```json -{ - "code": 0, - "data": { - "angleName": "正面睁眼", - "recordList": [ - { - "recordId": 5, - "recordDate": "2026-04-10" - }, - { - "recordId": 8, - "recordDate": "2026-05-15" - } - ] - } -} -``` +--- + +### 3.6 获取对比角度列表 -#### 返回字段说明 +#### 接口信息 +- **接口路径**: `/?r=xd/doctor/proptosis/get-compare-angle` +- **请求方式**: GET +- **代码位置**: `shop/modules/xd_frontend/controllers/doctor/ProptosisController.php` +- **认证方式**: 内部获取当前登录医生ID -| 字段名 | 类型 | 说明 | -| ---------- | ------ | ------------------------ | -| angleName | string | 当前角度中文名称 | -| recordList | array | 记录列表（不包含基准照） | -| recordId | int | 记录ID | -| recordDate | string | 记录日期 | +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| photoAngle | object | 对比角度列表 | +| photoAngle.front_open | string | 正面睁眼 | +| photoAngle.front_closed | string | 正面闭眼 | +| photoAngle.front_looking_up | string | 正面仰头 | +| photoAngle.side_left_90 | string | 90°左侧 | +| photoAngle.side_right_90 | string | 90°右侧 | +| photoAngle.side_left_45 | string | 45°左侧 | +| photoAngle.side_right_45 | string | 45°右侧 | +| photoAngle.eye_up_left | string | 左上 | +| photoAngle.eye_up | string | 向上 | +| photoAngle.eye_up_right | string | 右上 | +| photoAngle.eye_left | string | 向左 | +| photoAngle.eye_right | string | 向右 | +| photoAngle.eye_down_left | string | 左下 | +| photoAngle.eye_down | string | 向下 | +| photoAngle.eye_down_right | string | 右下 | --- -### 2.8 获取对比详情 +## 四、管理后台接口 -| 项目 | 内容 | -| ---------------- | ------------------------------- | -| **接口路径** | ?r=xd/protrusion/compare-detail | -| **请求方式** | GET | -| **是否需要登录** | 是 | +### 4.1 获取图片列表 + +#### 接口信息 +- **接口路径**: `/?r=photo/list` +- **请求方式**: GET +- **代码位置**: `shop/family/controller/PhotoController.php` +- **认证方式**: 内部获取当前登录管理员ID #### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| page | int | 否 | 页码(默认1) | +| pageSize | int | 否 | 每页数量(默认10) | +| userId | string | 否 | 用户ID | +| patientId | string | 否 | 患者ID | +| startDate | string | 否 | 开始日期(YYYY-MM-DD) | +| endDate | string | 否 | 结束日期(YYYY-MM-DD) | +| checkStatus | int | 否 | 审核状态(1-机审通过,2-机审不通过,3-人工审核不通过) | + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| list[].photoId | string | 照片ID | +| list[].submitTime | string | 提交时间 | +| list[].doctorName | string | 邀约医生 | +| list[].userIdentity | string | 用户身份 | +| list[].userName | string | 用户姓名 | +| list[].photoAngle | string | 拍摄角度 | +| list[].photoAngleName | string | 拍摄角度名称 | +| list[].photoUrl | string | 拍摄图片 | +| list[].checkStatus | int | 审核状态(1-机审通过,2-机审不通过,3-人工审核不通过) | +| list[].operation | object | 可操作信息 | +| list[].operation.canReject | bool | 是否可驳回 | +| pagination.total | int | 总记录数 | + +#### 业务规则 +- 机审通过(状态1)时，显示"审核驳回"按钮 +- 机审不通过(状态2)时，无操作按钮 +- 人工审核不通过(状态3)时，无操作按钮 -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ------ | ---- | ---------------------- | -| angle | string | 是 | 照片角度标识 | -| recordIds | string | 是 | 记录ID，多个用逗号分隔 | +--- -#### 响应示例 +### 4.2 人工审核驳回 -```json -{ - "code": 0, - "data": { - "angleName": "正面睁眼", - "baselineRecord": { - "recordId": 1, - "recordDate": "2026-01-01", - "treatmentCount": 0, - "leftEye": 20.0, - "rightEye": 20.5, - "interorbitalDistance": 100.0, - "photoUrl": "http://example.com/baseline.jpg" - }, - "compareRecords": [ - { - "recordId": 5, - "recordDate": "2026-04-10", - "treatmentCount": 3, - "leftEye": 18.5, - "rightEye": 19.0, - "interorbitalDistance": 95.0, - "photoUrl": "http://example.com/compare1.jpg" - }, - { - "recordId": 8, - "recordDate": "2026-05-15", - "treatmentCount": 5, - "leftEye": 17.5, - "rightEye": 18.0, - "interorbitalDistance": 92.0, - "photoUrl": "http://example.com/compare2.jpg" - } - ] - } -} -``` +#### 接口信息 +- **接口路径**: `/?r=photo/reject` +- **请求方式**: POST +- **代码位置**: `shop/family/controller/PhotoController.php` +- **认证方式**: 内部获取当前登录管理员ID +- **Content-Type**: application/json -#### 返回字段说明 +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| photoId | string | 是 | 照片ID | -| 字段名 | 类型 | 说明 | -| -------------- | ------ | ---------------- | -| angleName | string | 当前角度中文名称 | -| baselineRecord | object | 基准照记录 | -| compareRecords | array | 对比记录列表 | +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| success | bool | 是否成功 | --- -### 2.9 获取角度选项 +### 4.3 获取系统配置 -| 项目 | 内容 | -| ---------------- | ------------------------------ | -| **接口路径** | ?r=xd/protrusion/angle-options | -| **请求方式** | GET | -| **是否需要登录** | 否 | +#### 接口信息 +- **接口路径**: `/?r=settings/get-proptosis-config` +- **请求方式**: GET +- **代码位置**: `shop/family/controller/SettingsController.php` +- **认证方式**: 内部获取当前登录管理员ID -#### 响应示例 +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| configKey | string | 否 | 配置键(不传则返回所有配置) | -```json -{ - "code": 0, - "data": { - "frontOpen": "正面睁眼", - "frontClose": "正面闭眼", - "frontUp": "正面仰头", - "sideLeft90": "90°左侧", - "sideRight90": "90°右侧", - "sideLeft45": "45°左侧", - "sideRight45": "45°右侧", - "eyeUpLeft": "左上", - "eyeUp": "向上", - "eyeUpRight": "右上", - "eyeLeft": "向左", - "eyeRight": "向右", - "eyeDownLeft": "左下", - "eyeDown": "向下", - "eyeDownRight": "右下" - } -} -``` +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| configKey | string | 配置键 | +| configValue | string | 配置值 | +| description | string | 配置描述 | + +--- + +### 4.4 设置系统配置 + +#### 接口信息 +- **接口路径**: `/?r=settings/set-proptosis-config` +- **请求方式**: POST +- **代码位置**: `shop/family/controller/SettingsController.php` +- **认证方式**: 内部获取当前登录管理员ID +- **Content-Type**: application/json + +#### 请求参数 +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| configKey | string | 是 | 配置键 | +| configValue | string | 是 | 配置值 | +| description | string | 否 | 配置描述 | + +#### 预置配置 +- `proptosis_continue_on_failed`: 不合规图片是否继续(1-是,0-否) + +#### 返回字段 +| 字段名 | 类型 | 说明 | +|--------|------|------| +| success | bool | 是否成功 | --- -## 三、错误码说明 +## 五、腾讯云IMS集成说明 + +### 5.1 图片内容安全校验 +- 调用腾讯云图片内容安全(Image Moderation)接口 +- 检测图片是否包含违规内容(色情、暴力等) +- 同步返回检测结果 + +### 5.2 配置项说明（使用t_settings表） +| 配置键 | 配置值 | 说明 | +|--------|--------|------| +| proptosis_continue_on_failed | 1 | 不合规图片允许继续上传 | +| proptosis_continue_on_failed | 0 | 不合规图片不允许继续上传(报错) | -| 错误码 | 说明 | -| ------ | -------- | -| 0 | 成功 | -| 1 | 通用错误 | -| 403 | 需要登录 | +### 5.3 校验结果处理 +| 校验结果 | 配置值 | 返回状态 | 是否允许继续 | +|----------|--------|----------|--------------| +| 通过 | - | 1(机审通过) | 是 | +| 不通过 | 1(继续) | 2(机审不通过) | 是 | +| 不通过 | 0(不继续) | 2(机审不通过) | 否 | --- -## 四、注意事项 +## 六、代码文件结构 -1. **UserId获取**: 用户ID从登录上下文中自动获取，无需传入 -2. **基准照唯一性**: 设置新基准照时，系统会自动取消之前的基准照 -3. **照片上传**: 照片为URL链接，物理文件存储在其他服务器 -4. **软删除**: 删除记录采用软删除方式 -5. **记录完整性**: 当photoCount达到15时，uploadCompleted自动变为1 +``` +shop/ +├── modules/ +│ └── xd_frontend/ +│ └── controllers/ +│ ├── ProptosisController.php # 患者端控制器 +│ └── doctor/ +│ └── ProptosisController.php # 医生端控制器 +└── family/ + └── controller/ + ├── PhotoController.php # 管理后台-图片管理 + └── SettingsController.php # 管理后台-配置管理 +```