hzdyjs/docs/需求文档/社团管理需求/社团管理系统需求说明.md

社团管理系统需求说明

1. 项目定位

• 一级模块：社团管理系统（Club Management System）
• 功能标识前缀：stgl_（社团管理-sheTuanGuanLi）
• 技术架构：前后端分离 + 移动端
• 主要角色：社团管理员、指导老师、社长、副社长、成员、学生

2. 业务背景与目标

2.1 业务背景

校园社团管理需要支持社团创建、活动组织、成员管理、考勤签到、材料收集等全流程管理，同时支持志愿者队伍管理，提升校园社团活动的组织效率和管理水平。

2.2 业务目标

• 建立完整的社团信息管理体系
• 支持灵活的活动创建、报名、审批流程
• 实现地理位置签到和考勤管理
• 提供多维度的材料收集功能
• 支持活动评分和质量评估
• 建立数据权限和角色权限体系

3. 主要功能模块

3.1 社团基础管理

• 社团信息管理：创建、编辑、删除、转让社团
• 成员管理：支持单个/批量导入成员，角色分配（社长、副社长、成员）
• 权限管理：指导老师可授权不同人员负责社团活动创建和审批
• 信息查看：支持查看社团信息、成员信息

3.2 志愿者队伍管理

• 队伍管理：新增、编辑、删除、转让志愿者队伍
• 成员管理：支持单个/批量导入志愿者成员
• 信息查看：支持查看志愿者队伍信息

3.3 活动管理

• 活动创建：支持活动创建、导出、复制功能
• 信息管理：包含基本信息、主办承办方、指导老师、报名设置等
• 筛选功能：根据名称、主办方、承办方、活动状态、日期等筛选
• 审批流程：活动审批流程跟踪（暂不挂工作流）
• 评分管理：查看用户对活动的评分情况（5分制，1-5星评分）

3.4 报名管理

• 报名功能：学生报名社团、志愿者队伍、活动
• 报名方式：支持个人报名和团队报名
• 审核管理：支持报名审核（保存、提交、审核功能）
• 材料查看：支持团队报名材料查看

3.5 考勤与签到管理

• 考勤任务：考勤任务新建、停止等操作
• 签到功能：支持地理位置签到
  • Web端：仅更改签到状态，不记录位置
  • 移动端：记录签到状态和签到位置
• 数据管理：根据名称、活动状态等筛选考勤数据
• 统计导出：完成从任务发起、学生打卡、结束到数据统计导出的全流程

3.6 材料收集管理

• 收集设置：活动过程自定义收集材料（文本、附件、图片）
• 多轮收集：支持多次收集、关闭或恢复材料征集
• 材料管理：材料查看、状态管理

3.7 数据管理

• 导入导出：支持Excel格式的导入导出
• 数据权限：根据添加人或其所在组织划分数据权限
• 成员管理：活动详情中可查看基本信息、成员获得成绩情况、添加或删除成员

4. 角色权限体系

4.1 角色定义

• 社团管理员：系统级管理员，拥有所有功能权限
• 指导老师：可授权人员负责社团活动创建和审批，分配社团成员管理权限
• 社长：社团最高负责人，无特殊权限差异
• 副社长：社团副负责人，无特殊权限差异
• 成员：普通社团成员，无特殊权限差异
• 学生：可报名参加社团、活动
• 班主任：有权限查看自己班级学生社团参与情况

4.2 权限说明

• 社团内部角色（社长、副社长、成员）暂无权限差异
• 权限管理通过系统管理-角色管理中增加角色，为角色分配用户实现
• 数据权限按照添加人或其所在组织进行划分

5. 数据结构设计

5.1 基础字段要求

所有业务表必须包含以下标准字段（顺序和类型完全一致）：

`id` bigint(20) NOT NULL COMMENT '主键ID',
`tenant_id` varchar(20) NOT NULL DEFAULT '000000' COMMENT '租户编号',
`create_dept` bigint(20) DEFAULT NULL COMMENT '创建部门',
`create_by` bigint(20) DEFAULT NULL COMMENT '创建者',
`create_time` datetime DEFAULT NULL COMMENT '创建时间',
`update_by` bigint(20) DEFAULT NULL COMMENT '更新者',
`update_time` datetime DEFAULT NULL COMMENT '更新时间',
`deleted` tinyint(1) DEFAULT 0 COMMENT '删除标志（0代表存在 1代表删除）'

