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 患者端 - 记录列表

```typescript
// 接口返回
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 医生端 - 凸眼度对比表格

```typescript
// 接口返回 (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 角度映射

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

```typescript
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或自家服务器）