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

> 依据《副本二期功能--定稿0802.docx》（4 大模块 26 项功能），结合 tuanwei-admin（Vue3）与 tuanwei-java（Spring Boot）现有底座制定。文档中括号内的疑问已逐条对应到「待确认项」，未确认处按默认假设推进。

## 一、总体判断

二期不是从零建设。现有系统已经具备四项可复用底座：**申报+审核流引擎**（9 张申报表、三级审核、状态回写）、**学生/教师名册与认领体系**（`gxmu_student.user_id` 是身份主键）、**文件与 Word 导出**（S3 存储、XWPF 直绘、电子签名图片叠加）、**爬虫与异步任务**（jsoup + 定时 + 进度表）。

真正缺失的是三块能力，必须新建：
1. **站内消息中心**——后端完全没有 `oa_notice`，但前端顶栏铃铛和 `/user/notice` 页面已经在调 `/oa/notice/*`，属于「前端等后端」。
2. **业务域**——学分、志愿、社团、场地、青马培养档案、专家评审均无表、无接口。
3. **OCR / PDF 生成**——无 OCR 依赖；PDF 只能靠服务器 LibreOffice 转换。

**结论：全量规划、分三期实施。** 本期（P0）先打通「学生成长主页 + 学分 + 志愿 + 社团场地 + 青马档案 + 消息中心 + 团课库」这条主干，P1 补齐审核类与 AI 类，P2 做画像与数字人。

移动端：本机没有 uni-app 工程，`tuanwei-admin` 是纯 PC 后台。**本期只交付 PC，接口按可对外（`/api/open`）设计**，学生端后续独立建工程，不阻塞本期。

---

## 二、菜单规划

原则：**不动现有 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   评优申报 + 审核 + 公示
```

### 挂到现有菜单

| 现有菜单 | 新增子项 | path |
|---|---|---|
| 数字化团员 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`（已隐藏菜单）+ 顶栏铃铛，零改动即可生效。

### 不推荐但已备选

把「五四评优/学术之星/青马工程」从数字化团员迁到申报系统，结构更清晰，但会动 6 个菜单的 `parent_id` 和全部角色授权，回归风险高。如后续确需重组，单独出一个迁移脚本。

---

## 三、分期实施计划

### P0（本期，可上线的最小闭环）

| # | 功能 | 对应文档 | 交付物 |
|---|---|---|---|
| 1 | 站内消息中心 | 模块一·4 | `oa_notice` + 记录表 + `/oa/notice/*` 接口 + 审核钩子（提交/通过/驳回/待办）+ 顶栏铃铛生效 |
| 2 | 第二课堂学分 | 模块一·1 | 学分规则表 + 学分记录表 + Excel 导入（模板/校验/失败清单）+ 明细页 |
| 3 | 学生成长主页 | 模块一·3 | 聚合接口 + 简历式页面（基本信息/学分/志愿/活动/申报/荣誉） |
| 4 | 志愿时长 | 模块三·1·2 | 个人录入（盖章附件）+ 桂志愿导入 + 二级学院审核 |
| 5 | 社团管理 | 模块三·3·7 | 社团主档 + 成员 + 指导老师 + 活动发起 + 四级审批 |
| 6 | 场地预约 | 模块三·6 | 场地主档 + 日历视图 + 冲突校验 + 指导老师→校团委审批 |
| 7 | 青马培养档案 | 模块二·1 | 学员主档 + 培养材料提交 + 任务清单 + 任务完成度 |
| 8 | 主题团课库 | 模块二·6 | 爬虫（jsoup + 定时 + upsert）+ 列表/详情/下载 + 标签 |
| 9 | 工程配套 | — | 菜单/按钮/角色授权 SQL、字典、权限码、联调回归 |

估算 **53 人日**，2 人并行约 **5.5 周**。

### P1（第二批）

社会实践学分申报（四级审核 + 教务处模板导出）、学分预警（规则 + 定时 + 消息）、智能推荐（内容库 + 规则引擎 + 推送）、学生画像（维度聚合 + 雷达图）、社团年审（指标配置 + 自评 + 自动取数 + 公示）、社团评优、年度志愿证明（docx + 电子章 + PDF）、社团年度报告（聚合 + AI 小结 + 导出）、专家评审（专家库 + 任务 + 分配 + 打分 + 汇总）、AI 辅助教学设计与主题团日设计、**审核流并行审批改造**。

估算 **63 人日**，2 人并行约 **6.5 周**。

### P2（探索期）

AI 学员学习情况分析、AI 定制培养建议、OCR 公章识别接入、AI 数字人（形象 + 浮窗 + 知识库问答）、移动端接口整理。

