时序同笺 (SDNUChronoSync)

🌐 在线访问

线上地址：https://sxtj.hxcn.space

欢迎访问在线版本，体验完整的课表与日程管理功能。

📋 项目简介

时序同笺 (SDNUChronoSync) 是一个现代化的、全功能的多用户课表与日程管理 Web 应用，专为山东师范大学设计。支持个人多课表管理、高级调休功能、完整的团队协作系统，以及灵活的管理员控制功能。专为教育机构和团队协作场景设计。

✨ 功能特性

个人日程管理

多课表管理：支持创建多个课表，如"大二上学期"、"大二下学期"等
灵活导入方式：
- 从正方教务系统一键导入课表
- 从ICS文件导入（支持其他日历应用导出的文件）
- 手动创建日程事件
灵活的日程编辑：支持手动创建、编辑和删除日程事件
多视图模式：周视图和月视图自由切换
多种导出格式：
- 导出为PNG图片，方便分享截图
- 导出为ICS文件，兼容各大日历应用（苹果日历、Google Calendar等）

智能调休系统

节假日设置：HOLIDAY类型调整，逻辑隐藏指定日期的所有课程
智能换课系统：SWAP类型调整，将源日期课程完整移动到目标日期
服务器端逻辑：调休计算在后端处理，确保数据一致性和完整性
调休记录追踪：完整记录所有调休操作的历史和影响范围
实时生效机制：调休设置立即在课表视图中反映，无需刷新

团队协作系统

智能邀请机制：8位随机邀请码（大写字母+数字，避免易混淆字符0,O,1,I）
灵活团队管理：团队创建者自动成为管理员，支持添加/移除成员
团队管理员角色：支持指定团队管理员，分担团队管理工作
- 创建者可以提升成员为团队管理员
- 团队管理员拥有成员管理和课表管理权限
- 支持随时添加或移除团队管理员权限
团队所有权转让：创建者可以将团队管理权转让给其他成员
分层权限控制：系统管理员 > 团队创建者 > 团队管理员 > 普通成员的四级权限体系
团队课表聚合：实时查看团队所有成员的活跃课程安排和时间冲突
高级筛选功能：支持按成员姓名、学号、班级、年级等多维度筛选
便捷成员操作：通过学号精确添加成员，支持成员自主退出和管理员移除
团队生命周期管理：从创建、管理、转让到解散的完整流程

管理员功能

用户管理：创建、编辑、删除用户账户
用户状态管理：支持封禁和恢复用户账户
登录记录监控：查看所有用户的登录历史和活动追踪
批量操作：支持批量删除、封禁、恢复用户
团队监控：监管所有团队的运行状态
系统设置：配置头像上传、存储等系统参数

UI/UX 特性

响应式设计：完美适配桌面、平板和手机
统一模态框系统：基于Headless UI的可访问性组件
智能加载指示器：统一的加载状态视觉反馈
实时状态反馈：操作结果立即反馈给用户
直观的视觉设计：清晰的信息层次和交互指引
批量操作支持：高效的批量管理功能
更新日志集成：实时查看系统版本更新内容

高性能架构

前后端分离：Astro + Vue.js 前端，FastAPI 后端
智能状态管理：Pinia 驱动的响应式状态系统
数据库优化：SQLAlchemy ORM 的高效查询
API设计：RESTful接口设计，支持并发访问

📖 使用指南

🎯 个人课表管理

创建课表：
- 访问"我的课表"页面
- 点击课表下拉菜单中的"新建课表"
- 设置课表名称、学期开始日期和总周数
使用"更多"操作菜单：
- 点击页面右上角的"更多"按钮，可访问以下功能：
  - 添加日程：手动创建日程事件
  - 导入课表：选择从ICS文件或教务系统导入
  - 导出课表：导出为PNG图片或ICS文件
  - 放假调休：设置节假日和课程对调
  - 课表设置：编辑课表名称、日期等信息
导入课程：
- 从教务系统导入：
  - 点击"更多" → "导入课表" → "从教务系统导入"
  - 输入学号、密码和验证码
  - 系统自动获取并导入课表
- 从ICS文件导入：
  - 点击"更多" → "导入课表" → "从ICS文件导入"
  - 选择从其他日历应用导出的.ics文件
  - 系统自动解析并导入事件
- 手动添加：
  - 点击"更多" → "添加日程"
  - 或直接点击日历上的日期
导出课表：
- 导出为图片：
  - 点击"更多" → "导出课表" → "导出到图片(PNG)"
  - 适合分享给他人或打印
- 导出为ICS：
  - 点击"更多" → "导出课表" → "导出到ICS"
  - 可导入到苹果日历、Google Calendar等应用
多课表管理：
- 支持同时管理多个课表（如不同学期）
- 通过下拉菜单快速切换活跃课表
- 每个课表独立管理课程和调休设置

🎯 高级调休功能

节假日设置（HOLIDAY类型）：
- 在"我的课表"页面点击"更多" → "放假调休"
- 选择"设置假期"模式
- 选择需要放假的日期
- 点击"确认放假"，系统将逻辑隐藏该日期的所有课程
智能换课（SWAP类型）：
- 点击"更多" → "放假调休"
- 选择"对调工作日"模式
- 设置源日期（需要移动的课程日期）
- 设置目标日期（课程移动到的日期）
- 系统自动创建覆盖事件，保持原有课程信息
调休记录管理：
- 所有调休操作记录在ScheduleAdjustment表中
- 支持查看调休历史和影响的事件数量
- 调休效果立即在课表视图中生效

🎯 团队协作系统

1. 创建团队

