信达小程序

29 KiB

Raw Blame History

突眼日记接口文档

一、接口规范

1.1 基本规范

接口路径格式: /?r=xd/xxx (Yii2路由格式)
请求方式: GET / POST
返回格式: JSON
字符编码: UTF-8
用户认证: 通过Session/Token获取用户ID，接口内部逻辑处理

1.2 返回格式

{
  "code": 0,
  "msg": "success",
  "data": {}
}

1.3 错误码说明

错误码	说明
0	成功
400	参数错误
401	未授权
403	禁止访问
404	资源不存在
500	服务器内部错误

二、患者端接口

2.1 获取基准照设置状态

接口信息

接口路径: /?r=xd/proptosis/baseline-status
请求方式: GET
代码位置: shop/modules/xd_frontend/controllers/ProptosisController.php
认证方式: 内部获取当前登录用户ID

返回字段

字段名	类型	说明
hasBaseline	bool	是否已设置基准照
baselineRecordId	string	基准照记录ID(如果有)

2.2 获取突眼记录列表

接口信息

接口路径: /?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.3 获取突眼记录详情

接口信息

接口路径: /?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	上传时间

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

业务流程（修订后）

前端：点击保存按钮时，先调用 photo-checker 上传照片（此时没有recordId，返回临时photoId）
前端：然后调用 record-save 保存基本信息（含photoIds），将照片关联到记录
这样设计是因为只有一个保存按钮，需要先创建记录，再上传照片

业务规则

同一天只能创建一条记录，若已存在返回错误提示："该日期已有记录，同一天不可重复记录"

2.5 上传照片(含图片安全校验)

接口信息

接口路径: /?r=xd/proptosis/photo-checker
请求方式: 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	提示信息

业务流程（调整后）

前端：先调用 photo-checker 上传照片，返回 photoId
前端：再调用 record-save，传入 photoIds 关联照片和记录

同步保存数据

userId（内部获取）
sessionId（可能不存在）
photoUrl
uploadTime
recordId（创建记录后传入）

2.6 删除突眼记录

接口信息

接口路径: /?r=xd/proptosis/record-delete
请求方式: POST
代码位置: shop/modules/xd_frontend/controllers/ProptosisController.php
认证方式: 内部获取当前登录用户ID
Content-Type: application/json

请求参数

参数名	类型	必填	说明
recordId	string	是	记录ID

返回字段

字段名	类型	说明
success	bool	是否成功

2.7 获取对比照片可用日期

接口信息

接口路径: /?r=xd/proptosis/compare-dates
请求方式: GET
代码位置: shop/modules/xd_frontend/controllers/ProptosisController.php
认证方式: 内部获取当前登录用户ID

请求参数

参数名	类型	必填	说明
photoAngle	string	是	照片角度

返回字段

字段名	类型	说明
baseline	object	基准照信息
baseline.recordId	string	记录ID
baseline.recordDate	string	记录日期
nonBaselineList[]	array	非基准照日期列表
nonBaselineList[].recordId	string	记录ID
nonBaselineList[].recordDate	string	记录日期

2.8 根据角度和日期列表获取照片

接口信息

接口路径: /?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	替妥尤使用次数

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.10 获取唯一标识

接口信息

接口路径: /?r=xd/proptosis/get-session-id
请求方式: GET
代码位置: shop/modules/xd_frontend/controllers/ProptosisController.php
认证方式: 内部获取当前登录用户ID

请求参数

参数名	类型	必填	说明

返回字段

字段名	类型	说明
sessionId	string	唯一标识

三、医生端接口

3.1 获取患者最近的突眼记录

接口信息

接口路径: /?r=xd/doctor/proptosis/latest
请求方式: GET
代码位置: shop/modules/xd_frontend/controllers/doctor/ProptosisController.php
认证方式: 内部获取当前登录医生ID

请求参数

参数名	类型	必填	说明
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	第一张角度图片

3.2 获取患者所有突眼记录列表

接口信息

接口路径: /?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	总记录数

3.3 获取患者某条突眼记录详情

接口信息

接口路径: /?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	上传时间

3.4 获取患者凸眼度对比(Excel导出)

