# 变更审计记录：小程序登录页头像昵称获取功能（前端实施）

| 字段 | 值 |
|------|-----|
| 日期 | 2026-03-24 21:08:04 |
| Prompt-ID | P20260324-210327 |
| Session-ID | b95fcdcc |
| Session 路径 | docs/audit/session_logs/2026-03/24/70_1f4ab609_204000 |

## 操作摘要

在小程序申请页（apply）添加 chooseAvatar 头像选择 + nickname input 昵称快捷填入功能。头像通过 `wx.uploadFile` 上传到后端持久化。同时修改个人页（my-profile）和 `app.ts` 以支持头像展示。本次为前端实施部分（Step 9-16），后端接口（`/api/xcx/avatar/upload`）已在上一轮实施完成。

## 风险评估

- 低风险：纯前端 UI 变更 + 文档更新
- chooseAvatar 基础库要求 ≥ 2.21.2，nickname input ≥ 2.25.3
- 头像上传依赖后端 `/api/xcx/avatar/upload` 接口（已在上一轮实施完成）

## 变更文件清单

### 前端（小程序）
| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `apps/miniprogram/miniprogram/pages/apply/apply.ts` | 修改 | 新增 avatarTempPath/avatarUploaded data、onChooseAvatar、_uploadAvatar（wx.uploadFile）、onSubmit 先上传头像再提交、_checkAccess 保存 avatarUrl 到 globalData |
| `apps/miniprogram/miniprogram/pages/apply/apply.wxml` | 修改 | 新增头像选择区域（button open-type="chooseAvatar"）、昵称 input 改为 type="nickname" |
| `apps/miniprogram/miniprogram/pages/apply/apply.wxss` | 修改 | 新增头像选择区域样式（avatar-section、avatar-btn、avatar-preview、avatar-img、avatar-camera） |
| `apps/miniprogram/miniprogram/pages/my-profile/my-profile.ts` | 修改 | loadUserInfo 从 fetchMe 的 avatarUrl 构建完整头像 URL（API_BASE + /api/xcx/avatar/{userId}） |
| `apps/miniprogram/miniprogram/app.ts` | 修改 | checkAuthStatus 保存 avatarUrl 到 globalData.authUser |

### 文档
| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `docs/database/BD_Manual_auth_users_avatar.md` | 新增 | BD 手册：avatar_url 字段定义、数据流、关联接口 |
| `docs/deployment/EXPORT-PATHS.md` | 修改 | 新增 AVATAR_EXPORT_PATH 映射（目录总览、环境变量表、代码适配状态表、服务器配置示例） |

### 环境配置
| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `.env` | 修改 | 新增 AVATAR_EXPORT_PATH 环境变量 |
| `.env.template` | 修改 | 新增 AVATAR_EXPORT_PATH 模板 |

## 改动注解

### `apps/miniprogram/miniprogram/pages/apply/apply.ts`
- 变更类型：修改
- 原始原因：用户要求小程序登录时读取头像和用户名，头像存本地，用户名在申请提交时自动带到租户审核信息
- 思路分析：使用微信 chooseAvatar 组件获取临时头像路径，通过 wx.uploadFile 上传到后端 `/api/xcx/avatar/upload` 接口持久化。在 onSubmit 流程中先上传头像再提交申请，确保头像 URL 已持久化。_checkAccess 中将 avatarUrl 保存到 globalData 供全局使用
- 修改结果：申请页支持头像选择和上传，头像 URL 持久化到服务器，昵称通过 nickname input 快捷填入

### `apps/miniprogram/miniprogram/pages/apply/apply.wxml`
- 变更类型：修改
- 原始原因：需要在申请页 UI 中添加头像选择和昵称输入区域
- 思路分析：使用 `button open-type="chooseAvatar"` 触发微信头像选择，昵称 input 设置 `type="nickname"` 启用微信昵称快捷填入
- 修改结果：申请页新增头像选择区域和昵称快捷输入，符合微信小程序最新 API 规范

### `apps/miniprogram/miniprogram/pages/apply/apply.wxss`
- 变更类型：修改
- 原始原因：头像选择区域需要配套样式
- 思路分析：新增 avatar-section、avatar-btn、avatar-preview、avatar-img、avatar-camera 等样式类
- 修改结果：头像选择区域视觉呈现完整

### `apps/miniprogram/miniprogram/pages/my-profile/my-profile.ts`
- 变更类型：修改
- 原始原因：个人页需要展示用户头像
- 思路分析：从 fetchMe 接口返回的 avatarUrl 字段构建完整头像 URL（API_BASE + /api/xcx/avatar/{userId}），用于 image 组件展示
- 修改结果：个人页可展示用户上传的头像

### `apps/miniprogram/miniprogram/app.ts`
- 变更类型：修改
- 原始原因：全局需要缓存用户头像 URL 供各页面使用
- 思路分析：在 checkAuthStatus 中将 avatarUrl 保存到 globalData.authUser，避免各页面重复请求
- 修改结果：头像 URL 全局可用

### `docs/database/BD_Manual_auth_users_avatar.md`
- 变更类型：新增
- 原始原因：avatar_url 字段新增到 auth_users 表，需要配套 BD 手册文档
- 思路分析：记录字段定义、数据流（小程序 → wx.uploadFile → 后端 → 文件系统）、关联接口
- 修改结果：数据库文档与代码同步

### `docs/deployment/EXPORT-PATHS.md`
- 变更类型：修改
- 原始原因：新增 AVATAR_EXPORT_PATH 环境变量，需要在部署文档中记录
- 思路分析：在目录总览、环境变量表、代码适配状态表、服务器配置示例中新增 avatar 相关条目
- 修改结果：部署文档完整覆盖头像存储路径配置

## 本次对话文件变更

### 新增文件
- `docs/audit/prompt_logs/prompt_log_20260324_210327.md`
- `docs/audit/session_logs/2026-03/24/70_1f4ab609_204000/main_01_b95fcdcc.md`
- `docs/audit/session_logs/2026-03/24/70_1f4ab609_204000/sub_01_16c3d9c7.md`
- `docs/audit/session_logs/2026-03/24/71_9dd37e1b_204432/main_01_2dd5a2b8.md`
- `docs/audit/session_logs/2026-03/24/72_4e2c3fe5_205502/main_01_16c3d9c7.md`

### 删除文件
- `docs/audit/session_logs/2026-03/24/70_1f4ab609_204000/main_01_a9795623.md`

## 合规检查

| 检查项 | 状态 |
|--------|------|
| 新增迁移 SQL | 无（迁移在上一轮已完成） |
| DDL 基线 | ⚠️ DDL 基线待合并（has_ddl_baseline: false） |
| OpenAPI spec | 无需更新（api_changed: false） |
| BD 手册 | 已新建 `BD_Manual_auth_users_avatar.md` |
| 文档同步 | `.env` / `.env.template` / EXPORT-PATHS.md 已同步 |
