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

操作时间：2026-09-02

操作类型：修改、扩展

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

操作前状态

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

具体操作

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

操作后状态

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

代码变更

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 中没有该文件；本地后端虽已正常运行，仍会回退首字母。需要从服务器同步对应头像文件，或在本地重新上传头像后再验证真实图片。

4.3 KiB Raw Blame History Unescape Escape