feat: enforce student avatar presets

docs/refactor/taro-frontend-integration.md

@@ -754,7 +754,7 @@ POST /api/tenant-admin/badge-grants
 | 学习概览卡片 | `GET /api/learning/stats?days=30` | 返回总答题、正确率、报告数、错题数、收藏数、题型分布 |
 | 正确率趋势图 | `GET /api/learning/trend?days=14` | 返回每日答题数、正确数、错题数、session 数、报告数 |
 | 错题复习入口 | `GET /api/learning/wrong-questions/review-plan?limit=20` | 返回建议复习题和后端组卷 nextAction |
-| 排行榜 | `GET /api/learning/leaderboard?metric=questions&period=7d&regionId=...&classId=...` | 仅租户 `features.enableLeaderboard=true` 时请求；返回排名、用户展示信息、当前用户排名和范围信息 |
+| 排行榜 | `GET /api/learning/leaderboard?metric=questions&period=7d&regionId=...&classId=...` | 仅租户 `features.enableLeaderboard=true` 时请求；返回排名、用户展示信息、当前用户排名、范围信息和 `avatarPreset` 默认头像路径 |
 
 错题复习创建 session：
 
@@ -786,7 +786,7 @@ POST /api/tenant-admin/badge-grants
 | `classId` | UUID | 班级范围，可选，后端按当前租户校验 |
 | `limit` / `page` | 正整数 | 分页 |
 
-响应会包含 `items` 和 `currentUser`。即使当前用户未进入前 N 名，也应优先展示 `currentUser` 作为“我的排名”。后台后续会补日/周榜预聚合和防刷策略，前端只消费接口返回口径。
+响应会包含 `items` 和 `currentUser`。即使当前用户未进入前 N 名，也应优先展示 `currentUser` 作为“我的排名”。排行榜用户头像只返回系统默认头像路径和 `avatarPreset`，前端不能尝试展示微信/QQ 头像或旧库头像 URL。后台后续会补日/周榜预聚合和防刷策略，前端只消费接口返回口径。
 
 ### 租户数据看板
 
@@ -1125,7 +1125,7 @@ GET /api/tenant-content/assets/security-scan-events?assetId=<assetId>&limit=100
 
 ## 个人中心预设头像
 
-学生端不支持用户上传头像。系统只提供男女两种默认头像预设，避免头像上传带来的存储、内容安全、隐私和审核复杂度。前端不要展示文件选择器，不要调用对象存储上传链路，也不要把微信/QQ 返回的头像 URL 写入学生资料。后端登录链路和 PocketBase 导入脚本也会丢弃第三方头像字段，学生展示头像必须来自 `avatarPreset`。
+学生端不支持用户上传头像。系统只提供男女两种默认头像预设，避免头像上传带来的存储、内容安全、隐私和审核复杂度。前端不要展示文件选择器，不要调用对象存储上传链路，也不要把微信/QQ 返回的头像 URL 写入学生资料。后端登录链路和 PocketBase 导入脚本会丢弃第三方头像字段；租户后台学生创建、更新、批量导入和批量分班也会拒绝 `avatarUrl/avatar_url/avatar/headimgurl/figureurl` 等字段，学生展示头像必须来自 `avatarPreset`。
 
 当前 Taro service 使用：
 
@@ -1156,6 +1156,7 @@ updateProfile({ avatarPreset: 'male' | 'female' })
 - 允许用户在 UI 中二选一切换 `male` / `female`，调用 `PATCH /api/profile/me` 的 `avatarPreset` 字段保存。
 - `PATCH /api/profile/me` 传 `avatarUrl` 会返回 `PROFILE_AVATAR_URL_DIRECT_UPDATE_REJECTED`，前端不应提供该输入。
 - `avatarPreset` 只能是 `male` 或 `female`；其它值会返回 `INVALID_AVATAR_PRESET`。
+- `PUT /api/tenant-admin/students`、`POST /api/tenant-admin/students/bulk-upsert`、`POST /api/tenant-admin/classes/members/bulk-assign` 针对学生数据传头像字段会返回或逐行记录 `STUDENT_AVATAR_URL_UNSUPPORTED`；传 `primaryRole/primary_role` 会返回或逐行记录 `STUDENT_PRIMARY_ROLE_UNSUPPORTED`。
 - 默认头像资源由前端静态资产或 CDN 提供，路径保持 `/assets/avatars/default-male.svg` 和 `/assets/avatars/default-female.svg`。
 
 签到入口调用：
@@ -1475,7 +1476,7 @@ content_entries
 - 管理后台菜单按 `GET /api/tenant-admin/permissions` 返回的 `current.permissions`、`current.templatePermissions`、`current.menuPermissions`、`current.modulePermissions` 渲染；接口权限仍以后端校验为准。
 - 教师、班主任、助教类账号进入租户后台时，学生列表以 `GET /api/tenant-admin/students` 返回的 `scoped` 和 `items` 为准；前端不要自行用本地班级 ID 放大查询范围。
 - 学生手机号、订单金额、客资归属等敏感字段按 `fieldPermissions` 控制显示；字段被后端返回为 `null` 时前端展示脱敏占位，不要从其它接口补取。
-- 学生批量导入和批量分班接口会返回 `total/successCount/errorCount/results`，前端必须展示逐行错误，不要在浏览器端静默丢弃失败行。
+- 学生批量导入和批量分班接口会返回 `total/successCount/errorCount/results`，前端必须展示逐行错误，不要在浏览器端静默丢弃失败行。学生导入模板不要提供头像 URL 或 `primaryRole` 字段；后端会拒绝这类字段，学生头像统一由个人中心 `avatarPreset` 控制。
 - 教师可以为范围内学生创建备注和跟进任务，但是否能禁用学生、批量导入、查看手机号由后端权限和字段权限决定；前端只按返回值渲染。
 - H5 自定义域名下要注意缓存隔离，不能把 A 租户主题缓存用到 B 租户。