5.2 社团信息表（stgl_club）

基本信息字段

• club_name varchar(100) NOT NULL COMMENT '社团名称（唯一）'
• club_type varchar(50) NOT NULL COMMENT '社团类型'
• establish_date date COMMENT '成立日期'
• description text COMMENT '社团简介（500字以内）'
• email varchar(100) COMMENT '邮箱'
• phone varchar(20) COMMENT '电话'
• logo_url varchar(500) COMMENT 'logo图片路径'

管理人员信息

• president_name varchar(50) COMMENT '社长姓名'
• president_student_no varchar(20) COMMENT '社长学号'
• president_dept varchar(100) COMMENT '社长院系'
• president_major varchar(100) COMMENT '社长专业'
• president_class varchar(100) COMMENT '社长班级'
• president_phone varchar(20) COMMENT '社长联系方式'
• vice_president_name varchar(50) COMMENT '副社长姓名'
• vice_president_student_no varchar(20) COMMENT '副社长学号'
• advisor_name varchar(50) COMMENT '指导老师姓名'
• advisor_dept varchar(100) COMMENT '指导老师所属院系'

运营信息

• member_limit int DEFAULT 0 COMMENT '成员规模上限'
• departments text COMMENT '组织架构（部门设置及职责）'
• recruit_cycle varchar(50) COMMENT '招新周期'
• recruit_time varchar(50) COMMENT '招新时间'
• activity_frequency varchar(50) COMMENT '活动频率'
• funding_sources varchar(200) COMMENT '经费来源（多选）'
• charter_url varchar(500) COMMENT '章程文档路径'
• honors text COMMENT '历史荣誉'
• status tinyint DEFAULT 1 COMMENT '状态（1-正常 0-停用）'

社团类型码表值

• 学术科技类
• 文化艺术类
• 体育健身类
• 实践技能类
• 兴趣爱好类
• 思想政治类

5.3 活动信息表（stgl_activity）

基本信息

• activity_name varchar(100) NOT NULL COMMENT '活动名称'
• activity_type varchar(50) NOT NULL COMMENT '活动类型'
• activity_theme varchar(100) COMMENT '活动主题'
• start_time datetime COMMENT '开始时间'
• end_time datetime COMMENT '结束时间'
• location varchar(200) COMMENT '活动地点'
• description text COMMENT '活动简介（1000字以内）'
• poster_url varchar(500) COMMENT '活动海报路径'
• related_club_id bigint(20) COMMENT '关联社团ID'

主办承办方信息

• organizer_name varchar(100) COMMENT '主办方名称'
• organizer_type varchar(50) COMMENT '主办方类型'
• organizer_contact varchar(100) COMMENT '主办方联系人'
• organizer_phone varchar(20) COMMENT '主办方电话'
• co_organizers text COMMENT '承办方信息（JSON格式存储多个承办方）'

指导老师信息

• instructors text COMMENT '指导老师列表（JSON格式）'

报名管理信息

• registration_type tinyint COMMENT '报名方式（1-个人 2-团队 3-两者均可）'
• registration_start datetime COMMENT '报名开始时间'
• registration_end datetime COMMENT '报名结束时间'
• registration_status tinyint COMMENT '报名状态（0-未开始 1-报名中 2-已截止 3-已关闭）'
• max_participants int COMMENT '总人数上限'
• max_teams int COMMENT '团队数量上限'
• team_size_min int COMMENT '每队最小人数'
• team_size_max int COMMENT '每队最大人数'
• need_approval tinyint DEFAULT 0 COMMENT '是否需要审核（0-无需 1-需要）'

活动状态信息

• activity_status varchar(20) COMMENT '活动状态'
• is_finished tinyint DEFAULT 0 COMMENT '是否为已办活动'
• summary text COMMENT '活动总结报告'
• achievements text COMMENT '活动成果'
• import_source varchar(200) COMMENT '导入来源信息'

活动类型码表值

• 学术科技类
• 文化艺术类
• 体育健身类
• 志愿公益类
• 实践技能类
• 兴趣爱好类
• 思想政治类

活动状态码表值

• 筹备中
• 待审批
• 已通过
• 进行中
• 已结束
• 已取消
• 已驳回

