# 突眼日记接口文档 ## 一、接口概览 ### 1.1 基本信息 - **模块名称**: 突眼日记 - **控制器路径**: modules\xd_frontend\controllers\ProtrusionController - **接口前缀**: ?r=xd/protrusion - **请求方式**: 需要登录（Header中传入loginState） ### 1.2 响应格式 ```json // 成功响应 { "code": 0, "data": { // 业务数据 } } // 失败响应 { "code": 1, "msg": "错误信息" } ``` --- ## 二、接口详情 ### 2.1 获取基准照状态 | 项目 | 内容 | | ---------------- | -------------------------------- | | **接口路径** | ?r=xd/protrusion/baseline-status | | **请求方式** | GET | | **是否需要登录** | 是 | #### 响应示例 ```json { "code": 0, "data": { "hasBaseline": true, "baselineRecordId": 1 } } ``` #### 返回字段说明 | 字段名 | 类型 | 说明 | | ---------------- | ---- | --------------------- | | hasBaseline | bool | 是否已设置基准照 | | baselineRecordId | int | 基准照记录ID(无则为0) | --- ### 2.2 获取记录列表 | 项目 | 内容 | | ---------------- | ---------------------------- | | **接口路径** | ?r=xd/protrusion/record-list | | **请求方式** | GET | | **是否需要登录** | 是 | #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | | -------- | ---- | ---- | ---------------- | | page | int | 否 | 页码，默认1 | | pageSize | int | 否 | 每页数量，默认10 | #### 响应示例 ```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 } } ``` #### 返回字段说明 | 字段名 | 类型 | 说明 | | -------------------- | ------ | ----------------------------- | | 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 | 当前页码 | --- ### 2.3 新增记录 | 项目 | 内容 | | ---------------- | --------------------------- | | **接口路径** | ?r=xd/protrusion/record-add | | **请求方式** | POST | | **是否需要登录** | 是 | #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | | -------------------- | ------ | ---- | ------------------------------ | | 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 | #### 响应示例 ```json { "code": 0, "data": { "recordId": 1 } } ``` #### 返回字段说明 | 字段名 | 类型 | 说明 | | -------- | ---- | ------------ | | recordId | int | 新增记录的ID | --- ### 2.4 更新记录 | 项目 | 内容 | | ---------------- | ------------------------------ | | **接口路径** | ?r=xd/protrusion/record-update | | **请求方式** | POST | | **是否需要登录** | 是 | #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | | -------------------- | ------ | ---- | ------------------------ | | 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.5 获取记录详情 | 项目 | 内容 | | ---------------- | ------------------------------ | | **接口路径** | ?r=xd/protrusion/record-detail | | **请求方式** | GET | | **是否需要登录** | 是 | #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | | -------- | ---- | ---- | ------ | | recordId | int | 是 | 记录ID | #### 响应示例 ```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" } } ``` #### 返回字段说明 | 字段名 | 类型 | 说明 | | -------------------- | ------ | ------------------ | | 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 | 创建时间 | --- ### 2.6 删除记录 | 项目 | 内容 | | ---------------- | ------------------------------ | | **接口路径** | ?r=xd/protrusion/record-delete | | **请求方式** | POST | | **是否需要登录** | 是 | #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | | -------- | ---- | ---- | ------ | | recordId | int | 是 | 记录ID | #### 响应示例 ```json { "code": 0, "data": { "success": true } } ``` > **注意**: 删除为软删除，仅更新状态，不实际删除数据 --- ### 2.7 获取可对比记录列表 | 项目 | 内容 | | ---------------- | ---------------------------------- | | **接口路径** | ?r=xd/protrusion/compare-date-list | | **请求方式** | GET | | **是否需要登录** | 是 | #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------------ | | angle | string | 是 | 照片角度标识 | #### 响应示例 ```json { "code": 0, "data": { "angleName": "正面睁眼", "recordList": [ { "recordId": 5, "recordDate": "2026-04-10" }, { "recordId": 8, "recordDate": "2026-05-15" } ] } } ``` #### 返回字段说明 | 字段名 | 类型 | 说明 | | ---------- | ------ | ------------------------ | | angleName | string | 当前角度中文名称 | | recordList | array | 记录列表（不包含基准照） | | recordId | int | 记录ID | | recordDate | string | 记录日期 | --- ### 2.8 获取对比详情 | 项目 | 内容 | | ---------------- | ------------------------------- | | **接口路径** | ?r=xd/protrusion/compare-detail | | **请求方式** | GET | | **是否需要登录** | 是 | #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | | --------- | ------ | ---- | ---------------------- | | angle | string | 是 | 照片角度标识 | | recordIds | string | 是 | 记录ID，多个用逗号分隔 | #### 响应示例 ```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" } ] } } ``` #### 返回字段说明 | 字段名 | 类型 | 说明 | | -------------- | ------ | ---------------- | | angleName | string | 当前角度中文名称 | | baselineRecord | object | 基准照记录 | | compareRecords | array | 对比记录列表 | --- ### 2.9 获取角度选项 | 项目 | 内容 | | ---------------- | ------------------------------ | | **接口路径** | ?r=xd/protrusion/angle-options | | **请求方式** | GET | | **是否需要登录** | 否 | #### 响应示例 ```json { "code": 0, "data": { "frontOpen": "正面睁眼", "frontClose": "正面闭眼", "frontUp": "正面仰头", "sideLeft90": "90°左侧", "sideRight90": "90°右侧", "sideLeft45": "45°左侧", "sideRight45": "45°右侧", "eyeUpLeft": "左上", "eyeUp": "向上", "eyeUpRight": "右上", "eyeLeft": "向左", "eyeRight": "向右", "eyeDownLeft": "左下", "eyeDown": "向下", "eyeDownRight": "右下" } } ``` --- ## 三、错误码说明 | 错误码 | 说明 | | ------ | -------- | | 0 | 成功 | | 1 | 通用错误 | | 403 | 需要登录 | --- ## 四、注意事项 1. **UserId获取**: 用户ID从登录上下文中自动获取，无需传入 2. **基准照唯一性**: 设置新基准照时，系统会自动取消之前的基准照 3. **照片上传**: 照片为URL链接，物理文件存储在其他服务器 4. **软删除**: 删除记录采用软删除方式 5. **记录完整性**: 当photoCount达到15时，uploadCompleted自动变为1