接口信息

接口路径: /?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)

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	替妥尤使用次数

3.6 获取对比角度列表

接口信息

接口路径: /?r=xd/doctor/proptosis/get-compare-angle
请求方式: GET
代码位置: shop/modules/xd_frontend/controllers/doctor/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	右下

3.7 获取对比照片可用日期

接口信息

接口路径: /?r=xd/doctor/proptosis/compare-dates
请求方式: GET
代码位置: shop/modules/xd_frontend/controllers/doctor/ProptosisController.php
认证方式: 内部获取当前登录医生ID

请求参数

参数名	类型	必填	说明
patientId	string	是	患者ID
photoAngle	string	是	照片角度

返回字段

字段名	类型	说明
baseline	object	基准照信息
baseline.recordId	string	记录ID
baseline.recordDate	string	记录日期
nonBaselineList[]	array	非基准照日期列表
nonBaselineList[].recordId	string	记录ID
nonBaselineList[].recordDate	string	记录日期

四、管理后台接口

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)时，无操作按钮

4.2 人工审核驳回

接口信息

接口路径: /?r=photo/reject
请求方式: POST
代码位置: shop/family/controller/PhotoController.php
认证方式: 内部获取当前登录管理员ID
Content-Type: application/json

请求参数

参数名	类型	必填	说明
photoId	string	是	照片ID

返回字段

字段名	类型	说明
success	bool	是否成功

4.3 获取系统配置

接口信息

接口路径: /?r=settings/get-proptosis-config
请求方式: GET
代码位置: shop/family/controller/SettingsController.php
认证方式: 内部获取当前登录管理员ID

请求参数

参数名	类型	必填	说明
configKey	string	否	配置键(不传则返回所有配置)

返回字段

字段名	类型	说明
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	不合规图片不允许继续上传(报错)

5.3 校验结果处理

校验结果	配置值	返回状态	是否允许继续
通过	-	1(机审通过)	是
不通过	1(继续)	2(机审不通过)	是
不通过	0(不继续)	2(机审不通过)	否

六、代码文件结构

shop/
├── modules/
│   └── xd_frontend/
│       └── controllers/
│           ├── ProptosisController.php       # 患者端控制器
│           └── doctor/
│               └── ProptosisController.php   # 医生端控制器
└── family/
    └── controller/
        ├── PhotoController.php               # 管理后台-图片管理
        └── SettingsController.php           # 管理后台-配置管理

29 KiB Raw Blame History

突眼日记接口文档

一、接口规范

1.1 基本规范

1.2 返回格式

1.3 错误码说明

二、患者端接口

2.1 获取基准照设置状态

接口信息

返回字段

2.2 获取突眼记录列表

接口信息

请求参数

返回字段

2.3 获取突眼记录详情

接口信息

请求参数

返回字段

2.4 创建/更新突眼记录（含图片ID列表）

接口信息

请求参数（修订）

返回字段

业务流程（修订后）

业务规则

2.5 上传照片(含图片安全校验)

接口信息

请求参数

返回字段

业务流程（调整后）

同步保存数据

2.6 删除突眼记录

接口信息

请求参数

返回字段

2.7 获取对比照片可用日期

接口信息

请求参数

返回字段

2.8 根据角度和日期列表获取照片

接口信息

请求参数

返回字段

2.9 获取对比角度列表

接口信息

请求参数

返回字段

2.10 获取唯一标识

接口信息

请求参数

返回字段

三、医生端接口

3.1 获取患者最近的突眼记录

接口信息

请求参数

返回字段

3.2 获取患者所有突眼记录列表

接口信息

请求参数

返回字段

3.3 获取患者某条突眼记录详情

接口信息

请求参数

返回字段

3.4 获取患者凸眼度对比(Excel导出)

接口信息

请求参数

返回格式

Excel数据格式

3.5 获取患者凸眼照对比数据（统一使用recordIds）

接口信息

请求参数（修订）

返回字段

3.6 获取对比角度列表

接口信息

请求参数

返回字段

3.7 获取对比照片可用日期

接口信息

请求参数

返回字段

29 KiB

Raw Blame History