From 0c1385b7d44d4f06924e9f836c9821a994f05608 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:32:10 +0800
Subject: [PATCH 01/62] docs: add profile account and check-in design

---
 ...00\345\217\221\350\256\276\350\256\241.md" | 725 ++++++++++++++++++
 1 file changed, 725 insertions(+)
 create mode 100644 "docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md"

diff --git "a/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md" "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md"
new file mode 100644
index 0000000..072ff7d
--- /dev/null
+++ "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md"
@@ -0,0 +1,725 @@
+# 个人主页账户资料与自动打卡开发设计
+
+## 1. 文档状态
+
+- 设计日期：2026-07-31。
+- 适用仓库：`UniSpeaking`。
+- 定位基线：当前提交 `27e8618`。
+- 当前状态：设计已确认，等待用户明确批准后才允许进入开发。
+- 本文中的行号以当前提交为准；实施时同时使用类名、方法名和代码锚点定位，禁止仅凭行号修改。
+- 本文只定义开发方案，不代表已经修改源码、配置、数据库或依赖。
+
+## 2. 强制开发规范
+
+开发前必须完整阅读仓库根目录的 `CLAUDE.md`。本功能必须遵守其中以下规则：
+
+1. Java 21、Spring Boot 4、PostgreSQL、MyBatis-Plus 3.5.x，不引入第二套 ORM。
+2. Controller 只处理 HTTP 协议、参数校验、认证用户解析和统一响应，不写业务逻辑。
+3. 业务逻辑位于 `service/profile` 或 `service/auth`，数据库读写只能通过 Repository。
+4. Mapper 继承 `BaseMapper<Entity>`；查询和更新只能使用 MyBatis-Plus Lambda Wrapper。
+5. Java 代码中禁止原始 SQL、SQL 注解、Mapper XML，以及 `.last()`、`.apply()`、
+   `.inSql()`、`.notInSql()`、`.setSql()`。
+6. 当前用户 ID 必须来自 JWT；任何个人资料接口都不接收客户端传入的 `userId`。
+7. OSS Access Key、Secret、Bucket 和 Endpoint 只允许由环境变量注入，不得进入 DTO、
+   前端、日志或 Git。
+8. 数据库只保存头像对象 Key，不保存长期签名 URL。
+9. 上传头像必须验证实际内容、大小、图片尺寸和对象归属。
+10. 业务异常使用 `BusinessException` 和稳定错误码，响应使用统一 `ApiResponse`。
+11. 日志不得记录密码、JWT、OSS 密钥、签名 URL 或图片二进制。
+12. 新行为必须有测试，默认测试不得调用真实 OSS 或其他外网服务。
+
+`CLAUDE.md` 本身不需要修改，它是本设计的上位约束。
+
+## 3. 已确认需求
+
+### 3.1 展示昵称
+
+- 用户可以修改个人主页的展示昵称。
+- 展示昵称使用现有 `"user".nickname`。
+- `"user".username` 实际是登录邮箱，本次不得修改。
+- 昵称去除首尾空格后长度必须为 1～32 个字符。
+
+### 3.2 用户头像
+
+- 用户可以上传 JPEG 或 PNG 头像。
+- 头像保存到阿里云 OSS。
+- 后端保存对象 Key，并按需生成有效期 1 小时的签名读取 URL。
+- 未设置头像或签名 URL 暂时不可用时，前端显示
+  `/brand/unispeaking-mark-user.jpg`。
+- 用户头像不得继续使用当前 AI 老师的图片。
+
+### 3.3 修改密码
+
+- 用户必须提交当前密码和新密码。
+- 新密码长度沿用注册规则：6～72 位。
+- 新密码不得与当前密码相同。
+- 修改成功后 `"user".auth_version + 1`。
+- 当前设备和其他设备的全部旧 JWT 立即失效。
+- 前端收到成功响应后清除本地 Token，并跳转登录页。
+
+### 3.4 自动打卡
+
+- 只要当天存在一份已经持久化的五维报告，就算当天完成打卡。
+- 判断依据是现有 `session_evaluation` 记录，不判断分数高低。
+- 正常报告、零分报告和降级报告都算打卡。
+- 同一天存在多份报告，日历仍只显示一次打卡。
+- 打卡日期按 `Asia/Shanghai` 将 `session_evaluation.created_at` 转为业务日期。
+- 不新增打卡表，不修改 `session_evaluation` 表，不引入 Redis。
+- 已软删除场景的历史报告仍须参与打卡计算。
+- 五维结果弹窗拿到报告时显示“今日已自动打卡”。
+
+### 3.5 保留的现有静态内容
+
+以下现有静态内容保持原样，不改为后端统计：
+
+- “本周学习时长”统计卡；
+- “已保存学习资产”统计卡；
+- “连续学习天数”统计卡；
+- 七日练习节奏柱状图；
+- 成就系统及其静态进度。
+
+只有学习日历中的打卡日期改为由五维报告动态推导。
+
+## 4. 不在本次范围
+
+- 不修改登录邮箱。
+- 不增加邮箱验证、找回密码或忘记密码流程。
+- 不增加删除账户功能；现有按钮继续保持未接入状态。
+- 不增加打卡按钮、补签、撤销打卡或管理员改打卡。
+- 不增加 `user_check_in` 表。
+- 不增加 Redis 依赖、Redis 容器或 Redis 配置。
+- 不修改五维评分算法、五维报告字段或评分表结构。
+- 不把原有静态统计、练习节奏或成就系统改为动态数据。
+- 不引入消息队列、CDN 或浏览器直传 OSS。
+- 不在本次工作中重构整个 `App.jsx`。
+
+## 5. 当前项目事实
+
+1. `"user"` 已有 `username`、`password_hash`、`nickname`、`auth_version` 和
+   `updated_at`。
+2. `AuthServiceImpl.requireAuthenticatedUser()` 已验证 JWT subject、账号状态和
+   `auth_version`。
+3. `session_evaluation` 已有 `scene_id`、五维分数和 `created_at`。
+4. `scene` 已有 `user_id` 和 `deleted_at`，并有 `idx_scene_user_id`。
+5. `session_evaluation` 已有
+   `idx_session_evaluation_scene_id (scene_id, created_at DESC)`。
+6. 旧对话清理只删除 `session_message` 和 `turn_evaluation`，不会删除
+   `session_evaluation`，因此历史五维报告可以用于推导打卡。
+7. 前端个人主页、学习日历、统计卡和成就目前都在 `src/App.jsx`。
+8. 当前侧边栏和个人主页将 `teacher.image` 错当成用户头像。
+9. “修改密码”按钮目前没有事件处理。
+10. 当前项目没有 Redis 和 OSS 依赖。
+
+## 6. 总体架构
+
+```text
+ProfileController
+    ├── AuthService.requireUserId(null)
+    ├── ProfileOverviewService
+    │       ├── UserAccountRepository
+    │       ├── SceneRepository
+    │       ├── SessionEvaluationRepository
+    │       └── ObjectStorageProvider
+    └── ProfileAccountService
+            ├── UserAccountRepository
+            ├── AvatarImageProcessor
+            └── ObjectStorageProvider
+
+AuthController
+    └── AuthService.changePassword(...)
+            ├── UserAccountRepository
+            └── PasswordEncoder
+
+ObjectStorageProvider
+    └── AliyunOssObjectStorageProvider
+```
+
+边界说明：
+
+- `ProfileOverviewService` 只负责个人主页读取聚合和打卡日期推导。
+- `ProfileAccountService` 只负责昵称和头像资料写入。
+- `ProfileService` 继续只负责老师、语速、CEFR 和长期资料，不扩大为万能服务。
+- `AuthService` 继续拥有密码与 JWT 失效逻辑。
+- 不创建 `CheckInService`，因为本次没有打卡写操作。
+- 不让 `SessionService` 调用 Profile 模块；评分报告保存完成后无需额外写入。
+
+## 7. 数据库设计
+
+### 7.1 唯一数据库改动
+
+只修改 `"user"` 表，增加 OSS 对象 Key：
+
+```sql
+ALTER TABLE "user"
+ADD COLUMN IF NOT EXISTS avatar_object_key VARCHAR(512);
+
+ALTER TABLE "user"
+DROP CONSTRAINT IF EXISTS user_avatar_object_key_check;
+
+ALTER TABLE "user"
+ADD CONSTRAINT user_avatar_object_key_check
+CHECK (
+    avatar_object_key IS NULL
+    OR BTRIM(avatar_object_key) <> ''
+);
+
+COMMENT ON COLUMN "user".avatar_object_key IS
+'用户头像在对象存储中的对象 Key；不保存签名 URL、Bucket 密钥或完整访问地址';
+```
+
+对象 Key 格式：
+
+```text
+avatars/{userId}/{uuid}.{jpg|png}
+```
+
+示例：
+
+```text
+avatars/22222222-2222-4222-8222-222222222222/550e8400-e29b-41d4-a716-446655440000.jpg
+```
+
+### 7.2 明确禁止的数据库改动
+
+- 不增加 `user_check_in`。
+- 不给 `session_evaluation` 增加可用状态。
+- 不在数据库保存头像签名 URL。
+- 不在数据库保存头像二进制。
+- 不修改 `username`、`nickname`、`password_hash` 或 `auth_version` 的类型。
+- 不设置新的数据库外键。
+
+### 7.3 打卡读取算法
+
+1. 从 JWT 获取用户 UUID。
+2. 读取该用户所有场景 ID，包含软删除场景。
+3. 将请求月份在 `Asia/Shanghai` 的月初和下月月初转换为两个 UTC Instant。
+4. 查询这些场景在 `[monthStart, nextMonthStart)` 范围内的
+   `session_evaluation.created_at`。
+5. 将每个时间转换为 `Asia/Shanghai` 的 `LocalDate`。
+6. `distinct + sort` 后返回 `checkedDates`。
+7. 使用同一查询结果判断 `checkedInToday`。
+
+Repository 查询必须使用：
+
+```java
+LambdaQueryWrapper<SceneEntity>
+LambdaQueryWrapper<SessionEvaluationEntity>
+```
+
+允许 `.eq()`、`.in()`、`.ge()`、`.lt()`、`.select()` 和 `.orderByAsc()`；
+禁止 SQL 拼接和 `CLAUDE.md` 列出的所有危险 Wrapper 方法。
+
+## 8. HTTP 接口
+
+所有接口都必须携带 JWT，响应继续使用统一 `ApiResponse`。
+
+### 8.1 获取个人主页
+
+```http
+GET /api/profile/overview?month=2026-07
+Authorization: Bearer <JWT>
+```
+
+响应：
+
+```json
+{
+  "success": true,
+  "code": "OK",
+  "message": "success",
+  "data": {
+    "account": {
+      "userId": "22222222-2222-4222-8222-222222222222",
+      "email": "learner@example.com",
+      "nickname": "Sunny",
+      "displayName": "Sunny",
+      "avatarUrl": "https://example.oss-cn-hangzhou.aliyuncs.com/...",
+      "avatarUrlExpiresAt": "2026-07-31T10:00:00Z"
+    },
+    "calendar": {
+      "month": "2026-07",
+      "checkedDates": [
+        "2026-07-01",
+        "2026-07-02",
+        "2026-07-04"
+      ],
+      "checkedInToday": true
+    }
+  }
+}
+```
+
+`displayName` 规则：
+
+1. 有非空 `nickname` 时使用 `nickname`；
+2. 否则使用登录邮箱 `@` 前的部分；
+3. 仍为空时使用 `UniSpeaking User`。
+
+`month` 必须是 `yyyy-MM`；省略时使用 `Asia/Shanghai` 当前月份；未来月份返回
+`PROFILE_MONTH_INVALID`。
+
+### 8.2 修改昵称
+
+```http
+PATCH /api/profile
+Authorization: Bearer <JWT>
+Content-Type: application/json
+```
+
+请求：
+
+```json
+{
+  "nickname": "Sunny"
+}
+```
+
+响应数据：
+
+```json
+{
+  "nickname": "Sunny",
+  "displayName": "Sunny"
+}
+```
+
+### 8.3 上传头像
+
+```http
+POST /api/profile/avatar
+Authorization: Bearer <JWT>
+Content-Type: multipart/form-data
+```
+
+表单字段：
+
+```text
+avatar=<binary>
+```
+
+响应数据：
+
+```json
+{
+  "avatarUrl": "https://example.oss-cn-hangzhou.aliyuncs.com/...",
+  "avatarUrlExpiresAt": "2026-07-31T10:00:00Z"
+}
+```
+
+### 8.4 修改密码
+
+```http
+PUT /api/auth/password
+Authorization: Bearer <JWT>
+Content-Type: application/json
+```
+
+请求：
+
+```json
+{
+  "currentPassword": "old-password",
+  "newPassword": "new-password"
+}
+```
+
+响应数据：
+
+```json
+{
+  "reauthenticationRequired": true
+}
+```
+
+前端确认密码只在浏览器本地校验，不发送 `confirmPassword`。
+
+## 9. 头像处理与 OSS 设计
+
+### 9.1 文件规则
+
+- 最大文件大小：2 MiB，即 `2097152` bytes。
+- 允许格式：JPEG、PNG。
+- 最小宽高：128×128。
+- 最大宽高：4096×4096。
+- 不信任文件扩展名和客户端 `Content-Type`。
+- 使用 Java `ImageIO` 解码实际内容。
+- 解码后重新编码为 JPEG 或 PNG，移除 EXIF 和其他原始元数据。
+- 图片不强制裁剪；前端继续使用 `object-fit: cover`。
+
+Spring 全局 multipart 上限继续保持 10 MB，避免影响现有音频接口；头像 2 MiB 限制在
+`AvatarImageProcessor` 中执行。
+
+### 9.2 OSS 接口
+
+`ObjectStorageProvider` 定义以下稳定接口：
+
+```java
+void put(String objectKey, byte[] content, String contentType);
+URI signGetUrl(String objectKey, Duration ttl);
+void delete(String objectKey);
+```
+
+业务代码只能依赖该接口，不得依赖阿里云 SDK 类。
+
+### 9.3 上传补偿顺序
+
+```text
+认证用户
+  → 校验并规范化图片
+  → 生成归属当前 userId 的对象 Key
+  → 上传新对象
+  → 更新 user.avatar_object_key
+  → 生成新签名 URL
+  → 尽力删除旧对象
+```
+
+失败策略：
+
+- 图片校验失败：不调用 OSS，不修改数据库。
+- 新对象上传失败：不修改数据库。
+- 新对象上传成功但数据库更新失败：立即尽力删除新对象，然后返回失败。
+- 数据库更新成功但旧对象删除失败：新头像继续生效，只记录脱敏警告日志。
+- 读取资料时签名失败：资料接口仍成功，`avatarUrl` 和
+  `avatarUrlExpiresAt` 返回 `null`。
+- 不在请求内重试超过一次，不引入 MQ 或后台重试框架。
+
+### 9.4 OSS 配置
+
+`application.yaml` 中新增：
+
+```yaml
+profile:
+  time-zone: ${PROFILE_TIME_ZONE:Asia/Shanghai}
+
+object-storage:
+  aliyun:
+    endpoint: ${OSS_ENDPOINT:}
+    bucket: ${OSS_BUCKET:}
+    access-key-id: ${OSS_ACCESS_KEY_ID:}
+    access-key-secret: ${OSS_ACCESS_KEY_SECRET:}
+    avatar-prefix: ${OSS_AVATAR_PREFIX:avatars}
+    signed-url-ttl: ${OSS_SIGNED_URL_TTL:1h}
+```
+
+`.env.example` 只增加占位值：
+
+```properties
+PROFILE_TIME_ZONE=Asia/Shanghai
+OSS_ENDPOINT=
+OSS_BUCKET=
+OSS_ACCESS_KEY_ID=
+OSS_ACCESS_KEY_SECRET=
+OSS_AVATAR_PREFIX=avatars
+OSS_SIGNED_URL_TTL=1h
+```
+
+实际密钥只由用户写入被 Git 忽略的 `deploy/env/.env`。开发过程不得自动修改或输出该
+文件。
+
+### 9.5 依赖
+
+`pom.xml` 增加：
+
+```xml
+<aliyun-oss.version>3.18.5</aliyun-oss.version>
+```
+
+以及：
+
+```xml
+<dependency>
+    <groupId>com.aliyun.oss</groupId>
+    <artifactId>aliyun-sdk-oss</artifactId>
+    <version>${aliyun-oss.version}</version>
+</dependency>
+```
+
+Java 21 下如 OSS SDK 依赖树未提供 JAXB，再按阿里云官方 Java 9+ 指引补充
+`jaxb-api 2.3.1`、`activation 1.1.1` 和 `jaxb-runtime 2.3.3`；是否需要以
+`./mvnw dependency:tree` 和编译结果为准，不预先引入重复依赖。
+
+参考：
+
+- [阿里云 OSS Java SDK 安装说明](https://help.aliyun.com/en/oss/developer-reference/oss-java-sdk/)
+- [OSS Java SDK 3.18.5 Maven 坐标](https://mvnrepository.com/artifact/com.aliyun.oss/aliyun-sdk-oss/3.18.5)
+
+## 10. 具体文件和修改位置
+
+本节中的 Java 主代码短路径统一相对于：
+
+```text
+backend/unispeaking-server/src/main/java/com/unispeaking/
+```
+
+例如 `domain/po/auth/UserAccount.java` 的完整仓库路径是
+`backend/unispeaking-server/src/main/java/com/unispeaking/domain/po/auth/UserAccount.java`。
+第 11 节中的后端测试短路径统一相对于
+`backend/unispeaking-server/src/test/java/com/unispeaking/`。其余文件均写完整仓库
+相对路径。
+
+### 10.1 数据库与部署
+
+| 动作 | 文件 | 当前定位/锚点 | 必须修改的内容 |
+| --- | --- | --- | --- |
+| 修改 | `backend/unispeaking-server/src/main/resources/db/schema.sql` | 当前第 1 行 `"user"` 建表；`ALTER COLUMN username TYPE VARCHAR(254)` 之后 | 增加 `avatar_object_key`、非空白约束和字段注释；不增加其他表或字段 |
+| 新建 | `deploy/postgres/profile.sql` | 新文件 | 用 `BEGIN/COMMIT` 包装同一组幂等头像字段迁移 SQL |
+| 修改 | `backend/unispeaking-server/src/main/resources/application.yaml` | 当前第 41 行 `auth:` 之前 | 新增 `profile.time-zone` 和 `object-storage.aliyun` 配置 |
+| 修改 | `deploy/env/.env.example` | 当前第 12～23 行 PostgreSQL/JWT 配置之后 | 增加 Profile 时区和 OSS 占位变量，不填真实密钥 |
+| 修改 | `deploy/nginx/nginx.conf` | 当前第 12 行 `server` 块内、`location /backend/` 之前 | 增加 `client_max_body_size 10m;`，与 Spring 现有 multipart 上限对齐 |
+| 不改 | `deploy/env/.env` | 被 Git 忽略 | 真实 OSS 配置由用户自行填写，开发不得读取、输出或提交 |
+| 不改 | `deploy/docker-compose.yml` | `backend.env_file` 已存在 | OSS 变量会由现有 `env_file` 自动传入，不新增 Redis 或其他服务 |
+
+### 10.2 Domain 和 DTO
+
+| 动作 | 文件 | 当前定位/锚点 | 必须修改的内容 |
+| --- | --- | --- | --- |
+| 修改 | `domain/po/auth/UserAccount.java` | record 参数中 `nickname` 之后；`withLastLoginAt()` | 增加 `avatarObjectKey`；同步所有复制方法和构造调用 |
+| 不改 | `domain/dto/auth/UserAccountResponse.java` | 当前 `from(UserAccount)` | `/api/auth/me` 保持现有契约；签名 URL 不进入 Auth DTO |
+| 新建 | `domain/dto/auth/ChangePasswordRequest.java` | 新文件 | `currentPassword`、`newPassword`，均 `@NotBlank`、`@Size(min=6,max=72)` |
+| 新建 | `domain/dto/auth/ChangePasswordResponse.java` | 新文件 | 单字段 `reauthenticationRequired` |
+| 新建 | `domain/dto/profile/UpdateProfileRequest.java` | 新文件 | `nickname`，`@NotBlank`、`@Size(max=32)` |
+| 新建 | `domain/dto/profile/UpdateProfileResponse.java` | 新文件 | `nickname`、`displayName` |
+| 新建 | `domain/dto/profile/ProfileAccountResponse.java` | 新文件 | `userId`、`email`、`nickname`、`displayName`、`avatarUrl`、`avatarUrlExpiresAt` |
+| 新建 | `domain/dto/profile/ProfileCalendarResponse.java` | 新文件 | `month`、`List<LocalDate> checkedDates`、`checkedInToday` |
+| 新建 | `domain/dto/profile/ProfileOverviewResponse.java` | 新文件 | `account`、`calendar` |
+| 新建 | `domain/dto/profile/AvatarResponse.java` | 新文件 | `avatarUrl`、`avatarUrlExpiresAt` |
+| 不改 | `domain/dto/evaluation/DialogueReportResult.java` | 整个 record | 任意已保存报告都算打卡，不新增状态字段 |
+
+### 10.3 Controller
+
+| 动作 | 文件 | 当前定位/锚点 | 必须修改的内容 |
+| --- | --- | --- | --- |
+| 新建 | `controller/ProfileController.java` | 新文件，`@RequestMapping("/api/profile")` | `GET /overview`、`PATCH /api/profile`、`POST /avatar`；每个方法先通过 `AuthService.requireUserId(null)` 获取身份 |
+| 修改 | `controller/AuthController.java` | 当前第 36 行 `me()` 之后 | 增加 `@PutMapping("/password")`，只转发 `@Valid ChangePasswordRequest` |
+| 不改 | `controller/UserPreferenceController.java` | 整个文件 | 老师、语速和 CEFR 接口继续独立 |
+| 不改 | `controller/CustomSceneController.java` | 五维评分完成接口 | 不写打卡，不新增打卡调用 |
+
+Controller 禁止：
+
+- 接收 `userId`；
+- 直接访问 Repository、Mapper、OSS SDK；
+- 计算月份边界或拼对象 Key；
+- 校验当前密码；
+- 编写上传补偿逻辑。
+
+### 10.4 Service
+
+| 动作 | 文件 | 当前定位/锚点 | 必须修改的内容 |
+| --- | --- | --- | --- |
+| 新建 | `service/profile/ProfileOverviewService.java` | 新文件 | 定义 `getOverview(String userId, String month)` |
+| 新建 | `service/profile/impl/ProfileOverviewServiceImpl.java` | 新文件 | 查询账户、全部场景 ID、月份报告时间，转换业务日期并签名头像 URL |
+| 新建 | `service/profile/ProfileAccountService.java` | 新文件 | 定义 `updateNickname(...)`、`replaceAvatar(...)` |
+| 新建 | `service/profile/impl/ProfileAccountServiceImpl.java` | 新文件 | 昵称更新、图片规范化、OSS 上传、数据库更新和补偿删除 |
+| 新建 | `service/profile/image/AvatarImageProcessor.java` | 新文件 | 纯图片验证和重新编码；不访问数据库或 OSS |
+| 不改 | `service/profile/ProfileService.java` | 当前第 7 行接口 | 继续只处理用户偏好 |
+| 不改 | `service/profile/impl/ProfileServiceImpl.java` | 整个文件 | 不把资料、头像和打卡逻辑塞入现有偏好服务 |
+| 修改 | `service/auth/AuthService.java` | 当前第 11 行 `currentUser()` 后 | 增加 `changePassword(ChangePasswordRequest)` |
+| 修改 | `service/auth/impl/AuthServiceImpl.java` | 当前第 97 行 `currentUser()` 后 | 增加 `@Transactional changePassword`，复用 `requireAuthenticatedUser()` |
+| 不改 | `service/session/impl/SessionServiceImpl.java` | `completeCustomScene()` | 报告保存逻辑不增加打卡写入 |
+
+修改密码流程：
+
+1. `requireAuthenticatedUser()` 获取数据库中的当前账号。
+2. `passwordEncoder.matches(currentPassword, passwordHash)`。
+3. 检查新密码是否与当前密码相同。
+4. `passwordEncoder.encode(newPassword)`。
+5. Repository 使用 `id + expectedAuthVersion` 条件原子更新哈希和
+   `authVersion + 1`。
+6. 更新行数不是 1 时抛出 `PASSWORD_UPDATE_CONFLICT`。
+7. 返回 `reauthenticationRequired=true`。
+
+### 10.5 持久化
+
+| 动作 | 文件 | 当前定位/锚点 | 必须修改的内容 |
+| --- | --- | --- | --- |
+| 修改 | `infrastructure/persistence/entity/user/UserAccountEntity.java` | 当前第 22 行 `nickname` 后 | 增加 `String avatarObjectKey` |
+| 修改 | `infrastructure/persistence/repository/user/UserAccountRepository.java` | 当前第 8 行接口 | 增加 `updateNickname`、`updateAvatarObjectKey`、`updatePasswordAndAuthVersion` |
+| 修改 | `infrastructure/persistence/repository/user/MybatisUserAccountRepository.java` | 当前第 27～79 行 | 更新 Entity/Domain 映射；新增三个 LambdaUpdateWrapper 更新方法 |
+| 修改 | `infrastructure/persistence/repository/scene/SceneRepository.java` | 当前第 18 行 `findAssetsByUserId` 附近 | 增加 `findAllIdsByUserId(String userId)`，语义明确包含软删除场景 |
+| 修改 | `infrastructure/persistence/repository/scene/MybatisSceneRepository.java` | 当前第 102 行 `findAssetsByUserId` 前 | 实现只按 `userId` 查询 ID，不加 `deletedAt IS NULL` |
+| 修改 | `infrastructure/persistence/repository/evaluation/SessionEvaluationRepository.java` | 当前第 83 行 `findBySceneId` 后 | 增加 `findCreatedAtBySceneIdsBetween(sceneIds,start,end)`，空 ID 集合直接返回空列表 |
+| 不改 | `infrastructure/persistence/entity/evaluation/SessionEvaluationEntity.java` | 整个类 | 直接读取现有 `sceneId` 和 `createdAt` |
+| 不改 | `infrastructure/persistence/mapper/*` | 所有 Mapper | 现有 BaseMapper 足够，不增加 SQL/XML |
+
+账户更新方法的契约：
+
+```java
+boolean updateNickname(UUID userId, String nickname);
+boolean updateAvatarObjectKey(
+        UUID userId,
+        String expectedObjectKey,
+        String newObjectKey);
+boolean updatePasswordAndAuthVersion(
+        UUID userId,
+        long expectedAuthVersion,
+        String passwordHash);
+```
+
+头像更新必须以 `expectedObjectKey` 作为并发条件，避免两个并发上传互相删除正在使用的
+对象。密码更新必须以 `expectedAuthVersion` 作为并发条件。
+
+### 10.6 OSS 基础设施
+
+| 动作 | 文件 | 当前定位/锚点 | 必须修改的内容 |
+| --- | --- | --- | --- |
+| 新建 | `infrastructure/storage/ObjectStorageProvider.java` | 新文件 | 稳定的上传、签名和删除接口 |
+| 新建 | `infrastructure/storage/UnavailableObjectStorageProvider.java` | 新文件 | OSS 未配置时提供明确业务失败，不让应用启动失败 |
+| 新建 | `infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java` | 新文件 | 唯一允许依赖阿里云 OSS SDK 的实现 |
+| 新建 | `infrastructure/config/ObjectStorageProperties.java` | 新文件 | `@ConfigurationProperties("object-storage.aliyun")` |
+| 新建 | `infrastructure/config/ObjectStorageConfig.java` | 新文件 | 配置完整时创建 OSS Provider，否则创建不可用 Provider；OSS Client 关闭时调用 `shutdown()` |
+| 新建 | `infrastructure/config/ProfileProperties.java` | 新文件 | `@ConfigurationProperties("profile")`，校验 `ZoneId` |
+| 修改 | `backend/unispeaking-server/pom.xml` | 当前第 29～32 行 properties；第 63～72 行 PostgreSQL/音频依赖之间 | 增加 OSS SDK 版本属性和依赖 |
+
+### 10.7 异常处理
+
+修改 `common/exception/GlobalExceptionHandler.java` 当前第 16～22 行状态映射：
+
+| 错误码 | HTTP |
+| --- | --- |
+| `PROFILE_MONTH_INVALID` | 400 |
+| `PROFILE_NICKNAME_REQUIRED` | 400 |
+| `PROFILE_NICKNAME_TOO_LONG` | 400 |
+| `AVATAR_FILE_REQUIRED` | 400 |
+| `AVATAR_FILE_TOO_LARGE` | 400 |
+| `AVATAR_TYPE_UNSUPPORTED` | 400 |
+| `AVATAR_DIMENSION_INVALID` | 422 |
+| `AVATAR_CONTENT_INVALID` | 422 |
+| `CURRENT_PASSWORD_INVALID` | 400 |
+| `NEW_PASSWORD_SAME_AS_CURRENT` | 400 |
+| `PASSWORD_UPDATE_CONFLICT` | 409 |
+| `PROFILE_UPDATE_CONFLICT` | 409 |
+| `AVATAR_STORAGE_UNAVAILABLE` | 503 |
+| `AVATAR_STORAGE_FAILED` | 502 |
+
+不得把 OSS 原始响应、Endpoint、Bucket、对象签名 URL 或异常堆栈返回给客户端。
+
+### 10.8 前端
+
+| 动作 | 文件 | 当前定位/锚点 | 必须修改的内容 |
+| --- | --- | --- | --- |
+| 修改 | `frontend/Unispeaking_fronted/src/apiClient.js` | 当前第 65 行 `getCurrentUser()` 和第 69 行偏好接口之间 | 增加 `getProfileOverview`、`updateProfile`、`uploadAvatar`、`changePassword` |
+| 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 572 行 `AppShell` | 新增 `avatarUrl` 参数；第 585 行用用户头像或默认头像替代 `teacher.image` |
+| 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 1194 行 `ResultModal` | `evaluation` 存在时展示“今日已自动打卡”状态 |
+| 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 1968 行 `Profile` | 使用 Profile account；增加昵称编辑入口和头像上传入口 |
+| 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 1976～1989 行 `learningMonths` | 删除静态月份打卡数据；不得删除静态统计卡、节奏柱状图和成就常量 |
+| 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 2006 行 `LearningCalendar` | 按月份调用后端并渲染 `checkedDates`；月份切换支持历史月份，不允许未来月份 |
+| 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 2073 行 `Overview` | 继续原样渲染三张静态卡、节奏和成就；只向日历传动态数据 |
+| 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 2082 行 `Settings` 的“账户与隐私” | 给“修改密码”接入弹窗；“删除账户”保持不变 |
+| 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 2096 行 `App` 状态与第 2175 行认证启动 | 增加 profile 状态；认证启动并行加载当前月份 overview；资料更新后同步状态 |
+| 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 2287 行 `logout()` 附近 | 修改密码成功后复用清理 Token 和跳转登录逻辑 |
+| 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 2373～2374 行 Profile/AppShell 渲染 | 向 Profile 和 AppShell 传 account、avatarUrl 及更新回调 |
+| 修改 | `frontend/Unispeaking_fronted/src/styles.css` | 当前第 256～258 行 sidebar avatar | 保持头像裁切；增加加载失败/默认头像状态 |
+| 修改 | `frontend/Unispeaking_fronted/src/styles.css` | 当前第 806 行 profile 区域 | 增加头像编辑、昵称编辑、上传预览、表单错误、提交中状态 |
+| 修改 | `frontend/Unispeaking_fronted/src/styles.css` | 当前第 810～838 行日历 | 保持现有视觉，只将 `is-practiced` 数据源改为报告日期 |
+| 修改 | `frontend/Unispeaking_fronted/src/styles.css` | 当前第 879 行设置区域 | 增加修改密码弹窗状态样式 |
+
+前端交互要求：
+
+- 用户进入应用时获取当前月份 Profile Overview，以便侧边栏立即显示用户头像。
+- Profile 请求失败不得清除 JWT；只有认证接口返回 401 才清理登录状态。
+- 头像签名 URL 加载失败时只允许自动刷新 Profile 一次，避免无限请求。
+- 头像上传中禁止重复提交。
+- 昵称和头像成功后同步更新 Profile 和 AppShell，不刷新整页。
+- 修改密码成功后立即清除 `unispeaking.accessToken`，跳转 `/auth/login`。
+- 不把 OSS 配置、签名逻辑或密钥放到前端。
+
+### 10.9 文档
+
+| 动作 | 文件 | 修改位置 | 必须修改的内容 |
+| --- | --- | --- | --- |
+| 修改 | `docs/frontend-backend-interface-contract.md` | 当前第 113 行“2.3 当前用户”之后 | 增加“2.4 修改密码”；在第 131 行用户资料章节前增加个人主页 overview、昵称和头像接口 |
+| 修改 | `docs/deployment.md` | 当前第 26 行“Available settings”中，Realtime 配置之前 | 增加阿里云 OSS 配置、RAM 最小权限、Bucket 私有读和签名 URL 说明 |
+| 不改 | `CLAUDE.md` | 整个文件 | 继续作为强制规范，不重复或弱化规则 |
+| 不改 | `README.md` | 整个文件 | 本次接口和部署信息由上述专用文档维护 |
+
+## 11. 测试文件和覆盖范围
+
+### 11.1 新建测试
+
+| 文件 | 覆盖内容 |
+| --- | --- |
+| `src/test/java/com/unispeaking/service/profile/ProfileOverviewServiceImplTest.java` | 同日多报告去重、跨日、跨月、上海零点边界、软删除场景、无场景、无头像和签名失败降级 |
+| `src/test/java/com/unispeaking/service/profile/ProfileAccountServiceImplTest.java` | 昵称规范化、邮箱不变、头像上传补偿、并发更新冲突、旧对象删除失败 |
+| `src/test/java/com/unispeaking/service/profile/image/AvatarImageProcessorTest.java` | JPEG/PNG、伪造扩展名、非图片、2 MiB 上限、尺寸上下限、重新编码 |
+| `src/test/java/com/unispeaking/controller/ProfileControllerTest.java` | JWT 身份、月份参数、统一响应、multipart、禁止客户端 userId |
+| `src/test/java/com/unispeaking/infrastructure/storage/aliyun/AliyunOssObjectStorageProviderTest.java` | 使用 Mock OSS Client 验证 Key、Content-Type、签名 TTL、错误转换和删除，不访问外网 |
+
+### 11.2 修改现有测试
+
+| 文件 | 修改位置 | 覆盖内容 |
+| --- | --- | --- |
+| `src/test/java/com/unispeaking/service/auth/AuthServiceImplTest.java` | 当前第 84 行 JWT 测试之后；所有 `UserAccount` 构造器 | 当前密码错误、新旧密码相同、BCrypt 编码、authVersion 增加、并发冲突、旧 JWT 被撤销 |
+| `src/test/java/com/unispeaking/infrastructure/persistence/PersistenceArchitectureTest.java` | 当前第 17～19 行禁止 API 正则及现有测试 | 确保新增 Repository 未使用 SQL 注解和禁止的 Wrapper 方法 |
+| `src/test/java/com/unispeaking/UniSpeakingApplicationTests.java` | 应用启动测试 | OSS 配置为空时应用仍能启动 |
+
+### 11.3 前端验证
+
+当前前端没有自动化组件测试框架，本次不为单一功能引入第二套测试框架。必须执行：
+
+```bash
+cd frontend/Unispeaking_fronted
+npm run build
+npm run check:routes
+npm run check:realtime-events
+```
+
+手工验收：
+
+1. 生成任意一份五维报告后，结果弹窗显示“今日已自动打卡”。
+2. 进入个人主页，当天显示为已打卡。
+3. 同一天生成多份报告，日历仍只有一个打卡标记。
+4. 跨上海时区零点生成报告，日期归属正确。
+5. 三张静态统计卡、七日节奏和成就系统内容与开发前一致。
+6. 修改昵称后，个人主页和侧边栏名称立即更新；重新登录后仍保留。
+7. 登录邮箱不因昵称修改而变化。
+8. 上传合法头像后立即更新，刷新页面后仍通过 OSS 显示。
+9. 非图片、伪造扩展名、超限图片和异常尺寸被拒绝，旧头像不变。
+10. 修改密码成功后自动返回登录页，旧 Token 请求 `/api/auth/me` 得到 401。
+
+### 11.4 后端验证
+
+```bash
+cd backend/unispeaking-server
+./mvnw test
+```
+
+还必须检查：
+
+```bash
+./mvnw dependency:tree
+```
+
+确认没有重复 JSON/HTTP 技术栈、第二套 ORM 或不必要的 JAXB 重复依赖。
+
+## 12. 实施顺序
+
+本节只定义顺序，不授权开始开发。
+
+1. 数据库头像字段及 Domain/Entity 映射。
+2. Repository 原子更新和报告日期查询。
+3. Profile DTO、月份读取服务及其测试。
+4. 图片处理器及其测试。
+5. ObjectStorageProvider、阿里云实现、配置和 Mock 测试。
+6. Profile 资料写服务、补偿逻辑及测试。
+7. 修改密码 DTO、Service、Repository 和测试。
+8. ProfileController、AuthController 与 Controller 测试。
+9. 前端 API、Profile 状态、动态日历、昵称、头像和密码交互。
+10. Nginx 上传上限、环境变量示例和部署文档。
+11. 完整后端测试、前端构建、路由/实时事件检查和手工验收。
+
+## 13. 完成标准
+
+只有同时满足以下条件才算完成：
+
+- 仅 `"user"` 表新增 `avatar_object_key`，没有打卡表、Redis 或评分表改动。
+- 打卡完全由已有五维报告推导，任意持久化报告都算。
+- 静态统计卡、节奏和成就保持不变。
+- 登录邮箱不可修改，昵称可持久化修改。
+- 头像只保存 OSS Key，签名 URL 短期生成，失败补偿完整。
+- 修改密码验证当前密码，并通过 `auth_version` 撤销全部旧 JWT。
+- Controller 无业务逻辑，Service 不写 SQL，Repository 不泄漏 Entity。
+- 新增持久化只使用 MyBatis-Plus Lambda Wrapper。
+- 配置和日志无密码、JWT、OSS 密钥和签名 URL。
+- 所有新增行为有测试，默认测试不访问真实 OSS。
+- `./mvnw test`、`npm run build`、`npm run check:routes` 和
+  `npm run check:realtime-events` 全部通过。

From ab28d464d3b04dd15096ed328be1bd10494cfa12 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:34:13 +0800
Subject: [PATCH 02/62] docs: add profile implementation plan

---
 ...36\346\226\275\350\256\241\345\210\222.md" | 100 ++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 "docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md"

diff --git "a/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md" "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md"
new file mode 100644
index 0000000..1553660
--- /dev/null
+++ "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md"
@@ -0,0 +1,100 @@
+# 个人主页账户资料与自动打卡实施计划
+
+> **执行要求：** 严格按照本计划逐项实施。每项只修改一个文件，验证该文件相关编译后立即单独 commit。用户明确要求不新增或修改测试文件，因此本计划不创建测试代码，使用现有测试套件、前端构建与检查作为回归验证。
+
+**目标：** 实现动态报告打卡日历、展示昵称修改、阿里云 OSS 用户头像和全端 JWT 失效的密码修改功能。
+
+**架构：** 完整设计以 `docs/个人主页账户资料与自动打卡开发设计.md` 为准。Profile 读取、Profile 写入、Auth 和 OSS 基础设施保持独立；打卡只读取现有 `session_evaluation`，不增加打卡写模型、Redis 或评分表字段。
+
+**技术栈：** Java 21、Spring Boot 4、MyBatis-Plus 3.5.17、PostgreSQL、阿里云 OSS Java SDK、React 19、Vite 6。
+
+## 全局约束
+
+- 开发前遵循仓库根目录 `CLAUDE.md`。
+- 当前分支固定为 `feat/profile-account-checkin`。
+- 每个 commit 只包含一个文件。
+- 不新增或修改 `src/test` 文件，不删除现有测试。
+- Java 中不写原始 SQL，不使用 SQL 注解、Mapper XML 或被禁止的 Wrapper 方法。
+- 用户身份只来自 JWT。
+- 不读取、修改或提交 `deploy/env/.env`。
+- 不新增打卡表、Redis、MQ 或评分表字段。
+
+---
+
+### Task 1：数据库与依赖
+
+- [ ] 修改 `backend/unispeaking-server/src/main/resources/db/schema.sql`：只给 `"user"` 增加 `avatar_object_key VARCHAR(512)`、非空白约束和注释；运行 `./mvnw -q -DskipTests compile`；单文件 commit。
+- [ ] 新建 `deploy/postgres/profile.sql`：用 `BEGIN/COMMIT` 包装同一幂等迁移；单文件 commit。
+- [ ] 修改 `backend/unispeaking-server/pom.xml`：增加 `aliyun-oss.version=3.18.5` 和 `com.aliyun.oss:aliyun-sdk-oss`；运行 `./mvnw -q -DskipTests compile`；单文件 commit。
+- [ ] 修改 `backend/unispeaking-server/src/main/resources/application.yaml`：增加 `profile.time-zone` 与 `object-storage.aliyun`；单文件 commit。
+- [ ] 修改 `deploy/env/.env.example`：增加 Profile/OSS 空占位配置；单文件 commit。
+- [ ] 修改 `deploy/nginx/nginx.conf`：在 server 块设置 `client_max_body_size 10m`；单文件 commit。
+
+### Task 2：账号持久化
+
+- [ ] 修改 `domain/po/auth/UserAccount.java`：record 增加 `avatarObjectKey`，增加 `withNickname`、`withAvatarObjectKey`、`withPasswordHashAndAuthVersion`，同步 `withLastLoginAt`；编译；单文件 commit。
+- [ ] 修改 `infrastructure/persistence/entity/user/UserAccountEntity.java`：在 `nickname` 后增加 `avatarObjectKey`；编译；单文件 commit。
+- [ ] 修改 `infrastructure/persistence/repository/user/UserAccountRepository.java`：增加三个原子更新接口，返回 `boolean`；编译；单文件 commit。
+- [ ] 修改 `infrastructure/persistence/repository/user/MybatisUserAccountRepository.java`：补全 Entity 映射并使用 `LambdaUpdateWrapper` 实现昵称、头像和密码版本更新；编译；单文件 commit。
+- [ ] 修改 `service/auth/impl/AuthServiceImpl.java` 中注册用 `UserAccount` 构造参数；编译；单文件 commit。
+
+### Task 3：打卡读取数据
+
+- [ ] 修改 `infrastructure/persistence/repository/scene/SceneRepository.java`：增加 `findAllIdsByUserId(String userId)`；编译；单文件 commit。
+- [ ] 修改 `infrastructure/persistence/repository/scene/MybatisSceneRepository.java`：只按 `userId` 查询所有场景 ID，包含软删除；编译；单文件 commit。
+- [ ] 修改 `infrastructure/persistence/repository/evaluation/SessionEvaluationRepository.java`：增加 `findCreatedAtBySceneIdsBetween(List<String>, OffsetDateTime, OffsetDateTime)`；编译；单文件 commit。
+
+### Task 4：Profile DTO 与配置
+
+- [ ] 新建 `domain/dto/profile/ProfileOverviewResponse.java`：包含嵌套 `Account` 和 `Calendar` record；编译；单文件 commit。
+- [ ] 新建 `domain/dto/profile/UpdateProfileRequest.java`：昵称非空且最长 32；编译；单文件 commit。
+- [ ] 新建 `domain/dto/profile/UpdateProfileResponse.java`：返回 nickname/displayName；编译；单文件 commit。
+- [ ] 新建 `domain/dto/profile/AvatarResponse.java`：返回签名 URL 和到期时间；编译；单文件 commit。
+- [ ] 新建 `infrastructure/config/ProfileProperties.java`：绑定 `profile.time-zone` 并提供合法 `ZoneId`；编译；单文件 commit。
+- [ ] 新建 `infrastructure/config/ObjectStorageProperties.java`：绑定 endpoint、bucket、Access Key、前缀和签名 TTL；编译；单文件 commit。
+
+### Task 5：OSS 与图片处理
+
+- [ ] 新建 `infrastructure/storage/ObjectStorageProvider.java`：定义 `put`、`signGetUrl`、`delete`；编译；单文件 commit。
+- [ ] 新建 `infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java`：唯一 OSS SDK 适配器，转换供应商异常；编译；单文件 commit。
+- [ ] 新建 `infrastructure/config/ObjectStorageConfig.java`：配置完整时创建 OSS Provider，不完整时提供明确不可用实现，关闭时 shutdown；编译；单文件 commit。
+- [ ] 新建 `service/profile/image/AvatarImageProcessor.java`：校验 2 MiB、JPEG/PNG、128～4096 像素并重新编码；编译；单文件 commit。
+
+### Task 6：Profile 业务与接口
+
+- [ ] 新建 `service/profile/ProfileOverviewService.java`：定义 `getOverview(userId, month)`；编译；单文件 commit。
+- [ ] 新建 `service/profile/impl/ProfileOverviewServiceImpl.java`：按上海时区推导日期、生成 displayName、签名头像并对签名失败降级；编译；单文件 commit。
+- [ ] 新建 `service/profile/ProfileAccountService.java`：定义昵称和头像更新接口；编译；单文件 commit。
+- [ ] 新建 `service/profile/impl/ProfileAccountServiceImpl.java`：实现昵称、头像对象 Key、并发条件和 OSS 补偿；编译；单文件 commit。
+- [ ] 新建 `controller/ProfileController.java`：实现 overview、PATCH profile 和 multipart avatar；编译；单文件 commit。
+- [ ] 修改 `common/exception/GlobalExceptionHandler.java`：增加 Profile/Auth/OSS 错误状态映射；编译；单文件 commit。
+
+### Task 7：修改密码
+
+- [ ] 新建 `domain/dto/auth/ChangePasswordRequest.java`：当前密码和新密码均 6～72 位；编译；单文件 commit。
+- [ ] 新建 `domain/dto/auth/ChangePasswordResponse.java`：固定返回 `reauthenticationRequired=true`；编译；单文件 commit。
+- [ ] 修改 `service/auth/AuthService.java`：增加 `changePassword`；编译；单文件 commit。
+- [ ] 修改 `service/auth/impl/AuthServiceImpl.java`：验证当前密码、新旧相同检查、BCrypt 和 authVersion 原子更新；编译；单文件 commit。
+- [ ] 修改 `controller/AuthController.java`：增加 `PUT /api/auth/password`；编译；单文件 commit。
+
+### Task 8：前端
+
+- [ ] 修改 `frontend/Unispeaking_fronted/src/apiClient.js`：增加 overview、昵称、头像和密码请求；运行 `npm run build`；单文件 commit。
+- [ ] 修改 `frontend/Unispeaking_fronted/src/App.jsx`：增加 Profile 状态、动态日历、昵称/头像/密码交互、结果打卡提示和全局用户头像；运行 `npm run build`；单文件 commit。
+- [ ] 修改 `frontend/Unispeaking_fronted/src/styles.css`：增加资料编辑、上传、密码弹窗和打卡提示样式；运行 `npm run build`；单文件 commit。
+
+### Task 9：接口与部署文档
+
+- [ ] 修改 `docs/frontend-backend-interface-contract.md`：补充 Profile 和密码接口；单文件 commit。
+- [ ] 修改 `docs/deployment.md`：补充 OSS、私有 Bucket、RAM 最小权限和签名 URL；单文件 commit。
+
+### Task 10：最终验证
+
+- [ ] 确认 `git status --short` 为空。
+- [ ] 确认从设计文档 commit 之后的每个 commit 都只包含一个文件。
+- [ ] 运行 `backend/unispeaking-server/./mvnw test`，期望 0 failures、0 errors。
+- [ ] 运行 `npm run build`，期望成功。
+- [ ] 运行 `npm run check:routes`，期望 32 assertions passed。
+- [ ] 运行 `npm run check:realtime-events`，期望通过。
+- [ ] 运行 `./mvnw dependency:tree`，确认没有第二套 ORM/JSON/HTTP 技术栈。
+

From 3e4b88703d166340fd97ee0e613d42af701bb591 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:35:40 +0800
Subject: [PATCH 03/62] feat: add avatar key to user schema

---
 .../src/main/resources/db/schema.sql                | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/backend/unispeaking-server/src/main/resources/db/schema.sql b/backend/unispeaking-server/src/main/resources/db/schema.sql
index 0b325a0..87882c4 100644
--- a/backend/unispeaking-server/src/main/resources/db/schema.sql
+++ b/backend/unispeaking-server/src/main/resources/db/schema.sql
@@ -17,6 +17,19 @@ CREATE TABLE IF NOT EXISTS "user" (
 ALTER TABLE "user"
 ALTER COLUMN username TYPE VARCHAR(254);
 
+ALTER TABLE "user"
+ADD COLUMN IF NOT EXISTS avatar_object_key VARCHAR(512);
+
+ALTER TABLE "user"
+DROP CONSTRAINT IF EXISTS user_avatar_object_key_check;
+
+ALTER TABLE "user"
+ADD CONSTRAINT user_avatar_object_key_check
+CHECK (avatar_object_key IS NULL OR BTRIM(avatar_object_key) <> '');
+
+COMMENT ON COLUMN "user".avatar_object_key IS
+'用户头像在对象存储中的对象 Key；不保存签名 URL、Bucket 密钥或完整访问地址';
+
 CREATE TABLE IF NOT EXISTS user_preference (
     user_id UUID PRIMARY KEY,
     preferred_voice VARCHAR(64),

From 654dd2919c40a576fc6ecdfdb1228a48ba059755 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:35:40 +0800
Subject: [PATCH 04/62] feat: add profile database migration

---
 deploy/postgres/profile.sql | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
 create mode 100644 deploy/postgres/profile.sql

diff --git a/deploy/postgres/profile.sql b/deploy/postgres/profile.sql
new file mode 100644
index 0000000..0c67328
--- /dev/null
+++ b/deploy/postgres/profile.sql
@@ -0,0 +1,16 @@
+BEGIN;
+
+ALTER TABLE "user"
+ADD COLUMN IF NOT EXISTS avatar_object_key VARCHAR(512);
+
+ALTER TABLE "user"
+DROP CONSTRAINT IF EXISTS user_avatar_object_key_check;
+
+ALTER TABLE "user"
+ADD CONSTRAINT user_avatar_object_key_check
+CHECK (avatar_object_key IS NULL OR BTRIM(avatar_object_key) <> '');
+
+COMMENT ON COLUMN "user".avatar_object_key IS
+'用户头像在对象存储中的对象 Key；不保存签名 URL、Bucket 密钥或完整访问地址';
+
+COMMIT;

From 848255bcdea47f745cc4e4c15ca2a5d156ff69f4 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:35:40 +0800
Subject: [PATCH 05/62] build: add aliyun oss sdk

---
 backend/unispeaking-server/pom.xml | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/backend/unispeaking-server/pom.xml b/backend/unispeaking-server/pom.xml
index efeac05..c86ba2c 100644
--- a/backend/unispeaking-server/pom.xml
+++ b/backend/unispeaking-server/pom.xml
@@ -26,9 +26,10 @@
 		<tag/>
 		<url/>
 	</scm>
-	<properties>
-		<java.version>21</java.version>
-		<mybatis-plus.version>3.5.17</mybatis-plus.version>
+		<properties>
+			<java.version>21</java.version>
+			<mybatis-plus.version>3.5.17</mybatis-plus.version>
+			<aliyun-oss.version>3.18.5</aliyun-oss.version>
 	</properties>
 		<dependencies>
 			<dependency>
@@ -60,11 +61,16 @@
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
 		</dependency>
-		<dependency>
-			<groupId>org.postgresql</groupId>
-			<artifactId>postgresql</artifactId>
-			<scope>runtime</scope>
-		</dependency>
+			<dependency>
+				<groupId>org.postgresql</groupId>
+				<artifactId>postgresql</artifactId>
+				<scope>runtime</scope>
+			</dependency>
+			<dependency>
+				<groupId>com.aliyun.oss</groupId>
+				<artifactId>aliyun-sdk-oss</artifactId>
+				<version>${aliyun-oss.version}</version>
+			</dependency>
 		<dependency>
 			<groupId>de.sciss</groupId>
 			<artifactId>jump3r</artifactId>

From b8c98178b73bb024aec758ccb300ea1ea4e00643 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:35:40 +0800
Subject: [PATCH 06/62] config: add profile and oss settings

---
 .../src/main/resources/application.yaml              | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/backend/unispeaking-server/src/main/resources/application.yaml b/backend/unispeaking-server/src/main/resources/application.yaml
index 201dd98..64561c9 100644
--- a/backend/unispeaking-server/src/main/resources/application.yaml
+++ b/backend/unispeaking-server/src/main/resources/application.yaml
@@ -20,6 +20,18 @@ spring:
 server:
   port: ${SERVER_PORT:8080}
 
+profile:
+  time-zone: ${PROFILE_TIME_ZONE:Asia/Shanghai}
+
+object-storage:
+  aliyun:
+    endpoint: ${OSS_ENDPOINT:}
+    bucket: ${OSS_BUCKET:}
+    access-key-id: ${OSS_ACCESS_KEY_ID:}
+    access-key-secret: ${OSS_ACCESS_KEY_SECRET:}
+    avatar-prefix: ${OSS_AVATAR_PREFIX:avatars}
+    signed-url-ttl: ${OSS_SIGNED_URL_TTL:1h}
+
 prompt:
   templates:
     directory: ${PROMPT_TEMPLATE_DIR:}

From 027fa49560412f7690c986ee0427fa4409256f2d Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:35:40 +0800
Subject: [PATCH 07/62] docs: add profile oss environment placeholders

---
 deploy/env/.env.example | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/deploy/env/.env.example b/deploy/env/.env.example
index ae4e7a6..08c1d60 100644
--- a/deploy/env/.env.example
+++ b/deploy/env/.env.example
@@ -22,6 +22,17 @@ JWT_SECRET=replace-with-at-least-32-random-bytes-in-base64
 JWT_ISSUER=unispeaking
 JWT_ACCESS_TOKEN_TTL=2h
 
+# =============================================================================
+# Profile and Alibaba Cloud OSS
+# =============================================================================
+PROFILE_TIME_ZONE=Asia/Shanghai
+OSS_ENDPOINT=
+OSS_BUCKET=
+OSS_ACCESS_KEY_ID=
+OSS_ACCESS_KEY_SECRET=
+OSS_AVATAR_PREFIX=avatars
+OSS_SIGNED_URL_TTL=1h
+
 # =============================================================================
 # AI model routes
 # The first model is primary; later models are fallbacks.

From 5a771196797633b0c815baaadbc7c5c7710466c1 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:35:40 +0800
Subject: [PATCH 08/62] config: allow profile avatar uploads

---
 deploy/nginx/nginx.conf | 1 +
 1 file changed, 1 insertion(+)

diff --git a/deploy/nginx/nginx.conf b/deploy/nginx/nginx.conf
index a78de36..7be3dc7 100644
--- a/deploy/nginx/nginx.conf
+++ b/deploy/nginx/nginx.conf
@@ -11,6 +11,7 @@ http {
 
   server {
     listen 80;
+    client_max_body_size 10m;
 
     location /backend/ {
       proxy_pass http://backend/;

From 6bbe98f886a32f23555bcddb1048deb161ce8ac9 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:28 +0800
Subject: [PATCH 09/62] feat(profile): extend user account profile fields

---
 .../domain/po/auth/UserAccount.java           | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/domain/po/auth/UserAccount.java b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/po/auth/UserAccount.java
index 887f274..454b666 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/domain/po/auth/UserAccount.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/po/auth/UserAccount.java
@@ -8,6 +8,7 @@ public record UserAccount(
 		String username,
 		String passwordHash,
 		String nickname,
+		String avatarObjectKey,
 		UserRole role,
 		UserStatus status,
 		long authVersion,
@@ -15,12 +16,28 @@ public record UserAccount(
 		Instant createdAt,
 		Instant updatedAt) {
 
+	public UserAccount(
+			UUID id,
+			String username,
+			String passwordHash,
+			String nickname,
+			UserRole role,
+			UserStatus status,
+			long authVersion,
+			Instant lastLoginAt,
+			Instant createdAt,
+			Instant updatedAt) {
+		this(id, username, passwordHash, nickname, null, role, status,
+				authVersion, lastLoginAt, createdAt, updatedAt);
+	}
+
 	public UserAccount withLastLoginAt(Instant value) {
 		return new UserAccount(
 				id,
 				username,
 				passwordHash,
 				nickname,
+				avatarObjectKey,
 				role,
 				status,
 				authVersion,
@@ -28,4 +45,19 @@ public UserAccount withLastLoginAt(Instant value) {
 				createdAt,
 				updatedAt);
 	}
+
+	public UserAccount withNickname(String value) {
+		return new UserAccount(id, username, passwordHash, value, avatarObjectKey,
+				role, status, authVersion, lastLoginAt, createdAt, updatedAt);
+	}
+
+	public UserAccount withAvatarObjectKey(String value) {
+		return new UserAccount(id, username, passwordHash, nickname, value,
+				role, status, authVersion, lastLoginAt, createdAt, updatedAt);
+	}
+
+	public UserAccount withPasswordHashAndAuthVersion(String value, long version) {
+		return new UserAccount(id, username, value, nickname, avatarObjectKey,
+				role, status, version, lastLoginAt, createdAt, updatedAt);
+	}
 }

From 23fbe962bc5b3bfa6509ac57e302675848498114 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:28 +0800
Subject: [PATCH 10/62] feat(profile): map avatar object key

---
 .../persistence/entity/user/UserAccountEntity.java               | 1 +
 1 file changed, 1 insertion(+)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/entity/user/UserAccountEntity.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/entity/user/UserAccountEntity.java
index b9d84ec..8cd8814 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/entity/user/UserAccountEntity.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/entity/user/UserAccountEntity.java
@@ -20,6 +20,7 @@ public class UserAccountEntity {
 	private String username;
 	private String passwordHash;
 	private String nickname;
+	private String avatarObjectKey;
 	private String role;
 	private String status;
 	private Long authVersion;

From 8548f10fdad7d721172239f931155d1da7f3280f Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:28 +0800
Subject: [PATCH 11/62] feat(profile): define account update operations

---
 .../persistence/repository/user/UserAccountRepository.java  | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/user/UserAccountRepository.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/user/UserAccountRepository.java
index 476a9bf..5444913 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/user/UserAccountRepository.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/user/UserAccountRepository.java
@@ -10,4 +10,10 @@ public interface UserAccountRepository {
 	Optional<UserAccount> findByUsername(String username);
 	UserAccount create(UserAccount user);
 	void updateLastLoginAt(UUID id, Instant lastLoginAt);
+	boolean updateNickname(UUID id, String nickname);
+	boolean updateAvatarObjectKey(UUID id, String expectedObjectKey, String newObjectKey);
+	boolean updatePasswordAndAuthVersion(
+			UUID id,
+			long expectedAuthVersion,
+			String passwordHash);
 }

From de3279b4139f8037701fff989b375f03f0b4fd82 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:29 +0800
Subject: [PATCH 12/62] feat(profile): persist account profile changes

---
 .../user/MybatisUserAccountRepository.java    | 42 +++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/user/MybatisUserAccountRepository.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/user/MybatisUserAccountRepository.java
index 413ad8a..84213d5 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/user/MybatisUserAccountRepository.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/user/MybatisUserAccountRepository.java
@@ -1,6 +1,7 @@
 package com.unispeaking.infrastructure.persistence.repository.user;
 
 import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
 import com.unispeaking.domain.po.auth.UserAccount;
 import com.unispeaking.domain.po.auth.UserRole;
 import com.unispeaking.domain.po.auth.UserStatus;
@@ -53,12 +54,52 @@ public void updateLastLoginAt(UUID id, Instant lastLoginAt) {
 		mapper.updateById(entity);
 	}
 
+	@Override
+	public boolean updateNickname(UUID id, String nickname) {
+		return mapper.update(null, Wrappers.<UserAccountEntity>lambdaUpdate()
+				.eq(UserAccountEntity::getId, id)
+				.set(UserAccountEntity::getNickname, nickname)
+				.set(UserAccountEntity::getUpdatedAt, OffsetDateTime.now(ZoneOffset.UTC))) == 1;
+	}
+
+	@Override
+	public boolean updateAvatarObjectKey(
+			UUID id,
+			String expectedObjectKey,
+			String newObjectKey) {
+		LambdaUpdateWrapper<UserAccountEntity> update = Wrappers.lambdaUpdate();
+		update.eq(UserAccountEntity::getId, id);
+		if (expectedObjectKey == null) {
+			update.isNull(UserAccountEntity::getAvatarObjectKey);
+		}
+		else {
+			update.eq(UserAccountEntity::getAvatarObjectKey, expectedObjectKey);
+		}
+		update.set(UserAccountEntity::getAvatarObjectKey, newObjectKey)
+				.set(UserAccountEntity::getUpdatedAt, OffsetDateTime.now(ZoneOffset.UTC));
+		return mapper.update(null, update) == 1;
+	}
+
+	@Override
+	public boolean updatePasswordAndAuthVersion(
+			UUID id,
+			long expectedAuthVersion,
+			String passwordHash) {
+		return mapper.update(null, Wrappers.<UserAccountEntity>lambdaUpdate()
+				.eq(UserAccountEntity::getId, id)
+				.eq(UserAccountEntity::getAuthVersion, expectedAuthVersion)
+				.set(UserAccountEntity::getPasswordHash, passwordHash)
+				.set(UserAccountEntity::getAuthVersion, expectedAuthVersion + 1)
+				.set(UserAccountEntity::getUpdatedAt, OffsetDateTime.now(ZoneOffset.UTC))) == 1;
+	}
+
 	private UserAccountEntity toEntity(UserAccount user) {
 		UserAccountEntity entity = new UserAccountEntity();
 		entity.setId(user.id());
 		entity.setUsername(user.username());
 		entity.setPasswordHash(user.passwordHash());
 		entity.setNickname(user.nickname());
+		entity.setAvatarObjectKey(user.avatarObjectKey());
 		entity.setRole(user.role().name());
 		entity.setStatus(user.status().name());
 		entity.setAuthVersion(user.authVersion());
@@ -74,6 +115,7 @@ private UserAccount toDomain(UserAccountEntity entity) {
 				entity.getUsername(),
 				entity.getPasswordHash(),
 				entity.getNickname(),
+				entity.getAvatarObjectKey(),
 				UserRole.valueOf(entity.getRole()),
 				UserStatus.valueOf(entity.getStatus()),
 				entity.getAuthVersion(),

From 31f3700be9fcc95ae26473f0831141319ed1d606 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:29 +0800
Subject: [PATCH 13/62] feat(profile): expose user scene ids

---
 .../persistence/repository/scene/SceneRepository.java            | 1 +
 1 file changed, 1 insertion(+)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/SceneRepository.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/SceneRepository.java
index 913ab2f..300cb22 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/SceneRepository.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/SceneRepository.java
@@ -16,4 +16,5 @@ SceneGenerationResponse saveCustomScene(
 	Optional<SceneGenerationResponse> findGeneratedById(String sceneId);
 	Optional<CustomSceneDefinition> findCustomDefinitionById(String sceneId);
 	List<SceneAssetSnapshot> findAssetsByUserId(String userId);
+	List<String> findAllIdsByUserId(String userId);
 }

From 359be8e9ad6bbe25f0b61ca1bf76cebd8e9d91c0 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:29 +0800
Subject: [PATCH 14/62] feat(profile): query all user scene ids

---
 .../scene/MybatisSceneRepository.java           | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/MybatisSceneRepository.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/MybatisSceneRepository.java
index 92f1f8d..46b117a 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/MybatisSceneRepository.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/MybatisSceneRepository.java
@@ -120,6 +120,23 @@ public List<SceneAssetSnapshot> findAssetsByUserId(String userId) {
 				.toList();
 	}
 
+	@Override
+	public List<String> findAllIdsByUserId(String userId) {
+		UUID ownerId;
+		try {
+			ownerId = UUID.fromString(userId);
+		}
+		catch (IllegalArgumentException exception) {
+			return List.of();
+		}
+		return sceneMapper.selectList(new LambdaQueryWrapper<SceneEntity>()
+						.select(SceneEntity::getId)
+						.eq(SceneEntity::getUserId, ownerId))
+				.stream()
+				.map(SceneEntity::getId)
+				.toList();
+	}
+
 	private CustomSceneDefinition toDefinition(SceneEntity scene) {
 		return new CustomSceneDefinition(
 				scene.getId(),

From e1d8c422d01b89b6333418079d1942d416db9b2d Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:29 +0800
Subject: [PATCH 15/62] feat(profile): query report timestamps

---
 .../SessionEvaluationRepository.java           | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/evaluation/SessionEvaluationRepository.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/evaluation/SessionEvaluationRepository.java
index 008ee23..dc86f63 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/evaluation/SessionEvaluationRepository.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/evaluation/SessionEvaluationRepository.java
@@ -96,6 +96,24 @@ public List<SessionEvaluationRecord> findBySceneId(String sceneId) {
 		}
 	}
 
+	public List<OffsetDateTime> findCreatedAtBySceneIdsBetween(
+			List<String> sceneIds,
+			OffsetDateTime start,
+			OffsetDateTime end) {
+		if (sceneIds == null || sceneIds.isEmpty()) {
+			return List.of();
+		}
+		return mapper.selectList(new LambdaQueryWrapper<SessionEvaluationEntity>()
+						.select(SessionEvaluationEntity::getCreatedAt)
+						.in(SessionEvaluationEntity::getSceneId, sceneIds)
+						.ge(SessionEvaluationEntity::getCreatedAt, start)
+						.lt(SessionEvaluationEntity::getCreatedAt, end)
+						.orderByAsc(SessionEvaluationEntity::getCreatedAt))
+				.stream()
+				.map(SessionEvaluationEntity::getCreatedAt)
+				.toList();
+	}
+
 	private SessionEvaluationEntity toEntity(
 			String sceneId,
 			String sessionId,

From b3acbae49605654aea52ca16e1601e7b155d2e2b Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:29 +0800
Subject: [PATCH 16/62] feat(profile): add overview response model

---
 .../dto/profile/ProfileOverviewResponse.java  | 26 +++++++++++++++++++
 1 file changed, 26 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/ProfileOverviewResponse.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/ProfileOverviewResponse.java b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/ProfileOverviewResponse.java
new file mode 100644
index 0000000..dfc9615
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/ProfileOverviewResponse.java
@@ -0,0 +1,26 @@
+package com.unispeaking.domain.dto.profile;
+
+import java.time.Instant;
+import java.time.LocalDate;
+import java.util.List;
+import java.util.UUID;
+
+public record ProfileOverviewResponse(Account account, Calendar calendar) {
+	public record Account(
+			UUID userId,
+			String email,
+			String nickname,
+			String displayName,
+			String avatarUrl,
+			Instant avatarUrlExpiresAt) {
+	}
+
+	public record Calendar(
+			String month,
+			List<LocalDate> checkedDates,
+			boolean checkedInToday) {
+		public Calendar {
+			checkedDates = List.copyOf(checkedDates);
+		}
+	}
+}

From b09642ced8700506399c0c5f8eda923b73454b53 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:29 +0800
Subject: [PATCH 17/62] feat(profile): add nickname update request

---
 .../domain/dto/profile/UpdateProfileRequest.java       | 10 ++++++++++
 1 file changed, 10 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/UpdateProfileRequest.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/UpdateProfileRequest.java b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/UpdateProfileRequest.java
new file mode 100644
index 0000000..f057867
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/UpdateProfileRequest.java
@@ -0,0 +1,10 @@
+package com.unispeaking.domain.dto.profile;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Size;
+
+public record UpdateProfileRequest(
+		@NotBlank(message = "不能为空")
+		@Size(max = 32, message = "不能超过 32 个字符")
+		String nickname) {
+}

From 29258c6edfbf124eca3f43325a3a5b64eeeb2109 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:29 +0800
Subject: [PATCH 18/62] feat(profile): add nickname update response

---
 .../unispeaking/domain/dto/profile/UpdateProfileResponse.java | 4 ++++
 1 file changed, 4 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/UpdateProfileResponse.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/UpdateProfileResponse.java b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/UpdateProfileResponse.java
new file mode 100644
index 0000000..bf57659
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/UpdateProfileResponse.java
@@ -0,0 +1,4 @@
+package com.unispeaking.domain.dto.profile;
+
+public record UpdateProfileResponse(String nickname, String displayName) {
+}

From 3469ce42e0f3a98953a9b9226408addae8ebf7df Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:29 +0800
Subject: [PATCH 19/62] feat(profile): add avatar response

---
 .../com/unispeaking/domain/dto/profile/AvatarResponse.java  | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/AvatarResponse.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/AvatarResponse.java b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/AvatarResponse.java
new file mode 100644
index 0000000..11713ad
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/AvatarResponse.java
@@ -0,0 +1,6 @@
+package com.unispeaking.domain.dto.profile;
+
+import java.time.Instant;
+
+public record AvatarResponse(String avatarUrl, Instant avatarUrlExpiresAt) {
+}

From dcfbac4e27229eea44ecb1d5c6e68b67d84831fa Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:29 +0800
Subject: [PATCH 20/62] feat(profile): add profile settings binding

---
 .../config/ProfileProperties.java             | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ProfileProperties.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ProfileProperties.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ProfileProperties.java
new file mode 100644
index 0000000..45b28b0
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ProfileProperties.java
@@ -0,0 +1,21 @@
+package com.unispeaking.infrastructure.config;
+
+import java.time.ZoneId;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+@ConfigurationProperties("profile")
+public class ProfileProperties {
+	private String timeZone = "Asia/Shanghai";
+
+	public String getTimeZone() {
+		return timeZone;
+	}
+
+	public void setTimeZone(String timeZone) {
+		this.timeZone = timeZone;
+	}
+
+	public ZoneId zoneId() {
+		return ZoneId.of(timeZone);
+	}
+}

From fc083425d4058b1404d220b792dfaa5057faa583 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:29 +0800
Subject: [PATCH 21/62] feat(profile): add object storage settings binding

---
 .../config/ObjectStorageProperties.java       | 31 +++++++++++++++++++
 1 file changed, 31 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageProperties.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageProperties.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageProperties.java
new file mode 100644
index 0000000..6854e79
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageProperties.java
@@ -0,0 +1,31 @@
+package com.unispeaking.infrastructure.config;
+
+import java.time.Duration;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+@ConfigurationProperties("object-storage.aliyun")
+public class ObjectStorageProperties {
+	private String endpoint = "";
+	private String bucket = "";
+	private String accessKeyId = "";
+	private String accessKeySecret = "";
+	private String avatarPrefix = "avatars";
+	private Duration signedUrlTtl = Duration.ofHours(1);
+
+	public boolean configured() {
+		return !endpoint.isBlank() && !bucket.isBlank()
+				&& !accessKeyId.isBlank() && !accessKeySecret.isBlank();
+	}
+	public String getEndpoint() { return endpoint; }
+	public void setEndpoint(String value) { endpoint = value == null ? "" : value.trim(); }
+	public String getBucket() { return bucket; }
+	public void setBucket(String value) { bucket = value == null ? "" : value.trim(); }
+	public String getAccessKeyId() { return accessKeyId; }
+	public void setAccessKeyId(String value) { accessKeyId = value == null ? "" : value.trim(); }
+	public String getAccessKeySecret() { return accessKeySecret; }
+	public void setAccessKeySecret(String value) { accessKeySecret = value == null ? "" : value.trim(); }
+	public String getAvatarPrefix() { return avatarPrefix; }
+	public void setAvatarPrefix(String value) { avatarPrefix = value == null ? "avatars" : value.trim(); }
+	public Duration getSignedUrlTtl() { return signedUrlTtl; }
+	public void setSignedUrlTtl(Duration value) { signedUrlTtl = value; }
+}

From 515a4b365eb800851378cea683b00f18baaed73c Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:29 +0800
Subject: [PATCH 22/62] feat(profile): define object storage provider

---
 .../infrastructure/storage/ObjectStorageProvider.java | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/ObjectStorageProvider.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/ObjectStorageProvider.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/ObjectStorageProvider.java
new file mode 100644
index 0000000..2f1a6e6
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/ObjectStorageProvider.java
@@ -0,0 +1,11 @@
+package com.unispeaking.infrastructure.storage;
+
+import java.net.URI;
+import java.time.Duration;
+
+public interface ObjectStorageProvider {
+	void put(String objectKey, byte[] content, String contentType);
+	URI signGetUrl(String objectKey, Duration ttl);
+	void delete(String objectKey);
+	boolean available();
+}

From f3f46994804dcbd53facffc8c36f9dfc82594576 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:29 +0800
Subject: [PATCH 23/62] feat(profile): implement Aliyun OSS provider

---
 .../AliyunOssObjectStorageProvider.java       | 68 +++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java
new file mode 100644
index 0000000..bc8b8b4
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java
@@ -0,0 +1,68 @@
+package com.unispeaking.infrastructure.storage.aliyun;
+
+import com.aliyun.oss.OSS;
+import com.aliyun.oss.model.ObjectMetadata;
+import com.unispeaking.common.exception.BusinessException;
+import com.unispeaking.infrastructure.config.ObjectStorageProperties;
+import com.unispeaking.infrastructure.storage.ObjectStorageProvider;
+import java.io.ByteArrayInputStream;
+import java.net.URI;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.Date;
+
+public class AliyunOssObjectStorageProvider implements ObjectStorageProvider {
+	private final OSS client;
+	private final ObjectStorageProperties properties;
+
+	public AliyunOssObjectStorageProvider(OSS client, ObjectStorageProperties properties) {
+		this.client = client;
+		this.properties = properties;
+	}
+
+	@Override
+	public void put(String objectKey, byte[] content, String contentType) {
+		try {
+			ObjectMetadata metadata = new ObjectMetadata();
+			metadata.setContentLength(content.length);
+			metadata.setContentType(contentType);
+			client.putObject(properties.getBucket(), objectKey,
+					new ByteArrayInputStream(content), metadata);
+		}
+		catch (RuntimeException exception) {
+			throw storageFailure();
+		}
+	}
+
+	@Override
+	public URI signGetUrl(String objectKey, Duration ttl) {
+		try {
+			return client.generatePresignedUrl(
+					properties.getBucket(),
+					objectKey,
+					Date.from(Instant.now().plus(ttl))).toURI();
+		}
+		catch (Exception exception) {
+			throw storageFailure();
+		}
+	}
+
+	@Override
+	public void delete(String objectKey) {
+		try {
+			client.deleteObject(properties.getBucket(), objectKey);
+		}
+		catch (RuntimeException exception) {
+			throw storageFailure();
+		}
+	}
+
+	@Override
+	public boolean available() {
+		return true;
+	}
+
+	private BusinessException storageFailure() {
+		return new BusinessException("AVATAR_STORAGE_FAILED", "头像存储服务暂时不可用");
+	}
+}

From 59b33b0984529fa9dff5f88a578617c366998fe8 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:29 +0800
Subject: [PATCH 24/62] feat(profile): configure avatar object storage

---
 .../config/ObjectStorageConfig.java           | 55 +++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageConfig.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageConfig.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageConfig.java
new file mode 100644
index 0000000..0ea21e5
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageConfig.java
@@ -0,0 +1,55 @@
+package com.unispeaking.infrastructure.config;
+
+import com.aliyun.oss.OSS;
+import com.aliyun.oss.OSSClientBuilder;
+import com.unispeaking.common.exception.BusinessException;
+import com.unispeaking.infrastructure.storage.ObjectStorageProvider;
+import com.unispeaking.infrastructure.storage.aliyun.AliyunOssObjectStorageProvider;
+import java.net.URI;
+import java.time.Duration;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class ObjectStorageConfig {
+
+	@Bean(destroyMethod = "")
+	ObjectStorageProvider objectStorageProvider(ObjectStorageProperties properties) {
+		if (!properties.configured()) {
+			return new UnavailableObjectStorageProvider();
+		}
+		OSS client = new OSSClientBuilder().build(
+				properties.getEndpoint(),
+				properties.getAccessKeyId(),
+				properties.getAccessKeySecret());
+		return new ManagedAliyunProvider(client, properties);
+	}
+
+	private static final class ManagedAliyunProvider
+			extends AliyunOssObjectStorageProvider {
+		private final OSS client;
+
+		private ManagedAliyunProvider(OSS client, ObjectStorageProperties properties) {
+			super(client, properties);
+			this.client = client;
+		}
+
+		@SuppressWarnings("unused")
+		public void shutdown() {
+			client.shutdown();
+		}
+	}
+
+	private static final class UnavailableObjectStorageProvider
+			implements ObjectStorageProvider {
+		@Override public void put(String key, byte[] content, String type) { throw unavailable(); }
+		@Override public URI signGetUrl(String key, Duration ttl) { throw unavailable(); }
+		@Override public void delete(String key) { throw unavailable(); }
+		@Override public boolean available() { return false; }
+		private BusinessException unavailable() {
+			return new BusinessException(
+					"AVATAR_STORAGE_UNAVAILABLE",
+					"头像存储尚未配置");
+		}
+	}
+}

From 70ac2c3687c0d9fe8c08eed9354918a95aee776e Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:30 +0800
Subject: [PATCH 25/62] feat(profile): validate and normalize avatar images

---
 .../profile/image/AvatarImageProcessor.java   | 54 +++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/image/AvatarImageProcessor.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/image/AvatarImageProcessor.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/image/AvatarImageProcessor.java
new file mode 100644
index 0000000..664c18a
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/image/AvatarImageProcessor.java
@@ -0,0 +1,54 @@
+package com.unispeaking.service.profile.image;
+
+import com.unispeaking.common.exception.BusinessException;
+import java.awt.image.BufferedImage;
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import javax.imageio.ImageIO;
+import org.springframework.stereotype.Component;
+
+@Component
+public class AvatarImageProcessor {
+	private static final int MAX_BYTES = 2 * 1024 * 1024;
+	private static final int MIN_DIMENSION = 128;
+	private static final int MAX_DIMENSION = 4096;
+
+	public ProcessedAvatar process(byte[] input) {
+		if (input == null || input.length == 0) {
+			throw error("AVATAR_FILE_REQUIRED", "请选择头像文件");
+		}
+		if (input.length > MAX_BYTES) {
+			throw error("AVATAR_FILE_TOO_LARGE", "头像不能超过 2 MB");
+		}
+		try {
+			BufferedImage image = ImageIO.read(new ByteArrayInputStream(input));
+			if (image == null) {
+				throw error("AVATAR_CONTENT_INVALID", "头像内容无法识别");
+			}
+			if (image.getWidth() < MIN_DIMENSION || image.getHeight() < MIN_DIMENSION
+					|| image.getWidth() > MAX_DIMENSION || image.getHeight() > MAX_DIMENSION) {
+				throw error("AVATAR_DIMENSION_INVALID", "头像尺寸必须在 128 到 4096 像素之间");
+			}
+			String format = image.getColorModel().hasAlpha() ? "png" : "jpg";
+			ByteArrayOutputStream output = new ByteArrayOutputStream();
+			if (!ImageIO.write(image, format, output)) {
+				throw error("AVATAR_TYPE_UNSUPPORTED", "仅支持 JPEG 和 PNG 头像");
+			}
+			return new ProcessedAvatar(
+					output.toByteArray(),
+					format.equals("png") ? "image/png" : "image/jpeg",
+					format);
+		}
+		catch (IOException exception) {
+			throw error("AVATAR_CONTENT_INVALID", "头像内容无法识别");
+		}
+	}
+
+	private BusinessException error(String code, String message) {
+		return new BusinessException(code, message);
+	}
+
+	public record ProcessedAvatar(byte[] content, String contentType, String extension) {
+	}
+}

From a013c0fec27a5a59dfa472f9b8ba48a11ee255cd Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:30 +0800
Subject: [PATCH 26/62] feat(profile): define profile overview service

---
 .../service/profile/ProfileOverviewService.java            | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/ProfileOverviewService.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/ProfileOverviewService.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/ProfileOverviewService.java
new file mode 100644
index 0000000..2e992de
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/ProfileOverviewService.java
@@ -0,0 +1,7 @@
+package com.unispeaking.service.profile;
+
+import com.unispeaking.domain.dto.profile.ProfileOverviewResponse;
+
+public interface ProfileOverviewService {
+	ProfileOverviewResponse getOverview(String userId, String month);
+}

From 31afee8edc3b6c83fb71bef997c4955a7a8e364e Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:30 +0800
Subject: [PATCH 27/62] feat(profile): derive report based checkins

---
 .../impl/ProfileOverviewServiceImpl.java      | 112 ++++++++++++++++++
 1 file changed, 112 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImpl.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImpl.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImpl.java
new file mode 100644
index 0000000..53e1fef
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImpl.java
@@ -0,0 +1,112 @@
+package com.unispeaking.service.profile.impl;
+
+import com.unispeaking.common.exception.BusinessException;
+import com.unispeaking.domain.dto.profile.ProfileOverviewResponse;
+import com.unispeaking.domain.po.auth.UserAccount;
+import com.unispeaking.infrastructure.config.ObjectStorageProperties;
+import com.unispeaking.infrastructure.config.ProfileProperties;
+import com.unispeaking.infrastructure.persistence.repository.evaluation.SessionEvaluationRepository;
+import com.unispeaking.infrastructure.persistence.repository.scene.SceneRepository;
+import com.unispeaking.infrastructure.persistence.repository.user.UserAccountRepository;
+import com.unispeaking.infrastructure.storage.ObjectStorageProvider;
+import com.unispeaking.service.profile.ProfileOverviewService;
+import java.net.URI;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.YearMonth;
+import java.time.ZoneId;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeParseException;
+import java.util.List;
+import java.util.UUID;
+import org.springframework.stereotype.Service;
+
+@Service
+public class ProfileOverviewServiceImpl implements ProfileOverviewService {
+	private final UserAccountRepository accounts;
+	private final SceneRepository scenes;
+	private final SessionEvaluationRepository evaluations;
+	private final ObjectStorageProvider storage;
+	private final ObjectStorageProperties storageProperties;
+	private final ZoneId zoneId;
+
+	public ProfileOverviewServiceImpl(
+			UserAccountRepository accounts,
+			SceneRepository scenes,
+			SessionEvaluationRepository evaluations,
+			ObjectStorageProvider storage,
+			ObjectStorageProperties storageProperties,
+			ProfileProperties profileProperties) {
+		this.accounts = accounts;
+		this.scenes = scenes;
+		this.evaluations = evaluations;
+		this.storage = storage;
+		this.storageProperties = storageProperties;
+		this.zoneId = profileProperties.zoneId();
+	}
+
+	@Override
+	public ProfileOverviewResponse getOverview(String userId, String requestedMonth) {
+		UUID id = UUID.fromString(userId);
+		UserAccount user = accounts.findById(id)
+				.orElseThrow(() -> new BusinessException("USER_NOT_FOUND", "用户不存在"));
+		YearMonth current = YearMonth.now(zoneId);
+		YearMonth month = parseMonth(requestedMonth, current);
+		if (month.isAfter(current)) {
+			throw new BusinessException("PROFILE_MONTH_INVALID", "不能查看未来月份");
+		}
+		Instant start = month.atDay(1).atStartOfDay(zoneId).toInstant();
+		Instant end = month.plusMonths(1).atDay(1).atStartOfDay(zoneId).toInstant();
+		List<LocalDate> dates = evaluations.findCreatedAtBySceneIdsBetween(
+						scenes.findAllIdsByUserId(userId),
+						start.atOffset(ZoneOffset.UTC),
+						end.atOffset(ZoneOffset.UTC))
+				.stream()
+				.map(value -> value.toInstant().atZone(zoneId).toLocalDate())
+				.distinct()
+				.sorted()
+				.toList();
+		SignedAvatar signed = signAvatar(user.avatarObjectKey());
+		String displayName = displayName(user);
+		return new ProfileOverviewResponse(
+				new ProfileOverviewResponse.Account(
+						user.id(), user.username(), user.nickname(), displayName,
+						signed.url(), signed.expiresAt()),
+				new ProfileOverviewResponse.Calendar(
+						month.toString(), dates, dates.contains(LocalDate.now(zoneId))));
+	}
+
+	private YearMonth parseMonth(String value, YearMonth current) {
+		if (value == null || value.isBlank()) return current;
+		try {
+			return YearMonth.parse(value.trim());
+		}
+		catch (DateTimeParseException exception) {
+			throw new BusinessException("PROFILE_MONTH_INVALID", "month 必须使用 yyyy-MM");
+		}
+	}
+
+	private SignedAvatar signAvatar(String objectKey) {
+		if (objectKey == null || objectKey.isBlank() || !storage.available()) {
+			return new SignedAvatar(null, null);
+		}
+		try {
+			URI uri = storage.signGetUrl(objectKey, storageProperties.getSignedUrlTtl());
+			return new SignedAvatar(
+					uri.toString(),
+					Instant.now().plus(storageProperties.getSignedUrlTtl()));
+		}
+		catch (BusinessException exception) {
+			return new SignedAvatar(null, null);
+		}
+	}
+
+	private String displayName(UserAccount user) {
+		if (user.nickname() != null && !user.nickname().isBlank()) return user.nickname();
+		String username = user.username() == null ? "" : user.username();
+		int at = username.indexOf('@');
+		return at > 0 ? username.substring(0, at) : "UniSpeaking User";
+	}
+
+	private record SignedAvatar(String url, Instant expiresAt) {}
+}

From c6634aca15c22041c084f7a0993ceda1ba3090d8 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:30 +0800
Subject: [PATCH 28/62] feat(profile): define profile account service

---
 .../service/profile/ProfileAccountService.java         | 10 ++++++++++
 1 file changed, 10 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/ProfileAccountService.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/ProfileAccountService.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/ProfileAccountService.java
new file mode 100644
index 0000000..7c70e7a
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/ProfileAccountService.java
@@ -0,0 +1,10 @@
+package com.unispeaking.service.profile;
+
+import com.unispeaking.domain.dto.profile.AvatarResponse;
+import com.unispeaking.domain.dto.profile.UpdateProfileRequest;
+import com.unispeaking.domain.dto.profile.UpdateProfileResponse;
+
+public interface ProfileAccountService {
+	UpdateProfileResponse updateNickname(String userId, UpdateProfileRequest request);
+	AvatarResponse replaceAvatar(String userId, byte[] content);
+}

From 3762533752484c53a29088a7252c2171d660213b Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:30 +0800
Subject: [PATCH 29/62] feat(profile): implement nickname and avatar updates

---
 .../impl/ProfileAccountServiceImpl.java       | 83 +++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileAccountServiceImpl.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileAccountServiceImpl.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileAccountServiceImpl.java
new file mode 100644
index 0000000..c8add83
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileAccountServiceImpl.java
@@ -0,0 +1,83 @@
+package com.unispeaking.service.profile.impl;
+
+import com.unispeaking.common.exception.BusinessException;
+import com.unispeaking.domain.dto.profile.AvatarResponse;
+import com.unispeaking.domain.dto.profile.UpdateProfileRequest;
+import com.unispeaking.domain.dto.profile.UpdateProfileResponse;
+import com.unispeaking.domain.po.auth.UserAccount;
+import com.unispeaking.infrastructure.config.ObjectStorageProperties;
+import com.unispeaking.infrastructure.persistence.repository.user.UserAccountRepository;
+import com.unispeaking.infrastructure.storage.ObjectStorageProvider;
+import com.unispeaking.service.profile.ProfileAccountService;
+import com.unispeaking.service.profile.image.AvatarImageProcessor;
+import java.net.URI;
+import java.time.Instant;
+import java.util.UUID;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.stereotype.Service;
+
+@Service
+public class ProfileAccountServiceImpl implements ProfileAccountService {
+	private static final Logger LOGGER = LoggerFactory.getLogger(ProfileAccountServiceImpl.class);
+	private final UserAccountRepository accounts;
+	private final ObjectStorageProvider storage;
+	private final ObjectStorageProperties properties;
+	private final AvatarImageProcessor images;
+
+	public ProfileAccountServiceImpl(
+			UserAccountRepository accounts,
+			ObjectStorageProvider storage,
+			ObjectStorageProperties properties,
+			AvatarImageProcessor images) {
+		this.accounts = accounts;
+		this.storage = storage;
+		this.properties = properties;
+		this.images = images;
+	}
+
+	@Override
+	public UpdateProfileResponse updateNickname(String userId, UpdateProfileRequest request) {
+		String nickname = request.nickname().trim();
+		if (nickname.isEmpty()) {
+			throw new BusinessException("PROFILE_NICKNAME_REQUIRED", "昵称不能为空");
+		}
+		UUID id = UUID.fromString(userId);
+		if (!accounts.updateNickname(id, nickname)) {
+			throw new BusinessException("PROFILE_UPDATE_CONFLICT", "资料已发生变化，请重试");
+		}
+		return new UpdateProfileResponse(nickname, nickname);
+	}
+
+	@Override
+	public AvatarResponse replaceAvatar(String userId, byte[] content) {
+		if (!storage.available()) {
+			throw new BusinessException("AVATAR_STORAGE_UNAVAILABLE", "头像存储尚未配置");
+		}
+		UUID id = UUID.fromString(userId);
+		UserAccount user = accounts.findById(id)
+				.orElseThrow(() -> new BusinessException("USER_NOT_FOUND", "用户不存在"));
+		var avatar = images.process(content);
+		String prefix = properties.getAvatarPrefix().replaceAll("^/+|/+$", "");
+		String key = prefix + "/" + userId + "/" + UUID.randomUUID() + "." + avatar.extension();
+		storage.put(key, avatar.content(), avatar.contentType());
+		if (!accounts.updateAvatarObjectKey(id, user.avatarObjectKey(), key)) {
+			safeDelete(key);
+			throw new BusinessException("PROFILE_UPDATE_CONFLICT", "头像已发生变化，请重试");
+		}
+		if (user.avatarObjectKey() != null) safeDelete(user.avatarObjectKey());
+		URI signed = storage.signGetUrl(key, properties.getSignedUrlTtl());
+		return new AvatarResponse(
+				signed.toString(),
+				Instant.now().plus(properties.getSignedUrlTtl()));
+	}
+
+	private void safeDelete(String key) {
+		try {
+			storage.delete(key);
+		}
+		catch (BusinessException exception) {
+			LOGGER.warn("avatar object cleanup failed");
+		}
+	}
+}

From 691056028e9be5364888c40708fc0430e9775698 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:30 +0800
Subject: [PATCH 30/62] feat(profile): expose profile account endpoints

---
 .../controller/ProfileController.java         | 59 +++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/controller/ProfileController.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/controller/ProfileController.java b/backend/unispeaking-server/src/main/java/com/unispeaking/controller/ProfileController.java
new file mode 100644
index 0000000..a5f4040
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/controller/ProfileController.java
@@ -0,0 +1,59 @@
+package com.unispeaking.controller;
+
+import com.unispeaking.common.response.ApiResponse;
+import com.unispeaking.domain.dto.profile.AvatarResponse;
+import com.unispeaking.domain.dto.profile.ProfileOverviewResponse;
+import com.unispeaking.domain.dto.profile.UpdateProfileRequest;
+import com.unispeaking.domain.dto.profile.UpdateProfileResponse;
+import com.unispeaking.service.auth.AuthService;
+import com.unispeaking.service.profile.ProfileAccountService;
+import com.unispeaking.service.profile.ProfileOverviewService;
+import jakarta.validation.Valid;
+import java.io.IOException;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PatchMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RequestPart;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.multipart.MultipartFile;
+
+@RestController
+@RequestMapping("/api/profile")
+public class ProfileController {
+	private final AuthService authService;
+	private final ProfileOverviewService overviewService;
+	private final ProfileAccountService accountService;
+
+	public ProfileController(
+			AuthService authService,
+			ProfileOverviewService overviewService,
+			ProfileAccountService accountService) {
+		this.authService = authService;
+		this.overviewService = overviewService;
+		this.accountService = accountService;
+	}
+
+	@GetMapping("/overview")
+	public ApiResponse<ProfileOverviewResponse> overview(
+			@RequestParam(required = false) String month) {
+		return ApiResponse.success(overviewService.getOverview(
+				authService.requireUserId(null), month));
+	}
+
+	@PatchMapping
+	public ApiResponse<UpdateProfileResponse> update(
+			@Valid @RequestBody UpdateProfileRequest request) {
+		return ApiResponse.success(accountService.updateNickname(
+				authService.requireUserId(null), request));
+	}
+
+	@PostMapping("/avatar")
+	public ApiResponse<AvatarResponse> avatar(
+			@RequestPart("avatar") MultipartFile avatar) throws IOException {
+		return ApiResponse.success(accountService.replaceAvatar(
+				authService.requireUserId(null), avatar.getBytes()));
+	}
+}

From 225456470c89491adc546c9cb10167c85107d034 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:30 +0800
Subject: [PATCH 31/62] feat(auth): add password change request

---
 .../domain/dto/auth/ChangePasswordRequest.java      | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/auth/ChangePasswordRequest.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/auth/ChangePasswordRequest.java b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/auth/ChangePasswordRequest.java
new file mode 100644
index 0000000..e233d9b
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/auth/ChangePasswordRequest.java
@@ -0,0 +1,13 @@
+package com.unispeaking.domain.dto.auth;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Size;
+
+public record ChangePasswordRequest(
+		@NotBlank(message = "不能为空")
+		@Size(min = 6, max = 72, message = "长度必须为 6 到 72 位")
+		String currentPassword,
+		@NotBlank(message = "不能为空")
+		@Size(min = 6, max = 72, message = "长度必须为 6 到 72 位")
+		String newPassword) {
+}

From c988ff6b1917d7c7a959aa4653044e8b4dc3cd99 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:30 +0800
Subject: [PATCH 32/62] feat(auth): add password change response

---
 .../domain/dto/auth/ChangePasswordResponse.java            | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/auth/ChangePasswordResponse.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/auth/ChangePasswordResponse.java b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/auth/ChangePasswordResponse.java
new file mode 100644
index 0000000..f011244
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/auth/ChangePasswordResponse.java
@@ -0,0 +1,7 @@
+package com.unispeaking.domain.dto.auth;
+
+public record ChangePasswordResponse(boolean reauthenticationRequired) {
+	public static ChangePasswordResponse required() {
+		return new ChangePasswordResponse(true);
+	}
+}

From 9d49433b62b319fa92c35b0540b713767cb36d2f Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:30 +0800
Subject: [PATCH 33/62] feat(auth): define password change operation

---
 .../main/java/com/unispeaking/service/auth/AuthService.java    | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/auth/AuthService.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/auth/AuthService.java
index 0ceb093..35ed6ae 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/service/auth/AuthService.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/auth/AuthService.java
@@ -1,6 +1,8 @@
 package com.unispeaking.service.auth;
 
 import com.unispeaking.domain.dto.auth.AuthResponse;
+import com.unispeaking.domain.dto.auth.ChangePasswordRequest;
+import com.unispeaking.domain.dto.auth.ChangePasswordResponse;
 import com.unispeaking.domain.dto.auth.LoginRequest;
 import com.unispeaking.domain.dto.auth.RegisterRequest;
 import com.unispeaking.domain.dto.auth.UserAccountResponse;
@@ -9,5 +11,6 @@ public interface AuthService {
 	AuthResponse register(RegisterRequest request);
 	AuthResponse login(LoginRequest request);
 	UserAccountResponse currentUser();
+	ChangePasswordResponse changePassword(ChangePasswordRequest request);
 	String requireUserId(String requestedUserId);
 }

From b02326b5db3e26b51973bbc8927035b9b3bd2fd2 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:30 +0800
Subject: [PATCH 34/62] feat(auth): implement password rotation

---
 .../service/auth/impl/AuthServiceImpl.java    | 20 +++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/auth/impl/AuthServiceImpl.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/auth/impl/AuthServiceImpl.java
index c105fab..3349b9f 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/service/auth/impl/AuthServiceImpl.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/auth/impl/AuthServiceImpl.java
@@ -1,6 +1,8 @@
 package com.unispeaking.service.auth.impl;
 
 import com.unispeaking.domain.dto.auth.AuthResponse;
+import com.unispeaking.domain.dto.auth.ChangePasswordRequest;
+import com.unispeaking.domain.dto.auth.ChangePasswordResponse;
 import com.unispeaking.domain.dto.auth.LoginRequest;
 import com.unispeaking.domain.dto.auth.RegisterRequest;
 import com.unispeaking.domain.dto.auth.UserAccountResponse;
@@ -98,6 +100,24 @@ public UserAccountResponse currentUser() {
 		return UserAccountResponse.from(requireAuthenticatedUser());
 	}
 
+	@Override
+	@Transactional
+	public ChangePasswordResponse changePassword(ChangePasswordRequest request) {
+		UserAccount user = requireAuthenticatedUser();
+		if (!passwordEncoder.matches(request.currentPassword(), user.passwordHash())) {
+			throw new BusinessException("CURRENT_PASSWORD_INVALID", "当前密码不正确");
+		}
+		if (passwordEncoder.matches(request.newPassword(), user.passwordHash())) {
+			throw new BusinessException("NEW_PASSWORD_SAME_AS_CURRENT", "新密码不能与当前密码相同");
+		}
+		String encoded = passwordEncoder.encode(request.newPassword());
+		if (!userAccountRepository.updatePasswordAndAuthVersion(
+				user.id(), user.authVersion(), encoded)) {
+			throw new BusinessException("PASSWORD_UPDATE_CONFLICT", "账号已发生变化，请重新登录后再试");
+		}
+		return ChangePasswordResponse.required();
+	}
+
 	@Override
 	public String requireUserId(String requestedUserId) {
 		return requireAuthenticatedUser().id().toString();

From e64136a64f3db676a1a0d8bb1a6aff2f19aeb2a3 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:30 +0800
Subject: [PATCH 35/62] feat(auth): expose password change endpoint

---
 .../java/com/unispeaking/controller/AuthController.java  | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/controller/AuthController.java b/backend/unispeaking-server/src/main/java/com/unispeaking/controller/AuthController.java
index 4667856..d7863b2 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/controller/AuthController.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/controller/AuthController.java
@@ -1,6 +1,8 @@
 package com.unispeaking.controller;
 
 import com.unispeaking.domain.dto.auth.AuthResponse;
+import com.unispeaking.domain.dto.auth.ChangePasswordRequest;
+import com.unispeaking.domain.dto.auth.ChangePasswordResponse;
 import com.unispeaking.domain.dto.auth.LoginRequest;
 import com.unispeaking.domain.dto.auth.RegisterRequest;
 import com.unispeaking.domain.dto.auth.UserAccountResponse;
@@ -9,6 +11,7 @@
 import jakarta.validation.Valid;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
@@ -37,4 +40,10 @@ public ApiResponse<AuthResponse> login(@Valid @RequestBody LoginRequest request)
 	public ApiResponse<UserAccountResponse> me() {
 		return ApiResponse.success(authService.currentUser());
 	}
+
+	@PutMapping("/password")
+	public ApiResponse<ChangePasswordResponse> changePassword(
+			@Valid @RequestBody ChangePasswordRequest request) {
+		return ApiResponse.success(authService.changePassword(request));
+	}
 }

From 6e44687d75a0fdf0db1335d9ca775b302c78d1da Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:41:31 +0800
Subject: [PATCH 36/62] feat(api): map profile operation failures

---
 .../common/exception/GlobalExceptionHandler.java           | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/common/exception/GlobalExceptionHandler.java b/backend/unispeaking-server/src/main/java/com/unispeaking/common/exception/GlobalExceptionHandler.java
index 8898366..43336fe 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/common/exception/GlobalExceptionHandler.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/common/exception/GlobalExceptionHandler.java
@@ -17,7 +17,12 @@ public ResponseEntity<ApiResponse<Void>> handleBusinessException(BusinessExcepti
 			case "AUTHENTICATION_REQUIRED", "INVALID_ACCESS_TOKEN", "ACCESS_TOKEN_REVOKED",
 					"INVALID_CREDENTIALS", "USER_NOT_ACTIVE" -> HttpStatus.UNAUTHORIZED;
 			case "SESSION_ACCESS_DENIED" -> HttpStatus.FORBIDDEN;
-			case "USERNAME_ALREADY_EXISTS" -> HttpStatus.CONFLICT;
+			case "USERNAME_ALREADY_EXISTS", "PASSWORD_UPDATE_CONFLICT",
+					"PROFILE_UPDATE_CONFLICT" -> HttpStatus.CONFLICT;
+			case "AVATAR_STORAGE_FAILED" -> HttpStatus.BAD_GATEWAY;
+			case "AVATAR_STORAGE_UNAVAILABLE" -> HttpStatus.SERVICE_UNAVAILABLE;
+			case "AVATAR_DIMENSION_INVALID", "AVATAR_CONTENT_INVALID" ->
+					HttpStatus.UNPROCESSABLE_ENTITY;
 			default -> HttpStatus.BAD_REQUEST;
 		};
 		return ResponseEntity.status(status)

From 793a79ca55b5206ccde7fcbb0eb546bbbf717642 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:47:25 +0800
Subject: [PATCH 37/62] feat(profile): add profile account API client

---
 frontend/Unispeaking_fronted/src/apiClient.js | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/frontend/Unispeaking_fronted/src/apiClient.js b/frontend/Unispeaking_fronted/src/apiClient.js
index dbbe14f..8c58d11 100644
--- a/frontend/Unispeaking_fronted/src/apiClient.js
+++ b/frontend/Unispeaking_fronted/src/apiClient.js
@@ -66,6 +66,34 @@ export function getCurrentUser() {
   return request("/api/auth/me");
 }
 
+export function getProfileOverview(month) {
+  const query = month ? `?month=${encodeURIComponent(month)}` : "";
+  return request(`/api/profile/overview${query}`);
+}
+
+export function updateProfile({ nickname }) {
+  return request("/api/profile", {
+    method: "PATCH",
+    body: JSON.stringify({ nickname }),
+  });
+}
+
+export function uploadProfileAvatar(file) {
+  const formData = new FormData();
+  formData.append("avatar", file);
+  return request("/api/profile/avatar", {
+    method: "POST",
+    body: formData,
+  });
+}
+
+export function changePassword({ currentPassword, newPassword }) {
+  return request("/api/auth/password", {
+    method: "PUT",
+    body: JSON.stringify({ currentPassword, newPassword }),
+  });
+}
+
 export function getUserPreference() {
   return request("/api/user-preferences");
 }

From 9aad901a28f92e0ace21dcd634614a476e0ef1fc Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:47:25 +0800
Subject: [PATCH 38/62] feat(profile): connect account and report checkins

---
 frontend/Unispeaking_fronted/src/App.jsx | 198 +++++++++++++++++------
 1 file changed, 148 insertions(+), 50 deletions(-)

diff --git a/frontend/Unispeaking_fronted/src/App.jsx b/frontend/Unispeaking_fronted/src/App.jsx
index d217b56..25cb918 100644
--- a/frontend/Unispeaking_fronted/src/App.jsx
+++ b/frontend/Unispeaking_fronted/src/App.jsx
@@ -59,6 +59,7 @@ import {
 } from "lucide-react";
 import { learningItems, levels, plans, recommendations, teachers } from "./data.js";
 import {
+  changePassword,
   clearAuthSession,
   advanceCustomSceneFlow,
   createCustomSceneFlow,
@@ -67,6 +68,7 @@ import {
   getCurrentUser,
   getLearningAsset,
   getLearningAssets,
+  getProfileOverview,
   getUserPreference,
   hasAuthSession,
   login,
@@ -74,7 +76,9 @@ import {
   synthesizeSpeech,
   translateSceneText,
   translateSessionText,
+  updateProfile,
   updateUserPreference,
+  uploadProfileAvatar,
 } from "./apiClient.js";
 import { createPcmWavRecorder } from "./audioRecorder.js";
 import { createRealtimeClient } from "./realtimeClient.js";
@@ -569,7 +573,7 @@ function TeacherSetup({ selectedId, onSelect, onFinish }) {
   );
 }
 
-function AppShell({ page, setPage, teacher, children }) {
+function AppShell({ page, setPage, teacher, avatarUrl, children }) {
   const [sidebarOpen, setSidebarOpen] = useState(false);
   const items = [
     { id: "conversation", label: "自由对话", icon: Waveform },
@@ -582,7 +586,7 @@ function AppShell({ page, setPage, teacher, children }) {
       <aside className={cx("sidebar", sidebarOpen && "is-open")} onMouseEnter={() => setSidebarOpen(true)} onMouseLeave={() => setSidebarOpen(false)}>
         <Brand compact={!sidebarOpen} />
         <nav>{items.map(({ id, label, icon: Icon }) => <button key={id} className={cx("sidebar__item", activePage === id && "is-active")} onClick={() => { if (activePage !== id) setPage(id); }} aria-label={label} title={label}><Icon weight={activePage === id ? "bold" : "regular"} /><span className="sidebar__label"><span>{label}</span></span></button>)}</nav>
-        <button className={cx("sidebar__avatar", ["profile", "membership", "settings"].includes(page) && "is-active")} onClick={() => setPage("profile")}><img src={teacher.image} alt="个人中心" /></button>
+        <button className={cx("sidebar__avatar", ["profile", "membership", "settings"].includes(page) && "is-active")} onClick={() => setPage("profile")}><img src={avatarUrl || teacher.image} alt="个人中心" /></button>
       </aside>
       <div className="app-main">{children}</div>
     </div>
@@ -1210,7 +1214,7 @@ function ResultModal({ completed, evaluation, onBack, onAssets }) {
   return (
     <Modal wide dismissible={false} className="result-modal">
       <header className="result-modal__header">
-        <div><p className="eyebrow">SIMULATION COMPLETE</p><h2>{completed ? "模拟完成" : "本次模拟已结束"}</h2><p className="result-modal__lead">{evaluation?.summary || "会话已经结束，但评分报告暂未返回。请稍后在学习资产中查看。"}</p></div>
+        <div><p className="eyebrow">SIMULATION COMPLETE</p><h2>{completed ? "模拟完成" : "本次模拟已结束"}</h2>{evaluation && <span className="result-checkin"><CalendarCheck2 />今日已自动打卡</span>}<p className="result-modal__lead">{evaluation?.summary || "会话已经结束，但评分报告暂未返回。请稍后在学习资产中查看。"}</p></div>
         <div className="result-modal__score"><strong>{totalScore}</strong><span>/100</span></div>
       </header>
       <section className="result-modal__overview">
@@ -1965,29 +1969,27 @@ function Assets({ sceneId, onPractice, onRestart, onIelts, onInterview, onOpenRe
   );
 }
 
-function Profile({ section, setSection, user, teacher, speed, level, onSettingsChange, onLogout }) {
-  const displayName = user?.nickname || user?.username?.split("@")[0] || "UniSpeaking User";
-  const email = user?.username || "";
+function Profile({ section, setSection, user, profile, teacher, speed, level, onSettingsChange, onMonthChange, onNicknameChange, onAvatarChange, onPasswordChange, onLogout }) {
+  const account = profile?.account;
+  const displayName = account?.displayName || user?.nickname || user?.username?.split("@")[0] || "UniSpeaking User";
+  const email = account?.email || user?.username || "";
+  const avatarUrl = account?.avatarUrl || teacher.image;
+  const avatarInputRef = useRef(null);
+  const editNickname = async () => {
+    const nickname = window.prompt("请输入新的用户名（昵称）", account?.nickname || user?.nickname || "");
+    if (nickname === null) return;
+    await onNicknameChange(nickname.trim());
+  };
+  const selectAvatar = async (event) => {
+    const file = event.target.files?.[0];
+    event.target.value = "";
+    if (file) await onAvatarChange(file);
+  };
   return (
-    <main className="profile-layout"><aside className="profile-nav"><div className="profile-user"><img src={teacher.image} alt={displayName} /><span><strong>{displayName}</strong><small>{email}</small></span></div><nav><button className={section === "profile" ? "is-active" : ""} onClick={() => setSection("profile")}><User />个人概览</button><button className={section === "membership" ? "is-active" : ""} onClick={() => setSection("membership")}><Crown />会员权益</button><button className={section === "settings" ? "is-active" : ""} onClick={() => setSection("settings")}><SlidersHorizontal />助手设置</button></nav><button className="logout" onClick={onLogout}><SignOut />退出登录</button></aside><section className="profile-content">{section === "profile" && <Overview />}{section === "membership" && <Membership />}{section === "settings" && <Settings teacher={teacher} speed={speed} level={level} onSettingsChange={onSettingsChange} />}</section></main>
+    <main className="profile-layout"><aside className="profile-nav"><div className="profile-user"><img src={avatarUrl} alt={displayName} /><span><strong>{displayName}</strong><small>{email}</small></span></div><div className="profile-user-actions"><button type="button" onClick={editNickname}>修改用户名</button><button type="button" onClick={() => avatarInputRef.current?.click()}>更换头像</button><input ref={avatarInputRef} type="file" accept="image/jpeg,image/png" onChange={selectAvatar} /></div><nav><button className={section === "profile" ? "is-active" : ""} onClick={() => setSection("profile")}><User />个人概览</button><button className={section === "membership" ? "is-active" : ""} onClick={() => setSection("membership")}><Crown />会员权益</button><button className={section === "settings" ? "is-active" : ""} onClick={() => setSection("settings")}><SlidersHorizontal />助手设置</button></nav><button className="logout" onClick={onLogout}><SignOut />退出登录</button></aside><section className="profile-content">{section === "profile" && <Overview calendar={profile?.calendar} onMonthChange={onMonthChange} />}{section === "membership" && <Membership />}{section === "settings" && <Settings teacher={teacher} speed={speed} level={level} onSettingsChange={onSettingsChange} onPasswordChange={onPasswordChange} />}</section></main>
   );
 }
 
-const learningMonths = [
-  {
-    key: "2026-05", year: 2026, month: 4, label: "2026 年 5 月",
-    records: { 2: [14, 1, 2], 5: [22, 2, 3], 8: [18, 1, 2], 12: [31, 2, 4], 13: [12, 1, 1], 17: [26, 2, 3], 20: [35, 3, 5], 24: [19, 1, 2], 27: [28, 2, 4], 30: [16, 1, 2] },
-  },
-  {
-    key: "2026-06", year: 2026, month: 5, label: "2026 年 6 月",
-    records: { 1: [20, 1, 2], 3: [28, 2, 3], 4: [16, 1, 2], 7: [34, 2, 4], 9: [15, 1, 2], 10: [25, 2, 3], 14: [38, 3, 5], 15: [18, 1, 2], 18: [31, 2, 4], 19: [12, 1, 1], 21: [27, 2, 3], 23: [35, 3, 5], 24: [22, 2, 3], 28: [29, 2, 4], 30: [17, 1, 2] },
-  },
-  {
-    key: "2026-07", year: 2026, month: 6, label: "2026 年 7 月",
-    records: { 1: [18, 1, 2], 2: [26, 2, 3], 4: [34, 2, 4], 5: [12, 1, 1], 7: [40, 3, 5], 8: [31, 2, 4], 9: [22, 2, 3], 11: [24, 2, 3], 12: [16, 1, 2], 14: [33, 2, 4], 15: [20, 1, 2], 16: [29, 2, 4], 17: [37, 3, 5], 18: [34, 2, 4], 19: [18, 1, 2], 20: [28, 2, 4] },
-  },
-];
-
 const achievements = [
   { id: "first-talk", title: "初次开口", desc: "完成首次自由对话", category: "开口", progress: 1, total: 1, icon: MessageCircleMore },
   { id: "seven-days", title: "七日同行", desc: "连续学习 7 天", category: "连续", progress: 7, total: 7, icon: Footprints },
@@ -2003,38 +2005,45 @@ const achievements = [
   { id: "speaking-master", title: "口语大师", desc: "解锁其余全部成就", category: "场景", progress: 4, total: 11, icon: Trophy },
 ];
 
-function LearningCalendar() {
-  const [monthIndex, setMonthIndex] = useState(learningMonths.length - 1);
-  const [selectedDay, setSelectedDay] = useState(20);
-  const month = learningMonths[monthIndex];
-  const daysInMonth = new Date(month.year, month.month + 1, 0).getDate();
-  const leadingDays = (new Date(month.year, month.month, 1).getDay() + 6) % 7;
-  const selectedRecord = month.records[selectedDay];
-  const changeMonth = (nextIndex) => {
-    const nextMonth = learningMonths[nextIndex];
-    const latestRecordedDay = Math.max(...Object.keys(nextMonth.records).map(Number));
-    setMonthIndex(nextIndex);
-    setSelectedDay(latestRecordedDay);
+function LearningCalendar({ calendar, onMonthChange }) {
+  const monthKey = calendar?.month || new Date().toLocaleDateString("sv-SE", { timeZone: "Asia/Shanghai" }).slice(0, 7);
+  const [year, monthNumber] = monthKey.split("-").map(Number);
+  const checkedDays = new Set((calendar?.checkedDates || []).map((date) => Number(date.slice(-2))));
+  const today = new Date().toLocaleDateString("sv-SE", { timeZone: "Asia/Shanghai" });
+  const todayDay = today.startsWith(monthKey) ? Number(today.slice(-2)) : null;
+  const latestCheckedDay = Math.max(0, ...checkedDays);
+  const [selectedDay, setSelectedDay] = useState(todayDay || latestCheckedDay || 1);
+  useEffect(() => {
+    setSelectedDay(todayDay || latestCheckedDay || 1);
+  }, [monthKey]);
+  const daysInMonth = new Date(year, monthNumber, 0).getDate();
+  const leadingDays = (new Date(year, monthNumber - 1, 1).getDay() + 6) % 7;
+  const label = `${year} 年 ${monthNumber} 月`;
+  const selectedRecord = checkedDays.has(selectedDay);
+  const currentMonth = today.slice(0, 7);
+  const shiftMonth = (offset) => {
+    const shifted = new Date(Date.UTC(year, monthNumber - 1 + offset, 1));
+    return `${shifted.getUTCFullYear()}-${String(shifted.getUTCMonth() + 1).padStart(2, "0")}`;
   };
   return (
     <article className="calendar-card">
       <header className="calendar-card__header">
         <div><p className="eyebrow">LEARNING CALENDAR</p><h2>学习日历</h2></div>
         <div className="calendar-month-switcher">
-          <button type="button" aria-label="查看上一个月" disabled={monthIndex === 0} onClick={() => changeMonth(monthIndex - 1)}><ChevronLeft /></button>
-          <strong aria-live="polite">{month.label}</strong>
-          <button type="button" aria-label="查看下一个月" disabled={monthIndex === learningMonths.length - 1} onClick={() => changeMonth(monthIndex + 1)}><ChevronRight /></button>
+          <button type="button" aria-label="查看上一个月" onClick={() => onMonthChange(shiftMonth(-1))}><ChevronLeft /></button>
+          <strong aria-live="polite">{label}</strong>
+          <button type="button" aria-label="查看下一个月" disabled={monthKey >= currentMonth} onClick={() => onMonthChange(shiftMonth(1))}><ChevronRight /></button>
         </div>
       </header>
       <div className="calendar-weekdays" aria-hidden="true">{["一", "二", "三", "四", "五", "六", "日"].map((day) => <span key={day}>周{day}</span>)}</div>
-      <div className="calendar-days" role="grid" aria-label={`${month.label}学习记录`}>
+      <div className="calendar-days" role="grid" aria-label={`${label}学习记录`}>
         {Array.from({ length: leadingDays }, (_, index) => <span key={`blank-${index}`} className="calendar-blank" />)}
         {Array.from({ length: daysInMonth }, (_, index) => {
           const day = index + 1;
-          const record = month.records[day];
-          const isToday = month.key === "2026-07" && day === 20;
+          const record = checkedDays.has(day);
+          const isToday = todayDay === day;
           return (
-            <button key={day} type="button" role="gridcell" aria-label={`${month.label}${day}日${record ? `，已打卡 ${record[0]} 分钟` : "，无学习记录"}`} className={cx(record && "is-practiced", isToday && "is-today", selectedDay === day && "is-selected")} onClick={() => setSelectedDay(day)}>
+            <button key={day} type="button" role="gridcell" aria-label={`${label}${day}日${record ? "，已自动打卡" : "，无打卡记录"}`} className={cx(record && "is-practiced", isToday && "is-today", selectedDay === day && "is-selected")} onClick={() => setSelectedDay(day)}>
               <span>{day}</span>{record && <i aria-hidden="true" />}{isToday && <small>今天</small>}
             </button>
           );
@@ -2042,7 +2051,7 @@ function LearningCalendar() {
       </div>
       <div className={cx("calendar-summary", selectedRecord && "is-complete")}>
         <span className="calendar-summary__status"><CalendarCheck2 />{selectedRecord ? "已打卡" : "未打卡"}</span>
-        <div><strong>{month.month + 1} 月 {selectedDay} 日</strong><small>{selectedRecord ? `${selectedRecord[0]} 分钟 · ${selectedRecord[1]} 次练习 · ${selectedRecord[2]} 个学习资产` : "这一天还没有学习记录"}</small></div>
+        <div><strong>{monthNumber} 月 {selectedDay} 日</strong><small>{selectedRecord ? "已生成五维评分报告，自动打卡完成" : "这一天还没有五维评分报告"}</small></div>
       </div>
     </article>
   );
@@ -2070,8 +2079,8 @@ function AchievementSystem() {
   );
 }
 
-function Overview() {
-  return <><PageHeader eyebrow="PERSONAL OVERVIEW" title="你的学习空间" subtitle="把每一次开口变成看得见、可继续的成长记录。" /><div className="stat-grid"><article><Clock /><span><small>本周学习时长</small><strong>183 <em>分钟</em></strong></span></article><article><BookOpenText /><span><small>已保存学习资产</small><strong>12 <em>项</em></strong></span></article><article><Fire /><span><small>连续学习天数</small><strong>7 <em>天</em></strong></span></article></div><section className="overview-grid"><LearningCalendar /><article className="rhythm-card"><p className="eyebrow">LAST SEVEN DAYS</p><h2>练习节奏</h2><div className="bars">{[38, 62, 78, 26, 92, 70, 48].map((height, index) => <span key={index} style={{ height: `${height}%` }}><small>{[18, 26, 34, 12, 40, 31, 22][index]}m</small></span>)}</div></article></section><AchievementSystem /></>;
+function Overview({ calendar, onMonthChange }) {
+  return <><PageHeader eyebrow="PERSONAL OVERVIEW" title="你的学习空间" subtitle="把每一次开口变成看得见、可继续的成长记录。" action={calendar?.checkedInToday ? <span className="today-checkin"><CalendarCheck2 />今日已打卡</span> : null} /><div className="stat-grid"><article><Clock /><span><small>本周学习时长</small><strong>183 <em>分钟</em></strong></span></article><article><BookOpenText /><span><small>已保存学习资产</small><strong>12 <em>项</em></strong></span></article><article><Fire /><span><small>连续学习天数</small><strong>7 <em>天</em></strong></span></article></div><section className="overview-grid"><LearningCalendar calendar={calendar} onMonthChange={onMonthChange} /><article className="rhythm-card"><p className="eyebrow">LAST SEVEN DAYS</p><h2>练习节奏</h2><div className="bars">{[38, 62, 78, 26, 92, 70, 48].map((height, index) => <span key={index} style={{ height: `${height}%` }}><small>{[18, 26, 34, 12, 40, 31, 22][index]}m</small></span>)}</div></article></section><AchievementSystem /></>;
 }
 
 function Membership() {
@@ -2079,14 +2088,39 @@ function Membership() {
   return <><PageHeader eyebrow="MEMBERSHIP & PRICING" title="会员与订阅中心" subtitle="练习额度平时不会打扰你，只会在不足 20% 或无法开始时提醒。" /><div className="plan-grid">{plans.map((plan) => <article key={plan.id} className={cx("plan-card", plan.id === "pro" && "is-featured")}><div>{plan.id === "free" && <span className="plan-label">当前方案</span>}{plan.id === "pro" && <span className="plan-label">推荐</span>}<h2>{plan.name}</h2><p>{plan.desc}</p></div><p className="price"><small>¥</small><strong>{plan.price}</strong><span>{plan.suffix}</span></p><ul>{plan.features.map((feature) => <li key={feature}><Check />{feature}</li>)}</ul>{plan.id === "free" ? <div className="quota"><span><small>今日自由对话</small><strong>3 / 5 分钟</strong></span><progress value="3" max="5" /><span><small>今日普通场景</small><strong>0 / 1 次</strong></span></div> : <Button variant={plan.id === "pro" ? "primary" : "secondary"} onClick={() => setCheckout(plan)}>升级{plan.name}</Button>}</article>)}</div>{checkout && <Modal onClose={() => setCheckout(null)}><p className="eyebrow">MOCK PAYMENT</p><h2>确认升级至{checkout.name}</h2><p className="modal-lead">首版为支付演示。确认后仅展示成功状态，不会产生真实扣款。</p><dl className="checkout-summary"><div><dt>订阅方案</dt><dd>{checkout.name}</dd></div><div><dt>订阅金额</dt><dd>¥{checkout.price} / 月</dd></div><div><dt>生效时间</dt><dd>立即生效</dd></div></dl><Button onClick={() => setCheckout(null)}>模拟支付并完成</Button></Modal>}</>;
 }
 
-function Settings({ teacher, speed, level, onSettingsChange }) {
+function PasswordChangeModal({ onClose, onSubmit }) {
+  const [currentPassword, setCurrentPassword] = useState("");
+  const [newPassword, setNewPassword] = useState("");
+  const [confirmPassword, setConfirmPassword] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState("");
+  const submit = async (event) => {
+    event.preventDefault();
+    if (newPassword !== confirmPassword) {
+      setError("两次输入的新密码不一致");
+      return;
+    }
+    setSubmitting(true);
+    setError("");
+    try {
+      await onSubmit({ currentPassword, newPassword });
+    } catch (submitError) {
+      setError(submitError instanceof Error ? submitError.message : "密码修改失败");
+      setSubmitting(false);
+    }
+  };
+  return <Modal onClose={submitting ? undefined : onClose}><p className="eyebrow">ACCOUNT SECURITY</p><h2>修改密码</h2><p className="modal-lead">修改成功后，所有已登录设备都需要重新登录。</p><form className="password-form" onSubmit={submit}><label>当前密码<input type="password" autoComplete="current-password" minLength={6} maxLength={72} required value={currentPassword} onChange={(event) => setCurrentPassword(event.target.value)} /></label><label>新密码<input type="password" autoComplete="new-password" minLength={6} maxLength={72} required value={newPassword} onChange={(event) => setNewPassword(event.target.value)} /></label><label>确认新密码<input type="password" autoComplete="new-password" minLength={6} maxLength={72} required value={confirmPassword} onChange={(event) => setConfirmPassword(event.target.value)} /></label>{error && <p className="form-error" role="alert">{error}</p>}<div className="modal-actions"><Button type="button" variant="secondary" disabled={submitting} onClick={onClose}>取消</Button><Button type="submit" disabled={submitting}>{submitting ? "正在修改" : "确认修改"}</Button></div></form></Modal>;
+}
+
+function Settings({ teacher, speed, level, onSettingsChange, onPasswordChange }) {
   const [syncPulse, setSyncPulse] = useState(0);
+  const [passwordOpen, setPasswordOpen] = useState(false);
   const updateSettings = async (next) => {
     if (await onSettingsChange(next)) {
       setSyncPulse((current) => current + 1);
     }
   };
-  return <div className="assistant-settings-page"><PageHeader eyebrow="ASSISTANT SETTINGS" title="AI 助手设置" subtitle="只调整真正影响对话体验的选项。" action={<span key={syncPulse} className="sync-state"><CheckCircle />设置已同步</span>} /><section className="settings-list"><article><div><h2>对话语速</h2><p>选择更舒适的回应节奏。</p></div><SpeedSelector className="assistant-settings__speed" value={speed} onChange={(nextSpeed) => updateSettings({ speed: nextSpeed })} /></article><article><div><h2>英语水平</h2><p>新对话会按照该难度调整表达。</p></div><LevelSelect value={level} onChange={(nextLevel) => updateSettings({ level: nextLevel })} /></article><article className="teacher-settings"><div><h2>AI 老师</h2><p>每位老师有固定口音和陪练方式。</p></div><TeacherSelector className="assistant-settings__teachers" selectedId={teacher.id} onSelect={(nextTeacher) => updateSettings({ teacher: nextTeacher })} /></article><article><div><h2>账户与隐私</h2><p>管理密码与账户数据。</p></div><div className="account-actions"><button><Password />修改密码<CaretRight /></button><button className="danger"><Trash />删除账户<CaretRight /></button></div></article></section></div>;
+  return <div className="assistant-settings-page"><PageHeader eyebrow="ASSISTANT SETTINGS" title="AI 助手设置" subtitle="只调整真正影响对话体验的选项。" action={<span key={syncPulse} className="sync-state"><CheckCircle />设置已同步</span>} /><section className="settings-list"><article><div><h2>对话语速</h2><p>选择更舒适的回应节奏。</p></div><SpeedSelector className="assistant-settings__speed" value={speed} onChange={(nextSpeed) => updateSettings({ speed: nextSpeed })} /></article><article><div><h2>英语水平</h2><p>新对话会按照该难度调整表达。</p></div><LevelSelect value={level} onChange={(nextLevel) => updateSettings({ level: nextLevel })} /></article><article className="teacher-settings"><div><h2>AI 老师</h2><p>每位老师有固定口音和陪练方式。</p></div><TeacherSelector className="assistant-settings__teachers" selectedId={teacher.id} onSelect={(nextTeacher) => updateSettings({ teacher: nextTeacher })} /></article><article><div><h2>账户与隐私</h2><p>管理密码与账户数据。</p></div><div className="account-actions"><button type="button" onClick={() => setPasswordOpen(true)}><Password />修改密码<CaretRight /></button><button type="button" className="danger"><Trash />删除账户<CaretRight /></button></div></article></section>{passwordOpen && <PasswordChangeModal onClose={() => setPasswordOpen(false)} onSubmit={onPasswordChange} />}</div>;
 }
 
 function Paywall({ title, onClose, onMembership }) {
@@ -2097,6 +2131,7 @@ export function App() {
   const initialRoute = useMemo(() => resolveRoute(window.location), []);
   const [authReady, setAuthReady] = useState(false);
   const [user, setUser] = useState(null);
+  const [profileOverview, setProfileOverview] = useState(null);
   const [flow, setFlow] = useState(initialRoute.flow);
   const [authMode, setAuthMode] = useState(initialRoute.authMode);
   const [level, setLevel] = useState("");
@@ -2183,12 +2218,14 @@ export function App() {
         return;
       }
       try {
-        const [currentUser, preference] = await Promise.all([
+        const [currentUser, preference, profile] = await Promise.all([
           getCurrentUser(),
           getUserPreference(),
+          getProfileOverview(),
         ]);
         if (cancelled) return;
         setUser(currentUser);
+        setProfileOverview(profile);
         applyPreference(preference);
         if (initialRoute.flow === "app" && !preference.cefrLevel) {
           navigate(paths.auth.level, {}, true);
@@ -2217,7 +2254,11 @@ export function App() {
   const enterApp = () => setMainPage("conversation");
   const completeAuthentication = async (auth, mode) => {
     setUser(auth.user);
-    const preference = await getUserPreference();
+    const [preference, profile] = await Promise.all([
+      getUserPreference(),
+      getProfileOverview(),
+    ]);
+    setProfileOverview(profile);
     applyPreference(preference);
     if (mode === "signup" || !preference.cefrLevel) {
       goLevel();
@@ -2285,8 +2326,62 @@ export function App() {
   const logout = () => {
     clearAuthSession();
     setUser(null);
+    setProfileOverview(null);
     goSplash();
   };
+  const updateNickname = async (nickname) => {
+    if (!nickname) {
+      window.alert("用户名不能为空");
+      return false;
+    }
+    try {
+      const updated = await updateProfile({ nickname });
+      setUser((current) => current ? { ...current, nickname: updated.nickname } : current);
+      setProfileOverview((current) => current ? {
+        ...current,
+        account: { ...current.account, nickname: updated.nickname, displayName: updated.displayName },
+      } : current);
+      return true;
+    } catch (error) {
+      window.alert(error instanceof Error ? error.message : "用户名修改失败");
+      return false;
+    }
+  };
+  const loadProfileMonth = async (month) => {
+    try {
+      setProfileOverview(await getProfileOverview(month));
+    } catch (error) {
+      window.alert(error instanceof Error ? error.message : "学习日历加载失败");
+    }
+  };
+  const updateAvatar = async (file) => {
+    if (!["image/jpeg", "image/png"].includes(file.type) || file.size > 2 * 1024 * 1024) {
+      window.alert("请选择不超过 2 MiB 的 JPEG 或 PNG 图片");
+      return false;
+    }
+    try {
+      const updated = await uploadProfileAvatar(file);
+      setProfileOverview((current) => current ? {
+        ...current,
+        account: {
+          ...current.account,
+          avatarUrl: updated.avatarUrl,
+          avatarUrlExpiresAt: updated.avatarUrlExpiresAt,
+        },
+      } : current);
+      return true;
+    } catch (error) {
+      window.alert(error instanceof Error ? error.message : "头像上传失败");
+      return false;
+    }
+  };
+  const updatePassword = async (passwords) => {
+    await changePassword(passwords);
+    clearAuthSession();
+    setUser(null);
+    setProfileOverview(null);
+    navigate(paths.auth.login, { authMode: "login" }, true);
+  };
   const startTraining = (sceneOrTitle, initialStep = "learn", options = {}) => {
     const scene = typeof sceneOrTitle === "object" ? sceneOrTitle : null;
     const title = scene?.title || sceneOrTitle;
@@ -2345,6 +2440,9 @@ export function App() {
       training,
       result: { completed, evaluation },
     });
+    if (evaluation) {
+      void getProfileOverview().then(setProfileOverview).catch(() => undefined);
+    }
   };
   const setMainPage = (next) => navigate(hrefForPage(next), { page: next, authMode, training: null, result: null });
   const navigateIelts = (path) => navigate(path, { authMode });
@@ -2370,6 +2468,6 @@ export function App() {
   else if (page === "ielts-assets") content = <IeltsAssets route={ieltsRoute} onNavigate={navigateIelts} onBackToAssets={() => setMainPage("assets")} onInterviewAssets={() => setMainPage("interview-assets")} onTraining={() => navigateIelts(paths.ielts.root)} />;
   else if (page === "interview") content = <InterviewTrainingCenter route={interviewRoute} onNavigate={navigateInterview} onExit={() => setMainPage("scenes")} onAssets={() => navigateInterview(paths.interview.assets.root)} />;
   else if (page === "interview-assets") content = <InterviewAssets route={interviewRoute} onNavigate={navigateInterview} onBackToAssets={() => setMainPage("assets")} onIeltsAssets={() => setMainPage("ielts-assets")} onTraining={() => navigateInterview(paths.interview.root)} />;
-  else content = <Profile section={page} setSection={setMainPage} user={user} teacher={teacher} speed={conversationSpeed} level={level} onSettingsChange={persistSettings} onLogout={logout} />;
-  return <AppShell page={page} setPage={setMainPage} teacher={teacher}>{content}{paywall && <Paywall title={paywall} onClose={() => setPaywall(null)} onMembership={() => { setPaywall(null); setMainPage("membership"); }} />}</AppShell>;
+  else content = <Profile section={page} setSection={setMainPage} user={user} profile={profileOverview} teacher={teacher} speed={conversationSpeed} level={level} onSettingsChange={persistSettings} onMonthChange={loadProfileMonth} onNicknameChange={updateNickname} onAvatarChange={updateAvatar} onPasswordChange={updatePassword} onLogout={logout} />;
+  return <AppShell page={page} setPage={setMainPage} teacher={teacher} avatarUrl={profileOverview?.account?.avatarUrl}>{content}{paywall && <Paywall title={paywall} onClose={() => setPaywall(null)} onMembership={() => { setPaywall(null); setMainPage("membership"); }} />}</AppShell>;
 }

From b4b4f43a87b2ea70cbbd08284cb80cadf8489db7 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:47:25 +0800
Subject: [PATCH 39/62] style(profile): present account editing controls

---
 frontend/Unispeaking_fronted/src/styles.css | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/frontend/Unispeaking_fronted/src/styles.css b/frontend/Unispeaking_fronted/src/styles.css
index a4d9f15..ab47757 100644
--- a/frontend/Unispeaking_fronted/src/styles.css
+++ b/frontend/Unispeaking_fronted/src/styles.css
@@ -803,7 +803,10 @@ svg { display: block; }
   .assets-page:not(.asset-conversation-page):not(.asset-module-placeholder) .page-header > div > p:last-child { font-size: 17px; }
 }
 
-.profile-layout { min-height: 100%; display: grid; grid-template-columns: 250px 1fr; }.profile-nav { border-right: 1px solid var(--line); padding: 38px 22px 28px; display: flex; flex-direction: column; }.profile-user { display: flex; align-items: center; gap: 12px; padding: 0 10px 32px; }.profile-user img { width: 48px; height: 48px; border-radius: 14px; object-fit: cover; object-position: top; }.profile-user strong, .profile-user small { display: block; }.profile-user small { color: var(--muted); margin-top: 5px; font-size: 10px; }.profile-nav nav { display: grid; gap: 7px; }.profile-nav nav button, .logout { height: 46px; padding: 0 13px; border: 0; border-radius: 10px; background: #fff; display: flex; align-items: center; gap: 10px; cursor: pointer; }.profile-nav nav button.is-active { background: var(--soft-2); font-weight: 650; }.profile-nav nav svg, .logout svg { width: 19px; height: 19px; }.logout { margin-top: auto; color: #555; }.profile-content { padding: 52px clamp(42px, 5vw, 84px) 60px; overflow: auto; }.stat-grid { display: grid; grid-template-columns: repeat(3,1fr); gap: 16px; }.stat-grid article { min-height: 106px; padding: 20px; border: 1px solid var(--line); border-radius: 14px; display: flex; gap: 14px; align-items: center; }.stat-grid article > svg { width: 22px; height: 22px; }.stat-grid small, .stat-grid strong { display: block; }.stat-grid small { color: var(--muted); }.stat-grid strong { font-size: 26px; margin-top: 7px; }.stat-grid em { font-style: normal; font-size: 11px; }
+.profile-layout { min-height: 100%; display: grid; grid-template-columns: 250px 1fr; }.profile-nav { border-right: 1px solid var(--line); padding: 38px 22px 28px; display: flex; flex-direction: column; }.profile-user { display: flex; align-items: center; gap: 12px; padding: 0 10px 12px; }.profile-user img { width: 48px; height: 48px; border-radius: 14px; object-fit: cover; object-position: center; }.profile-user strong, .profile-user small { display: block; }.profile-user small { color: var(--muted); margin-top: 5px; font-size: 10px; }.profile-user-actions { display: flex; gap: 6px; padding: 0 10px 28px; }.profile-user-actions button { padding: 0; border: 0; background: transparent; color: #747470; font-size: 10px; cursor: pointer; }.profile-user-actions button:hover { color: var(--ink); text-decoration: underline; }.profile-user-actions input { display: none; }.profile-nav nav { display: grid; gap: 7px; }.profile-nav nav button, .logout { height: 46px; padding: 0 13px; border: 0; border-radius: 10px; background: #fff; display: flex; align-items: center; gap: 10px; cursor: pointer; }.profile-nav nav button.is-active { background: var(--soft-2); font-weight: 650; }.profile-nav nav svg, .logout svg { width: 19px; height: 19px; }.logout { margin-top: auto; color: #555; }.profile-content { padding: 52px clamp(42px, 5vw, 84px) 60px; overflow: auto; }.stat-grid { display: grid; grid-template-columns: repeat(3,1fr); gap: 16px; }.stat-grid article { min-height: 106px; padding: 20px; border: 1px solid var(--line); border-radius: 14px; display: flex; gap: 14px; align-items: center; }.stat-grid article > svg { width: 22px; height: 22px; }.stat-grid small, .stat-grid strong { display: block; }.stat-grid small { color: var(--muted); }.stat-grid strong { font-size: 26px; margin-top: 7px; }.stat-grid em { font-style: normal; font-size: 11px; }
+.today-checkin, .result-checkin { display: inline-flex; align-items: center; gap: 7px; padding: 8px 12px; border-radius: 999px; background: #20201f; color: #fff; font-size: 12px; font-weight: 700; }
+.today-checkin svg, .result-checkin svg { width: 16px; height: 16px; }
+.result-checkin { margin-top: 13px; }
 .overview-grid { display: grid; grid-template-columns: minmax(0, 1.45fr) minmax(330px, .75fr); gap: 18px; margin-top: 18px; }
 .overview-grid > article { min-height: 440px; border: 1px solid var(--line); border-radius: 18px; padding: 26px; }
 .overview-grid h2 { margin: 7px 0 0; font-size: 24px; letter-spacing: -.03em; }
@@ -908,6 +911,11 @@ svg { display: block; }
 .account-actions button.danger { color: var(--danger); }
 .account-actions svg { width: 19px; height: 19px; }
 .settings-list > article:last-child { padding-block: 24px; }
+.password-form { display: grid; gap: 15px; margin-top: 24px; }
+.password-form label { display: grid; gap: 7px; color: #555551; font-size: 13px; font-weight: 650; }
+.password-form input { height: 46px; padding: 0 13px; border: 1px solid var(--line); border-radius: 10px; font: inherit; }
+.password-form input:focus { outline: 2px solid #242423; outline-offset: 1px; }
+.password-form .form-error { margin: 0; color: var(--danger); font-size: 12px; }
 
 @media (max-width: 1250px) {
   .page { padding-inline: 48px; }

From 90d5cf1df089213e8229476f5925e3ea9a05c56b Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:48:58 +0800
Subject: [PATCH 40/62] docs(api): document profile account endpoints

---
 docs/frontend-backend-interface-contract.md | 76 +++++++++++++++++++++
 1 file changed, 76 insertions(+)

diff --git a/docs/frontend-backend-interface-contract.md b/docs/frontend-backend-interface-contract.md
index c5e7de7..fa4f72d 100644
--- a/docs/frontend-backend-interface-contract.md
+++ b/docs/frontend-backend-interface-contract.md
@@ -2,6 +2,82 @@
 
 本文档用于前端和后端对齐接口。当前后端已实现登录注册、JWT 鉴权、用户偏好、字幕翻译、自由会话开始、WebSocket 追加完整消息和结束；其他未实现接口会单独标记。
 
+## 个人主页与账户安全接口
+
+以下接口均从 JWT 获取当前用户，不接收客户端传入的 `userId`。
+
+### 获取个人主页
+
+```text
+GET /api/profile/overview?month=2026-07
+Authorization: Bearer <accessToken>
+```
+
+`month` 可省略，格式为 `yyyy-MM`，省略时按 `Asia/Shanghai` 返回当前月；未来月份不允许查询。日历的打卡依据是该用户场景下已经持久化的五维评分报告，同一天多份报告只返回一个日期。
+
+```json
+{
+  "account": {
+    "userId": "11111111-1111-4111-8111-111111111111",
+    "email": "name@example.com",
+    "nickname": "Sunny",
+    "displayName": "Sunny",
+    "avatarUrl": "https://signed-oss-url.example/avatar.jpg",
+    "avatarUrlExpiresAt": "2026-07-31T08:00:00Z"
+  },
+  "calendar": {
+    "month": "2026-07",
+    "checkedDates": ["2026-07-02", "2026-07-15"],
+    "checkedInToday": true
+  }
+}
+```
+
+`avatarUrl` 是短期签名地址，未上传头像或对象存储暂不可用时为 `null`。
+
+### 修改用户名（昵称）
+
+```text
+PATCH /api/profile
+Authorization: Bearer <accessToken>
+Content-Type: application/json
+```
+
+```json
+{
+  "nickname": "Sunny"
+}
+```
+
+这里只修改展示昵称，不修改登录邮箱。昵称去除首尾空白后长度必须为 1～80。
+
+### 上传头像
+
+```text
+POST /api/profile/avatar
+Authorization: Bearer <accessToken>
+Content-Type: multipart/form-data
+```
+
+表单字段名为 `avatar`。仅接受 JPEG/PNG，文件不超过 2 MiB，宽高均为 128～4096 像素。后端会解码并重新编码后写入阿里云 OSS，响应包含一小时有效的签名 URL。
+
+### 修改密码
+
+```text
+PUT /api/auth/password
+Authorization: Bearer <accessToken>
+Content-Type: application/json
+```
+
+```json
+{
+  "currentPassword": "old-password",
+  "newPassword": "new-password"
+}
+```
+
+新密码长度为 6～72，且不能与当前密码相同。成功响应中的 `reauthenticationRequired` 为 `true`；服务端同时递增 `auth_version`，使该用户所有现有 JWT（包括当前请求所用 JWT）失效，前端必须清除 Token 并跳转登录页。
+
 ## 1. 基础约定
 
 ### 1.1 Base URL

From b35fc0308a7695a7c9836da1c9d921cc1dc6c68b Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:48:59 +0800
Subject: [PATCH 41/62] docs(deploy): document profile storage rollout

---
 docs/deployment.md | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/docs/deployment.md b/docs/deployment.md
index 04bf57a..07e10b4 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -12,17 +12,42 @@ The repository contains `deploy/env/.env.example`. The working copy also uses
 `deploy/env/.env`, which is ignored by Git.
 
 Set the following variables in `deploy/env/.env` before starting a realtime
-session:
+session or using profile avatars:
 
 ```properties
 DASHSCOPE_API_KEY=replace-with-your-real-key
 BAILIAN_WORKSPACE_ID=replace-with-your-workspace-id
 BAILIAN_MODEL=qwen3.5-omni-flash-realtime
+ALIYUN_OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
+ALIYUN_OSS_BUCKET=replace-with-your-private-bucket
+ALIYUN_OSS_ACCESS_KEY_ID=replace-with-your-access-key-id
+ALIYUN_OSS_ACCESS_KEY_SECRET=replace-with-your-access-key-secret
+ALIYUN_OSS_AVATAR_PREFIX=avatars
+ALIYUN_OSS_SIGNED_URL_TTL=1h
+PROFILE_TIME_ZONE=Asia/Shanghai
 ```
 
 Do not put API keys in a `VITE_` variable because Vite embeds those values in
 browser assets.
 
+The OSS bucket must remain private. The backend stores only the object key in
+PostgreSQL and returns a short-lived signed download URL to the browser. Grant
+the configured RAM identity only the object read/write/delete permissions
+required for the avatar prefix.
+
+## Profile database migration
+
+Before deploying the profile feature to an existing database, apply:
+
+```bash
+psql "$DATABASE_URL" -f deploy/postgres/profile.sql
+```
+
+The migration adds only `user.avatar_object_key`; check-in dates continue to be
+derived from persisted `session_evaluation` reports, so no check-in table and no
+Redis data structure are required. New databases receive the same definition
+from `backend/unispeaking-server/src/main/resources/db/schema.sql`.
+
 ## Available settings
 
 The Spring Boot defaults live in
@@ -41,6 +66,18 @@ realtime:
     connect-timeout: ${REALTIME_QWEN_CONNECT_TIMEOUT:10s}
     read-timeout: ${REALTIME_QWEN_READ_TIMEOUT:20s}
     max-answer-bytes: ${REALTIME_QWEN_MAX_ANSWER_BYTES:1048576}
+
+profile:
+  time-zone: ${PROFILE_TIME_ZONE:Asia/Shanghai}
+
+object-storage:
+  aliyun:
+    endpoint: ${ALIYUN_OSS_ENDPOINT:}
+    bucket: ${ALIYUN_OSS_BUCKET:}
+    access-key-id: ${ALIYUN_OSS_ACCESS_KEY_ID:}
+    access-key-secret: ${ALIYUN_OSS_ACCESS_KEY_SECRET:}
+    avatar-prefix: ${ALIYUN_OSS_AVATAR_PREFIX:avatars}
+    signed-url-ttl: ${ALIYUN_OSS_SIGNED_URL_TTL:1h}
 ```
 
 The WebRTC SDP endpoint is derived automatically:

From 15d0138fad31bc2568864d02fa4a0a2dd0a54ef7 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:50:48 +0800
Subject: [PATCH 42/62] fix(profile): make storage lifecycle explicit

---
 .../infrastructure/storage/ObjectStorageProvider.java       | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/ObjectStorageProvider.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/ObjectStorageProvider.java
index 2f1a6e6..22a81d8 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/ObjectStorageProvider.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/ObjectStorageProvider.java
@@ -3,9 +3,13 @@
 import java.net.URI;
 import java.time.Duration;
 
-public interface ObjectStorageProvider {
+public interface ObjectStorageProvider extends AutoCloseable {
 	void put(String objectKey, byte[] content, String contentType);
 	URI signGetUrl(String objectKey, Duration ttl);
 	void delete(String objectKey);
 	boolean available();
+
+	@Override
+	default void close() {
+	}
 }

From 9277ad6096c987c2018ddc7c6cd58659e9ccffe8 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:50:48 +0800
Subject: [PATCH 43/62] fix(profile): close Aliyun OSS client

---
 .../storage/aliyun/AliyunOssObjectStorageProvider.java       | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java
index bc8b8b4..84dd1ff 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java
@@ -62,6 +62,11 @@ public boolean available() {
 		return true;
 	}
 
+	@Override
+	public void close() {
+		client.shutdown();
+	}
+
 	private BusinessException storageFailure() {
 		return new BusinessException("AVATAR_STORAGE_FAILED", "头像存储服务暂时不可用");
 	}

From 9ff67b62445d20cea3f5d9b45a97176e3af9f43f Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:50:48 +0800
Subject: [PATCH 44/62] fix(profile): register storage cleanup

---
 .../config/ObjectStorageConfig.java           | 19 ++-----------------
 1 file changed, 2 insertions(+), 17 deletions(-)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageConfig.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageConfig.java
index 0ea21e5..2828042 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageConfig.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageConfig.java
@@ -13,7 +13,7 @@
 @Configuration
 public class ObjectStorageConfig {
 
-	@Bean(destroyMethod = "")
+	@Bean(destroyMethod = "close")
 	ObjectStorageProvider objectStorageProvider(ObjectStorageProperties properties) {
 		if (!properties.configured()) {
 			return new UnavailableObjectStorageProvider();
@@ -22,22 +22,7 @@ ObjectStorageProvider objectStorageProvider(ObjectStorageProperties properties)
 				properties.getEndpoint(),
 				properties.getAccessKeyId(),
 				properties.getAccessKeySecret());
-		return new ManagedAliyunProvider(client, properties);
-	}
-
-	private static final class ManagedAliyunProvider
-			extends AliyunOssObjectStorageProvider {
-		private final OSS client;
-
-		private ManagedAliyunProvider(OSS client, ObjectStorageProperties properties) {
-			super(client, properties);
-			this.client = client;
-		}
-
-		@SuppressWarnings("unused")
-		public void shutdown() {
-			client.shutdown();
-		}
+		return new AliyunOssObjectStorageProvider(client, properties);
 	}
 
 	private static final class UnavailableObjectStorageProvider

From 3c365636095a18fc735dcfa47c8405222d42fb77 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:50:48 +0800
Subject: [PATCH 45/62] fix(profile): degrade avatar signing failures

---
 .../profile/impl/ProfileAccountServiceImpl.java  | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileAccountServiceImpl.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileAccountServiceImpl.java
index c8add83..e6aa795 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileAccountServiceImpl.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileAccountServiceImpl.java
@@ -65,11 +65,21 @@ public AvatarResponse replaceAvatar(String userId, byte[] content) {
 			safeDelete(key);
 			throw new BusinessException("PROFILE_UPDATE_CONFLICT", "头像已发生变化，请重试");
 		}
+		URI signed = signAvatar(key);
 		if (user.avatarObjectKey() != null) safeDelete(user.avatarObjectKey());
-		URI signed = storage.signGetUrl(key, properties.getSignedUrlTtl());
 		return new AvatarResponse(
-				signed.toString(),
-				Instant.now().plus(properties.getSignedUrlTtl()));
+				signed == null ? null : signed.toString(),
+				signed == null ? null : Instant.now().plus(properties.getSignedUrlTtl()));
+	}
+
+	private URI signAvatar(String key) {
+		try {
+			return storage.signGetUrl(key, properties.getSignedUrlTtl());
+		}
+		catch (BusinessException exception) {
+			LOGGER.warn("avatar url signing failed");
+			return null;
+		}
 	}
 
 	private void safeDelete(String key) {

From ec1e7154a8fe96fec33ee72137d060f6d57edc9a Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:50:49 +0800
Subject: [PATCH 46/62] fix(profile): enforce avatar image formats

---
 .../profile/image/AvatarImageProcessor.java   | 21 ++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/image/AvatarImageProcessor.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/image/AvatarImageProcessor.java
index 664c18a..a758453 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/image/AvatarImageProcessor.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/image/AvatarImageProcessor.java
@@ -19,7 +19,10 @@ public ProcessedAvatar process(byte[] input) {
 			throw error("AVATAR_FILE_REQUIRED", "请选择头像文件");
 		}
 		if (input.length > MAX_BYTES) {
-			throw error("AVATAR_FILE_TOO_LARGE", "头像不能超过 2 MB");
+			throw error("AVATAR_FILE_TOO_LARGE", "头像不能超过 2 MiB");
+		}
+		if (!hasJpegHeader(input) && !hasPngHeader(input)) {
+			throw error("AVATAR_TYPE_UNSUPPORTED", "仅支持 JPEG 和 PNG 头像");
 		}
 		try {
 			BufferedImage image = ImageIO.read(new ByteArrayInputStream(input));
@@ -45,6 +48,22 @@ public ProcessedAvatar process(byte[] input) {
 		}
 	}
 
+	private boolean hasJpegHeader(byte[] input) {
+		return input.length >= 3
+				&& (input[0] & 0xff) == 0xff
+				&& (input[1] & 0xff) == 0xd8
+				&& (input[2] & 0xff) == 0xff;
+	}
+
+	private boolean hasPngHeader(byte[] input) {
+		byte[] signature = {(byte) 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a};
+		if (input.length < signature.length) return false;
+		for (int index = 0; index < signature.length; index++) {
+			if (input[index] != signature[index]) return false;
+		}
+		return true;
+	}
+
 	private BusinessException error(String code, String message) {
 		return new BusinessException(code, message);
 	}

From 7dce1658b95bbe076c1a91fc207e01e1570b721a Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:52:17 +0800
Subject: [PATCH 47/62] fix(auth): preserve service adapter compatibility

---
 .../main/java/com/unispeaking/service/auth/AuthService.java   | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/auth/AuthService.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/auth/AuthService.java
index 35ed6ae..80f4afb 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/service/auth/AuthService.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/auth/AuthService.java
@@ -11,6 +11,8 @@ public interface AuthService {
 	AuthResponse register(RegisterRequest request);
 	AuthResponse login(LoginRequest request);
 	UserAccountResponse currentUser();
-	ChangePasswordResponse changePassword(ChangePasswordRequest request);
+	default ChangePasswordResponse changePassword(ChangePasswordRequest request) {
+		throw new UnsupportedOperationException("Password change is not supported");
+	}
 	String requireUserId(String requestedUserId);
 }

From 11d2200b3565b6ef076d97a72cc469a7cf876e6b Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Fri, 31 Jul 2026 15:53:54 +0800
Subject: [PATCH 48/62] docs(deploy): align OSS environment names

---
 docs/deployment.md | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/deployment.md b/docs/deployment.md
index 07e10b4..577dbb5 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -18,12 +18,12 @@ session or using profile avatars:
 DASHSCOPE_API_KEY=replace-with-your-real-key
 BAILIAN_WORKSPACE_ID=replace-with-your-workspace-id
 BAILIAN_MODEL=qwen3.5-omni-flash-realtime
-ALIYUN_OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
-ALIYUN_OSS_BUCKET=replace-with-your-private-bucket
-ALIYUN_OSS_ACCESS_KEY_ID=replace-with-your-access-key-id
-ALIYUN_OSS_ACCESS_KEY_SECRET=replace-with-your-access-key-secret
-ALIYUN_OSS_AVATAR_PREFIX=avatars
-ALIYUN_OSS_SIGNED_URL_TTL=1h
+OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
+OSS_BUCKET=replace-with-your-private-bucket
+OSS_ACCESS_KEY_ID=replace-with-your-access-key-id
+OSS_ACCESS_KEY_SECRET=replace-with-your-access-key-secret
+OSS_AVATAR_PREFIX=avatars
+OSS_SIGNED_URL_TTL=1h
 PROFILE_TIME_ZONE=Asia/Shanghai
 ```
 
@@ -72,12 +72,12 @@ profile:
 
 object-storage:
   aliyun:
-    endpoint: ${ALIYUN_OSS_ENDPOINT:}
-    bucket: ${ALIYUN_OSS_BUCKET:}
-    access-key-id: ${ALIYUN_OSS_ACCESS_KEY_ID:}
-    access-key-secret: ${ALIYUN_OSS_ACCESS_KEY_SECRET:}
-    avatar-prefix: ${ALIYUN_OSS_AVATAR_PREFIX:avatars}
-    signed-url-ttl: ${ALIYUN_OSS_SIGNED_URL_TTL:1h}
+    endpoint: ${OSS_ENDPOINT:}
+    bucket: ${OSS_BUCKET:}
+    access-key-id: ${OSS_ACCESS_KEY_ID:}
+    access-key-secret: ${OSS_ACCESS_KEY_SECRET:}
+    avatar-prefix: ${OSS_AVATAR_PREFIX:avatars}
+    signed-url-ttl: ${OSS_SIGNED_URL_TTL:1h}
 ```
 
 The WebRTC SDP endpoint is derived automatically:

From b3f7ea646f314d0a51faf998b6d2bc9f9829d571 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Mon, 3 Aug 2026 13:34:41 +0800
Subject: [PATCH 49/62] =?UTF-8?q?=E5=8A=9F=E8=83=BD=EF=BC=9A=E5=B0=86?=
 =?UTF-8?q?=E4=B8=AA=E4=BA=BA=E8=B5=84=E6=96=99=E4=BF=AE=E6=94=B9=E6=95=B4?=
 =?UTF-8?q?=E5=90=88=E5=88=B0=E7=BC=96=E8=BE=91=E5=BC=B9=E7=AA=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend/Unispeaking_fronted/src/App.jsx    | 75 +++++++++++++++++----
 frontend/Unispeaking_fronted/src/styles.css | 15 ++++-
 2 files changed, 77 insertions(+), 13 deletions(-)

diff --git a/frontend/Unispeaking_fronted/src/App.jsx b/frontend/Unispeaking_fronted/src/App.jsx
index 1d8783b..847d903 100644
--- a/frontend/Unispeaking_fronted/src/App.jsx
+++ b/frontend/Unispeaking_fronted/src/App.jsx
@@ -25,6 +25,7 @@ import {
   PaperPlaneTilt,
   Pause,
   Password,
+  PencilSimple,
   PhoneDisconnect,
   Play,
   Plus,
@@ -2063,24 +2064,74 @@ function Assets({ sceneId, onPractice, onRestart, onIelts, onInterview, onOpenRe
   );
 }
 
+function ProfileEditModal({ account, user, avatarUrl, onClose, onNicknameChange, onAvatarChange }) {
+  const currentNickname = account?.nickname || user?.nickname || "";
+  const [nickname, setNickname] = useState(currentNickname);
+  const [avatar, setAvatar] = useState(null);
+  const [previewUrl, setPreviewUrl] = useState(avatarUrl);
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    if (!avatar) {
+      setPreviewUrl(avatarUrl);
+      return undefined;
+    }
+    const objectUrl = URL.createObjectURL(avatar);
+    setPreviewUrl(objectUrl);
+    return () => URL.revokeObjectURL(objectUrl);
+  }, [avatar, avatarUrl]);
+
+  const selectAvatar = (event) => {
+    const file = event.target.files?.[0] || null;
+    event.target.value = "";
+    if (!file) return;
+    if (!["image/jpeg", "image/png"].includes(file.type) || file.size > 2 * 1024 * 1024) {
+      setError("请选择不超过 2 MiB 的 JPEG 或 PNG 图片");
+      return;
+    }
+    setError("");
+    setAvatar(file);
+  };
+
+  const submit = async (event) => {
+    event.preventDefault();
+    const normalizedNickname = nickname.trim();
+    if (!normalizedNickname) {
+      setError("用户名不能为空");
+      return;
+    }
+    const nicknameChanged = normalizedNickname !== currentNickname;
+    if (!nicknameChanged && !avatar) {
+      onClose();
+      return;
+    }
+    setSubmitting(true);
+    setError("");
+    if (nicknameChanged && !(await onNicknameChange(normalizedNickname))) {
+      setError("用户名修改失败，请稍后重试");
+      setSubmitting(false);
+      return;
+    }
+    if (avatar && !(await onAvatarChange(avatar))) {
+      setError("头像修改失败，请稍后重试");
+      setSubmitting(false);
+      return;
+    }
+    onClose();
+  };
+
+  return <Modal onClose={submitting ? undefined : onClose} className="profile-edit-modal"><p className="eyebrow">EDIT PROFILE</p><h2>编辑个人资料</h2><p className="modal-lead">修改你的展示用户名或个人头像。</p><form className="profile-edit-form" onSubmit={submit}><div className="profile-edit-avatar"><img src={previewUrl} alt="头像预览" /><div><strong>个人头像</strong><small>支持 JPEG、PNG，文件不超过 2 MiB</small><label className="profile-avatar-picker">选择新头像<input type="file" accept="image/jpeg,image/png" disabled={submitting} onChange={selectAvatar} /></label></div></div><label className="profile-edit-name">用户名<input type="text" minLength={1} maxLength={80} required disabled={submitting} value={nickname} onChange={(event) => setNickname(event.target.value)} /></label>{error && <p className="form-error" role="alert">{error}</p>}<div className="modal-actions"><Button type="button" variant="secondary" disabled={submitting} onClick={onClose}>取消</Button><Button type="submit" disabled={submitting}>{submitting ? "正在保存" : "保存修改"}</Button></div></form></Modal>;
+}
+
 function Profile({ section, setSection, user, profile, teacher, speed, level, onSettingsChange, onMonthChange, onNicknameChange, onAvatarChange, onPasswordChange, onLogout }) {
   const account = profile?.account;
   const displayName = account?.displayName || user?.nickname || user?.username?.split("@")[0] || "UniSpeaking User";
   const email = account?.email || user?.username || "";
   const avatarUrl = account?.avatarUrl || teacher.image;
-  const avatarInputRef = useRef(null);
-  const editNickname = async () => {
-    const nickname = window.prompt("请输入新的用户名（昵称）", account?.nickname || user?.nickname || "");
-    if (nickname === null) return;
-    await onNicknameChange(nickname.trim());
-  };
-  const selectAvatar = async (event) => {
-    const file = event.target.files?.[0];
-    event.target.value = "";
-    if (file) await onAvatarChange(file);
-  };
+  const [profileEditOpen, setProfileEditOpen] = useState(false);
   return (
-    <main className="profile-layout"><aside className="profile-nav"><div className="profile-user"><img src={avatarUrl} alt={displayName} /><span><strong>{displayName}</strong><small>{email}</small></span></div><div className="profile-user-actions"><button type="button" onClick={editNickname}>修改用户名</button><button type="button" onClick={() => avatarInputRef.current?.click()}>更换头像</button><input ref={avatarInputRef} type="file" accept="image/jpeg,image/png" onChange={selectAvatar} /></div><nav><button className={section === "profile" ? "is-active" : ""} onClick={() => setSection("profile")}><User />个人概览</button><button className={section === "membership" ? "is-active" : ""} onClick={() => setSection("membership")}><Crown />会员权益</button><button className={section === "settings" ? "is-active" : ""} onClick={() => setSection("settings")}><SlidersHorizontal />助手设置</button></nav><button className="logout" onClick={onLogout}><SignOut />退出登录</button></aside><section className="profile-content">{section === "profile" && <Overview calendar={profile?.calendar} onMonthChange={onMonthChange} />}{section === "membership" && <Membership />}{section === "settings" && <Settings teacher={teacher} speed={speed} level={level} onSettingsChange={onSettingsChange} onPasswordChange={onPasswordChange} />}</section></main>
+    <main className="profile-layout"><aside className="profile-nav"><div className="profile-user"><img src={avatarUrl} alt={displayName} /><span><strong>{displayName}</strong><small>{email}</small></span><button type="button" className="profile-user__edit" onClick={() => setProfileEditOpen(true)}><PencilSimple />编辑</button></div><nav><button className={section === "profile" ? "is-active" : ""} onClick={() => setSection("profile")}><User />个人概览</button><button className={section === "membership" ? "is-active" : ""} onClick={() => setSection("membership")}><Crown />会员权益</button><button className={section === "settings" ? "is-active" : ""} onClick={() => setSection("settings")}><SlidersHorizontal />助手设置</button></nav><button className="logout" onClick={onLogout}><SignOut />退出登录</button></aside><section className="profile-content">{section === "profile" && <Overview calendar={profile?.calendar} onMonthChange={onMonthChange} />}{section === "membership" && <Membership />}{section === "settings" && <Settings teacher={teacher} speed={speed} level={level} onSettingsChange={onSettingsChange} onPasswordChange={onPasswordChange} />}</section>{profileEditOpen && <ProfileEditModal account={account} user={user} avatarUrl={avatarUrl} onClose={() => setProfileEditOpen(false)} onNicknameChange={onNicknameChange} onAvatarChange={onAvatarChange} />}</main>
   );
 }
 
diff --git a/frontend/Unispeaking_fronted/src/styles.css b/frontend/Unispeaking_fronted/src/styles.css
index b471b8d..d9cdb70 100644
--- a/frontend/Unispeaking_fronted/src/styles.css
+++ b/frontend/Unispeaking_fronted/src/styles.css
@@ -810,7 +810,7 @@ svg { display: block; }
   .assets-page:not(.asset-conversation-page):not(.asset-module-placeholder) .page-header > div > p:last-child { font-size: 17px; }
 }
 
-.profile-layout { min-height: 100%; display: grid; grid-template-columns: 250px 1fr; }.profile-nav { border-right: 1px solid var(--line); padding: 38px 22px 28px; display: flex; flex-direction: column; }.profile-user { display: flex; align-items: center; gap: 12px; padding: 0 10px 12px; }.profile-user img { width: 48px; height: 48px; border-radius: 14px; object-fit: cover; object-position: center; }.profile-user strong, .profile-user small { display: block; }.profile-user small { color: var(--muted); margin-top: 5px; font-size: 10px; }.profile-user-actions { display: flex; gap: 6px; padding: 0 10px 28px; }.profile-user-actions button { padding: 0; border: 0; background: transparent; color: #747470; font-size: 10px; cursor: pointer; }.profile-user-actions button:hover { color: var(--ink); text-decoration: underline; }.profile-user-actions input { display: none; }.profile-nav nav { display: grid; gap: 7px; }.profile-nav nav button, .logout { height: 46px; padding: 0 13px; border: 0; border-radius: 10px; background: #fff; display: flex; align-items: center; gap: 10px; cursor: pointer; }.profile-nav nav button.is-active { background: var(--soft-2); font-weight: 650; }.profile-nav nav svg, .logout svg { width: 19px; height: 19px; }.logout { margin-top: auto; color: #555; }.profile-content { padding: 52px clamp(42px, 5vw, 84px) 60px; overflow: auto; }.stat-grid { display: grid; grid-template-columns: repeat(3,1fr); gap: 16px; }.stat-grid article { min-height: 106px; padding: 20px; border: 1px solid var(--line); border-radius: 14px; display: flex; gap: 14px; align-items: center; }.stat-grid article > svg { width: 22px; height: 22px; }.stat-grid small, .stat-grid strong { display: block; }.stat-grid small { color: var(--muted); }.stat-grid strong { font-size: 26px; margin-top: 7px; }.stat-grid em { font-style: normal; font-size: 11px; }
+.profile-layout { min-height: 100%; display: grid; grid-template-columns: 250px 1fr; }.profile-nav { border-right: 1px solid var(--line); padding: 38px 22px 28px; display: flex; flex-direction: column; }.profile-user { display: flex; align-items: center; gap: 12px; padding: 0 6px 32px 10px; }.profile-user > img { flex: 0 0 auto; width: 48px; height: 48px; border-radius: 14px; object-fit: cover; object-position: center; }.profile-user > span { min-width: 0; flex: 1; }.profile-user strong, .profile-user small { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }.profile-user small { color: var(--muted); margin-top: 5px; font-size: 10px; }.profile-user__edit { flex: 0 0 auto; display: inline-flex; align-items: center; gap: 3px; padding: 6px; border: 0; border-radius: 8px; background: transparent; color: #777772; font-size: 10px; cursor: pointer; }.profile-user__edit:hover { background: var(--soft-2); color: var(--ink); }.profile-user__edit svg { width: 13px; height: 13px; }.profile-nav nav { display: grid; gap: 7px; }.profile-nav nav button, .logout { height: 46px; padding: 0 13px; border: 0; border-radius: 10px; background: #fff; display: flex; align-items: center; gap: 10px; cursor: pointer; }.profile-nav nav button.is-active { background: var(--soft-2); font-weight: 650; }.profile-nav nav svg, .logout svg { width: 19px; height: 19px; }.logout { margin-top: auto; color: #555; }.profile-content { padding: 52px clamp(42px, 5vw, 84px) 60px; overflow: auto; }.stat-grid { display: grid; grid-template-columns: repeat(3,1fr); gap: 16px; }.stat-grid article { min-height: 106px; padding: 20px; border: 1px solid var(--line); border-radius: 14px; display: flex; gap: 14px; align-items: center; }.stat-grid article > svg { width: 22px; height: 22px; }.stat-grid small, .stat-grid strong { display: block; }.stat-grid small { color: var(--muted); }.stat-grid strong { font-size: 26px; margin-top: 7px; }.stat-grid em { font-style: normal; font-size: 11px; }
 .today-checkin, .result-checkin { display: inline-flex; align-items: center; gap: 7px; padding: 8px 12px; border-radius: 999px; background: #20201f; color: #fff; font-size: 12px; font-weight: 700; }
 .today-checkin svg, .result-checkin svg { width: 16px; height: 16px; }
 .result-checkin { margin-top: 13px; }
@@ -923,6 +923,19 @@ svg { display: block; }
 .password-form input { height: 46px; padding: 0 13px; border: 1px solid var(--line); border-radius: 10px; font: inherit; }
 .password-form input:focus { outline: 2px solid #242423; outline-offset: 1px; }
 .password-form .form-error { margin: 0; color: var(--danger); font-size: 12px; }
+.profile-edit-form { display: grid; gap: 22px; margin-top: 24px; }
+.profile-edit-avatar { display: grid; grid-template-columns: 78px minmax(0, 1fr); gap: 17px; align-items: center; padding: 17px; border: 1px solid var(--line); border-radius: 14px; background: #fafaf8; }
+.profile-edit-avatar > img { width: 78px; height: 78px; border-radius: 18px; object-fit: cover; object-position: center; background: var(--soft); }
+.profile-edit-avatar strong, .profile-edit-avatar small { display: block; }
+.profile-edit-avatar strong { font-size: 15px; }
+.profile-edit-avatar small { margin-top: 6px; color: var(--muted); font-size: 11px; }
+.profile-avatar-picker { width: fit-content; display: inline-flex; align-items: center; min-height: 34px; margin-top: 12px; padding: 0 13px; border: 1px solid #d3d3ce; border-radius: 999px; background: #fff; color: #444440; font-size: 11px; font-weight: 700; cursor: pointer; }
+.profile-avatar-picker:hover { border-color: #979792; color: var(--ink); }
+.profile-avatar-picker input { display: none; }
+.profile-edit-name { display: grid; gap: 8px; color: #555551; font-size: 13px; font-weight: 650; }
+.profile-edit-name input { height: 46px; padding: 0 13px; border: 1px solid var(--line); border-radius: 10px; font: inherit; }
+.profile-edit-name input:focus { outline: 2px solid #242423; outline-offset: 1px; }
+.profile-edit-form .form-error { margin: 0; color: var(--danger); font-size: 12px; }
 
 @media (max-width: 1250px) {
   .page { padding-inline: 48px; }

From 39573b342ed5e9dd697bf97f54c9e73962a4e935 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Mon, 3 Aug 2026 13:40:34 +0800
Subject: [PATCH 50/62] =?UTF-8?q?=E9=87=8D=E6=9E=84=EF=BC=9A=E5=B0=86?=
 =?UTF-8?q?=E5=A4=B4=E5=83=8F=E5=AF=B9=E8=B1=A1=E5=AD=98=E5=82=A8=E5=88=87?=
 =?UTF-8?q?=E6=8D=A2=E4=B8=BA=E4=B8=83=E7=89=9B=E4=BA=91?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 backend/unispeaking-server/pom.xml            |   8 +-
 .../config/ObjectStorageConfig.java           |  24 ++--
 .../config/ObjectStorageProperties.java       |  24 ++--
 .../AliyunOssObjectStorageProvider.java       |  73 ----------
 .../qiniu/QiniuObjectStorageProvider.java     | 125 ++++++++++++++++++
 .../src/main/resources/application.yaml       |  14 +-
 .../qiniu/QiniuObjectStorageProviderTest.java | 102 ++++++++++++++
 deploy/env/.env.example                       |  14 +-
 8 files changed, 272 insertions(+), 112 deletions(-)
 delete mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/qiniu/QiniuObjectStorageProvider.java
 create mode 100644 backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/storage/qiniu/QiniuObjectStorageProviderTest.java

diff --git a/backend/unispeaking-server/pom.xml b/backend/unispeaking-server/pom.xml
index 19b0a88..2131b88 100644
--- a/backend/unispeaking-server/pom.xml
+++ b/backend/unispeaking-server/pom.xml
@@ -30,7 +30,7 @@
 	<properties>
 		<java.version>21</java.version>
 		<mybatis-plus.version>3.5.17</mybatis-plus.version>
-		<aliyun-oss.version>3.18.5</aliyun-oss.version>
+		<qiniu-java-sdk.version>7.19.0</qiniu-java-sdk.version>
 		<jacoco.version>0.8.13</jacoco.version>
 		<testcontainers.version>2.0.5</testcontainers.version>
 		<skipUnitTests>false</skipUnitTests>
@@ -75,9 +75,9 @@
 				<scope>runtime</scope>
 			</dependency>
 			<dependency>
-				<groupId>com.aliyun.oss</groupId>
-				<artifactId>aliyun-sdk-oss</artifactId>
-				<version>${aliyun-oss.version}</version>
+				<groupId>com.qiniu</groupId>
+				<artifactId>qiniu-java-sdk</artifactId>
+				<version>${qiniu-java-sdk.version}</version>
 			</dependency>
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageConfig.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageConfig.java
index 2828042..a91377a 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageConfig.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageConfig.java
@@ -1,10 +1,11 @@
 package com.unispeaking.infrastructure.config;
 
-import com.aliyun.oss.OSS;
-import com.aliyun.oss.OSSClientBuilder;
+import com.qiniu.storage.BucketManager;
+import com.qiniu.storage.UploadManager;
+import com.qiniu.util.Auth;
 import com.unispeaking.common.exception.BusinessException;
 import com.unispeaking.infrastructure.storage.ObjectStorageProvider;
-import com.unispeaking.infrastructure.storage.aliyun.AliyunOssObjectStorageProvider;
+import com.unispeaking.infrastructure.storage.qiniu.QiniuObjectStorageProvider;
 import java.net.URI;
 import java.time.Duration;
 import org.springframework.context.annotation.Bean;
@@ -13,16 +14,21 @@
 @Configuration
 public class ObjectStorageConfig {
 
-	@Bean(destroyMethod = "close")
+	@Bean
 	ObjectStorageProvider objectStorageProvider(ObjectStorageProperties properties) {
 		if (!properties.configured()) {
 			return new UnavailableObjectStorageProvider();
 		}
-		OSS client = new OSSClientBuilder().build(
-				properties.getEndpoint(),
-				properties.getAccessKeyId(),
-				properties.getAccessKeySecret());
-		return new AliyunOssObjectStorageProvider(client, properties);
+		com.qiniu.storage.Configuration configuration =
+				com.qiniu.storage.Configuration.create();
+		Auth auth = Auth.create(
+				properties.getAccessKey(),
+				properties.getSecretKey());
+		return new QiniuObjectStorageProvider(
+				auth,
+				new UploadManager(configuration),
+				new BucketManager(auth, configuration),
+				properties);
 	}
 
 	private static final class UnavailableObjectStorageProvider
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageProperties.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageProperties.java
index 6854e79..ce89780 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageProperties.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/config/ObjectStorageProperties.java
@@ -3,27 +3,27 @@
 import java.time.Duration;
 import org.springframework.boot.context.properties.ConfigurationProperties;
 
-@ConfigurationProperties("object-storage.aliyun")
+@ConfigurationProperties("object-storage.qiniu")
 public class ObjectStorageProperties {
-	private String endpoint = "";
 	private String bucket = "";
-	private String accessKeyId = "";
-	private String accessKeySecret = "";
+	private String accessKey = "";
+	private String secretKey = "";
+	private String domain = "";
 	private String avatarPrefix = "avatars";
 	private Duration signedUrlTtl = Duration.ofHours(1);
 
 	public boolean configured() {
-		return !endpoint.isBlank() && !bucket.isBlank()
-				&& !accessKeyId.isBlank() && !accessKeySecret.isBlank();
+		return !bucket.isBlank() && !accessKey.isBlank()
+				&& !secretKey.isBlank() && !domain.isBlank();
 	}
-	public String getEndpoint() { return endpoint; }
-	public void setEndpoint(String value) { endpoint = value == null ? "" : value.trim(); }
 	public String getBucket() { return bucket; }
 	public void setBucket(String value) { bucket = value == null ? "" : value.trim(); }
-	public String getAccessKeyId() { return accessKeyId; }
-	public void setAccessKeyId(String value) { accessKeyId = value == null ? "" : value.trim(); }
-	public String getAccessKeySecret() { return accessKeySecret; }
-	public void setAccessKeySecret(String value) { accessKeySecret = value == null ? "" : value.trim(); }
+	public String getAccessKey() { return accessKey; }
+	public void setAccessKey(String value) { accessKey = value == null ? "" : value.trim(); }
+	public String getSecretKey() { return secretKey; }
+	public void setSecretKey(String value) { secretKey = value == null ? "" : value.trim(); }
+	public String getDomain() { return domain; }
+	public void setDomain(String value) { domain = value == null ? "" : value.trim(); }
 	public String getAvatarPrefix() { return avatarPrefix; }
 	public void setAvatarPrefix(String value) { avatarPrefix = value == null ? "avatars" : value.trim(); }
 	public Duration getSignedUrlTtl() { return signedUrlTtl; }
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java
deleted file mode 100644
index 84dd1ff..0000000
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java
+++ /dev/null
@@ -1,73 +0,0 @@
-package com.unispeaking.infrastructure.storage.aliyun;
-
-import com.aliyun.oss.OSS;
-import com.aliyun.oss.model.ObjectMetadata;
-import com.unispeaking.common.exception.BusinessException;
-import com.unispeaking.infrastructure.config.ObjectStorageProperties;
-import com.unispeaking.infrastructure.storage.ObjectStorageProvider;
-import java.io.ByteArrayInputStream;
-import java.net.URI;
-import java.time.Duration;
-import java.time.Instant;
-import java.util.Date;
-
-public class AliyunOssObjectStorageProvider implements ObjectStorageProvider {
-	private final OSS client;
-	private final ObjectStorageProperties properties;
-
-	public AliyunOssObjectStorageProvider(OSS client, ObjectStorageProperties properties) {
-		this.client = client;
-		this.properties = properties;
-	}
-
-	@Override
-	public void put(String objectKey, byte[] content, String contentType) {
-		try {
-			ObjectMetadata metadata = new ObjectMetadata();
-			metadata.setContentLength(content.length);
-			metadata.setContentType(contentType);
-			client.putObject(properties.getBucket(), objectKey,
-					new ByteArrayInputStream(content), metadata);
-		}
-		catch (RuntimeException exception) {
-			throw storageFailure();
-		}
-	}
-
-	@Override
-	public URI signGetUrl(String objectKey, Duration ttl) {
-		try {
-			return client.generatePresignedUrl(
-					properties.getBucket(),
-					objectKey,
-					Date.from(Instant.now().plus(ttl))).toURI();
-		}
-		catch (Exception exception) {
-			throw storageFailure();
-		}
-	}
-
-	@Override
-	public void delete(String objectKey) {
-		try {
-			client.deleteObject(properties.getBucket(), objectKey);
-		}
-		catch (RuntimeException exception) {
-			throw storageFailure();
-		}
-	}
-
-	@Override
-	public boolean available() {
-		return true;
-	}
-
-	@Override
-	public void close() {
-		client.shutdown();
-	}
-
-	private BusinessException storageFailure() {
-		return new BusinessException("AVATAR_STORAGE_FAILED", "头像存储服务暂时不可用");
-	}
-}
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/qiniu/QiniuObjectStorageProvider.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/qiniu/QiniuObjectStorageProvider.java
new file mode 100644
index 0000000..d4eb9f0
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/storage/qiniu/QiniuObjectStorageProvider.java
@@ -0,0 +1,125 @@
+package com.unispeaking.infrastructure.storage.qiniu;
+
+import com.qiniu.common.QiniuException;
+import com.qiniu.http.Response;
+import com.qiniu.storage.BucketManager;
+import com.qiniu.storage.DownloadUrl;
+import com.qiniu.storage.UploadManager;
+import com.qiniu.util.Auth;
+import com.unispeaking.common.exception.BusinessException;
+import com.unispeaking.infrastructure.config.ObjectStorageProperties;
+import com.unispeaking.infrastructure.storage.ObjectStorageProvider;
+import java.net.URI;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.Objects;
+
+public class QiniuObjectStorageProvider implements ObjectStorageProvider {
+	private final Auth auth;
+	private final UploadManager uploadManager;
+	private final BucketManager bucketManager;
+	private final ObjectStorageProperties properties;
+	private final String downloadDomain;
+
+	public QiniuObjectStorageProvider(
+			Auth auth,
+			UploadManager uploadManager,
+			BucketManager bucketManager,
+			ObjectStorageProperties properties) {
+		this.auth = Objects.requireNonNull(auth, "Qiniu auth is required");
+		this.uploadManager = Objects.requireNonNull(
+				uploadManager, "Qiniu upload manager is required");
+		this.bucketManager = Objects.requireNonNull(
+				bucketManager, "Qiniu bucket manager is required");
+		this.properties = Objects.requireNonNull(
+				properties, "Qiniu storage properties are required");
+		this.downloadDomain = requireHttpsDomain(properties.getDomain());
+	}
+
+	@Override
+	public void put(String objectKey, byte[] content, String contentType) {
+		Response response = null;
+		try {
+			response = uploadManager.put(
+				content,
+				objectKey,
+				auth.uploadToken(properties.getBucket(), objectKey),
+				null,
+				contentType,
+				false);
+		}
+		catch (QiniuException exception) {
+			throw storageFailure();
+		}
+		finally {
+			if (response != null) {
+				response.close();
+			}
+		}
+	}
+
+	@Override
+	public URI signGetUrl(String objectKey, Duration ttl) {
+		if (ttl == null || ttl.isZero() || ttl.isNegative()) {
+			throw storageFailure();
+		}
+		try {
+			long deadline = Instant.now().plus(ttl).getEpochSecond();
+			String url = new DownloadUrl(downloadDomain, true, objectKey)
+					.buildURL(auth, deadline);
+			return URI.create(url);
+		}
+		catch (QiniuException | IllegalArgumentException exception) {
+			throw storageFailure();
+		}
+	}
+
+	@Override
+	public void delete(String objectKey) {
+		try {
+			bucketManager.delete(properties.getBucket(), objectKey);
+		}
+		catch (QiniuException exception) {
+			throw storageFailure();
+		}
+	}
+
+	@Override
+	public boolean available() {
+		return true;
+	}
+
+	private String requireHttpsDomain(String value) {
+		String configured = value == null ? "" : value.trim();
+		URI uri;
+		try {
+			uri = URI.create(configured.contains("://")
+					? configured
+					: "https://" + configured);
+		}
+		catch (IllegalArgumentException exception) {
+			throw new IllegalArgumentException(
+					"Qiniu download domain is invalid", exception);
+		}
+		if (!"https".equalsIgnoreCase(uri.getScheme())
+				|| uri.getHost() == null
+				|| uri.getUserInfo() != null
+				|| uri.getQuery() != null
+				|| uri.getFragment() != null
+				|| (uri.getPath() != null
+						&& !uri.getPath().isBlank()
+						&& !"/".equals(uri.getPath()))) {
+			throw new IllegalArgumentException(
+					"Qiniu download domain must be an HTTPS host");
+		}
+		return uri.getPort() < 0
+				? uri.getHost()
+				: uri.getHost() + ":" + uri.getPort();
+	}
+
+	private BusinessException storageFailure() {
+		return new BusinessException(
+				"AVATAR_STORAGE_FAILED",
+				"头像存储服务暂时不可用");
+	}
+}
diff --git a/backend/unispeaking-server/src/main/resources/application.yaml b/backend/unispeaking-server/src/main/resources/application.yaml
index 2200e16..c7ce611 100644
--- a/backend/unispeaking-server/src/main/resources/application.yaml
+++ b/backend/unispeaking-server/src/main/resources/application.yaml
@@ -29,13 +29,13 @@ profile:
   time-zone: ${PROFILE_TIME_ZONE:Asia/Shanghai}
 
 object-storage:
-  aliyun:
-    endpoint: ${OSS_ENDPOINT:}
-    bucket: ${OSS_BUCKET:}
-    access-key-id: ${OSS_ACCESS_KEY_ID:}
-    access-key-secret: ${OSS_ACCESS_KEY_SECRET:}
-    avatar-prefix: ${OSS_AVATAR_PREFIX:avatars}
-    signed-url-ttl: ${OSS_SIGNED_URL_TTL:1h}
+  qiniu:
+    access-key: ${QINIU_ACCESS_KEY:}
+    secret-key: ${QINIU_SECRET_KEY:}
+    bucket: ${QINIU_BUCKET:}
+    domain: ${QINIU_DOMAIN:}
+    avatar-prefix: ${QINIU_AVATAR_PREFIX:avatars}
+    signed-url-ttl: ${QINIU_SIGNED_URL_TTL:1h}
 
 prompt:
   templates:
diff --git a/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/storage/qiniu/QiniuObjectStorageProviderTest.java b/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/storage/qiniu/QiniuObjectStorageProviderTest.java
new file mode 100644
index 0000000..81097fd
--- /dev/null
+++ b/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/storage/qiniu/QiniuObjectStorageProviderTest.java
@@ -0,0 +1,102 @@
+package com.unispeaking.infrastructure.storage.qiniu;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import com.qiniu.http.Response;
+import com.qiniu.storage.BucketManager;
+import com.qiniu.storage.UploadManager;
+import com.qiniu.util.Auth;
+import com.unispeaking.infrastructure.config.ObjectStorageProperties;
+import java.net.URI;
+import java.time.Duration;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+class QiniuObjectStorageProviderTest {
+
+	private static final String BUCKET = "profile-bucket";
+	private static final String OBJECT_KEY = "avatars/user/avatar.png";
+	private UploadManager uploadManager;
+	private BucketManager bucketManager;
+	private QiniuObjectStorageProvider provider;
+
+	@BeforeEach
+	void setUp() {
+		ObjectStorageProperties properties = new ObjectStorageProperties();
+		properties.setAccessKey("test-access-key");
+		properties.setSecretKey("test-secret-key");
+		properties.setBucket(BUCKET);
+		properties.setDomain("https://profile.example.com");
+		uploadManager = mock(UploadManager.class);
+		bucketManager = mock(BucketManager.class);
+		provider = new QiniuObjectStorageProvider(
+				Auth.create("test-access-key", "test-secret-key"),
+				uploadManager,
+				bucketManager,
+				properties);
+	}
+
+	@Test
+	void uploadsWithAKeyScopedTokenAndClosesTheResponse() throws Exception {
+		byte[] content = new byte[] {1, 2, 3};
+		Response response = mock(Response.class);
+		when(uploadManager.put(
+				eq(content),
+				eq(OBJECT_KEY),
+				anyString(),
+				isNull(),
+				eq("image/png"),
+				eq(false))).thenReturn(response);
+
+		provider.put(OBJECT_KEY, content, "image/png");
+
+		verify(uploadManager).put(
+				eq(content),
+				eq(OBJECT_KEY),
+				anyString(),
+				isNull(),
+				eq("image/png"),
+				eq(false));
+		verify(response).close();
+	}
+
+	@Test
+	void createsAnHttpsPrivateDownloadUrl() {
+		URI result = provider.signGetUrl(OBJECT_KEY, Duration.ofMinutes(5));
+
+		assertEquals("https", result.getScheme());
+		assertEquals("profile.example.com", result.getHost());
+		assertEquals("/" + OBJECT_KEY, result.getPath());
+		assertTrue(result.getQuery().contains("e="));
+		assertTrue(result.getQuery().contains("token=test-access-key:"));
+	}
+
+	@Test
+	void deletesFromTheConfiguredBucket() throws Exception {
+		provider.delete(OBJECT_KEY);
+
+		verify(bucketManager).delete(BUCKET, OBJECT_KEY);
+	}
+
+	@Test
+	void rejectsAnInsecureDownloadDomain() {
+		ObjectStorageProperties properties = new ObjectStorageProperties();
+		properties.setDomain("http://profile.example.com");
+
+		assertThrows(
+				IllegalArgumentException.class,
+				() -> new QiniuObjectStorageProvider(
+						Auth.create("access-key", "secret-key"),
+						uploadManager,
+						bucketManager,
+						properties));
+	}
+}
diff --git a/deploy/env/.env.example b/deploy/env/.env.example
index 08c1d60..89da391 100644
--- a/deploy/env/.env.example
+++ b/deploy/env/.env.example
@@ -23,15 +23,15 @@ JWT_ISSUER=unispeaking
 JWT_ACCESS_TOKEN_TTL=2h
 
 # =============================================================================
-# Profile and Alibaba Cloud OSS
+# Profile and Qiniu Kodo
 # =============================================================================
 PROFILE_TIME_ZONE=Asia/Shanghai
-OSS_ENDPOINT=
-OSS_BUCKET=
-OSS_ACCESS_KEY_ID=
-OSS_ACCESS_KEY_SECRET=
-OSS_AVATAR_PREFIX=avatars
-OSS_SIGNED_URL_TTL=1h
+QINIU_ACCESS_KEY=
+QINIU_SECRET_KEY=
+QINIU_BUCKET=
+QINIU_DOMAIN=
+QINIU_AVATAR_PREFIX=avatars
+QINIU_SIGNED_URL_TTL=1h
 
 # =============================================================================
 # AI model routes

From 4ab8b287994a9bf7098c815978c91650053a0d6c Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Mon, 3 Aug 2026 13:44:11 +0800
Subject: [PATCH 51/62] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E6=9B=B4?=
 =?UTF-8?q?=E6=96=B0=E4=B8=83=E7=89=9B=E4=BA=91=E5=A4=B4=E5=83=8F=E5=AD=98?=
 =?UTF-8?q?=E5=82=A8=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CLAUDE.md                                     |   2 +-
 docs/deployment.md                            |  35 ++---
 docs/frontend-backend-interface-contract.md   |   2 +-
 ...36\346\226\275\350\256\241\345\210\222.md" |  37 ++---
 ...00\345\217\221\350\256\276\350\256\241.md" | 132 +++++++++---------
 5 files changed, 106 insertions(+), 102 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 62230e7..a4e436a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -352,7 +352,7 @@ infrastructure/messaging/{rabbitmq|kafka}/{module}
 ```text
 infrastructure/storage
 ├── ObjectStorageProvider.java
-└── aliyun
+└── qiniu
 infrastructure/cdn
 infrastructure/config/ObjectStorageProperties.java
 infrastructure/config/CdnProperties.java
diff --git a/docs/deployment.md b/docs/deployment.md
index 577dbb5..f966a0a 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -18,22 +18,23 @@ session or using profile avatars:
 DASHSCOPE_API_KEY=replace-with-your-real-key
 BAILIAN_WORKSPACE_ID=replace-with-your-workspace-id
 BAILIAN_MODEL=qwen3.5-omni-flash-realtime
-OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
-OSS_BUCKET=replace-with-your-private-bucket
-OSS_ACCESS_KEY_ID=replace-with-your-access-key-id
-OSS_ACCESS_KEY_SECRET=replace-with-your-access-key-secret
-OSS_AVATAR_PREFIX=avatars
-OSS_SIGNED_URL_TTL=1h
+QINIU_ACCESS_KEY=replace-with-your-access-key
+QINIU_SECRET_KEY=replace-with-your-secret-key
+QINIU_BUCKET=replace-with-your-private-bucket
+QINIU_DOMAIN=https://replace-with-your-https-download-domain
+QINIU_AVATAR_PREFIX=avatars
+QINIU_SIGNED_URL_TTL=1h
 PROFILE_TIME_ZONE=Asia/Shanghai
 ```
 
 Do not put API keys in a `VITE_` variable because Vite embeds those values in
 browser assets.
 
-The OSS bucket must remain private. The backend stores only the object key in
-PostgreSQL and returns a short-lived signed download URL to the browser. Grant
-the configured RAM identity only the object read/write/delete permissions
-required for the avatar prefix.
+The Qiniu Kodo bucket must remain private. `QINIU_DOMAIN` must be the bucket's
+HTTPS download domain and must not contain a path, query, or fragment. The
+backend stores only the object key in PostgreSQL and returns a short-lived
+signed download URL to the browser. Grant the configured Qiniu key only the
+upload, download, and delete permissions required for this bucket.
 
 ## Profile database migration
 
@@ -71,13 +72,13 @@ profile:
   time-zone: ${PROFILE_TIME_ZONE:Asia/Shanghai}
 
 object-storage:
-  aliyun:
-    endpoint: ${OSS_ENDPOINT:}
-    bucket: ${OSS_BUCKET:}
-    access-key-id: ${OSS_ACCESS_KEY_ID:}
-    access-key-secret: ${OSS_ACCESS_KEY_SECRET:}
-    avatar-prefix: ${OSS_AVATAR_PREFIX:avatars}
-    signed-url-ttl: ${OSS_SIGNED_URL_TTL:1h}
+  qiniu:
+    access-key: ${QINIU_ACCESS_KEY:}
+    secret-key: ${QINIU_SECRET_KEY:}
+    bucket: ${QINIU_BUCKET:}
+    domain: ${QINIU_DOMAIN:}
+    avatar-prefix: ${QINIU_AVATAR_PREFIX:avatars}
+    signed-url-ttl: ${QINIU_SIGNED_URL_TTL:1h}
 ```
 
 The WebRTC SDP endpoint is derived automatically:
diff --git a/docs/frontend-backend-interface-contract.md b/docs/frontend-backend-interface-contract.md
index fa4f72d..1010612 100644
--- a/docs/frontend-backend-interface-contract.md
+++ b/docs/frontend-backend-interface-contract.md
@@ -59,7 +59,7 @@ Authorization: Bearer <accessToken>
 Content-Type: multipart/form-data
 ```
 
-表单字段名为 `avatar`。仅接受 JPEG/PNG，文件不超过 2 MiB，宽高均为 128～4096 像素。后端会解码并重新编码后写入阿里云 OSS，响应包含一小时有效的签名 URL。
+表单字段名为 `avatar`。仅接受 JPEG/PNG，文件不超过 2 MiB，宽高均为 128～4096 像素。后端会解码并重新编码后写入七牛云 Kodo 私有空间，响应包含一小时有效的签名 URL。
 
 ### 修改密码
 
diff --git "a/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md" "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md"
index 1553660..d92a828 100644
--- "a/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md"
+++ "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md"
@@ -1,19 +1,21 @@
 # 个人主页账户资料与自动打卡实施计划
 
-> **执行要求：** 严格按照本计划逐项实施。每项只修改一个文件，验证该文件相关编译后立即单独 commit。用户明确要求不新增或修改测试文件，因此本计划不创建测试代码，使用现有测试套件、前端构建与检查作为回归验证。
+> **执行要求：** 严格按照本计划逐项实施。按可独立验收的功能大点提交中文 commit。测试保持最小必要范围：复用现有套件，只有供应商适配等 `CLAUDE.md` 明确要求覆盖的新边界才增加定向测试，不扩张前端测试框架。
 
-**目标：** 实现动态报告打卡日历、展示昵称修改、阿里云 OSS 用户头像和全端 JWT 失效的密码修改功能。
+> 下列任务末尾保留的“单文件 commit”是初版计划的历史拆分标记；实际提交粒度以本页最新执行要求和用户后续确认为准。
 
-**架构：** 完整设计以 `docs/个人主页账户资料与自动打卡开发设计.md` 为准。Profile 读取、Profile 写入、Auth 和 OSS 基础设施保持独立；打卡只读取现有 `session_evaluation`，不增加打卡写模型、Redis 或评分表字段。
+**目标：** 实现动态报告打卡日历、展示昵称修改、七牛云 Kodo 用户头像和全端 JWT 失效的密码修改功能。
 
-**技术栈：** Java 21、Spring Boot 4、MyBatis-Plus 3.5.17、PostgreSQL、阿里云 OSS Java SDK、React 19、Vite 6。
+**架构：** 完整设计以 `docs/个人主页账户资料与自动打卡开发设计.md` 为准。Profile 读取、Profile 写入、Auth 和对象存储基础设施保持独立；打卡只读取现有 `session_evaluation`，不增加打卡写模型、Redis 或评分表字段。
+
+**技术栈：** Java 21、Spring Boot 4、MyBatis-Plus 3.5.17、PostgreSQL、七牛云 Java SDK 7.19.0、React 19、Vite 6。
 
 ## 全局约束
 
 - 开发前遵循仓库根目录 `CLAUDE.md`。
 - 当前分支固定为 `feat/profile-account-checkin`。
-- 每个 commit 只包含一个文件。
-- 不新增或修改 `src/test` 文件，不删除现有测试。
+- 每个 commit 只包含一个可独立验收的功能大点，提交信息使用中文。
+- 不删除现有测试，不增加与本次需求无关或重复的测试。
 - Java 中不写原始 SQL，不使用 SQL 注解、Mapper XML 或被禁止的 Wrapper 方法。
 - 用户身份只来自 JWT。
 - 不读取、修改或提交 `deploy/env/.env`。
@@ -25,9 +27,9 @@
 
 - [ ] 修改 `backend/unispeaking-server/src/main/resources/db/schema.sql`：只给 `"user"` 增加 `avatar_object_key VARCHAR(512)`、非空白约束和注释；运行 `./mvnw -q -DskipTests compile`；单文件 commit。
 - [ ] 新建 `deploy/postgres/profile.sql`：用 `BEGIN/COMMIT` 包装同一幂等迁移；单文件 commit。
-- [ ] 修改 `backend/unispeaking-server/pom.xml`：增加 `aliyun-oss.version=3.18.5` 和 `com.aliyun.oss:aliyun-sdk-oss`；运行 `./mvnw -q -DskipTests compile`；单文件 commit。
-- [ ] 修改 `backend/unispeaking-server/src/main/resources/application.yaml`：增加 `profile.time-zone` 与 `object-storage.aliyun`；单文件 commit。
-- [ ] 修改 `deploy/env/.env.example`：增加 Profile/OSS 空占位配置；单文件 commit。
+- [ ] 修改 `backend/unispeaking-server/pom.xml`：增加 `qiniu-java-sdk.version=7.19.0` 和 `com.qiniu:qiniu-java-sdk`；运行 `./mvnw -q -DskipTests compile`；单文件 commit。
+- [ ] 修改 `backend/unispeaking-server/src/main/resources/application.yaml`：增加 `profile.time-zone` 与 `object-storage.qiniu`；单文件 commit。
+- [ ] 修改 `deploy/env/.env.example`：增加 Profile/七牛云空占位配置；单文件 commit。
 - [ ] 修改 `deploy/nginx/nginx.conf`：在 server 块设置 `client_max_body_size 10m`；单文件 commit。
 
 ### Task 2：账号持久化
@@ -51,13 +53,13 @@
 - [ ] 新建 `domain/dto/profile/UpdateProfileResponse.java`：返回 nickname/displayName；编译；单文件 commit。
 - [ ] 新建 `domain/dto/profile/AvatarResponse.java`：返回签名 URL 和到期时间；编译；单文件 commit。
 - [ ] 新建 `infrastructure/config/ProfileProperties.java`：绑定 `profile.time-zone` 并提供合法 `ZoneId`；编译；单文件 commit。
-- [ ] 新建 `infrastructure/config/ObjectStorageProperties.java`：绑定 endpoint、bucket、Access Key、前缀和签名 TTL；编译；单文件 commit。
+- [ ] 新建 `infrastructure/config/ObjectStorageProperties.java`：绑定 domain、bucket、Access Key、Secret Key、前缀和签名 TTL；编译；单文件 commit。
 
-### Task 5：OSS 与图片处理
+### Task 5：七牛云对象存储与图片处理
 
 - [ ] 新建 `infrastructure/storage/ObjectStorageProvider.java`：定义 `put`、`signGetUrl`、`delete`；编译；单文件 commit。
-- [ ] 新建 `infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java`：唯一 OSS SDK 适配器，转换供应商异常；编译；单文件 commit。
-- [ ] 新建 `infrastructure/config/ObjectStorageConfig.java`：配置完整时创建 OSS Provider，不完整时提供明确不可用实现，关闭时 shutdown；编译；单文件 commit。
+- [ ] 新建 `infrastructure/storage/qiniu/QiniuObjectStorageProvider.java`：唯一七牛云 SDK 适配器，转换供应商异常；编译；单文件 commit。
+- [ ] 新建 `infrastructure/config/ObjectStorageConfig.java`：配置完整时创建七牛云 Provider，不完整时提供明确不可用实现；编译；单文件 commit。
 - [ ] 新建 `service/profile/image/AvatarImageProcessor.java`：校验 2 MiB、JPEG/PNG、128～4096 像素并重新编码；编译；单文件 commit。
 
 ### Task 6：Profile 业务与接口
@@ -65,9 +67,9 @@
 - [ ] 新建 `service/profile/ProfileOverviewService.java`：定义 `getOverview(userId, month)`；编译；单文件 commit。
 - [ ] 新建 `service/profile/impl/ProfileOverviewServiceImpl.java`：按上海时区推导日期、生成 displayName、签名头像并对签名失败降级；编译；单文件 commit。
 - [ ] 新建 `service/profile/ProfileAccountService.java`：定义昵称和头像更新接口；编译；单文件 commit。
-- [ ] 新建 `service/profile/impl/ProfileAccountServiceImpl.java`：实现昵称、头像对象 Key、并发条件和 OSS 补偿；编译；单文件 commit。
+- [ ] 新建 `service/profile/impl/ProfileAccountServiceImpl.java`：实现昵称、头像对象 Key、并发条件和对象存储补偿；编译；单文件 commit。
 - [ ] 新建 `controller/ProfileController.java`：实现 overview、PATCH profile 和 multipart avatar；编译；单文件 commit。
-- [ ] 修改 `common/exception/GlobalExceptionHandler.java`：增加 Profile/Auth/OSS 错误状态映射；编译；单文件 commit。
+- [ ] 修改 `common/exception/GlobalExceptionHandler.java`：增加 Profile/Auth/对象存储错误状态映射；编译；单文件 commit。
 
 ### Task 7：修改密码
 
@@ -86,15 +88,14 @@
 ### Task 9：接口与部署文档
 
 - [ ] 修改 `docs/frontend-backend-interface-contract.md`：补充 Profile 和密码接口；单文件 commit。
-- [ ] 修改 `docs/deployment.md`：补充 OSS、私有 Bucket、RAM 最小权限和签名 URL；单文件 commit。
+- [ ] 修改 `docs/deployment.md`：补充七牛云配置、私有 Bucket、最小权限和签名 URL；单文件 commit。
 
 ### Task 10：最终验证
 
 - [ ] 确认 `git status --short` 为空。
-- [ ] 确认从设计文档 commit 之后的每个 commit 都只包含一个文件。
+- [ ] 确认每个开发 commit 都只包含一个可独立验收的功能大点，且提交信息为中文。
 - [ ] 运行 `backend/unispeaking-server/./mvnw test`，期望 0 failures、0 errors。
 - [ ] 运行 `npm run build`，期望成功。
 - [ ] 运行 `npm run check:routes`，期望 32 assertions passed。
 - [ ] 运行 `npm run check:realtime-events`，期望通过。
 - [ ] 运行 `./mvnw dependency:tree`，确认没有第二套 ORM/JSON/HTTP 技术栈。
-
diff --git "a/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md" "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md"
index 072ff7d..e9bac31 100644
--- "a/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md"
+++ "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md"
@@ -5,9 +5,9 @@
 - 设计日期：2026-07-31。
 - 适用仓库：`UniSpeaking`。
 - 定位基线：当前提交 `27e8618`。
-- 当前状态：设计已确认，等待用户明确批准后才允许进入开发。
+- 当前状态：设计已确认并已进入实施；对象存储供应商已按后续确认切换为七牛云 Kodo。
 - 本文中的行号以当前提交为准；实施时同时使用类名、方法名和代码锚点定位，禁止仅凭行号修改。
-- 本文只定义开发方案，不代表已经修改源码、配置、数据库或依赖。
+- 本文记录确认后的开发方案及精确修改位置；实际完成情况以 Git 提交和验证结果为准。
 
 ## 2. 强制开发规范
 
@@ -20,15 +20,16 @@
 5. Java 代码中禁止原始 SQL、SQL 注解、Mapper XML，以及 `.last()`、`.apply()`、
    `.inSql()`、`.notInSql()`、`.setSql()`。
 6. 当前用户 ID 必须来自 JWT；任何个人资料接口都不接收客户端传入的 `userId`。
-7. OSS Access Key、Secret、Bucket 和 Endpoint 只允许由环境变量注入，不得进入 DTO、
+7. 七牛 Access Key、Secret Key、Bucket 和下载域名只允许由环境变量注入，不得进入 DTO、
    前端、日志或 Git。
 8. 数据库只保存头像对象 Key，不保存长期签名 URL。
 9. 上传头像必须验证实际内容、大小、图片尺寸和对象归属。
 10. 业务异常使用 `BusinessException` 和稳定错误码，响应使用统一 `ApiResponse`。
-11. 日志不得记录密码、JWT、OSS 密钥、签名 URL 或图片二进制。
-12. 新行为必须有测试，默认测试不得调用真实 OSS 或其他外网服务。
+11. 日志不得记录密码、JWT、对象存储密钥、签名 URL 或图片二进制。
+12. 新行为必须有测试，默认测试不得调用真实七牛云或其他外网服务。
 
-`CLAUDE.md` 本身不需要修改，它是本设计的上位约束。
+`CLAUDE.md` 是本设计的上位约束；仅将其中对象存储供应商目录由 `aliyun` 同步为
+`qiniu`，不改变其分层、安全或测试规则。
 
 ## 3. 已确认需求
 
@@ -42,7 +43,7 @@
 ### 3.2 用户头像
 
 - 用户可以上传 JPEG 或 PNG 头像。
-- 头像保存到阿里云 OSS。
+- 头像保存到七牛云 Kodo 私有空间。
 - 后端保存对象 Key，并按需生成有效期 1 小时的签名读取 URL。
 - 未设置头像或签名 URL 暂时不可用时，前端显示
   `/brand/unispeaking-mark-user.jpg`。
@@ -90,7 +91,7 @@
 - 不增加 Redis 依赖、Redis 容器或 Redis 配置。
 - 不修改五维评分算法、五维报告字段或评分表结构。
 - 不把原有静态统计、练习节奏或成就系统改为动态数据。
-- 不引入消息队列、CDN 或浏览器直传 OSS。
+- 不引入消息队列、CDN 或浏览器直传七牛云。
 - 不在本次工作中重构整个 `App.jsx`。
 
 ## 5. 当前项目事实
@@ -108,7 +109,8 @@
 7. 前端个人主页、学习日历、统计卡和成就目前都在 `src/App.jsx`。
 8. 当前侧边栏和个人主页将 `teacher.image` 错当成用户头像。
 9. “修改密码”按钮目前没有事件处理。
-10. 当前项目没有 Redis 和 OSS 依赖。
+10. 当前项目不引入 Redis；头像对象存储通过 `ObjectStorageProvider` 抽象，由七牛云
+    Java SDK 适配，配置为空时使用不可用实现且不阻止应用启动。
 
 ## 6. 总体架构
 
@@ -131,7 +133,7 @@ AuthController
             └── PasswordEncoder
 
 ObjectStorageProvider
-    └── AliyunOssObjectStorageProvider
+    └── QiniuObjectStorageProvider
 ```
 
 边界说明：
@@ -147,7 +149,7 @@ ObjectStorageProvider
 
 ### 7.1 唯一数据库改动
 
-只修改 `"user"` 表，增加 OSS 对象 Key：
+只修改 `"user"` 表，增加对象存储 Key：
 
 ```sql
 ALTER TABLE "user"
@@ -233,7 +235,7 @@ Authorization: Bearer <JWT>
       "email": "learner@example.com",
       "nickname": "Sunny",
       "displayName": "Sunny",
-      "avatarUrl": "https://example.oss-cn-hangzhou.aliyuncs.com/...",
+      "avatarUrl": "https://profile.example.com/...",
       "avatarUrlExpiresAt": "2026-07-31T10:00:00Z"
     },
     "calendar": {
@@ -301,7 +303,7 @@ avatar=<binary>
 
 ```json
 {
-  "avatarUrl": "https://example.oss-cn-hangzhou.aliyuncs.com/...",
+  "avatarUrl": "https://profile.example.com/...",
   "avatarUrlExpiresAt": "2026-07-31T10:00:00Z"
 }
 ```
@@ -333,7 +335,7 @@ Content-Type: application/json
 
 前端确认密码只在浏览器本地校验，不发送 `confirmPassword`。
 
-## 9. 头像处理与 OSS 设计
+## 9. 头像处理与七牛云对象存储设计
 
 ### 9.1 文件规则
 
@@ -349,7 +351,7 @@ Content-Type: application/json
 Spring 全局 multipart 上限继续保持 10 MB，避免影响现有音频接口；头像 2 MiB 限制在
 `AvatarImageProcessor` 中执行。
 
-### 9.2 OSS 接口
+### 9.2 对象存储接口
 
 `ObjectStorageProvider` 定义以下稳定接口：
 
@@ -359,7 +361,7 @@ URI signGetUrl(String objectKey, Duration ttl);
 void delete(String objectKey);
 ```
 
-业务代码只能依赖该接口，不得依赖阿里云 SDK 类。
+业务代码只能依赖该接口，不得依赖七牛云 SDK 类。
 
 ### 9.3 上传补偿顺序
 
@@ -375,7 +377,7 @@ void delete(String objectKey);
 
 失败策略：
 
-- 图片校验失败：不调用 OSS，不修改数据库。
+- 图片校验失败：不调用对象存储，不修改数据库。
 - 新对象上传失败：不修改数据库。
 - 新对象上传成功但数据库更新失败：立即尽力删除新对象，然后返回失败。
 - 数据库更新成功但旧对象删除失败：新头像继续生效，只记录脱敏警告日志。
@@ -383,7 +385,7 @@ void delete(String objectKey);
   `avatarUrlExpiresAt` 返回 `null`。
 - 不在请求内重试超过一次，不引入 MQ 或后台重试框架。
 
-### 9.4 OSS 配置
+### 9.4 七牛云配置
 
 `application.yaml` 中新增：
 
@@ -392,56 +394,56 @@ profile:
   time-zone: ${PROFILE_TIME_ZONE:Asia/Shanghai}
 
 object-storage:
-  aliyun:
-    endpoint: ${OSS_ENDPOINT:}
-    bucket: ${OSS_BUCKET:}
-    access-key-id: ${OSS_ACCESS_KEY_ID:}
-    access-key-secret: ${OSS_ACCESS_KEY_SECRET:}
-    avatar-prefix: ${OSS_AVATAR_PREFIX:avatars}
-    signed-url-ttl: ${OSS_SIGNED_URL_TTL:1h}
+  qiniu:
+    access-key: ${QINIU_ACCESS_KEY:}
+    secret-key: ${QINIU_SECRET_KEY:}
+    bucket: ${QINIU_BUCKET:}
+    domain: ${QINIU_DOMAIN:}
+    avatar-prefix: ${QINIU_AVATAR_PREFIX:avatars}
+    signed-url-ttl: ${QINIU_SIGNED_URL_TTL:1h}
 ```
 
 `.env.example` 只增加占位值：
 
 ```properties
 PROFILE_TIME_ZONE=Asia/Shanghai
-OSS_ENDPOINT=
-OSS_BUCKET=
-OSS_ACCESS_KEY_ID=
-OSS_ACCESS_KEY_SECRET=
-OSS_AVATAR_PREFIX=avatars
-OSS_SIGNED_URL_TTL=1h
+QINIU_ACCESS_KEY=
+QINIU_SECRET_KEY=
+QINIU_BUCKET=
+QINIU_DOMAIN=
+QINIU_AVATAR_PREFIX=avatars
+QINIU_SIGNED_URL_TTL=1h
 ```
 
 实际密钥只由用户写入被 Git 忽略的 `deploy/env/.env`。开发过程不得自动修改或输出该
-文件。
+文件。`QINIU_DOMAIN` 必须填写对应私有空间的 HTTPS 下载域名，只允许主机及可选端口，
+不得带路径、查询参数或片段。
 
 ### 9.5 依赖
 
 `pom.xml` 增加：
 
 ```xml
-<aliyun-oss.version>3.18.5</aliyun-oss.version>
+<qiniu-java-sdk.version>7.19.0</qiniu-java-sdk.version>
 ```
 
 以及：
 
 ```xml
 <dependency>
-    <groupId>com.aliyun.oss</groupId>
-    <artifactId>aliyun-sdk-oss</artifactId>
-    <version>${aliyun-oss.version}</version>
+    <groupId>com.qiniu</groupId>
+    <artifactId>qiniu-java-sdk</artifactId>
+    <version>${qiniu-java-sdk.version}</version>
 </dependency>
 ```
 
-Java 21 下如 OSS SDK 依赖树未提供 JAXB，再按阿里云官方 Java 9+ 指引补充
-`jaxb-api 2.3.1`、`activation 1.1.1` 和 `jaxb-runtime 2.3.3`；是否需要以
-`./mvnw dependency:tree` 和编译结果为准，不预先引入重复依赖。
+版本固定为 `7.19.0`，避免 Maven 版本范围导致构建结果漂移。上传使用对象 Key 受限的
+Upload Token；私有下载使用配置的 HTTPS 域名和短期签名 URL。
 
 参考：
 
-- [阿里云 OSS Java SDK 安装说明](https://help.aliyun.com/en/oss/developer-reference/oss-java-sdk/)
-- [OSS Java SDK 3.18.5 Maven 坐标](https://mvnrepository.com/artifact/com.aliyun.oss/aliyun-sdk-oss/3.18.5)
+- [七牛云 Java SDK 文档](https://developer.qiniu.com/kodo/1239/java)
+- [七牛云 Java SDK 官方仓库](https://github.com/qiniu/java-sdk)
 
 ## 10. 具体文件和修改位置
 
@@ -463,11 +465,11 @@ backend/unispeaking-server/src/main/java/com/unispeaking/
 | --- | --- | --- | --- |
 | 修改 | `backend/unispeaking-server/src/main/resources/db/schema.sql` | 当前第 1 行 `"user"` 建表；`ALTER COLUMN username TYPE VARCHAR(254)` 之后 | 增加 `avatar_object_key`、非空白约束和字段注释；不增加其他表或字段 |
 | 新建 | `deploy/postgres/profile.sql` | 新文件 | 用 `BEGIN/COMMIT` 包装同一组幂等头像字段迁移 SQL |
-| 修改 | `backend/unispeaking-server/src/main/resources/application.yaml` | 当前第 41 行 `auth:` 之前 | 新增 `profile.time-zone` 和 `object-storage.aliyun` 配置 |
-| 修改 | `deploy/env/.env.example` | 当前第 12～23 行 PostgreSQL/JWT 配置之后 | 增加 Profile 时区和 OSS 占位变量，不填真实密钥 |
+| 修改 | `backend/unispeaking-server/src/main/resources/application.yaml` | 顶层 `profile:` 之后、`prompt:` 之前 | 新增 `object-storage.qiniu`，绑定 Access Key、Secret Key、Bucket、HTTPS 下载域名、头像前缀和签名 TTL |
+| 修改 | `deploy/env/.env.example` | `# Profile and Qiniu Kodo` 段 | 增加 `QINIU_ACCESS_KEY`、`QINIU_SECRET_KEY`、`QINIU_BUCKET`、`QINIU_DOMAIN`、头像前缀和签名 TTL 占位值，不填真实密钥 |
 | 修改 | `deploy/nginx/nginx.conf` | 当前第 12 行 `server` 块内、`location /backend/` 之前 | 增加 `client_max_body_size 10m;`，与 Spring 现有 multipart 上限对齐 |
-| 不改 | `deploy/env/.env` | 被 Git 忽略 | 真实 OSS 配置由用户自行填写，开发不得读取、输出或提交 |
-| 不改 | `deploy/docker-compose.yml` | `backend.env_file` 已存在 | OSS 变量会由现有 `env_file` 自动传入，不新增 Redis 或其他服务 |
+| 不改 | `deploy/env/.env` | 被 Git 忽略 | 真实七牛云配置由用户自行填写，开发不得读取、输出或提交 |
+| 不改 | `deploy/docker-compose.yml` | `backend.env_file` 已存在 | 七牛云变量会由现有 `env_file` 自动传入，不新增 Redis 或其他服务 |
 
 ### 10.2 Domain 和 DTO
 
@@ -497,7 +499,7 @@ backend/unispeaking-server/src/main/java/com/unispeaking/
 Controller 禁止：
 
 - 接收 `userId`；
-- 直接访问 Repository、Mapper、OSS SDK；
+- 直接访问 Repository、Mapper、七牛云 SDK；
 - 计算月份边界或拼对象 Key；
 - 校验当前密码；
 - 编写上传补偿逻辑。
@@ -509,8 +511,8 @@ Controller 禁止：
 | 新建 | `service/profile/ProfileOverviewService.java` | 新文件 | 定义 `getOverview(String userId, String month)` |
 | 新建 | `service/profile/impl/ProfileOverviewServiceImpl.java` | 新文件 | 查询账户、全部场景 ID、月份报告时间，转换业务日期并签名头像 URL |
 | 新建 | `service/profile/ProfileAccountService.java` | 新文件 | 定义 `updateNickname(...)`、`replaceAvatar(...)` |
-| 新建 | `service/profile/impl/ProfileAccountServiceImpl.java` | 新文件 | 昵称更新、图片规范化、OSS 上传、数据库更新和补偿删除 |
-| 新建 | `service/profile/image/AvatarImageProcessor.java` | 新文件 | 纯图片验证和重新编码；不访问数据库或 OSS |
+| 新建 | `service/profile/impl/ProfileAccountServiceImpl.java` | 新文件 | 昵称更新、图片规范化、七牛云上传、数据库更新和补偿删除 |
+| 新建 | `service/profile/image/AvatarImageProcessor.java` | 新文件 | 纯图片验证和重新编码；不访问数据库或对象存储 |
 | 不改 | `service/profile/ProfileService.java` | 当前第 7 行接口 | 继续只处理用户偏好 |
 | 不改 | `service/profile/impl/ProfileServiceImpl.java` | 整个文件 | 不把资料、头像和打卡逻辑塞入现有偏好服务 |
 | 修改 | `service/auth/AuthService.java` | 当前第 11 行 `currentUser()` 后 | 增加 `changePassword(ChangePasswordRequest)` |
@@ -558,17 +560,17 @@ boolean updatePasswordAndAuthVersion(
 头像更新必须以 `expectedObjectKey` 作为并发条件，避免两个并发上传互相删除正在使用的
 对象。密码更新必须以 `expectedAuthVersion` 作为并发条件。
 
-### 10.6 OSS 基础设施
+### 10.6 七牛云对象存储基础设施
 
 | 动作 | 文件 | 当前定位/锚点 | 必须修改的内容 |
 | --- | --- | --- | --- |
 | 新建 | `infrastructure/storage/ObjectStorageProvider.java` | 新文件 | 稳定的上传、签名和删除接口 |
-| 新建 | `infrastructure/storage/UnavailableObjectStorageProvider.java` | 新文件 | OSS 未配置时提供明确业务失败，不让应用启动失败 |
-| 新建 | `infrastructure/storage/aliyun/AliyunOssObjectStorageProvider.java` | 新文件 | 唯一允许依赖阿里云 OSS SDK 的实现 |
-| 新建 | `infrastructure/config/ObjectStorageProperties.java` | 新文件 | `@ConfigurationProperties("object-storage.aliyun")` |
-| 新建 | `infrastructure/config/ObjectStorageConfig.java` | 新文件 | 配置完整时创建 OSS Provider，否则创建不可用 Provider；OSS Client 关闭时调用 `shutdown()` |
+| 内嵌 | `infrastructure/config/ObjectStorageConfig.java` 的 `UnavailableObjectStorageProvider` | 配置类末尾的私有静态类 | 七牛云未配置时提供明确业务失败，不让应用启动失败 |
+| 新建 | `infrastructure/storage/qiniu/QiniuObjectStorageProvider.java` | 新文件 | 唯一允许依赖七牛云 SDK 的实现；负责上传、私有下载签名、删除和供应商异常转换 |
+| 新建 | `infrastructure/config/ObjectStorageProperties.java` | 新文件 | `@ConfigurationProperties("object-storage.qiniu")`，包含 `accessKey`、`secretKey`、`bucket`、`domain`、前缀和 TTL |
+| 新建 | `infrastructure/config/ObjectStorageConfig.java` | 新文件 | `objectStorageProvider(...)` 中配置完整时创建 `Auth`、`UploadManager`、`BucketManager` 和七牛 Provider，否则创建不可用 Provider |
 | 新建 | `infrastructure/config/ProfileProperties.java` | 新文件 | `@ConfigurationProperties("profile")`，校验 `ZoneId` |
-| 修改 | `backend/unispeaking-server/pom.xml` | 当前第 29～32 行 properties；第 63～72 行 PostgreSQL/音频依赖之间 | 增加 OSS SDK 版本属性和依赖 |
+| 修改 | `backend/unispeaking-server/pom.xml` | `<properties>` 与 PostgreSQL 依赖之后 | 增加 `qiniu-java-sdk.version=7.19.0` 和 `com.qiniu:qiniu-java-sdk` 依赖 |
 
 ### 10.7 异常处理
 
@@ -591,7 +593,7 @@ boolean updatePasswordAndAuthVersion(
 | `AVATAR_STORAGE_UNAVAILABLE` | 503 |
 | `AVATAR_STORAGE_FAILED` | 502 |
 
-不得把 OSS 原始响应、Endpoint、Bucket、对象签名 URL 或异常堆栈返回给客户端。
+不得把七牛云原始响应、下载域名、Bucket、对象签名 URL 或异常堆栈返回给客户端。
 
 ### 10.8 前端
 
@@ -621,15 +623,15 @@ boolean updatePasswordAndAuthVersion(
 - 头像上传中禁止重复提交。
 - 昵称和头像成功后同步更新 Profile 和 AppShell，不刷新整页。
 - 修改密码成功后立即清除 `unispeaking.accessToken`，跳转 `/auth/login`。
-- 不把 OSS 配置、签名逻辑或密钥放到前端。
+- 不把七牛云配置、签名逻辑或密钥放到前端。
 
 ### 10.9 文档
 
 | 动作 | 文件 | 修改位置 | 必须修改的内容 |
 | --- | --- | --- | --- |
 | 修改 | `docs/frontend-backend-interface-contract.md` | 当前第 113 行“2.3 当前用户”之后 | 增加“2.4 修改密码”；在第 131 行用户资料章节前增加个人主页 overview、昵称和头像接口 |
-| 修改 | `docs/deployment.md` | 当前第 26 行“Available settings”中，Realtime 配置之前 | 增加阿里云 OSS 配置、RAM 最小权限、Bucket 私有读和签名 URL 说明 |
-| 不改 | `CLAUDE.md` | 整个文件 | 继续作为强制规范，不重复或弱化规则 |
+| 修改 | `docs/deployment.md` | “Secret file”变量清单与“Available settings”中的 `object-storage` 段 | 增加七牛云 Kodo 配置、私有 Bucket、HTTPS 下载域名、最小权限和签名 URL 说明 |
+| 修改 | `CLAUDE.md` | 第 9 节对象存储目录树 | 将供应商目录从 `aliyun` 同步为 `qiniu`，其余强制规范不变 |
 | 不改 | `README.md` | 整个文件 | 本次接口和部署信息由上述专用文档维护 |
 
 ## 11. 测试文件和覆盖范围
@@ -642,7 +644,7 @@ boolean updatePasswordAndAuthVersion(
 | `src/test/java/com/unispeaking/service/profile/ProfileAccountServiceImplTest.java` | 昵称规范化、邮箱不变、头像上传补偿、并发更新冲突、旧对象删除失败 |
 | `src/test/java/com/unispeaking/service/profile/image/AvatarImageProcessorTest.java` | JPEG/PNG、伪造扩展名、非图片、2 MiB 上限、尺寸上下限、重新编码 |
 | `src/test/java/com/unispeaking/controller/ProfileControllerTest.java` | JWT 身份、月份参数、统一响应、multipart、禁止客户端 userId |
-| `src/test/java/com/unispeaking/infrastructure/storage/aliyun/AliyunOssObjectStorageProviderTest.java` | 使用 Mock OSS Client 验证 Key、Content-Type、签名 TTL、错误转换和删除，不访问外网 |
+| `src/test/java/com/unispeaking/infrastructure/storage/qiniu/QiniuObjectStorageProviderTest.java` | 使用 Mock 七牛客户端验证 Key、Content-Type、私有签名 URL、HTTPS 域名和删除，不访问外网 |
 
 ### 11.2 修改现有测试
 
@@ -650,7 +652,7 @@ boolean updatePasswordAndAuthVersion(
 | --- | --- | --- |
 | `src/test/java/com/unispeaking/service/auth/AuthServiceImplTest.java` | 当前第 84 行 JWT 测试之后；所有 `UserAccount` 构造器 | 当前密码错误、新旧密码相同、BCrypt 编码、authVersion 增加、并发冲突、旧 JWT 被撤销 |
 | `src/test/java/com/unispeaking/infrastructure/persistence/PersistenceArchitectureTest.java` | 当前第 17～19 行禁止 API 正则及现有测试 | 确保新增 Repository 未使用 SQL 注解和禁止的 Wrapper 方法 |
-| `src/test/java/com/unispeaking/UniSpeakingApplicationTests.java` | 应用启动测试 | OSS 配置为空时应用仍能启动 |
+| `src/test/java/com/unispeaking/UniSpeakingApplicationTests.java` | 应用启动测试 | 七牛云配置为空时应用仍能启动 |
 
 ### 11.3 前端验证
 
@@ -672,7 +674,7 @@ npm run check:realtime-events
 5. 三张静态统计卡、七日节奏和成就系统内容与开发前一致。
 6. 修改昵称后，个人主页和侧边栏名称立即更新；重新登录后仍保留。
 7. 登录邮箱不因昵称修改而变化。
-8. 上传合法头像后立即更新，刷新页面后仍通过 OSS 显示。
+8. 上传合法头像后立即更新，刷新页面后仍通过七牛云签名 URL 显示。
 9. 非图片、伪造扩展名、超限图片和异常尺寸被拒绝，旧头像不变。
 10. 修改密码成功后自动返回登录页，旧 Token 请求 `/api/auth/me` 得到 401。
 
@@ -699,7 +701,7 @@ cd backend/unispeaking-server
 2. Repository 原子更新和报告日期查询。
 3. Profile DTO、月份读取服务及其测试。
 4. 图片处理器及其测试。
-5. ObjectStorageProvider、阿里云实现、配置和 Mock 测试。
+5. ObjectStorageProvider、七牛云实现、配置和 Mock 测试。
 6. Profile 资料写服务、补偿逻辑及测试。
 7. 修改密码 DTO、Service、Repository 和测试。
 8. ProfileController、AuthController 与 Controller 测试。
@@ -715,11 +717,11 @@ cd backend/unispeaking-server
 - 打卡完全由已有五维报告推导，任意持久化报告都算。
 - 静态统计卡、节奏和成就保持不变。
 - 登录邮箱不可修改，昵称可持久化修改。
-- 头像只保存 OSS Key，签名 URL 短期生成，失败补偿完整。
+- 头像只保存对象 Key，签名 URL 短期生成，失败补偿完整。
 - 修改密码验证当前密码，并通过 `auth_version` 撤销全部旧 JWT。
 - Controller 无业务逻辑，Service 不写 SQL，Repository 不泄漏 Entity。
 - 新增持久化只使用 MyBatis-Plus Lambda Wrapper。
-- 配置和日志无密码、JWT、OSS 密钥和签名 URL。
-- 所有新增行为有测试，默认测试不访问真实 OSS。
+- 配置和日志无密码、JWT、七牛云密钥和签名 URL。
+- 所有新增行为有测试，默认测试不访问真实七牛云。
 - `./mvnw test`、`npm run build`、`npm run check:routes` 和
   `npm run check:realtime-events` 全部通过。

From 0624e142e5629f7c33f62db660f2ed30ad332bb7 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Mon, 3 Aug 2026 14:00:43 +0800
Subject: [PATCH 52/62] =?UTF-8?q?feat:=20=E5=9B=BA=E5=AE=9A=E4=B8=AA?=
 =?UTF-8?q?=E4=BA=BA=E4=B8=BB=E9=A1=B5=E4=BE=A7=E6=A0=8F=E5=B9=B6=E8=B0=83?=
 =?UTF-8?q?=E6=95=B4=E7=BC=96=E8=BE=91=E6=8C=89=E9=92=AE=E4=BD=8D=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend/Unispeaking_fronted/src/styles.css | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/frontend/Unispeaking_fronted/src/styles.css b/frontend/Unispeaking_fronted/src/styles.css
index d9cdb70..2d51641 100644
--- a/frontend/Unispeaking_fronted/src/styles.css
+++ b/frontend/Unispeaking_fronted/src/styles.css
@@ -810,7 +810,24 @@ svg { display: block; }
   .assets-page:not(.asset-conversation-page):not(.asset-module-placeholder) .page-header > div > p:last-child { font-size: 17px; }
 }
 
-.profile-layout { min-height: 100%; display: grid; grid-template-columns: 250px 1fr; }.profile-nav { border-right: 1px solid var(--line); padding: 38px 22px 28px; display: flex; flex-direction: column; }.profile-user { display: flex; align-items: center; gap: 12px; padding: 0 6px 32px 10px; }.profile-user > img { flex: 0 0 auto; width: 48px; height: 48px; border-radius: 14px; object-fit: cover; object-position: center; }.profile-user > span { min-width: 0; flex: 1; }.profile-user strong, .profile-user small { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }.profile-user small { color: var(--muted); margin-top: 5px; font-size: 10px; }.profile-user__edit { flex: 0 0 auto; display: inline-flex; align-items: center; gap: 3px; padding: 6px; border: 0; border-radius: 8px; background: transparent; color: #777772; font-size: 10px; cursor: pointer; }.profile-user__edit:hover { background: var(--soft-2); color: var(--ink); }.profile-user__edit svg { width: 13px; height: 13px; }.profile-nav nav { display: grid; gap: 7px; }.profile-nav nav button, .logout { height: 46px; padding: 0 13px; border: 0; border-radius: 10px; background: #fff; display: flex; align-items: center; gap: 10px; cursor: pointer; }.profile-nav nav button.is-active { background: var(--soft-2); font-weight: 650; }.profile-nav nav svg, .logout svg { width: 19px; height: 19px; }.logout { margin-top: auto; color: #555; }.profile-content { padding: 52px clamp(42px, 5vw, 84px) 60px; overflow: auto; }.stat-grid { display: grid; grid-template-columns: repeat(3,1fr); gap: 16px; }.stat-grid article { min-height: 106px; padding: 20px; border: 1px solid var(--line); border-radius: 14px; display: flex; gap: 14px; align-items: center; }.stat-grid article > svg { width: 22px; height: 22px; }.stat-grid small, .stat-grid strong { display: block; }.stat-grid small { color: var(--muted); }.stat-grid strong { font-size: 26px; margin-top: 7px; }.stat-grid em { font-style: normal; font-size: 11px; }
+.app-main:has(.profile-layout) { overflow: hidden; }
+.profile-layout { height: 100%; min-height: 0; display: grid; grid-template-columns: 250px minmax(0, 1fr); }
+.profile-nav { min-height: 0; height: 100%; border-right: 1px solid var(--line); padding: 38px 22px 28px; display: flex; flex-direction: column; background: #fff; }
+.profile-user { position: relative; min-height: 94px; display: flex; align-items: flex-start; gap: 12px; padding: 0 6px 42px 10px; }
+.profile-user > img { flex: 0 0 auto; width: 48px; height: 48px; border-radius: 14px; object-fit: cover; object-position: center; }
+.profile-user > span { min-width: 0; flex: 1; padding-top: 2px; }
+.profile-user strong, .profile-user small { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.profile-user small { color: var(--muted); margin-top: 5px; font-size: 10px; }
+.profile-user__edit { position: absolute; right: 6px; bottom: 8px; display: inline-flex; align-items: center; gap: 3px; padding: 6px; border: 0; border-radius: 8px; background: transparent; color: #777772; font-size: 10px; cursor: pointer; }
+.profile-user__edit:hover { background: var(--soft-2); color: var(--ink); }
+.profile-user__edit svg { width: 13px; height: 13px; }
+.profile-nav nav { display: grid; gap: 7px; }
+.profile-nav nav button, .logout { height: 46px; padding: 0 13px; border: 0; border-radius: 10px; background: #fff; display: flex; align-items: center; gap: 10px; cursor: pointer; }
+.profile-nav nav button.is-active { background: var(--soft-2); font-weight: 650; }
+.profile-nav nav svg, .logout svg { width: 19px; height: 19px; }
+.logout { flex: 0 0 46px; margin-top: auto; color: #555; }
+.profile-content { min-width: 0; min-height: 0; padding: 52px clamp(42px, 5vw, 84px) 60px; overflow: auto; }
+.stat-grid { display: grid; grid-template-columns: repeat(3,1fr); gap: 16px; }.stat-grid article { min-height: 106px; padding: 20px; border: 1px solid var(--line); border-radius: 14px; display: flex; gap: 14px; align-items: center; }.stat-grid article > svg { width: 22px; height: 22px; }.stat-grid small, .stat-grid strong { display: block; }.stat-grid small { color: var(--muted); }.stat-grid strong { font-size: 26px; margin-top: 7px; }.stat-grid em { font-style: normal; font-size: 11px; }
 .today-checkin, .result-checkin { display: inline-flex; align-items: center; gap: 7px; padding: 8px 12px; border-radius: 999px; background: #20201f; color: #fff; font-size: 12px; font-weight: 700; }
 .today-checkin svg, .result-checkin svg { width: 16px; height: 16px; }
 .result-checkin { margin-top: 13px; }

From 7e254a7ccc68fcdb0890abb6f2f43de7c10e96cb Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Mon, 3 Aug 2026 15:02:07 +0800
Subject: [PATCH 53/62] =?UTF-8?q?feat:=20=E6=8C=81=E4=B9=85=E5=8C=96?=
 =?UTF-8?q?=E5=85=A8=E5=9C=BA=E6=99=AF=E7=BB=83=E4=B9=A0=E4=BC=9A=E8=AF=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../po/session/PracticeSessionRecord.java     |  17 ++
 .../entity/session/PracticeSessionEntity.java |  32 ++++
 .../mapper/session/PracticeSessionMapper.java |   8 +
 .../session/PracticeSessionRepository.java    | 168 ++++++++++++++++++
 .../service/session/SessionService.java       |   5 +-
 .../session/impl/SessionServiceImpl.java      |  52 +++---
 .../db/migration/V2__practice_session.sql     |  48 +++++
 .../PracticeSessionRepositoryTest.java        |  65 +++++++
 .../SessionServiceImplRepracticeTest.java     |  15 +-
 deploy/postgres/profile.sql                   |  37 ++++
 10 files changed, 425 insertions(+), 22 deletions(-)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/domain/po/session/PracticeSessionRecord.java
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/entity/session/PracticeSessionEntity.java
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/mapper/session/PracticeSessionMapper.java
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/session/PracticeSessionRepository.java
 create mode 100644 backend/unispeaking-server/src/main/resources/db/migration/V2__practice_session.sql
 create mode 100644 backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/session/PracticeSessionRepositoryTest.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/domain/po/session/PracticeSessionRecord.java b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/po/session/PracticeSessionRecord.java
new file mode 100644
index 0000000..f50e982
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/po/session/PracticeSessionRecord.java
@@ -0,0 +1,17 @@
+package com.unispeaking.domain.po.session;
+
+import com.unispeaking.domain.vo.scene.SceneType;
+import com.unispeaking.domain.vo.session.SessionStatus;
+import java.time.Instant;
+import java.util.UUID;
+
+public record PracticeSessionRecord(
+		String sessionId,
+		UUID userId,
+		String sceneId,
+		SceneType sceneType,
+		SessionStatus status,
+		Instant startedAt,
+		Instant endedAt) {
+}
+
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/entity/session/PracticeSessionEntity.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/entity/session/PracticeSessionEntity.java
new file mode 100644
index 0000000..4a91360
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/entity/session/PracticeSessionEntity.java
@@ -0,0 +1,32 @@
+package com.unispeaking.infrastructure.persistence.entity.session;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import com.unispeaking.infrastructure.persistence.typehandler.PostgresUuidTypeHandler;
+import java.time.OffsetDateTime;
+import java.util.UUID;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+@Getter
+@Setter
+@NoArgsConstructor
+@TableName(value = "practice_session", autoResultMap = true)
+public class PracticeSessionEntity {
+
+	@TableId(value = "session_id", type = IdType.INPUT)
+	private String sessionId;
+	@TableField(typeHandler = PostgresUuidTypeHandler.class)
+	private UUID userId;
+	private String sceneId;
+	private String sceneType;
+	private String status;
+	private OffsetDateTime startedAt;
+	private OffsetDateTime endedAt;
+	private OffsetDateTime createdAt;
+	private OffsetDateTime updatedAt;
+}
+
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/mapper/session/PracticeSessionMapper.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/mapper/session/PracticeSessionMapper.java
new file mode 100644
index 0000000..2a196fa
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/mapper/session/PracticeSessionMapper.java
@@ -0,0 +1,8 @@
+package com.unispeaking.infrastructure.persistence.mapper.session;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.unispeaking.infrastructure.persistence.entity.session.PracticeSessionEntity;
+
+public interface PracticeSessionMapper extends BaseMapper<PracticeSessionEntity> {
+}
+
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/session/PracticeSessionRepository.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/session/PracticeSessionRepository.java
new file mode 100644
index 0000000..a548214
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/session/PracticeSessionRepository.java
@@ -0,0 +1,168 @@
+package com.unispeaking.infrastructure.persistence.repository.session;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
+import com.unispeaking.common.exception.BusinessException;
+import com.unispeaking.domain.po.session.PracticeSessionRecord;
+import com.unispeaking.domain.vo.scene.SceneType;
+import com.unispeaking.domain.vo.session.SessionStatus;
+import com.unispeaking.infrastructure.persistence.entity.session.PracticeSessionEntity;
+import com.unispeaking.infrastructure.persistence.mapper.session.PracticeSessionMapper;
+import java.time.Instant;
+import java.time.OffsetDateTime;
+import java.time.ZoneOffset;
+import java.util.List;
+import java.util.UUID;
+import org.springframework.stereotype.Repository;
+
+@Repository
+public class PracticeSessionRepository {
+
+	private final PracticeSessionMapper mapper;
+
+	public PracticeSessionRepository(PracticeSessionMapper mapper) {
+		this.mapper = mapper;
+	}
+
+	public void create(PracticeSessionRecord record) {
+		PracticeSessionEntity entity = toEntity(record);
+		OffsetDateTime now = OffsetDateTime.now(ZoneOffset.UTC);
+		entity.setCreatedAt(now);
+		entity.setUpdatedAt(now);
+		try {
+			if (mapper.insert(entity) != 1) {
+				throw persistenceFailure();
+			}
+		}
+		catch (BusinessException exception) {
+			throw exception;
+		}
+		catch (RuntimeException exception) {
+			throw persistenceFailure();
+		}
+	}
+
+	public void complete(String sessionId, UUID userId, Instant endedAt) {
+		updateTerminalStatus(
+				sessionId,
+				userId,
+				SessionStatus.COMPLETED,
+				endedAt);
+	}
+
+	public void fail(String sessionId, UUID userId, Instant endedAt) {
+		updateTerminalStatus(
+				sessionId,
+				userId,
+				SessionStatus.FAILED,
+				endedAt);
+	}
+
+	public List<PracticeSessionRecord> findCompletedOverlapping(
+			UUID userId,
+			Instant start,
+			Instant end) {
+		try {
+			return mapper.selectList(
+						new LambdaQueryWrapper<PracticeSessionEntity>()
+								.eq(PracticeSessionEntity::getUserId, userId)
+								.eq(
+										PracticeSessionEntity::getStatus,
+										SessionStatus.COMPLETED.name())
+								.isNotNull(PracticeSessionEntity::getEndedAt)
+								.lt(
+										PracticeSessionEntity::getStartedAt,
+										atUtc(end))
+								.gt(
+										PracticeSessionEntity::getEndedAt,
+										atUtc(start))
+								.orderByAsc(
+										PracticeSessionEntity::getStartedAt))
+					.stream()
+					.map(this::toDomain)
+					.toList();
+		}
+		catch (RuntimeException exception) {
+			throw persistenceFailure();
+		}
+	}
+
+	private void updateTerminalStatus(
+			String sessionId,
+			UUID userId,
+			SessionStatus status,
+			Instant endedAt) {
+		OffsetDateTime end = atUtc(endedAt);
+		try {
+			int updated = mapper.update(
+					null,
+					new LambdaUpdateWrapper<PracticeSessionEntity>()
+							.eq(PracticeSessionEntity::getSessionId, sessionId)
+							.eq(PracticeSessionEntity::getUserId, userId)
+							.notIn(
+									PracticeSessionEntity::getStatus,
+									SessionStatus.COMPLETED.name(),
+									SessionStatus.FAILED.name())
+							.set(PracticeSessionEntity::getStatus, status.name())
+							.set(PracticeSessionEntity::getEndedAt, end)
+							.set(PracticeSessionEntity::getUpdatedAt, end));
+			if (updated == 1 || alreadyTerminal(sessionId, userId, status)) {
+				return;
+			}
+			throw persistenceFailure();
+		}
+		catch (BusinessException exception) {
+			throw exception;
+		}
+		catch (RuntimeException exception) {
+			throw persistenceFailure();
+		}
+	}
+
+	private boolean alreadyTerminal(
+			String sessionId,
+			UUID userId,
+			SessionStatus status) {
+		return mapper.selectCount(
+				new LambdaQueryWrapper<PracticeSessionEntity>()
+						.eq(PracticeSessionEntity::getSessionId, sessionId)
+						.eq(PracticeSessionEntity::getUserId, userId)
+						.eq(PracticeSessionEntity::getStatus, status.name())) == 1;
+	}
+
+	private PracticeSessionEntity toEntity(PracticeSessionRecord record) {
+		PracticeSessionEntity entity = new PracticeSessionEntity();
+		entity.setSessionId(record.sessionId());
+		entity.setUserId(record.userId());
+		entity.setSceneId(record.sceneId());
+		entity.setSceneType(record.sceneType().name());
+		entity.setStatus(record.status().name());
+		entity.setStartedAt(atUtc(record.startedAt()));
+		entity.setEndedAt(record.endedAt() == null ? null : atUtc(record.endedAt()));
+		return entity;
+	}
+
+	private PracticeSessionRecord toDomain(PracticeSessionEntity entity) {
+		return new PracticeSessionRecord(
+				entity.getSessionId(),
+				entity.getUserId(),
+				entity.getSceneId(),
+				SceneType.valueOf(entity.getSceneType()),
+				SessionStatus.valueOf(entity.getStatus()),
+				entity.getStartedAt().toInstant(),
+				entity.getEndedAt() == null
+						? null
+						: entity.getEndedAt().toInstant());
+	}
+
+	private OffsetDateTime atUtc(Instant instant) {
+		return instant.atOffset(ZoneOffset.UTC);
+	}
+
+	private BusinessException persistenceFailure() {
+		return new BusinessException(
+				"PRACTICE_SESSION_PERSISTENCE_FAILED",
+				"练习会话记录保存失败");
+	}
+}
+
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/session/SessionService.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/session/SessionService.java
index a791387..079fe88 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/service/session/SessionService.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/session/SessionService.java
@@ -12,7 +12,10 @@
 
 public interface SessionService {
 
-	StartSessionResponse startSession(SceneType sceneType, String prompt);
+	StartSessionResponse startSession(
+			SceneType sceneType,
+			String sceneId,
+			String prompt);
 
 	StartSceneSessionResponse startFreeChat(StartFreeChatRequest request);
 
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/session/impl/SessionServiceImpl.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/session/impl/SessionServiceImpl.java
index 09a5933..12ab417 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/service/session/impl/SessionServiceImpl.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/session/impl/SessionServiceImpl.java
@@ -20,6 +20,7 @@
 import com.unispeaking.domain.po.session.AbstractSceneSession;
 import com.unispeaking.domain.po.session.CustomSceneSession;
 import com.unispeaking.domain.po.session.FreeChatSceneSession;
+import com.unispeaking.domain.po.session.PracticeSessionRecord;
 import com.unispeaking.domain.vo.session.SpeakerType;
 import com.unispeaking.domain.vo.session.SessionPrompt;
 import com.unispeaking.domain.vo.provider.ProviderType;
@@ -30,6 +31,7 @@
 import com.unispeaking.common.exception.BusinessException;
 import com.unispeaking.common.exception.SessionNotFoundException;
 import com.unispeaking.infrastructure.persistence.repository.session.SessionMessageRepository;
+import com.unispeaking.infrastructure.persistence.repository.session.PracticeSessionRepository;
 import com.unispeaking.provider.AiProviderRegistry;
 import com.unispeaking.infrastructure.persistence.repository.scene.SceneRepository;
 import com.unispeaking.component.session.ActiveSessionRegistry;
@@ -44,7 +46,6 @@
 import com.unispeaking.service.scene.impl.ScenarioDialogueStateMachine;
 import com.unispeaking.service.session.SessionService;
 import java.time.Instant;
-import java.time.format.DateTimeParseException;
 import java.util.List;
 import java.util.UUID;
 import org.springframework.stereotype.Service;
@@ -58,6 +59,7 @@ public class SessionServiceImpl implements SessionService {
 	private final SceneRepository sceneRepository;
 	private final ActiveSessionRegistry activeSessionRegistry;
 	private final SessionMessageRepository sessionMessageRepository;
+	private final PracticeSessionRepository practiceSessionRepository;
 	private final RealtimeSdpExchange realtimeSdpExchange;
 	private final EvaluationService evaluationService;
 	private final ScenarioDialogueStateMachine stateMachine;
@@ -73,6 +75,7 @@ public SessionServiceImpl(
 			SceneRepository sceneRepository,
 			ActiveSessionRegistry activeSessionRegistry,
 			SessionMessageRepository sessionMessageRepository,
+			PracticeSessionRepository practiceSessionRepository,
 			RealtimeSdpExchange realtimeSdpExchange,
 			EvaluationService evaluationService,
 			ScenarioDialogueStateMachine stateMachine,
@@ -86,6 +89,7 @@ public SessionServiceImpl(
 		this.sceneRepository = sceneRepository;
 		this.activeSessionRegistry = activeSessionRegistry;
 		this.sessionMessageRepository = sessionMessageRepository;
+		this.practiceSessionRepository = practiceSessionRepository;
 		this.realtimeSdpExchange = realtimeSdpExchange;
 		this.evaluationService = evaluationService;
 		this.stateMachine = stateMachine;
@@ -96,7 +100,10 @@ public SessionServiceImpl(
 	}
 
 	@Override
-	public StartSessionResponse startSession(SceneType sceneType, String prompt) {
+	public StartSessionResponse startSession(
+			SceneType sceneType,
+			String sceneId,
+			String prompt) {
 		String userId = authService.requireUserId(null);
 		SceneType type = sceneType == null ? SceneType.FREE_CHAT : sceneType;
 		String sessionId = SessionIdGenerator.generate(type);
@@ -104,7 +111,16 @@ public StartSessionResponse startSession(SceneType sceneType, String prompt) {
 				? new FreeChatSceneSession(sessionId, userId)
 				: new CustomSceneSession(sessionId, userId);
 		session.setSceneType(type);
+		session.setSceneId(sceneId);
 		session.setPrompt(new SessionPrompt(requirePrompt(prompt)));
+		practiceSessionRepository.create(new PracticeSessionRecord(
+				session.getId(),
+				UUID.fromString(userId),
+				sceneId,
+				type,
+				session.getStatus(),
+				session.getCreatedAt(),
+				null));
 		activeSessionRegistry.save(session);
 		RealtimeFlowLog.info(
 				"session.start sessionId={} userId={} sceneType={} startTime={} prompt={}",
@@ -129,6 +145,7 @@ public StartSceneSessionResponse startFreeChat(StartFreeChatRequest request) {
 		SceneFlowResponse flow = sceneFlowService.createFlow(scene.sceneId());
 		StartSessionResponse started = startSession(
 				SceneType.FREE_CHAT,
+				scene.sceneId(),
 				scene.scenePrompt());
 		RealtimeConnectionResult connection = connect(
 				started.sessionId(),
@@ -166,6 +183,7 @@ public StartSceneSessionResponse startCustomScene(
 		String basePrompt = resolvePrompt(scene, definition, userId);
 		StartSessionResponse started = startSession(
 				SceneType.CUSTOM_SCENE,
+				sceneId,
 				basePrompt);
 		stateMachine.start(started.sessionId(), definition);
 		try {
@@ -241,7 +259,12 @@ public void addMessage(String userId, String sessionId, Message message) {
 	public void endSession(String userId, String sessionId, String stopTime) {
 		AbstractSceneSession session = requireOwnedSession(userId, sessionId);
 		if (session.getStatus() != SessionStatus.COMPLETED) {
-			session.complete(parseStopTime(stopTime));
+			Instant endedAt = Instant.now();
+			practiceSessionRepository.complete(
+					sessionId,
+					UUID.fromString(userId),
+					endedAt);
+			session.complete(endedAt);
 			activeSessionRegistry.save(session);
 		}
 		RealtimeFlowLog.info(
@@ -267,10 +290,8 @@ public CompleteCustomSceneDialogueResponse completeCustomScene(
 				stateMachine.findState(sessionId)
 						.map(ignored -> stateMachine.beginClosing(sessionId))
 						.orElse(null);
-		String endedAt = stopTime == null || stopTime.isBlank()
-				? Instant.now().toString()
-				: stopTime.trim();
-		endSession(userId, sessionId, endedAt);
+		endSession(userId, sessionId, stopTime);
+		String endedAt = session.getEndedAt().toString();
 		RealtimeFlowLog.info(
 				"evaluation.report.start sceneId={} sessionId={}",
 				sceneId,
@@ -417,6 +438,10 @@ private RealtimeConnectionResult connect(
 		}
 		catch (RuntimeException exception) {
 			session.fail("REALTIME_CONNECTION_FAILED", exception.getMessage());
+			practiceSessionRepository.fail(
+					sessionId,
+					UUID.fromString(session.getUserId()),
+					session.getEndedAt());
 			activeSessionRegistry.remove(sessionId);
 			throw exception;
 		}
@@ -532,17 +557,4 @@ private String requirePrompt(String prompt) {
 		return prompt;
 	}
 
-	private Instant parseStopTime(String stopTime) {
-		if (stopTime == null || stopTime.isBlank()) {
-			return Instant.now();
-		}
-		try {
-			return Instant.parse(stopTime.trim());
-		}
-		catch (DateTimeParseException exception) {
-			throw new BusinessException(
-					"INVALID_STOP_TIME",
-					"stopTime must use ISO-8601 format");
-		}
-	}
 }
diff --git a/backend/unispeaking-server/src/main/resources/db/migration/V2__practice_session.sql b/backend/unispeaking-server/src/main/resources/db/migration/V2__practice_session.sql
new file mode 100644
index 0000000..481d82e
--- /dev/null
+++ b/backend/unispeaking-server/src/main/resources/db/migration/V2__practice_session.sql
@@ -0,0 +1,48 @@
+CREATE TABLE IF NOT EXISTS practice_session (
+    session_id VARCHAR(64) PRIMARY KEY,
+    user_id UUID NOT NULL,
+    scene_id VARCHAR(64),
+    scene_type VARCHAR(32) NOT NULL,
+    status VARCHAR(16) NOT NULL,
+    started_at TIMESTAMPTZ NOT NULL,
+    ended_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT practice_session_scene_type_check
+        CHECK (scene_type IN (
+            'FREE_CHAT',
+            'CUSTOM_SCENE',
+            'INTERVIEW_SCENE',
+            'IELTS_SCENE'
+        )),
+    CONSTRAINT practice_session_status_check
+        CHECK (status IN (
+            'CREATED',
+            'CONNECTING',
+            'WAITING_CLIENT',
+            'ACTIVE',
+            'PAUSED',
+            'INTERRUPTED',
+            'COMPLETED',
+            'FAILED'
+        )),
+    CONSTRAINT practice_session_time_check
+        CHECK (ended_at IS NULL OR ended_at >= started_at)
+);
+
+CREATE INDEX IF NOT EXISTS idx_practice_session_user_started_at
+ON practice_session (user_id, started_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_practice_session_user_completed_at
+ON practice_session (user_id, ended_at DESC)
+WHERE status = 'COMPLETED' AND ended_at IS NOT NULL;
+
+COMMENT ON TABLE practice_session IS
+'全场景练习会话事实；学习时长由 started_at 与 ended_at 计算，不保存聚合统计值';
+
+COMMENT ON COLUMN practice_session.user_id IS
+'逻辑关联 user.id，不设置数据库外键';
+
+COMMENT ON COLUMN practice_session.scene_id IS
+'场景业务 ID；自由对话和后续无需持久化场景定义的类型也允许记录';
+
diff --git a/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/session/PracticeSessionRepositoryTest.java b/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/session/PracticeSessionRepositoryTest.java
new file mode 100644
index 0000000..fa38293
--- /dev/null
+++ b/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/session/PracticeSessionRepositoryTest.java
@@ -0,0 +1,65 @@
+package com.unispeaking.infrastructure.persistence.repository.session;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import com.unispeaking.domain.po.session.PracticeSessionRecord;
+import com.unispeaking.domain.vo.scene.SceneType;
+import com.unispeaking.domain.vo.session.SessionStatus;
+import com.unispeaking.infrastructure.persistence.entity.session.PracticeSessionEntity;
+import com.unispeaking.infrastructure.persistence.mapper.session.PracticeSessionMapper;
+import java.time.Instant;
+import java.util.List;
+import java.util.UUID;
+import org.junit.jupiter.api.Test;
+
+class PracticeSessionRepositoryTest {
+
+	@Test
+	void createsPracticeSessionWithBusinessFields() {
+		PracticeSessionMapper mapper = mock(PracticeSessionMapper.class);
+		when(mapper.insert(any(PracticeSessionEntity.class))).thenReturn(1);
+		PracticeSessionRepository repository =
+				new PracticeSessionRepository(mapper);
+		UUID userId = UUID.randomUUID();
+
+		repository.create(new PracticeSessionRecord(
+				"custom_session_1",
+				userId,
+				"custom_scene1",
+				SceneType.CUSTOM_SCENE,
+				SessionStatus.CREATED,
+				Instant.parse("2026-08-03T02:00:00Z"),
+				null));
+
+		verify(mapper).insert(any(PracticeSessionEntity.class));
+	}
+
+	@Test
+	void mapsCompletedSessionsFromRequestedWindow() {
+		PracticeSessionMapper mapper = mock(PracticeSessionMapper.class);
+		PracticeSessionEntity entity = new PracticeSessionEntity();
+		entity.setSessionId("freechat_session_1");
+		entity.setUserId(UUID.randomUUID());
+		entity.setSceneId("freechat_scene1");
+		entity.setSceneType(SceneType.FREE_CHAT.name());
+		entity.setStatus(SessionStatus.COMPLETED.name());
+		entity.setStartedAt(Instant.parse("2026-08-03T02:00:00Z").atOffset(java.time.ZoneOffset.UTC));
+		entity.setEndedAt(Instant.parse("2026-08-03T02:05:00Z").atOffset(java.time.ZoneOffset.UTC));
+		when(mapper.selectList(any())).thenReturn(List.of(entity));
+		PracticeSessionRepository repository =
+				new PracticeSessionRepository(mapper);
+
+		List<PracticeSessionRecord> records = repository.findCompletedOverlapping(
+				entity.getUserId(),
+				Instant.parse("2026-08-03T00:00:00Z"),
+				Instant.parse("2026-08-04T00:00:00Z"));
+
+		assertEquals(1, records.size());
+		assertEquals(entity.getStartedAt().toInstant(), records.getFirst().startedAt());
+		assertEquals(entity.getEndedAt().toInstant(), records.getFirst().endedAt());
+	}
+}
diff --git a/backend/unispeaking-server/src/test/java/com/unispeaking/service/session/SessionServiceImplRepracticeTest.java b/backend/unispeaking-server/src/test/java/com/unispeaking/service/session/SessionServiceImplRepracticeTest.java
index 4fa485c..8d904b6 100644
--- a/backend/unispeaking-server/src/test/java/com/unispeaking/service/session/SessionServiceImplRepracticeTest.java
+++ b/backend/unispeaking-server/src/test/java/com/unispeaking/service/session/SessionServiceImplRepracticeTest.java
@@ -3,6 +3,7 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.ArgumentMatchers.isNull;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.never;
@@ -19,6 +20,7 @@
 import com.unispeaking.domain.vo.session.RealtimeConnectionResult;
 import com.unispeaking.infrastructure.persistence.repository.scene.SceneRepository;
 import com.unispeaking.infrastructure.persistence.repository.session.SessionMessageRepository;
+import com.unispeaking.infrastructure.persistence.repository.session.PracticeSessionRepository;
 import com.unispeaking.infrastructure.realtime.RealtimeSdpExchange;
 import com.unispeaking.provider.AiProviderRegistry;
 import com.unispeaking.service.asset.impl.ObsoleteDialogueCleanup;
@@ -38,7 +40,7 @@ class SessionServiceImplRepracticeTest {
 
 	@Test
 	void repracticeStartsWithoutAnInMemorySceneFlow() {
-		String userId = "user_1";
+		String userId = "f76889ee-7f7c-4dae-bcc2-61b85a63dcec";
 		String sceneId = "custom_repeat123";
 		String prompt = "layer 1\n\nlayer 2\n\nlayer 3\n\nlayer 4\n\nlayer 5";
 		AuthService authService = mock(AuthService.class);
@@ -48,6 +50,8 @@ void repracticeStartsWithoutAnInMemorySceneFlow() {
 		ScenarioDialogueStateMachine stateMachine =
 				mock(ScenarioDialogueStateMachine.class);
 		ActiveSessionRegistry sessions = new ActiveSessionRegistry();
+		PracticeSessionRepository practiceSessions =
+				mock(PracticeSessionRepository.class);
 		CustomSceneDefinition definition = new CustomSceneDefinition(
 				sceneId,
 				userId,
@@ -89,6 +93,7 @@ void repracticeStartsWithoutAnInMemorySceneFlow() {
 				sceneRepository,
 				sessions,
 				mock(SessionMessageRepository.class),
+				practiceSessions,
 				realtimeSdpExchange,
 				mock(EvaluationService.class),
 				stateMachine,
@@ -110,6 +115,14 @@ void repracticeStartsWithoutAnInMemorySceneFlow() {
 		assertEquals(SceneFlowStage.DIALOGUE, response.currentStage());
 		assertEquals("answer-sdp", response.answerSdp());
 		assertNotNull(response.sessionId());
+		service.endSession(
+				userId,
+				response.sessionId(),
+				"2000-01-01T00:00:00Z");
+		verify(practiceSessions).complete(
+				eq(response.sessionId()),
+				eq(java.util.UUID.fromString(userId)),
+				any(Instant.class));
 		verify(sceneFlowService, never()).getByCurrentStage(
 				any(),
 				any());
diff --git a/deploy/postgres/profile.sql b/deploy/postgres/profile.sql
index 0c67328..a170cb8 100644
--- a/deploy/postgres/profile.sql
+++ b/deploy/postgres/profile.sql
@@ -14,3 +14,40 @@ COMMENT ON COLUMN "user".avatar_object_key IS
 '用户头像在对象存储中的对象 Key；不保存签名 URL、Bucket 密钥或完整访问地址';
 
 COMMIT;
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS practice_session (
+    session_id VARCHAR(64) PRIMARY KEY,
+    user_id UUID NOT NULL,
+    scene_id VARCHAR(64),
+    scene_type VARCHAR(32) NOT NULL,
+    status VARCHAR(16) NOT NULL,
+    started_at TIMESTAMPTZ NOT NULL,
+    ended_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT practice_session_scene_type_check
+        CHECK (scene_type IN (
+            'FREE_CHAT', 'CUSTOM_SCENE', 'INTERVIEW_SCENE', 'IELTS_SCENE'
+        )),
+    CONSTRAINT practice_session_status_check
+        CHECK (status IN (
+            'CREATED', 'CONNECTING', 'WAITING_CLIENT', 'ACTIVE',
+            'PAUSED', 'INTERRUPTED', 'COMPLETED', 'FAILED'
+        )),
+    CONSTRAINT practice_session_time_check
+        CHECK (ended_at IS NULL OR ended_at >= started_at)
+);
+
+CREATE INDEX IF NOT EXISTS idx_practice_session_user_started_at
+ON practice_session (user_id, started_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_practice_session_user_completed_at
+ON practice_session (user_id, ended_at DESC)
+WHERE status = 'COMPLETED' AND ended_at IS NOT NULL;
+
+COMMENT ON TABLE practice_session IS
+'全场景练习会话事实；学习时长由 started_at 与 ended_at 计算，不保存聚合统计值';
+
+COMMIT;

From d0298881e191f47eeaaf6772bc37ee98fcb786a2 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Mon, 3 Aug 2026 15:05:29 +0800
Subject: [PATCH 54/62] =?UTF-8?q?feat:=20=E6=8E=A5=E5=85=A5=E4=B8=AA?=
 =?UTF-8?q?=E4=BA=BA=E4=B8=BB=E9=A1=B5=E7=9C=9F=E5=AE=9E=E5=AD=A6=E4=B9=A0?=
 =?UTF-8?q?=E7=BB=9F=E8=AE=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../dto/profile/ProfileOverviewResponse.java  | 18 +++-
 .../scene/MybatisSceneRepository.java         | 14 +++
 .../repository/scene/SceneRepository.java     |  1 +
 .../profile/PracticeDurationCalculator.java   | 87 ++++++++++++++++++
 .../impl/ProfileOverviewServiceImpl.java      | 88 +++++++++++++++++-
 .../scene/MybatisSceneRepositoryTest.java     | 19 ++++
 .../PracticeDurationCalculatorTest.java       | 61 ++++++++++++
 .../impl/ProfileOverviewServiceImplTest.java  | 92 +++++++++++++++++++
 8 files changed, 374 insertions(+), 6 deletions(-)
 create mode 100644 backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/PracticeDurationCalculator.java
 create mode 100644 backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/PracticeDurationCalculatorTest.java
 create mode 100644 backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImplTest.java

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/ProfileOverviewResponse.java b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/ProfileOverviewResponse.java
index dfc9615..ba382d4 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/ProfileOverviewResponse.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/dto/profile/ProfileOverviewResponse.java
@@ -5,7 +5,10 @@
 import java.util.List;
 import java.util.UUID;
 
-public record ProfileOverviewResponse(Account account, Calendar calendar) {
+public record ProfileOverviewResponse(
+		Account account,
+		PracticeStatistics statistics,
+		Calendar calendar) {
 	public record Account(
 			UUID userId,
 			String email,
@@ -23,4 +26,17 @@ public record Calendar(
 			checkedDates = List.copyOf(checkedDates);
 		}
 	}
+
+	public record PracticeStatistics(
+			long weeklyPracticeSeconds,
+			long trainingRecordCount,
+			int consecutiveLearningDays,
+			List<DailyPractice> lastSevenDays) {
+		public PracticeStatistics {
+			lastSevenDays = List.copyOf(lastSevenDays);
+		}
+	}
+
+	public record DailyPractice(LocalDate date, long practiceSeconds) {
+	}
 }
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/MybatisSceneRepository.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/MybatisSceneRepository.java
index 46b117a..2f1ed35 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/MybatisSceneRepository.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/MybatisSceneRepository.java
@@ -120,6 +120,20 @@ public List<SceneAssetSnapshot> findAssetsByUserId(String userId) {
 				.toList();
 	}
 
+	@Override
+	public long countActiveByUserId(String userId) {
+		UUID ownerId;
+		try {
+			ownerId = UUID.fromString(userId);
+		}
+		catch (IllegalArgumentException exception) {
+			return 0;
+		}
+		return sceneMapper.selectCount(new LambdaQueryWrapper<SceneEntity>()
+				.eq(SceneEntity::getUserId, ownerId)
+				.isNull(SceneEntity::getDeletedAt));
+	}
+
 	@Override
 	public List<String> findAllIdsByUserId(String userId) {
 		UUID ownerId;
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/SceneRepository.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/SceneRepository.java
index 300cb22..a4498c9 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/SceneRepository.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/scene/SceneRepository.java
@@ -16,5 +16,6 @@ SceneGenerationResponse saveCustomScene(
 	Optional<SceneGenerationResponse> findGeneratedById(String sceneId);
 	Optional<CustomSceneDefinition> findCustomDefinitionById(String sceneId);
 	List<SceneAssetSnapshot> findAssetsByUserId(String userId);
+	long countActiveByUserId(String userId);
 	List<String> findAllIdsByUserId(String userId);
 }
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/PracticeDurationCalculator.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/PracticeDurationCalculator.java
new file mode 100644
index 0000000..f6b57e1
--- /dev/null
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/PracticeDurationCalculator.java
@@ -0,0 +1,87 @@
+package com.unispeaking.service.profile;
+
+import com.unispeaking.domain.dto.profile.ProfileOverviewResponse;
+import com.unispeaking.domain.po.session.PracticeSessionRecord;
+import java.time.Duration;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.ZoneId;
+import java.time.temporal.TemporalAdjusters;
+import java.util.List;
+
+public class PracticeDurationCalculator {
+
+	public static final long MINIMUM_PRACTICE_SECONDS = 180;
+
+	public ProfileOverviewResponse.PracticeStatistics calculate(
+			List<PracticeSessionRecord> records,
+			LocalDate today,
+			Instant now,
+			ZoneId zoneId,
+			long trainingRecordCount,
+			int consecutiveLearningDays) {
+		Instant weekStart = today
+				.with(TemporalAdjusters.previousOrSame(java.time.DayOfWeek.MONDAY))
+				.atStartOfDay(zoneId)
+				.toInstant();
+		long weeklySeconds = eligible(records).stream()
+				.mapToLong(record -> overlapSeconds(record, weekStart, now))
+				.sum();
+		List<ProfileOverviewResponse.DailyPractice> dailyPractice =
+				java.util.stream.IntStream.rangeClosed(0, 6)
+						.mapToObj(offset -> today.minusDays(6L - offset))
+						.map(date -> new ProfileOverviewResponse.DailyPractice(
+								date,
+								practiceSecondsForDate(records, date, zoneId, now)))
+						.toList();
+		return new ProfileOverviewResponse.PracticeStatistics(
+				weeklySeconds,
+				trainingRecordCount,
+				consecutiveLearningDays,
+				dailyPractice);
+	}
+
+	private long practiceSecondsForDate(
+			List<PracticeSessionRecord> records,
+			LocalDate date,
+			ZoneId zoneId,
+			Instant now) {
+		Instant start = date.atStartOfDay(zoneId).toInstant();
+		Instant nextDay = date.plusDays(1).atStartOfDay(zoneId).toInstant();
+		Instant end = nextDay.isBefore(now) ? nextDay : now;
+		if (!end.isAfter(start)) {
+			return 0;
+		}
+		return eligible(records).stream()
+				.mapToLong(record -> overlapSeconds(record, start, end))
+				.sum();
+	}
+
+	private List<PracticeSessionRecord> eligible(
+			List<PracticeSessionRecord> records) {
+		if (records == null || records.isEmpty()) {
+			return List.of();
+		}
+		return records.stream()
+				.filter(record -> record.startedAt() != null && record.endedAt() != null)
+				.filter(record -> !record.endedAt().isBefore(record.startedAt()))
+				.filter(record -> Duration.between(
+						record.startedAt(), record.endedAt()).getSeconds()
+						>= MINIMUM_PRACTICE_SECONDS)
+				.toList();
+	}
+
+	private long overlapSeconds(
+			PracticeSessionRecord record,
+			Instant rangeStart,
+			Instant rangeEnd) {
+		Instant start = record.startedAt().isAfter(rangeStart)
+				? record.startedAt()
+				: rangeStart;
+		Instant end = record.endedAt().isBefore(rangeEnd)
+				? record.endedAt()
+				: rangeEnd;
+		return end.isAfter(start) ? Duration.between(start, end).getSeconds() : 0;
+	}
+}
+
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImpl.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImpl.java
index 53e1fef..f349d04 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImpl.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImpl.java
@@ -7,17 +7,24 @@
 import com.unispeaking.infrastructure.config.ProfileProperties;
 import com.unispeaking.infrastructure.persistence.repository.evaluation.SessionEvaluationRepository;
 import com.unispeaking.infrastructure.persistence.repository.scene.SceneRepository;
+import com.unispeaking.infrastructure.persistence.repository.session.PracticeSessionRepository;
 import com.unispeaking.infrastructure.persistence.repository.user.UserAccountRepository;
 import com.unispeaking.infrastructure.storage.ObjectStorageProvider;
 import com.unispeaking.service.profile.ProfileOverviewService;
+import com.unispeaking.service.profile.PracticeDurationCalculator;
 import java.net.URI;
+import java.time.Clock;
 import java.time.Instant;
 import java.time.LocalDate;
+import java.time.OffsetDateTime;
 import java.time.YearMonth;
 import java.time.ZoneId;
 import java.time.ZoneOffset;
 import java.time.format.DateTimeParseException;
+import java.time.temporal.TemporalAdjusters;
+import java.util.HashSet;
 import java.util.List;
+import java.util.Set;
 import java.util.UUID;
 import org.springframework.stereotype.Service;
 
@@ -26,23 +33,50 @@ public class ProfileOverviewServiceImpl implements ProfileOverviewService {
 	private final UserAccountRepository accounts;
 	private final SceneRepository scenes;
 	private final SessionEvaluationRepository evaluations;
+	private final PracticeSessionRepository practiceSessions;
 	private final ObjectStorageProvider storage;
 	private final ObjectStorageProperties storageProperties;
 	private final ZoneId zoneId;
+	private final Clock clock;
+	private final PracticeDurationCalculator durationCalculator;
 
 	public ProfileOverviewServiceImpl(
 			UserAccountRepository accounts,
 			SceneRepository scenes,
 			SessionEvaluationRepository evaluations,
+			PracticeSessionRepository practiceSessions,
 			ObjectStorageProvider storage,
 			ObjectStorageProperties storageProperties,
 			ProfileProperties profileProperties) {
+		this(
+				accounts,
+				scenes,
+				evaluations,
+				practiceSessions,
+				storage,
+				storageProperties,
+				profileProperties.zoneId(),
+				Clock.system(profileProperties.zoneId()));
+	}
+
+	ProfileOverviewServiceImpl(
+			UserAccountRepository accounts,
+			SceneRepository scenes,
+			SessionEvaluationRepository evaluations,
+			PracticeSessionRepository practiceSessions,
+			ObjectStorageProvider storage,
+			ObjectStorageProperties storageProperties,
+			ZoneId zoneId,
+			Clock clock) {
 		this.accounts = accounts;
 		this.scenes = scenes;
 		this.evaluations = evaluations;
+		this.practiceSessions = practiceSessions;
 		this.storage = storage;
 		this.storageProperties = storageProperties;
-		this.zoneId = profileProperties.zoneId();
+		this.zoneId = zoneId;
+		this.clock = clock;
+		this.durationCalculator = new PracticeDurationCalculator();
 	}
 
 	@Override
@@ -50,15 +84,18 @@ public ProfileOverviewResponse getOverview(String userId, String requestedMonth)
 		UUID id = UUID.fromString(userId);
 		UserAccount user = accounts.findById(id)
 				.orElseThrow(() -> new BusinessException("USER_NOT_FOUND", "用户不存在"));
-		YearMonth current = YearMonth.now(zoneId);
+		Instant now = clock.instant();
+		LocalDate today = now.atZone(zoneId).toLocalDate();
+		YearMonth current = YearMonth.from(today);
 		YearMonth month = parseMonth(requestedMonth, current);
 		if (month.isAfter(current)) {
 			throw new BusinessException("PROFILE_MONTH_INVALID", "不能查看未来月份");
 		}
 		Instant start = month.atDay(1).atStartOfDay(zoneId).toInstant();
 		Instant end = month.plusMonths(1).atDay(1).atStartOfDay(zoneId).toInstant();
+		List<String> sceneIds = scenes.findAllIdsByUserId(userId);
 		List<LocalDate> dates = evaluations.findCreatedAtBySceneIdsBetween(
-						scenes.findAllIdsByUserId(userId),
+						sceneIds,
 						start.atOffset(ZoneOffset.UTC),
 						end.atOffset(ZoneOffset.UTC))
 				.stream()
@@ -68,12 +105,53 @@ public ProfileOverviewResponse getOverview(String userId, String requestedMonth)
 				.toList();
 		SignedAvatar signed = signAvatar(user.avatarObjectKey());
 		String displayName = displayName(user);
+		LocalDate sevenDayStart = today.minusDays(6);
+		LocalDate weekStart = today.with(
+				TemporalAdjusters.previousOrSame(java.time.DayOfWeek.MONDAY));
+		Instant statisticsStart = (sevenDayStart.isBefore(weekStart)
+				? sevenDayStart
+				: weekStart).atStartOfDay(zoneId).toInstant();
+		int consecutiveLearningDays = consecutiveLearningDays(
+				evaluations.findCreatedAtBySceneIdsBetween(
+						sceneIds,
+						Instant.EPOCH.atOffset(ZoneOffset.UTC),
+						today.plusDays(1).atStartOfDay(zoneId)
+								.toInstant().atOffset(ZoneOffset.UTC)),
+				today);
+		ProfileOverviewResponse.PracticeStatistics statistics =
+				durationCalculator.calculate(
+						practiceSessions.findCompletedOverlapping(
+								id, statisticsStart, now),
+						today,
+						now,
+						zoneId,
+						scenes.countActiveByUserId(userId),
+						consecutiveLearningDays);
 		return new ProfileOverviewResponse(
 				new ProfileOverviewResponse.Account(
 						user.id(), user.username(), user.nickname(), displayName,
 						signed.url(), signed.expiresAt()),
+				statistics,
 				new ProfileOverviewResponse.Calendar(
-						month.toString(), dates, dates.contains(LocalDate.now(zoneId))));
+						month.toString(), dates, dates.contains(today)));
+	}
+
+	private int consecutiveLearningDays(
+			List<OffsetDateTime> reportTimes,
+			LocalDate today) {
+		Set<LocalDate> checkedDates = new HashSet<>();
+		for (OffsetDateTime reportTime : reportTimes) {
+			checkedDates.add(reportTime.toInstant().atZone(zoneId).toLocalDate());
+		}
+		LocalDate cursor = checkedDates.contains(today)
+				? today
+				: today.minusDays(1);
+		int days = 0;
+		while (checkedDates.contains(cursor)) {
+			days++;
+			cursor = cursor.minusDays(1);
+		}
+		return days;
 	}
 
 	private YearMonth parseMonth(String value, YearMonth current) {
@@ -94,7 +172,7 @@ private SignedAvatar signAvatar(String objectKey) {
 			URI uri = storage.signGetUrl(objectKey, storageProperties.getSignedUrlTtl());
 			return new SignedAvatar(
 					uri.toString(),
-					Instant.now().plus(storageProperties.getSignedUrlTtl()));
+					clock.instant().plus(storageProperties.getSignedUrlTtl()));
 		}
 		catch (BusinessException exception) {
 			return new SignedAvatar(null, null);
diff --git a/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/scene/MybatisSceneRepositoryTest.java b/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/scene/MybatisSceneRepositoryTest.java
index b624f34..0868a46 100644
--- a/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/scene/MybatisSceneRepositoryTest.java
+++ b/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/scene/MybatisSceneRepositoryTest.java
@@ -7,6 +7,7 @@
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.times;
 import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
 
 import com.unispeaking.domain.dto.scene.LearningContentItem;
 import com.unispeaking.domain.dto.scene.SceneGenerationResponse;
@@ -88,6 +89,24 @@ void persistsSceneAndAllGeneratedLearningContent() {
 						&& value.getSentenceId().startsWith("sentence_")));
 	}
 
+	@Test
+	void countsOnlyActiveTrainingRecords() {
+		SceneMapper sceneMapper = mock(SceneMapper.class);
+		when(sceneMapper.selectCount(any())).thenReturn(3L);
+		var repository = new MybatisSceneRepository(
+				sceneMapper,
+				mock(SceneWordMapper.class),
+				mock(ScenePhraseMapper.class),
+				mock(SceneSentenceMapper.class),
+				mock(CustomScenePersistence.class));
+
+		long count = repository.countActiveByUserId(
+				"11111111-1111-4111-8111-111111111111");
+
+		assertEquals(3, count);
+		verify(sceneMapper).selectCount(any());
+	}
+
 	private Fixture fixture() {
 		String sceneId = "custom_abc123";
 		List<LearningContentItem> words = items("word", 5);
diff --git a/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/PracticeDurationCalculatorTest.java b/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/PracticeDurationCalculatorTest.java
new file mode 100644
index 0000000..3ff770f
--- /dev/null
+++ b/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/PracticeDurationCalculatorTest.java
@@ -0,0 +1,61 @@
+package com.unispeaking.service.profile;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import com.unispeaking.domain.po.session.PracticeSessionRecord;
+import com.unispeaking.domain.vo.scene.SceneType;
+import com.unispeaking.domain.vo.session.SessionStatus;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.ZoneId;
+import java.util.List;
+import java.util.UUID;
+import org.junit.jupiter.api.Test;
+
+class PracticeDurationCalculatorTest {
+
+	private static final ZoneId ZONE_ID = ZoneId.of("Asia/Shanghai");
+	private final PracticeDurationCalculator calculator =
+			new PracticeDurationCalculator();
+
+	@Test
+	void excludesSessionsShorterThanThreeMinutes() {
+		var result = calculate(List.of(
+				record("2026-08-03T01:00:00Z", "2026-08-03T01:02:59Z"),
+				record("2026-08-03T02:00:00Z", "2026-08-03T02:03:00Z")));
+
+		assertEquals(180, result.weeklyPracticeSeconds());
+		assertEquals(180, result.lastSevenDays().getLast().practiceSeconds());
+	}
+
+	@Test
+	void splitsEligibleSessionAcrossLocalCalendarDays() {
+		var result = calculate(List.of(
+				record("2026-08-02T15:58:00Z", "2026-08-02T16:03:00Z")));
+
+		assertEquals(120, result.lastSevenDays().get(5).practiceSeconds());
+		assertEquals(180, result.lastSevenDays().get(6).practiceSeconds());
+	}
+
+	private com.unispeaking.domain.dto.profile.ProfileOverviewResponse
+			.PracticeStatistics calculate(List<PracticeSessionRecord> records) {
+		return calculator.calculate(
+				records,
+				LocalDate.of(2026, 8, 3),
+				Instant.parse("2026-08-03T12:00:00Z"),
+				ZONE_ID,
+				4,
+				2);
+	}
+
+	private PracticeSessionRecord record(String start, String end) {
+		return new PracticeSessionRecord(
+				"freechat_" + start,
+				UUID.randomUUID(),
+				"freechat_scene",
+				SceneType.FREE_CHAT,
+				SessionStatus.COMPLETED,
+				Instant.parse(start),
+				Instant.parse(end));
+	}
+}
diff --git a/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImplTest.java b/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImplTest.java
new file mode 100644
index 0000000..a13738f
--- /dev/null
+++ b/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImplTest.java
@@ -0,0 +1,92 @@
+package com.unispeaking.service.profile.impl;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import com.unispeaking.domain.po.auth.UserAccount;
+import com.unispeaking.domain.po.auth.UserRole;
+import com.unispeaking.domain.po.auth.UserStatus;
+import com.unispeaking.domain.po.session.PracticeSessionRecord;
+import com.unispeaking.domain.vo.scene.SceneType;
+import com.unispeaking.domain.vo.session.SessionStatus;
+import com.unispeaking.infrastructure.config.ObjectStorageProperties;
+import com.unispeaking.infrastructure.persistence.repository.evaluation.SessionEvaluationRepository;
+import com.unispeaking.infrastructure.persistence.repository.scene.SceneRepository;
+import com.unispeaking.infrastructure.persistence.repository.session.PracticeSessionRepository;
+import com.unispeaking.infrastructure.persistence.repository.user.UserAccountRepository;
+import com.unispeaking.infrastructure.storage.ObjectStorageProvider;
+import java.time.Clock;
+import java.time.Instant;
+import java.time.OffsetDateTime;
+import java.time.ZoneId;
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+import org.junit.jupiter.api.Test;
+
+class ProfileOverviewServiceImplTest {
+
+	@Test
+	void returnsRealPracticeAssetsAndCheckInStreak() {
+		ZoneId zoneId = ZoneId.of("Asia/Shanghai");
+		Instant now = Instant.parse("2026-08-03T12:00:00Z");
+		UUID userId = UUID.randomUUID();
+		UserAccountRepository accounts = mock(UserAccountRepository.class);
+		SceneRepository scenes = mock(SceneRepository.class);
+		SessionEvaluationRepository evaluations =
+				mock(SessionEvaluationRepository.class);
+		PracticeSessionRepository practiceSessions =
+				mock(PracticeSessionRepository.class);
+		ObjectStorageProvider storage = mock(ObjectStorageProvider.class);
+		when(accounts.findById(userId)).thenReturn(Optional.of(new UserAccount(
+				userId,
+				"learner@example.com",
+				"hash",
+				"学习者",
+				UserRole.USER,
+				UserStatus.ACTIVE,
+				0,
+				null,
+				now,
+				now)));
+		when(scenes.findAllIdsByUserId(userId.toString()))
+				.thenReturn(List.of("custom_scene1"));
+		when(scenes.countActiveByUserId(userId.toString())).thenReturn(4L);
+		List<OffsetDateTime> reports = List.of(
+				OffsetDateTime.parse("2026-08-03T02:00:00Z"),
+				OffsetDateTime.parse("2026-08-02T02:00:00Z"),
+				OffsetDateTime.parse("2026-08-01T02:00:00Z"));
+		when(evaluations.findCreatedAtBySceneIdsBetween(any(), any(), any()))
+				.thenReturn(reports, reports);
+		when(practiceSessions.findCompletedOverlapping(any(), any(), any()))
+				.thenReturn(List.of(new PracticeSessionRecord(
+						"custom_session1",
+						userId,
+						"custom_scene1",
+						SceneType.CUSTOM_SCENE,
+						SessionStatus.COMPLETED,
+						Instant.parse("2026-08-03T01:00:00Z"),
+						Instant.parse("2026-08-03T01:05:00Z"))));
+		when(storage.available()).thenReturn(false);
+		ProfileOverviewServiceImpl service = new ProfileOverviewServiceImpl(
+				accounts,
+				scenes,
+				evaluations,
+				practiceSessions,
+				storage,
+				new ObjectStorageProperties(),
+				zoneId,
+				Clock.fixed(now, zoneId));
+
+		var overview = service.getOverview(userId.toString(), "2026-08");
+
+		assertEquals(300, overview.statistics().weeklyPracticeSeconds());
+		assertEquals(4, overview.statistics().trainingRecordCount());
+		assertEquals(3, overview.statistics().consecutiveLearningDays());
+		assertEquals(7, overview.statistics().lastSevenDays().size());
+		assertEquals(300,
+				overview.statistics().lastSevenDays().getLast().practiceSeconds());
+	}
+}

From 377ef8de4ba93f77f8f8d225f06e412e2447888e Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Mon, 3 Aug 2026 15:07:00 +0800
Subject: [PATCH 55/62] =?UTF-8?q?feat:=20=E4=BC=98=E5=8C=96=E5=A4=B4?=
 =?UTF-8?q?=E5=83=8F=E7=BC=96=E8=BE=91=E5=85=A5=E5=8F=A3=E5=92=8C=E7=BB=9F?=
 =?UTF-8?q?=E8=AE=A1=E5=B1=95=E7=A4=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend/Unispeaking_fronted/src/App.jsx    | 11 ++++++++---
 frontend/Unispeaking_fronted/src/styles.css | 21 ++++++++++++++-------
 2 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/frontend/Unispeaking_fronted/src/App.jsx b/frontend/Unispeaking_fronted/src/App.jsx
index 847d903..93f1c73 100644
--- a/frontend/Unispeaking_fronted/src/App.jsx
+++ b/frontend/Unispeaking_fronted/src/App.jsx
@@ -2131,7 +2131,7 @@ function Profile({ section, setSection, user, profile, teacher, speed, level, on
   const avatarUrl = account?.avatarUrl || teacher.image;
   const [profileEditOpen, setProfileEditOpen] = useState(false);
   return (
-    <main className="profile-layout"><aside className="profile-nav"><div className="profile-user"><img src={avatarUrl} alt={displayName} /><span><strong>{displayName}</strong><small>{email}</small></span><button type="button" className="profile-user__edit" onClick={() => setProfileEditOpen(true)}><PencilSimple />编辑</button></div><nav><button className={section === "profile" ? "is-active" : ""} onClick={() => setSection("profile")}><User />个人概览</button><button className={section === "membership" ? "is-active" : ""} onClick={() => setSection("membership")}><Crown />会员权益</button><button className={section === "settings" ? "is-active" : ""} onClick={() => setSection("settings")}><SlidersHorizontal />助手设置</button></nav><button className="logout" onClick={onLogout}><SignOut />退出登录</button></aside><section className="profile-content">{section === "profile" && <Overview calendar={profile?.calendar} onMonthChange={onMonthChange} />}{section === "membership" && <Membership />}{section === "settings" && <Settings teacher={teacher} speed={speed} level={level} onSettingsChange={onSettingsChange} onPasswordChange={onPasswordChange} />}</section>{profileEditOpen && <ProfileEditModal account={account} user={user} avatarUrl={avatarUrl} onClose={() => setProfileEditOpen(false)} onNicknameChange={onNicknameChange} onAvatarChange={onAvatarChange} />}</main>
+    <main className="profile-layout"><aside className="profile-nav"><div className="profile-user"><div className="profile-user__avatar"><img src={avatarUrl} alt={displayName} /><button type="button" className="profile-user__edit" aria-label="编辑用户名和头像" title="编辑用户名和头像" onClick={() => setProfileEditOpen(true)}><PencilSimple weight="bold" /></button></div><span><strong>{displayName}</strong><small>{email}</small></span></div><nav><button className={section === "profile" ? "is-active" : ""} onClick={() => setSection("profile")}><User />个人概览</button><button className={section === "membership" ? "is-active" : ""} onClick={() => setSection("membership")}><Crown />会员权益</button><button className={section === "settings" ? "is-active" : ""} onClick={() => setSection("settings")}><SlidersHorizontal />助手设置</button></nav><button className="logout" onClick={onLogout}><SignOut />退出登录</button></aside><section className="profile-content">{section === "profile" && <Overview calendar={profile?.calendar} statistics={profile?.statistics} onMonthChange={onMonthChange} />}{section === "membership" && <Membership />}{section === "settings" && <Settings teacher={teacher} speed={speed} level={level} onSettingsChange={onSettingsChange} onPasswordChange={onPasswordChange} />}</section>{profileEditOpen && <ProfileEditModal account={account} user={user} avatarUrl={avatarUrl} onClose={() => setProfileEditOpen(false)} onNicknameChange={onNicknameChange} onAvatarChange={onAvatarChange} />}</main>
   );
 }
 
@@ -2224,8 +2224,13 @@ function AchievementSystem() {
   );
 }
 
-function Overview({ calendar, onMonthChange }) {
-  return <><PageHeader eyebrow="PERSONAL OVERVIEW" title="你的学习空间" subtitle="把每一次开口变成看得见、可继续的成长记录。" action={calendar?.checkedInToday ? <span className="today-checkin"><CalendarCheck2 />今日已打卡</span> : null} /><div className="stat-grid"><article><Clock /><span><small>本周学习时长</small><strong>183 <em>分钟</em></strong></span></article><article><BookOpenText /><span><small>已保存学习资产</small><strong>12 <em>项</em></strong></span></article><article><Fire /><span><small>连续学习天数</small><strong>7 <em>天</em></strong></span></article></div><section className="overview-grid"><LearningCalendar calendar={calendar} onMonthChange={onMonthChange} /><article className="rhythm-card"><p className="eyebrow">LAST SEVEN DAYS</p><h2>练习节奏</h2><div className="bars">{[38, 62, 78, 26, 92, 70, 48].map((height, index) => <span key={index} style={{ height: `${height}%` }}><small>{[18, 26, 34, 12, 40, 31, 22][index]}m</small></span>)}</div></article></section><AchievementSystem /></>;
+function Overview({ calendar, statistics, onMonthChange }) {
+  const weeklyMinutes = Math.floor((statistics?.weeklyPracticeSeconds || 0) / 60);
+  const trainingRecordCount = statistics?.trainingRecordCount || 0;
+  const consecutiveLearningDays = statistics?.consecutiveLearningDays || 0;
+  const days = statistics?.lastSevenDays || [];
+  const maximumSeconds = Math.max(0, ...days.map((day) => day.practiceSeconds || 0));
+  return <><PageHeader eyebrow="PERSONAL OVERVIEW" title="你的学习空间" subtitle="把每一次开口变成看得见、可继续的成长记录。" action={calendar?.checkedInToday ? <span className="today-checkin"><CalendarCheck2 />今日已打卡</span> : null} /><div className="stat-grid"><article><Clock /><span><small>本周学习时长</small><strong>{weeklyMinutes} <em>分钟</em></strong></span></article><article><BookOpenText /><span><small>已保存学习资产</small><strong>{trainingRecordCount} <em>项</em></strong></span></article><article><Fire /><span><small>连续学习天数</small><strong>{consecutiveLearningDays} <em>天</em></strong></span></article></div><section className="overview-grid"><LearningCalendar calendar={calendar} onMonthChange={onMonthChange} /><article className="rhythm-card"><p className="eyebrow">LAST SEVEN DAYS</p><h2>练习节奏</h2><div className={cx("bars", !days.length && "is-empty")}>{days.length ? days.map((day) => { const seconds = day.practiceSeconds || 0; const minutes = Math.floor(seconds / 60); const height = maximumSeconds ? Math.max(3, (seconds / maximumSeconds) * 100) : 3; const weekday = new Date(`${day.date}T00:00:00+08:00`).toLocaleDateString("zh-CN", { weekday: "short", timeZone: "Asia/Shanghai" }); return <span key={day.date} className={seconds ? "" : "is-zero"} style={{ height: `${height}%` }} aria-label={`${day.date}，练习 ${minutes} 分钟`} title={`${day.date} · ${minutes} 分钟`}><small>{minutes}m</small><em>{weekday}</em></span>; }) : <p>完成一次至少 3 分钟的练习后，这里会显示你的节奏。</p>}</div></article></section><AchievementSystem /></>;
 }
 
 function Membership() {
diff --git a/frontend/Unispeaking_fronted/src/styles.css b/frontend/Unispeaking_fronted/src/styles.css
index 2d51641..a64f5e1 100644
--- a/frontend/Unispeaking_fronted/src/styles.css
+++ b/frontend/Unispeaking_fronted/src/styles.css
@@ -811,15 +811,18 @@ svg { display: block; }
 }
 
 .app-main:has(.profile-layout) { overflow: hidden; }
-.profile-layout { height: 100%; min-height: 0; display: grid; grid-template-columns: 250px minmax(0, 1fr); }
+.profile-layout { height: 100%; min-height: 0; display: grid; grid-template-columns: 280px minmax(0, 1fr); }
 .profile-nav { min-height: 0; height: 100%; border-right: 1px solid var(--line); padding: 38px 22px 28px; display: flex; flex-direction: column; background: #fff; }
-.profile-user { position: relative; min-height: 94px; display: flex; align-items: flex-start; gap: 12px; padding: 0 6px 42px 10px; }
-.profile-user > img { flex: 0 0 auto; width: 48px; height: 48px; border-radius: 14px; object-fit: cover; object-position: center; }
-.profile-user > span { min-width: 0; flex: 1; padding-top: 2px; }
+.profile-user { min-height: 112px; display: flex; align-items: center; gap: 17px; padding: 0 7px 30px 10px; }
+.profile-user__avatar { position: relative; flex: 0 0 72px; width: 72px; height: 72px; }
+.profile-user__avatar > img { width: 72px; height: 72px; border-radius: 50%; object-fit: cover; object-position: center; background: var(--soft); }
+.profile-user > span { min-width: 0; flex: 1; }
 .profile-user strong, .profile-user small { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.profile-user small { color: var(--muted); margin-top: 5px; font-size: 10px; }
-.profile-user__edit { position: absolute; right: 6px; bottom: 8px; display: inline-flex; align-items: center; gap: 3px; padding: 6px; border: 0; border-radius: 8px; background: transparent; color: #777772; font-size: 10px; cursor: pointer; }
-.profile-user__edit:hover { background: var(--soft-2); color: var(--ink); }
+.profile-user strong { font-size: 18px; line-height: 1.25; }
+.profile-user small { color: var(--muted); margin-top: 7px; font-size: 11px; }
+.profile-user__edit { position: absolute; top: -3px; right: -3px; width: 28px; height: 28px; display: grid; place-items: center; padding: 0; border: 3px solid #fff; border-radius: 50%; background: #252524; color: #fff; box-shadow: 0 4px 12px rgba(20,20,19,.18); cursor: pointer; transition: transform .2s, background .2s; }
+.profile-user__edit:hover { background: #565652; transform: scale(1.08); }
+.profile-user__edit:focus-visible { outline: 2px solid #252524; outline-offset: 2px; }
 .profile-user__edit svg { width: 13px; height: 13px; }
 .profile-nav nav { display: grid; gap: 7px; }
 .profile-nav nav button, .logout { height: 46px; padding: 0 13px; border: 0; border-radius: 10px; background: #fff; display: flex; align-items: center; gap: 10px; cursor: pointer; }
@@ -867,7 +870,11 @@ svg { display: block; }
 .bars { flex: 1; min-height: 270px; display: flex; align-items: end; justify-content: space-around; gap: 12px; padding: 48px 4px 34px; }
 .bars > span { width: 24px; min-height: 12px; background: linear-gradient(180deg, #686863 0%, #d6d6d0 100%); border-radius: 7px 7px 2px 2px; position: relative; transition: filter .2s, transform .2s; }
 .bars > span:hover { filter: brightness(.88) contrast(1.04); transform: scaleX(1.08); }
+.bars > span.is-zero { background: #e5e5e0; }
 .bars small { position: absolute; bottom: -25px; left: 50%; transform: translateX(-50%); color: #666662; font-size: 9px; }
+.bars em { position: absolute; bottom: -42px; left: 50%; transform: translateX(-50%); color: #aaa9a5; font-size: 8px; font-style: normal; white-space: nowrap; }
+.bars.is-empty { align-items: center; justify-content: center; }
+.bars.is-empty > p { max-width: 210px; margin: 0; color: var(--muted); font-size: 11px; line-height: 1.7; text-align: center; }
 .achievement-system { margin-top: 18px; padding: 28px; border: 1px solid var(--line); border-radius: 18px; }
 .achievement-system__header { display: flex; justify-content: space-between; align-items: flex-end; gap: 28px; }
 .achievement-system__header .eyebrow { margin: 0 0 7px; }

From 3cb2ed1079c333f47dda6636bf25614667e88472 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Mon, 3 Aug 2026 15:10:41 +0800
Subject: [PATCH 56/62] =?UTF-8?q?feat:=20=E4=BF=AE=E5=A4=8D=E4=B8=AA?=
 =?UTF-8?q?=E4=BA=BA=E4=B8=BB=E9=A1=B5=E7=BB=9F=E8=AE=A1=E6=9C=8D=E5=8A=A1?=
 =?UTF-8?q?=E6=9E=84=E9=80=A0=E6=B3=A8=E5=85=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../service/profile/impl/ProfileOverviewServiceImpl.java        | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImpl.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImpl.java
index f349d04..2184a3b 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImpl.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/impl/ProfileOverviewServiceImpl.java
@@ -26,6 +26,7 @@
 import java.util.List;
 import java.util.Set;
 import java.util.UUID;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Service;
 
 @Service
@@ -40,6 +41,7 @@ public class ProfileOverviewServiceImpl implements ProfileOverviewService {
 	private final Clock clock;
 	private final PracticeDurationCalculator durationCalculator;
 
+	@Autowired
 	public ProfileOverviewServiceImpl(
 			UserAccountRepository accounts,
 			SceneRepository scenes,

From dfe7bf347147ea8538990ad3c93894aa596a8218 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Mon, 3 Aug 2026 15:12:46 +0800
Subject: [PATCH 57/62] =?UTF-8?q?feat:=20=E6=9B=B4=E6=96=B0=E4=B8=AA?=
 =?UTF-8?q?=E4=BA=BA=E4=B8=BB=E9=A1=B5=E7=9C=9F=E5=AE=9E=E7=BB=9F=E8=AE=A1?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/deployment.md                            | 22 ++++-
 docs/frontend-backend-interface-contract.md   | 32 ++++++-
 ...36\346\226\275\350\256\241\345\210\222.md" | 33 ++++++-
 ...00\345\217\221\350\256\276\350\256\241.md" | 87 ++++++++++++++-----
 4 files changed, 140 insertions(+), 34 deletions(-)

diff --git a/docs/deployment.md b/docs/deployment.md
index f966a0a..f78078c 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -44,10 +44,24 @@ Before deploying the profile feature to an existing database, apply:
 psql "$DATABASE_URL" -f deploy/postgres/profile.sql
 ```
 
-The migration adds only `user.avatar_object_key`; check-in dates continue to be
-derived from persisted `session_evaluation` reports, so no check-in table and no
-Redis data structure are required. New databases receive the same definition
-from `backend/unispeaking-server/src/main/resources/db/schema.sql`.
+The migration adds `user.avatar_object_key` and the `practice_session` session
+fact table. Check-in dates continue to be derived from persisted
+`session_evaluation` reports, so no check-in table and no Redis data structure
+are required. Learning duration is calculated from completed practice sessions;
+sessions shorter than 180 seconds are excluded at query time. New databases use
+the Flyway migrations in
+`backend/unispeaking-server/src/main/resources/db/migration`.
+
+Spring Boot runs `V2__practice_session.sql` automatically on startup. For an
+existing environment, either let Flyway apply V2 or run `profile.sql` manually;
+do not run both concurrently. Verify the migration with:
+
+```sql
+SELECT column_name, data_type
+FROM information_schema.columns
+WHERE table_name = 'practice_session'
+ORDER BY ordinal_position;
+```
 
 ## Available settings
 
diff --git a/docs/frontend-backend-interface-contract.md b/docs/frontend-backend-interface-contract.md
index 1010612..bef6d05 100644
--- a/docs/frontend-backend-interface-contract.md
+++ b/docs/frontend-backend-interface-contract.md
@@ -13,7 +13,7 @@ GET /api/profile/overview?month=2026-07
 Authorization: Bearer <accessToken>
 ```
 
-`month` 可省略，格式为 `yyyy-MM`，省略时按 `Asia/Shanghai` 返回当前月；未来月份不允许查询。日历的打卡依据是该用户场景下已经持久化的五维评分报告，同一天多份报告只返回一个日期。
+`month` 可省略，格式为 `yyyy-MM`，省略时按 `Asia/Shanghai` 返回当前月；未来月份不允许查询。日历的打卡依据是该用户场景下已经持久化的五维评分报告，同一天多份报告只返回一个日期。学习时长来自所有场景共用的 `practice_session`，不依赖是否生成评分报告。
 
 ```json
 {
@@ -25,6 +25,16 @@ Authorization: Bearer <accessToken>
     "avatarUrl": "https://signed-oss-url.example/avatar.jpg",
     "avatarUrlExpiresAt": "2026-07-31T08:00:00Z"
   },
+  "statistics": {
+    "weeklyPracticeSeconds": 10980,
+    "trainingRecordCount": 12,
+    "consecutiveLearningDays": 7,
+    "lastSevenDays": [
+      {"date": "2026-07-25", "practiceSeconds": 1080},
+      {"date": "2026-07-26", "practiceSeconds": 1560},
+      {"date": "2026-07-27", "practiceSeconds": 0}
+    ]
+  },
   "calendar": {
     "month": "2026-07",
     "checkedDates": ["2026-07-02", "2026-07-15"],
@@ -35,6 +45,15 @@ Authorization: Bearer <accessToken>
 
 `avatarUrl` 是短期签名地址，未上传头像或对象存储暂不可用时为 `null`。
 
+统计口径：
+
+- `weeklyPracticeSeconds`：本周一 00:00 至当前时刻的有效学习秒数。
+- `trainingRecordCount`：未软删除训练记录条数，同一记录复练多次仍计为一项。
+- `consecutiveLearningDays`：由五维报告自动打卡日期计算；当天未打卡时从昨天向前计算。
+- `lastSevenDays`：今天及之前六个上海自然日的有效学习秒数，按日期升序返回。
+- 单次完整会话不足 180 秒时不计入任何时长；达到 180 秒时全部计入。
+- 有效会话跨越上海零点时，时长按每个自然日实际覆盖区间拆分。
+
 ### 修改用户名（昵称）
 
 ```text
@@ -342,7 +361,9 @@ Profile 和偏好，固定以 `FREE_CHAT` 调用 `SceneService` 和
 `systemPrompt` 是后端在 `SceneService.generateScene(...)` 中完成权限校验、
 用户 Profile 注入和用户偏好注入后的完整五层提示词。前端必须将它放入
 DataChannel `session.update.session.instructions`，不得使用客户端默认提示词替代。
-`SessionService.startSession(prompt)` 只创建业务会话并记录开始时间。
+`SessionService.startSession(sceneType, sceneId, prompt)` 创建业务会话，同时在
+`practice_session` 中保存服务器开始时间。自由对话和自定义场景已经接入该统一入口；
+雅思、面试及后续场景接入时必须复用同一生命周期。
 `RealtimeSessionConnector` 使用 `offerSdp/model/voice` 调用
 `RealtimeConnectionService`，内部申请短期凭证并交换 Answer SDP。`systemPrompt`
 就是 `SceneService` 生成的 `scenePrompt`，启动响应只保留这一个提示词字段。
@@ -431,8 +452,11 @@ HTTP `POST /api/scene-sessions/{sessionId}/end` 目前保留，方便调试和
 后端行为：
 
 1. 会话状态变为 `COMPLETED`。
-2. 结算用量。
-3. 保留本次完整消息；不更新用户长期 `memory_text`。
+2. 后端使用服务器当前时间更新 `practice_session.ended_at`；请求中的 `stopTime`
+   只为旧客户端兼容，不作为学习时长依据。
+3. 单次会话完整时长达到 180 秒后，才会进入个人主页学习时长与七日节奏统计。
+4. 自由对话不保存消息正文；自定义场景保留本次完整消息；两者都不更新用户长期
+   `memory_text`。
 
 ## 6. 自定义场景接口
 
diff --git "a/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md" "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md"
index d92a828..e397fae 100644
--- "a/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md"
+++ "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md"
@@ -4,7 +4,7 @@
 
 > 下列任务末尾保留的“单文件 commit”是初版计划的历史拆分标记；实际提交粒度以本页最新执行要求和用户后续确认为准。
 
-**目标：** 实现动态报告打卡日历、展示昵称修改、七牛云 Kodo 用户头像和全端 JWT 失效的密码修改功能。
+**目标：** 实现动态报告打卡日历、展示昵称修改、七牛云 Kodo 用户头像、全端 JWT 失效的密码修改，以及全场景真实学习时长统计。
 
 **架构：** 完整设计以 `docs/个人主页账户资料与自动打卡开发设计.md` 为准。Profile 读取、Profile 写入、Auth 和对象存储基础设施保持独立；打卡只读取现有 `session_evaluation`，不增加打卡写模型、Redis 或评分表字段。
 
@@ -19,13 +19,13 @@
 - Java 中不写原始 SQL，不使用 SQL 注解、Mapper XML 或被禁止的 Wrapper 方法。
 - 用户身份只来自 JWT。
 - 不读取、修改或提交 `deploy/env/.env`。
-- 不新增打卡表、Redis、MQ 或评分表字段。
+- 不新增打卡表、Redis、MQ 或评分表字段；允许新增已确认的 `practice_session` 会话事实表。
 
 ---
 
 ### Task 1：数据库与依赖
 
-- [ ] 修改 `backend/unispeaking-server/src/main/resources/db/schema.sql`：只给 `"user"` 增加 `avatar_object_key VARCHAR(512)`、非空白约束和注释；运行 `./mvnw -q -DskipTests compile`；单文件 commit。
+- [x] 修改 `backend/unispeaking-server/src/main/resources/db/migration/V1__baseline.sql`：给 `"user"` 增加 `avatar_object_key VARCHAR(512)`、非空白约束和注释。
 - [ ] 新建 `deploy/postgres/profile.sql`：用 `BEGIN/COMMIT` 包装同一幂等迁移；单文件 commit。
 - [ ] 修改 `backend/unispeaking-server/pom.xml`：增加 `qiniu-java-sdk.version=7.19.0` 和 `com.qiniu:qiniu-java-sdk`；运行 `./mvnw -q -DskipTests compile`；单文件 commit。
 - [ ] 修改 `backend/unispeaking-server/src/main/resources/application.yaml`：增加 `profile.time-zone` 与 `object-storage.qiniu`；单文件 commit。
@@ -99,3 +99,30 @@
 - [ ] 运行 `npm run check:routes`，期望 32 assertions passed。
 - [ ] 运行 `npm run check:realtime-events`，期望通过。
 - [ ] 运行 `./mvnw dependency:tree`，确认没有第二套 ORM/JSON/HTTP 技术栈。
+
+### Task 11：统一练习会话事实
+
+- [x] 新建 `backend/unispeaking-server/src/main/resources/db/migration/V2__practice_session.sql`，保存全场景会话开始、结束和状态。
+- [x] 新建 Practice Session Domain、Entity、Mapper 和 Repository，数据库访问只使用 MyBatis-Plus。
+- [x] 修改 `SessionService.startSession/endSession`，结束时间使用服务器时间，Realtime 失败写入 `FAILED`。
+- [x] 更新 `deploy/postgres/profile.sql`，支持现有数据库手工迁移。
+
+### Task 12：个人主页真实统计
+
+- [x] `ProfileOverviewResponse` 增加 `statistics`。
+- [x] 新增 `PracticeDurationCalculator`，实现 180 秒门槛、周统计和跨零点拆分。
+- [x] 训练记录数量直接统计未软删除 `scene` 记录，不累加复练次数。
+- [x] 连续学习天数继续依据五维报告日期计算。
+
+### Task 13：前端真实数据和资料区域
+
+- [x] 三张统计卡和七日练习节奏读取 `profile.statistics`。
+- [x] 头像调整为圆形并放大，编辑按钮定位到头像右上角。
+- [x] 用户名和邮箱适当放大；左侧资料区及底部退出登录继续固定。
+
+### Task 14：本轮提交
+
+- [x] `feat: 持久化全场景练习会话`
+- [x] `feat: 接入个人主页真实学习统计`
+- [x] `feat: 优化头像编辑入口和统计展示`
+- [x] `feat: 更新个人主页真实统计文档`
diff --git "a/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md" "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md"
index e9bac31..d654603 100644
--- "a/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md"
+++ "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md"
@@ -5,7 +5,7 @@
 - 设计日期：2026-07-31。
 - 适用仓库：`UniSpeaking`。
 - 定位基线：当前提交 `27e8618`。
-- 当前状态：设计已确认并已进入实施；对象存储供应商已按后续确认切换为七牛云 Kodo。
+- 当前状态：账户资料、七牛云头像、自动打卡和真实学习统计均已按后续确认进入实施。
 - 本文中的行号以当前提交为准；实施时同时使用类名、方法名和代码锚点定位，禁止仅凭行号修改。
 - 本文记录确认后的开发方案及精确修改位置；实际完成情况以 Git 提交和验证结果为准。
 
@@ -69,17 +69,17 @@
 - 已软删除场景的历史报告仍须参与打卡计算。
 - 五维结果弹窗拿到报告时显示“今日已自动打卡”。
 
-### 3.5 保留的现有静态内容
+### 3.5 真实学习统计
 
-以下现有静态内容保持原样，不改为后端统计：
-
-- “本周学习时长”统计卡；
-- “已保存学习资产”统计卡；
-- “连续学习天数”统计卡；
-- 七日练习节奏柱状图；
-- 成就系统及其静态进度。
-
-只有学习日历中的打卡日期改为由五维报告动态推导。
+- “本周学习时长”统计所有已正常结束且整场时长不少于 3 分钟的会话。
+- 自由对话、自定义场景、雅思、面试以及后续复用统一会话生命周期的场景使用同一口径。
+- 会话从后端创建时间 `started_at` 计算到后端确认结束时间 `ended_at`；客户端时间不作为统计真相。
+- 单次会话不足 180 秒时整场排除；达到 180 秒时全部计入。
+- 跨越上海时区零点的有效会话按各自然日实际覆盖秒数拆分。
+- “已保存学习资产”直接等于未软删除训练记录数量，不累加同一记录的复练次数。
+- “连续学习天数”仍由五维报告打卡日期计算；当日尚未打卡时允许从昨日向前延续。
+- 七日练习节奏使用与本周学习时长完全相同的有效时长口径。
+- 成就系统及其进度暂时保持静态。
 
 ## 4. 不在本次范围
 
@@ -90,7 +90,7 @@
 - 不增加 `user_check_in` 表。
 - 不增加 Redis 依赖、Redis 容器或 Redis 配置。
 - 不修改五维评分算法、五维报告字段或评分表结构。
-- 不把原有静态统计、练习节奏或成就系统改为动态数据。
+- 不把成就系统改为动态数据。
 - 不引入消息队列、CDN 或浏览器直传七牛云。
 - 不在本次工作中重构整个 `App.jsx`。
 
@@ -111,6 +111,8 @@
 9. “修改密码”按钮目前没有事件处理。
 10. 当前项目不引入 Redis；头像对象存储通过 `ObjectStorageProvider` 抽象，由七牛云
     Java SDK 适配，配置为空时使用不可用实现且不阻止应用启动。
+11. 学习时长需要覆盖不生成五维报告的自由对话，不能由 `session_evaluation` 或
+    `session_message` 反推，因此使用 `practice_session` 保存统一会话事实。
 
 ## 6. 总体架构
 
@@ -121,6 +123,8 @@ ProfileController
     │       ├── UserAccountRepository
     │       ├── SceneRepository
     │       ├── SessionEvaluationRepository
+    │       ├── PracticeSessionRepository
+    │       ├── PracticeDurationCalculator
     │       └── ObjectStorageProvider
     └── ProfileAccountService
             ├── UserAccountRepository
@@ -190,6 +194,10 @@ avatars/22222222-2222-4222-8222-222222222222/550e8400-e29b-41d4-a716-44665544000
 - 不修改 `username`、`nickname`、`password_hash` 或 `auth_version` 的类型。
 - 不设置新的数据库外键。
 
+允许新增 `practice_session` 作为统一会话事实表。它不是打卡表或统计汇总表，只保存
+`session_id`、`user_id`、`scene_id`、`scene_type`、`status`、`started_at` 和
+`ended_at` 等会话原始事实。Redis 不得替代该表。
+
 ### 7.3 打卡读取算法
 
 1. 从 JWT 获取用户 UUID。
@@ -211,6 +219,17 @@ LambdaQueryWrapper<SessionEvaluationEntity>
 允许 `.eq()`、`.in()`、`.ge()`、`.lt()`、`.select()` 和 `.orderByAsc()`；
 禁止 SQL 拼接和 `CLAUDE.md` 列出的所有危险 Wrapper 方法。
 
+### 7.4 学习时长算法
+
+1. `SessionService.startSession(...)` 在保存进程内会话前插入一条 `CREATED` 记录。
+2. Realtime 连接失败时将记录更新为 `FAILED` 并写入服务器结束时间。
+3. `SessionService.endSession(...)` 使用服务器 `Instant.now()` 将记录幂等更新为
+   `COMPLETED`，同时结束进程内会话。
+4. 统计只读取与目标时间范围重叠的 `COMPLETED` 记录。
+5. 先按完整会话判断 `ended_at - started_at >= 180 秒`，再与周区间或自然日区间求交集。
+6. 本周从 `Asia/Shanghai` 周一 00:00 开始；七日节奏从今天向前取六个自然日。
+7. 后端返回秒数，前端向下取整为完整分钟展示，不在数据库保存分钟或累计值。
+
 ## 8. HTTP 接口
 
 所有接口都必须携带 JWT，响应继续使用统一 `ApiResponse`。
@@ -238,6 +257,15 @@ Authorization: Bearer <JWT>
       "avatarUrl": "https://profile.example.com/...",
       "avatarUrlExpiresAt": "2026-07-31T10:00:00Z"
     },
+    "statistics": {
+      "weeklyPracticeSeconds": 10980,
+      "trainingRecordCount": 12,
+      "consecutiveLearningDays": 7,
+      "lastSevenDays": [
+        {"date": "2026-07-25", "practiceSeconds": 1080},
+        {"date": "2026-07-26", "practiceSeconds": 1560}
+      ]
+    },
     "calendar": {
       "month": "2026-07",
       "checkedDates": [
@@ -463,8 +491,9 @@ backend/unispeaking-server/src/main/java/com/unispeaking/
 
 | 动作 | 文件 | 当前定位/锚点 | 必须修改的内容 |
 | --- | --- | --- | --- |
-| 修改 | `backend/unispeaking-server/src/main/resources/db/schema.sql` | 当前第 1 行 `"user"` 建表；`ALTER COLUMN username TYPE VARCHAR(254)` 之后 | 增加 `avatar_object_key`、非空白约束和字段注释；不增加其他表或字段 |
-| 新建 | `deploy/postgres/profile.sql` | 新文件 | 用 `BEGIN/COMMIT` 包装同一组幂等头像字段迁移 SQL |
+| 修改 | `backend/unispeaking-server/src/main/resources/db/migration/V1__baseline.sql` | `"user"` 建表及头像字段迁移 | 增加 `avatar_object_key`、非空白约束和字段注释 |
+| 新建 | `backend/unispeaking-server/src/main/resources/db/migration/V2__practice_session.sql` | 新文件 | 新增统一练习会话事实表、时间约束及用户时间索引 |
+| 修改 | `deploy/postgres/profile.sql` | 头像字段迁移之后 | 补充可手工执行的幂等 `practice_session` 建表和索引 |
 | 修改 | `backend/unispeaking-server/src/main/resources/application.yaml` | 顶层 `profile:` 之后、`prompt:` 之前 | 新增 `object-storage.qiniu`，绑定 Access Key、Secret Key、Bucket、HTTPS 下载域名、头像前缀和签名 TTL |
 | 修改 | `deploy/env/.env.example` | `# Profile and Qiniu Kodo` 段 | 增加 `QINIU_ACCESS_KEY`、`QINIU_SECRET_KEY`、`QINIU_BUCKET`、`QINIU_DOMAIN`、头像前缀和签名 TTL 占位值，不填真实密钥 |
 | 修改 | `deploy/nginx/nginx.conf` | 当前第 12 行 `server` 块内、`location /backend/` 之前 | 增加 `client_max_body_size 10m;`，与 Spring 现有 multipart 上限对齐 |
@@ -483,7 +512,7 @@ backend/unispeaking-server/src/main/java/com/unispeaking/
 | 新建 | `domain/dto/profile/UpdateProfileResponse.java` | 新文件 | `nickname`、`displayName` |
 | 新建 | `domain/dto/profile/ProfileAccountResponse.java` | 新文件 | `userId`、`email`、`nickname`、`displayName`、`avatarUrl`、`avatarUrlExpiresAt` |
 | 新建 | `domain/dto/profile/ProfileCalendarResponse.java` | 新文件 | `month`、`List<LocalDate> checkedDates`、`checkedInToday` |
-| 新建 | `domain/dto/profile/ProfileOverviewResponse.java` | 新文件 | `account`、`calendar` |
+| 新建 | `domain/dto/profile/ProfileOverviewResponse.java` | 新文件 | `account`、`statistics`、`calendar`；statistics 包含周时长、训练记录数、连续天数和七日时长 |
 | 新建 | `domain/dto/profile/AvatarResponse.java` | 新文件 | `avatarUrl`、`avatarUrlExpiresAt` |
 | 不改 | `domain/dto/evaluation/DialogueReportResult.java` | 整个 record | 任意已保存报告都算打卡，不新增状态字段 |
 
@@ -517,7 +546,8 @@ Controller 禁止：
 | 不改 | `service/profile/impl/ProfileServiceImpl.java` | 整个文件 | 不把资料、头像和打卡逻辑塞入现有偏好服务 |
 | 修改 | `service/auth/AuthService.java` | 当前第 11 行 `currentUser()` 后 | 增加 `changePassword(ChangePasswordRequest)` |
 | 修改 | `service/auth/impl/AuthServiceImpl.java` | 当前第 97 行 `currentUser()` 后 | 增加 `@Transactional changePassword`，复用 `requireAuthenticatedUser()` |
-| 不改 | `service/session/impl/SessionServiceImpl.java` | `completeCustomScene()` | 报告保存逻辑不增加打卡写入 |
+| 修改 | `service/session/impl/SessionServiceImpl.java` | `startSession()`、`endSession()`、Realtime 连接失败分支 | 创建、完成或失败时同步持久化 `practice_session`；不增加打卡写入 |
+| 新建 | `service/profile/PracticeDurationCalculator.java` | 新文件 | 处理 180 秒门槛、周区间求交和跨自然日拆分 |
 
 修改密码流程：
 
@@ -540,8 +570,14 @@ Controller 禁止：
 | 修改 | `infrastructure/persistence/repository/scene/SceneRepository.java` | 当前第 18 行 `findAssetsByUserId` 附近 | 增加 `findAllIdsByUserId(String userId)`，语义明确包含软删除场景 |
 | 修改 | `infrastructure/persistence/repository/scene/MybatisSceneRepository.java` | 当前第 102 行 `findAssetsByUserId` 前 | 实现只按 `userId` 查询 ID，不加 `deletedAt IS NULL` |
 | 修改 | `infrastructure/persistence/repository/evaluation/SessionEvaluationRepository.java` | 当前第 83 行 `findBySceneId` 后 | 增加 `findCreatedAtBySceneIdsBetween(sceneIds,start,end)`，空 ID 集合直接返回空列表 |
+| 新建 | `domain/po/session/PracticeSessionRecord.java` | 新文件 | 向 Service 暴露会话事实，不泄漏数据库 Entity |
+| 新建 | `infrastructure/persistence/entity/session/PracticeSessionEntity.java` | 新文件 | 映射 `practice_session`，`session_id` 使用输入主键 |
+| 新建 | `infrastructure/persistence/mapper/session/PracticeSessionMapper.java` | 新文件 | 仅继承 `BaseMapper<PracticeSessionEntity>`，不写 SQL/XML |
+| 新建 | `infrastructure/persistence/repository/session/PracticeSessionRepository.java` | 新文件 | 封装创建、终态幂等更新和时间范围重叠查询 |
+| 修改 | `infrastructure/persistence/repository/scene/SceneRepository.java` | `findAssetsByUserId` 附近 | 增加 `countActiveByUserId`，语义为未软删除训练记录数 |
+| 修改 | `infrastructure/persistence/repository/scene/MybatisSceneRepository.java` | `findAssetsByUserId` 后 | 使用 `selectCount` 实现训练记录计数，不加载学习内容详情 |
 | 不改 | `infrastructure/persistence/entity/evaluation/SessionEvaluationEntity.java` | 整个类 | 直接读取现有 `sceneId` 和 `createdAt` |
-| 不改 | `infrastructure/persistence/mapper/*` | 所有 Mapper | 现有 BaseMapper 足够，不增加 SQL/XML |
+| 不改 | 其他 `infrastructure/persistence/mapper/*` | 其他 Mapper | 不增加 SQL/XML |
 
 账户更新方法的契约：
 
@@ -603,15 +639,15 @@ boolean updatePasswordAndAuthVersion(
 | 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 572 行 `AppShell` | 新增 `avatarUrl` 参数；第 585 行用用户头像或默认头像替代 `teacher.image` |
 | 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 1194 行 `ResultModal` | `evaluation` 存在时展示“今日已自动打卡”状态 |
 | 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 1968 行 `Profile` | 使用 Profile account；增加昵称编辑入口和头像上传入口 |
-| 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 1976～1989 行 `learningMonths` | 删除静态月份打卡数据；不得删除静态统计卡、节奏柱状图和成就常量 |
+| 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | `Profile` 和 `Overview` 组件 | 删除统计卡和节奏硬编码，读取 overview.statistics；成就常量保持不变 |
 | 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 2006 行 `LearningCalendar` | 按月份调用后端并渲染 `checkedDates`；月份切换支持历史月份，不允许未来月份 |
-| 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 2073 行 `Overview` | 继续原样渲染三张静态卡、节奏和成就；只向日历传动态数据 |
+| 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | `Overview` | 周时长、训练记录数、连续天数和七日节奏全部渲染真实数据 |
 | 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 2082 行 `Settings` 的“账户与隐私” | 给“修改密码”接入弹窗；“删除账户”保持不变 |
 | 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 2096 行 `App` 状态与第 2175 行认证启动 | 增加 profile 状态；认证启动并行加载当前月份 overview；资料更新后同步状态 |
 | 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 2287 行 `logout()` 附近 | 修改密码成功后复用清理 Token 和跳转登录逻辑 |
 | 修改 | `frontend/Unispeaking_fronted/src/App.jsx` | 当前第 2373～2374 行 Profile/AppShell 渲染 | 向 Profile 和 AppShell 传 account、avatarUrl 及更新回调 |
 | 修改 | `frontend/Unispeaking_fronted/src/styles.css` | 当前第 256～258 行 sidebar avatar | 保持头像裁切；增加加载失败/默认头像状态 |
-| 修改 | `frontend/Unispeaking_fronted/src/styles.css` | 当前第 806 行 profile 区域 | 增加头像编辑、昵称编辑、上传预览、表单错误、提交中状态 |
+| 修改 | `frontend/Unispeaking_fronted/src/styles.css` | `.profile-user`、`.profile-user__avatar`、`.profile-user__edit`、`.bars` | 放大圆形头像和账户文字；编辑按钮放到头像右上角；增加真实柱状图零值和日期样式 |
 | 修改 | `frontend/Unispeaking_fronted/src/styles.css` | 当前第 810～838 行日历 | 保持现有视觉，只将 `is-practiced` 数据源改为报告日期 |
 | 修改 | `frontend/Unispeaking_fronted/src/styles.css` | 当前第 879 行设置区域 | 增加修改密码弹窗状态样式 |
 
@@ -641,6 +677,8 @@ boolean updatePasswordAndAuthVersion(
 | 文件 | 覆盖内容 |
 | --- | --- |
 | `src/test/java/com/unispeaking/service/profile/ProfileOverviewServiceImplTest.java` | 同日多报告去重、跨日、跨月、上海零点边界、软删除场景、无场景、无头像和签名失败降级 |
+| `src/test/java/com/unispeaking/service/profile/PracticeDurationCalculatorTest.java` | 180 秒临界值、不足 180 秒排除、跨上海零点拆分 |
+| `src/test/java/com/unispeaking/infrastructure/persistence/repository/session/PracticeSessionRepositoryTest.java` | 会话创建映射和完成记录时间范围查询 |
 | `src/test/java/com/unispeaking/service/profile/ProfileAccountServiceImplTest.java` | 昵称规范化、邮箱不变、头像上传补偿、并发更新冲突、旧对象删除失败 |
 | `src/test/java/com/unispeaking/service/profile/image/AvatarImageProcessorTest.java` | JPEG/PNG、伪造扩展名、非图片、2 MiB 上限、尺寸上下限、重新编码 |
 | `src/test/java/com/unispeaking/controller/ProfileControllerTest.java` | JWT 身份、月份参数、统一响应、multipart、禁止客户端 userId |
@@ -648,6 +686,9 @@ boolean updatePasswordAndAuthVersion(
 
 ### 11.2 修改现有测试
 
+- `SessionServiceImplRepracticeTest`：同步构造参数，并验证结束时间写入 Practice Session Repository。
+- `MybatisSceneRepositoryTest`：验证未软删除训练记录使用数据库计数查询。
+
 | 文件 | 修改位置 | 覆盖内容 |
 | --- | --- | --- |
 | `src/test/java/com/unispeaking/service/auth/AuthServiceImplTest.java` | 当前第 84 行 JWT 测试之后；所有 `UserAccount` 构造器 | 当前密码错误、新旧密码相同、BCrypt 编码、authVersion 增加、并发冲突、旧 JWT 被撤销 |
@@ -671,7 +712,7 @@ npm run check:realtime-events
 2. 进入个人主页，当天显示为已打卡。
 3. 同一天生成多份报告，日历仍只有一个打卡标记。
 4. 跨上海时区零点生成报告，日期归属正确。
-5. 三张静态统计卡、七日节奏和成就系统内容与开发前一致。
+5. 三张统计卡和七日节奏来自后端真实数据；成就系统内容与开发前一致。
 6. 修改昵称后，个人主页和侧边栏名称立即更新；重新登录后仍保留。
 7. 登录邮箱不因昵称修改而变化。
 8. 上传合法头像后立即更新，刷新页面后仍通过七牛云签名 URL 显示。
@@ -713,9 +754,9 @@ cd backend/unispeaking-server
 
 只有同时满足以下条件才算完成：
 
-- 仅 `"user"` 表新增 `avatar_object_key`，没有打卡表、Redis 或评分表改动。
+- `"user"` 表新增 `avatar_object_key`，并新增 `practice_session` 会话事实表；没有打卡表、Redis 或评分表改动。
 - 打卡完全由已有五维报告推导，任意持久化报告都算。
-- 静态统计卡、节奏和成就保持不变。
+- 统计卡和七日节奏使用真实数据，成就保持不变。
 - 登录邮箱不可修改，昵称可持久化修改。
 - 头像只保存对象 Key，签名 URL 短期生成，失败补偿完整。
 - 修改密码验证当前密码，并通过 `auth_version` 撤销全部旧 JWT。

From e0e4555f6a53503659a8dff5614ebb038148da1f Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Mon, 3 Aug 2026 15:13:20 +0800
Subject: [PATCH 58/62] =?UTF-8?q?feat:=20=E6=B8=85=E7=90=86=E7=BB=83?=
 =?UTF-8?q?=E4=B9=A0=E7=BB=9F=E8=AE=A1=E6=96=87=E4=BB=B6=E6=A0=BC=E5=BC=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../com/unispeaking/domain/po/session/PracticeSessionRecord.java | 1 -
 .../persistence/entity/session/PracticeSessionEntity.java        | 1 -
 .../persistence/mapper/session/PracticeSessionMapper.java        | 1 -
 .../repository/session/PracticeSessionRepository.java            | 1 -
 .../unispeaking/service/profile/PracticeDurationCalculator.java  | 1 -
 .../src/main/resources/db/migration/V2__practice_session.sql     | 1 -
 6 files changed, 6 deletions(-)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/domain/po/session/PracticeSessionRecord.java b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/po/session/PracticeSessionRecord.java
index f50e982..54cf241 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/domain/po/session/PracticeSessionRecord.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/domain/po/session/PracticeSessionRecord.java
@@ -14,4 +14,3 @@ public record PracticeSessionRecord(
 		Instant startedAt,
 		Instant endedAt) {
 }
-
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/entity/session/PracticeSessionEntity.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/entity/session/PracticeSessionEntity.java
index 4a91360..34ac05a 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/entity/session/PracticeSessionEntity.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/entity/session/PracticeSessionEntity.java
@@ -29,4 +29,3 @@ public class PracticeSessionEntity {
 	private OffsetDateTime createdAt;
 	private OffsetDateTime updatedAt;
 }
-
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/mapper/session/PracticeSessionMapper.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/mapper/session/PracticeSessionMapper.java
index 2a196fa..fb59f29 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/mapper/session/PracticeSessionMapper.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/mapper/session/PracticeSessionMapper.java
@@ -5,4 +5,3 @@
 
 public interface PracticeSessionMapper extends BaseMapper<PracticeSessionEntity> {
 }
-
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/session/PracticeSessionRepository.java b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/session/PracticeSessionRepository.java
index a548214..79b352a 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/session/PracticeSessionRepository.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/infrastructure/persistence/repository/session/PracticeSessionRepository.java
@@ -165,4 +165,3 @@ private BusinessException persistenceFailure() {
 				"练习会话记录保存失败");
 	}
 }
-
diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/PracticeDurationCalculator.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/PracticeDurationCalculator.java
index f6b57e1..cef98bf 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/PracticeDurationCalculator.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/PracticeDurationCalculator.java
@@ -84,4 +84,3 @@ private long overlapSeconds(
 		return end.isAfter(start) ? Duration.between(start, end).getSeconds() : 0;
 	}
 }
-
diff --git a/backend/unispeaking-server/src/main/resources/db/migration/V2__practice_session.sql b/backend/unispeaking-server/src/main/resources/db/migration/V2__practice_session.sql
index 481d82e..74a7f4e 100644
--- a/backend/unispeaking-server/src/main/resources/db/migration/V2__practice_session.sql
+++ b/backend/unispeaking-server/src/main/resources/db/migration/V2__practice_session.sql
@@ -45,4 +45,3 @@ COMMENT ON COLUMN practice_session.user_id IS
 
 COMMENT ON COLUMN practice_session.scene_id IS
 '场景业务 ID；自由对话和后续无需持久化场景定义的类型也允许记录';
-

From 9280568192e3a8c58bfa56b38e8aaf221ff3abc3 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Mon, 3 Aug 2026 15:29:27 +0800
Subject: [PATCH 59/62] =?UTF-8?q?feat:=20=E5=B0=86=E6=9C=89=E6=95=88?=
 =?UTF-8?q?=E5=AD=A6=E4=B9=A0=E6=97=B6=E9=95=BF=E9=97=A8=E6=A7=9B=E8=B0=83?=
 =?UTF-8?q?=E6=95=B4=E4=B8=BA=E4=B8=89=E5=8D=81=E7=A7=92?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../service/profile/PracticeDurationCalculator.java  |  2 +-
 .../profile/PracticeDurationCalculatorTest.java      | 10 +++++-----
 docs/deployment.md                                   |  2 +-
 docs/frontend-backend-interface-contract.md          |  5 +++--
 ...5\256\236\346\226\275\350\256\241\345\210\222.md" |  2 +-
 ...5\274\200\345\217\221\350\256\276\350\256\241.md" | 12 ++++++------
 frontend/Unispeaking_fronted/src/App.jsx             |  4 ++--
 7 files changed, 19 insertions(+), 18 deletions(-)

diff --git a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/PracticeDurationCalculator.java b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/PracticeDurationCalculator.java
index cef98bf..825806f 100644
--- a/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/PracticeDurationCalculator.java
+++ b/backend/unispeaking-server/src/main/java/com/unispeaking/service/profile/PracticeDurationCalculator.java
@@ -11,7 +11,7 @@
 
 public class PracticeDurationCalculator {
 
-	public static final long MINIMUM_PRACTICE_SECONDS = 180;
+	public static final long MINIMUM_PRACTICE_SECONDS = 30;
 
 	public ProfileOverviewResponse.PracticeStatistics calculate(
 			List<PracticeSessionRecord> records,
diff --git a/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/PracticeDurationCalculatorTest.java b/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/PracticeDurationCalculatorTest.java
index 3ff770f..c2a79b9 100644
--- a/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/PracticeDurationCalculatorTest.java
+++ b/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/PracticeDurationCalculatorTest.java
@@ -19,13 +19,13 @@ class PracticeDurationCalculatorTest {
 			new PracticeDurationCalculator();
 
 	@Test
-	void excludesSessionsShorterThanThreeMinutes() {
+	void excludesSessionsShorterThanThirtySeconds() {
 		var result = calculate(List.of(
-				record("2026-08-03T01:00:00Z", "2026-08-03T01:02:59Z"),
-				record("2026-08-03T02:00:00Z", "2026-08-03T02:03:00Z")));
+				record("2026-08-03T01:00:00Z", "2026-08-03T01:00:29Z"),
+				record("2026-08-03T02:00:00Z", "2026-08-03T02:00:30Z")));
 
-		assertEquals(180, result.weeklyPracticeSeconds());
-		assertEquals(180, result.lastSevenDays().getLast().practiceSeconds());
+		assertEquals(30, result.weeklyPracticeSeconds());
+		assertEquals(30, result.lastSevenDays().getLast().practiceSeconds());
 	}
 
 	@Test
diff --git a/docs/deployment.md b/docs/deployment.md
index f78078c..cd504a9 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -48,7 +48,7 @@ The migration adds `user.avatar_object_key` and the `practice_session` session
 fact table. Check-in dates continue to be derived from persisted
 `session_evaluation` reports, so no check-in table and no Redis data structure
 are required. Learning duration is calculated from completed practice sessions;
-sessions shorter than 180 seconds are excluded at query time. New databases use
+sessions shorter than 30 seconds are excluded at query time. New databases use
 the Flyway migrations in
 `backend/unispeaking-server/src/main/resources/db/migration`.
 
diff --git a/docs/frontend-backend-interface-contract.md b/docs/frontend-backend-interface-contract.md
index bef6d05..8ba514d 100644
--- a/docs/frontend-backend-interface-contract.md
+++ b/docs/frontend-backend-interface-contract.md
@@ -51,8 +51,9 @@ Authorization: Bearer <accessToken>
 - `trainingRecordCount`：未软删除训练记录条数，同一记录复练多次仍计为一项。
 - `consecutiveLearningDays`：由五维报告自动打卡日期计算；当天未打卡时从昨天向前计算。
 - `lastSevenDays`：今天及之前六个上海自然日的有效学习秒数，按日期升序返回。
-- 单次完整会话不足 180 秒时不计入任何时长；达到 180 秒时全部计入。
+- 单次完整会话不足 30 秒时不计入任何时长；达到 30 秒时全部计入。
 - 有效会话跨越上海零点时，时长按每个自然日实际覆盖区间拆分。
+- 接口始终返回精确秒数；当前页面对非零有效秒数按分钟向上展示，因此 30～59 秒显示为 1 分钟。
 
 ### 修改用户名（昵称）
 
@@ -454,7 +455,7 @@ HTTP `POST /api/scene-sessions/{sessionId}/end` 目前保留，方便调试和
 1. 会话状态变为 `COMPLETED`。
 2. 后端使用服务器当前时间更新 `practice_session.ended_at`；请求中的 `stopTime`
    只为旧客户端兼容，不作为学习时长依据。
-3. 单次会话完整时长达到 180 秒后，才会进入个人主页学习时长与七日节奏统计。
+3. 单次会话完整时长达到 30 秒后，才会进入个人主页学习时长与七日节奏统计。
 4. 自由对话不保存消息正文；自定义场景保留本次完整消息；两者都不更新用户长期
    `memory_text`。
 
diff --git "a/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md" "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md"
index e397fae..b6d9bbb 100644
--- "a/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md"
+++ "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\256\236\346\226\275\350\256\241\345\210\222.md"
@@ -110,7 +110,7 @@
 ### Task 12：个人主页真实统计
 
 - [x] `ProfileOverviewResponse` 增加 `statistics`。
-- [x] 新增 `PracticeDurationCalculator`，实现 180 秒门槛、周统计和跨零点拆分。
+- [x] 新增 `PracticeDurationCalculator`，实现最新确认的 30 秒门槛、周统计和跨零点拆分。
 - [x] 训练记录数量直接统计未软删除 `scene` 记录，不累加复练次数。
 - [x] 连续学习天数继续依据五维报告日期计算。
 
diff --git "a/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md" "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md"
index d654603..72af80c 100644
--- "a/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md"
+++ "b/docs/\344\270\252\344\272\272\344\270\273\351\241\265\350\264\246\346\210\267\350\265\204\346\226\231\344\270\216\350\207\252\345\212\250\346\211\223\345\215\241\345\274\200\345\217\221\350\256\276\350\256\241.md"
@@ -71,10 +71,10 @@
 
 ### 3.5 真实学习统计
 
-- “本周学习时长”统计所有已正常结束且整场时长不少于 3 分钟的会话。
+- “本周学习时长”统计所有已正常结束且整场时长不少于 30 秒的会话。
 - 自由对话、自定义场景、雅思、面试以及后续复用统一会话生命周期的场景使用同一口径。
 - 会话从后端创建时间 `started_at` 计算到后端确认结束时间 `ended_at`；客户端时间不作为统计真相。
-- 单次会话不足 180 秒时整场排除；达到 180 秒时全部计入。
+- 单次会话不足 30 秒时整场排除；达到 30 秒时全部计入。
 - 跨越上海时区零点的有效会话按各自然日实际覆盖秒数拆分。
 - “已保存学习资产”直接等于未软删除训练记录数量，不累加同一记录的复练次数。
 - “连续学习天数”仍由五维报告打卡日期计算；当日尚未打卡时允许从昨日向前延续。
@@ -226,9 +226,9 @@ LambdaQueryWrapper<SessionEvaluationEntity>
 3. `SessionService.endSession(...)` 使用服务器 `Instant.now()` 将记录幂等更新为
    `COMPLETED`，同时结束进程内会话。
 4. 统计只读取与目标时间范围重叠的 `COMPLETED` 记录。
-5. 先按完整会话判断 `ended_at - started_at >= 180 秒`，再与周区间或自然日区间求交集。
+5. 先按完整会话判断 `ended_at - started_at >= 30 秒`，再与周区间或自然日区间求交集。
 6. 本周从 `Asia/Shanghai` 周一 00:00 开始；七日节奏从今天向前取六个自然日。
-7. 后端返回秒数，前端向下取整为完整分钟展示，不在数据库保存分钟或累计值。
+7. 后端返回秒数；前端对非零有效时长按分钟向上展示，确保 30～59 秒显示为 1 分钟；数据库不保存分钟或累计值。
 
 ## 8. HTTP 接口
 
@@ -547,7 +547,7 @@ Controller 禁止：
 | 修改 | `service/auth/AuthService.java` | 当前第 11 行 `currentUser()` 后 | 增加 `changePassword(ChangePasswordRequest)` |
 | 修改 | `service/auth/impl/AuthServiceImpl.java` | 当前第 97 行 `currentUser()` 后 | 增加 `@Transactional changePassword`，复用 `requireAuthenticatedUser()` |
 | 修改 | `service/session/impl/SessionServiceImpl.java` | `startSession()`、`endSession()`、Realtime 连接失败分支 | 创建、完成或失败时同步持久化 `practice_session`；不增加打卡写入 |
-| 新建 | `service/profile/PracticeDurationCalculator.java` | 新文件 | 处理 180 秒门槛、周区间求交和跨自然日拆分 |
+| 新建 | `service/profile/PracticeDurationCalculator.java` | 新文件 | 处理 30 秒门槛、周区间求交和跨自然日拆分 |
 
 修改密码流程：
 
@@ -677,7 +677,7 @@ boolean updatePasswordAndAuthVersion(
 | 文件 | 覆盖内容 |
 | --- | --- |
 | `src/test/java/com/unispeaking/service/profile/ProfileOverviewServiceImplTest.java` | 同日多报告去重、跨日、跨月、上海零点边界、软删除场景、无场景、无头像和签名失败降级 |
-| `src/test/java/com/unispeaking/service/profile/PracticeDurationCalculatorTest.java` | 180 秒临界值、不足 180 秒排除、跨上海零点拆分 |
+| `src/test/java/com/unispeaking/service/profile/PracticeDurationCalculatorTest.java` | 30 秒临界值、不足 30 秒排除、跨上海零点拆分 |
 | `src/test/java/com/unispeaking/infrastructure/persistence/repository/session/PracticeSessionRepositoryTest.java` | 会话创建映射和完成记录时间范围查询 |
 | `src/test/java/com/unispeaking/service/profile/ProfileAccountServiceImplTest.java` | 昵称规范化、邮箱不变、头像上传补偿、并发更新冲突、旧对象删除失败 |
 | `src/test/java/com/unispeaking/service/profile/image/AvatarImageProcessorTest.java` | JPEG/PNG、伪造扩展名、非图片、2 MiB 上限、尺寸上下限、重新编码 |
diff --git a/frontend/Unispeaking_fronted/src/App.jsx b/frontend/Unispeaking_fronted/src/App.jsx
index 93f1c73..e266161 100644
--- a/frontend/Unispeaking_fronted/src/App.jsx
+++ b/frontend/Unispeaking_fronted/src/App.jsx
@@ -2225,12 +2225,12 @@ function AchievementSystem() {
 }
 
 function Overview({ calendar, statistics, onMonthChange }) {
-  const weeklyMinutes = Math.floor((statistics?.weeklyPracticeSeconds || 0) / 60);
+  const weeklyMinutes = Math.ceil((statistics?.weeklyPracticeSeconds || 0) / 60);
   const trainingRecordCount = statistics?.trainingRecordCount || 0;
   const consecutiveLearningDays = statistics?.consecutiveLearningDays || 0;
   const days = statistics?.lastSevenDays || [];
   const maximumSeconds = Math.max(0, ...days.map((day) => day.practiceSeconds || 0));
-  return <><PageHeader eyebrow="PERSONAL OVERVIEW" title="你的学习空间" subtitle="把每一次开口变成看得见、可继续的成长记录。" action={calendar?.checkedInToday ? <span className="today-checkin"><CalendarCheck2 />今日已打卡</span> : null} /><div className="stat-grid"><article><Clock /><span><small>本周学习时长</small><strong>{weeklyMinutes} <em>分钟</em></strong></span></article><article><BookOpenText /><span><small>已保存学习资产</small><strong>{trainingRecordCount} <em>项</em></strong></span></article><article><Fire /><span><small>连续学习天数</small><strong>{consecutiveLearningDays} <em>天</em></strong></span></article></div><section className="overview-grid"><LearningCalendar calendar={calendar} onMonthChange={onMonthChange} /><article className="rhythm-card"><p className="eyebrow">LAST SEVEN DAYS</p><h2>练习节奏</h2><div className={cx("bars", !days.length && "is-empty")}>{days.length ? days.map((day) => { const seconds = day.practiceSeconds || 0; const minutes = Math.floor(seconds / 60); const height = maximumSeconds ? Math.max(3, (seconds / maximumSeconds) * 100) : 3; const weekday = new Date(`${day.date}T00:00:00+08:00`).toLocaleDateString("zh-CN", { weekday: "short", timeZone: "Asia/Shanghai" }); return <span key={day.date} className={seconds ? "" : "is-zero"} style={{ height: `${height}%` }} aria-label={`${day.date}，练习 ${minutes} 分钟`} title={`${day.date} · ${minutes} 分钟`}><small>{minutes}m</small><em>{weekday}</em></span>; }) : <p>完成一次至少 3 分钟的练习后，这里会显示你的节奏。</p>}</div></article></section><AchievementSystem /></>;
+  return <><PageHeader eyebrow="PERSONAL OVERVIEW" title="你的学习空间" subtitle="把每一次开口变成看得见、可继续的成长记录。" action={calendar?.checkedInToday ? <span className="today-checkin"><CalendarCheck2 />今日已打卡</span> : null} /><div className="stat-grid"><article><Clock /><span><small>本周学习时长</small><strong>{weeklyMinutes} <em>分钟</em></strong></span></article><article><BookOpenText /><span><small>已保存学习资产</small><strong>{trainingRecordCount} <em>项</em></strong></span></article><article><Fire /><span><small>连续学习天数</small><strong>{consecutiveLearningDays} <em>天</em></strong></span></article></div><section className="overview-grid"><LearningCalendar calendar={calendar} onMonthChange={onMonthChange} /><article className="rhythm-card"><p className="eyebrow">LAST SEVEN DAYS</p><h2>练习节奏</h2><div className={cx("bars", !days.length && "is-empty")}>{days.length ? days.map((day) => { const seconds = day.practiceSeconds || 0; const minutes = Math.ceil(seconds / 60); const height = maximumSeconds ? Math.max(3, (seconds / maximumSeconds) * 100) : 3; const weekday = new Date(`${day.date}T00:00:00+08:00`).toLocaleDateString("zh-CN", { weekday: "short", timeZone: "Asia/Shanghai" }); return <span key={day.date} className={seconds ? "" : "is-zero"} style={{ height: `${height}%` }} aria-label={`${day.date}，练习 ${minutes} 分钟`} title={`${day.date} · ${minutes} 分钟`}><small>{minutes}m</small><em>{weekday}</em></span>; }) : <p>完成一次至少 30 秒的练习后，这里会显示你的节奏。</p>}</div></article></section><AchievementSystem /></>;
 }
 
 function Membership() {

From e06a9caabff16217cd4d760f55bd1a35b1b63f35 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Mon, 3 Aug 2026 15:46:07 +0800
Subject: [PATCH 60/62] =?UTF-8?q?feat:=20=E4=BC=98=E5=8C=96=E4=B8=AA?=
 =?UTF-8?q?=E4=BA=BA=E4=B8=BB=E9=A1=B5=E8=B5=84=E4=BA=A7=E8=B7=B3=E8=BD=AC?=
 =?UTF-8?q?=E4=B8=8E=E7=BC=96=E8=BE=91=E6=8C=89=E9=92=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend/Unispeaking_fronted/src/App.jsx    | 10 +++++-----
 frontend/Unispeaking_fronted/src/styles.css |  6 +++---
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/frontend/Unispeaking_fronted/src/App.jsx b/frontend/Unispeaking_fronted/src/App.jsx
index e266161..5d6c89f 100644
--- a/frontend/Unispeaking_fronted/src/App.jsx
+++ b/frontend/Unispeaking_fronted/src/App.jsx
@@ -2124,14 +2124,14 @@ function ProfileEditModal({ account, user, avatarUrl, onClose, onNicknameChange,
   return <Modal onClose={submitting ? undefined : onClose} className="profile-edit-modal"><p className="eyebrow">EDIT PROFILE</p><h2>编辑个人资料</h2><p className="modal-lead">修改你的展示用户名或个人头像。</p><form className="profile-edit-form" onSubmit={submit}><div className="profile-edit-avatar"><img src={previewUrl} alt="头像预览" /><div><strong>个人头像</strong><small>支持 JPEG、PNG，文件不超过 2 MiB</small><label className="profile-avatar-picker">选择新头像<input type="file" accept="image/jpeg,image/png" disabled={submitting} onChange={selectAvatar} /></label></div></div><label className="profile-edit-name">用户名<input type="text" minLength={1} maxLength={80} required disabled={submitting} value={nickname} onChange={(event) => setNickname(event.target.value)} /></label>{error && <p className="form-error" role="alert">{error}</p>}<div className="modal-actions"><Button type="button" variant="secondary" disabled={submitting} onClick={onClose}>取消</Button><Button type="submit" disabled={submitting}>{submitting ? "正在保存" : "保存修改"}</Button></div></form></Modal>;
 }
 
-function Profile({ section, setSection, user, profile, teacher, speed, level, onSettingsChange, onMonthChange, onNicknameChange, onAvatarChange, onPasswordChange, onLogout }) {
+function Profile({ section, setSection, user, profile, teacher, speed, level, onSettingsChange, onMonthChange, onNicknameChange, onAvatarChange, onPasswordChange, onAssets, onLogout }) {
   const account = profile?.account;
   const displayName = account?.displayName || user?.nickname || user?.username?.split("@")[0] || "UniSpeaking User";
   const email = account?.email || user?.username || "";
   const avatarUrl = account?.avatarUrl || teacher.image;
   const [profileEditOpen, setProfileEditOpen] = useState(false);
   return (
-    <main className="profile-layout"><aside className="profile-nav"><div className="profile-user"><div className="profile-user__avatar"><img src={avatarUrl} alt={displayName} /><button type="button" className="profile-user__edit" aria-label="编辑用户名和头像" title="编辑用户名和头像" onClick={() => setProfileEditOpen(true)}><PencilSimple weight="bold" /></button></div><span><strong>{displayName}</strong><small>{email}</small></span></div><nav><button className={section === "profile" ? "is-active" : ""} onClick={() => setSection("profile")}><User />个人概览</button><button className={section === "membership" ? "is-active" : ""} onClick={() => setSection("membership")}><Crown />会员权益</button><button className={section === "settings" ? "is-active" : ""} onClick={() => setSection("settings")}><SlidersHorizontal />助手设置</button></nav><button className="logout" onClick={onLogout}><SignOut />退出登录</button></aside><section className="profile-content">{section === "profile" && <Overview calendar={profile?.calendar} statistics={profile?.statistics} onMonthChange={onMonthChange} />}{section === "membership" && <Membership />}{section === "settings" && <Settings teacher={teacher} speed={speed} level={level} onSettingsChange={onSettingsChange} onPasswordChange={onPasswordChange} />}</section>{profileEditOpen && <ProfileEditModal account={account} user={user} avatarUrl={avatarUrl} onClose={() => setProfileEditOpen(false)} onNicknameChange={onNicknameChange} onAvatarChange={onAvatarChange} />}</main>
+    <main className="profile-layout"><aside className="profile-nav"><div className="profile-user"><div className="profile-user__avatar"><img src={avatarUrl} alt={displayName} /><button type="button" className="profile-user__edit" aria-label="编辑用户名和头像" title="编辑用户名和头像" onClick={() => setProfileEditOpen(true)}><PencilSimple weight="bold" /></button></div><span><strong>{displayName}</strong><small>{email}</small></span></div><nav><button className={section === "profile" ? "is-active" : ""} onClick={() => setSection("profile")}><User />个人概览</button><button className={section === "membership" ? "is-active" : ""} onClick={() => setSection("membership")}><Crown />会员权益</button><button className={section === "settings" ? "is-active" : ""} onClick={() => setSection("settings")}><SlidersHorizontal />助手设置</button></nav><button className="logout" onClick={onLogout}><SignOut />退出登录</button></aside><section className="profile-content">{section === "profile" && <Overview calendar={profile?.calendar} statistics={profile?.statistics} onMonthChange={onMonthChange} onAssets={onAssets} />}{section === "membership" && <Membership />}{section === "settings" && <Settings teacher={teacher} speed={speed} level={level} onSettingsChange={onSettingsChange} onPasswordChange={onPasswordChange} />}</section>{profileEditOpen && <ProfileEditModal account={account} user={user} avatarUrl={avatarUrl} onClose={() => setProfileEditOpen(false)} onNicknameChange={onNicknameChange} onAvatarChange={onAvatarChange} />}</main>
   );
 }
 
@@ -2224,13 +2224,13 @@ function AchievementSystem() {
   );
 }
 
-function Overview({ calendar, statistics, onMonthChange }) {
+function Overview({ calendar, statistics, onMonthChange, onAssets }) {
   const weeklyMinutes = Math.ceil((statistics?.weeklyPracticeSeconds || 0) / 60);
   const trainingRecordCount = statistics?.trainingRecordCount || 0;
   const consecutiveLearningDays = statistics?.consecutiveLearningDays || 0;
   const days = statistics?.lastSevenDays || [];
   const maximumSeconds = Math.max(0, ...days.map((day) => day.practiceSeconds || 0));
-  return <><PageHeader eyebrow="PERSONAL OVERVIEW" title="你的学习空间" subtitle="把每一次开口变成看得见、可继续的成长记录。" action={calendar?.checkedInToday ? <span className="today-checkin"><CalendarCheck2 />今日已打卡</span> : null} /><div className="stat-grid"><article><Clock /><span><small>本周学习时长</small><strong>{weeklyMinutes} <em>分钟</em></strong></span></article><article><BookOpenText /><span><small>已保存学习资产</small><strong>{trainingRecordCount} <em>项</em></strong></span></article><article><Fire /><span><small>连续学习天数</small><strong>{consecutiveLearningDays} <em>天</em></strong></span></article></div><section className="overview-grid"><LearningCalendar calendar={calendar} onMonthChange={onMonthChange} /><article className="rhythm-card"><p className="eyebrow">LAST SEVEN DAYS</p><h2>练习节奏</h2><div className={cx("bars", !days.length && "is-empty")}>{days.length ? days.map((day) => { const seconds = day.practiceSeconds || 0; const minutes = Math.ceil(seconds / 60); const height = maximumSeconds ? Math.max(3, (seconds / maximumSeconds) * 100) : 3; const weekday = new Date(`${day.date}T00:00:00+08:00`).toLocaleDateString("zh-CN", { weekday: "short", timeZone: "Asia/Shanghai" }); return <span key={day.date} className={seconds ? "" : "is-zero"} style={{ height: `${height}%` }} aria-label={`${day.date}，练习 ${minutes} 分钟`} title={`${day.date} · ${minutes} 分钟`}><small>{minutes}m</small><em>{weekday}</em></span>; }) : <p>完成一次至少 30 秒的练习后，这里会显示你的节奏。</p>}</div></article></section><AchievementSystem /></>;
+  return <><PageHeader eyebrow="PERSONAL OVERVIEW" title="你的学习空间" subtitle="把每一次开口变成看得见、可继续的成长记录。" action={calendar?.checkedInToday ? <span className="today-checkin"><CalendarCheck2 />今日已打卡</span> : null} /><div className="stat-grid"><article><Clock /><span><small>本周学习时长</small><strong>{weeklyMinutes} <em>分钟</em></strong></span></article><button type="button" className="stat-card-action" aria-label={`查看已保存的 ${trainingRecordCount} 项学习资产`} onClick={onAssets}><BookOpenText /><span><small>已保存学习资产</small><strong>{trainingRecordCount} <em>项</em></strong></span></button><article><Fire /><span><small>连续学习天数</small><strong>{consecutiveLearningDays} <em>天</em></strong></span></article></div><section className="overview-grid"><LearningCalendar calendar={calendar} onMonthChange={onMonthChange} /><article className="rhythm-card"><p className="eyebrow">LAST SEVEN DAYS</p><h2>练习节奏</h2><div className={cx("bars", !days.length && "is-empty")}>{days.length ? days.map((day) => { const seconds = day.practiceSeconds || 0; const minutes = Math.ceil(seconds / 60); const height = maximumSeconds ? Math.max(3, (seconds / maximumSeconds) * 100) : 3; const weekday = new Date(`${day.date}T00:00:00+08:00`).toLocaleDateString("zh-CN", { weekday: "short", timeZone: "Asia/Shanghai" }); return <span key={day.date} className={seconds ? "" : "is-zero"} style={{ height: `${height}%` }} aria-label={`${day.date}，练习 ${minutes} 分钟`} title={`${day.date} · ${minutes} 分钟`}><small>{minutes}m</small><em>{weekday}</em></span>; }) : <p>完成一次至少 30 秒的练习后，这里会显示你的节奏。</p>}</div></article></section><AchievementSystem /></>;
 }
 
 function Membership() {
@@ -2624,6 +2624,6 @@ export function App() {
   else if (page === "ielts-assets") content = <IeltsAssets route={ieltsRoute} onNavigate={navigateIelts} onBackToAssets={() => setMainPage("assets")} onInterviewAssets={() => setMainPage("interview-assets")} onTraining={() => navigateIelts(paths.ielts.root)} />;
   else if (page === "interview") content = <InterviewTrainingCenter route={interviewRoute} onNavigate={navigateInterview} onExit={() => setMainPage("scenes")} onAssets={() => navigateInterview(paths.interview.assets.root)} />;
   else if (page === "interview-assets") content = <InterviewAssets route={interviewRoute} onNavigate={navigateInterview} onBackToAssets={() => setMainPage("assets")} onIeltsAssets={() => setMainPage("ielts-assets")} onTraining={() => navigateInterview(paths.interview.root)} />;
-  else content = <Profile section={page} setSection={setMainPage} user={user} profile={profileOverview} teacher={teacher} speed={conversationSpeed} level={level} onSettingsChange={persistSettings} onMonthChange={loadProfileMonth} onNicknameChange={updateNickname} onAvatarChange={updateAvatar} onPasswordChange={updatePassword} onLogout={logout} />;
+  else content = <Profile section={page} setSection={setMainPage} user={user} profile={profileOverview} teacher={teacher} speed={conversationSpeed} level={level} onSettingsChange={persistSettings} onMonthChange={loadProfileMonth} onNicknameChange={updateNickname} onAvatarChange={updateAvatar} onPasswordChange={updatePassword} onAssets={() => setMainPage("assets")} onLogout={logout} />;
   return <AppShell page={page} setPage={setMainPage} teacher={teacher} avatarUrl={profileOverview?.account?.avatarUrl}>{content}{paywall && <Paywall title={paywall} onClose={() => setPaywall(null)} onMembership={() => { setPaywall(null); setMainPage("membership"); }} />}</AppShell>;
 }
diff --git a/frontend/Unispeaking_fronted/src/styles.css b/frontend/Unispeaking_fronted/src/styles.css
index a64f5e1..4f3db24 100644
--- a/frontend/Unispeaking_fronted/src/styles.css
+++ b/frontend/Unispeaking_fronted/src/styles.css
@@ -820,8 +820,8 @@ svg { display: block; }
 .profile-user strong, .profile-user small { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .profile-user strong { font-size: 18px; line-height: 1.25; }
 .profile-user small { color: var(--muted); margin-top: 7px; font-size: 11px; }
-.profile-user__edit { position: absolute; top: -3px; right: -3px; width: 28px; height: 28px; display: grid; place-items: center; padding: 0; border: 3px solid #fff; border-radius: 50%; background: #252524; color: #fff; box-shadow: 0 4px 12px rgba(20,20,19,.18); cursor: pointer; transition: transform .2s, background .2s; }
-.profile-user__edit:hover { background: #565652; transform: scale(1.08); }
+.profile-user__edit { position: absolute; top: -3px; right: -3px; width: 28px; height: 28px; display: grid; place-items: center; padding: 0; border: 1px solid rgba(255,255,255,.88); border-radius: 50%; background: rgba(255,255,255,.62); color: rgba(37,37,36,.82); box-shadow: 0 4px 12px rgba(20,20,19,.15); -webkit-backdrop-filter: blur(5px); backdrop-filter: blur(5px); cursor: pointer; transition: transform .2s, background .2s, color .2s; }
+.profile-user__edit:hover { background: rgba(255,255,255,.84); color: #252524; transform: scale(1.08); }
 .profile-user__edit:focus-visible { outline: 2px solid #252524; outline-offset: 2px; }
 .profile-user__edit svg { width: 13px; height: 13px; }
 .profile-nav nav { display: grid; gap: 7px; }
@@ -830,7 +830,7 @@ svg { display: block; }
 .profile-nav nav svg, .logout svg { width: 19px; height: 19px; }
 .logout { flex: 0 0 46px; margin-top: auto; color: #555; }
 .profile-content { min-width: 0; min-height: 0; padding: 52px clamp(42px, 5vw, 84px) 60px; overflow: auto; }
-.stat-grid { display: grid; grid-template-columns: repeat(3,1fr); gap: 16px; }.stat-grid article { min-height: 106px; padding: 20px; border: 1px solid var(--line); border-radius: 14px; display: flex; gap: 14px; align-items: center; }.stat-grid article > svg { width: 22px; height: 22px; }.stat-grid small, .stat-grid strong { display: block; }.stat-grid small { color: var(--muted); }.stat-grid strong { font-size: 26px; margin-top: 7px; }.stat-grid em { font-style: normal; font-size: 11px; }
+.stat-grid { display: grid; grid-template-columns: repeat(3,1fr); gap: 16px; }.stat-grid article, .stat-grid > button { min-height: 106px; padding: 20px; border: 1px solid var(--line); border-radius: 14px; display: flex; gap: 14px; align-items: center; }.stat-grid > button { width: 100%; background: #fff; color: var(--ink); font: inherit; text-align: left; cursor: pointer; transition: border-color .2s, box-shadow .2s, transform .2s; }.stat-grid > button:hover { border-color: #b9b9b3; box-shadow: 0 9px 24px rgba(20,20,19,.08); transform: translateY(-2px); }.stat-grid > button:focus-visible { outline: 2px solid #252524; outline-offset: 3px; }.stat-grid article > svg, .stat-grid > button > svg { width: 22px; height: 22px; }.stat-grid small, .stat-grid strong { display: block; }.stat-grid small { color: var(--muted); }.stat-grid strong { font-size: 26px; margin-top: 7px; }.stat-grid em { font-style: normal; font-size: 11px; }
 .today-checkin, .result-checkin { display: inline-flex; align-items: center; gap: 7px; padding: 8px 12px; border-radius: 999px; background: #20201f; color: #fff; font-size: 12px; font-weight: 700; }
 .today-checkin svg, .result-checkin svg { width: 16px; height: 16px; }
 .result-checkin { margin-top: 13px; }

From ceca16f838ef276096bf797f60e5a89ebc9b43c3 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Mon, 3 Aug 2026 15:57:38 +0800
Subject: [PATCH 61/62] =?UTF-8?q?feat:=20=E8=A1=A5=E5=85=85=E4=B8=AA?=
 =?UTF-8?q?=E4=BA=BA=E4=B8=BB=E9=A1=B5=E5=8A=9F=E8=83=BD=E6=B5=8B=E8=AF=95?=
 =?UTF-8?q?=E5=B9=B6=E6=BB=A1=E8=B6=B3CI=E8=A6=86=E7=9B=96=E7=8E=87?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../SessionEvaluationRepositoryTest.java      | 180 ++++++++++++++++
 .../MybatisUserAccountRepositoryTest.java     | 161 +++++++++++++++
 .../image/AvatarImageProcessorTest.java       |  94 +++++++++
 .../impl/ProfileAccountServiceImplTest.java   | 193 ++++++++++++++++++
 4 files changed, 628 insertions(+)
 create mode 100644 backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/evaluation/SessionEvaluationRepositoryTest.java
 create mode 100644 backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/user/MybatisUserAccountRepositoryTest.java
 create mode 100644 backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/image/AvatarImageProcessorTest.java
 create mode 100644 backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/impl/ProfileAccountServiceImplTest.java

diff --git a/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/evaluation/SessionEvaluationRepositoryTest.java b/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/evaluation/SessionEvaluationRepositoryTest.java
new file mode 100644
index 0000000..84b8ed1
--- /dev/null
+++ b/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/evaluation/SessionEvaluationRepositoryTest.java
@@ -0,0 +1,180 @@
+package com.unispeaking.infrastructure.persistence.repository.evaluation;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.unispeaking.common.exception.evaluation.EvaluationErrorCode;
+import com.unispeaking.common.exception.evaluation.EvaluationException;
+import com.unispeaking.domain.dto.asset.SessionEvaluationRecord;
+import com.unispeaking.domain.dto.evaluation.DialogueReportResult;
+import com.unispeaking.infrastructure.persistence.entity.evaluation.SessionEvaluationEntity;
+import com.unispeaking.infrastructure.persistence.mapper.evaluation.SessionEvaluationMapper;
+import java.math.BigDecimal;
+import java.time.OffsetDateTime;
+import java.time.ZoneOffset;
+import java.util.List;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+class SessionEvaluationRepositoryTest {
+
+	@BeforeAll
+	static void initializeMybatisMetadata() {
+		TableInfoHelper.initTableInfo(
+				new MapperBuilderAssistant(new MybatisConfiguration(), "test"),
+				SessionEvaluationEntity.class);
+	}
+
+	@Test
+	void insertsNewEvaluationWithAllReportFields() {
+		SessionEvaluationMapper mapper = mock(SessionEvaluationMapper.class);
+		when(mapper.selectById("session-1")).thenReturn(null);
+		when(mapper.insert(any(SessionEvaluationEntity.class))).thenReturn(1);
+		SessionEvaluationRepository repository = new SessionEvaluationRepository(mapper);
+
+		repository.save("scene-1", "session-1", report());
+
+		ArgumentCaptor<SessionEvaluationEntity> captor =
+				ArgumentCaptor.forClass(SessionEvaluationEntity.class);
+		verify(mapper).insert(captor.capture());
+		SessionEvaluationEntity saved = captor.getValue();
+		assertEquals("scene-1", saved.getSceneId());
+		assertEquals(new BigDecimal("91"), saved.getFinalScore());
+		assertEquals(List.of("表达清楚"), List.of(saved.getStrengths()));
+		assertEquals(saved.getCreatedAt(), saved.getUpdatedAt());
+	}
+
+	@Test
+	void updatesExistingEvaluationAndKeepsCreatedTime() {
+		SessionEvaluationMapper mapper = mock(SessionEvaluationMapper.class);
+		SessionEvaluationEntity existing = entity("scene-1", "session-1");
+		when(mapper.selectById("session-1")).thenReturn(existing);
+		when(mapper.updateById(any(SessionEvaluationEntity.class))).thenReturn(1);
+		SessionEvaluationRepository repository = new SessionEvaluationRepository(mapper);
+
+		repository.save("scene-1", "session-1", report());
+
+		ArgumentCaptor<SessionEvaluationEntity> captor =
+				ArgumentCaptor.forClass(SessionEvaluationEntity.class);
+		verify(mapper).updateById(captor.capture());
+		assertEquals(existing.getCreatedAt(), captor.getValue().getCreatedAt());
+	}
+
+	@Test
+	void translatesInsertAndDatabaseFailures() {
+		SessionEvaluationMapper mapper = mock(SessionEvaluationMapper.class);
+		when(mapper.insert(any(SessionEvaluationEntity.class))).thenReturn(0);
+		SessionEvaluationRepository repository = new SessionEvaluationRepository(mapper);
+
+		EvaluationException rejected = assertThrows(
+				EvaluationException.class,
+				() -> repository.save("scene", "session", report()));
+		assertEquals(EvaluationErrorCode.PERSISTENCE_FAILED, rejected.errorCode());
+
+		when(mapper.selectById("broken")).thenThrow(new IllegalStateException("database"));
+		EvaluationException failed = assertThrows(
+				EvaluationException.class,
+				() -> repository.find("broken"));
+		assertEquals(EvaluationErrorCode.PERSISTENCE_FAILED, failed.errorCode());
+	}
+
+	@Test
+	void findsReportAndHandlesMissingArrays() {
+		SessionEvaluationMapper mapper = mock(SessionEvaluationMapper.class);
+		SessionEvaluationEntity entity = entity("scene-1", "session-1");
+		entity.setStrengths(null);
+		entity.setImprovements(null);
+		when(mapper.selectById("session-1")).thenReturn(entity);
+		when(mapper.selectById("missing")).thenReturn(null);
+		SessionEvaluationRepository repository = new SessionEvaluationRepository(mapper);
+
+		DialogueReportResult result = repository.find("session-1").orElseThrow();
+
+		assertEquals(new BigDecimal("91"), result.finalScore());
+		assertTrue(result.strengths().isEmpty());
+		assertTrue(result.improvements().isEmpty());
+		assertTrue(repository.find("missing").isEmpty());
+	}
+
+	@Test
+	void findsOnlyCompleteEvaluationRecords() {
+		SessionEvaluationMapper mapper = mock(SessionEvaluationMapper.class);
+		SessionEvaluationEntity valid = entity("scene-1", "session-1");
+		SessionEvaluationEntity blankScene = entity(" ", "session-2");
+		when(mapper.selectById("session-1")).thenReturn(valid);
+		when(mapper.selectById("session-2")).thenReturn(blankScene);
+		when(mapper.selectById("missing")).thenReturn(null);
+		SessionEvaluationRepository repository = new SessionEvaluationRepository(mapper);
+
+		SessionEvaluationRecord record = repository.findRecord("session-1").orElseThrow();
+
+		assertEquals("scene-1", record.sceneId());
+		assertEquals("session-1", record.sessionId());
+		assertTrue(repository.findRecord("session-2").isEmpty());
+		assertTrue(repository.findRecord("missing").isEmpty());
+	}
+
+	@Test
+	void listsSceneRecordsAndCreationDates() {
+		SessionEvaluationMapper mapper = mock(SessionEvaluationMapper.class);
+		SessionEvaluationEntity first = entity("scene-1", "session-1");
+		SessionEvaluationEntity second = entity("scene-1", "session-2");
+		second.setCreatedAt(first.getCreatedAt().plusMinutes(5));
+		when(mapper.selectList(any())).thenReturn(List.of(first, second));
+		SessionEvaluationRepository repository = new SessionEvaluationRepository(mapper);
+
+		assertEquals(2, repository.findBySceneId("scene-1").size());
+		assertEquals(
+				List.of(first.getCreatedAt(), second.getCreatedAt()),
+				repository.findCreatedAtBySceneIdsBetween(
+						List.of("scene-1"),
+						first.getCreatedAt().minusDays(1),
+						second.getCreatedAt().plusDays(1)));
+		assertTrue(repository.findCreatedAtBySceneIdsBetween(
+				List.of(), first.getCreatedAt(), second.getCreatedAt()).isEmpty());
+		assertTrue(repository.findCreatedAtBySceneIdsBetween(
+				null, first.getCreatedAt(), second.getCreatedAt()).isEmpty());
+	}
+
+	private DialogueReportResult report() {
+		return new DialogueReportResult(
+				new BigDecimal("90"),
+				new BigDecimal("89"),
+				new BigDecimal("88"),
+				new BigDecimal("87"),
+				new BigDecimal("86"),
+				new BigDecimal("91"),
+				"整体表现良好",
+				List.of("表达清楚"),
+				List.of("注意时态"));
+	}
+
+	private SessionEvaluationEntity entity(String sceneId, String sessionId) {
+		DialogueReportResult report = report();
+		SessionEvaluationEntity entity = new SessionEvaluationEntity();
+		entity.setSceneId(sceneId);
+		entity.setSessionId(sessionId);
+		entity.setAccuracyScore(report.accuracyScore());
+		entity.setFluencyScore(report.fluencyScore());
+		entity.setGrammarScore(report.grammarScore());
+		entity.setVocabularyScore(report.vocabularyScore());
+		entity.setNaturalnessScore(report.naturalnessScore());
+		entity.setFinalScore(report.finalScore());
+		entity.setSummary(report.summary());
+		entity.setStrengths(report.strengths().toArray(String[]::new));
+		entity.setImprovements(report.improvements().toArray(String[]::new));
+		entity.setCreatedAt(OffsetDateTime.of(
+				2026, 8, 3, 3, 0, 0, 0, ZoneOffset.UTC));
+		entity.setUpdatedAt(entity.getCreatedAt());
+		return entity;
+	}
+}
diff --git a/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/user/MybatisUserAccountRepositoryTest.java b/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/user/MybatisUserAccountRepositoryTest.java
new file mode 100644
index 0000000..5ebf1a5
--- /dev/null
+++ b/backend/unispeaking-server/src/test/java/com/unispeaking/infrastructure/persistence/repository/user/MybatisUserAccountRepositoryTest.java
@@ -0,0 +1,161 @@
+package com.unispeaking.infrastructure.persistence.repository.user;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import com.baomidou.mybatisplus.core.conditions.Wrapper;
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.unispeaking.domain.po.auth.UserAccount;
+import com.unispeaking.domain.po.auth.UserRole;
+import com.unispeaking.domain.po.auth.UserStatus;
+import com.unispeaking.infrastructure.persistence.entity.user.UserAccountEntity;
+import com.unispeaking.infrastructure.persistence.mapper.user.UserAccountMapper;
+import java.time.Instant;
+import java.time.OffsetDateTime;
+import java.time.ZoneOffset;
+import java.util.UUID;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+class MybatisUserAccountRepositoryTest {
+
+	@BeforeAll
+	static void initializeMybatisMetadata() {
+		TableInfoHelper.initTableInfo(
+				new MapperBuilderAssistant(new MybatisConfiguration(), "test"),
+				UserAccountEntity.class);
+	}
+
+	@Test
+	void mapsEntityToDomainById() {
+		UserAccountMapper mapper = mock(UserAccountMapper.class);
+		UUID id = UUID.randomUUID();
+		UserAccountEntity entity = entity(id);
+		when(mapper.selectById(id)).thenReturn(entity);
+		MybatisUserAccountRepository repository =
+				new MybatisUserAccountRepository(mapper);
+
+		UserAccount account = repository.findById(id).orElseThrow();
+
+		assertEquals(id, account.id());
+		assertEquals("learner@example.com", account.username());
+		assertEquals("avatar/object.png", account.avatarObjectKey());
+		assertEquals(UserRole.USER, account.role());
+		assertEquals(UserStatus.ACTIVE, account.status());
+		assertEquals(entity.getCreatedAt().toInstant(), account.createdAt());
+	}
+
+	@Test
+	void findsUsernameAndReturnsEmptyWhenMissing() {
+		UserAccountMapper mapper = mock(UserAccountMapper.class);
+		when(mapper.selectOne(any()))
+				.thenReturn(entity(UUID.randomUUID()))
+				.thenReturn(null);
+		MybatisUserAccountRepository repository =
+				new MybatisUserAccountRepository(mapper);
+
+		assertTrue(repository.findByUsername("learner@example.com").isPresent());
+		assertTrue(repository.findByUsername("missing@example.com").isEmpty());
+	}
+
+	@Test
+	void mapsDomainFieldsWhenCreatingAccount() {
+		UserAccountMapper mapper = mock(UserAccountMapper.class);
+		when(mapper.insert(any(UserAccountEntity.class))).thenReturn(1);
+		MybatisUserAccountRepository repository =
+				new MybatisUserAccountRepository(mapper);
+		UUID id = UUID.randomUUID();
+		Instant now = Instant.parse("2026-08-03T01:02:03Z");
+		UserAccount account = new UserAccount(
+				id,
+				"new@example.com",
+				"hash",
+				"新用户",
+				null,
+				UserRole.ADMIN,
+				UserStatus.LOCKED,
+				3,
+				null,
+				now,
+				now);
+
+		assertEquals(account, repository.create(account));
+
+		ArgumentCaptor<UserAccountEntity> captor =
+				ArgumentCaptor.forClass(UserAccountEntity.class);
+		verify(mapper).insert(captor.capture());
+		UserAccountEntity saved = captor.getValue();
+		assertEquals(id, saved.getId());
+		assertEquals("ADMIN", saved.getRole());
+		assertEquals("LOCKED", saved.getStatus());
+		assertEquals(3L, saved.getAuthVersion());
+		assertNull(saved.getAvatarObjectKey());
+		assertNull(saved.getLastLoginAt());
+		assertEquals(now, saved.getCreatedAt().toInstant());
+	}
+
+	@Test
+	void updatesLastLoginOnlyForExistingAccount() {
+		UserAccountMapper mapper = mock(UserAccountMapper.class);
+		UUID id = UUID.randomUUID();
+		UserAccountEntity entity = entity(id);
+		when(mapper.selectById(id)).thenReturn(entity);
+		MybatisUserAccountRepository repository =
+				new MybatisUserAccountRepository(mapper);
+		Instant loginAt = Instant.parse("2026-08-03T03:00:00Z");
+
+		repository.updateLastLoginAt(id, loginAt);
+
+		assertEquals(loginAt, entity.getLastLoginAt().toInstant());
+		verify(mapper).updateById(entity);
+
+		UUID missingId = UUID.randomUUID();
+		when(mapper.selectById(missingId)).thenReturn(null);
+		repository.updateLastLoginAt(missingId, loginAt);
+		verify(mapper, times(1)).updateById(any(UserAccountEntity.class));
+	}
+
+	@Test
+	void returnsWhetherProfileAndPasswordUpdatesMatched() {
+		UserAccountMapper mapper = mock(UserAccountMapper.class);
+		when(mapper.update(isNull(), any(Wrapper.class)))
+				.thenReturn(1, 0, 1, 0);
+		MybatisUserAccountRepository repository =
+				new MybatisUserAccountRepository(mapper);
+		UUID id = UUID.randomUUID();
+
+		assertTrue(repository.updateNickname(id, "新昵称"));
+		assertFalse(repository.updateAvatarObjectKey(id, null, "new.png"));
+		assertTrue(repository.updateAvatarObjectKey(id, "old.png", "new.png"));
+		assertFalse(repository.updatePasswordAndAuthVersion(id, 2, "new-hash"));
+	}
+
+	private UserAccountEntity entity(UUID id) {
+		OffsetDateTime now = OffsetDateTime.of(
+				2026, 8, 3, 1, 2, 3, 0, ZoneOffset.UTC);
+		UserAccountEntity entity = new UserAccountEntity();
+		entity.setId(id);
+		entity.setUsername("learner@example.com");
+		entity.setPasswordHash("hash");
+		entity.setNickname("学习者");
+		entity.setAvatarObjectKey("avatar/object.png");
+		entity.setRole("USER");
+		entity.setStatus("ACTIVE");
+		entity.setAuthVersion(2L);
+		entity.setLastLoginAt(now);
+		entity.setCreatedAt(now);
+		entity.setUpdatedAt(now);
+		return entity;
+	}
+}
diff --git a/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/image/AvatarImageProcessorTest.java b/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/image/AvatarImageProcessorTest.java
new file mode 100644
index 0000000..456d99a
--- /dev/null
+++ b/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/image/AvatarImageProcessorTest.java
@@ -0,0 +1,94 @@
+package com.unispeaking.service.profile.image;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import com.unispeaking.common.exception.BusinessException;
+import java.awt.Color;
+import java.awt.Graphics2D;
+import java.awt.image.BufferedImage;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import javax.imageio.ImageIO;
+import org.junit.jupiter.api.Test;
+
+class AvatarImageProcessorTest {
+
+	private final AvatarImageProcessor processor = new AvatarImageProcessor();
+
+	@Test
+	void preservesAlphaImagesAsPng() throws IOException {
+		byte[] input = image("png", BufferedImage.TYPE_INT_ARGB, 256, 256);
+
+		var result = processor.process(input);
+
+		assertEquals("png", result.extension());
+		assertEquals("image/png", result.contentType());
+		assertTrue(result.content().length > 0);
+	}
+
+	@Test
+	void convertsOpaqueImagesToJpeg() throws IOException {
+		byte[] input = image("jpg", BufferedImage.TYPE_INT_RGB, 256, 256);
+
+		var result = processor.process(input);
+
+		assertEquals("jpg", result.extension());
+		assertEquals("image/jpeg", result.contentType());
+		assertTrue(result.content().length > 0);
+	}
+
+	@Test
+	void requiresAvatarContent() {
+		assertCode("AVATAR_FILE_REQUIRED", () -> processor.process(null));
+		assertCode("AVATAR_FILE_REQUIRED", () -> processor.process(new byte[0]));
+	}
+
+	@Test
+	void rejectsOversizedAvatar() {
+		assertCode(
+				"AVATAR_FILE_TOO_LARGE",
+				() -> processor.process(new byte[2 * 1024 * 1024 + 1]));
+	}
+
+	@Test
+	void rejectsUnsupportedHeader() {
+		assertCode(
+				"AVATAR_TYPE_UNSUPPORTED",
+				() -> processor.process(new byte[] {1, 2, 3, 4}));
+	}
+
+	@Test
+	void rejectsUnreadableImageWithSupportedHeader() {
+		byte[] pngHeader = {
+				(byte) 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a
+		};
+
+		assertCode("AVATAR_CONTENT_INVALID", () -> processor.process(pngHeader));
+	}
+
+	@Test
+	void rejectsImageOutsideAllowedDimensions() throws IOException {
+		byte[] tooSmall = image("png", BufferedImage.TYPE_INT_ARGB, 127, 128);
+
+		assertCode("AVATAR_DIMENSION_INVALID", () -> processor.process(tooSmall));
+	}
+
+	private byte[] image(String format, int type, int width, int height)
+			throws IOException {
+		BufferedImage image = new BufferedImage(width, height, type);
+		Graphics2D graphics = image.createGraphics();
+		graphics.setColor(Color.BLUE);
+		graphics.fillRect(0, 0, width, height);
+		graphics.dispose();
+		ByteArrayOutputStream output = new ByteArrayOutputStream();
+		ImageIO.write(image, format, output);
+		return output.toByteArray();
+	}
+
+	private void assertCode(String code, Runnable action) {
+		BusinessException exception = assertThrows(BusinessException.class, action::run);
+		assertEquals(code, exception.code());
+	}
+}
diff --git a/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/impl/ProfileAccountServiceImplTest.java b/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/impl/ProfileAccountServiceImplTest.java
new file mode 100644
index 0000000..43de747
--- /dev/null
+++ b/backend/unispeaking-server/src/test/java/com/unispeaking/service/profile/impl/ProfileAccountServiceImplTest.java
@@ -0,0 +1,193 @@
+package com.unispeaking.service.profile.impl;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import com.unispeaking.common.exception.BusinessException;
+import com.unispeaking.domain.dto.profile.AvatarResponse;
+import com.unispeaking.domain.dto.profile.UpdateProfileRequest;
+import com.unispeaking.domain.po.auth.UserAccount;
+import com.unispeaking.domain.po.auth.UserRole;
+import com.unispeaking.domain.po.auth.UserStatus;
+import com.unispeaking.infrastructure.config.ObjectStorageProperties;
+import com.unispeaking.infrastructure.persistence.repository.user.UserAccountRepository;
+import com.unispeaking.infrastructure.storage.ObjectStorageProvider;
+import com.unispeaking.service.profile.image.AvatarImageProcessor;
+import com.unispeaking.service.profile.image.AvatarImageProcessor.ProcessedAvatar;
+import java.net.URI;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.Optional;
+import java.util.UUID;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+class ProfileAccountServiceImplTest {
+
+	private final UserAccountRepository accounts = mock(UserAccountRepository.class);
+	private final ObjectStorageProvider storage = mock(ObjectStorageProvider.class);
+	private final AvatarImageProcessor images = mock(AvatarImageProcessor.class);
+	private final ObjectStorageProperties properties = new ObjectStorageProperties();
+	private ProfileAccountServiceImpl service;
+
+	@BeforeEach
+	void setUp() {
+		properties.setAvatarPrefix("/profile-avatars/");
+		properties.setSignedUrlTtl(Duration.ofMinutes(30));
+		service = new ProfileAccountServiceImpl(accounts, storage, properties, images);
+	}
+
+	@Test
+	void trimsAndUpdatesNickname() {
+		UUID userId = UUID.randomUUID();
+		when(accounts.updateNickname(userId, "新昵称")).thenReturn(true);
+
+		var response = service.updateNickname(
+				userId.toString(),
+				new UpdateProfileRequest("  新昵称  "));
+
+		assertEquals("新昵称", response.nickname());
+		assertEquals("新昵称", response.displayName());
+	}
+
+	@Test
+	void rejectsBlankNickname() {
+		BusinessException exception = assertThrows(
+				BusinessException.class,
+				() -> service.updateNickname(
+						UUID.randomUUID().toString(),
+						new UpdateProfileRequest("   ")));
+
+		assertEquals("PROFILE_NICKNAME_REQUIRED", exception.code());
+	}
+
+	@Test
+	void reportsConcurrentNicknameUpdate() {
+		UUID userId = UUID.randomUUID();
+		when(accounts.updateNickname(userId, "昵称")).thenReturn(false);
+
+		BusinessException exception = assertThrows(
+				BusinessException.class,
+				() -> service.updateNickname(
+						userId.toString(),
+						new UpdateProfileRequest("昵称")));
+
+		assertEquals("PROFILE_UPDATE_CONFLICT", exception.code());
+	}
+
+	@Test
+	void replacesAvatarAndDeletesPreviousObject() {
+		UUID userId = UUID.randomUUID();
+		byte[] original = {1, 2, 3};
+		byte[] processed = {4, 5, 6};
+		UserAccount user = user(userId, "old/avatar.png");
+		when(storage.available()).thenReturn(true);
+		when(accounts.findById(userId)).thenReturn(Optional.of(user));
+		when(images.process(original))
+				.thenReturn(new ProcessedAvatar(processed, "image/png", "png"));
+		when(accounts.updateAvatarObjectKey(eq(userId), eq("old/avatar.png"), any()))
+				.thenReturn(true);
+		when(storage.signGetUrl(any(), eq(Duration.ofMinutes(30))))
+				.thenReturn(URI.create("https://cdn.example/avatar.png"));
+
+		AvatarResponse response = service.replaceAvatar(userId.toString(), original);
+
+		assertEquals("https://cdn.example/avatar.png", response.avatarUrl());
+		assertNotNull(response.avatarUrlExpiresAt());
+		verify(storage).put(
+				org.mockito.ArgumentMatchers.startsWith(
+						"profile-avatars/" + userId + "/"),
+				eq(processed),
+				eq("image/png"));
+		verify(storage).delete("old/avatar.png");
+	}
+
+	@Test
+	void rejectsAvatarWhenStorageIsUnavailable() {
+		when(storage.available()).thenReturn(false);
+
+		BusinessException exception = assertThrows(
+				BusinessException.class,
+				() -> service.replaceAvatar(UUID.randomUUID().toString(), new byte[] {1}));
+
+		assertEquals("AVATAR_STORAGE_UNAVAILABLE", exception.code());
+		verify(accounts, never()).findById(any());
+	}
+
+	@Test
+	void rejectsAvatarForMissingUser() {
+		UUID userId = UUID.randomUUID();
+		when(storage.available()).thenReturn(true);
+		when(accounts.findById(userId)).thenReturn(Optional.empty());
+
+		BusinessException exception = assertThrows(
+				BusinessException.class,
+				() -> service.replaceAvatar(userId.toString(), new byte[] {1}));
+
+		assertEquals("USER_NOT_FOUND", exception.code());
+	}
+
+	@Test
+	void deletesUploadedAvatarWhenConcurrentUpdateWins() {
+		UUID userId = UUID.randomUUID();
+		when(storage.available()).thenReturn(true);
+		when(accounts.findById(userId)).thenReturn(Optional.of(user(userId, null)));
+		when(images.process(any()))
+				.thenReturn(new ProcessedAvatar(new byte[] {2}, "image/jpeg", "jpg"));
+		when(accounts.updateAvatarObjectKey(eq(userId), eq(null), any()))
+				.thenReturn(false);
+
+		BusinessException exception = assertThrows(
+				BusinessException.class,
+				() -> service.replaceAvatar(userId.toString(), new byte[] {1}));
+
+		assertEquals("PROFILE_UPDATE_CONFLICT", exception.code());
+		verify(storage).delete(org.mockito.ArgumentMatchers.contains(userId.toString()));
+	}
+
+	@Test
+	void keepsSuccessfulAvatarUpdateWhenSigningAndCleanupFail() {
+		UUID userId = UUID.randomUUID();
+		when(storage.available()).thenReturn(true);
+		when(accounts.findById(userId)).thenReturn(Optional.of(user(userId, "old.png")));
+		when(images.process(any()))
+				.thenReturn(new ProcessedAvatar(new byte[] {2}, "image/png", "png"));
+		when(accounts.updateAvatarObjectKey(eq(userId), eq("old.png"), any()))
+				.thenReturn(true);
+		when(storage.signGetUrl(any(), any()))
+				.thenThrow(new BusinessException("SIGN_FAILED", "签名失败"));
+		doThrow(new BusinessException("DELETE_FAILED", "删除失败"))
+				.when(storage).delete("old.png");
+
+		AvatarResponse response = service.replaceAvatar(userId.toString(), new byte[] {1});
+
+		assertNull(response.avatarUrl());
+		assertNull(response.avatarUrlExpiresAt());
+		verify(storage).delete("old.png");
+	}
+
+	private UserAccount user(UUID id, String avatarObjectKey) {
+		Instant now = Instant.parse("2026-08-03T00:00:00Z");
+		return new UserAccount(
+				id,
+				"learner@example.com",
+				"hash",
+				"学习者",
+				avatarObjectKey,
+				UserRole.USER,
+				UserStatus.ACTIVE,
+				1,
+				now,
+				now,
+				now);
+	}
+}

From 55465c724b4ab95afb3a3a1c933deeecb3072652 Mon Sep 17 00:00:00 2001
From: suerzzh <zfl18720351635@gnail.com>
Date: Mon, 3 Aug 2026 16:10:07 +0800
Subject: [PATCH 62/62] =?UTF-8?q?feat:=20=E4=BF=AE=E5=A4=8D=E6=95=B0?=
 =?UTF-8?q?=E6=8D=AE=E5=BA=93=E8=BF=81=E7=A7=BB=E9=9B=86=E6=88=90=E6=B5=8B?=
 =?UTF-8?q?=E8=AF=95=E6=96=AD=E8=A8=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../com/unispeaking/integration/PostgresPersistenceIT.java    | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend/unispeaking-server/src/test/java/com/unispeaking/integration/PostgresPersistenceIT.java b/backend/unispeaking-server/src/test/java/com/unispeaking/integration/PostgresPersistenceIT.java
index fd5d6d6..c95a7c2 100644
--- a/backend/unispeaking-server/src/test/java/com/unispeaking/integration/PostgresPersistenceIT.java
+++ b/backend/unispeaking-server/src/test/java/com/unispeaking/integration/PostgresPersistenceIT.java
@@ -129,7 +129,7 @@ void migratesEmptyDatabaseAndRegistersFlywayHistory() {
 				""",
 				String.class);
 
-		assertEquals(1, migrationCount);
+		assertEquals(2, migrationCount);
 		assertEquals("jsonb", successFactorType);
 	}
 
@@ -388,7 +388,7 @@ status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE',
 						"SELECT COUNT(*) FROM legacy_ci.\"user\" WHERE username = 'legacy@example.com'",
 						Integer.class));
 		assertEquals(
-				List.of("0", "1"),
+				List.of("0", "1", "2"),
 				jdbcTemplate.queryForList(
 						"""
 						SELECT version