估算 **23 人日**，约 **2.5 周**。

**合计约 139 人日，2 人并行约 14-15 周。**

---

## 四、数据模型（新表）

统一规范：`id BIGINT AUTO_INCREMENT`、`tenant_id`、`user_id`、`deleted`、`create_time`、`update_time`；附件用 `file_id + file_url` 或 JSON 数组；审批一律复用 `gxmu_review_list(module, pk)`。

### 学分 / 成长域
- `gxmu_credit_rule`：学分类别、项目、分值、认定方式（import/manual/practice）、适用年级
- `gxmu_credit_record`：`user_id, source(second_class|practice|activity), external_id, category, item_name, score, acquire_time, status, evidence`
- `gxmu_practice_credit_apply`：学年、活动名、类型、起止、角色、内容、附件 JSON
- `gxmu_graduate_requirement`：`year, college_id, major, category, required_score`
- `gxmu_credit_warning`：`user_id, category, gap, level, hit_time, notified`
- `gxmu_student_profile`：画像快照（维度分、标签 JSON、更新时间）
- `gxmu_recommend_content`：类型（article/activity）、标题、封面、关联 ID、标签
- `gxmu_recommend_delivery`：`user_id, content_id, channel, is_read`

### 志愿域
- `gxmu_volunteer_record`：`user_id, source(gz|self), project, hours, service_date, org_name, proof_files JSON, status`
- `gxmu_certificate_template`：模板标题、正文占位符、电子章图片、编号前缀
- `gxmu_volunteer_certificate`：`user_id, year, total_hours, serial_no, file_id`

### 社团 / 场地域
- `gxmu_club`：名称、类别、`college_id`、`advisor_user_id`、社长、等级、状态
- `gxmu_club_member`：`club_id, user_id, role, join_time, status`
- `gxmu_club_activity`：`club_id, title, start/end, place, scale, budget, attachments JSON, review_status, ocr_status, ocr_org`
- `gxmu_club_annual_metric`：指标名、权重、取数方式（auto/manual）、公式
- `gxmu_club_annual_review`：`club_id, year, self_score, auto_score, final_score, materials, status`
- `gxmu_club_award_apply`：`club_id, year, award_type, materials, status`
- `gxmu_club_report`：`club_id, year, summary JSON, file_id`
- `gxmu_venue`：名称、楼栋、容量、设备、开放时段、管理员、状态
- `gxmu_venue_booking`：`venue_id, user_id, club_id, booking_date, start_time, end_time, purpose, status`

### 青马域
- `gxmu_qmgc_student`：`user_id, form_id, batch, year, college_id, candidate_no, stage, result`
- `gxmu_qmgc_material`：`student_id, stage, type, title, content, file_id, score`
- `gxmu_qmgc_task`：批次、阶段、标题、类型（online/offline）、跳转方式、截止时间
- `gxmu_qmgc_task_assign`：`student_id, task_id, status, submit_time, score`
- `gxmu_qmgc_score`：`student_id, dimension, item, score, scorer, comment`
- `gxmu_qmgc_exam` / `gxmu_qmgc_exam_record`：题目 JSON、及格线、作答、得分

### 团课 / 专家 / 消息
- `gxmu_thematic_course`：`title, type(courseware|script|video|case|activity), source_site, source_url, source_key UNIQUE, file_id, content, tags, heat`
- `gxmu_expert`：`user_id, name, college, field_code, level, phone`
- `gxmu_expert_review_task`：`module, declare_id, round, start/end, quota`
- `gxmu_expert_review_assign`：`task_id, expert_id, status`
- `gxmu_expert_review_score`：`assign_id, dimensions JSON, total, comment, submit_time`
- `oa_notice` + `oa_notice_record`：从 `/Users/gxwebsoft/JAVA/com.gxwebsoft.open` 移植，字段对齐前端已有的 `noticeRecordId/type/files/channel/progress`

### 对现有表的改动（小步、可回滚）
1. `gxmu_review_flow` + `gxmu_review_list` 增加 `parallel_group INT NULL` —— 支持「二级学院团委与党委同时审核」。
2. `gxmu_review_list` 增加 `attachments TEXT` —— 审核节点上传盖章附件。
3. `gxmu_declare.module` 若新增「团委科研课题」，同步加枚举（见待确认项）。

---

## 五、后端设计

### 包结构（新增，不动现有 24 个 gxmu 控制器）