5.4 志愿者队伍表（stgl_volunteer_team）

基本信息

• team_name varchar(100) NOT NULL COMMENT '队伍名称'
• team_type varchar(50) COMMENT '队伍类型'
• description text COMMENT '队伍简介'
• leader_name varchar(50) COMMENT '队长姓名'
• leader_student_no varchar(20) COMMENT '队长学号'
• advisor_name varchar(50) COMMENT '指导老师'
• member_limit int DEFAULT 0 COMMENT '成员上限'
• status tinyint DEFAULT 1 COMMENT '状态（1-正常 0-停用）'

5.5 成员关系表（stgl_member）

• member_type tinyint COMMENT '成员类型（1-社团成员 2-志愿者）'
• relation_id bigint(20) COMMENT '关联ID（社团ID或志愿者队伍ID）'
• user_id bigint(20) COMMENT '用户ID'
• student_no varchar(20) COMMENT '学号'
• student_name varchar(50) COMMENT '学生姓名'
• role_type tinyint COMMENT '角色类型（1-社长 2-副社长 3-成员）'
• join_time datetime COMMENT '加入时间'
• status tinyint DEFAULT 1 COMMENT '状态（1-正常 0-退出）'

5.6 活动报名表（stgl_activity_registration）

基本信息

• activity_id bigint(20) NOT NULL COMMENT '活动ID'
• user_id bigint(20) COMMENT '用户ID'
• student_no varchar(20) COMMENT '学号'
• student_name varchar(50) COMMENT '学生姓名'
• registration_type tinyint COMMENT '报名类型（1-个人 2-团队）'
• team_id bigint(20) COMMENT '团队ID（团队报名时）'
• team_name varchar(100) COMMENT '团队名称'
• registration_time datetime COMMENT '报名时间'
• remark text COMMENT '申请理由（非必填）'

审核信息

• approval_status tinyint COMMENT '审核状态（0-待审核 1-通过 2-驳回）'
• approval_time datetime COMMENT '审核时间'
• approval_by bigint(20) COMMENT '审核人'
• approval_remark varchar(500) COMMENT '审核意见'

成绩信息

• score varchar(50) COMMENT '获得成绩'
• score_time datetime COMMENT '成绩录入时间'
• score_by bigint(20) COMMENT '成绩录入人'

外键约束

• FOREIGN KEY (activity_id) REFERENCES stgl_activity(id)
• FOREIGN KEY (team_id) REFERENCES stgl_activity_team_info(id)

5.7 活动团队信息表（stgl_activity_team_info）

基本信息

• team_name varchar(100) NOT NULL COMMENT '团队名称'
• activity_id bigint(20) NOT NULL COMMENT '关联活动ID'
• leader_user_id bigint(20) NOT NULL COMMENT '队长用户ID'
• leader_name varchar(50) COMMENT '队长姓名'
• leader_student_no varchar(20) COMMENT '队长学号'
• team_members json COMMENT '团队成员信息（JSON格式）'
• team_size int DEFAULT 0 COMMENT '团队人数'
• description text COMMENT '团队简介'

外键约束

• FOREIGN KEY (activity_id) REFERENCES stgl_activity(id)

5.8 考勤任务表（stgl_attendance_task）

• activity_id bigint(20) COMMENT '关联活动ID'
• task_name varchar(100) COMMENT '考勤任务名称'
• task_status tinyint COMMENT '任务状态（0-未发起 1-进行中 2-已停止 3-已结束）'
• start_time datetime COMMENT '签到开始时间'
• end_time datetime COMMENT '签到结束时间'
• location_required tinyint DEFAULT 0 COMMENT '是否需要地理位置（0-否 1-是）'
• check_location varchar(200) COMMENT '签到地点'
• location_range int DEFAULT 500 COMMENT '允许签到范围（米）'

5.9 签到记录表（stgl_attendance_record）

• task_id bigint(20) COMMENT '考勤任务ID'
• user_id bigint(20) COMMENT '用户ID'
• student_no varchar(20) COMMENT '学号'
• student_name varchar(50) COMMENT '学生姓名'
• check_time datetime COMMENT '签到时间'
• check_status tinyint COMMENT '签到状态（1-已签到 2-迟到 0-未签到）'
• check_location varchar(100) COMMENT '签到位置（经纬度）'
• device_type tinyint COMMENT '设备类型（1-Web 2-移动端）'

