# 用户端个人头像展示修复操作日志

操作时间：2026-09-02

操作类型：修改、扩展

影响模块：用户端 Flutter App 个人中心、用户端头像读取接口

## 操作前状态

个人资料接口和领域模型已包含 `avatar` 字段，但“我的”页面固定展示用户名首字母，没有读取真实头像。首次尝试直接访问 `/uploads/avatars/...` 后，经管理端与用户端截图对照确认仍回退为首字母；根因是头像文件位于受控目录，管理端使用鉴权接口读取，用户端缺少读取本人头像的对应接口。

## 具体操作

1. 新增 `GET /heqi/client/v1/user/auth/avatar`，复用 `user_app` JWT 和当前用户范围，只返回本人受保护头像二进制内容。
2. Flutter HTTP 客户端新增携带当前登录令牌的二进制读取能力，404 按无头像处理，其他失败使用中文异常。
3. 个人资料 Repository 新增本人头像读取方法，不再尝试公开访问受控文件路径。
4. 新增圆形头像组件，真实图片使用 `BoxFit.cover` 居中裁剪。
5. 头像为空、加载中、图片损坏或头像接口失败时继续显示用户名首字母；用户名为空时显示“用”，头像失败不阻塞钱包等其他资料。
6. 个人中心接入真实头像组件，本次不增加上传、更换或资料修改入口。
7. 新增后端路由、鉴权二进制请求和头像状态测试。

## 操作后状态

新增接口部署后，用户资料存在有效头像时，“我的”页面会通过鉴权请求显示真实头像；没有头像或图片不可用时保持原有首字母占位，不会出现空白或破图。登录、钱包、地址、合同、流水和维修功能未改变。

## 代码变更

- `backend/api/internal/routers/client.go`：注册当前用户头像读取路由。
- `backend/api/internal/routers/client_test.go`：验证用户头像路由存在。
- `backend/api/internal/logic/client/user/auth.go`：按当前登录用户读取受保护头像。
- `apps/user_app/lib/data/services/api_client.dart`：新增携带登录令牌的二进制读取方法。
- `apps/user_app/lib/data/repositories/client_repository.dart`：新增当前用户头像读取方法。
- `apps/user_app/lib/ui/features/profile/profile_avatar.dart`：新增真实头像与回退组件。
- `apps/user_app/lib/ui/features/profile/profile_page.dart`：个人资料卡片接入头像组件。
- `apps/user_app/test/data/api_client_test.dart`：覆盖头像字节、鉴权请求头、404 和异常文案。
- `apps/user_app/test/ui/profile_avatar_test.dart`：覆盖正常头像、空头像、损坏图片和接口失败状态。
- `docs/03-用户端App需求.md`：补充个人头像展示规则。
- `docs/11-数据接口与安全.md`：补充用户本人头像读取边界。

## 验证结果

- `flutter analyze`：通过，无问题。
- `flutter test`：通过，共 15 项测试。
- `go test ./internal/routers ./internal/logic/upload ./internal/logic/client/user`：通过。
- `go build ./cmd/main/main.go`：通过；临时构建产物已清理。
- `flutter build web --release --dart-define=API_BASE_URL=http://rest.heqiapp.com`：通过。
- 本地后端：已使用开发配置启动，`12426` 正常监听；新增头像接口未登录访问返回 401，路由和鉴权守卫生效。
- 本地用户端：已在 `5180` 重新启动并切换到 `http://127.0.0.1:12426`；原登录状态可读取个人资料和钱包。
- 边界案例：空头像、损坏图片、接口 404、接口异常和空用户名均有安全回退。

## 风险评估

- 新接口仅允许 `user_app` 令牌读取当前登录用户自己的头像，不接受目标用户标识，避免越权读取。
- 头像通过客户端鉴权请求读取，不开放受控文件目录；网络或文件异常时界面会安全回退为首字母。
- 本次未实现头像上传和更换，避免扩大文件选择、上传校验与资料更新范围。
- 当前 `rest.heqiapp.com` 运行版本尚未包含新增头像接口；部署服务端后才能在现有本地用户端页面看到真实头像。
- 当前账号记录指向 2026-09-02 上传的头像文件，本地 `runtime/uploads/avatars` 中没有该文件；本地后端虽已正常运行，仍会回退首字母。需要从服务器同步对应头像文件，或在本地重新上传头像后再验证真实图片。