访问"我的团队"页面（导航栏"团队"菜单）
在"创建新团队"区域输入团队名称
点击"创建团队"按钮
系统自动生成8位安全邀请码（避免0O1I等易混淆字符）
创建者自动成为团队管理员并加入成员列表
页面显示团队代码，可一键复制分享给成员

2. 加入团队

向团队创建者获取8位团队邀请码
在"加入团队"区域输入邀请码（自动转换为大写）
点击"加入团队"按钮
系统验证邀请码有效性后自动加入团队
成功加入后可立即查看团队课表

3. 团队管理（创建者和团队管理员）

基础管理：

点击团队卡片上的"管理团队"按钮
打开高级团队管理面板
查看创建的所有团队及成员统计 成员管理：
添加成员：在团队编辑窗口输入学号，系统自动查找并添加用户
移除成员：点击成员列表中的"移除"按钮删除成员
- 团队管理员可以移除普通成员
- 不能移除团队创建者和系统管理员
查看成员：查看所有成员的姓名、学号、班级等信息 团队管理员管理（仅创建者）：
提升管理员：
- 在团队成员列表中选择普通成员
- 点击"设为管理员"按钮
- 该成员将获得团队管理权限
- 团队管理员可以管理成员、编辑团队信息
移除管理员：
- 在团队管理员列表中选择要降级的管理员
- 点击"移除管理员"按钮
- 该用户将降级为普通成员 团队转让（仅创建者）：
点击"转让团队"按钮
从当前成员列表中选择新的团队创建者
确认后，团队所有权和管理权限将转移给新创建者
原创建者将变成普通成员 解散团队（仅创建者）：
点击"解散团队"按钮
输入团队名称进行二次确认
确认后团队及所有成员关系将被永久删除
此操作不可撤销

4. 退出团队（普通成员）

在"我的团队"页面找到要退出的团队
点击团队卡片上的"退出团队"按钮
在弹出的确认窗口中确认退出
退出后将无法再访问该团队的课表

5. 团队课表聚合视图

查看团队课表：

点击团队卡片上的"查看课表"按钮
进入团队课表聚合视图页面
显示所有成员的活跃课表（status="进行"）
不同成员的课程用不同颜色标识 高级筛选功能：
按成员筛选：勾选特定成员，只显示其课程
按班级筛选：选择班级，显示该班级所有成员的课程
按年级筛选：选择年级，显示该年级所有成员的课程
关键词搜索：搜索成员姓名或课程名称
移动端支持：移动端提供侧边筛选抽屉 视图模式：
周视图：查看一周的课程安排，适合查看详细时间
月视图：查看整月的课程分布，适合宏观规划
日期导航：前后翻页或跳转到今天 课程冲突识别：
同一时间多个成员有课时，可点击查看详情
显示所有冲突的课程列表
标识出每门课的授课教师和地点
便于协调团队会议时间

6. 管理员团队监控

访问管理后台"团队管理"页面
查看系统中所有团队的统计信息
搜索和筛选特定团队
查看任意团队的成员列表
必要时删除不活跃或违规的团队

🎯 管理员功能

用户管理：
- 创建、编辑、删除用户账户
- 重置用户密码和角色权限
- 查看用户的课表和活动统计
- 用户账户封禁和恢复功能
- 批量操作：批量删除、封禁、恢复用户
- 查看用户登录历史和最近登录记录
系统设置：
- 配置头像上传方式（本地存储/AList）
- 设置文件上传限制和存储路径
- 管理系统全局配置参数
团队监控：
- 查看所有团队信息
- 必要时删除团队
- 监控团队活动和成员状况

🛠️ 技术栈

前端

Astro - 静态站点生成和路由
Vue.ts 3 - 交互式 UI 组件
Tailwind CSS - 响应式样式框架
Headless UI - 无样式 UI 组件
Pinia - 状态管理
Axios - HTTP 客户端

后端

Python 3.10+ - 编程语言
FastAPI - Web 框架
SQLAlchemy - ORM
SQLite - 数据库
JWT - 用户认证
ICS - 日历导出

📁 项目结构