5.10 材料收集任务表（stgl_material_task）

• activity_id bigint(20) COMMENT '关联活动ID'
• task_name varchar(100) COMMENT '收集任务名称'
• collection_types varchar(100) COMMENT '收集类型（文本,附件,图片）'
• task_description text COMMENT '收集说明'
• task_status tinyint COMMENT '任务状态（1-开启 0-关闭）'
• deadline datetime COMMENT '截止时间'
• round_number int DEFAULT 1 COMMENT '收集轮次'

5.11 材料提交记录表（stgl_material_submission）

• task_id bigint(20) COMMENT '收集任务ID'
• user_id bigint(20) COMMENT '提交人ID'
• submission_type tinyint COMMENT '提交类型（1-个人 2-团队）'
• content_text text COMMENT '文本内容'
• file_urls text COMMENT '附件路径（JSON格式）'
• image_urls text COMMENT '图片路径（JSON格式）'
• submission_time datetime COMMENT '提交时间'
• round_number int DEFAULT 1 COMMENT '提交轮次'

5.12 活动评分表（stgl_activity_rating）

• activity_id bigint(20) COMMENT '活动ID'
• user_id bigint(20) COMMENT '评分人ID'
• rating_score decimal(3,1) COMMENT '综合评分(1-5分，保留1位小数)'
• rating_comment varchar(500) COMMENT '评分备注'
• rating_time datetime COMMENT '评分时间'

6. 系统集成需求

6.1 学生信息系统集成

• 班级信息：集成班级表 xg_class_msg
• 学生信息：集成学生信息表 xg_student_msg
• 用户信息：集成用户表 sys_user
• 数据同步：确保学生、班级信息的实时同步

6.2 通知系统集成

• 活动通知：活动创建、开始、结束通知
• 报名结果通知：报名审核结果通知
• 考勤提醒：签到开始、结束提醒
• 材料收集通知：材料征集开始、截止提醒

7. 技术架构要求

7.1 技术栈

• 前端：Vue 3 + TypeScript + Element Plus
• 后端：Spring Boot 3.4.6 + MyBatis-Plus
• 移动端：Vue 3.4.21 + uni-app + uview-plus 3.4.45
• 数据库：MySQL（遵循雪花ID、逻辑删除、多租户规范）

7.2 开发规范

• 数据库：遵循标准基础字段、雪花ID主键、逻辑删除
• API接口：统一响应格式、Token认证、权限注解
• 文档管理：代码变更必须同步更新API文档
• 导入导出：统一使用Excel格式

7.3 部署要求

• 前端访问：http://localhost (默认80端口)
• 后端服务：http://localhost:8080
• 移动端：支持H5、微信小程序、App等多端发布

8. 特殊要求

8.1 码表管理

• 所有码表数据直接存储在数据库中
• 不通过系统管理-字典管理配置
• 码表数据在建表SQL中直接初始化

8.2 地理位置签到

• Web端：仅更改签到状态，不记录地理位置
• 移动端：记录签到状态和签到位置（经纬度）
• 位置验证：支持设置签到范围，默认500米

8.3 工作流集成准备

• 当前版本不挂接工作流
• 预留工作流接口：保存、提交、审核功能按钮
• 后续版本通过"提交"按钮进入工作流

9. 开发优先级

9.1 第一阶段（核心功能）

1. 社团基础管理（社团信息、成员管理）
2. 活动管理（活动创建、基本信息管理）
3. 报名管理（个人报名、审核功能）

9.2 第二阶段（扩展功能）

1. 考勤签到管理
2. 材料收集管理
3. 活动评分系统

9.3 第三阶段（完善功能）

1. 志愿者队伍管理
2. 统计报表功能
3. 移动端功能完善

10. 验收标准

• ✅ 完整的社团管理功能（创建、编辑、成员管理）
• ✅ 活动全生命周期管理（创建、报名、考勤、评分）
• ✅ 地理位置签到功能（区分Web端和移动端）
• ✅ 材料收集和多轮征集功能
• ✅ Excel导入导出功能
• ✅ 完整的权限控制和数据权限
• ✅ 与学生信息系统和通知系统集成
• ✅ 符合项目开发规范和文档要求