# 团委智能化平台二期实施方案

> 依据《副本二期功能--定稿0802.docx》（4 大模块 26 项功能）制定。
> 前端仓库：`tuanwei-admin`（Vue3 + ele-admin-pro）；后端仓库：`tuanwei-java`（Spring Boot + MyBatis-Plus）。

## 一、现状结论

二期的四项底座已经具备，可直接复用：

| 底座 | 现状 | 可复用点 |
| --- | --- | --- |
| 申报 + 审核流 | `gxmu_declare` / `gxmu_review_flow` / `gxmu_review_flow_config` / `gxmu_review_list`，9 张申报表全部接入 | 三级审核、状态回写、`ReviewFlowStarterService` |
| 学生统一身份 | `gxmu_student.user_id`（开放平台同步 + 认领）、`gxmu_teacher`、`gxmu_tygl_form` | 成长主页身份主键、组织作用域 |
| 文件存储 | `/api/file/upload` + S3 对象存储 + 缩略图 + office 转 PDF | 所有附件、证明材料 |
| 爬虫 + 异步任务 | `CrossSchoolActivityCrawlerServiceImpl`（jsoup + 定时 + upsert）、`OpenplatSyncServiceImpl`（进度表 + 轮询） | 主题团课库、批量导入与导出 |

三项能力必须新建：

1. **站内消息中心**：后端无 `oa_notice`，但前端顶栏铃铛与 `/user/notice` 已在调用 `/api/oa/notice/*`，属于前端等后端。
2. **业务域**：学分、志愿、社团、场地、青马培养、专家评审均无表无接口。
3. **OCR 与 PDF 生成**：无 OCR 依赖；PDF 只能通过服务器 LibreOffice 转换。

## 二、菜单规划

原则：不动现有 12 个一级菜单，不迁移已有子菜单（避免破坏角色授权）。新增 2 个一级菜单，其余挂到语义最近的现有菜单。

### 新增一级菜单

```
成长中心 /growth                                  menu_id 14500
├ 我的成长        /growth/myHome                  14501
├ 学分明细        /growth/credit                  14502
├ 社会实践学分    /growth/practiceCredit          14503
├ 学分预警        /growth/creditWarning           14504
├ 学生画像        /growth/portrait                14505
└ 推荐内容        /growth/recommend               14506

社团与志愿 /club                                  menu_id 14520
├ 志愿服务时长    /club/volunteerHour             14521
├ 志愿时长审核    /club/volunteerReview           14522
├ 志愿证明        /club/volunteerCertificate      14523
├ 社团管理        /club/club                      14524
├ 社团活动        /club/activity                  14525
├ 活动审批        /club/activityReview            14526
├ 场地预约        /club/venue                     14527
├ 场地审批        /club/venueReview               14528
├ 社团年审        /club/annualReview              14529
└ 社团评优        /club/award                     14530
```

### 挂到现有菜单

| 现有菜单 | 新增子项 |
| --- | --- |
| 数字化团员 14342 | 青马学员档案 `/gxmu/qmgcStudent`、培养任务 `/gxmu/qmgcTask`、考核评分 `/gxmu/qmgcScore`、主题团课库 `/gxmu/thematicCourse` |
| AI内容创作与宣传助手 14365 | AI辅助教学设计 `/gxmu/teachingDesign`、AI主题团日设计 `/gxmu/themeDayDesign` |
| 挑战杯 14372 | 专家评审 `/gxmu/expertReview`、专家库 `/gxmu/expertPool` |
| 系统设置 8574 | 消息模板 `/system/messageTemplate`、推送记录 `/system/messageLog` |

`青马工程`（14353）保留为申报入口；新增学员档案管理培养期，两者不合并。
消息中心的用户侧直接复用已有 `/user/notice` 与顶栏铃铛，前端零改动即可生效。

## 三、分期

### P0（可上线的最小闭环，约 53 人日）

| # | 功能 | 交付物 |
| --- | --- | --- |
| 1 | 站内消息中心 | `oa_notice` + `oa_notice_record` + `/api/oa/notice/*` + 审核钩子 |
| 2 | 第二课堂学分 | 学分规则/记录表 + Excel 导入 + 明细页 + 汇总 |
| 3 | 学生成长主页 | 聚合接口 + 简历式页面 |
| 4 | 志愿服务 | 个人录入 + 桂志愿导入 + 二级学院审核 + 时长汇总 |
| 5 | 社团管理 | 社团主档 + 成员 + 指导老师 |
| 6 | 场地预约 | 场地主档 + 日历 + 冲突校验 + 审批 |
| 7 | 青马培养档案 | 学员主档 + 培养材料 + 任务清单 |
| 8 | 主题团课库 | 表 + 列表 + 爬虫入库 |
| 9 | 工程配套 | 菜单/按钮/角色 SQL + 字典 + 权限码 |

### P1（第二批，约 63 人日）

社会实践学分申报（四级审核 + 教务处模板导出）、学分预警、智能推荐、学生画像、社团年审、社团评优、年度志愿证明、社团年度报告、专家评审、AI 辅助教学设计与主题团日设计、审核流并行审批改造。

### P2（探索期，约 23 人日）

AI 学员学习情况分析、AI 定制培养建议、OCR 公章识别、AI 数字人、移动端接口整理。

