From e7fe92b8634fb477901cb522b0a424f6fb87cd7d Mon Sep 17 00:00:00 2001
From: stu2not <stu2not@stu2notdeMac-mini.local>
Date: Thu, 16 Apr 2026 18:21:54 +0800
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E5=B0=8F=E7=A8=8B=E5=BA=8F?=
 =?UTF-8?q?=E5=90=8E=E7=AB=AF=20API=20=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 mini-program/docs/api.md | 155 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 150 insertions(+), 5 deletions(-)

diff --git a/mini-program/docs/api.md b/mini-program/docs/api.md
index 9ae5f15..d257007 100644
--- a/mini-program/docs/api.md
+++ b/mini-program/docs/api.md
@@ -38,18 +38,25 @@ http://127.0.0.1:8001
 
 用途：
 
-- 用户登录并获取访问令牌（access token）。
-- 当前示例账号：`test1/test2/test3`，密码均为 `123`。
+- 小程序端上传 `wx.login` 返回的一次性 `code`。
+- 服务端调用微信 `code2Session` 换取真实 `openid/unionid`，并签发本地访问令牌。
 
 请求体：
 
 ```json
 {
-  "username": "test1",
-  "password": "123"
+  "code": "0312abcdEFGHijklMNopqrstUVwxYZ12",
+  "nickname": "家长昵称",
+  "avatar_url": "https://thirdwx.qlogo.cn/mmopen/xxx/132"
 }
 ```
 
+字段说明：
+
+- `code`：必填，来自微信 `wx.login` / `Taro.login`
+- `nickname`：可选，仅作为资料字段
+- `avatar_url`：可选，仅作为资料字段
+
 成功响应（`200`）：
 
 ```json
@@ -63,8 +70,10 @@ http://127.0.0.1:8001
 
 常见错误码：
 
-- `401`：用户名或密码错误，或账号不可用
+- `401`：微信 `code` 无效、已过期或已被使用
 - `422`：请求参数校验失败
+- `502`：微信登录服务不可用或返回异常数据
+- `503`：服务端未配置正确的微信小程序凭证
 
 ## 3. 发送消息
 
@@ -218,3 +227,139 @@ GET /messages?conversation_id=1&cursor_seq=50&limit=20
 - `403`：无权限读取该会话
 - `404`：会话不存在
 - `422`：请求参数校验失败
+
+## 5. 家长头像
+
+### `POST /parents/me/avatar`
+
+用途：
+
+- 上传当前登录用户头像到 COS 头像桶。
+- 服务端会将 COS `avatar_file_key` 写入数据库，并在响应中返回可用的 `avatar_url`。
+
+请求头：
+
+```
+Authorization: Bearer <access_token>
+Content-Type: multipart/form-data
+```
+
+表单字段：
+
+- `file`：头像图片文件，支持 `jpg/jpeg/png/webp`
+
+成功响应（`200`）：
+
+```json
+{
+  "user_id": 1,
+  "openid": "wx_xxx",
+  "unionid": null,
+  "nickname": "Parent A",
+  "avatar_url": "https://ava-1320289366.cos.ap-guangzhou.myqcloud.com/...",
+  "phone": null,
+  "status": 1
+}
+```
+
+常见错误码：
+
+- `401`：未登录或 token 无效
+- `404`：当前用户不存在
+- `413`：头像文件过大
+- `415`：头像文件类型不支持
+
+### `GET /parents/{user_id}/avatar`
+
+用途：
+
+- 获取指定用户头像的可访问 URL。
+- 如果数据库里存的是 COS `avatar_file_key`，服务端会返回短时有效的签名 URL。
+- 如果数据库里仍是旧的 `avatar_url`，服务端会直接返回旧 URL。
+
+请求头：
+
+```
+Authorization: Bearer <access_token>
+```
+
+成功响应（`200`）：
+
+```json
+{
+  "avatar_url": "https://ava-1320289366.cos.ap-guangzhou.myqcloud.com/...",
+  "expires_in": 86400
+}
+```
+
+常见错误码：
+
+- `401`：未登录或 token 无效
+- `404`：用户不存在或未设置头像
+
+## 6. 设备绑定列表
+
+### `GET /bindings`
+
+用途：
+
+- 查询当前登录家长名下的全部有效绑定设备。
+- 返回结果包含 `child_name`，可直接用于首页设备卡片展示。
+- 返回结果按最新绑定记录优先排序。
+
+请求头：
+
+```
+Authorization: Bearer <access_token>
+```
+
+Query 参数：
+
+- `cursor`（可选）：`int >= 1`，用于向后翻页
+- `limit`（可选）：默认 `20`，最大 `100`
+
+请求示例：
+
+```
+GET /bindings
+GET /bindings?cursor=120&limit=20
+```
+
+成功响应（`200`）：
+
+```json
+{
+  "items": [
+    {
+      "device_id": "DEV-002",
+      "child_id": null,
+      "child_name": null,
+      "status": 1,
+      "bound_at": "2026-04-16T18:00:00"
+    },
+    {
+      "device_id": "DEV-001",
+      "child_id": 10,
+      "child_name": "小明",
+      "status": 1,
+      "bound_at": "2026-04-16T17:30:00"
+    }
+  ],
+  "total": 2,
+  "next_cursor": null
+}
+```
+
+字段说明：
+
+- `device_id`：设备业务标识
+- `child_id`：当前绑定儿童 ID，可为空
+- `child_name`：当前绑定儿童昵称，可为空
+- `status`：绑定状态，当前列表只返回有效绑定
+- `bound_at`：设备绑定时间
+- `next_cursor`：下一页游标，没有更多数据时为 `null`
+
+常见错误码：
+
+- `401`：未登录或 token 无效
+- `422`：请求参数校验失败