xinda-miniprogram/.trae/documents/proptosis_api_integration_plan.md

突眼日记接口联调计划

一、项目现状分析

1.1 已有页面结构

医生端 (d_ 前缀)

• d_noteList - 突眼记录列表页（拍摄示例页）

• d_noteDetail - 突眼记录详情页

• d_noteDiffData - 凸眼度对比数据页（表格展示）

患者端 (patient/pages/note)*

• note - 突眼日记首页

• noteAdd - 新增记录页

• noteHistory - 历史记录页

• noteDiff - 照片对比页

• noteDiffEdit - 对比编辑页

• noteDemo - 拍摄示例页

1.2 当前状态

• 所有页面都是静态数据，未接入接口

• 请求工具已封装在 utils/request.ts

• 使用 wx.ajax 进行接口调用（在 app.ts 中挂载）

---

二、需要的信息

在开始联调前，需要你提供以下信息：

2.1 环境信息

信息项	说明	是否必需
后端环境地址	开发/测试服务器地址	是
接口是否已部署	后端接口是否已上线可调用	是
登录态获取方式	如何获取 loginState/session	是

2.2 接口测试信息

信息项	说明	是否必需
测试账号	医生账号和患者账号	是
测试患者ID	用于医生端接口测试	是
已有数据	是否有已创建的突眼记录数据	否

2.3 图片上传相关

信息项	说明	是否必需
图片上传方式	上传到腾讯云COS还是自家服务器	是
腾讯云IMS配置	是否已配置图片内容安全校验	否

---

三、接口联调清单

3.1 患者端接口 (10个)

序号	接口	用途	对应页面	优先级
1	baseline-status	获取基准照状态	note	P0
2	record-list	获取记录列表	note, noteHistory	P0
3	record-detail	获取记录详情	noteHistory	P0
4	record-save	创建/更新记录	noteAdd	P0
5	photo-upload	上传照片	noteAdd	P0
6	record-delete	删除记录	noteHistory	P1
7	compare-dates	获取对比可用日期	noteDiff	P1
8	compare-photos	获取对比照片	noteDiff	P1
9	get-compare-angle	获取对比角度列表	noteDiffEdit	P1
10	get-session-id	获取唯一标识	noteAdd	P2

3.2 医生端接口 (6个)

序号	接口	用途	对应页面	优先级
1	doctor/proptosis/latest	获取最近记录	d_patientDetail	P0
2	doctor/proptosis/list	获取患者记录列表	d_noteList	P0
3	doctor/proptosis/detail	获取记录详情	d_noteDetail	P0
4	doctor/proptosis/export	Excel导出	d_noteDiffData	P1
5	doctor/proptosis/compare	获取对比数据	d_noteDiffData	P1
6	doctor/proptosis/get-compare-angle	获取对比角度	d_noteDiffData	P1

---

四、实施步骤

Phase 1: 基础联调准备

1. 确认后端环境可用
2. 获取测试账号和患者ID
3. 验证登录态获取

Phase 2: 患者端核心功能

1. 实现记录列表获取 (record-list)
2. 实现记录详情获取 (record-detail)
3. 实现记录创建/更新 (record-save)
4. 实现照片上传 (photo-upload)

Phase 3: 患者端对比功能

1. 实现对比日期获取 (compare-dates)
2. 实现对比照片获取 (compare-photos)
3. 实现对比角度获取 (get-compare-angle)

Phase 4: 医生端功能

1. 实现患者最近记录获取 (doctor/proptosis/latest)
2. 实现患者记录列表 (doctor/proptosis/list)
3. 实现记录详情 (doctor/proptosis/detail)
4. 实现对比数据获取 (doctor/proptosis/compare)

Phase 5: 导出功能

1. 实现Excel导出 (doctor/proptosis/export)

---

五、数据结构映射

5.1 患者端 - 记录列表

// 接口返回
interface RecordItem {
  recordId: string
  recordDate: string
  isBaseline: number
  photoCount: number
  firstPhotoUrl: string
  treatmentCount: number
  leftEye: number
  rightEye: number
  interorbitalDistance: number
  uploadCompleted: number
}

// 页面使用
interface DataListItem {
  date: string // recordDate 格式化
  left: string // leftEye
  spacing: string // interorbitalDistance
  right: string // rightEye
  count: string // treatmentCount
  isBaseline: boolean
  photoCount: number
  firstPhotoUrl: string
}

5.2 医生端 - 凸眼度对比表格

// 接口返回 (compare 接口)
interface CompareItem {
  recordId: string
  recordDate: string
  photoUrl: string
  leftEye: number
  rightEye: number
  interorbitalDistance: number
  treatmentCount: number
}

// 页面使用 (d_noteDiffData)
interface TableItem {
  date: string // recordDate 格式化 2026.1.5
  left: string // leftEye
  spacing: string // interorbitalDistance
  right: string // rightEye
  count: string // treatmentCount
}

---

六、注意事项

6.1 业务规则

1. 同一天只能创建一条记录
2. 必须先上传照片再保存记录（photoIds 关联）
3. 基准照只能有一张
4. 图片需要经过腾讯云IMS安全校验

6.2 技术注意

1. 使用 wx.ajax 进行请求（已挂载在 app 上）
2. 医生端页面需要等待登录态 app.waitLogin({ type: [2] })
3. 患者端页面需要等待登录态 app.waitLogin({ type: [1] })
4. 图片URL需要拼接 {{imageUrl}} 前缀

6.3 角度映射

接口角度值与页面显示名称映射：

const angleMap = {
  front_open: '正面睁眼',
  front_closed: '正面闭眼',
  front_looking_up: '正面仰头',
  side_left_90: '90°左侧',
  side_right_90: '90°右侧',
  side_left_45: '45°左侧',
  side_right_45: '45°右侧',
  eye_up_left: '左上',
  eye_up: '向上',
  eye_up_right: '右上',
  eye_left: '向左',
  eye_right: '向右',
  eye_down_left: '左下',
  eye_down: '向下',
  eye_down_right: '右下',
}

---

七、下一步

请提供以下信息，我将开始实施联调：

1. 后端环境地址（如：https://m.xd.hbraas.com）
2. 测试账号（医生和患者各一个）
3. 测试患者ID（用于医生端接口测试）
4. 接口是否已部署（确认后端已完成开发）
5. 图片上传方式（腾讯云COS或自家服务器）