feat(education): submit sessions and persist reports

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/controller/admin/EducationCapabilityController.java

@@ -35,7 +35,8 @@ public class EducationCapabilityController {
                 .module("education")
                 .enabled(educationProperties.isEnabled())
                 .version(educationProperties.getVersion())
-                .capabilities(List.of("shell", "catalog", "questions", "practice-preview", "answer-save"))
+                .capabilities(List.of("shell", "catalog", "questions", "practice-preview",
+                        "answer-save", "session-submit", "practice-report"))
                 .build();
         return success(resp);
     }

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/controller/app/practice/PracticeSessionController.java

@@ -1,17 +1,22 @@
 package cn.iocoder.yudao.module.education.controller.app.practice;
 
 import cn.iocoder.yudao.framework.common.pojo.CommonResult;
+import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.framework.security.core.LoginUser;
 import cn.iocoder.yudao.framework.security.core.util.SecurityFrameworkUtils;
 import cn.iocoder.yudao.module.education.controller.app.practice.vo.PracticeAnswerReqVO;
 import cn.iocoder.yudao.module.education.controller.app.practice.vo.PracticeAnswerRespVO;
 import cn.iocoder.yudao.module.education.controller.app.practice.vo.PracticeSessionCreateReqVO;
 import cn.iocoder.yudao.module.education.controller.app.practice.vo.PracticeSessionRespVO;
+import cn.iocoder.yudao.module.education.controller.app.practice.vo.PracticeSubmitReqVO;
+import cn.iocoder.yudao.module.education.controller.app.practice.vo.PracticeSubmitRespVO;
 import cn.iocoder.yudao.module.education.service.practice.PracticeSessionService;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.Resource;
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
 import jakarta.validation.Valid;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.validation.annotation.Validated;
@@ -46,20 +51,14 @@ public class PracticeSessionController {
             description = "根据练习配置创建一次持久化练习。同一 clientSessionId 重复调用返回已有会话。"
                     + "题目顺序由服务端固定，选项不含答案标记。")
     public CommonResult<PracticeSessionRespVO> createSession(@Valid @RequestBody PracticeSessionCreateReqVO reqVO) {
-        Long userId = getUserId();
-        Long tenantId = getTenantId();
-        PracticeSessionRespVO resp = practiceSessionService.createPracticeSession(reqVO, userId, tenantId);
-        return success(resp);
+        return success(practiceSessionService.createPracticeSession(reqVO, getUserId(), getTenantId()));
     }
 
     @GetMapping("/practice-session/current")
     @Operation(summary = "获取当前进行中的练习会话",
             description = "返回当前用户最近一条 ACTIVE 状态的练习会话，用于刷新恢复。无进行中会话时返回 data=null。")
     public CommonResult<PracticeSessionRespVO> currentSession() {
-        Long userId = getUserId();
-        Long tenantId = getTenantId();
-        PracticeSessionRespVO resp = practiceSessionService.getCurrentSession(userId, tenantId);
-        return success(resp);
+        return success(practiceSessionService.getCurrentSession(getUserId(), getTenantId()));
     }
 
     @GetMapping("/practice-session/get")
@@ -67,10 +66,7 @@ public class PracticeSessionController {
             description = "按会话 ID 获取会话详情，必须验证租户和用户所有权。")
     public CommonResult<PracticeSessionRespVO> getSession(
             @Parameter(description = "会话 ID", required = true) @RequestParam Long id) {
-        Long userId = getUserId();
-        Long tenantId = getTenantId();
-        PracticeSessionRespVO resp = practiceSessionService.getSession(id, userId, tenantId);
-        return success(resp);
+        return success(practiceSessionService.getSession(id, getUserId(), getTenantId()));
     }
 
     // ========== 答案保存 ==========
