# BD 手册：auth.users.avatar_url 字段

## 概述

`auth.users` 表新增 `avatar_url` 字段，存储用户头像的相对路径。

## 字段定义

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `avatar_url` | `VARCHAR(500)` | `NULL` | 头像相对路径，格式 `avatars/{user_id}.jpg` |

## 数据流

1. 小程序端通过 `<button open-type="chooseAvatar">` 获取微信头像临时路径
2. 通过 `wx.uploadFile` 上传到 `POST /api/xcx/avatar/upload`
3. 后端保存文件到 `AVATAR_EXPORT_PATH/{user_id}.jpg`（覆盖式，幂等）
4. 数据库 `avatar_url` 更新为 `avatars/{user_id}.jpg`（相对路径）
5. 小程序通过 `GET /api/xcx/avatar/{user_id}` 获取头像文件

## 关联接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/xcx/avatar/upload` | POST | 上传头像，更新 avatar_url |
| `/api/xcx/avatar/{user_id}` | GET | 获取头像文件（FileResponse） |
| `/api/xcx/me` | GET | 返回 avatar_url 字段 |

## 设计决策

- 审核表 `auth.user_applications` 不冗余 `avatar_url`，通过 JOIN `auth.users` 获取（头像可能更新）
- 文件命名按 `user_id`，覆盖式保存（幂等，无历史版本）
- 文件大小限制 2MB，空文件拒绝

## 迁移脚本

`db/zqyy_app/migrations/20260324_add_avatar_url_to_users.sql`

## 环境变量

`AVATAR_EXPORT_PATH` — 头像文件存储目录，缺失时后端报 500 错误

## 回滚

```sql
ALTER TABLE auth.users DROP COLUMN IF EXISTS avatar_url;
```

## 验证

```sql
SELECT id, avatar_url FROM auth.users WHERE avatar_url IS NOT NULL LIMIT 5;
```