gxwebsoft
567e4aabdb
- 新增 updateSelfUser 方法，用于修改当前登录用户的个人资料 - 个人中心调用接口由原 updateUser 切换为 updateSelfUser，避免学生账号权限不足导致的保存失败 - 更新了头像保存、个人信息保存等相关调用代码，添加异常捕获和提示 - 修正环境变量 .env.development 中 API URL 配置为生产地址 - 优化审核记录排序逻辑，新增获取最新审核记录和编辑入口显示判断函数 - 调整审核状态标签使用统一排序规则，防止显示和编辑状态不一致 - 新增社团活动、社团编辑、志愿时长录入、学分记录编辑、社会实践学分申报、青马学员编辑等多个新增组件及表单功能 - 各新增功能支持表单验证、操作反馈和数据加载优化
296 lines
19 KiB
Markdown
296 lines
19 KiB
Markdown
# 团委智能化平台二期实施方案
|
||
|
||
> 依据《副本二期功能--定稿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 可以立即启动。**
|