```
com.gxwebsoft.gxmu.credit/    学分规则、记录、导入、预警
com.gxwebsoft.gxmu.qmgc/      青马学员、任务、评分、考试
com.gxwebsoft.gxmu.club/      社团、活动、年审、评优、年度报告
com.gxwebsoft.gxmu.venue/     场地与预约
com.gxwebsoft.gxmu.volunteer/ 志愿时长与证明
com.gxwebsoft.gxmu.thematic/  主题团课库与爬虫
com.gxwebsoft.gxmu.portrait/  画像与推荐
com.gxwebsoft.gxmu.expert/    专家评审
com.gxwebsoft.notice/         消息中心（移植 + 渠道）
```

每个子包内 `controller/entity/mapper/service/param`，与现有 `gxmu.openplat` 的组织方式一致。

### 接口约定

- 管理端统一 `/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/*` 实现（`page`/`list`/`{id}`/`getUnReadNum`/`save`/`update`/`remove`），顶栏铃铛和 `/user/notice` 不需要改一行代码。
- 导出走现有模式：Controller 生成文件 → `FileStorageService.storeFile` → `FileRecord` → 返回下载地址。

### 关键改造：审核流支持并行节点

现状：`ReviewListController.update` 用 `sortNumber + 1` 取下一节点，隐含「一个节点一个人」。青马选拔要求团委与党委**同时审核**，因此：
- 模板按 `level` 分组，同 `level` 的多行属于同一并行组；
- 通过时先检查同组是否还有 `status=0` 的节点，有则不推进；
- 同组全部通过才进入下一 `level`；
- 组内任一驳回是否终止整条流，做成 `ReviewFlowConfig.rejectMode`（任一驳回 / 全部驳回后终止），默认前者。
- 该改造同时被社会实践学分、社团活动、场地预约复用。

### 关键改造：学分引擎

不引入规则引擎，用「配置表 + 计算服务」：
1. `CreditRuleService.resolve(userId, year)` 按学院/年级/专业匹配 `gxmu_graduate_requirement`，得到各类别应修学分。
2. `CreditSummaryService` 汇总 `gxmu_credit_record` 中 `status=有效` 的记录，按类别输出「已修/应修/差额/完成率」。
3. 预警任务每天跑一次：差额 > 0 且距毕业不足 N 学期 → 生成 `gxmu_credit_warning` + 发站内消息；同一学生同一类别本月只发一次。
4. 推荐：先做规则匹配（缺分 → 推荐可加分的活动/课程，按标签和学院过滤），AI 排序留到 P2。

### 关键技术点

- **志愿证明 PDF**：XWPF 直绘（复用 `WxxzxDocxExportUtil` 的 `addPicture` 叠电子章）→ `OpenOfficeUtil.converterToPDF` → 存 `FileRecord`。若服务器无 `soffice`，降级为前端打印（复用 `youthDataCenter.exportPdf` 模式），不阻塞上线。
- **团课库爬虫**：完全复用 `CrossSchoolActivityCrawlerServiceImpl` 范式（站点配置 + jsoup + `source_key` 唯一键 + `batchUpsert` + 定时任务 + 手动 `/sync`），新增文件下载入库。
- **AI 扩展**：`DifyProperties.AppKeys` 增加 4 个应用 key；`AiChatType` 增加 `teaching_design / theme_day_design / student_analysis / training_advice`；新增 `/api/ai/{xxx}` 与 `/stream`，沿用 `AiGenerationRecorder` 落历史。
- **OCR**：不引入本地推理。P1 通过阿里云 OCR HTTP 接口（需开通 + AK），字段预留 `ocr_status/ocr_org/ocr_raw`；未开通时走「人工核验 + 附件留痕」。
- **消息渠道**：站内信必做；企业微信在 `WxWorkUtil` 增加 `message/send`（token 逻辑已有）；短信暂不做。

---

## 六、前端设计

### 目录与页面

```
src/views/growth/
  myHome/          我的成长（简历式：基本信息/学分/志愿/活动/申报/荣誉）
  credit/          学分明细（类别筛选 + 来源 + 明细表 + 导入）
  practiceCredit/  社会实践学分（申报表单 + 审核状态）
  creditWarning/   学分预警（雷达/进度条/建议）
  portrait/        学生画像
  recommend/       推荐内容
src/views/club/
  volunteerHour/   我的志愿时长（录入 + 导入 + 列表）
  volunteerReview/ 志愿时长审核
  volunteerCertificate/
  club/            社团管理（主档 + 成员抽屉）
  activity/        社团活动
  activityReview/  活动审批（复用 reviewFlowModal）
  venue/           场地预约（日历 + 预约弹窗）
  venueReview/
  annualReview/    年审（指标 + 自评 + 打分）
  award/
src/views/gxmu/
  qmgcStudent/ qmgcTask/ qmgcScore/ thematicCourse/
  teachingDesign/ themeDayDesign/
  expertReview/ expertPool/
src/views/system/
  messageTemplate/ messageLog/
```