> AI 学员学习情况分析的前端入口已落在青马学员档案（列表操作列「AI 分析」+ 档案抽屉按钮），
> 复用 `utils/ai-stream.ts` 流式链路，接口契约见 `docs/ai-qmgc-student-analysis-contract.md`。
> 归入 AI 能力域、入口留在业务域，不作为独立 AI 菜单页。

## 四、数据模型

统一规范：`id BIGINT AUTO_INCREMENT`、`tenant_id`、`user_id`、`deleted`、`create_time`、`update_time`。
附件：单文件用 `file_id + file_url`；多文件用 JSON 数组字符串。
审批统一复用 `gxmu_review_list(module, pk)`，模块名即业务表名。

建表脚本见：

- `docs/sql/phase2_01_growth_credit.sql`：学分、社会实践、毕业要求、预警、画像、推荐
- `docs/sql/phase2_02_volunteer.sql`：志愿服务与证明
- `docs/sql/phase2_03_club_venue.sql`：社团、成员、活动、年审、评优、场地、预约
- `docs/sql/phase2_04_qmgc.sql`：青马学员、材料、任务、评分、考试
- `docs/sql/phase2_05_thematic_course.sql`：主题团课库
- `docs/sql/phase2_06_notice.sql`：消息中心
- `docs/sql/phase2_07_review_parallel.sql`：审核流并行节点改造
- `docs/sql/phase2_08_menu_permission.sql`：菜单、按钮、角色授权

## 五、后端设计

新增包（不改动现有 24 个 gxmu 控制器）：

```
com.gxwebsoft.gxmu.credit      学分规则、记录、导入、汇总、预警
com.gxwebsoft.gxmu.volunteer   志愿时长与证明
com.gxwebsoft.gxmu.club        社团、活动、年审、评优
com.gxwebsoft.gxmu.venue       场地与预约
com.gxwebsoft.gxmu.qmgcpro     青马培养档案（与现有 QmgcForm 申报区分）
com.gxwebsoft.gxmu.thematic    主题团课库
com.gxwebsoft.gxmu.growth      成长主页聚合
com.gxwebsoft.notice           消息中心
```

接口约定：

- 管理端：`/api/gxmu/{domain}/page|list|{id}|save|update|remove|batch`，沿用 `BaseController` + `BaseParam`，前端继续传 `backendAccess=true`。
- 学生自助：`/api/gxmu/{domain}/my/*`，用 `hasOnlyStudentRole()` 收口，只返回本人数据。
- 审核：不重复造轮子，统一写 `gxmu_review_list`，前端复用 `reviewStatusTag` / `reviewHistoryModal` / `reviewFlowModal`。
- 消息中心按前端既有路径 `/api/oa/notice/*` 实现，顶栏铃铛与 `/user/notice` 无需改代码。

## 六、前端设计

新增目录：

```
src/views/growth/{myHome,credit,practiceCredit,creditWarning,portrait,recommend}
src/views/club/{volunteerHour,volunteerReview,volunteerCertificate,club,activity,activityReview,venue,venueReview,annualReview,award}
src/views/gxmu/{qmgcStudent,qmgcTask,qmgcScore,thematicCourse,teachingDesign,themeDayDesign,expertReview,expertPool}
src/views/system/{messageTemplate,messageLog}
```

复用清单：

- 列表骨架 `ele-pro-table`，照 `views/gxmu/studentRoster`。
- 导入 `views/gxmu/components/common-import.vue`。
- 附件 `components/attachmentList.vue` + `views/gxmu/utils/attachment.ts`。
- 审核 `reviewStatusTag` / `reviewHistoryModal` / `reviewFlowModal`。
- 图表 `utils/use-echarts.ts`，照 `views/gxmu/youthDataCenter`。
- AI 页复制 `activityOutlineGen` 壳 + `utils/ai-stream.ts`。

新建公共件：

1. `components/MultiFileUpload`：统一多附件上传。
2. `components/AiGenPageShell`：AI 生成页外壳。
3. `utils/export.ts`：收敛 Excel/CSV/打印 PDF。

顺带修复：

- `views/user/profile` 保存改用 `PUT /system/user/self`（学生账号当前会因缺 `sys:user:update` 失败）。
- 统一「最新审核记录」排序规则到 `views/gxmu/utils/review.ts`。

## 七、实施顺序

1. 基建：消息中心 + 菜单权限 SQL + 公共上传组件。
2. 学分域：规则/记录/导入 → 成长主页聚合 → 明细页。
3. 志愿域：录入/导入 → 审核 → 汇总。
4. 社团域：社团主档/成员 → 活动 → 场地 → 预约。
5. 青马域：学员档案 → 任务 → 材料。
6. 团课库：建表 → 爬虫 → 列表。
7. P1 / P2 按上表推进。

## 八、待确认事项（有默认值，不阻塞 P0）

| 事项 | 默认假设 |
| --- | --- |
| 第二课堂 / 桂志愿 是否有 API | 先 Excel 导入，`source/external_id` 预留 |
| 学分规则与毕业要求 | 按「学院 + 年级 + 专业 + 类别」配置应修学分 |
| 青马评分标准 | 做成可配置评分项与权重 |
| 社团年审量化指标 | 指标配置表，活动数/参与人次/稿件数自动取数 |
| 指导老师人数 | 社团主档存 1 名主指导，审批节点支持多人 |
| 志愿证明模板与电子章 | 需提供模板与印章图；未提供时用占位版 |
| 团委科研课题是否新申报模块 | 视为新模块，新增 `gxmu_research_project` |
| 数字人形象 | 先用团委现有卡通形象，不做 3D |