@@ -81,27 +77,55 @@ public class PracticeSessionController {
                     + "旧 clientSequence 或旧 expectedSessionVersion 拒绝覆盖。"
                     + "客户端根据响应中的 serverVersion 和 acceptedSequence 更新本地状态。")
     public CommonResult<PracticeAnswerRespVO> submitAnswer(@Valid @RequestBody PracticeAnswerReqVO reqVO) {
-        Long userId = getUserId();
-        Long tenantId = getTenantId();
-        PracticeAnswerRespVO resp = practiceSessionService.submitAnswer(reqVO, userId, tenantId);
-        return success(resp);
+        return success(practiceSessionService.submitAnswer(reqVO, getUserId(), getTenantId()));
+    }
+
+    // ========== 交卷提交 ==========
+
+    @PostMapping("/practice-session/submit")
+    @Operation(summary = "交卷提交（幂等，原子单向状态转换）",
+            description = "提交练习会话完成评分。ACTIVE→SUBMITTED 原子单向转换。"
+                    + "同一 idempotencyKey + 相同载荷返回首次评分报告（超时重试安全）。"
+                    + "交卷后不可再修改答案。")
+    public CommonResult<PracticeSubmitRespVO> submitSession(@Valid @RequestBody PracticeSubmitReqVO reqVO) {
+        return success(practiceSessionService.submitSession(reqVO, getUserId(), getTenantId()));
+    }
+
+    // ========== 报告查看 ==========
+
+    @GetMapping("/practice-session/report")
+    @Operation(summary = "获取会话评分报告",
+            description = "按会话 ID 获取评分报告，含逐题结果、正确答案和解析。仅已提交会话可用。")
+    public CommonResult<PracticeSubmitRespVO> getReport(
+            @Parameter(description = "会话 ID", required = true) @RequestParam Long sessionId) {
+        return success(practiceSessionService.getReport(sessionId, getUserId(), getTenantId()));
+    }
+
+    @GetMapping("/practice-session/reports")
+    @Operation(summary = "分页查询练习历史报告",
+            description = "分页查询当前用户的历史练习报告列表，按创建时间降序。仅返回本人记录。")
+    public CommonResult<PageResult<PracticeSubmitRespVO>> getReportHistory(
+            @Parameter(description = "页码", example = "1") @RequestParam(defaultValue = "1") @Min(1) int pageNo,
+            @Parameter(description = "每页条数", example = "10") @RequestParam(defaultValue = "10") @Min(1) @Max(100) int pageSize) {
+        return success(practiceSessionService.getReportHistory(getUserId(), getTenantId(), pageNo, pageSize));
     }
 
     // ========== security helpers ==========
 
     private Long getUserId() {
-        Long userId = SecurityFrameworkUtils.getLoginUserId();
-        if (userId == null) {
+        LoginUser loginUser = SecurityFrameworkUtils.getLoginUser();
+        if (loginUser == null) {
             throw exception(UNAUTHORIZED);
         }
-        return userId;
+        return loginUser.getId();
     }
 
     private Long getTenantId() {
         LoginUser loginUser = SecurityFrameworkUtils.getLoginUser();
-        if (loginUser == null || loginUser.getTenantId() == null) {
+        if (loginUser == null) {
             throw exception(UNAUTHORIZED);
         }
         return loginUser.getTenantId();
     }
+
 }

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/controller/app/practice/vo/PracticeReportDetailRespVO.java

@@ -0,0 +1,50 @@
+package cn.iocoder.yudao.module.education.controller.app.practice.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * 报告逐题明细响应 VO — 含正确答案和解析。
+ *
+ * <p>仅在报告查看接口中暴露，创建/获取会话接口中绝不出现在响应中。</p>
+ *
+ * @author 恭学教育
+ */
+@Schema(description = "用户 APP - 报告逐题明细响应")
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class PracticeReportDetailRespVO {
+
+    @Schema(description = "题目序号（1-based）", requiredMode = Schema.RequiredMode.REQUIRED, example = "1")
+    private Integer sequence;
+
+    @Schema(description = "原始题目 ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "q-001")
+    private String questionId;
+
+    @Schema(description = "题干", requiredMode = Schema.RequiredMode.REQUIRED, example = "1+1等于几？")
+    private String stem;
+
+    @Schema(description = "题型", requiredMode = Schema.RequiredMode.REQUIRED, example = "choice")
+    private String type;
+
+    @Schema(description = "难度", example = "easy")
+    private String difficulty;
+
+    @Schema(description = "学生已选答案", example = "A")
+    private String selectedAnswer;
+
+    @Schema(description = "正确答案", example = "B")
+    private String correctAnswer;
+
+    @Schema(description = "是否正确", requiredMode = Schema.RequiredMode.REQUIRED, example = "false")
+    private Boolean isCorrect;
+
+    @Schema(description = "解析", example = "1+1=2，因此正确答案为 B")
+    private String explanation;
+
+}

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/controller/app/practice/vo/PracticeSubmitReqVO.java

@@ -0,0 +1,34 @@
+package cn.iocoder.yudao.module.education.controller.app.practice.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+/**
+ * 交卷提交请求 VO。
+ *
+ * @author 恭学教育
+ */
+@Schema(description = "用户 APP - 交卷提交请求")
+@Data
+public class PracticeSubmitReqVO {
+
+    @Schema(description = "会话 ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "1001")
+    @NotNull(message = "会话 ID 不能为空")
+    private Long sessionId;
+
+    @Schema(description = "客户端幂等键（UUID）", requiredMode = Schema.RequiredMode.REQUIRED,
+            example = "550e8400-e29b-41d4-a716-446655440000")
+    @NotBlank(message = "幂等键不能为空")
+    @Size(max = 64, message = "幂等键长度不能超过 64 字符")
+    private String idempotencyKey;
+
+    @Schema(description = "客户端期望的会话版本号", requiredMode = Schema.RequiredMode.REQUIRED, example = "5")
+    @NotNull(message = "期望会话版本号不能为空")
+    @Min(value = 1, message = "期望会话版本号必须为正整数")
+    private Integer expectedSessionVersion;
+
+}

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/controller/app/practice/vo/PracticeSubmitRespVO.java

@@ -0,0 +1,52 @@
+package cn.iocoder.yudao.module.education.controller.app.practice.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.List;
+
+/**
+ * 交卷提交响应 VO — 评分总览 + 逐题结果。
+ *
+ * <p>包含报告 ID、得分统计和逐题明细。明细中才暴露正确答案和解析。</p>
+ *
+ * @author 恭学教育
+ */
+@Schema(description = "用户 APP - 交卷提交响应")
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class PracticeSubmitRespVO {
+
+    @Schema(description = "报告 ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "5001")
+    private Long reportId;
+
+    @Schema(description = "会话 ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "1001")
+    private Long sessionId;
+
+    @Schema(description = "题目总数", requiredMode = Schema.RequiredMode.REQUIRED, example = "10")
+    private Integer questionCount;
+
+    @Schema(description = "已答题数", requiredMode = Schema.RequiredMode.REQUIRED, example = "8")
+    private Integer answeredCount;
+
+    @Schema(description = "未答题数", requiredMode = Schema.RequiredMode.REQUIRED, example = "2")
+    private Integer unansweredCount;
+
+    @Schema(description = "正确题数", requiredMode = Schema.RequiredMode.REQUIRED, example = "6")
+    private Integer correctCount;
+
+    @Schema(description = "错误题数", requiredMode = Schema.RequiredMode.REQUIRED, example = "2")
+    private Integer incorrectCount;
+
+    @Schema(description = "得分（整数，满分 100 为基准）", requiredMode = Schema.RequiredMode.REQUIRED, example = "75")
+    private Integer score;
+
+    @Schema(description = "逐题明细（含正确答案和解析）")
+    private List<PracticeReportDetailRespVO> details;
+
+}

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/dal/dataobject/PracticeQuestionDO.java

@@ -48,6 +48,12 @@ public class PracticeQuestionDO extends TenantBaseDO {
     /** 选项快照 JSON — 仅含 label、content、order，不含 isCorrect */
     private String options;
 
+    /** 正确答案快照 — 不可在交卷前暴露，JSON 格式 */
+    private String correctAnswer;
+
+    /** 解析快照 — 不可在交卷前暴露 */
+    private String explanation;
+
     /** 学生已选答案 */
     private String selectedAnswer;
 

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/dal/dataobject/PracticeReportDO.java

@@ -0,0 +1,54 @@
+package cn.iocoder.yudao.module.education.dal.dataobject;
+
+import cn.iocoder.yudao.framework.tenant.core.db.TenantBaseDO;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.*;
+
+/**
+ * 练习报告 DO — 会话级评分结果。
+ *
+ * <p>一个会话最多一份报告（uk_report_session）。创建后不可变。
+ * 题目级结果存储在 PracticeReportDetailDO 中。</p>
+ *
+ * @author 恭学教育
+ */
+@TableName("education_practice_report")
+@Data
+@EqualsAndHashCode(callSuper = true)
+@NoArgsConstructor
+@AllArgsConstructor
+public class PracticeReportDO extends TenantBaseDO {
+
+    /** 主键 */
+    @TableId
+    private Long id;
+
+    /** 用户编号 */
+    private Long userId;
+
+    /** 会话 ID */
+    private Long sessionId;
+
+    /** 题目总数 */
+    private Integer questionCount;
+
+    /** 已答题数 */
+    private Integer answeredCount;
+
+    /** 未答题数 */
+    private Integer unansweredCount;
+
+    /** 正确题数 */
+    private Integer correctCount;
+
+    /** 错误题数 */
+    private Integer incorrectCount;
+
+    /** 得分（整数，满分 100 为基准） */
+    private Integer score;
+
+    /** 报告状态 */
+    private String status;
+
+}

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/dal/dataobject/PracticeReportDetailDO.java

@@ -0,0 +1,63 @@
+package cn.iocoder.yudao.module.education.dal.dataobject;
+
+import cn.iocoder.yudao.framework.tenant.core.db.TenantBaseDO;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.*;
+
+/**
+ * 练习报告明细 DO — 逐题评分结果。
+ *
+ * <p>交卷时从会话题目快照计算，含题干、学生答案、正确答案和解析的快照。
+ * 创建后不可变，确保历史报告不受后续题目修改影响。</p>
+ *
+ * @author 恭学教育
+ */
+@TableName("education_practice_report_detail")
+@Data
+@EqualsAndHashCode(callSuper = true)
+@NoArgsConstructor
+@AllArgsConstructor
+public class PracticeReportDetailDO extends TenantBaseDO {
+
+    /** 主键 */
+    @TableId
+    private Long id;
+
+    /** 用户编号 */
+    private Long userId;
+
+    /** 报告 ID */
+    private Long reportId;
+
+    /** 会话 ID */
+    private Long sessionId;
+
+    /** 原始题目 ID */
+    private String questionId;
+
+    /** 题目序号（1-based） */
+    private Integer sequence;
+
+    /** 题干快照 */
+    private String stem;
+
+    /** 题型快照 */
+    private String type;
+
+    /** 难度快照 */
+    private String difficulty;
+
+    /** 学生已选答案 */
+    private String selectedAnswer;
+
+    /** 正确答案快照 */
+    private String correctAnswer;
+
+    /** 是否正确 */
+    private Boolean isCorrect;
+
+    /** 解析快照 */
+    private String explanation;
+
+}

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/dal/dataobject/SubmitIdempotencyDO.java

@@ -0,0 +1,52 @@
+package cn.iocoder.yudao.module.education.dal.dataobject;
+
+import cn.iocoder.yudao.framework.tenant.core.db.TenantBaseDO;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.*;
+
+/**
+ * 交卷幂等记录 DO。
+ *
+ * <p>同一 (tenant, user, operation, idempotencyKey) 的唯一约束保证幂等性。
+ * requestHash 用于检测相同键不同载荷的冲突。
+ * responseJson 存储首次成功的完整报告 JSON，用于超时重试重放。</p>
+ *
+ * @author 恭学教育
+ */
+@TableName("education_submit_idempotency")
+@Data
+@EqualsAndHashCode(callSuper = true)
+@NoArgsConstructor
+@AllArgsConstructor
+public class SubmitIdempotencyDO extends TenantBaseDO {
+
+    /** 主键 */
+    @TableId
+    private Long id;
+
+    /** 交卷用户编号 */
+    private Long userId;
+
+    /** 操作类型：SUBMIT_SESSION */
+    private String operation;
+
+    /** 客户端幂等键（UUID） */
+    private String idempotencyKey;
+
+    /** 请求载荷 SHA-256 哈希 */
+    private String requestHash;
+
+    /** 会话 ID */
+    private Long sessionId;
+
+    /** 关联的报告 ID（成功时有值） */
+    private Long reportId;
+
+    /** 状态：ACCEPTED / CONFLICT */
+    private String status;
+
+    /** 首次成功响应 JSON（用于重试重放） */
+    private String responseJson;
+
+}

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/dal/mysql/AnswerIdempotencyMapper.java

@@ -3,7 +3,9 @@ package cn.iocoder.yudao.module.education.dal.mysql;
 import cn.iocoder.yudao.framework.mybatis.core.mapper.BaseMapperX;
 import cn.iocoder.yudao.framework.mybatis.core.query.LambdaQueryWrapperX;
 import cn.iocoder.yudao.module.education.dal.dataobject.AnswerIdempotencyDO;
+import org.apache.ibatis.annotations.Insert;
 import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Options;
 
 /**
  * 答案命令幂等记录 Mapper。
@@ -24,4 +26,18 @@ public interface AnswerIdempotencyMapper extends BaseMapperX<AnswerIdempotencyDO
                 .eq(AnswerIdempotencyDO::getIdempotencyKey, idempotencyKey));
     }
 
+    /**
+     * INSERT IGNORE — attempt insertion; returns 1 if inserted, 0 if duplicate was silently ignored.
+     * Safe for concurrent same-key resolution without DuplicateKeyException.
+     */
+    @Insert("INSERT IGNORE INTO education_answer_idempotency " +
+            "(tenant_id, user_id, operation, idempotency_key, request_hash, session_id, " +
+            "question_id, selected_answer, status, response_json, " +
+            "creator, create_time, updater, update_time, deleted) " +
+            "VALUES (#{tenantId}, #{userId}, #{operation}, #{idempotencyKey}, #{requestHash}, " +
+            "#{sessionId}, #{questionId}, #{selectedAnswer}, #{status}, #{responseJson}, " +
+            "#{creator}, #{createTime}, #{updater}, #{updateTime}, FALSE)")
+    @Options(useGeneratedKeys = true, keyProperty = "id")
+    int insertIgnore(AnswerIdempotencyDO record);
+
 }

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/dal/mysql/PracticeReportDetailMapper.java

@@ -0,0 +1,38 @@
+package cn.iocoder.yudao.module.education.dal.mysql;
+
+import cn.iocoder.yudao.framework.mybatis.core.mapper.BaseMapperX;
+import cn.iocoder.yudao.framework.mybatis.core.query.LambdaQueryWrapperX;
+import cn.iocoder.yudao.module.education.dal.dataobject.PracticeReportDetailDO;
+import org.apache.ibatis.annotations.Mapper;
+
+import java.util.List;
+
+/**
+ * 练习报告明细 Mapper。
+ *
+ * @author 恭学教育
+ */
+@Mapper
+public interface PracticeReportDetailMapper extends BaseMapperX<PracticeReportDetailDO> {
+    /**
+     * 按报告 ID、租户、用户查询所有明细，按 sequence 升序。
+     * Ownership check: tenant + user must match the report owner.
+     */
+    default List<PracticeReportDetailDO> selectByReportIdAndTenantAndUser(Long reportId, Long tenantId, Long userId) {
+        return selectList(new LambdaQueryWrapperX<PracticeReportDetailDO>()
+                .eq(PracticeReportDetailDO::getReportId, reportId)
+                .eq(PracticeReportDetailDO::getTenantId, tenantId)
+                .eq(PracticeReportDetailDO::getUserId, userId)
+                .orderByAsc(PracticeReportDetailDO::getSequence));
+    }
+
+    /**
+     * 按报告 ID 查询所有明细，按 sequence 升序。
+     * Prefer {@link #selectByReportIdAndTenantAndUser} when tenant/user context is available.
+     */
+    default List<PracticeReportDetailDO> selectByReportIdOrderBySequence(Long reportId) {
+        return selectList(new LambdaQueryWrapperX<PracticeReportDetailDO>()
+                .eq(PracticeReportDetailDO::getReportId, reportId)
+                .orderByAsc(PracticeReportDetailDO::getSequence));
+    }
+}

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/dal/mysql/PracticeReportMapper.java

@@ -0,0 +1,52 @@
+package cn.iocoder.yudao.module.education.dal.mysql;
+
+import cn.iocoder.yudao.framework.mybatis.core.mapper.BaseMapperX;
+import cn.iocoder.yudao.framework.mybatis.core.query.LambdaQueryWrapperX;
+import cn.iocoder.yudao.module.education.dal.dataobject.PracticeReportDO;
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import org.apache.ibatis.annotations.Insert;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Options;
+
+/**
+ * 练习报告 Mapper。
+ *
+ * @author 恭学教育
+ */
+@Mapper
+public interface PracticeReportMapper extends BaseMapperX<PracticeReportDO> {
+
+    /**
+     * 按会话 ID 和租户查找报告。
+     */
+    default PracticeReportDO selectBySessionIdAndTenant(Long sessionId, Long tenantId) {
+        return selectOne(new LambdaQueryWrapperX<PracticeReportDO>()
+                .eq(PracticeReportDO::getSessionId, sessionId)
+                .eq(PracticeReportDO::getTenantId, tenantId));
+    }
+
+    /**
+     * 按租户和用户分页查询报告，按创建时间降序。
+     */
+    default IPage<PracticeReportDO> selectPageByTenantAndUser(IPage<PracticeReportDO> page, Long tenantId, Long userId) {
+        return selectPage(page, new LambdaQueryWrapperX<PracticeReportDO>()
+                .eq(PracticeReportDO::getTenantId, tenantId)
+                .eq(PracticeReportDO::getUserId, userId)
+                .orderByDesc(PracticeReportDO::getCreateTime));
+    }
+
+    /**
+     * INSERT IGNORE — attempt insertion; returns 1 if inserted, 0 if duplicate (uk_report_session) was silently ignored.
+     * Safe for concurrent submit race resolution without DuplicateKeyException.
+     */
+    @Insert("INSERT IGNORE INTO education_practice_report " +
+            "(tenant_id, user_id, session_id, question_count, answered_count, unanswered_count, " +
+            "correct_count, incorrect_count, score, status, " +
+            "creator, create_time, updater, update_time, deleted) " +
+            "VALUES (#{tenantId}, #{userId}, #{sessionId}, #{questionCount}, #{answeredCount}, #{unansweredCount}, " +
+            "#{correctCount}, #{incorrectCount}, #{score}, #{status}, " +
+            "#{creator}, #{createTime}, #{updater}, #{updateTime}, FALSE)")
+    @Options(useGeneratedKeys = true, keyProperty = "id")
+    int insertIgnore(PracticeReportDO record);
+
+}

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/dal/mysql/SubmitIdempotencyMapper.java

@@ -0,0 +1,43 @@
+package cn.iocoder.yudao.module.education.dal.mysql;
+
+import cn.iocoder.yudao.framework.mybatis.core.mapper.BaseMapperX;
+import cn.iocoder.yudao.framework.mybatis.core.query.LambdaQueryWrapperX;
+import cn.iocoder.yudao.module.education.dal.dataobject.SubmitIdempotencyDO;
+import org.apache.ibatis.annotations.Insert;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Options;
+
+/**
+ * 交卷幂等记录 Mapper。
+ *
+ * @author 恭学教育
+ */
+@Mapper
+public interface SubmitIdempotencyMapper extends BaseMapperX<SubmitIdempotencyDO> {
+
+    /**
+     * 按租户、用户、操作、幂等键查找记录。
+     */
+    default SubmitIdempotencyDO selectByKey(Long tenantId, Long userId, String operation, String idempotencyKey) {
+        return selectOne(new LambdaQueryWrapperX<SubmitIdempotencyDO>()
+                .eq(SubmitIdempotencyDO::getTenantId, tenantId)
+                .eq(SubmitIdempotencyDO::getUserId, userId)
+                .eq(SubmitIdempotencyDO::getOperation, operation)
+                .eq(SubmitIdempotencyDO::getIdempotencyKey, idempotencyKey));
+    }
+
+    /**
+     * INSERT IGNORE — attempt insertion; returns 1 if inserted, 0 if duplicate was silently ignored.
+     * Safe for concurrent same-key resolution without DuplicateKeyException.
+     */
+    @Insert("INSERT IGNORE INTO education_submit_idempotency " +
+            "(tenant_id, user_id, operation, idempotency_key, request_hash, session_id, " +
+            "report_id, status, response_json, " +
+            "creator, create_time, updater, update_time, deleted) " +
+            "VALUES (#{tenantId}, #{userId}, #{operation}, #{idempotencyKey}, #{requestHash}, " +
+            "#{sessionId}, #{reportId}, #{status}, #{responseJson}, " +
+            "#{creator}, #{createTime}, #{updater}, #{updateTime}, FALSE)")
+    @Options(useGeneratedKeys = true, keyProperty = "id")
+    int insertIgnore(SubmitIdempotencyDO record);
+
+}

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/enums/ErrorCodeConstants.java

@@ -65,4 +65,13 @@ public interface ErrorCodeConstants {
     ErrorCode ANSWER_STALE_CROSS_QUESTION_SEQUENCE = new ErrorCode(1_005_003_022, "客户端命令序号过期（跨题目），当前序号 {} 不大于会话已接受的 {}");
     ErrorCode CATALOG_UPSTREAM_OPTIONS_MALFORMED = new ErrorCode(1_005_003_023, "题目选项数据格式异常，请稍后重试");
     ErrorCode ANSWER_FIELD_TOO_LONG = new ErrorCode(1_005_003_024, "请求字段过长：{}");
+
+    // ========== 交卷提交 1-005-003-030 ~ 1-005-003-039 ==========
+    ErrorCode SUBMIT_SESSION_NOT_ACTIVE = new ErrorCode(1_005_003_030, "会话不是进行中状态，无法交卷");
+    ErrorCode SUBMIT_IDEMPOTENCY_CONFLICT = new ErrorCode(1_005_003_031, "交卷幂等键相同但请求内容不一致，请刷新重试");
+    ErrorCode SUBMIT_STALE_VERSION = new ErrorCode(1_005_003_032, "会话版本已更新，请刷新后重新交卷（期望版本：{}，当前版本：{}）");
+    ErrorCode SUBMIT_CONCURRENT_CONFLICT = new ErrorCode(1_005_003_033, "交卷失败：会话状态已被其他请求变更，请重试");
+    ErrorCode REPORT_NOT_FOUND = new ErrorCode(1_005_003_034, "报告不存在");
+    ErrorCode REPORT_NOT_OWN = new ErrorCode(1_005_003_035, "无权访问该报告");
+    ErrorCode REPORT_SESSION_NOT_SUBMITTED = new ErrorCode(1_005_003_036, "会话尚未提交，报告不可用");
 }

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/service/practice/PracticeSessionService.java

@@ -1,9 +1,12 @@
 package cn.iocoder.yudao.module.education.service.practice;
 
+import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.module.education.controller.app.practice.vo.PracticeAnswerReqVO;
 import cn.iocoder.yudao.module.education.controller.app.practice.vo.PracticeAnswerRespVO;
 import cn.iocoder.yudao.module.education.controller.app.practice.vo.PracticeSessionCreateReqVO;
 import cn.iocoder.yudao.module.education.controller.app.practice.vo.PracticeSessionRespVO;
+import cn.iocoder.yudao.module.education.controller.app.practice.vo.PracticeSubmitReqVO;
+import cn.iocoder.yudao.module.education.controller.app.practice.vo.PracticeSubmitRespVO;
 
 /**
  * 练习会话服务接口。
@@ -57,4 +60,41 @@ public interface PracticeSessionService {
      */
     PracticeAnswerRespVO submitAnswer(PracticeAnswerReqVO reqVO, Long userId, Long tenantId);
 
+    /**
+     * 幂等交卷提交 — ACTIVE→SUBMITTED 原子单向状态转换。
+     *
+     * <p>同一 idempotencyKey + 相同载荷 → 返回首次评分报告（超时重试安全）。
+     * 同一 idempotencyKey + 不同载荷 → 业务冲突。
+     * 并发提交仅第一个完成评分和持久化，其余返回首次结果。</p>
+     *
+     * <p>评分使用会话固定的题目快照及答案版本，交卷后不可再修改答案。</p>
+     *
+     * @param reqVO 交卷请求
+     * @param userId 当前用户 ID（由安全上下文派生）
+     * @param tenantId 当前租户 ID（由安全上下文派生）
+     * @return 评分报告
+     */
+    PracticeSubmitRespVO submitSession(PracticeSubmitReqVO reqVO, Long userId, Long tenantId);
+
+    /**
+     * 获取会话评分报告（仅已提交会话）。
+     *
+     * @param sessionId 会话 ID
+     * @param userId 当前用户 ID
+     * @param tenantId 当前租户 ID
+     * @return 评分报告（含逐题明细和解析）
+     */
+    PracticeSubmitRespVO getReport(Long sessionId, Long userId, Long tenantId);
+
+    /**
+     * 分页查询当前用户的历史练习报告。
+     *
+     * @param userId 当前用户 ID
+     * @param tenantId 当前租户 ID
+     * @param pageNo 页码（从 1 开始）
+     * @param pageSize 每页条数
+     * @return 分页报告列表
+     */
+    PageResult<PracticeSubmitRespVO> getReportHistory(Long userId, Long tenantId, int pageNo, int pageSize);
+
 }

yudao-module-education/src/main/java/cn/iocoder/yudao/module/education/service/practice/PracticeSessionServiceImpl.java

@@ -2,31 +2,27 @@ package cn.iocoder.yudao.module.education.service.practice;
 
 import cn.hutool.core.collection.CollUtil;
 import cn.hutool.crypto.digest.DigestUtil;
+import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.framework.common.util.json.JsonUtils;
 import cn.iocoder.yudao.module.education.controller.app.practice.vo.*;
-import cn.iocoder.yudao.module.education.dal.dataobject.AnswerIdempotencyDO;
-import cn.iocoder.yudao.module.education.dal.dataobject.PracticeQuestionDO;
-import cn.iocoder.yudao.module.education.dal.dataobject.PracticeSessionDO;
-import cn.iocoder.yudao.module.education.dal.mysql.AnswerIdempotencyMapper;
-import cn.iocoder.yudao.module.education.dal.mysql.PracticeQuestionMapper;
-import cn.iocoder.yudao.module.education.dal.mysql.PracticeSessionMapper;
+import cn.iocoder.yudao.module.education.dal.dataobject.*;
+import cn.iocoder.yudao.module.education.dal.mysql.*;
 import cn.iocoder.yudao.module.education.service.question.QuestionCatalogProvider;
 import cn.iocoder.yudao.module.education.service.question.dto.CatalogQuestionDTO;
 import cn.iocoder.yudao.module.education.service.question.dto.CatalogQuestionPageResult;
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 import org.springframework.dao.DuplicateKeyException;
-
-import java.nio.charset.StandardCharsets;
 import java.util.*;
 import java.util.stream.Collectors;
 
 import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
 import static cn.iocoder.yudao.module.education.enums.ErrorCodeConstants.*;
 
-
 /**
  * 练习会话服务实现。
  *
@@ -40,15 +36,24 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
     private final PracticeSessionMapper sessionMapper;
     private final PracticeQuestionMapper questionMapper;
     private final AnswerIdempotencyMapper idempotencyMapper;
+    private final SubmitIdempotencyMapper submitIdempotencyMapper;
+    private final PracticeReportMapper reportMapper;
+    private final PracticeReportDetailMapper reportDetailMapper;
     private final QuestionCatalogProvider questionCatalogProvider;
 
     public PracticeSessionServiceImpl(PracticeSessionMapper sessionMapper,
                                        PracticeQuestionMapper questionMapper,
                                        AnswerIdempotencyMapper idempotencyMapper,
+                                       SubmitIdempotencyMapper submitIdempotencyMapper,
+                                       PracticeReportMapper reportMapper,
+                                       PracticeReportDetailMapper reportDetailMapper,
                                        QuestionCatalogProvider questionCatalogProvider) {
         this.sessionMapper = sessionMapper;
         this.questionMapper = questionMapper;
         this.idempotencyMapper = idempotencyMapper;
+        this.submitIdempotencyMapper = submitIdempotencyMapper;
+        this.reportMapper = reportMapper;
+        this.reportDetailMapper = reportDetailMapper;
         this.questionCatalogProvider = questionCatalogProvider;
     }
 
@@ -59,7 +64,6 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
         PracticeSessionDO existing = sessionMapper.selectByTenantAndClientSessionId(tenantId, reqVO.getClientSessionId());
         if (existing != null) {
             if (!Objects.equals(existing.getUserId(), userId)) {
-                // Same tenant, same clientSessionId, but different user → ownership violation
                 throw exception(SESSION_NOT_FOUND);
             }
             if (!isSameFingerprint(existing, reqVO)) {
@@ -73,7 +77,7 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
         List<CatalogQuestionDTO> questions = fetchAndOrderQuestions(reqVO.getCollectionId(), reqVO.getNodeId(),
                 reqVO.getType(), reqVO.getDifficulty(), requestedCount);
 
-        // 2a. Reject underfilled sessions: fewer visible questions than requested
+        // 2a. Reject underfilled sessions
         if (questions.size() < requestedCount) {
             throw exception(INSUFFICIENT_ELIGIBLE_QUESTIONS, questions.size(), requestedCount);
         }
@@ -94,13 +98,10 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
         try {
             sessionMapper.insert(session);
         } catch (DuplicateKeyException e) {
-            // Race: another thread inserted the same tenant+clientSessionId between our check and insert.
-            // Reload and verify ownership + fingerprint match.
             log.warn("DuplicateKeyException on clientSessionId={} for tenant={} — reloading for idempotency resolution",
                     reqVO.getClientSessionId(), tenantId);
             PracticeSessionDO winner = sessionMapper.selectByTenantAndClientSessionId(tenantId, reqVO.getClientSessionId());
             if (winner == null) {
-                // Defensive: should not happen if UK constraint triggered
                 throw exception(SESSION_DUPLICATE_CLIENT_ID);
             }
             if (!Objects.equals(winner.getUserId(), userId)) {
@@ -112,7 +113,7 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
             return buildSessionResp(winner, questionMapper.selectBySessionIdOrderBySequence(winner.getId()));
         }
 
-        // 4. Create question snapshots (server-determined order)
+        // 4. Create question snapshots with protected answer key
         List<PracticeQuestionDO> questionDOs = new ArrayList<>(questions.size());
         int seq = 1;
         for (CatalogQuestionDTO q : questions) {
@@ -126,6 +127,8 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
             pq.setType(q.getType());
             pq.setDifficulty(q.getDifficulty());
             pq.setOptions(optionsToSafeJson(q.getOptions()));
+            pq.setCorrectAnswer(correctAnswerToJson(q.getCorrectAnswer()));
+            pq.setExplanation(q.getExplanation());
             pq.setIsAnswered(false);
             questionDOs.add(pq);
         }
@@ -163,22 +166,32 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
     @Override
     @Transactional(rollbackFor = Exception.class)
     public PracticeAnswerRespVO submitAnswer(PracticeAnswerReqVO reqVO, Long userId, Long tenantId) {
-        // 1. Compute request hash for content-based idempotency (lightweight, no DB)
         String requestHash = computeRequestHash(reqVO);
 
-        // 2. Check idempotency FIRST — before any business validation (replay safety)
-        AnswerIdempotencyDO existingRecord = idempotencyMapper.selectByKey(
-                tenantId, userId, "SUBMIT_ANSWER", reqVO.getIdempotencyKey());
-        if (existingRecord != null) {
-            // Same key + same hash → replay original committed response
-            if (Objects.equals(existingRecord.getRequestHash(), requestHash)) {
-                return JsonUtils.parseObject(existingRecord.getResponseJson(), PracticeAnswerRespVO.class);
+        // 1. INSERT IGNORE idempotency — replay committed responses before any state checks
+        AnswerIdempotencyDO idempotency = new AnswerIdempotencyDO();
+        idempotency.setTenantId(tenantId);
+        idempotency.setUserId(userId);
+        idempotency.setOperation("SUBMIT_ANSWER");
+        idempotency.setIdempotencyKey(reqVO.getIdempotencyKey());
+        idempotency.setRequestHash(requestHash);
+        idempotency.setSessionId(reqVO.getSessionId());
+        idempotency.setQuestionId(""); // placeholder, updated after question lookup
+        idempotency.setSelectedAnswer(reqVO.getSelectedAnswer());
+        idempotency.setStatus("ACCEPTED");
+        idempotency.setResponseJson(""); // placeholder
+
+        int idemInserted = idempotencyMapper.insertIgnore(idempotency);
+        if (idemInserted == 0) {
+            AnswerIdempotencyDO existing = idempotencyMapper.selectByKey(
+                    tenantId, userId, "SUBMIT_ANSWER", reqVO.getIdempotencyKey());
+            if (existing != null && Objects.equals(existing.getRequestHash(), requestHash)) {
+                return JsonUtils.parseObject(existing.getResponseJson(), PracticeAnswerRespVO.class);
             }
-            // Same key + different hash → conflict
             throw exception(ANSWER_IDEMPOTENCY_CONFLICT);
         }
 
-        // 3. Load and validate session ownership, status, version
+        // 2. Load and validate session
         PracticeSessionDO session = sessionMapper.selectByIdAndTenant(reqVO.getSessionId(), tenantId);
         if (session == null) {
             throw exception(SESSION_NOT_FOUND);
@@ -195,7 +208,6 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
             });
         }
 
-        // 4. Version guard: null/overflow defensive check (finding #5)
         if (session.getVersion() == null) {
             throw exception(ANSWER_SESSION_VERSION_NULL);
         }
@@ -206,26 +218,24 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
             throw exception(ANSWER_SESSION_VERSION_OVERFLOW);
         }
 
-        // 5. Session-level clientSequence guard (finding #3)
         if (session.getLastClientSequence() != null
                 && reqVO.getClientSequence() <= session.getLastClientSequence()) {
             throw exception(ANSWER_STALE_CROSS_QUESTION_SEQUENCE,
                     reqVO.getClientSequence(), session.getLastClientSequence());
         }
 
-        // 6. Load question, validate it belongs to session
+        // 3. Load question and validate
         PracticeQuestionDO question = questionMapper.selectBySessionIdAndSequence(
                 reqVO.getSessionId(), reqVO.getQuestionSequence());
         if (question == null) {
             throw exception(ANSWER_QUESTION_NOT_IN_SESSION);
         }
 
-        // 7. Validate selected answer against question options (fail-closed, finding #4)
         if (reqVO.getSelectedAnswer() != null && !reqVO.getSelectedAnswer().isEmpty()) {
             validateOption(question, reqVO.getSelectedAnswer());
         }
 
-        // 8. Compute anticipated response
+        // 4. Build response and update idempotency with full data
         int newVersion = session.getVersion() + 1;
         PracticeAnswerRespVO response = PracticeAnswerRespVO.builder()
                 .sessionId(session.getId())
@@ -234,68 +244,254 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
                 .serverVersion(newVersion)
                 .acceptedSequence(reqVO.getClientSequence())
                 .build();
+        String responseJson = JsonUtils.toJsonString(response);
 
-        // 9. Insert idempotency record (reserve key — rollback on failure)
-        AnswerIdempotencyDO idempotency = new AnswerIdempotencyDO();
-        idempotency.setTenantId(tenantId);
-        idempotency.setUserId(userId);
-        idempotency.setOperation("SUBMIT_ANSWER");
-        idempotency.setIdempotencyKey(reqVO.getIdempotencyKey());
-        idempotency.setRequestHash(requestHash);
-        idempotency.setSessionId(session.getId());
-        idempotency.setQuestionId(question.getQuestionId());
-        idempotency.setSelectedAnswer(reqVO.getSelectedAnswer());
-        idempotency.setStatus("ACCEPTED");
-        idempotency.setResponseJson(JsonUtils.toJsonString(response));
-
-        try {
-            idempotencyMapper.insert(idempotency);
-        } catch (DuplicateKeyException e) {
-            // Race: another request with same idempotency key arrived between select and insert
-            log.warn("DuplicateKeyException on idempotencyKey={} for user={} tenant={}",
-                    reqVO.getIdempotencyKey(), userId, tenantId);
-            AnswerIdempotencyDO winner = idempotencyMapper.selectByKey(
-                    tenantId, userId, "SUBMIT_ANSWER", reqVO.getIdempotencyKey());
-            if (winner != null && Objects.equals(winner.getRequestHash(), requestHash)) {
-                return JsonUtils.parseObject(winner.getResponseJson(), PracticeAnswerRespVO.class);
-            }
-            throw exception(ANSWER_IDEMPOTENCY_CONFLICT);
+        // Re-select idempotency to get auto-generated ID, then update with full response
+        AnswerIdempotencyDO inserted = idempotencyMapper.selectByKey(
+                tenantId, userId, "SUBMIT_ANSWER", reqVO.getIdempotencyKey());
+        if (inserted != null) {
+            idempotencyMapper.update(null,
+                    new com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper<AnswerIdempotencyDO>()
+                            .eq(AnswerIdempotencyDO::getId, inserted.getId())
+                            .set(AnswerIdempotencyDO::getQuestionId, question.getQuestionId())
+                            .set(AnswerIdempotencyDO::getResponseJson, responseJson));
         }
 
-        // 10. CAS session version + lastClientSequence atomically (finding #2)
+        // 5. CAS session version + lastClientSequence
         int casResult = sessionMapper.casIncrementVersion(session.getId(), tenantId, userId,
                 session.getVersion(), reqVO.getClientSequence());
         if (casResult == 0) {
-            // Version changed or session no longer ACTIVE — rollback + throw
             throw exception(ANSWER_STALE_VERSION, session.getVersion(),
                     "已被其他请求更新，请刷新重试");
         }
 
-        // 11. CAS update question answer (finding #1: conditional, affected-row result)
+        // 6. Update question answer with clientSequence guard
         int updated = questionMapper.updateAnswerIfNewer(question.getId(), tenantId,
                 reqVO.getSelectedAnswer(),
                 reqVO.getSelectedAnswer() != null && !reqVO.getSelectedAnswer().isEmpty(),
                 reqVO.getClientSequence());
         if (updated == 0) {
-            // Reload and classify staleness
             PracticeQuestionDO reloaded = questionMapper.selectById(question.getId());
             if (reloaded != null && reloaded.getClientSequence() != null
                     && reqVO.getClientSequence() <= reloaded.getClientSequence()) {
                 throw exception(ANSWER_STALE_CLIENT_SEQUENCE,
                         reqVO.getClientSequence(), reloaded.getClientSequence());
             }
-            // tenant guard failed or question deleted — treat as not-in-session
             throw exception(ANSWER_QUESTION_NOT_IN_SESSION);
         }
 
         return response;
     }
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public PracticeSubmitRespVO submitSession(PracticeSubmitReqVO reqVO, Long userId, Long tenantId) {
+        // 1. Compute request hash
+        String requestHash = computeSubmitHash(reqVO);
+
+        // 2. Idempotency check: SELECT before any writes
+        SubmitIdempotencyDO existing = submitIdempotencyMapper.selectByKey(
+                tenantId, userId, "SUBMIT_SESSION", reqVO.getIdempotencyKey());
+        if (existing != null) {
+            if (!Objects.equals(existing.getRequestHash(), requestHash)) {
+                throw exception(SUBMIT_IDEMPOTENCY_CONFLICT);
+            }
+            // Same hash — only replay a fully committed response (reportId != null)
+            if (existing.getReportId() != null) {
+                return JsonUtils.parseObject(existing.getResponseJson(), PracticeSubmitRespVO.class);
+            }
+            // Same key, same hash, but reportId is null: another request with this key is in-flight.
+            throw exception(SUBMIT_CONCURRENT_CONFLICT);
+        }
+
+        // 3. Load and validate session
+        PracticeSessionDO session = sessionMapper.selectByIdAndTenant(reqVO.getSessionId(), tenantId);
+        if (session == null) {
+            throw exception(SESSION_NOT_FOUND);
+        }
+        if (!Objects.equals(session.getUserId(), userId)) {
+            throw exception(SESSION_NOT_OWN);
+        }
+        if (!"ACTIVE".equals(session.getStatus())) {
+            // If session is SUBMITTED and a report exists, return it (different-key concurrent submit loser)
+            if ("SUBMITTED".equals(session.getStatus())) {
+                PracticeReportDO existingReport = reportMapper.selectBySessionIdAndTenant(session.getId(), tenantId);
+                if (existingReport != null) {
+                    List<PracticeReportDetailDO> details =
+                            reportDetailMapper.selectByReportIdAndTenantAndUser(
+                                    existingReport.getId(), tenantId, userId);
+                    return buildSubmitResp(existingReport, details);
+                }
+            }
+            throw exception(switch (session.getStatus()) {
+                case "SUBMITTED" -> SESSION_ALREADY_SUBMITTED;
+                case "EXPIRED" -> SESSION_EXPIRED;
+                case "CANCELLED" -> SESSION_CANCELLED;
+                default -> SUBMIT_SESSION_NOT_ACTIVE;
+            });
+        }
+        if (!Objects.equals(session.getVersion(), reqVO.getExpectedSessionVersion())) {
+            throw exception(SUBMIT_STALE_VERSION, reqVO.getExpectedSessionVersion(), session.getVersion());
+        }
+
+        // 4. Load question snapshots and score
+        List<PracticeQuestionDO> questions = questionMapper.selectBySessionIdOrderBySequence(session.getId());
+        int score = computeScore(questions);
+        int answeredCount = (int) questions.stream().filter(q -> q.getIsAnswered() != null && q.getIsAnswered()).count();
+        int unansweredCount = questions.size() - answeredCount;
+        int correctCount = (int) questions.stream()
+                .filter(q -> q.getIsAnswered() != null && q.getIsAnswered() && isAnswerCorrect(q))
+                .count();
+        int incorrectCount = answeredCount - correctCount;
+
+        // 5. Build report details
+        List<PracticeReportDetailDO> details = new ArrayList<>(questions.size());
+        for (PracticeQuestionDO q : questions) {
+            PracticeReportDetailDO detail = new PracticeReportDetailDO();
+            detail.setTenantId(tenantId);
+            detail.setUserId(userId);
+            detail.setSessionId(session.getId());
+            detail.setQuestionId(q.getQuestionId());
+            detail.setSequence(q.getSequence());
+            detail.setStem(q.getStem());
+            detail.setType(q.getType());
+            detail.setDifficulty(q.getDifficulty());
+            detail.setSelectedAnswer(q.getSelectedAnswer());
+            detail.setCorrectAnswer(q.getCorrectAnswer());
+            detail.setIsCorrect(q.getIsAnswered() != null && q.getIsAnswered() && isAnswerCorrect(q));
+            detail.setExplanation(q.getExplanation());
+            details.add(detail);
+        }
+
+        // 6. Build report
+        PracticeReportDO report = new PracticeReportDO();
+        report.setTenantId(tenantId);
+        report.setUserId(userId);
+        report.setSessionId(session.getId());
+        report.setQuestionCount(questions.size());
+        report.setAnsweredCount(answeredCount);
+        report.setUnansweredCount(unansweredCount);
+        report.setCorrectCount(correctCount);
+        report.setIncorrectCount(incorrectCount);
+        report.setScore(score);
+        report.setStatus("SUBMITTED");
+
+        // 7. INSERT IGNORE report — resolves concurrent different-key submit races
+        int reportInserted = reportMapper.insertIgnore(report);
+        if (reportInserted == 0) {
+            // Another submit already committed for this session — return winner's report
+            PracticeReportDO winnerReport = reportMapper.selectBySessionIdAndTenant(session.getId(), tenantId);
+            if (winnerReport != null) {
+                SubmitIdempotencyDO winnerKey = submitIdempotencyMapper.selectByKey(
+                        tenantId, userId, "SUBMIT_SESSION", reqVO.getIdempotencyKey());
+                if (winnerKey != null && !Objects.equals(winnerKey.getRequestHash(), requestHash)) {
+                    throw exception(SUBMIT_IDEMPOTENCY_CONFLICT);
+                }
+                // A different idempotency key may have won. Return the immutable winner report;
+                // do not create a second replay record for this losing key.
+                List<PracticeReportDetailDO> winnerDetails =
+                        reportDetailMapper.selectByReportIdAndTenantAndUser(
+                                winnerReport.getId(), tenantId, userId);
+                return buildSubmitResp(winnerReport, winnerDetails);
+            }
+            throw exception(SUBMIT_CONCURRENT_CONFLICT);
+        }
+        // Re-select to get auto-generated ID
+        report = reportMapper.selectBySessionIdAndTenant(session.getId(), tenantId);
+
+        // 8. Insert details
+        for (PracticeReportDetailDO detail : details) {
+            detail.setReportId(report.getId());
+        }
+        reportDetailMapper.insertBatch(details);
+
+        // 9. CAS: ACTIVE → SUBMITTED
+        int casResult = sessionMapper.update(null,
+                new com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper<PracticeSessionDO>()
+                        .eq(PracticeSessionDO::getId, session.getId())
+                        .eq(PracticeSessionDO::getTenantId, tenantId)
+                        .eq(PracticeSessionDO::getUserId, userId)
+                        .eq(PracticeSessionDO::getStatus, "ACTIVE")
+                        .eq(PracticeSessionDO::getVersion, reqVO.getExpectedSessionVersion())
+                        .set(PracticeSessionDO::getStatus, "SUBMITTED")
+                        .setSql("version = version + 1"));
+        if (casResult == 0) {
+            log.error("Submit CAS failed for sessionId={}, expectedVersion={}",
+                    session.getId(), reqVO.getExpectedSessionVersion());
+            throw exception(SUBMIT_CONCURRENT_CONFLICT);
+        }
+
+        // 10. Build final response
+        PracticeSubmitRespVO submitResp = PracticeSubmitRespVO.builder()
+                .reportId(report.getId())
+                .sessionId(session.getId())
+                .questionCount(questions.size())
+                .answeredCount(answeredCount)
+                .unansweredCount(unansweredCount)
+                .correctCount(correctCount)
+                .incorrectCount(incorrectCount)
+                .score(score)
+                .details(buildReportDetailVOs(details))
+                .build();
+        String responseJson = JsonUtils.toJsonString(submitResp);
+
+        // 11. Regular INSERT idempotency — only winners reach here (no race on same key)
+        // If DuplicateKeyException occurs, the transaction rolls back cleanly (CAS + details also rolled back).
+        SubmitIdempotencyDO idempotency = new SubmitIdempotencyDO();
+        idempotency.setTenantId(tenantId);
+        idempotency.setUserId(userId);
+        idempotency.setOperation("SUBMIT_SESSION");
+        idempotency.setIdempotencyKey(reqVO.getIdempotencyKey());
+        idempotency.setRequestHash(requestHash);
+        idempotency.setSessionId(session.getId());
+        idempotency.setReportId(report.getId());
+        idempotency.setStatus("ACCEPTED");
+        idempotency.setResponseJson(responseJson);
+        submitIdempotencyMapper.insert(idempotency);
+
+        return submitResp;
+    }
+
+    @Override
+    public PracticeSubmitRespVO getReport(Long sessionId, Long userId, Long tenantId) {
+        PracticeSessionDO session = sessionMapper.selectByIdAndTenant(sessionId, tenantId);
+        if (session == null) {
+            throw exception(SESSION_NOT_FOUND);
+        }
+        if (!Objects.equals(session.getUserId(), userId)) {
+            throw exception(REPORT_NOT_OWN);
+        }
+        if (!"SUBMITTED".equals(session.getStatus())) {
+            throw exception(REPORT_SESSION_NOT_SUBMITTED);
+        }
+
+        PracticeReportDO report = reportMapper.selectBySessionIdAndTenant(sessionId, tenantId);
+        if (report == null) {
+            throw exception(REPORT_NOT_FOUND);
+        }
+        List<PracticeReportDetailDO> details = reportDetailMapper.selectByReportIdAndTenantAndUser(
+                report.getId(), tenantId, userId);
+
+        return buildSubmitResp(report, details);
+    }
+
+    @Override
+    public PageResult<PracticeSubmitRespVO> getReportHistory(Long userId, Long tenantId, int pageNo, int pageSize) {
+        IPage<PracticeReportDO> page = reportMapper.selectPageByTenantAndUser(
+                new Page<>(pageNo, pageSize), tenantId, userId);
+
+        List<PracticeSubmitRespVO> list = page.getRecords().stream()
+                .map(report -> {
+                    List<PracticeReportDetailDO> details =
+                            reportDetailMapper.selectByReportIdAndTenantAndUser(report.getId(), tenantId, userId);
+                    return buildSubmitResp(report, details);
+                })
+                .collect(Collectors.toList());
+
+        return new PageResult<>(list, page.getTotal());
+    }
 
     // ========== internal helpers ==========
 
-    /**
-     * 从 provider 获取题目列表，按 questionId 稳定排序，取前 count 条。
-     */
     /**
      * 从 provider 获取题目列表，按 questionId 稳定排序，取前 count 条。
      * 所有筛选条件（含 nodeId）完整转发到 provider，不做客户端裁剪。
@@ -351,6 +547,28 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
         return JsonUtils.toJsonString(safeOptions);
     }
 
+    /**
+     * Canonical answer representation for storage.
+     * String → stored as-is (e.g. "B"); List → sorted JSON array (e.g. '["A","C"]');
+     * null → null. This normalizes provider correctAnswer which may be a String or List.
+     */
+    private String correctAnswerToJson(Object correctAnswer) {
+        if (correctAnswer == null) {
+            return null;
+        }
+        if (correctAnswer instanceof String s) {
+            return s;
+        }
+        if (correctAnswer instanceof List<?> list) {
+            List<String> sorted = list.stream()
+                    .map(Object::toString)
+                    .sorted()
+                    .collect(Collectors.toList());
+            return JsonUtils.toJsonString(sorted);
+        }
+        return JsonUtils.toJsonString(correctAnswer);
+    }
+
     /**
      * 构建会话响应 VO。
      */
@@ -372,6 +590,7 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
 
     /**
      * 构建单题响应 VO — 从快照安全还原。
+     * 绝不包含 correctAnswer/explanation，仅暴露 label/content/order。
      */
     private PracticeQuestionRespVO buildQuestionResp(PracticeQuestionDO pq) {
         List<PracticeQuestionRespVO.OptionVO> options = parseOptions(pq.getOptions());
@@ -407,11 +626,101 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
                 .collect(Collectors.toList());
     }
 
+    /**
+     * Build submit response from report + details.
+     */
+    private PracticeSubmitRespVO buildSubmitResp(PracticeReportDO report, List<PracticeReportDetailDO> details) {
+        return PracticeSubmitRespVO.builder()
+                .reportId(report.getId())
+                .sessionId(report.getSessionId())
+                .questionCount(report.getQuestionCount())
+                .answeredCount(report.getAnsweredCount())
+                .unansweredCount(report.getUnansweredCount())
+                .correctCount(report.getCorrectCount())
+                .incorrectCount(report.getIncorrectCount())
+                .score(report.getScore())
+                .details(buildReportDetailVOs(details))
+                .build();
+    }
+
+    /**
+     * Convert report detail DOs to VOs (exposes correctAnswer/explanation for submitted sessions only).
+     */
+    private List<PracticeReportDetailRespVO> buildReportDetailVOs(List<PracticeReportDetailDO> details) {
+        return details.stream()
+                .map(d -> PracticeReportDetailRespVO.builder()
+                        .sequence(d.getSequence())
+                        .questionId(d.getQuestionId())
+                        .stem(d.getStem())
+                        .type(d.getType())
+                        .difficulty(d.getDifficulty())
+                        .selectedAnswer(d.getSelectedAnswer())
+                        .correctAnswer(d.getCorrectAnswer())
+                        .isCorrect(d.getIsCorrect())
+                        .explanation(d.getExplanation())
+                        .build())
+                .collect(Collectors.toList());
+    }
+
+    /**
+     * Normalize a stored answer string into its canonical form for comparison.
+     * - null/empty → null (treated as no answer / no correct answer)
+     * - JSON array (starts with '[') → parse as String list, sort, re-serialize
+     * - plain string → trim
+     * Malformed JSON arrays fall through as plain string comparison.
+     */
+    private String normalizeAnswer(String stored) {
+        if (stored == null || stored.isEmpty()) return null;
+        String trimmed = stored.trim();
+        if (trimmed.startsWith("[")) {
+            try {
+                @SuppressWarnings({"unchecked", "rawtypes"})
+                List<String> list = (List) JsonUtils.parseArray(trimmed, String.class);
+                if (list != null) {
+                    List<String> sorted = new ArrayList<>(list);
+                    Collections.sort(sorted);
+                    return JsonUtils.toJsonString(sorted);
+                }
+            } catch (Exception e) {
+                // Not valid JSON array → compare as plain string below
+            }
+        }
+        return trimmed;
+    }
+
+    /**
+     * Check if the student's selected answer matches the correct answer snapshot.
+     * Uses canonical normalization: single choice compares trimmed strings;
+     * multiple choice compares sorted sets order-insensitively via normalized JSON.
+     * Fail-closed: null/empty on either side → false.
+     */
+    private boolean isAnswerCorrect(PracticeQuestionDO question) {
+        String normCorrect = normalizeAnswer(question.getCorrectAnswer());
+        String normSelected = normalizeAnswer(question.getSelectedAnswer());
+        if (normCorrect == null || normSelected == null) {
+            return false;
+        }
+        return normCorrect.equals(normSelected);
+    }
+
+    /**
+     * Compute a score from the question snapshots on a 100-point integer basis.
+     * Deterministic: answered correct / total questions * 100, rounded half-up to integer.
+     */
+    private int computeScore(List<PracticeQuestionDO> questions) {
+        int total = questions.size();
+        if (total == 0) {
+            return 0;
+        }
+        int correct = (int) questions.stream()
+                .filter(q -> q.getIsAnswered() != null && q.getIsAnswered() && isAnswerCorrect(q))
+                .count();
+        // Deterministic rounding: (correct * 100 + total/2) / total
+        return (int) ((correct * 100L + total / 2) / total);
+    }
 
     /**
      * Verify that the existing session's immutable selection criteria match the current request.
-     * Used during race-resolution: if a concurrent insert wins, the calling thread's payload
-     * must be identical, otherwise it's an idempotency mismatch.
      */
     private boolean isSameFingerprint(PracticeSessionDO existing, PracticeSessionCreateReqVO reqVO) {
         return Objects.equals(existing.getCollectionId(), reqVO.getCollectionId())
@@ -422,8 +731,7 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
     }
 
     /**
-     * Compute SHA-256 hash of canonical request payload for idempotency content checking.
-     * Fields are ordered deterministically; same payload always produces same hash.
+     * Compute SHA-256 hash of canonical answer request payload for idempotency content checking.
      */
     private String computeRequestHash(PracticeAnswerReqVO reqVO) {
         Map<String, Object> canonical = new TreeMap<>();
@@ -436,12 +744,23 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
     }
 
     /**
-     * Validate that the selected answer exists among the question's options.
-     * Fail-closed: malformed options data → immediate rejection.
+     * Compute SHA-256 hash of canonical submit request payload for idempotency content checking.
+     */
+    private String computeSubmitHash(PracticeSubmitReqVO reqVO) {
+        Map<String, Object> canonical = new TreeMap<>();
+        canonical.put("sessionId", reqVO.getSessionId());
+        canonical.put("expectedSessionVersion", reqVO.getExpectedSessionVersion());
+        return DigestUtil.sha256Hex(JsonUtils.toJsonString(canonical));
+    }
+
+    /**
+     * Validate that the selected answer(s) exist among the question's options.
+     * Single choice: selectedAnswer is a plain label string (e.g. "B").
+     * Multiple choice: selectedAnswer is a JSON array string (e.g. '["A","C"]').
+     * Fail-closed: malformed options data or invalid answer → immediate rejection.
      */
     @SuppressWarnings({"unchecked", "rawtypes"})
     private void validateOption(PracticeQuestionDO question, String selectedAnswer) {
-        // null or blank options → upstream malformed
         if (question.getOptions() == null || question.getOptions().isBlank()) {
             throw exception(CATALOG_UPSTREAM_OPTIONS_MALFORMED);
         }
@@ -453,12 +772,12 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
             throw exception(CATALOG_UPSTREAM_OPTIONS_MALFORMED);
         }
 
-        // non-array or empty → malformed
         if (options == null || options.isEmpty()) {
             throw exception(CATALOG_UPSTREAM_OPTIONS_MALFORMED);
         }
 
-        // validate every element: non-null, has non-blank label
+        // Validate option labels exist
+        java.util.Set<String> validLabels = new java.util.HashSet<>();
         for (Map<String, Object> o : options) {
             if (o == null) {
                 throw exception(CATALOG_UPSTREAM_OPTIONS_MALFORMED);
@@ -467,13 +786,32 @@ public class PracticeSessionServiceImpl implements PracticeSessionService {
             if (label == null || (label instanceof String s && s.isBlank())) {
                 throw exception(CATALOG_UPSTREAM_OPTIONS_MALFORMED);
             }
+            validLabels.add(label.toString());
         }
 
-        // validate selectedAnswer exists in options
-        boolean valid = options.stream()
-                .anyMatch(o -> Objects.equals(o.get("label"), selectedAnswer));
-        if (!valid) {
-            throw exception(ANSWER_OPTION_INVALID, selectedAnswer);
+        // Parse selected answer(s) — support single label or JSON array of labels
+        String trimmed = selectedAnswer.trim();
+        if (trimmed.startsWith("[")) {
+            // Multiple-choice: parse JSON array, validate each element
+            List<String> selections;
+            try {
+                selections = (List<String>) JsonUtils.parseArray(trimmed, String.class);
+            } catch (Exception e) {
+                throw exception(ANSWER_OPTION_INVALID, selectedAnswer);
+            }
+            if (selections == null || selections.isEmpty()) {
+                throw exception(ANSWER_OPTION_INVALID, selectedAnswer);
+            }
+            for (String sel : selections) {
+                if (!validLabels.contains(sel)) {
+                    throw exception(ANSWER_OPTION_INVALID, sel);
+                }
+            }
+        } else {
+            // Single choice: plain label
+            if (!validLabels.contains(trimmed)) {
+                throw exception(ANSWER_OPTION_INVALID, trimmed);
+            }
         }
     }
 }