yl-frontend/api-docs/profile-api.txt

个人中心模块接口文档
================

基础信息
-------
- 基础路径: /api/v1/profile
- 请求方式: REST
- 数据格式: JSON
- 认证方式: Bearer Token

数据结构
-------

UserProfile 用户资料对象:
{
  id: number,          // 用户ID
  name: string,        // 姓名
  avatar: string,      // 头像URL
  gender: string,      // 性别
  age: number,         // 年龄
  phone: string,       // 手机号
  email: string,       // 邮箱
  address: string,     // 地址
  emergencyContacts: [ // 紧急联系人
    {
      id: number,      // 联系人ID
      name: string,    // 联系人姓名
      relation: string,// 关系
      phone: string,   // 联系电话
      isDefault: boolean // 是否默认联系人
    }
  ],
  healthInfo: {        // 健康信息
    bloodType: string, // 血型
    allergies: string[], // 过敏史
    chronicDiseases: string[], // 慢性病
    medications: string[], // 在服用的药物
    height: number,    // 身高(cm)
    weight: number     // 体重(kg)
  },
  preferences: {       // 偏好设置
    theme: string,     // 主题
    fontSize: number,  // 字体大小
    notification: boolean, // 通知开关
    language: string,  // 语言
    accessibility: {   // 无障碍设置
      voiceControl: boolean,
      highContrast: boolean,
      textToSpeech: boolean
    }
  }
}

API 接口
-------

1. 获取用户资料
GET /api/v1/profile

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    // UserProfile对象
  }
}

2. 更新基本信息
PUT /api/v1/profile

请求参数：
{
  "name": "张三",
  "gender": "男",
  "age": 65,
  "address": "北京市朝阳区..."
}

3. 更新头像
POST /api/v1/profile/avatar
Content-Type: multipart/form-data

请求参数：
| 参数名 | 类型 | 必填 | 说明 |
| file  | File | 是   | 头像图片文件 |

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "avatarUrl": "https://example.com/avatar.jpg"
  }
}

4. 添加紧急联系人
POST /api/v1/profile/emergency-contacts

请求参数：
{
  "name": "张小明",
  "relation": "子女",
  "phone": "13900139000",
  "isDefault": true
}

5. 删除紧急联系人
DELETE /api/v1/profile/emergency-contacts/{id}

6. 设置默认联系人
PUT /api/v1/profile/emergency-contacts/{id}/default

7. 更新健康信息
PUT /api/v1/profile/health-info

请求参数：
{
  "bloodType": "A",
  "allergies": ["花粉", "海鲜"],
  "chronicDiseases": ["高血压"],
  "medications": ["降压药"],
  "height": 170,
  "weight": 65
}

8. 更新偏好设置
PUT /api/v1/profile/preferences

请求参数：
{
  "theme": "light",
  "fontSize": 16,
  "notification": true,
  "language": "zh-CN",
  "accessibility": {
    "voiceControl": true,
    "highContrast": false,
    "textToSpeech": true
  }
}

9. 修改密码
PUT /api/v1/profile/password

请求参数：
{
  "oldPassword": "旧密码",
  "newPassword": "新密码"
}

10. 验证手机号
POST /api/v1/profile/verify-phone

请求参数：
{
  "phone": "13800138000",
  "code": "123456"
}

11. 发送验证码
POST /api/v1/profile/send-code

请求参数：
{
  "phone": "13800138000"
}

12. 绑定邮箱
POST /api/v1/profile/bind-email

请求参数：
{
  "email": "example@example.com",
  "code": "123456"
}

13. 获取账号安全等级
GET /api/v1/profile/security-level

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "level": "medium",
    "score": 75,
    "suggestions": [
      "建议开启双因素认证",
      "定期更新密码",
      "绑定备用手机号"
    ]
  }
}

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

注意事项
-------
1. 头像上传要求：
   - 支持格式：jpg、png
   - 大小限制：2MB
   - 建议尺寸：200x200px

2. 密码要求：
   - 长度：8-20位
   - 必须包含数字和字母
   - 不能与前3次使用的密码相同

3. 验证码规则：
   - 有效期：5分钟
   - 每天最多发送5次
   - 连续错误5次后锁定1小时

4. 安全建议：
   - 定期更新密码
   - 及时验证紧急联系方式
   - 保持联系人信息最新

5. 缓存策略：
   - 基本信息缓存：5分钟
   - 头像缓存：1小时
   - 设置缓存：即时失效