SDNUChronoSync/
├── backend/                 # 后端代码
│   ├── main.py             # 应用入口
│   ├── models.py           # 数据模型 (User, Schedule, Event, ScheduleAdjustment, Team, LoginRecord)
│   ├── schemas.py          # Pydantic 模式 (包含团队、调休、登录记录相关模式)
│   ├── crud.py             # 数据库操作 (团队CRUD + 调休记录 + 登录记录管理)
│   ├── auth.py             # 认证逻辑
│   ├── database.py         # 数据库配置 (含user_teams_table, team_admins_table关联表)
│   ├── config.py           # 系统配置
│   ├── utils.py            # 工具函数
│   ├── importer.py         # 教务系统导入
│   ├── services/           # 服务层
│   │   └── uploader_service.py  # 文件上传服务
│   └── routers/            # API 路由
│       ├── auth.py         # 认证路由（含登录记录）
│       ├── schedule.py     # 个人日程路由
│       ├── schedules.py    # 多课表+调休管理+ICS导入/导出路由
│       ├── team.py         # 完整团队管理路由
│       ├── admin.py        # 管理员路由（含用户封禁、登录记录查询）
│       ├── admin_settings.py # 系统设置路由
│       ├── import_route.py # 教务系统导入路由
│       ├── profile.py      # 个人资料路由（含登录历史）
│       └── changelog.py    # 更新日志代理路由
├── frontend/               # 前端代码
│   ├── src/
│   │   ├── components/     # Vue 组件
│   │   │   ├── ScheduleAdjuster.vue      # 调休管理组件（节假日+换课）
│   │   │   ├── ScheduleCalendar.vue      # 日历视图组件（支持调休、堆叠事件）
│   │   │   ├── ScheduleEditor.vue        # 课表编辑器
│   │   │   ├── ScheduleImporter.vue      # 教务系统导入
│   │   │   ├── ImportOptionsModal.vue    # 导入选项弹窗（ICS/教务系统）
│   │   │   ├── ExportOptionsModal.vue    # 导出选项弹窗（PNG/ICS）
│   │   │   ├── MySchedulePage.vue        # 个人课表页面（含调休功能）
│   │   │   ├── MyTeamsPage.vue           # 我的团队管理页面（创建/加入/列表）
│   │   │   ├── TeamViewPage.vue          # 团队课表聚合视图（筛选+冲突识别）
│   │   │   ├── AllTeamsViewPage.vue      # 全团队视图页面
│   │   │   ├── TeamEditorModal.vue       # 团队编辑模态框（成员管理+批量操作）
│   │   │   ├── CreatorTeamManagement.vue # 创建者高级团队管理面板
│   │   │   ├── TransferTeamModal.vue     # 团队所有权转让模态框
│   │   │   ├── DissolveTeamModal.vue     # 解散团队确认模态框
│   │   │   ├── LeaveTeamModal.vue        # 退出团队确认模态框
│   │   │   ├── TeamEventDetailModal.vue  # 团队课程详情及冲突显示
│   │   │   ├── StackedEventsModal.vue    # 堆叠事件详情显示
│   │   │   ├── FilterSidebar.vue         # 团队课表高级筛选侧边栏
│   │   │   ├── ChangelogModal.vue        # 更新日志显示模态框
│   │   │   ├── BatchActionBar.vue        # 批量操作工具栏
│   │   │   ├── ButtonLoadingSpinner.vue  # 按钮加载指示器
│   │   │   ├── PageLoadingSpinner.vue    # 页面加载指示器
│   │   │   ├── Navigation.vue            # 导航栏（含团队、更新日志入口）
│   │   │   ├── MobileDrawer.vue          # 移动端菜单
│   │   │   ├── EventModal.vue            # 事件编辑弹窗
│   │   │   └── admin/                    # 管理员组件
│   │   │       ├── AdminTeamManagement.vue   # 管理员团队管理组件
│   │   │       ├── UserManagementPage.vue    # 用户管理页面（含登录记录、批量操作）
│   │   │       ├── ConfirmDeleteModal.vue    # 批量删除确认模态框
│   │   │       ├── UserEditModal.vue         # 用户编辑模态框
│   │   │       ├── UserScheduleModal.vue     # 用户课表显示模态框
│   │   │       └── SystemSettings.vue        # 系统设置组件
│   │   ├── layouts/        # Astro 布局
│   │   │   ├── BaseLayout.astro          # 基础布局
│   │   │   └── DashboardLayout.astro     # 仪表板布局
│   │   ├── pages/          # 页面路由
│   │   │   ├── index.astro               # 首页
│   │   │   ├── login.astro               # 登录页
│   │   │   ├── register.astro            # 注册页
│   │   │   ├── 503.astro                 # 账户封禁错误页面
│   │   │   └── dashboard/                # 仪表板页面
│   │   │       ├── my-schedule.astro     # 个人课表（含调休管理）
│   │   │       ├── my-teams.astro        # 我的团队管理
│   │   │       ├── team-view/            # 团队视图页面
│   │   │       │   └── [teamId].astro    # 团队详情页
│   │   │       ├── team-view.astro       # 团队视图 (兼容)
│   │   │       ├── profile.astro         # 个人资料（含登录历史）
│   │   │       └── admin/                # 管理员页面
│   │   │           ├── user-management.astro  # 用户管理页面
│   │   │           ├── team-management.astro  # 团队管理页面
│   │   │           └── system-settings.astro  # 系统设置页面
│   │   ├── stores/         # Pinia 状态管理
│   │   │   ├── auth.ts                   # 认证状态
│   │   │   ├── schedule.ts               # 课表状态（含调休逻辑）
│   │   │   ├── team.ts                   # 团队状态管理
│   │   │   ├── ui.ts                     # UI状态管理（含更新日志通知）
│   │   │   └── theme.ts                  # 主题状态管理
│   │   ├── types/          # TypeScript 类型定义
│   │   │   └── index.ts                  # 包含Team、ScheduleAdjustment、LoginRecord等类型
│   │   └── utils/          # 工具函数
│   │       ├── api.ts                    # API 客户端 (已扩展)
│   │       ├── colors.ts                 # 颜色工具
│   │       ├── date.ts                   # 日期工具
│   │       ├── changelogService.ts       # 更新日志服务
│   │       └── schedule-segments.ts      # 课表时间段工具
│   ├── astro.config.mjs    # Astro 配置
│   ├── tailwind.config.mjs # Tailwind 配置
│   └── package.json        # 依赖管理
├── .gitignore              # Git 忽略文件
├── start_dev.sh            # 开发环境启动脚本
└── README.md               # 项目说明

🚀 快速开始

📋 环境要求

Python 3.10+
Node.js 18+
npm 或 yarn
Git (用于克隆项目)

⚡ 一键启动

我们提供了便捷的启动脚本：

# 克隆项目
git clone https://github.com/excniesNIED/SDNUChronoSync.git
cd SDNUChronoSync

# 使用启动脚本（推荐）
chmod +x start_dev.sh
./start_dev.sh

🔧 手动安装

1. 克隆项目

git clone https://github.com/excniesNIED/SDNUChronoSync.git
cd SDNUChronoSync

2. 后端设置

cd backend
pip install -r requirements.txt
python main.py

后端服务将在 http://localhost:8000 启动

3. 前端设置

cd frontend
npm install
npm run dev

前端应用将在 http://localhost:4321 启动

🐳 Docker 部署

# 使用 Docker Compose 一键部署
docker-compose up -d

📱 访问应用