### 复用清单（不要重写）

- 列表骨架：`ele-pro-table` + `.page/.ele-body/a-card`，照 `studentRoster`。
- 导入：`views/gxmu/components/common-import.vue`（模板下载、逐行校验、失败清单）。
- 附件：`components/attachmentList.vue` + `views/gxmu/utils/attachment.ts`；单文件用 `components/UploadFile`。
- 审核：`reviewStatusTag` / `reviewHistoryModal` / `reviewFlowModal` / `views/gxmu/utils/review.ts`。
- 图表：`utils/use-echarts.ts` + `vue-echarts`，照 `youthDataCenter`。
- 导出：Excel 用 `xlsx`；打印式 PDF 照 `youthDataCenter.exportPdf`；docx 用 `html-docx-js-typescript`。
- AI 页：复制 `activityOutlineGen` 壳 + `utils/ai-stream.ts` + `utils/ai-result.ts`。
- 权限：`hasPermission` / `v-permission`；角色用 `hasAnyRole`（`hasRole` 是「全部满足」语义）。

### 需要新建的公共件

1. `components/MultiFileUpload`：统一多附件上传（现有各表单各写了一套）。
2. `components/AiGenPageShell`：把「左侧表单 + 右侧流式输出 + 历史入口」抽出，避免再复制 4 个 800-1300 行的页面。
3. `utils/export.ts`：收敛 Excel/CSV/打印 PDF 的重复代码。
4. `src/constants/permissions.ts`：集中权限码。

### 顺带修的两个既有问题

- `views/user/profile` 保存走 `PUT /system/user`（要 `sys:user:update`），学生账号会失败。改为后端已有的 `PUT /system/user/self`，成长主页的「编辑资料」直接受益。
- `reviewStatusTag` 按 `id` 取最新，`utils/review.ts` 按 `createTime+id`，两处规则不一致。二期接入新审核模块前统一到 `utils/review.ts`。

---

## 七、实施顺序（建议按此推进）

1. **基建先行**：消息中心（表 + 移植 + 钩子）+ 菜单/权限 SQL + 字典 + `MultiFileUpload`。
2. **学历域**：学分规则/记录/导入 → 成长主页聚合 → 明细页。
3. **志愿域**：录入/导入 → 审核 → 证明（证明依赖 LibreOffice，放最后）。
4. **社团域**：社团主档/成员 → 活动 → 四级审批 → 场地日历 → 场地审批。
5. **青马域**：学员档案 → 任务 → 材料 → （P1）评分/考试。
6. **团课库**：建表 → 爬虫 → 列表/详情。
7. **P1**：学分预警/推荐/画像 → 社会实践 → 社团年审/评优/年报 → 专家评审 → AI 教学设计/团日设计 → 审核流并行改造（此改造需在青马选拔上线前完成，实际应提前到 P0 末尾）。
8. **P2**：AI 学员分析/培养建议 → OCR → 数字人。

每批交付都包含：建表 SQL（可重复执行）、菜单/按钮 SQL、后端接口、前端页面、联调、回归。第一步先在仓库落地 `docs/phase2-implementation-plan.md`（本方案）和 `docs/sql/phase2_*.sql`。

---

## 八、待你确认的业务细节（有默认值，确认前按默认推进）

| 事项 | 默认假设 | 影响 |
|---|---|---|
| 第二课堂 / 桂志愿 是否有 API | 先 Excel 导入，`source/external_id` 预留，后续换数据源 | P0 导入模板字段 |
| 学分规则与毕业要求 | 按「学院 + 年级 + 专业 + 类别」配应修学分，由管理员在后台维护 | 预警准确性 |
| 青马评分标准/任务清单 | 评分项和权重做成可配置表，任务分线上（可跳转）与线下（仅勾选） | P1 评分页 |
| 社团年审量化指标 | 做成指标配置表，活动数/参与人次/稿件数可自动取数，其余人工 | P1 年审 |
| 指导老师是单人还是多人 | 社团主档存 1 名主指导，审批节点支持多人并行 | 审批流 |
| 志愿证明模板与电子章 | 需要你提供模板文件与印章图片；未提供时用占位版 | P1 证明 |
| 「团委科研课题」是否新申报模块 | 视为新模块，新增 `gxmu_research_project` 表并加入申报枚举 | 专家评审范围 |
| 数字人形象 | 先用团委现有卡通形象，不做 3D | P2 |

其中前三项不确认就无法开工；其余可边做边定。**只要前三项给出结论，P0 可以立即启动。**