From d82a3b5426566d8e5a587e6f6efe620da780ec64 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 22:29:01 +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 | 141 +++++++++++++++++++++++++++++++++++++
 1 file changed, 141 insertions(+)

diff --git a/docs/phase2-P0-delivery.md b/docs/phase2-P0-delivery.md
index e24915d..5e0c2f8 100644
--- a/docs/phase2-P0-delivery.md
+++ b/docs/phase2-P0-delivery.md
@@ -249,3 +249,144 @@ src/views/system/{messageTemplate,messageLog}/
 ### 9.4 修复记录
 
 初版曾把 `gxmu_practice_credit` 加进 `DeclareGuardServiceImpl` 的模块列表，导致审核回写时按「模块名=表名」去更新不存在的表。已移除——社会实践用独立表 `gxmu_practice_credit_apply`，状态回写由自己的 service 负责。
+
+
+## 十、部署排查：部署后看不到新功能
+
+### 症状
+
+前端已是最新版本，侧栏没有「成长中心」「社团与志愿」；访问新接口报错：
+
+```
+Table 'tuanwei.gxmu_credit_record' doesn't exist
+```
+
+### 原因
+
+三个部分必须同时到位，缺一项都会表现为「没有新功能」：
+
+| 部分 | 状态判断 | 缺失表现 |
+| --- | --- | --- |
+| 前端 dist | 已确认包含新页面（`index.0475cb90.js` 内有 21 个新路由） | 页面 404 |
+| 后端 jar | 已确认新接口可达（返回业务错误而非 404） | 接口 404 |
+| **数据库** | **未执行二期 SQL** | **接口报表不存在、侧栏无菜单** |
+
+菜单是**动态从 `sys_menu` 读取的**（`GET /auth/user` → `formatMenus` → `addRoute`），
+库里没有菜单记录，前端代码再全也不会显示。
+
+### 部署步骤
+
+在服务器的 `tuanwei-java` 目录执行：
+
+```bash
+# 方式一：一键脚本（自动备份 + 执行 9 个脚本 + 验证）
+sh sql/deploy_phase2.sh ./sql
+
+# 方式二：合并脚本（单文件，等价于依次执行 01~09）
+docker exec -i 1Panel-mariadb-ZOpD \
+  mysql -utuanwei -p'TytQZsSW5m4wGh38' tuanwei < sql/phase2_all_in_one.sql
+
+# 方式三：逐个执行（便于定位问题）
+for f in sql/20261105_phase2_0*.sql; do
+  docker exec -i 1Panel-mariadb-ZOpD \
+    mysql -utuanwei -p'TytQZsSW5m4wGh38' tuanwei < "$f"
+done
+```
+
+执行完重启后端（Docker 里通常已配置 `restart: unless-stopped`，只需
+`docker restart tuanwei-api`），然后浏览器强制刷新并**重新登录**。
+
+### 脚本安全性
+
+- 全部可重复执行，实测连续执行两遍：146 条语句零报错，菜单/授权/模板/字典数量完全不变
+- `07` 会 ALTER 三张审核表，**只新增列并回填**存量数据，不改原有字段
+- 脚本建议先备份；`deploy_phase2.sh` 已内置自动备份并校验备份非空
+
+### 执行后的验证
+
+```sql
+SELECT COUNT(*) FROM sys_menu WHERE menu_id BETWEEN 14500 AND 14663;   -- 应为 62
+SELECT COUNT(*) FROM oa_notice_template;                                -- 应为 10
+SELECT COUNT(*) FROM gxmu_graduate_requirement;                         -- 应为 6
+```
+
+接口验证：
+
+```bash
+curl -H "Authorization: <token>" https://twai-api.gxmu.edu.cn/api/gxmu/credit/page
+# 应返回 {"code":0,...} 而不是 Table doesn't exist
+```
+
+### 若菜单仍未出现
+
+脚本 08 只给 `superAdmin` 和 `student` 授了权。若你当前账号是其他角色
+（校团委、二级学院团委、指导老师等），需在「系统设置 → 角色管理」里
+手动勾选二期菜单。
+
+
+## 十一、导入报错 ERROR 1273 Unknown collation
+
+### 症状
+
+导入 SQL 时在第 271 行报：
+
+```
+ERROR 1273 (HY000): Unknown collation: 'utf8mb4_0900_ai_ci'
+```
+
+出错语句是 `CREATE TABLE gxmu_certificate_template`，结尾带
+`COLLATE=utf8mb4_0900_ai_ci`。
+
+### 原因
+
+**导错了文件**：这条语句来自从**开发库导出的整库 dump**，不是二期的迁移脚本。
+
+- 开发库是 **MySQL 8.0.44**，建表时 `DEFAULT CHARSET=utf8mb4` 会隐式采用
+  MySQL 8 专有的 `utf8mb4_0900_ai_ci`
+- 生产是 **MariaDB**，不识别这个 collation，直接报错
+
+经核查，`sql/20261105_phase2_*.sql` 里 `COLLATE=` 出现 **0 次**，
+不是迁移脚本的问题。mysqldump 导出时会把隐式默认值显式写出来，于是把
+MySQL 8 的特性带进了 dump。
+
+### 解决方案
+
+**方案 A（推荐）：用迁移脚本，不要导整库 dump**
+
+```bash
+docker exec -i 1Panel-mariadb-ZOpD \
+  mysql -utuanwei -p'密码' tuanwei < sql/phase2_all_in_one.sql
+```
+
+迁移脚本的建表语句现在已显式锁定 `COLLATE=utf8mb4_general_ci`
+（30 处建表全部处理），在 MySQL 8 / MariaDB 上都能安全执行。
+
+**方案 B：确实要导整库 dump 时，先做兼容转换**
+
+```bash
+python3 sql/fix_mysql8_dump_for_mariadb.py dev_dump.sql
+# 生成 dev_dump.mariadb.sql，再导入
+docker exec -i 1Panel-mariadb-ZOpD \
+  mysql -utuanwei -p'密码' tuanwei < dev_dump.mariadb.sql
+```
+
+转换器会处理：
+
+| 转换项 | 说明 |
+| --- | --- |
+| `utf8mb4_0900_*` → `utf8mb4_general_ci` / `utf8mb4_bin` | 核心问题 |
+| `utf8mb3_*` → `utf8mb4_*` | MySQL 8 的新叫法，MariaDB 不认 |
+| `CHARACTER SET utf8mb3` / `CHARSET=utf8mb3` | 裸写声明 |
+| 删除 `SET @@GLOBAL.GTID_PURGED` 等 | MariaDB 不支持或会报错 |
+| 处理 `/*!80000 ... */` 版本条件注释 | 仅 MySQL 8 执行的内容 |
+
+### 当前开发库情况
+
+开发库 88 张表中有 **61 张**是 `utf8mb4_0900_ai_ci`（`sys_user`、`gxmu_club`
+等），如果整库同步到生产，这 61 张都会失败。**建议只同步二期新增的数据，
+或先跑转换器**。
+
+### 防呆
+
+`deploy_phase2.sh` 新增了预检：执行前扫描脚本中是否含
+`utf8mb4_0900_ai_ci`，命中则直接中止并提示「不要导入 MySQL 8 的整库 dump」。