前端应用: http://localhost:4321
后端API: http://localhost:8000
API文档: http://localhost:8000/docs

默认账户

系统会自动创建以下测试账户：

管理员账户：

用户名：admin
密码：admin123

学生账户：

用户名：202311001145
密码：password123
姓名：黄浩二
班级：计工本2303

🔌 API 接口

认证接口

POST /api/auth/token - 用户登录
POST /api/auth/register - 用户注册
GET /api/auth/users/me - 获取当前用户信息

课表管理接口

GET /api/schedules/ - 获取用户所有课表
POST /api/schedules/ - 创建新课表
GET /api/schedules/{id} - 获取指定课表详情
PUT /api/schedules/{id} - 更新课表信息
DELETE /api/schedules/{id} - 删除课表
GET /api/schedules/{id}/events - 获取课表事件（含调休逻辑）
POST /api/schedules/{id}/events - 在课表中创建事件
PUT /api/schedules/{id}/events/{event_id} - 更新课表事件
DELETE /api/schedules/{id}/events/{event_id} - 删除课表事件
POST /api/schedules/import-ics - 从ICS文件导入事件到指定课表
GET /api/schedules/{id}/export.ics - 导出课表为ICS文件

调休管理接口

GET /api/schedules/{id}/adjustments - 获取课表的所有调休历史记录
POST /api/schedules/{id}/adjustments - 创建调休调整（HOLIDAY/SWAP类型）
- HOLIDAY类型：{ "adjustment_type": "HOLIDAY", "holiday_date": "2024-10-01" }
- SWAP类型：{ "adjustment_type": "SWAP", "source_date": "2024-10-01", "target_date": "2024-10-02" }

团队管理接口

用户团队操作：

POST /api/teams - 创建新团队（自动生成8位邀请码，创建者自动加入）
POST /api/me/teams/join - 通过邀请码加入团队
GET /api/me/teams - 获取我参与的所有团队列表
POST /api/me/teams/{id}/leave - 退出团队（普通成员）

团队信息查询：

GET /api/teams/{id} - 获取团队详细信息（包含成员列表、创建者信息）
GET /api/teams/{id}/schedules - 获取团队聚合课表视图（所有成员的活跃课表）

团队管理操作（需要创建者或团队管理员权限）：

PUT /api/teams/{id} - 更新团队名称
POST /api/teams/{id}/members - 添加团队成员（通过学号精确查找）
DELETE /api/teams/{id}/members/{user_id} - 移除团队成员（不能移除创建者和系统管理员）

团队管理员管理（仅创建者和系统管理员）：

POST /api/teams/{id}/admins/{user_id} - 提升成员为团队管理员
- 要求：目标用户必须是团队成员
- 限制：不能提升创建者（已有隐式权限）和系统管理员
DELETE /api/teams/{id}/admins/{user_id} - 移除团队管理员权限
- 将团队管理员降级为普通成员
- 限制：不能降级创建者

团队所有权管理（仅创建者权限）：

POST /api/teams/{id}/transfer - 转让团队所有权给其他成员
DELETE /api/teams/{id} - 解散团队（删除团队及所有成员关系）

管理员专用接口：

GET /api/admin/teams - 获取系统中所有团队列表（包含统计信息）

路由说明

团队管理接口使用统一的路由前缀，遵循 RESTful 设计原则：

