From 9c45ff79f49f45d8d10b5b7a6580b481fd9c6661 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B5=B5=E5=BF=A0=E6=9E=97?= <170083662@qq.com>
Date: Thu, 5 Nov 2026 19:18:26 +0800
Subject: [PATCH] =?UTF-8?q?feat(credit):=20=E5=A2=9E=E5=8A=A0=E7=A4=BE?=
 =?UTF-8?q?=E4=BC=9A=E5=AE=9E=E8=B7=B5=E5=AD=A6=E5=88=86=E5=8F=8A=E5=AD=A6?=
 =?UTF-8?q?=E5=88=86=E9=A2=84=E8=AD=A6=E6=A8=A1=E5=9D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 实现社会实践学分的提交、撤回、作废、删除、汇总及导出功能
- 审核通过后自动发放学分，确保幂等性
- 新增学分预警功能，支持缺口计算、级别判定和月度去重推送
- 设计四级审核流程，审核状态变更后自动回调处理
- 支持教务处模板导出，输出标准xls格式文件
- 提供前端页面替换原占位页，提升用户体验
- 补充每日定时任务执行学分预警重算，支持配置开关
- 修复审核回写逻辑，避免误更新不存在的表数据
---
 docs/phase2-P0-delivery.md | 57 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/docs/phase2-P0-delivery.md b/docs/phase2-P0-delivery.md
index 288a33c..e24915d 100644
--- a/docs/phase2-P0-delivery.md
+++ b/docs/phase2-P0-delivery.md
@@ -192,3 +192,60 @@ src/views/system/{messageTemplate,messageLog}/
 ### 8.4 统一最新审核记录排序
 
 `reviewStatusTag` 原按 `id` 取最新，`utils/review.ts` 按 `createTime + id`，并行审核下两处可能给出矛盾结论。现已抽出 `getLatestReview()` 统一为「sortNumber → createTime → id」，两个调用方共用。
+
+
+## 九、P1 首批交付：社会实践学分 + 学分预警
+
+### 9.1 社会实践学分
+
+**后端**（`com.gxwebsoft.gxmu.credit`）
+
+| 文件 | 说明 |
+| --- | --- |
+| `PracticeCreditController` | 提交/撤回/作废/删除/汇总/导出 |
+| `PracticeCreditService` + `Impl` | 校验、状态回写、**通过后自动发放学分** |
+| `PracticeCreditApplyParam` | 查询参数 |
+
+**审核接入**：模块名 `gxmu_practice_credit`，走既有 `gxmu_review_list` 引擎，四级审核（个人 → 班级 → 二级学院团委 → 校团委）在「审核流配置」里绑定即可。`ReviewListController` 审核完成后回调：
+
+1. `syncReviewStatus` 回写申报状态；
+2. `grantCreditWhenApproved` 在通过时写一条 `gxmu_credit_record`（`source=practice`、`external_id=practice-{id}`，幂等）。
+
+**教务处模板导出**：`POST /api/gxmu/practice-credit/export`，输出 14 列 xls（序号/学号/姓名/学院/班级/学年/活动名称/活动类型/起止日期/实践内容/担任角色/核定学分/审核状态），走既有「生成文件 → FileRecord 入库 → 返回下载地址」模式。
+
+**前端**：`/growth/practiceCredit`，替换原占位页。
+
+### 9.2 学分预警
+
+| 文件 | 说明 |
+| --- | --- |
+| `CreditWarningService` + `Impl` | 缺口计算、级别判定、月度去重推送 |
+| `CreditWarningController` | 列表/汇总/重算/推送 |
+| `CreditWarningTask`（新增） | 每天 02:30 全量重算，`gxmu.credit-warning.enabled` 可关 |
+
+**级别规则**：`gap/required ≥ 0.6 且 gap ≥ 2` → danger；`≥ 0.3` → warn；其余 normal。
+叠加绝对门槛是因为只看比例会把「应修 1 分、缺 1 分」也判成严重。
+
+**去重**：同一学生同一类别每个自然月只推一条站内消息（`notify_month` 记录）。
+
+**闭环**：补分后重算会自动清理已达成类别的预警（逻辑删除），不会永远挂着。
+
+**前端**：`/growth/creditWarning`，替换原占位页。
+
+### 9.3 验证记录
+
+| 场景 | 结果 |
+| --- | --- |
+| 社会实践缺附件提交 | 拒绝「请上传社会实践证明材料」✓ |
+| 正常提交 → 生成审核节点 | ✓ |
+| 审核通过 → 申报状态置 2 | ✓ |
+| 审核通过 → 学分自动入账（2.00，source=practice） | ✓ |
+| 重复审核同一条 → 学分不重复发 | ✓（仍 1 条 2.00） |
+| 学分类别缺口识别 | 6 类全部识别 ✓ |
+| 补分后重算 → 该类别预警清除 | ✓（有效预警 6→5） |
+| 级别判定 | 缺 2 分 danger、缺 1 分 warn ✓ |
+| 预警推送 → 第一次 5 条、第二次 0 条 | 月度去重生效 ✓ |
+
+### 9.4 修复记录
+
+初版曾把 `gxmu_practice_credit` 加进 `DeclareGuardServiceImpl` 的模块列表，导致审核回写时按「模块名=表名」去更新不存在的表。已移除——社会实践用独立表 `gxmu_practice_credit_apply`，状态回写由自己的 service 负责。