b2894lxlx/tuanwei-admin
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d8e7e2a2a824ca2fc8cf35f1635383c1bb8e4f47
tuanwei-admin/.zcode/plans/plan-session_7ab6728b66664f295b2b7d1220f273d7.md
T
gxwebsoft 567e4aabdb feat(user): 支持修改当前用户资料接口并更新个人中心调用 
- 新增 updateSelfUser 方法，用于修改当前登录用户的个人资料
- 个人中心调用接口由原 updateUser 切换为 updateSelfUser，避免学生账号权限不足导致的保存失败
- 更新了头像保存、个人信息保存等相关调用代码，添加异常捕获和提示
- 修正环境变量 .env.development 中 API URL 配置为生产地址
- 优化审核记录排序逻辑，新增获取最新审核记录和编辑入口显示判断函数
- 调整审核状态标签使用统一排序规则，防止显示和编辑状态不一致
- 新增社团活动、社团编辑、志愿时长录入、学分记录编辑、社会实践学分申报、青马学员编辑等多个新增组件及表单功能
- 各新增功能支持表单验证、操作反馈和数据加载优化
2026-11-05 19:03:40 +08:00

19 KiB
Raw Blame History

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

依据《副本二期功能--定稿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 可以立即启动。

Reference in New Issue View Git Blame Copy Permalink