/api/teams/* - 团队的增删改查操作
/api/me/teams/* - 当前用户的团队操作
/api/admin/teams - 管理员团队监控

所有接口均需要 JWT 身份验证，通过 Authorization: Bearer <token> 请求头传递。

个人资料接口

GET /api/profile/ - 获取个人资料
PUT /api/profile/ - 更新个人资料
POST /api/profile/change-password - 修改密码
POST /api/profile/avatar - 更新头像URL
POST /api/profile/upload-avatar - 上传头像文件
GET /api/profile/statistics - 获取个人统计数据
GET /api/profile/recent-login - 获取最近一次登录记录
GET /api/profile/login-history - 获取登录历史记录（支持分页）

管理员接口

用户管理：

GET /api/admin/users - 获取所有用户（管理员）
POST /api/admin/users - 创建用户
PUT /api/admin/users/{id} - 更新用户
DELETE /api/admin/users/{id} - 删除用户
POST /api/admin/users/{id}/ban - 封禁用户账户
POST /api/admin/users/{id}/restore - 恢复用户账户

用户课表管理：

GET /api/admin/users/{id}/schedules-list - 获取用户的所有课表列表
GET /api/admin/users/{id}/schedules - 获取用户的所有日程事件
POST /api/admin/schedule/{user_id} - 为指定用户创建日程
PUT /api/admin/schedule/{event_id} - 更新任意日程事件
DELETE /api/admin/schedule/{event_id} - 删除任意日程事件

登录记录查询：

GET /api/admin/users/{id}/recent-login - 获取指定用户的最近登录记录
GET /api/admin/users/{id}/login-history - 获取指定用户的登录历史记录

系统设置：

GET /api/admin/settings - 获取系统设置
POST /api/admin/settings - 更新系统设置
POST /api/admin/settings/test-alist - 测试AList存储连接

更新日志接口

GET /api/changelog/content - 获取更新日志内容（后端代理，避免CORS问题）

📥 课表导入功能

系统支持两种课表导入方式：从教务系统导入和从ICS文件导入。

📚 教务系统课表导入

系统支持从山东师范大学正方教务系统导入课表。导入流程如下：

获取用户课表列表
- GET /api/import/schedules
- 描述: 获取当前用户的所有课表列表，用于选择导入目标。
- 响应: 返回课表列表数组。
获取会话与验证码
- GET /api/import/zfw/session
- 描述: 初始化导入流程，返回一个临时的 session_id 和 Base64 编码的验证码图片。
- 响应:
```
{
  "session_id": "string",
  "captcha_image": "string (base64)",
  "source": "string ('real' or 'fallback')"
}
```

提交登录信息并导入

POST /api/import/zfw
描述: 用户输入学号、密码和验证码后，提交至此接口。服务器将尝试登录教务系统，获取、解析课表，并存入指定的课表。

请求体:

{
  "session_id": "string",
  "username": "string (学号)",
  "password": "string",
  "captcha": "string (验证码)",
  "action": "string ('create_new' 或 'use_existing')",
  "schedule_id": "integer (action为use_existing时必填)",
  "schedule_name": "string (action为create_new时的课表名称)"
}

响应:

{
  "success": "boolean",
  "message": "string",
  "imported_count": "integer"
}

刷新验证码 (可选)
- GET /api/import/zfw/refresh/{session_id}
- 描述: 如果验证码无法识别，可使用此接口刷新验证码。
- 响应: 返回与获取会话接口相同的结构，但包含新的验证码图片。

📆 ICS文件导入

系统支持从标准ICS文件导入课表事件，兼容各大日历应用（苹果日历、Google Calendar、Outlook等）导出的文件。

API端点

端点: POST /api/schedules/import-ics
描述: 解析ICS文件并导入事件到指定课表
请求格式: multipart/form-data
参数:
- file: ICS文件（必需，只接受.ics格式）
- schedule_id: 目标课表ID（必需）

导入逻辑

时间计算: 根据课表的开始日期，自动计算每个事件的周数和星期几
日期验证: 自动跳过早于课表开始日期的事件
事件创建: 提取事件的标题、描述、地点、开始/结束时间等信息
错误处理: 记录导入失败的事件及原因

响应示例

{
  "success": true,
  "message": "成功导入 15 个事件，3 个事件导入失败",
  "count": 15,
  "errors": [
    "事件 '早期课程' 时间早于课表开始时间",
    "事件 '无效事件' 缺少时间信息"
  ]
}

使用说明

从其他日历应用（如苹果日历、Google Calendar）导出ICS文件
在"我的课表"页面点击"更多" → "导入课表" → "从ICS文件导入"
选择ICS文件上传
系统自动解析文件并导入事件到当前活跃课表
显示导入成功的数量和错误信息

🛠️ 开发指南

后端开发

数据模型修改：修改 models.py 后需要重启服务
API 路由：在 routers/ 目录下添加新的路由文件
数据库操作：在 crud.py 中添加新的数据库操作函数

前端开发

组件开发：在 src/components/ 下创建 Vue 组件
页面路由：在 src/pages/ 下创建 Astro 页面
状态管理：使用 Pinia stores 管理应用状态
样式开发：使用 Tailwind CSS 类名

🚀 部署说明

开发环境

后端：直接运行 python main.py
前端：运行 npm run dev

生产环境

后端：使用 Gunicorn 或 Uvicorn 部署
前端：运行 npm run build 生成静态文件，使用 Nginx 等服务器部署

贡献指南

Fork 项目
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
创建 Pull Request

📚 参考资料

本项目在开发过程中参考了以下开源项目和资源，特此致谢：

正方教务系统相关项目

openschoolcn/zfn_api - 正方教务系统API
whliao5am/zfnew - 正方教务系统新版本
whx1024/zfn_api12 - 正方教务系统API 1.2
zaigie/zfnew_webApi - 正方教务系统Web API
dairoot/school-api - 学校API项目
DuskU/zhengfang - 正方教务系统Gitee版本
FarmerChillax/new-school-sdk - 新学校SDK
Srpihot/zfapi - 正方教务系统API

课表管理相关项目

xxyangyoulin/ClassSchedule - 课程表项目
YZune/WakeupSchedule_Kotlin - WakeUp课程表Kotlin版本
qwqVictor/CQUPT-ics - 重庆邮电大学ICS课表
XiaoNaoWeiSuo/Grade2 - 成绩管理系统

技术文档

WakeUp课程表重构说明 - 课程表重构技术文档
CSDN博客 - 正方教务系统 - 正方教务系统相关技术文章

UI组件库

satyamchaudharydev/horrible-snake-35 - 加载动画组件（HTML/CSS）
Siyu1017/old-goat-8 - Windows 11 风格加载动画组件

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🤝 贡献指南

我们欢迎所有形式的贡献！请遵循以下步骤：

Fork 项目 - 点击右上角的 Fork 按钮
创建特性分支 - git checkout -b feature/amazing-feature
提交更改 - git commit -m 'Add amazing feature'
推送分支 - git push origin feature/amazing-feature
创建 Pull Request - 在 GitHub 上创建 PR

📞 联系我们

🌐 项目主页：https://github.com/HevSpecu/SDNUChronoSync
📖 使用教程：https://hs.cnies.org/archives/chronosync-user-guide
ℹ️ 关于本项目：https://hs.cnies.org/archives/chronosync
💬 问题反馈：通过项目 Issues 提出
📧 邮箱联系：hxcn@cnies.org

📝 更新日志

v2.5.4 (2025-11-02) - 团队筛选权限修复与只读成员课表

问题修复

修复：普通成员/团队管理员在团队视图筛选他人课表时出现 403 或筛选结果为空的问题。现在会在筛选请求中自动携带当前团队 team_ids 并在请求前同步视图对应的日期范围；当存在筛选条件时，日历优先使用过滤结果进行渲染。（前端 TeamViewPage.vue、stores/schedule.ts）

新增功能

新增：只读的“成员课表查看”面板，供团队创建者/团队管理员使用。支持周/月视图、日期导航，以及从过滤接口汇总生成的“课表选择”下拉；非系统管理员不再调用管理员专用接口。（前端 UserScheduleViewer.vue、TeamEditorModal.vue）

其他修复

修复：UserScheduleViewer.vue 模板缺失闭合标签导致的编译错误。

v2.5.3 (2025-11-01) - 团队管理权限与复选框点击修复

问题修复

修复：以团队创建者身份从 CreatorTeamManagement 打开 TeamEditorModal 无法进行任何操作的问题。通过在模态框挂载时初始化认证状态，确保权限判断生效，与 AdminTeamManagement 行为一致。（前端 TeamEditorModal.vue）
修复：成员列表与“全选”复选框需要点击视觉中心下方才会触发的问题。调整元素层级与指针事件，确保复选框视觉中心处点击即可正确响应。（前端 TeamEditorModal.vue）

影响范围

仅前端交互与权限判定逻辑，无后端改动。
既有管理员入口行为不受影响。

v2.5.2 (2025-10-31) - 中国大陆网络优化与加载加速

网络与性能优化

移除 Google Fonts 与 Material Icons 外链，改用本地/系统字体栈，避免在中国大陆网络环境下因 fonts.googleapis.com 阻断引发的 net::ERR_SOCKET_NOT_CONNECTED。
更新 Tailwind sans 字体栈为中文友好系统字体（PingFang SC、Microsoft YaHei、Noto Sans SC、Source Han Sans SC 等），提升可读性与加载速度。
减少第三方阻塞请求，加快登录页与仪表板首屏渲染，改善部分安卓设备加载过慢问题。
在弱网/受限网络环境下提升稳定性，避免外部资源加载失败导致的渲染卡顿。

v2.5.1 (2025-10-30) - 模态框交互体验优化

可访问性增强

♿ 模态框焦点管理：改进用户交互流程
- EventModal 添加初始焦点管理，自动聚焦到取消按钮
- UserScheduleModal 增强焦点控制，提升键盘导航体验
- TeamEditorModal 优化嵌套模态框交互逻辑
🎯 嵌套模态框处理：防止意外关闭
- TeamEditorModal 在日程模态框打开时阻止关闭
- 保护用户操作流程，避免数据丢失
- 优化模态框层级管理
⌨️ 键盘交互优化：提升无障碍访问
- 响应式焦点引用管理
- 改进 ESC 键和点击外部区域的行为
- 确保焦点始终在可操作元素上

技术改进

✅ 引入 initialFocusRef 响应式引用
✅ 重构模态框关闭逻辑，支持条件关闭
✅ 统一焦点管理策略，提升用户体验
✅ 完善模态框组件的可访问性标准

v2.5.0 (2025-10-30) - 登录记录管理与用户体验全面优化

安全增强功能

🔐 登录记录管理系统：完整的用户登录追踪功能
- 新增 LoginRecord 模型，记录用户登录时间、IP地址、用户代理信息
- 支持查看最近登录记录和完整登录历史
- 管理员可查看所有用户的登录记录，增强安全监控
🛡️ 用户封禁与恢复：完善的管理员工具
- 新增用户封禁功能，支持管理员封禁违规用户
- 用户封禁后无法登录系统，返回503错误页面
- 支持解封恢复功能，灵活管理用户状态
📊 登录历史集成：用户管理增强
- 用户管理页面新增登录记录查看功能
- 个人资料页面集成登录历史展示
- 提升用户对账户活动的透明度

用户体验优化

🎨 更新日志功能：新增版本更新追踪
- 新增 ChangelogModal 组件展示更新内容
- 后端代理接口避免CORS问题
- UI状态管理新版本通知
- 导航栏集成更新日志入口
🎯 模态框系统重构：统一交互体验
- 使用 Headless UI 的 Dialog 和 Transition 组件
- 增强可访问性和动画效果
- 统一团队管理模态框样式和行为
- 实现 Teleport 渲染，提升视觉层次
📋 批量操作增强：管理员效率提升
- 新增 BatchActionBar 组件支持批量操作
- 用户管理页面集成批量删除、封禁、恢复功能
- 团队管理支持批量成员操作
- 增强确认删除模态框支持批量操作

界面与交互优化

🎨 下拉菜单统一设计：视觉一致性提升
- 新增统一下拉样式配置
- 支持搜索过滤功能的下拉菜单
- 优化选择器交互体验
📝 输入框样式标准化：表单视觉升级
- 统一输入框基础样式
- 增强搜索输入框视觉效果
- 提升整体表单美观度
⏳ 加载状态优化：更流畅的等待体验
- 增大加载指示器尺寸，提升可见性
- 优化字母间距，改善可读性
- 统一加载动画样式

日历与事件管理

📅 堆叠事件处理：复杂课表场景支持
- 新增 StackedEventsModal 处理同时间段多课程
- 支持团队和个人视图的事件堆叠显示
- 优化事件点击和模态状态管理
🔄 课程时间更新：课时调整标准化
- 更新第10-11节课时间设置
- 前后端时间计算逻辑同步
- 优化事件重叠检测算法

团队管理优化

👥 管理权限细分：更精细的权限控制
- 区分创建团队和管理团队权限
- 支持查看可管理的团队列表
- 优化团队操作权限判断逻辑
🏗️ 团队生命周期管理：完整流程支持
- 创建、管理、转让、解散全流程
- 二次确认机制防止误操作
- 团队转让和解散的完整记录

系统优化

🚀 加载指示器统一：性能与视觉提升
- 新增 ButtonLoadingSpinner 和 PageLoadingSpinner 组件
- 替换所有旧式加载指示器
- 统一加载状态视觉风格
🗂️ 功能结构调整：简化管理界面
- 移除日程管理功能模块
- 用户管理页面整合用户日程显示
- 简化管理员导航结构
📖 文档清理：项目结构优化
- 移除 FEATURE_GUIDE.md 文档
- 调整文档策略和内容管理方式

v2.4.0 (2025-10-22) - 团队管理员功能与权限增强

新增功能

✨ 团队管理员角色系统：支持团队内部的分层管理
- 新增团队管理员（Team Admin）角色，区别于系统管理员和团队创建者
- 团队创建者可以将普通成员提升为团队管理员
- 团队管理员拥有成员管理、课表管理等权限
- 支持团队管理员降级为普通成员
✨ 团队管理员API接口：
- POST /api/teams/{team_id}/admins/{user_id} - 提升成员为团队管理员
- DELETE /api/teams/{team_id}/admins/{user_id} - 移除团队管理员权限
✨ 增强的权限控制：
- 团队管理员可以管理团队成员（添加、移除）
- 团队管理员可以编辑团队信息
- 保护机制：不能移除团队创建者和系统管理员
- 权限层级：系统管理员 > 团队创建者 > 团队管理员 > 普通成员

后端改进

✅ 新增 team_admins_table 关联表，支持多对多的团队管理员关系
✅ 新增 CRUD 函数：
- is_team_admin() - 检查用户是否为团队管理员
- add_team_admin() - 添加团队管理员
- remove_team_admin() - 移除团队管理员
✅ 优化权限检查函数 check_team_admin_permission()
- 支持系统管理员、团队创建者、团队管理员三种角色
✅ 增强成员移除逻辑：
- 移除成员时自动清除其团队管理员权限
- 禁止移除团队创建者
- 禁止移除系统管理员
✅ 所有团队查询接口增加 admins 字段加载

前端优化

✅ 新增 canAdminManage() 函数判断管理权限
- 团队管理员可以看到"管理团队"按钮
- 普通成员显示"退出团队"按钮
✅ 团队响应数据包含管理员列表信息
✅ 优化团队管理界面的权限显示

数据模型变更

✅ Team 模型新增 admins 关系字段
✅ TeamResponse schema 新增 admins 字段
✅ 自动数据库迁移支持

v2.3.0 (2025-10-14) - UI优化与品牌升级

新增功能

✨ 课表操作菜单重构：全新的"更多"按钮设计
- 整合5大核心功能：添加日程、导入课表、导出课表、放假调休、课表设置
- 统一的模态框交互，提升用户体验
- 响应式设计，完美适配移动端和桌面端
✨ ICS文件导入增强：优化导入流程
- 新增导入选项弹窗，支持ICS文件和教务系统两种导入方式
- 图标化界面，操作更直观
- 详细的导入结果反馈
✨ 导出选项弹窗：简化导出操作
- 统一的导出入口
- 支持PNG图片和ICS文件两种格式
- 一键选择，快速操作
🎨 品牌视觉升级：增强品牌形象
- 添加多种尺寸的favicon图标（PNG、JPG、SVG）
- 优化网站图标显示效果
- 提升浏览器标签页识别度

UI/UX优化

✅ 使用Heroicons图标库，统一视觉风格
✅ 优化按钮布局，减少界面复杂度
✅ 改进响应式断点设置
- 移动端（< 640px）：图标优先显示
- 桌面端（>= 640px）：图标+文字组合显示
✅ 优化操作流程，减少页面跳转

技术改进

✅ 新增ImportOptionsModal.vue组件
✅ 新增ExportOptionsModal.vue组件
✅ 重构MySchedulePage.vue操作按钮区域
✅ 优化文件上传和下载逻辑

v2.2.1 (2025-10-07) - 代码清理与优化

优化改进

🧹 代码清理：移除所有测试和废弃代码
- 删除示例用户创建代码
- 移除数据库迁移脚本
- 清理控制台调试日志
- 删除临时捕获文件和备份文件
✅ 功能验证：完成前后端功能测试
- 后端API接口测试通过
- 前端页面加载正常
- 用户认证功能正常
📖 文档更新：更新README.md
- 移除测试账户相关说明
- 更新项目结构描述
- 修正API接口文档说明

v2.2.0 (2025-10-07) - ICS导入功能与UI优化

新增功能

✅ ICS文件导入：支持从标准ICS文件导入课表事件
- 兼容苹果日历、Google Calendar、Outlook等主流日历应用
- 自动计算事件的周数和星期几
- 智能跳过早于课表开始日期的事件
- 详细的导入结果反馈（成功数量、失败原因）
✅ 统一操作菜单：重构课表页面UI
- 新增"更多"按钮，整合5大核心功能
- 添加日程、导入课表、导出课表、放假调休、课表设置
- 模态框式交互，操作流程更清晰
✅ 导入选项弹窗：新增 ImportOptionsModal.vue 组件
- 支持从ICS文件导入
- 支持从教务系统导入
- 图标化界面，操作直观
✅ 导出选项弹窗：新增 ExportOptionsModal.vue 组件
- 导出为PNG图片
- 导出为ICS文件
- 一键选择，快速操作

后端改进

✅ 新增API端点：POST /api/schedules/import-ics
✅ ICS文件解析与验证逻辑
✅ 周数和星期自动计算算法
✅ 完善的错误处理和日志记录

UI/UX优化

✅ 响应式"更多"按钮设计（移动端/桌面端自适应）
✅ 使用 Heroicons 图标库统一视觉风格
✅ 优化操作流程，减少页面跳转
✅ 提升移动端使用体验

v2.1.1 (2025-09-30) - 品牌升级

品牌更新

✅ 正式命名：系统正式命名为"时序同笺 (SDNUChronoSync)"
✅ 界面更新：导航栏、登录页、注册页全面使用新名称
✅ 文档完善：README 更新品牌信息
✅ 导航增强：新增"使用教程"和"关于"外部链接
- 使用教程：https://hs.cnies.org/archives/chronosync-user-guide
- 关于本项目：https://hs.cnies.org/archives/chronosync
✅ 用户体验：所有页面统一品牌形象

v2.1.0 (2025-09-30) - 团队管理系统完整升级

核心功能增强

✅ 团队所有权转让：创建者可以安全转让团队管理权限给其他成员
✅ 团队解散功能：带二次确认的团队解散流程，永久删除团队及成员关系
✅ 成员退出机制：普通成员支持自主退出团队
✅ 高级筛选系统：团队课表支持按成员、班级、年级多维度筛选
✅ 课程冲突识别：智能识别和显示同一时间段的课程冲突
✅ 创建者管理面板：专属的高级团队管理界面，统一管理所有创建的团队

新增组件

✅ CreatorTeamManagement.vue - 创建者高级管理面板
✅ TransferTeamModal.vue - 团队转让确认流程
✅ DissolveTeamModal.vue - 解散团队二次确认
✅ LeaveTeamModal.vue - 退出团队确认
✅ TeamEventDetailModal.vue - 课程冲突详情显示
✅ FilterSidebar.vue - 多条件组合筛选侧边栏

后端架构改进

✅ 团队转让接口：POST /api/teams/{id}/transfer
✅ 权限检查函数：check_team_admin_permission() / check_team_member_permission()
✅ 活跃课表筛选：只聚合 status="进行" 的课表
✅ 管理员全局监控：GET /api/admin/teams 获取所有团队统计

UI/UX 优化

✅ 移动端侧边筛选抽屉，完美适配小屏幕
✅ 实时状态反馈，所有操作提供即时成功/错误提示
✅ 团队卡片重新设计，清晰展示创建者/成员角色
✅ 统计卡片展示：我的团队数、创建的团队数、总成员数

v2.0.0 (2025-09-28) - 高级调休与团队协作系统基础

重大功能更新

✅ 多课表管理系统：支持创建和管理多个课表
✅ 高级调休功能：节假日设置与智能换课系统
✅ 基础团队协作：基于邀请码的团队创建和加入
✅ 权限分层管理：系统管理员、团队创建者、普通成员三级权限
✅ 团队课表聚合：查看团队所有成员的课程安排
✅ 调休记录管理：支持撤销和修改调休设置
✅ 实时数据同步：调休和团队变更立即生效
✅ 导航系统升级：新增"我的团队"功能入口
✅ API架构扩展：新增团队和调休相关接口
✅ 数据库模型扩展：新增 Team、user_teams_table、ScheduleAdjustment 模型

技术改进

✅ 服务器端调休逻辑处理，确保数据一致性
✅ 完善的错误处理和用户反馈机制
✅ 响应式UI适配新功能
✅ TypeScript类型系统完善
✅ 向后兼容性保证

v1.2.0 (2025-09-27)

✅ 个人资料管理系统
✅ 头像上传功能（本地存储/AList支持）
✅ 密码修改功能
✅ 系统设置管理
✅ 教务系统课表导入

v1.1.0 (2025-09-26)

✅ 多课表支持
✅ 课表导入功能
✅ ICS格式导出
✅ 课表状态管理
✅ 课程详细信息

v1.0.0 (2025-09-25)

✅ 基础功能完成
✅ 用户认证系统
✅ 个人日程管理
✅ 团队视图功能
✅ 管理员功能
✅ 响应式 UI 设计
✅ 多平台支持

分享

时序同笺 (SDNUChronoSync)

🌐 在线访问

📋 项目简介

✨ 功能特性

个人日程管理

智能调休系统

团队协作系统

管理员功能

UI/UX 特性

高性能架构

📖 使用指南

🎯 个人课表管理

🎯 高级调休功能

🎯 团队协作系统

1. 创建团队

2. 加入团队

3. 团队管理（创建者和团队管理员）

4. 退出团队（普通成员）

5. 团队课表聚合视图

6. 管理员团队监控

🎯 管理员功能

🛠️ 技术栈

前端

后端

📁 项目结构

🚀 快速开始

📋 环境要求

⚡ 一键启动

🔧 手动安装

1. 克隆项目

2. 后端设置

3. 前端设置

🐳 Docker 部署

📱 访问应用

默认账户

🔌 API 接口

认证接口

课表管理接口

调休管理接口

团队管理接口

路由说明

个人资料接口

管理员接口

更新日志接口

📥 课表导入功能

📚 教务系统课表导入

📆 ICS文件导入

API端点

导入逻辑

响应示例

使用说明

🛠️ 开发指南

后端开发

前端开发

🚀 部署说明

开发环境

生产环境

贡献指南

📚 参考资料

正方教务系统相关项目

课表管理相关项目

技术文档

UI组件库

📄 许可证

🤝 贡献指南

📞 联系我们

📝 更新日志

v2.5.4 (2025-11-02) - 团队筛选权限修复与只读成员课表

v2.5.3 (2025-11-01) - 团队管理权限与复选框点击修复

v2.5.2 (2025-10-31) - 中国大陆网络优化与加载加速

v2.5.1 (2025-10-30) - 模态框交互体验优化

v2.5.0 (2025-10-30) - 登录记录管理与用户体验全面优化

v2.4.0 (2025-10-22) - 团队管理员功能与权限增强

v2.3.0 (2025-10-14) - UI优化与品牌升级

v2.2.1 (2025-10-07) - 代码清理与优化

v2.2.0 (2025-10-07) - ICS导入功能与UI优化

v2.1.1 (2025-09-30) - 品牌升级

v2.1.0 (2025-09-30) - 团队管理系统完整升级

v2.0.0 (2025-09-28) - 高级调休与团队协作系统基础