Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 LoveChengke
|
f8c8980a82 | ||
|
LoveChengke
|
828fde80f9 |
No files matched your search
@@ -1,93 +0,0 @@
|
|||||||
name: 发布官网与文档站
|
|
||||||
|
|
||||||
# 把一个 GitHub Pages 站点发出去：
|
|
||||||
#
|
|
||||||
# / 产品官网（website/，纯静态、无构建步骤）
|
|
||||||
# /docs/ 文档站（docfx 构建 docs/ 得到）
|
|
||||||
#
|
|
||||||
# 为什么要拼成一个站点：**一个仓库在 GitHub Pages 上只有一个站点**。两者发布节奏也不一样
|
|
||||||
# （改个错别字就该上线，不该为此打个安装包），所以走 workflow 而不是塞进发布流程。
|
|
||||||
#
|
|
||||||
# 站点地址：https://lovechengke.github.io/ClassHelper/
|
|
||||||
# 需要在仓库 Settings → Pages 里把 Source 选成「GitHub Actions」（只需做一次）。
|
|
||||||
#
|
|
||||||
# 本地预览：pnpm dev:site（官网在 :5180，文档站挂在同一个端口的 /docs/ 下）
|
|
||||||
|
|
||||||
on:
|
|
||||||
push:
|
|
||||||
branches: [master]
|
|
||||||
paths:
|
|
||||||
- 'website/**'
|
|
||||||
- 'docs/**'
|
|
||||||
- 'scripts/build-pages.mjs'
|
|
||||||
- '.github/workflows/pages.yml'
|
|
||||||
# 两个页面上的版本号都取自根 package.json
|
|
||||||
# （官网是手写的徽章，文档站由 docs/build.mjs 用 --metadata 注入），
|
|
||||||
# 所以版本号变了也要重新发一次
|
|
||||||
- 'package.json'
|
|
||||||
workflow_dispatch:
|
|
||||||
|
|
||||||
# Pages 部署需要的三件套：读代码、写 Pages、用 OIDC 拿部署令牌
|
|
||||||
permissions:
|
|
||||||
contents: read
|
|
||||||
pages: write
|
|
||||||
id-token: write
|
|
||||||
|
|
||||||
# 同一时间只跑一个部署；已经在跑的那次不取消（半途取消会留下一个坏掉的站点）
|
|
||||||
concurrency:
|
|
||||||
group: pages
|
|
||||||
cancel-in-progress: false
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
build:
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
timeout-minutes: 20
|
|
||||||
steps:
|
|
||||||
- name: 检出代码
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
|
|
||||||
- name: 安装 .NET SDK 8
|
|
||||||
uses: actions/setup-dotnet@v4
|
|
||||||
with:
|
|
||||||
dotnet-version: '8.0.x'
|
|
||||||
|
|
||||||
- name: 安装 docfx
|
|
||||||
# docfx 是 .NET 全局工具，装完在 ~/.dotnet/tools 下；setup-dotnet 会把它加进 PATH，
|
|
||||||
# 这里再显式补一次，免得换 runner 镜像后找不到命令。
|
|
||||||
run: |
|
|
||||||
dotnet tool install --global docfx
|
|
||||||
echo "$HOME/.dotnet/tools" >> "$GITHUB_PATH"
|
|
||||||
|
|
||||||
- name: 构建文档站
|
|
||||||
# --check 把 docfx 的警告当错误：最常见的警告是"某个 .md 没被任何 toc.yml 引用"，
|
|
||||||
# 那种页面会被构建出来但没有侧边栏 —— 属于必须修掉的疏漏，不该悄悄上线。
|
|
||||||
#
|
|
||||||
# DOCS_BASE 是给文档站那份 404 用的：项目页挂在 /<仓库名>/ 子路径下，而浏览器按
|
|
||||||
# **被请求的路径**解析 404 页里的相对链接，所以要把站点根钉成 <base>。
|
|
||||||
env:
|
|
||||||
DOCS_BASE: /${{ github.event.repository.name }}/docs/
|
|
||||||
run: node docs/build.mjs --check
|
|
||||||
|
|
||||||
- name: 组装站点（官网在根，文档站在 /docs/）
|
|
||||||
env:
|
|
||||||
SITE_BASE: /${{ github.event.repository.name }}/
|
|
||||||
run: node scripts/build-pages.mjs
|
|
||||||
|
|
||||||
- name: 配置 Pages
|
|
||||||
uses: actions/configure-pages@v5
|
|
||||||
|
|
||||||
- name: 上传构建产物
|
|
||||||
uses: actions/upload-pages-artifact@v3
|
|
||||||
with:
|
|
||||||
path: .cache/pages
|
|
||||||
|
|
||||||
deploy:
|
|
||||||
needs: build
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
environment:
|
|
||||||
name: github-pages
|
|
||||||
url: ${{ steps.deployment.outputs.page_url }}
|
|
||||||
steps:
|
|
||||||
- name: 部署到 GitHub Pages
|
|
||||||
id: deployment
|
|
||||||
uses: actions/deploy-pages@v4
|
|
||||||
@@ -1,132 +0,0 @@
|
|||||||
name: 发布 Linux 服务端安装包
|
|
||||||
|
|
||||||
# 为什么单独有这个 workflow：
|
|
||||||
# Linux 包的依赖（@libsql/linux-x64-gnu、@prisma/adapter-libsql 等）是平台相关的，
|
|
||||||
# 在 Windows 开发机上 npm install 出来的 node_modules 装到 Linux 跑不起来，
|
|
||||||
# 所以 Linux 包必须在 Linux 上构建。这个 workflow 用 ubuntu runner 产出
|
|
||||||
# classhelper-server-linux-x64-<版本>.tar.gz 并挂到 GitHub Release 上，
|
|
||||||
# 服务器上的 `classhelper upgrade` 就是从这里下载 + 校验 sha256 的。
|
|
||||||
#
|
|
||||||
# 用法：
|
|
||||||
# 1. 先在本地按惯例打出 Windows 包并发 Release（vX.Y.Z）；
|
|
||||||
# 2. 到 Actions 页面手动运行本 workflow，填 tag（例如 v1.1.2）；
|
|
||||||
# 3. 跑完 Release 里会多出 Linux 包与更新后的 SHA256SUMS-<版本>.txt。
|
|
||||||
#
|
|
||||||
# 也可以只跑构建不挂 Release（attach=false），产物在 workflow 的 Artifacts 里。
|
|
||||||
|
|
||||||
on:
|
|
||||||
workflow_dispatch:
|
|
||||||
inputs:
|
|
||||||
tag:
|
|
||||||
description: '要构建并挂载的 Release tag（例如 v1.1.2）'
|
|
||||||
required: true
|
|
||||||
type: string
|
|
||||||
attach:
|
|
||||||
description: '构建后上传到该 Release'
|
|
||||||
required: false
|
|
||||||
default: true
|
|
||||||
type: boolean
|
|
||||||
push:
|
|
||||||
tags:
|
|
||||||
- 'v*'
|
|
||||||
|
|
||||||
permissions:
|
|
||||||
contents: write
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
build-linux-package:
|
|
||||||
runs-on: ubuntu-22.04
|
|
||||||
timeout-minutes: 40
|
|
||||||
|
|
||||||
steps:
|
|
||||||
- name: 确定 tag
|
|
||||||
id: ref
|
|
||||||
run: |
|
|
||||||
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
|
|
||||||
echo "tag=${{ inputs.tag }}" >> "$GITHUB_OUTPUT"
|
|
||||||
echo "attach=${{ inputs.attach }}" >> "$GITHUB_OUTPUT"
|
|
||||||
else
|
|
||||||
echo "tag=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
|
|
||||||
echo "attach=true" >> "$GITHUB_OUTPUT"
|
|
||||||
fi
|
|
||||||
|
|
||||||
- name: 检出代码
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
with:
|
|
||||||
ref: ${{ steps.ref.outputs.tag }}
|
|
||||||
|
|
||||||
- name: 安装 Node 22
|
|
||||||
uses: actions/setup-node@v4
|
|
||||||
with:
|
|
||||||
node-version: '22'
|
|
||||||
|
|
||||||
- name: 安装 pnpm
|
|
||||||
uses: pnpm/action-setup@v4
|
|
||||||
with:
|
|
||||||
version: 11.8.0
|
|
||||||
run_install: false
|
|
||||||
|
|
||||||
- name: 安装依赖
|
|
||||||
run: pnpm install --frozen-lockfile
|
|
||||||
|
|
||||||
- name: 生成 Prisma Client
|
|
||||||
# 必须显式生成：packages/server/src/generated/prisma 是 gitignored 的，CI 上全新检出没有它。
|
|
||||||
# 少了这一步，`tsc` 会因为 Prisma 类型解析不到而把回调参数全推成 any，报出一大片
|
|
||||||
# "TS7006 Parameter 'item' implicitly has an 'any' type" / "TS2339 Property 'id' does not exist
|
|
||||||
# on type '{}'" —— 看着像代码写错了，实际是缺生成物（本机因为早就生成过，永远踩不到）。
|
|
||||||
# deploy/Dockerfile 的构建阶段有同样的步骤与注释。
|
|
||||||
run: pnpm --filter @classhelper/server db:generate
|
|
||||||
|
|
||||||
- name: 构建 Linux 安装包
|
|
||||||
run: pnpm dist:server:linux
|
|
||||||
|
|
||||||
- name: 展示产物
|
|
||||||
run: ls -la releases/server/*/linux-x64/
|
|
||||||
|
|
||||||
- name: 上传构建产物（Artifacts）
|
|
||||||
uses: actions/upload-artifact@v4
|
|
||||||
with:
|
|
||||||
name: classhelper-server-linux-x64
|
|
||||||
path: |
|
|
||||||
releases/server/*/linux-x64/classhelper-server-linux-x64-*.tar.gz
|
|
||||||
releases/server/*/linux-x64/classhelper-server-linux-x64-*.tar.gz.sha256
|
|
||||||
if-no-files-found: error
|
|
||||||
retention-days: 30
|
|
||||||
|
|
||||||
- name: 挂到 Release 并更新 SHA256SUMS
|
|
||||||
if: steps.ref.outputs.attach == 'true'
|
|
||||||
env:
|
|
||||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
||||||
TAG: ${{ steps.ref.outputs.tag }}
|
|
||||||
run: |
|
|
||||||
set -euo pipefail
|
|
||||||
VERSION="${TAG#v}"
|
|
||||||
ARTIFACT_DIR="releases/server/${VERSION}/linux-x64"
|
|
||||||
TARBALL="${ARTIFACT_DIR}/classhelper-server-linux-x64-${VERSION}.tar.gz"
|
|
||||||
SHAFILE="${TARBALL}.sha256"
|
|
||||||
SUMS="releases/SHA256SUMS-${VERSION}.txt"
|
|
||||||
|
|
||||||
if [ ! -f "$TARBALL" ]; then
|
|
||||||
echo "::error::没有找到 $TARBALL（tag 与 package.json 的版本号对得上吗？）"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
# .sha256 必须跟着一起传：它是独立发布的资产，只更新 tar.gz 会让这个文件指向旧哈希，
|
|
||||||
# 拿它校验的人会得到 mismatch（classhelper upgrade 用的是 --sha256/这个文件，不是 SHA256SUMS）。
|
|
||||||
if [ ! -f "$SHAFILE" ]; then
|
|
||||||
sha256sum "$TARBALL" | sed "s#${ARTIFACT_DIR}/##" > "$SHAFILE"
|
|
||||||
fi
|
|
||||||
|
|
||||||
# 取回已有的校验清单（Windows 包那几行），只替换/追加本包这一行，其余内容原样保留。
|
|
||||||
# 注意**不要**用 `sort -u` 去重：那份文件是人读的（表头 + 体积 + 说明），排序会把它们打散。
|
|
||||||
gh release download "$TAG" --pattern "SHA256SUMS-*.txt" --dir releases --clobber || true
|
|
||||||
DOWNLOADED="$(ls releases/SHA256SUMS-*.txt 2>/dev/null | head -n 1 || true)"
|
|
||||||
if [ -n "$DOWNLOADED" ] && [ "$DOWNLOADED" != "$SUMS" ]; then mv "$DOWNLOADED" "$SUMS"; fi
|
|
||||||
touch "$SUMS"
|
|
||||||
grep -v "^[0-9a-f]\{64\} classhelper-server-linux-" "$SUMS" > "${SUMS}.new" || true
|
|
||||||
printf '%s %s\n' "$(sha256sum "$TARBALL" | awk '{print $1}')" "$(basename "$TARBALL")" >> "${SUMS}.new"
|
|
||||||
mv "${SUMS}.new" "$SUMS"
|
|
||||||
|
|
||||||
gh release upload "$TAG" "$TARBALL" "$SHAFILE" "$SUMS" --clobber
|
|
||||||
echo "已上传："
|
|
||||||
cat "$SHAFILE"
|
|
||||||
cat "$SUMS"
|
|
||||||
-13
@@ -38,16 +38,3 @@ eslint-report.json
|
|||||||
.idea/
|
.idea/
|
||||||
.DS_Store
|
.DS_Store
|
||||||
Thumbs.db
|
Thumbs.db
|
||||||
|
|
||||||
# 参考用的第三方源码包（设计 token 已提取到 docs/winisland-design-tokens.md）
|
|
||||||
WinIsland-master.zip
|
|
||||||
releases/
|
|
||||||
|
|
||||||
# AI 浼氳瘽浜х墿锛圸Code 璁″垝/閰嶇疆锛屼笉灞炰簬浜у搧浠ｇ爜锛�
|
|
||||||
.zcode/
|
|
||||||
.zcodeignore
|
|
||||||
packages/server/prisma/backups/
|
|
||||||
packages/server/prisma/database-settings.json
|
|
||||||
|
|
||||||
# 鏂囨。绔欐瀯寤轰骇鐗╋紙pnpm docs:build 鐢熸垚锛岀敱 GitHub Pages 鍙戝竷锛涜� docs/锛�
|
|
||||||
docs/_site/
|
|
||||||
@@ -7,4 +7,3 @@ pnpm-lock.yaml
|
|||||||
.cache
|
.cache
|
||||||
.pnpm-store
|
.pnpm-store
|
||||||
.probe
|
.probe
|
||||||
docs/_site
|
|
||||||
@@ -1,233 +1,730 @@
|
|||||||
<!--markdownlint-disable MD033 MD041-->
|
# 班级小助手（Class Helper）
|
||||||
|
|
||||||
<div align="center">
|
班级信息管理系统，采用 pnpm monorepo，包含**后端服务**、**Web 管理端**（教师/管理员）与
|
||||||
|
**桌面客户端**（学生）三端。核心链路：
|
||||||
|
|
||||||
# <img src="build/classhelper.png" width="30" height="30" alt="" /> ClassHelper
|
```
|
||||||
|
教师在 Web 端发布内容
|
||||||
|
│ REST API（JWT 鉴权）
|
||||||
|
▼
|
||||||
|
后端服务（Express + Prisma）
|
||||||
|
│ 写入数据库 + 按班级房间广播
|
||||||
|
▼
|
||||||
|
Socket.IO ──► class:{classId} 房间 ──► 学生桌面客户端实时更新 UI
|
||||||
|
```
|
||||||
|
|
||||||
<img src="docs/images/web-dashboard.jpg" alt="ClassHelper · Web 管理端仪表盘" />
|
## 当前交付范围
|
||||||
|
|
||||||
[](https://github.com/LoveChengke/ClassHelper/releases/latest)
|
| 阶段 | 内容 | 状态 |
|
||||||
[](https://github.com/LoveChengke/ClassHelper/releases)
|
| ---- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
|
||||||
[](https://github.com/LoveChengke/ClassHelper/issues)
|
| 1 | pnpm monorepo 脚手架、TypeScript / ESLint / Prettier / 环境变量 | ✅ 已完成 |
|
||||||
<br/>
|
| 2 | 后端：Prisma schema + 迁移 + 种子数据 + JWT 认证 + RBAC + 模块化 REST API + Socket.IO | ✅ 已完成 |
|
||||||
|
| 3 | Web 管理端：登录、主布局、仪表盘、班级/学生/课表/作业/通知/成绩页面、Axios 封装、实时提示 | ✅ 已完成 |
|
||||||
|
| 4 | EXE 客户端：Electron 主进程/preload/渲染进程、登录、课表/作业/通知/成绩/设置、实时推送、IndexedDB 离线缓存 | ✅ 已完成（冒烟验证 27/27） |
|
||||||
|
| 5 | 三端联调脚本、打包命令、完整 README | ✅ 已完成（三套安装包 + 两套 UI 回归测试） |
|
||||||
|
| 6 | 测试账号与种子数据说明 | ✅ 已完成（见下文） |
|
||||||
[](https://github.com/LoveChengke/ClassHelper)
|
| 7 | 生产化：服务端安装程序（内置 Node）、Web 端 PWA 可安装、Docker + Nginx 部署、生产加固与运维文档 | ✅ 已完成（见 [`docs/production.md`](docs/production.md)） |
|
||||||
|
| 8 | 客户端灵动岛（通知浮窗，上课隐藏 / 下课弹出 / 紧急立即展开）与上课时段紧急通知二次确认 | ✅ 已完成（见"上课时段策略"） |
|
||||||
|
|
||||||
ClassHelper是给中小学班级用的一套信息管理系统。<br/>
|
> **与原始提示词的两处偏差（已与你确认）**
|
||||||
**老师发一条通知，教室客户端与灵动岛会实时提醒**；<br/>
|
>
|
||||||
学生打开客户端就能看到当天的课表和作业。
|
> 1. 桌面客户端采用 **Electron + Vue 3**（而非 Avalonia/FluentAvalonia）：正文 90% 的要求
|
||||||
|
> （Socket.IO Client、Pinia、IndexedDB 离线缓存、electron-builder）都基于 Electron，
|
||||||
|
> 且本机没有 .NET SDK。
|
||||||
|
> 2. 数据库 **先用 SQLite（libSQL 内嵌）跑通 MVP，并预留 MySQL 切换**：本机没有可用 MySQL
|
||||||
|
> 实例；`docs/mysql.md` 给出云数据库切换的完整步骤，`deploy/` 提供 MySQL 版 Compose。
|
||||||
|
|
||||||
#### [🚀 软件下载](https://github.com/LoveChengke/ClassHelper/releases/latest) | [📚 使用文档](docs/index.md) | [🧭 完整参考](docs/reference.md) | [💬 反馈问题](https://github.com/LoveChengke/ClassHelper/issues)
|
## 三套交付产物
|
||||||
|
|
||||||
</div>
|
| 产物 | 文件 | 用途 |
|
||||||
|
| ------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
||||||
|
| **服务端 + Web 管理端安装程序** | `release-server/班级小助手服务端-0.1.0-x64-setup.exe`（34 MB） | 装到教师电脑/校服务器即完整系统，**内置 Node 运行时**，双击安装、开机自启、自动建库建号 |
|
||||||
|
| **学生客户端安装程序** | `packages/desktop-client/release/班级小助手-0.1.0-x64-setup.exe`（107 MB） | 学生机安装（NSIS 安装包） |
|
||||||
|
| **学生客户端单文件版** | `packages/desktop-client/release/班级小助手-0.1.0-x64-portable.exe`（107 MB） | 免安装直接运行（U 盘分发） |
|
||||||
|
| Web 管理端（PWA） | 由服务端在 `/` 直接托管 | 浏览器打开即用，可在 Edge/Chrome 中「安装为应用」；**已适配手机小屏**（1Panel 风格抽屉导航） |
|
||||||
|
|
||||||
## 它由什么组成
|
生产部署（Windows 安装包 / Docker + MySQL / 手动部署）请看
|
||||||
|
**[docs/production.md](docs/production.md)**。
|
||||||
|
|
||||||
一份代码，三个交付物：
|
## 目录结构
|
||||||
|
|
||||||
| 装在哪 | 是什么 | 谁在用 |
|
```
|
||||||
| ----------------------- | -------------------------------------------------------------------- | -------------------- |
|
class-helper/
|
||||||
| 教师的电脑 / 学校服务器 | **服务端**（Express + Prisma + Socket.IO），同时托管 Web 管理端 | 管理端与客户端 |
|
├── package.json # 根脚本（dev / build / db:* / verify:* / dist:* / icons）
|
||||||
| 浏览器（手机也行） | **Web 管理端**（Vue 3 + Element Plus，PWA 可安装） | 老师、班主任、管理员 |
|
├── pnpm-workspace.yaml # workspace 定义 + allowBuilds（pnpm 11 依赖构建白名单）
|
||||||
| 教室那台机器 / 学生电脑 | **桌面客户端**（Electron + Vue 3），含「灵动岛」浮窗、托盘、离线缓存 | 教室大屏、学生 |
|
├── tsconfig.base.json # 共享 TS 基础配置
|
||||||
|
├── eslint.config.mjs # ESLint 扁平配置（TS + Vue）
|
||||||
|
├── .dockerignore # 容器构建上下文排除项
|
||||||
|
├── build/icon.{ico,png} # 应用图标（由 pnpm icons 生成）
|
||||||
|
├── scripts/
|
||||||
|
│ ├── use-database.mjs # SQLite ⇄ MySQL provider 切换助手
|
||||||
|
│ ├── generate-icons.mjs # 用 Electron 渲染 SVG 生成 PNG/ICO 图标
|
||||||
|
│ ├── dist-server.mjs # 服务端 + Web 管理端 打包（免安装目录 + NSIS 安装程序）
|
||||||
|
│ ├── lib/electron-env.mjs # 启动 Electron 的公共处理（清理 RUN_AS_NODE + 定位可执行文件）
|
||||||
|
│ ├── nsis/server-installer.nsi# 安装程序脚本模板
|
||||||
|
│ └── ui-smoke/ # Web 管理端 UI 真实点击回归测试（Electron 驱动 + 上课时段探针）
|
||||||
|
├── deploy/ # 生产部署：Dockerfile / docker-compose.yml / nginx.conf
|
||||||
|
├── docs/
|
||||||
|
│ ├── production.md # 生产部署指南（三种形态 + 运维 + 安全清单）
|
||||||
|
│ └── mysql.md # MySQL 切换指南
|
||||||
|
└── packages/
|
||||||
|
├── shared/ # 三端共享：类型契约、常量、工具函数
|
||||||
|
│ └── src/{types,constants,utils,index}.ts
|
||||||
|
├── server/ # 后端服务
|
||||||
|
│ ├── prisma/schema.prisma # 数据模型
|
||||||
|
│ ├── prisma/migrations/ # 迁移历史（已生成并应用）
|
||||||
|
│ ├── prisma/seed.ts # 种子数据
|
||||||
|
│ ├── prisma.config.ts # Prisma 7 配置（迁移/种子/连接串）
|
||||||
|
│ ├── scripts/verify-e2e.mjs # 后端端到端验收脚本（62 项）
|
||||||
|
│ └── src/
|
||||||
|
│ ├── app.ts # Express 装配（静态托管 + 探针 + 限流 + 模块挂载）
|
||||||
|
│ ├── index.ts # 启动入口（自检/初始化 + HTTP + Socket.IO + 优雅退出）
|
||||||
|
│ ├── config/env.ts # 环境变量校验（zod）+ 生产配置自检
|
||||||
|
│ ├── lib/ # db / db-bootstrap / web-static / http / jwt / access(RBAC) / mappers
|
||||||
|
│ ├── middleware/ # auth / error / validate / security(helmet+限流+耗时日志)
|
||||||
|
│ ├── realtime/ # socket.ts + bus.ts（事件总线）
|
||||||
|
│ └── modules/ # 功能模块 + registry.ts
|
||||||
|
├── web-admin/ # Web 管理端（Vue 3 + Vite + Element Plus + PWA）
|
||||||
|
│ ├── public/ # manifest / sw.js / 图标（由 pnpm icons 生成）
|
||||||
|
│ └── src/{api,stores,router,layouts,views,styles}
|
||||||
|
└── desktop-client/ # EXE 客户端（Electron + Vue 3）
|
||||||
|
├── electron-builder.yml # 打包配置（nsis 安装包 + portable 单文件）
|
||||||
|
├── build/icon.ico # 应用图标（electron-builder 自动使用）
|
||||||
|
├── vite.config.mts # 渲染进程构建（base: './'，hash 路由）
|
||||||
|
├── scripts/{build-main,dev,smoke,dist-win}.mjs
|
||||||
|
└── src/
|
||||||
|
├── main/ # 主进程：窗口/单实例/配置持久化(IPC)/冒烟验证/灵动岛
|
||||||
|
├── preload/ # contextBridge 安全桥（不暴露 ipcRenderer 本体）
|
||||||
|
├── island/ # 灵动岛渲染进程（独立透明置顶窗口）
|
||||||
|
├── types/desktop.d.ts # 主进程 <-> 渲染进程契约
|
||||||
|
└── renderer/ # 渲染进程：api / stores / cache / router / layouts / views
|
||||||
|
```
|
||||||
|
|
||||||
老师在 Web 端发布内容 → 服务端落库并按班级房间广播 → 客户端与灵动岛实时更新。
|
## 技术栈
|
||||||
|
|
||||||
## 功能
|
| 层 | 选型 | 版本 |
|
||||||
|
| ---------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
|
||||||
|
| 包管理 | pnpm workspace | 11.8.0 |
|
||||||
|
| 语言 | TypeScript | 5.9.3（`typescript-eslint` 要求 < 6.1，因此未用 7.x） |
|
||||||
|
| 后端 | Node.js + Express | 24.18 / 5.2 |
|
||||||
|
| ORM | Prisma + driver adapter | 7.10（+ `@prisma/adapter-libsql`） |
|
||||||
|
| 实时 | Socket.IO | 4.8 |
|
||||||
|
| 认证 | jsonwebtoken + bcryptjs | 9.0 / 3.0 |
|
||||||
|
| 校验 | zod | 4.6 |
|
||||||
|
| Web 端 | Vue 3 + Vite + Element Plus + Pinia + Vue Router + Axios + ECharts | 3.5 / 8.3 / 2.14 / 4.0 / 5.3 / 1.20 / 6.1 |
|
||||||
|
| EXE 客户端 | Electron + Vue 3 + Element Plus + Pinia + Socket.IO Client + IndexedDB | 44.3 / 3.5 / 2.14 / 4.0 / 4.8 |
|
||||||
|
| 打包 | electron-builder（nsis / portable） | 26.15 |
|
||||||
|
|
||||||
### Web 管理端（老师 / 管理员）
|
> 运行环境要求：**Node.js ≥ 20.19**（Prisma 7 硬性要求，推荐 22/24）。
|
||||||
|
|
||||||
- [x] 仪表盘：本班人数、课程、课表、作业、通知、成绩一屏概览
|
## 快速开始
|
||||||
- [x] 班级管理：建班自动生成班级码与班级密码，随时更换班主任、按科目配置各科任课老师
|
|
||||||
- [x] 学生 / 教师管理：单个录入或导入名单（xlsx / xls / csv / tsv）
|
|
||||||
- [x] 课表管理：按周排课、单双周，可直接从 ClassIsland 档案导入课表与节次时间
|
|
||||||
- [x] 作业发布：按「所属日期」归类，支持附件与未交名单
|
|
||||||
- [x] 通知发布：三档优先级；在**上课时段**发紧急通知会被拦下来并要求二次确认
|
|
||||||
- [x] 叫人：点名某位同学到办公室，分「普通」与「紧急」两级
|
|
||||||
- [x] 成绩录入：单条 / 批量 / 表格导入，带等级分布与得分率统计；单科排名自动出，可选「各科相加排总分榜」
|
|
||||||
- [x] 客户端管理：查看设备在线状态与版本，远控关机、重启、注销与锁屏；推送更新可选立即、放学后或空闲时安装
|
|
||||||
- [x] 数据库管理：连接体检、备份与恢复、SQLite ⇄ MySQL 一键切换
|
|
||||||
- [x] 权限组：37 个权限键，建组分配账号 —— 默认组可自定义，没分组的按角色默认组生效，分组后只按组的并集算
|
|
||||||
- [x] 客户端设备：每台教室机器的版本、在线状态与最后心跳；一键推送更新，可下发关机 / 重启 / 注销 / 锁屏
|
|
||||||
- [x] 大模型助手：一句话解析成待确认的作业 / 通知 / 叫人，点确认才落库
|
|
||||||
- [x] 通知与作业批量发布：勾多个班一次发完，个别班失败不影响其余班级
|
|
||||||
- [x] 系统设置：开发者模式、运行诊断、开机自启开关（仅安装形态）
|
|
||||||
- [x] 关怀模式：字号与控件整体放大
|
|
||||||
- [x] 手机小屏适配，可「添加到主屏幕」当应用用
|
|
||||||
|
|
||||||
### 教室里的桌面客户端
|
```bash
|
||||||
|
# 1. 安装依赖（Node >= 20.19，pnpm >= 10）
|
||||||
|
pnpm install
|
||||||
|
|
||||||
- [x] 班级码登录 —— 学生没有个人账号，一台教室机器代表一个班
|
# 2. 准备环境变量（后端）
|
||||||
- [x] 课表：「今天」时间轴（大时钟 + 正在上 / 下一节 + 距下课倒计时）与周视图
|
cp packages/server/.env.example packages/server/.env
|
||||||
- [x] 作业看板：按科目分卡、可全屏铺满、字号可调，也能切回列表
|
# → 至少修改 JWT_SECRET；本地开发可直接使用仓库内已有的 .env
|
||||||
- [x] 通知中心：未读红点、优先级标签、点击自动标为已读
|
|
||||||
- [x] 成绩总览：全班成绩表格 + 柱状图 + 等级分布；按考试看单科排名，老师开启后还有总分排名
|
# 3. 生成 Prisma Client 并建库、写入种子数据
|
||||||
- [x] 教室机器可直接录入作业、勾选未交名单
|
pnpm db:generate
|
||||||
- [x] 离线优先：断网回退 IndexedDB 缓存，恢复连接后自动同步
|
pnpm db:migrate
|
||||||
- [x] 断网期间错过的通知，重新上线时补弹一次；渲染进程崩了会安静地自己重建窗口
|
pnpm db:seed
|
||||||
- [x] 浅色 / 深色主题，跟随系统
|
|
||||||
|
# 4. 启动（后端 4000 + Web 端 5173 一起启动）
|
||||||
|
pnpm dev
|
||||||
|
```
|
||||||
|
|
||||||
|
启动后访问：
|
||||||
|
|
||||||
|
| 服务 | 地址 |
|
||||||
|
| ------------------------------------------ | -------------------------------- |
|
||||||
|
| Web 管理端（开发） | http://127.0.0.1:5173 |
|
||||||
|
| 后端服务首页（浏览器可读，列出已挂载模块） | http://127.0.0.1:4000 |
|
||||||
|
| 后端 API | http://127.0.0.1:4000/api |
|
||||||
|
| 健康检查 | http://127.0.0.1:4000/api/health |
|
||||||
|
|
||||||
|
> 后端只提供 REST API 与 WebSocket，没有业务网页界面。直接访问
|
||||||
|
> `http://127.0.0.1:4000/` 会返回服务首页（带 `Accept: application/json` 时返回结构化信息）；
|
||||||
|
> 其它未匹配路径统一返回 `{ "success": false, "code": "NOT_FOUND" }`。
|
||||||
|
> Web 管理端地址是 **5173** 端口，请勿访问 80 端口（会连接被拒绝）。
|
||||||
|
|
||||||
|
也可以分开启动：`pnpm dev:server`（仅后端）、`pnpm dev:web`（仅 Web 端）。
|
||||||
|
|
||||||
|
### 启动 EXE 客户端（学生端）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 开发模式：自动构建主进程 + 启动 Vite 渲染进程(5174) + 打开 Electron 窗口（支持热更新）
|
||||||
|
pnpm dev:desktop
|
||||||
|
|
||||||
|
# 已构建产物的冒烟验证（不弹窗，跑完自动退出）
|
||||||
|
pnpm build:desktop
|
||||||
|
pnpm verify:desktop
|
||||||
|
```
|
||||||
|
|
||||||
|
客户端首次启动会带上默认服务器地址 `http://127.0.0.1:4000`，可用学生账号 `student01 / student123` 登录。
|
||||||
|
若要验证"断网可查看缓存"，登录并浏览过程序后关闭后端（`Ctrl+C` 停掉 `pnpm dev:server`），
|
||||||
|
客户端会在顶部提示「当前处于离线状态」，页面继续显示本地缓存数据；重新启动后端后会自动同步。
|
||||||
|
|
||||||
|
### 端到端验收脚本
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 另开一个终端先启动后端：pnpm dev:server
|
||||||
|
pnpm verify:e2e # 后端 + REST + Socket.IO + RBAC + 上课时段拦截：62 项
|
||||||
|
pnpm verify:web # Web 管理端真实点击（含手机小屏适配、上课时段紧急通知全屏警告）：15 项
|
||||||
|
pnpm verify:desktop # Electron 客户端（含灵动岛、真实通知链路与联网集成）：27 项
|
||||||
|
```
|
||||||
|
|
||||||
|
后端脚本验证**实时推送时延、作业完成、成绩下发、权限隔离、上课时段紧急通知拦截**等 62 项，
|
||||||
|
实测通知 37ms、作业 26ms、成绩 25ms 到达（要求 < 5 秒），紧急通知 409 拦截与二次确认后发布均通过；
|
||||||
|
客户端脚本验证 preload 桥接、渲染进程、IndexedDB 读写、断网回退、**灵动岛四种状态切换**与联网集成
|
||||||
|
（登录 + 四类数据 + Socket.IO），实测 27/27 通过。
|
||||||
|
|
||||||
|
## 默认账号与种子数据
|
||||||
|
|
||||||
|
`pnpm db:seed` 会清空业务表并写入一套完整演示数据（1 管理员 / 2 教师 / 3 班级 / 15 学生 /
|
||||||
|
15 课程 / 90 条课表 / 15 份作业 / 12 条通知 / 90 条成绩）。
|
||||||
|
|
||||||
|
| 角色 | 用户名 | 密码 | 说明 |
|
||||||
|
| ------ | ------------------------- | ------------ | ------------------------------------------ |
|
||||||
|
| 管理员 | `admin` | `admin123` | 可访问全部班级 |
|
||||||
|
| 教师 | `teacher1` | `teacher123` | 张老师：高一(1)班、高二(3)班班主任 |
|
||||||
|
| 教师 | `teacher2` | `teacher123` | 李老师：高一(2)班班主任，高二(3)班协作教师 |
|
||||||
|
| 学生 | `student01` | `student123` | 高一(1)班 |
|
||||||
|
| 学生 | `student02` … `student05` | `student123` | 高一(1)班 |
|
||||||
|
| 学生 | `student06` … `student10` | `student123` | 高一(2)班 |
|
||||||
|
| 学生 | `student11` … `student15` | `student123` | 高二(3)班 |
|
||||||
|
|
||||||
|
- 学生初始密码可用 `DEFAULT_STUDENT_PASSWORD` 配置（默认 `123456`），
|
||||||
|
教师也可在「学生管理」里一键重置为默认密码。
|
||||||
|
- 教学周由 `TERM_START_DATE`（第 1 教学周的周一）换算，当前周次用于课表默认视图。
|
||||||
|
|
||||||
|
## 常用命令
|
||||||
|
|
||||||
|
| 命令 | 说明 |
|
||||||
|
| ------------------------------------------- | --------------------------------------------------------------------------------------- |
|
||||||
|
| `pnpm dev` | 并行启动 shared(tsc watch) + 后端 + Web 端 |
|
||||||
|
| `pnpm dev:server` / `pnpm dev:web` | 只启动后端 / 只启动 Web 端 |
|
||||||
|
| `pnpm dev:desktop` | 启动 EXE 客户端开发模式（Vite 5174 + Electron，热更新） |
|
||||||
|
| `pnpm build` | 构建 shared + 后端 + Web 端 + EXE 客户端 |
|
||||||
|
| `pnpm build:desktop` | 仅构建 EXE 客户端（esbuild 主进程/preload + Vite 渲染进程） |
|
||||||
|
| `pnpm icons` | 生成应用图标（PNG/ICO，用 Electron 渲染 SVG） |
|
||||||
|
| **`pnpm dist:server`** | **打包服务端 + Web 管理端**（免安装目录 + NSIS 安装程序，内置 Node） |
|
||||||
|
| `pnpm dist:dir` | 打包客户端免安装目录 `release/win-unpacked`（含可执行文件，最快） |
|
||||||
|
| `pnpm dist:win` | 打包客户端 nsis 安装包 + portable 单文件 EXE |
|
||||||
|
| `pnpm dist:all` | 服务端安装程序 + 客户端安装程序一起打 |
|
||||||
|
| `pnpm verify:e2e` | 后端端到端验收（62 项，需服务端已启动） |
|
||||||
|
| `pnpm verify:web` | Web 管理端 UI 真实点击测试（Electron 驱动，15 项，含手机小屏适配） |
|
||||||
|
| `pnpm verify:desktop` | EXE 客户端冒烟验证（27 项，含灵动岛行为/像素级截图/真实通知链路、侧边栏点击与离线回退） |
|
||||||
|
| `pnpm typecheck` | 全仓库类型检查（含 `vue-tsc`） |
|
||||||
|
| `pnpm lint` / `pnpm lint:fix` | ESLint 检查 / 自动修复 |
|
||||||
|
| `pnpm format` / `pnpm format:check` | Prettier 格式化 / 检查 |
|
||||||
|
| `pnpm db:generate` | 生成 Prisma Client（输出到 `packages/server/src/generated/prisma`） |
|
||||||
|
| `pnpm db:migrate` | 创建并应用迁移 |
|
||||||
|
| `pnpm db:seed` | 写入种子数据 |
|
||||||
|
| `pnpm db:reset` | 重置数据库并重新执行 seed |
|
||||||
|
| `pnpm db:studio` | 打开 Prisma Studio |
|
||||||
|
| `pnpm db:switch:mysql` / `db:switch:sqlite` | 切换数据库 provider |
|
||||||
|
|
||||||
|
## Web 管理端（含手机小屏适配）
|
||||||
|
|
||||||
|
布局沿用 **1Panel 风格**：固定深色侧边栏（`#1f2d3d` + 蓝色圆角选中态）+ 白色顶栏（当前页标题/连接状态/用户菜单）+
|
||||||
|
浅灰底 + 白色圆角卡片内容区。手机小屏下侧边栏收进抽屉，由顶栏汉堡按钮唤出。
|
||||||
|
|
||||||
|
| 断点 | 布局行为 |
|
||||||
|
| ---------------- | --------------------------------------------------------------------------------------------- |
|
||||||
|
| `> 992px` 桌面 | 常驻 210px 深色侧边栏 + 顶栏显示连接状态与"已接收 N 条实时事件" |
|
||||||
|
| `769–992px` 平板 | 保留侧边栏，内容区内边距压缩（14px） |
|
||||||
|
| `<= 768px` 手机 | 侧边栏**不渲染**，顶栏汉堡按钮 → 240px 深色抽屉菜单；顶栏显示当前页标题；用户菜单收成头像图标 |
|
||||||
|
|
||||||
|
手机端细节（1Panel 同款思路：控件纵向铺满、表格卡片内滚动、弹窗自适应）：
|
||||||
|
|
||||||
|
| 位置 | 小屏行为 |
|
||||||
|
| ----------- | ----------------------------------------------------------------------------- |
|
||||||
|
| 抽屉菜单 | 点汉堡滑出、点菜单项自动收起；`aria-expanded` 标记状态；桌面端侧边栏视觉不变 |
|
||||||
|
| 顶栏 | 只保留汉堡 + 当前页标题 + 连接状态圆点 + 头像；身份信息移入用户下拉菜单第一行 |
|
||||||
|
| 页面工具栏 | 选择器/搜索框/按钮全部铺满整行（`width: 100%`），方便拇指点击 |
|
||||||
|
| 表格 | 卡片内横向滚动（`.table-card` + `overflow-x: auto`），页面本身不横向滚动 |
|
||||||
|
| 弹窗/消息框 | 宽度 `calc(100vw - 24px)`、贴近整屏；表单标签与输入框自适应 |
|
||||||
|
| 详情抽屉 | 宽 86vw；`el-descriptions` 由 2~3 列自动降为单列，避免文字被压成竖排 |
|
||||||
|
| 统计卡片 | `.stat-grid` 两列；登录页卡片自适应宽度并保留安全内边距 |
|
||||||
|
|
||||||
|
实拍（`pnpm verify:web` 自动留档到 `docs/screenshots/web-mobile/`）：
|
||||||
|
|
||||||
|
| 场景 | 截图 |
|
||||||
|
| ----------------------------------------- | --------------------------------------------------------------------- |
|
||||||
|
| 手机抽屉菜单 |  |
|
||||||
|
| 手机通知页（工具栏铺满 + 表格卡片内滚动） |  |
|
||||||
|
| 手机弹窗自适应 |  |
|
||||||
|
|
||||||
|
实现位置：`src/composables/useResponsive.ts`（断点 + resize 监听）、`src/layouts/AdminLayout.vue`（抽屉/顶栏）、
|
||||||
|
`src/styles/index.css`（全局响应式规则）、各视图表格卡片加 `.table-card`。
|
||||||
|
|
||||||
|
`pnpm verify:web` 的 15 项里，后 7 项专门验证手机端（Electron 真实点击 + 真实尺寸窗口）：
|
||||||
|
|
||||||
|
| 校验项 | 实测结果 |
|
||||||
|
| -------------------------------------- | -------------------------------------------------------------------- |
|
||||||
|
| 侧边栏收起、顶栏汉堡按钮出现 | ✅ `innerWidth=377` 汉堡=true 桌面侧边栏未渲染 |
|
||||||
|
| 点汉堡滑出抽屉菜单（菜单项完整） | ✅ 7 项、`left=0`、`transform=none`、遮罩进入动画已结束 |
|
||||||
|
| 抽屉里真实点击"通知发布"并自动收起抽屉 | ✅ `path=/notifications`、抽屉 `right=0`（已滑出屏幕） |
|
||||||
|
| 页面无横向溢出 | ✅ `scrollWidth=377 = innerWidth`，越界元素=无（表格自身滚动不计入） |
|
||||||
|
| 表格在卡片内横向滚动 | ✅ 卡片可视 336px / 内容 576px / 表格 560px |
|
||||||
|
| 工具栏控件铺满整行 | ✅ 控件宽 338px（视口 377px） |
|
||||||
|
| 弹窗宽度自适应 | ✅ 弹窗宽 353px、`left=12`（不超出视口且接近整屏） |
|
||||||
|
|
||||||
|
> 踩坑记录：这套检查必须让窗口**真正可见**（`win.showInactive()`）。
|
||||||
|
> Chromium 会冻结隐藏页面的 CSS transition，Vue 的 `<Transition>` 收不到 `transitionend`，
|
||||||
|
> Element Plus 抽屉会一直停在 `enter-from`（表现为"点了没反应"）——冒烟里已按"等抽屉滑到位"断言，避免误判。
|
||||||
|
|
||||||
|
> 手机访问：与电脑同一局域网时用 `http://<主机IP>:4000` 打开管理端；
|
||||||
|
> 支持「添加到主屏幕」（PWA manifest + Service Worker）。
|
||||||
|
|
||||||
|
## EXE 客户端（学生端）
|
||||||
|
|
||||||
|
### 进程结构与安全设置
|
||||||
|
|
||||||
|
| 进程 | 文件 | 职责 |
|
||||||
|
| -------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
|
||||||
|
| 主进程 | `src/main/*` → `dist/main/index.js` | 窗口/单实例锁、配置持久化（`safeStorage` 加密 token）、IPC、冒烟验证 |
|
||||||
|
| 预加载 | `src/preload/index.ts` → `dist/preload/index.js` | 通过 `contextBridge` 暴露最小 API（`getConfig/saveConfig/getAppInfo/openExternal`），不暴露 `ipcRenderer` 本体 |
|
||||||
|
| 渲染进程 | `src/renderer/**` → `dist/renderer/*` | Vue 3 界面、Axios 请求、Socket.IO 实时、IndexedDB 离线缓存 |
|
||||||
|
|
||||||
|
安全基线：`contextIsolation: true`、`nodeIntegration: false`、`sandbox: true`、`webSecurity: true`，
|
||||||
|
外部链接一律交给系统浏览器打开，禁止应用内导航到非本地地址。
|
||||||
|
|
||||||
|
### 功能页面
|
||||||
|
|
||||||
|
| 页面 | 功能 |
|
||||||
|
| ---- | ----------------------------------------------------------------------------------------- |
|
||||||
|
| 登录 | 服务器地址 + 用户名 + 密码，附带「测试连接」；已登录但服务器不可达时可「离线进入」 |
|
||||||
|
| 课表 | 按周展示 7 列课表，支持上一周/下一周/下拉选择周次，高亮"今天"，显示周次范围与地点 |
|
||||||
|
| 作业 | 列表（全部/未完成/已完成过滤）、详情抽屉、标记完成/取消完成、附件链接、逾期高亮 |
|
||||||
|
| 通知 | 未读红点（侧边栏徽标）、优先级标签、点击自动标为已读、全部已读、未读过滤、详情抽屉 |
|
||||||
|
| 成绩 | 表格（分数/得分率进度条/等级）+ ECharts 柱状图（各次考试平均得分率）+ 等级分布 + 最近更新 |
|
||||||
|
| 设置 | 服务器地址（保存并测试）、账号信息、离线缓存条目统计与清空、客户端版本信息、退出登录 |
|
||||||
|
|
||||||
|
> 通知到达时还会由**灵动岛**在桌面中上方浮出提醒（见上一节），上课时段自动隐藏、紧急通知立即展开。
|
||||||
|
|
||||||
### 灵动岛（桌面通知浮窗）
|
### 灵动岛（桌面通知浮窗）
|
||||||
|
|
||||||
- [x] 通知、新作业、叫人都会上岛：先是胶囊，点开是详情卡
|
客户端有一个独立于主窗口的**灵动岛**：一个无边框、透明、置顶、不占任务栏的窄条窗口，
|
||||||
- [x] 多条消息展开为竖排列表，按重要程度排序，放不下时提示去应用内看
|
常驻桌面**中上方**（屏幕工作区顶部居中，`y = workArea.y + 8`）。它是"消息到达"的第一现场：
|
||||||
- [x] **上课时段不打扰**：普通通知暂存到下课再弹；紧急通知与叫人立刻弹
|
|
||||||
- [x] 尺寸、圆角、字号、主题色、停靠位置（顶部 / 底部 × 左 / 中 / 右）都可以调
|
|
||||||
- [x] 纯黑 / 毛玻璃 / 主题色渐变三种底
|
|
||||||
- [x] 触摸屏（希沃白板这类一体机）也能点开
|
|
||||||
|
|
||||||
### 部署与运维
|
| 场景 | 灵动岛行为 |
|
||||||
|
| -------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
||||||
|
| 收到通知（非上课时段） | **直接出现胶囊**（无"上岛"入场动画）：`新消息 · 共 N 条` + 发送人 + `点击查看`，15 秒后自动收起 |
|
||||||
|
| 点击胶囊 | 展开为**详情卡**（弹簧形变 + 内容弹入）：标题、内容、时间、`打开应用 / 标为已读 / 知道了`，20 秒后收起 |
|
||||||
|
| 点击卡片空白处 | 回缩为**胶囊**（不直接消失，仍可再次点开） |
|
||||||
|
| 点击右上角收起按钮 | 同上：回缩为胶囊 |
|
||||||
|
| 上课时间段收到普通通知 | **完全不显示**（窗口直接隐藏，不打扰课堂）并进入待发队列；下课后自动弹出详情（14 秒）→ 收起为胶囊（25 秒） |
|
||||||
|
| 上课时间段收到**紧急**通知 | **无论是否上课立刻展开**显示详情（带内部红色呼吸光晕与"紧急"角标，无需点击），45 秒后收起 |
|
||||||
|
| 上课时间段内的任何点击 | 一律不显示（不会展开、也不会回缩出胶囊），只有紧急通知能出现在屏幕上 |
|
||||||
|
| 多条约谈 | 队列按时间排序，紧急通知优先插播；卡片底部提示"还有 N 条通知" |
|
||||||
|
| 退出/断开 | 主窗口退出时灵动岛一并关闭；上课状态来自 `GET /api/schedules/current`（10 秒心跳 + 下课时长定时器） |
|
||||||
|
|
||||||
- [x] Windows 一键安装：内置 Node 运行时，双击安装、开机自启、自动建库建号
|
- 动画：窗口尺寸用逐帧缓动实现"形变"（胶囊 → 详情/紧急为 340ms `easeOutBack` **弹簧回弹**，
|
||||||
- [x] Linux 一键安装 + `classhelper` 运维命令（systemd 托管，升级 / 回滚 / 备份）
|
收起为 260ms `easeOutCubic`），胶囊出现**不做动画**直接显示；
|
||||||
- [x] Docker Compose（MySQL 版与 SQLite 版各一份）
|
卡片内部用 `cubic-bezier(0.34, 1.56, 0.64, 1)` 弹簧缩放入场，未读点用 `dot-pulse`。
|
||||||
- [x] SQLite 与 MySQL 一键切换，备份与跨库迁移共用同一份 JSON 快照
|
尺寸与淡入使用**独立令牌**，互不打断（早前"淡入取消形变导致窗口卡在胶囊尺寸"的问题已修复）。
|
||||||
- [x] 客户端批量更新不依赖外网：安装包由服务端下载缓存，教室机从服务端取，校验 sha256 后空闲时自动装
|
- 光晕：紧急形态的红色呼吸光晕**只用 inset 阴影**画在卡片内部。
|
||||||
|
窗口只比卡片大 2~4px，任何向外的 box-shadow/光晕都会被窗口边界裁切，
|
||||||
|
在屏幕上表现为"卡片周围一圈奇怪的光晕硬边"——冒烟测试里有一条像素断言守着这一点
|
||||||
|
（截图最外圈偏红像素必须为 0）。
|
||||||
|
- 事件流：`notification:new` → `renderer/stores/realtime.ts` → `pushNotificationToIsland()` →
|
||||||
|
主进程 `IslandController`（决定隐藏/胶囊/详情）→ 灵动岛渲染进程 `src/island/IslandApp.vue`。
|
||||||
|
- 相关文件：`src/main/island.ts`（控制器 + IPC）、`src/preload/island.ts`、`src/island/IslandApp.vue`、
|
||||||
|
`src/renderer/island/bridge.ts`（上课状态轮询与通知转发）。
|
||||||
|
|
||||||
## 软件截图
|
各形态实拍（由 `pnpm verify:desktop` 自动截取并归档到 `docs/screenshots/island/`，并做像素级校验）：
|
||||||
|
|
||||||
> 下面这些图都是脚本把程序真的跑起来截的（`node website/tools/capture-shots.mjs` 与客户端冒烟），不是示意图。
|
| 形态 | 截图 | 尺寸（逻辑 / 截图） | 说明 |
|
||||||
|
| ---------------------- | ------------------------------------------------------------------- | ------------------- | ----------------------------------------- |
|
||||||
|
| 下课后自动弹出详情 |  | 404×316 / 808×632 | 上课期间暂存的通知，下课后自动弹出 |
|
||||||
|
| 上课期间紧急通知 |  | 424×344 / 848×688 | 卡片**内部**红色光晕 + 紧急角标，无需点击 |
|
||||||
|
| 非上课时段"新消息"胶囊 |  | 268×44 / 536×88 | 直接出现（无入场动画），点击后展开 |
|
||||||
|
| 点击胶囊后的详情 |  | 404×316 / 808×632 | 标题/内容/时间 + 打开应用/标为已读/知道了 |
|
||||||
|
|
||||||
### Web 管理端
|
> 截图路径可用 `ISLAND_SHOTS_DIR` 覆盖（默认 `.cache/island-shots/`）；
|
||||||
|
> 归档目录里的图就是打包后 EXE 跑自动化验证时产出的同一份文件。
|
||||||
|
> 不设置该变量时只做像素统计与断言、不落盘，验证同样通过。
|
||||||
|
|
||||||
<img src="docs/images/web-schedules.jpg" alt="Web 管理端 · 课表管理" />
|
**灵动岛不出现时怎么排查**（客户端是 GUI，看不到控制台，因此提供两条自查通道）：
|
||||||
|
|
||||||
<details>
|
1. 客户端 → **设置 → 灵动岛（桌面通知浮窗）**：实时显示当前形态（隐藏 / 新消息胶囊 / 展开详情）、
|
||||||
<summary>展开其余页面……</summary>
|
是否处于上课时段、待查看条数与原因说明，并提供「测试灵动岛」按钮——
|
||||||
|
点击后本地推一条自检通知；能看到胶囊就说明灵动岛本身正常，问题在"没有通知到达"或"上课时段自动隐藏"。
|
||||||
|
2. 客户端日志：`%APPDATA%\@classhelper\desktop-client\logs\client.log`（超过 1MB 轮转为 `client.log.1`），
|
||||||
|
按时间记录灵动岛的每次状态流转，例如 `灵动岛：进入上课时间段，自动隐藏`、
|
||||||
|
`灵动岛暂存通知（上课中，下课后弹出）`、`灵动岛：下课，弹出上课期间暂存的通知`。
|
||||||
|
|
||||||
| 页面 | 截图 |
|
常见原因（按出现频率）：
|
||||||
| ---------- | -------------------------------------------------------------- |
|
|
||||||
| 仪表盘 | <img src="docs/images/web-dashboard.jpg" alt="仪表盘" /> |
|
|
||||||
| 班级管理 | <img src="docs/images/web-classes.jpg" alt="班级管理" /> |
|
|
||||||
| 学生管理 | <img src="docs/images/web-students.jpg" alt="学生管理" /> |
|
|
||||||
| 教师管理 | <img src="docs/images/web-teachers.jpg" alt="教师管理" /> |
|
|
||||||
| 课表管理 | <img src="docs/images/web-schedules.jpg" alt="课表管理" /> |
|
|
||||||
| 作业发布 | <img src="docs/images/web-homeworks.jpg" alt="作业发布" /> |
|
|
||||||
| 通知发布 | <img src="docs/images/web-notifications.jpg" alt="通知发布" /> |
|
|
||||||
| 成绩录入 | <img src="docs/images/web-grades.jpg" alt="成绩录入" /> |
|
|
||||||
| 数据库管理 | <img src="docs/images/web-database.jpg" alt="数据库管理" /> |
|
|
||||||
|
|
||||||
</details>
|
| 现象 | 原因与处理 |
|
||||||
|
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
|
| 一整天都不出现 | 客户端判定为"上课中"（课表覆盖当前时刻）→ 普通通知按设计暂存，紧急通知才立刻展开；下课后自动弹出 |
|
||||||
|
| 登录页时就期待出现 | 未登录不启动灵动岛桥接（`auth.token` 为空），登录后才有 |
|
||||||
|
| 点过「知道了」后消失 | 正常行为：该条已看过，队列为空时整体隐藏，下一条通知会再出现 |
|
||||||
|
| 换显示器 / 分辨率后看不到 | 已修复：显示器参数变化会自动重新定位到主屏顶部居中（此前会停留在旧坐标，可能跑到屏幕外） |
|
||||||
|
| 偶发"再也不出现" | 已修复：Windows 上 `hide()`/`show()` 异步生效，原先用 `isVisible()` 判断存在竞态（刚 hide 完仍报 true）→ 只做动画不再 show；现改为控制器自己维护显示标记 |
|
||||||
|
| 客户端在跑但服务端离线 | 实时通道断开时收不到新通知；恢复连接自动重连，历史未读仍可在"通知"页查看 |
|
||||||
|
|
||||||
### 教室里的客户端
|
### 离线缓存与自动同步
|
||||||
|
|
||||||
<img src="docs/images/client-schedule.png" alt="桌面客户端 · 课表「今天」时间轴" />
|
```
|
||||||
|
┌────────────── 在线 ──────────────┐
|
||||||
<details>
|
请求 → fetchWithCache(store, key, loader, fallback)
|
||||||
<summary>展开其余页面……</summary>
|
└── 失败 → 读取 IndexedDB 缓存 → 返回旧数据（UI 标记"离线缓存"）
|
||||||
|
实时推送(notification:new / grade:updated ...) → 更新内存状态 + 写回 IndexedDB
|
||||||
| 页面 | 截图 |
|
服务器不可达 → 可达（health 轮询 20s 或任意请求成功）→ 触发 onServerRecovered → 各页自动重新拉取
|
||||||
| ----------------------- | -------------------------------------------------------------------------- |
|
|
||||||
| 作业看板 | <img src="docs/images/client-homeworks.png" alt="作业看板" /> |
|
|
||||||
| 通知 | <img src="docs/images/client-notifications.png" alt="通知" /> |
|
|
||||||
| 成绩 | <img src="docs/images/client-grades.png" alt="成绩" /> |
|
|
||||||
| 设置 · 灵动岛 | <img src="docs/images/client-settings-island.png" alt="设置 · 灵动岛" /> |
|
|
||||||
| 设置 · 外观（深色主题） | <img src="docs/images/client-settings-appearance.png" alt="设置 · 外观" /> |
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
### 灵动岛
|
|
||||||
|
|
||||||
| 形态 | 截图 | 说明 |
|
|
||||||
| ------------------ | ----------------------------------------------------------------------- | ----------------------------------------------- |
|
|
||||||
| 新消息胶囊 | <img src="docs/images/island-4-pill.png" alt="新消息胶囊" /> | 非上课时段直接出现，点一下展开 |
|
|
||||||
| 点开后的详情 | <img src="docs/images/island-5-clicked.png" alt="详情卡" /> | 标题、内容、时间 + 打开应用 / 标为已读 / 知道了 |
|
|
||||||
| 多条消息列表 | <img src="docs/images/island-9-list.png" alt="多条消息列表" /> | 按重要程度排序，默认显示三条 |
|
|
||||||
| 上课期间的紧急通知 | <img src="docs/images/island-3-urgent.png" alt="紧急通知" /> | 卡片内部红色呼吸光晕，无需点击 |
|
|
||||||
| 下课后补弹 | <img src="docs/images/island-2-after-class.png" alt="下课后自动弹出" /> | 上课期间暂存的通知，下课后自动弹出来 |
|
|
||||||
| 老师叫人 | <img src="docs/images/island-8-call.png" alt="叫人卡片" /> | 「请 XXX 同学找 XXX 老师」 |
|
|
||||||
| 新作业 | <img src="docs/images/island-7-homework.png" alt="新作业" /> | 教室机器自己录的那条不会弹给自己 |
|
|
||||||
|
|
||||||
### 手机上
|
|
||||||
|
|
||||||
<details>
|
|
||||||
<summary>展开……</summary>
|
|
||||||
|
|
||||||
| 场景 | 截图 |
|
|
||||||
| -------- | ------------------------------------------------------------------------ |
|
|
||||||
| 仪表盘 | <img src="docs/images/mobile-dashboard.jpg" alt="手机 · 仪表盘" /> |
|
|
||||||
| 通知发布 | <img src="docs/images/mobile-notifications.jpg" alt="手机 · 通知发布" /> |
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
## 开始使用
|
|
||||||
|
|
||||||
| 装在哪 | 装什么 | 从 Releases 里拿 |
|
|
||||||
| ----------------------- | ------------------------------------------- | --------------------------------------------------------------------------- |
|
|
||||||
| 教师的电脑 / 学校服务器 | **服务端**（内含 Web 管理端与 Node 运行时） | `ClassHelper-<版本>-x64-server-setup.exe` |
|
|
||||||
| 教室机器 / 学生电脑 | **学生客户端** | `ClassHelper-<版本>-x64-client-setup.exe`，或 `-client-portable.exe` 免安装 |
|
|
||||||
|
|
||||||
也可以在官网的[下载页](https://lovechengke.github.io/ClassHelper/download.html)上挑：
|
|
||||||
选一个版本，四个包排成四张卡，文件名、体积与 SHA256 清单都在那儿 ——
|
|
||||||
那一页的清单是**当场**读 GitHub Releases 的，显示什么就能下什么。
|
|
||||||
|
|
||||||
服务端**装上就算跑起来了**：双击安装程序，建库、建号、开机自启都由它自己办，
|
|
||||||
装完在浏览器打开 `http://<服务器地址>:4000` 就能登录。教师的电脑、学校的服务器、
|
|
||||||
一台常年开机的机器都可以装。
|
|
||||||
|
|
||||||
Linux 服务器有更省事的路子，一行命令装成 systemd 服务，并带上 `classhelper` 运维命令：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -fsSL -o /tmp/classhelper-install.sh https://raw.githubusercontent.com/LoveChengke/ClassHelper/master/deploy/install.sh && sudo bash /tmp/classhelper-install.sh
|
|
||||||
```
|
```
|
||||||
|
|
||||||
先体检、不改动系统的话，在末尾加上 `--check`。也可以走 Docker Compose，
|
- 缓存按业务域分为 6 个 object store：`profile` / `classes` / `schedules` / `homeworks` / `notifications` / `grades`。
|
||||||
完整步骤见[部署指南](docs/management/production.md)与 [Linux 运维手册](docs/management/linux-deploy.md)。
|
- 缓存写入前统一做 JSON 纯化（Vue 响应式对象是 Proxy，直接写入 IndexedDB 会抛 `could not be cloned`）。
|
||||||
|
- 登录令牌由主进程用 Electron `safeStorage`（Windows 下为 DPAPI）加密后落盘，因此重启客户端可离线进入。
|
||||||
|
- 令牌缺失/失效时保持缓存资料可见，恢复网络后自动刷新个人资料。
|
||||||
|
|
||||||
## 获取帮助
|
### 打包 Windows EXE
|
||||||
|
|
||||||
- **使用文档**：[docs/](docs/index.md) —— 分四块：第一次装、已经在用了、负责运维、要改代码
|
|
||||||
- **完整参考**：[docs/reference.md](docs/reference.md) —— 功能口径、REST API、权限矩阵、验收证据
|
|
||||||
- **遇到问题 / 想提需求**：[提交 Issue](https://github.com/LoveChengke/ClassHelper/issues/new/choose)
|
|
||||||
|
|
||||||
## 开发
|
|
||||||
|
|
||||||
| 层 | 选型 |
|
|
||||||
| ---------- | ------------------------------------------------------------------- |
|
|
||||||
| 后端 | Node.js ≥ 20.19 + Express 5 + Prisma 7（SQLite / MySQL）+ Socket.IO |
|
|
||||||
| Web 管理端 | Vue 3 + Vite + Element Plus + Pinia |
|
|
||||||
| 桌面客户端 | Electron 44 + Vue 3 + IndexedDB 离线缓存（含独立的灵动岛渲染进程） |
|
|
||||||
| 共享契约 | `packages/shared`：类型、常量、权限矩阵、动效令牌 |
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pnpm install
|
pnpm dist:dir # 免安装目录：packages/desktop-client/release/win-unpacked/班级小助手.exe
|
||||||
cp packages/server/.env.example packages/server/.env # 至少改 JWT_SECRET
|
pnpm dist:win # nsis 安装包 + portable 单文件（需联网下载 NSIS 工具，可用镜像）
|
||||||
pnpm db:generate
|
|
||||||
pnpm --filter @classhelper/server db:deploy # 根 scripts 里没有 db:deploy
|
|
||||||
pnpm build:shared # 三端与 seed 的前置产物
|
|
||||||
pnpm db:seed
|
|
||||||
pnpm dev # 后端 4000 + Web 端 5173
|
|
||||||
```
|
```
|
||||||
|
|
||||||
`pnpm db:seed` 会写一套演示数据（1 管理员 / 2 教师 / 3 个班 / 15 名学生 / 课表 / 作业 / 通知 / 成绩）：
|
打包脚本 `packages/desktop-client/scripts/dist-win.mjs` 做了三件事，规避常见网络问题：
|
||||||
|
|
||||||
| 角色 | 账号 | 密码 |
|
1. **复用本地已解压的 Electron**：检测到 `node_modules/electron/dist/electron.exe` 时通过
|
||||||
| -------------------------- | ------------- | ------------ |
|
`--config.electronDist` 直接使用，不再重复下载 150MB+ 发行包；
|
||||||
| 管理员 | `admin` | `admin123` |
|
2. 默认走国内镜像（可用环境变量覆盖）：
|
||||||
| 教师 | `teacher1` | `teacher123` |
|
`ELECTRON_MIRROR=https://cdn.npmmirror.com/binaries/electron/`、
|
||||||
| ClassHelper 班级端（班级） | 班级码 `G101` | `123456` |
|
`ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/`；
|
||||||
|
3. 构建缓存固定到仓库内 `.cache/`，不污染全局目录。
|
||||||
|
|
||||||
- [AGENTS.md](AGENTS.md) —— 工程约定与开发环境注意事项，**改代码前先读它**
|
产物说明：`release/win-unpacked/班级小助手.exe`（约 235MB，Electron 运行时）+ `resources/app.asar`
|
||||||
- [docs/reference.md](docs/reference.md) —— 完整参考（功能行为、接口、验收记录）
|
（约 2.7MB，仅含 `dist/` 与 `package.json`，运行时不需要 node_modules）。
|
||||||
- [docs/dev/architecture.md](docs/dev/architecture.md) —— 架构总览
|
默认使用 Electron 内置图标（未提供 `build/icon.ico`）。
|
||||||
|
|
||||||
## 致谢
|
### 客户端冒烟验证（无需人工点击）
|
||||||
|
|
||||||
灵动岛的视觉与架构参考 [WinIsland](https://github.com/WinIslandProject/WinIsland)（Windows 上的动态岛）；
|
`pnpm verify:desktop` 以 `ELECTRON_SMOKE_TEST=1` 启动应用（不弹窗），主进程依次校验后自动退出：
|
||||||
动效语言取自 [beUI](https://beui.dev)；产品官网的版式参考 [ClassIsland 官网](https://www.classisland.tech/)。
|
|
||||||
三端的深色主题、图标与动效令牌都是照这些参考自己实现的，没有引入它们的运行时依赖。
|
|
||||||
|
|
||||||
<div align="center">
|
| 校验项 | 实测结果 |
|
||||||
|
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
|
| 渲染进程挂载 + 窗口标题 | ✅ `children=1` / `title=班级小助手` |
|
||||||
|
| 登录页渲染（三个输入框） | ✅ 服务器地址 / 用户名 / 密码 |
|
||||||
|
| preload contextBridge 注入 | ✅ 9 个方法（含灵动岛 3 个） |
|
||||||
|
| IPC 往返（getAppInfo/saveConfig） | ✅ Electron 44.3.0 |
|
||||||
|
| 配置文件写入用户目录 | ✅ `%APPDATA%\@classhelper\desktop-client\config.json` |
|
||||||
|
| IndexedDB 缓存读写 | ✅ 读写/统计/删除 + 6 个 store |
|
||||||
|
| 断网时回退本地缓存 | ✅ `fromCache=true`（请求不可达端口） |
|
||||||
|
| 灵动岛窗口创建（置顶/透明/不占任务栏） | ✅ `ready=true` |
|
||||||
|
| 上课期间普通通知自动隐藏 | ✅ `mode=hidden queued=1 visible=false`（窗口真的隐藏，不是只改状态） |
|
||||||
|
| 上课期间点击不展开（严格不显示） | ✅ `mode=hidden visible=false` |
|
||||||
|
| 下课后自动弹出暂存通知详情 | ✅ `mode=expanded reason=after-class` |
|
||||||
|
| 上课期间紧急通知立即展开（无需点击） | ✅ `mode=expanded reason=urgent` |
|
||||||
|
| **紧急通知带展开动画** | ✅ 16ms 采样 34 帧，出现 7 个中间尺寸，最终 `424x344`（窗口从胶囊尺寸弹簧展开） |
|
||||||
|
| 上课期间收起不回缩成胶囊 | ✅ `mode=hidden visible=false` |
|
||||||
|
| **真实通知链路（Socket.IO → 灵动岛）** | ✅ 教师真实发布通知 → 客户端实时通道 → `mode=pill 可见=true 文案="新消息 张老师 · 点击查看"`（用后删除测试通知） |
|
||||||
|
| **普通通知直接显示胶囊（无入场动画）** | ✅ 推送前已隐藏，60ms 内窗口即为 `268x44`、`mode=pill`（无"上岛"动画） |
|
||||||
|
| 胶囊 → 点击 → 展开详情 | ✅ `新消息 · 共 2 条` → `expanded`（含真实 DOM 断言与截图） |
|
||||||
|
| **点击卡片空白处回缩为胶囊** | ✅ 真实点击 `.body` 空白区域 → `mode=pill` |
|
||||||
|
| **点击右上角收起按钮回缩为胶囊** | ✅ 真实点击 `.icon-btn` → `mode=pill` |
|
||||||
|
| **灵动岛截图留档 + 像素级校验** | ✅ 4 张（808×632 / 848×688 / 536×88 / 808×632）；宽高比与状态机配置偏差 **0.000**；形态尺寸递增 pill < expanded < urgent；紧急态偏红 **20584 px**（卡片内部光晕） |
|
||||||
|
| **紧急红晕不外溢（窗口边缘无红光）** | ✅ 截图最外圈（2px）偏红像素 = **0**（守住"卡片周围不出现光晕硬边"） |
|
||||||
|
| 联网集成（`ELECTRON_SMOKE_ONLINE=1`） | ✅ 登录王小明 / 1 班级 / 7 作业 / 20 通知 / 8 成绩 / 第1周30节课 / Socket.IO 已连接 |
|
||||||
|
|
||||||
如果这个项目对你有帮助，欢迎点亮 Star ⭐
|
该验证对**开发产物与打包后的 EXE 都适用**（打包后用 `ELECTRON_SMOKE_RESULT=<file>` 写出 JSON 结果，
|
||||||
|
已实测 `packaged: true`、23/23 通过、退出码 0）。灵动岛各状态的窗口截图会写到
|
||||||
|
`ISLAND_SHOTS_DIR`（默认 `.cache/island-shots/`，仓库内留档目录 `docs/screenshots/island/`），
|
||||||
|
并对尺寸、宽高比、绘制内容（不透明像素/颜色种类）、紧急态红色像素与外溢红光做断言。
|
||||||
|
冒烟进程使用独立 userData（`ELECTRON_SMOKE_PROFILE`），因此**用户开着客户端也能跑验证**。
|
||||||
|
|
||||||
</div>
|
## 上课时段策略（紧急通知二次确认）
|
||||||
|
|
||||||
### 客户端维护
|
"上课时段"由课表实时判定：`GET /api/schedules/current?classId=` 返回
|
||||||
|
`{ inClass, current, next, week, serverTime }`（`at` 参数可覆盖判定时刻，便于联调与测试）。
|
||||||
|
|
||||||
支持远程关机、重启、注销与锁屏（管理端和本机分别确认），可查看最近一次执行结果。
|
**服务端强制拦截**（不是只靠前端提醒）：
|
||||||
统一更新支持立即安装、放学后安装或空闲时安装，支持取消下发。
|
|
||||||
管理员与教师的默认权限组均可自定义；管理员保留权限管理和系统管理入口。
|
```
|
||||||
|
POST /api/notifications { classId, title, content, priority: "URGENT" } → 409 URGENT_DURING_CLASS
|
||||||
|
POST /api/notifications { …, priority: "URGENT", confirmDuringClass: true } → 201
|
||||||
|
POST /api/notifications { …, priority: "NORMAL" }（上课时段） → 201（不受限）
|
||||||
|
```
|
||||||
|
|
||||||
|
409 响应体携带 `details: { classId, current, next, week, serverTime }`，前端据此渲染"正在上的课"。
|
||||||
|
这样即使有人绕过界面直接调接口，也一定会被拦下来。
|
||||||
|
|
||||||
|
**Web 管理端**：教师在通知发布弹窗选择"紧急"并提交时，先查询班级上课状态，命中则弹出**全屏二次确认**
|
||||||
|
（`packages/web-admin/src/components/UrgentClassWarning.vue`）：
|
||||||
|
|
||||||
|
- 全屏遮罩 + 强警示配色，文案"现在为上课时间段……" + 正在上的课时段 + 待发布标题；
|
||||||
|
- 确认按钮带 **3 秒倒计时**（圆环进度 + 每秒钟数提示），倒计时结束前不可点击，防止误触；
|
||||||
|
- 取消则不发；确认后带 `confirmDuringClass: true` 重新提交并成功发布；
|
||||||
|
- 兜底：并发场景（提交瞬间刚好打铃）仍会收到 409，此时同样弹出该警告。
|
||||||
|
|
||||||
|
**EXE 客户端**：上课时段非紧急通知自动隐藏、下课后自动弹出；紧急通知无论是否上课都立即展开（见"灵动岛"一节）。
|
||||||
|
|
||||||
|
回归测试：`verify:e2e` 覆盖 409 拦截 / 二次确认后 201 / 普通通知不受限（用 `at` 固定时刻，结果可复现）；
|
||||||
|
`verify:web` 用真实点击构造"正在上课"场景并断言全屏警告文案、按钮禁用与倒计时时长（实测 ~2.96s）。
|
||||||
|
|
||||||
|
## REST API 一览
|
||||||
|
|
||||||
|
统一响应体：`{ "success": true, "data": {}, "message": "" }`（错误为 `success:false` + `code`）。
|
||||||
|
所有接口前缀 `/api`，除登录外均需 `Authorization: Bearer <token>`。
|
||||||
|
|
||||||
|
| 方法 | 路径 | 权限 | 说明 |
|
||||||
|
| --------------------------- | -------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------- |
|
||||||
|
| POST | `/auth/login` | 公开 | 登录，返回 token + 用户信息 |
|
||||||
|
| GET | `/auth/me` | 登录 | 当前用户（学生附带班级/年级） |
|
||||||
|
| PATCH | `/auth/password` | 登录 | 修改自己的密码 |
|
||||||
|
| POST | `/auth/logout` | 登录 | 退出（无状态，客户端丢弃 token） |
|
||||||
|
| GET | `/classes` | 登录 | 班级列表（按权限收敛） |
|
||||||
|
| GET | `/classes/:id` | 班级可见 | 班级详情（学生/课程/协作教师） |
|
||||||
|
| POST / PATCH / DELETE | `/classes` `/classes/:id` | 教师/管理员 | 班级增删改 |
|
||||||
|
| GET / POST | `/classes/:id/students` | 班级可见 / 可写 | 学生名单 / 添加学生（已存在账号直接转入） |
|
||||||
|
| DELETE | `/classes/:id/students/:userId` | 教师/管理员 | 移出学生 |
|
||||||
|
| POST / DELETE | `/classes/:id/teachers[/:teacherId]` | 教师/管理员 | 分配 / 取消协作教师 |
|
||||||
|
| GET / POST / PATCH / DELETE | `/courses` | 登录 / 教师 | 课程管理 |
|
||||||
|
| GET | `/schedules?classId=&week=&dayOfWeek=` | 登录 | 课表列表（week 过滤周次范围） |
|
||||||
|
| GET | `/schedules/grid?classId=&week=` | 登录 | 周视图（7 列结构，供客户端直接渲染） |
|
||||||
|
| GET | `/schedules/current?classId=&at=` | 登录 | 当前上课状态（`inClass` / `current` / `next`；`at` 为诊断用时间覆盖） |
|
||||||
|
| POST / PATCH / DELETE | `/schedules` | 教师/管理员 | 课表增删改（广播 `schedule:updated`） |
|
||||||
|
| GET | `/homeworks?classId=&courseId=&pendingOnly=&keyword=` | 登录 | 作业列表（学生带完成状态，教师带完成人数） |
|
||||||
|
| GET | `/homeworks/:id` | 班级可见 | 作业详情 |
|
||||||
|
| POST / PATCH / DELETE | `/homeworks` | 教师/管理员 | 发布/修改/删除（广播 `homework:new` / `homework:updated`） |
|
||||||
|
| PATCH | `/homeworks/:id/status` | 登录 | 标记完成/取消（广播 `homework:status`） |
|
||||||
|
| GET | `/notifications?classId=&priority=&unreadOnly=&keyword=` | 登录 | 通知列表（带已读状态） |
|
||||||
|
| GET | `/notifications/unread-count` | 登录 | 未读数（红点） |
|
||||||
|
| POST | `/notifications` | 教师/管理员 | 发布通知（广播 `notification:new`）；上课时段发布紧急通知需 `confirmDuringClass` |
|
||||||
|
| POST | `/notifications/:id/read`、`/notifications/read-all` | 登录 | 标记已读 |
|
||||||
|
| DELETE | `/notifications/:id` | 教师/管理员 | 删除通知 |
|
||||||
|
| GET | `/grades/my` | 登录 | 个人成绩 |
|
||||||
|
| GET | `/grades?classId=&courseId=&userId=&examName=` | 教师/管理员 | 班级成绩 |
|
||||||
|
| GET | `/grades/stats?classId=&courseId=&examName=` | 教师/管理员 | 等级分布 + 各课程平均得分率 |
|
||||||
|
| POST | `/grades`、`/grades/bulk` | 教师/管理员 | 单条 / 批量录入（广播 `grade:updated`） |
|
||||||
|
| PATCH / DELETE | `/grades/:id` | 教师/管理员 | 修改 / 删除成绩 |
|
||||||
|
| GET | `/students?classId=&keyword=` | 教师/管理员 | 学生名单 |
|
||||||
|
| POST / PATCH / DELETE | `/students` | 教师/管理员 | 学生账号增删改 |
|
||||||
|
| POST | `/students/:id/reset-password` | 教师/管理员 | 重置密码 |
|
||||||
|
| GET | `/teachers?keyword=` | 教师/管理员 | 教师列表（分配协作教师用） |
|
||||||
|
| POST | `/teachers` | 管理员 | 新建教师账号 |
|
||||||
|
| GET | `/dashboard/summary` / `/dashboard/term` | 登录 | 仪表盘汇总 / 学期周次 |
|
||||||
|
| GET | `/health` | 公开 | 健康检查（含已挂载模块列表） |
|
||||||
|
|
||||||
|
## WebSocket 事件
|
||||||
|
|
||||||
|
连接方式：`io(url, { auth: { token } })`，握手阶段用 JWT 鉴权。
|
||||||
|
|
||||||
|
| 事件 | 方向 | 载荷 |
|
||||||
|
| ------------------------------------- | --------------- | ------------------------------------- |
|
||||||
|
| `connected` | 服务端 → 客户端 | `{ userId, role, rooms }` |
|
||||||
|
| `notification:new` | 服务端 → 客户端 | `NotificationDto` |
|
||||||
|
| `homework:new` | 服务端 → 客户端 | `HomeworkDto` |
|
||||||
|
| `homework:updated` | 服务端 → 客户端 | `HomeworkDto & { deleted?: boolean }` |
|
||||||
|
| `homework:status` | 服务端 → 客户端 | `HomeworkStatusDto & { classId }` |
|
||||||
|
| `grade:updated` | 服务端 → 客户端 | `GradeDto` |
|
||||||
|
| `schedule:updated` | 服务端 → 客户端 | `{ classId, action, schedule? }` |
|
||||||
|
| `class:updated` | 服务端 → 客户端 | `{ classId, action }` |
|
||||||
|
| `class:join` / `class:leave` / `ping` | 客户端 → 服务端 | 手动订阅班级（服务端二次校验权限） |
|
||||||
|
|
||||||
|
房间规则（`@classhelper/shared` 的 `SOCKET_ROOMS`）：
|
||||||
|
`class:{classId}`、`user:{userId}`、`role:{role}`、`students`、`teachers`。
|
||||||
|
客户端断线由 Socket.IO 自动重连（Web 端 store 与后续 EXE 端共用同一套事件名）。
|
||||||
|
|
||||||
|
## 权限模型（RBAC）
|
||||||
|
|
||||||
|
| 角色 | 可见范围 | 写权限 |
|
||||||
|
| --------- | ------------------------------------------------------------- | --------------------------------------- |
|
||||||
|
| `ADMIN` | 全部班级 | 全部 |
|
||||||
|
| `TEACHER` | 自己创建（`Class.teacherId`）或被分配（`ClassTeacher`）的班级 | 仅上述班级 |
|
||||||
|
| `STUDENT` | 仅自己所在班级（`User.classId` + `Enrollment`） | 无（仅能标记自己的作业状态 / 已读通知） |
|
||||||
|
|
||||||
|
实现要点：
|
||||||
|
|
||||||
|
- `src/middleware/auth.ts`：JWT 校验后会**回查数据库**，班级/角色变更立即生效。
|
||||||
|
- `src/lib/access.ts`：集中实现 `assertClassAccess` / `assertClassWritable` / `resolveClassScope`，
|
||||||
|
列表接口通过 scope 收敛数据（`classId in [...]`），单条接口直接断言。
|
||||||
|
- 越权请求统一返回 `403`，未登录返回 `401`（验收脚本已覆盖 10 项越权场景）。
|
||||||
|
|
||||||
|
## 模块化设计（可随时增删模块）
|
||||||
|
|
||||||
|
后端每个功能是一个独立目录，统一契约 `ApiModule = { name, basePath, router, enabled? }`：
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// packages/server/src/modules/registry.ts
|
||||||
|
export const apiModules: ApiModule[] = [
|
||||||
|
authModule,
|
||||||
|
classesModule,
|
||||||
|
coursesModule,
|
||||||
|
schedulesModule,
|
||||||
|
homeworksModule,
|
||||||
|
notificationsModule,
|
||||||
|
gradesModule,
|
||||||
|
studentsModule,
|
||||||
|
teachersModule, // ← 新增模块只需在这里加一行
|
||||||
|
dashboardModule,
|
||||||
|
].filter((module) => module.enabled !== false);
|
||||||
|
```
|
||||||
|
|
||||||
|
- **新增模块**：新建 `modules/<name>/`（`*.schemas.ts` 校验、`*.service.ts` 业务、`*.module.ts` 路由），
|
||||||
|
在 registry 里加一行即可，`app.ts` 无需改动。
|
||||||
|
- **移除/下线模块**：删掉对应行，或把 `enabled` 置为 `false`，其接口立即从路由表消失。
|
||||||
|
- **实时推送解耦**：业务模块只调用 `realtime/bus.ts` 的 `emitToClass/emitToUser`，
|
||||||
|
不直接依赖 Socket.IO 实例，因此「移除实时通道」不影响业务代码。
|
||||||
|
- **共享契约**：所有 DTO 与类型集中在 `@classhelper/shared`，三端共用，避免契约漂移。
|
||||||
|
|
||||||
|
## 数据库
|
||||||
|
|
||||||
|
- 默认：SQLite（Prisma 7 的 libSQL driver adapter，数据文件 `packages/server/prisma/dev.db`）。
|
||||||
|
- 模型设计为跨库通用（无 enum、无 `@db.*` 原生类型），**切换到 MySQL 只需改 provider + 连接串**。
|
||||||
|
- 完整步骤见 [`docs/mysql.md`](docs/mysql.md)：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pnpm db:switch:mysql
|
||||||
|
pnpm --filter @classhelper/server add @prisma/adapter-mariadb
|
||||||
|
# 修改 packages/server/.env 的 DATABASE_PROVIDER / DATABASE_URL
|
||||||
|
pnpm db:migrate && pnpm db:seed
|
||||||
|
```
|
||||||
|
|
||||||
|
数据库表：`User` / `Class` / `ClassTeacher` / `Enrollment` / `Course` / `Schedule` /
|
||||||
|
`Homework` / `HomeworkStatus` / `Notification` / `NotificationRead` / `Grade`（共 11 张）。
|
||||||
|
|
||||||
|
## 验收标准对照
|
||||||
|
|
||||||
|
| 验收项 | 结果 | 证据 |
|
||||||
|
| ------------------------------------------------ | ---- | -------------------------------------------------------------------------------------------- |
|
||||||
|
| 教师 Web 端发布通知，学生端 5 秒内收到 | ✅ | `verify:e2e`：`notification:new` **37–44ms** |
|
||||||
|
| 教师发布作业，学生能查看并标记完成 | ✅ | `homework:new` **26–40ms**，`PATCH /homeworks/:id/status` 200 且列表回显 `completed=true` |
|
||||||
|
| 教师录入成绩，学生能查看个人成绩 | ✅ | `grade:updated` **21–25ms**，`/grades/my` 返回记录；批量录入与统计接口通过 |
|
||||||
|
| 学生能查看课表，支持按周切换 | ✅ | `/schedules/grid?week=1` 返回 30 节，`week` 过滤 `weekStart ≤ week ≤ weekEnd` |
|
||||||
|
| 断网后客户端可查看缓存数据 | ✅ | 客户端冒烟：`断网时回退到本地缓存 → fromCache=true items=1`；离线横幅 + 缓存统计页可用 |
|
||||||
|
| 权限隔离：学生不能访问其他班级数据 | ✅ | 10 项越权断言全部 403/401（学生跨班/跨班作业/跨班课表、教师跨班发布、未登录访问…） |
|
||||||
|
| 上课时段发布紧急通知必须二次确认 | ✅ | 服务端 409 `URGENT_DURING_CLASS`（`confirmDuringClass` 后 201）；Web 端全屏警告 + 3 秒倒计时 |
|
||||||
|
| 客户端灵动岛：上课隐藏 / 下课弹出 / 紧急立即展开 | ✅ | `verify:desktop` 四种状态断言 + 截图（`.cache/island-shots/`） |
|
||||||
|
| 能成功打包 Windows EXE | ✅ | `班级小助手-0.1.0-x64-setup.exe` / `-portable.exe` / `win-unpacked/*.exe`（见下表） |
|
||||||
|
| 提供完整 README（启动、构建、打包、默认账号） | ✅ | 本文档含快速开始、命令表、API、WebSocket、RBAC、模块化、MySQL 切换、打包与常见问题 |
|
||||||
|
|
||||||
|
打包产物验证（对最终 EXE 实测，非仅开发产物）：
|
||||||
|
|
||||||
|
| 产物 | 大小 | 冒烟结果 |
|
||||||
|
| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
|
||||||
|
| 服务端安装程序（内置 Node + Web 端） | 34MB | ✅ 静默安装（升级保留 `.env` 与数据库）→ 自动建库建号 → 服务就绪 → **对安装实例跑 62/62 e2e + 15/15 UI** |
|
||||||
|
| `release/win-unpacked/班级小助手.exe` | 234.7MB | ✅ 23/23，`packaged: true`，退出码 0 |
|
||||||
|
| `release/…-x64-portable.exe`（单文件） | 106.9MB | ✅ 打包后冒烟 **23/23**，`packaged: true`，退出码 0（含灵动岛行为与像素校验） |
|
||||||
|
| `release/…-x64-setup.exe`（客户端） | 107.2MB | ✅ 构建成功，已嵌入自定义图标；含灵动岛与本次行为修正 |
|
||||||
|
|
||||||
|
当前实测：
|
||||||
|
|
||||||
|
| 验证 | 结果 |
|
||||||
|
| --------------------------------------------------------------------------------------- | ----------------------------------- |
|
||||||
|
| `pnpm verify:e2e`（开发环境与**安装后的生产实例**各跑一次） | **62/62** ✅ |
|
||||||
|
| `pnpm verify:web`（Web 管理端真实点击 + 手机小屏适配 + 上课时段紧急通知 + PWA） | **15/15** ✅ |
|
||||||
|
| `pnpm verify:desktop`（客户端冒烟 + 灵动岛行为 + 真实通知链路 + 像素级校验 + 离线回退） | **27/27** ✅ |
|
||||||
|
| `pnpm typecheck` / `pnpm lint` / `pnpm format:check` | 全部通过 ✅ |
|
||||||
|
| 安装程序完整生命周期（静默安装 → 启停脚本 → 卸载） | 通过 ✅ |
|
||||||
|
| Docker / Nginx 部署样例 | 文件已提供，本机无 Docker 未实测 ⚠️ |
|
||||||
|
|
||||||
|
## 常见问题（本机环境已知坑）
|
||||||
|
|
||||||
|
1. **在 DSH 桌面端（Electron 宿主）里执行 pnpm 时，依赖的 `.bin` 不会被注入 PATH**
|
||||||
|
现象：`pnpm run <script>` 报 `'prisma' 不是内部或外部命令`。
|
||||||
|
原因：本机 pnpm 由 Electron 进程承载，bin 目录位于
|
||||||
|
`node_modules/.pnpm/node_modules/.bin`，未注入子进程 PATH。
|
||||||
|
规避：直接用 Node 调用 CLI 入口，例如
|
||||||
|
`node packages/server/node_modules/prisma/build/index.js generate`、
|
||||||
|
`node packages/web-admin/node_modules/vite/bin/vite.js build`。
|
||||||
|
在普通终端（非 Electron 宿主）中 `pnpm <script>` 一切正常。
|
||||||
|
|
||||||
|
1.5 **脚本里启动 Electron 时必须清掉 `ELECTRON_RUN_AS_NODE`，并且不要 `import 'electron'` 取路径**
|
||||||
|
现象（两种，都只在本机这种"宿主终端本身是 Electron"的环境里出现）：
|
||||||
|
① `node scripts/smoke.mjs` 正常，但 `pnpm verify:desktop` 报
|
||||||
|
`Cannot find module 'electron'`（Electron 退化成纯 Node 运行）；
|
||||||
|
② `pnpm dist:win` 报 `Unknown argument: .../electron-builder/out/cli/cli.js`。
|
||||||
|
原因：本机 `pnpm` 运行在 Electron 内置 Node 上，会给子进程带上 `ELECTRON_RUN_AS_NODE=1`；
|
||||||
|
同时 `process.versions.electron` 存在时，`require('electron')` 返回的是 **API 对象而非可执行文件路径**，
|
||||||
|
`spawn(process.execPath, [cli.js, …])` 会被 Electron 当成"启动应用"而多出一个位置参数。
|
||||||
|
规避（已内置到代码里）：
|
||||||
|
|
||||||
|
- `scripts/lib/electron-env.mjs`：`resolveElectronEnv()` 清理变量、`resolveElectronExecutable()` 从
|
||||||
|
`node_modules/electron/path.txt` 定位 electron.exe；
|
||||||
|
- `scripts/lib/node-runtime.mjs`：`resolveNodeRuntime()` 明确找一个**真正的 node.exe**，
|
||||||
|
供 electron-builder CLI 与"内置 Node 运行时"打包使用。
|
||||||
|
|
||||||
|
2. **不要用 PowerShell 管道调用 `start.cmd`**
|
||||||
|
现象：`& "$install\start.cmd" | Select-Object -First 20` 会一直不返回。
|
||||||
|
原因：脚本内启动的 node 进程在该上下文里继承了管道句柄。
|
||||||
|
规避：双击运行，或用 `Start-Process cmd.exe "/c start.cmd"`（脚本自身 4 秒内退出）。
|
||||||
|
|
||||||
|
3. **原生模块会按 Electron ABI 构建**
|
||||||
|
同一原因会让 `node-gyp` / `prebuild-install` 以 `runtime=electron` 为目标，
|
||||||
|
装出的 `.node` 在 Node 进程里无法加载。本项目因此改用 **libSQL 适配器**
|
||||||
|
（`@libsql/win32-x64-msvc` 为 npm 预编译包，无需本地编译），彻底规避该问题。
|
||||||
|
|
||||||
|
4. **本机 TLS 中间人证书导致依赖二进制下载失败**
|
||||||
|
现象：`prebuild-install warn install unable to verify the first certificate`。
|
||||||
|
规避：安装时设置 `NODE_OPTIONS=--use-system-ca`（Node ≥ 22.15 支持），
|
||||||
|
并确保 `npm_config_cache` 指向可写目录（如仓库内 `.cache/npm-cache`）。
|
||||||
|
|
||||||
|
5. **受限沙箱下 Vite 构建报 `spawn EPERM`**
|
||||||
|
Vite 在 Windows 上通过 `execFile` 解析真实路径，需要放开子进程管道限制后再构建。
|
||||||
|
|
||||||
|
6. **Prisma 7 与旧版本差异**
|
||||||
|
`prisma` 的 npm `latest` 标签当前指向 `8.0.0-rc`，本项目**显式锁定 7.10.0**；
|
||||||
|
生成器为 `prisma-client`（输出到 `src/generated/prisma`，已 gitignore），
|
||||||
|
连接串在 `prisma.config.ts` 中配置，且必须通过 driver adapter 接入数据库。
|
||||||
|
|
||||||
|
7. **Electron 二进制下载慢或失败**
|
||||||
|
`electron` 的 postinstall 会从 GitHub 拉取约 151MB 发行包，本机实测 10 分钟仍未完成。
|
||||||
|
规避：安装前设置镜像与缓存目录（本项目已把 electron 缓存指向 `.cache/electron`）：
|
||||||
|
`ELECTRON_MIRROR=https://cdn.npmmirror.com/binaries/electron/`。
|
||||||
|
打包阶段 `scripts/dist-win.mjs` 已内置该镜像，并优先复用本地已解压的 Electron。
|
||||||
|
|
||||||
|
8. **electron-builder 的构建工具（NSIS / winCodeSign）下载慢**
|
||||||
|
通过 `ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/`
|
||||||
|
解决（已内置到 `dist-win.mjs`），实测 nsis-3.0.4.1 与 nsis-resources 正常下载。
|
||||||
|
`scripts/dist-server.mjs` 会直接复用 electron-builder 缓存里的 `makensis`。
|
||||||
|
|
||||||
|
9. **应用图标**
|
||||||
|
`pnpm icons` 会用 Electron 渲染 SVG 生成 `packages/desktop-client/build/icon.ico`（多尺寸）、
|
||||||
|
PWA 所需的 PNG 与 `favicon.svg`。electron-builder 与 NSIS 安装程序都会自动使用该图标。
|
||||||
|
|
||||||
|
10. **服务端安装包内的 `.cmd` 脚本为什么是英文提示？**
|
||||||
|
cmd.exe 按 OEM 代码页（GBK）解析脚本文件，UTF-8 中文会产生乱码甚至语法错误，
|
||||||
|
因此脚本提示统一用 ASCII，中文说明放在安装向导与 `README.txt` 中。
|
||||||
|
|
||||||
|
## 交付清单（阶段 7 · 生产化）
|
||||||
|
|
||||||
|
| 路径 | 说明 |
|
||||||
|
| --------------------------------------------------- | ---------------------------------------------------------------- |
|
||||||
|
| `scripts/dist-server.mjs` | 服务端 + Web 端打包（内置 Node、依赖、迁移、启停脚本、安装程序） |
|
||||||
|
| `scripts/nsis/server-installer.nsi` | NSIS 安装程序模板（安装/快捷方式/开机自启/卸载保留数据） |
|
||||||
|
| `scripts/generate-icons.mjs` + `scripts/icons/` | 图标生成（Electron 渲染 SVG → PNG/ICO） |
|
||||||
|
| `scripts/ui-smoke/` | Web 管理端 UI 真实点击回归测试 |
|
||||||
|
| `packages/server/src/middleware/security.ts` | helmet + 限流（通用/登录）+ 请求耗时日志 |
|
||||||
|
| `packages/server/src/lib/web-static.ts` | Web 管理端静态托管 + SPA 回退 + 缓存策略 |
|
||||||
|
| `packages/server/src/lib/db-bootstrap.ts` | 首启动自动迁移 + 自动创建管理员 |
|
||||||
|
| `packages/web-admin/public/{manifest,sw.js}` | PWA：可安装为应用 + 离线外壳 |
|
||||||
|
| `deploy/{Dockerfile,docker-compose.yml,nginx.conf}` | 云部署与 HTTPS 反代样例 |
|
||||||
|
| `docs/production.md` | 生产部署指南（三种形态 + 运维 + 安全清单 + 故障排查） |
|
||||||
|
|
||||||
|
阶段 8（灵动岛 + 上课时段策略）新增文件：
|
||||||
|
|
||||||
|
| 路径 | 说明 |
|
||||||
|
| ------------------------------------------------------------ | -------------------------------------------------------------------- |
|
||||||
|
| `packages/desktop-client/src/main/island.ts` | 灵动岛控制器（窗口/状态机/动画/超时/IPC） |
|
||||||
|
| `packages/desktop-client/src/preload/island.ts` | 灵动岛 preload 桥（`islandGetState/islandPush/islandSetClassState`） |
|
||||||
|
| `packages/desktop-client/src/island/IslandApp.vue` | 灵动岛界面（胶囊 / 详情 / 紧急三种形态 + 动画） |
|
||||||
|
| `packages/desktop-client/src/renderer/island/bridge.ts` | 上课状态轮询（10s）与通知转发 |
|
||||||
|
| `packages/server/src/modules/schedules/schedules.service.ts` | `computeClassStatus` / `getClassStatus`（上课时段判定） |
|
||||||
|
| `packages/web-admin/src/components/UrgentClassWarning.vue` | 上课时段发布紧急通知的全屏二次确认（3 秒倒计时） |
|
||||||
|
| `scripts/ui-smoke/live-probe.mjs` | UI 回归测试的"真实上课时段"探针（自建课表 + 用后清理） |
|
||||||
|
| `scripts/lib/{electron-env,node-runtime}.mjs` | Electron/Node 运行时定位与宿主环境兼容处理 |
|
||||||
|
| `docs/screenshots/island/*.png` | 灵动岛四种形态的自动化留档截图（由冒烟验证生成，含像素级断言） |
|
||||||
|
|
||||||
|
## 后续可选增强
|
||||||
|
|
||||||
|
1. 代码签名证书（消除 SmartScreen 提示）。
|
||||||
|
2. 客户端"提交类操作离线队列"（当前离线为只读，联网后自动同步读取的数据）。
|
||||||
|
3. Socket.IO 多实例广播（引入 `@socket.io/redis-adapter`）与 CI 流水线。
|
||||||
|
4. 灵动岛位置/尺寸可配置（多显示器时跟随当前活动屏幕，而非固定主屏）。
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 422 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 49 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 109 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 264 KiB |
+1
-6
@@ -7,7 +7,7 @@
|
|||||||
SERVER_PORT=4000
|
SERVER_PORT=4000
|
||||||
|
|
||||||
# 应用版本（镜像标签）
|
# 应用版本（镜像标签）
|
||||||
APP_VERSION=1.1.2
|
APP_VERSION=0.1.0
|
||||||
|
|
||||||
# MySQL 配置
|
# MySQL 配置
|
||||||
MYSQL_ROOT_PASSWORD=请改成强密码_root
|
MYSQL_ROOT_PASSWORD=请改成强密码_root
|
||||||
@@ -30,11 +30,6 @@ CORS_ORIGIN=*
|
|||||||
INITIAL_ADMIN_USERNAME=admin
|
INITIAL_ADMIN_USERNAME=admin
|
||||||
INITIAL_ADMIN_PASSWORD=admin123
|
INITIAL_ADMIN_PASSWORD=admin123
|
||||||
|
|
||||||
# 各类账号的默认初始密码（新增/重置时使用）
|
|
||||||
|
|
||||||
DEFAULT_CLASS_PASSWORD=123456
|
|
||||||
DEFAULT_TEACHER_PASSWORD=123456
|
|
||||||
|
|
||||||
# 第 1 教学周的周一（用于"当前周次"）
|
# 第 1 教学周的周一（用于"当前周次"）
|
||||||
TERM_START_DATE=2026-08-31
|
TERM_START_DATE=2026-08-31
|
||||||
|
|
||||||
|
|||||||
@@ -1,36 +0,0 @@
|
|||||||
# ---------------------------------------------------------------------------
|
|
||||||
# 班级小助手 · Docker 单容器（SQLite）环境变量
|
|
||||||
# 复制为 deploy/.env.sqlite 后填写：cp deploy/.env.sqlite.example deploy/.env.sqlite
|
|
||||||
# 配合 deploy/docker-compose.sqlite.yml 使用
|
|
||||||
# ---------------------------------------------------------------------------
|
|
||||||
|
|
||||||
# 服务端对外端口（宿主机）。注意与同机其他服务错开：80/443 常被反代占用
|
|
||||||
SERVER_PORT=4000
|
|
||||||
|
|
||||||
# 应用版本（镜像标签）
|
|
||||||
APP_VERSION=1.1.2
|
|
||||||
|
|
||||||
# JWT 签名密钥（必填，必须 ≥32 位；不能包含 secret / change-me 等示例词）
|
|
||||||
# 生成：node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
|
|
||||||
JWT_SECRET=
|
|
||||||
|
|
||||||
# 令牌有效期
|
|
||||||
JWT_EXPIRES_IN=7d
|
|
||||||
|
|
||||||
# 允许的跨域来源；用域名访问时建议写成具体来源，例如 https://class.example.com
|
|
||||||
CORS_ORIGIN=*
|
|
||||||
|
|
||||||
# 首次启动创建的管理员账号（**部署后请立即登录修改密码**）
|
|
||||||
INITIAL_ADMIN_USERNAME=admin
|
|
||||||
INITIAL_ADMIN_PASSWORD=admin123
|
|
||||||
|
|
||||||
# 各类账号的默认初始密码（新增/重置时使用）
|
|
||||||
|
|
||||||
DEFAULT_CLASS_PASSWORD=123456
|
|
||||||
DEFAULT_TEACHER_PASSWORD=123456
|
|
||||||
|
|
||||||
# 第 1 教学周的周一（用于"当前周次"）
|
|
||||||
TERM_START_DATE=2026-08-31
|
|
||||||
|
|
||||||
# 日志级别：debug | info | warn | error
|
|
||||||
LOG_LEVEL=info
|
|
||||||
+3
-8
@@ -1,17 +1,17 @@
|
|||||||
# ClassHelper 服务端 · 生产镜像
|
# 班级小助手服务端 · 生产镜像
|
||||||
#
|
#
|
||||||
# 两阶段构建：
|
# 两阶段构建：
|
||||||
# build —— 安装依赖并编译 shared / server / web-admin
|
# build —— 安装依赖并编译 shared / server / web-admin
|
||||||
# runtime —— 仅保留运行时所需内容（生产依赖 + 构建产物），镜像更小
|
# runtime —— 仅保留运行时所需内容（生产依赖 + 构建产物），镜像更小
|
||||||
#
|
#
|
||||||
# 构建（在仓库根目录执行）：
|
# 构建（在仓库根目录执行）：
|
||||||
# docker build -f deploy/Dockerfile -t classhelper-server:1.1.0 .
|
# docker build -f deploy/Dockerfile -t classhelper-server:0.1.0 .
|
||||||
#
|
#
|
||||||
# 运行（SQLite + 数据卷）：
|
# 运行（SQLite + 数据卷）：
|
||||||
# docker run -d --name classhelper -p 4000:4000 \
|
# docker run -d --name classhelper -p 4000:4000 \
|
||||||
# -e JWT_SECRET=<48字节随机串> \
|
# -e JWT_SECRET=<48字节随机串> \
|
||||||
# -v classhelper-data:/app/data \
|
# -v classhelper-data:/app/data \
|
||||||
# classhelper-server:1.1.0
|
# classhelper-server:0.1.0
|
||||||
#
|
#
|
||||||
# 生产推荐用 docker compose（见 deploy/docker-compose.yml，含 MySQL 与 HTTPS 反代）
|
# 生产推荐用 docker compose（见 deploy/docker-compose.yml，含 MySQL 与 HTTPS 反代）
|
||||||
|
|
||||||
@@ -33,12 +33,7 @@ RUN pnpm install --frozen-lockfile --ignore-scripts
|
|||||||
# 再拷贝源码并构建（只构建服务端与 Web 管理端，桌面客户端不参与）
|
# 再拷贝源码并构建（只构建服务端与 Web 管理端，桌面客户端不参与）
|
||||||
COPY packages ./packages
|
COPY packages ./packages
|
||||||
COPY scripts ./scripts
|
COPY scripts ./scripts
|
||||||
|
|
||||||
# 必须先生成 Prisma Client：`pnpm install --ignore-scripts` 跳过了 postinstall，
|
|
||||||
# 而生成产物 `packages/server/src/generated/prisma` 是 gitignored 的（clone 下来没有），
|
|
||||||
# 少了这一步下面的 tsc 会报 "Cannot find module '../generated/prisma/client.js'"。
|
|
||||||
RUN pnpm build:shared \
|
RUN pnpm build:shared \
|
||||||
&& pnpm --filter @classhelper/server run db:generate \
|
|
||||||
&& pnpm --filter @classhelper/server build \
|
&& pnpm --filter @classhelper/server build \
|
||||||
&& pnpm --filter @classhelper/web-admin build
|
&& pnpm --filter @classhelper/web-admin build
|
||||||
|
|
||||||
|
|||||||
@@ -1,45 +0,0 @@
|
|||||||
# ---------------------------------------------------------------------------
|
|
||||||
# 班级小助手服务端 · Docker 形态镜像（由 install.sh --mode docker 使用）
|
|
||||||
#
|
|
||||||
# 与仓库根 deploy/Dockerfile 的区别：
|
|
||||||
# - 那份是"从源码构建"（两阶段、需要 pnpm 与全量源码），适合开发与自己打包镜像；
|
|
||||||
# - 这份是"从安装包构建"：安装包里的 server/dist、web、node_modules 已经是**linux-x64 的真实目录**，
|
|
||||||
# 所以这里只做 COPY，不需要联网装依赖、不需要构建工具，几十秒就能出镜像。
|
|
||||||
#
|
|
||||||
# 构建（install.sh 自动执行，也可手工）：
|
|
||||||
# docker build -t classhelper-server:1.1.0 -f Dockerfile .
|
|
||||||
# 运行：
|
|
||||||
# docker run -d --name classhelper-server -p 4000:4000 \
|
|
||||||
# --env-file /etc/classhelper/config.env -v classhelper-data:/app/data \
|
|
||||||
# classhelper-server:1.1.0
|
|
||||||
# ---------------------------------------------------------------------------
|
|
||||||
FROM node:22-slim
|
|
||||||
|
|
||||||
ENV NODE_ENV=production \
|
|
||||||
HOST=0.0.0.0 \
|
|
||||||
PORT=4000
|
|
||||||
|
|
||||||
WORKDIR /app
|
|
||||||
|
|
||||||
# 运行时会用到的全部内容（安装包里就是这套布局）
|
|
||||||
COPY package.json ./
|
|
||||||
COPY node_modules ./node_modules
|
|
||||||
COPY server ./server
|
|
||||||
COPY web ./web
|
|
||||||
COPY tools ./tools
|
|
||||||
|
|
||||||
# 数据目录（compose 里挂成卷）
|
|
||||||
RUN mkdir -p /app/data /app/logs
|
|
||||||
|
|
||||||
# 说明：不用 `USER node`
|
|
||||||
# - 镜像只在本机跑，容器本身就是隔离边界；
|
|
||||||
# - 数据卷里的文件需要与宿主机上的 classhelper backup / restore 互通，
|
|
||||||
# 用 root 可以避免 uid 不一致导致的权限问题。
|
|
||||||
|
|
||||||
EXPOSE 4000
|
|
||||||
|
|
||||||
# 健康检查用 Node 自己发请求：slim 镜像里没有 curl/wget
|
|
||||||
HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
|
|
||||||
CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||4000)+'/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
|
|
||||||
|
|
||||||
CMD ["node", "server/dist/index.js"]
|
|
||||||
-1618
File diff suppressed because it is too large.
Load diff
@@ -1,81 +0,0 @@
|
|||||||
# ---------------------------------------------------------------------------
|
|
||||||
# 班级小助手 · 服务端 systemd 单元（Linux）
|
|
||||||
#
|
|
||||||
# 这是**模板**：`deploy/install.sh` 会把占位符替换成真实值后安装到
|
|
||||||
# /etc/systemd/system/classhelper.service。手动部署时照着替换这四处即可：
|
|
||||||
#
|
|
||||||
# __NODE__ Node 可执行文件的绝对路径（内置运行时：<安装目录>/runtime/node/bin/node）
|
|
||||||
# __DIR__ 安装目录（默认 /opt/classhelper）
|
|
||||||
# __USER__ 运行服务的系统用户（默认 classhelper）
|
|
||||||
# __CONFIG__ 环境变量文件（默认 /etc/classhelper/config.env）
|
|
||||||
# __CONFIGDIR__ __CONFIG__ 所在目录（需要写权限，见下面的 ReadWritePaths）
|
|
||||||
#
|
|
||||||
# sudo sed -e 's#__NODE__#/opt/classhelper/runtime/node/bin/node#' \
|
|
||||||
# -e 's#__DIR__#/opt/classhelper#' \
|
|
||||||
# -e 's#__USER__#classhelper#' \
|
|
||||||
# -e 's#__CONFIGDIR__#/etc/classhelper#' \
|
|
||||||
# -e 's#__CONFIG__#/etc/classhelper/config.env#' \
|
|
||||||
# deploy/classhelper.service > /tmp/classhelper.service
|
|
||||||
# sudo install -m 644 /tmp/classhelper.service /etc/systemd/system/classhelper.service
|
|
||||||
# sudo systemctl daemon-reload && sudo systemctl enable --now classhelper
|
|
||||||
#
|
|
||||||
# 常用命令（也有对应的 classhelper 封装）：
|
|
||||||
# classhelper status / start / stop / restart / logs -f
|
|
||||||
# systemctl status classhelper
|
|
||||||
# journalctl -u classhelper -f
|
|
||||||
# ---------------------------------------------------------------------------
|
|
||||||
|
|
||||||
[Unit]
|
|
||||||
Description=ClassHelper Server (班级小助手服务端)
|
|
||||||
Documentation=https://github.com/LoveChengke/ClassHelper
|
|
||||||
After=network-online.target
|
|
||||||
Wants=network-online.target
|
|
||||||
|
|
||||||
[Service]
|
|
||||||
Type=simple
|
|
||||||
User=__USER__
|
|
||||||
Group=__USER__
|
|
||||||
WorkingDirectory=__DIR__
|
|
||||||
|
|
||||||
# 配置从这里注入（唯一的配置真身；安装目录里的 .env 是指向它的软链，见 docs/linux-deploy.md）。
|
|
||||||
# systemd 会剥掉值两侧的引号，所以同一份文件给 dotenv / shell source / systemd 三种读法都能用。
|
|
||||||
# 前面不加 "-"：文件被删掉时直接启动失败，比拿着一份假配置跑起来更容易发现。
|
|
||||||
EnvironmentFile=__CONFIG__
|
|
||||||
ExecStart=__NODE__ server/dist/index.js
|
|
||||||
|
|
||||||
Restart=always
|
|
||||||
RestartSec=3
|
|
||||||
# Socket.IO 长连接较多：提高文件描述符上限
|
|
||||||
LimitNOFILE=65535
|
|
||||||
# 优雅退出：给在途请求与 websocket 收尾时间（index.ts 处理 SIGTERM/SIGINT）
|
|
||||||
KillSignal=SIGTERM
|
|
||||||
TimeoutStopSec=20
|
|
||||||
|
|
||||||
# 日志进 journald：journalctl -u classhelper
|
|
||||||
StandardOutput=journal
|
|
||||||
StandardError=journal
|
|
||||||
SyslogIdentifier=classhelper
|
|
||||||
|
|
||||||
# ---------------------------------------------------------------- 加固
|
|
||||||
# 为什么 ReadWritePaths 要给整个 __DIR__ 与配置目录，而不是只给 data/logs：
|
|
||||||
# 1) Web 端「数据库管理 → 一键切换」会在运行中改写 server/prisma/schema.prisma，
|
|
||||||
# 并把重新生成的 Prisma Client 编译进 server/dist/generated —— 那两处都在 __DIR__ 里；
|
|
||||||
# 2) 同一功能切换成功后要改写 __CONFIG__（DATABASE_PROVIDER / DATABASE_URL 两行）。
|
|
||||||
# ProtectSystem=full 默认把 /etc 与 /usr 设成只读，ReadWritePaths 是官方的"打洞"方式。
|
|
||||||
# 服务本来就以 __USER__ 身份运行，这里给的写权限没有超出它的既有边界。
|
|
||||||
ProtectSystem=full
|
|
||||||
ProtectHome=true
|
|
||||||
PrivateTmp=true
|
|
||||||
NoNewPrivileges=true
|
|
||||||
ReadWritePaths=__DIR__ __CONFIGDIR__
|
|
||||||
|
|
||||||
ProtectKernelTunables=true
|
|
||||||
ProtectKernelModules=true
|
|
||||||
ProtectControlGroups=true
|
|
||||||
RestrictSUIDSGID=true
|
|
||||||
LockPersonality=true
|
|
||||||
# 需要 AF_NETLINK：glibc 解析主机名（MySQL 主机 / GitHub API）时会用到
|
|
||||||
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK
|
|
||||||
|
|
||||||
[Install]
|
|
||||||
WantedBy=multi-user.target
|
|
||||||
@@ -1,56 +0,0 @@
|
|||||||
# ClassHelper · Docker 单容器部署（SQLite + 数据卷）
|
|
||||||
#
|
|
||||||
# 适用：云服务器 / 与别的服务共用一台机器。相比 deploy/docker-compose.yml（MySQL 变体）
|
|
||||||
# 少跑一个数据库容器，内存占用小很多；数据落在 Docker 卷 classhelper-data 里。
|
|
||||||
#
|
|
||||||
# 使用：
|
|
||||||
# 1) cp deploy/.env.sqlite.example deploy/.env.sqlite 并填 JWT_SECRET / 管理员密码
|
|
||||||
# （生成密钥：node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"）
|
|
||||||
# 2) docker compose -f deploy/docker-compose.sqlite.yml --env-file deploy/.env.sqlite up -d --build
|
|
||||||
# 3) 访问：http://<服务器IP>:${SERVER_PORT}/
|
|
||||||
#
|
|
||||||
# 首次启动（AUTO_MIGRATE=true）会自动执行 prisma/migrations 里的建表语句并创建管理员账号，
|
|
||||||
# 见 packages/server/src/lib/db-bootstrap.ts（"Docker 挂载空数据卷"就是它的目标场景之一）。
|
|
||||||
#
|
|
||||||
# 备份：docker run --rm -v classhelper-sqlite_classhelper-data:/data -v "$PWD":/backup alpine \
|
|
||||||
# tar czf /backup/classhelper-db.tar.gz -C /data .
|
|
||||||
|
|
||||||
name: classhelper-sqlite
|
|
||||||
|
|
||||||
services:
|
|
||||||
server:
|
|
||||||
build:
|
|
||||||
context: ..
|
|
||||||
dockerfile: deploy/Dockerfile
|
|
||||||
target: runtime
|
|
||||||
image: classhelper-server:${APP_VERSION:-1.3.3}
|
|
||||||
restart: unless-stopped
|
|
||||||
environment:
|
|
||||||
NODE_ENV: production
|
|
||||||
HOST: 0.0.0.0
|
|
||||||
PORT: 4000
|
|
||||||
DATABASE_PROVIDER: sqlite
|
|
||||||
# 必须写绝对路径：容器里 serverRoot 是 /app/server，相对路径会解析到别处
|
|
||||||
DATABASE_URL: file:/app/data/classhelper.db
|
|
||||||
# 首启动自动建表 + 建管理员；生产自检会拒绝 dev.db 与过短的 JWT_SECRET
|
|
||||||
AUTO_MIGRATE: 'true'
|
|
||||||
STARTUP_DB_CHECK: 'true'
|
|
||||||
JWT_SECRET: ${JWT_SECRET:?请在 deploy/.env.sqlite 中设置（≥32 位随机串）}
|
|
||||||
JWT_EXPIRES_IN: ${JWT_EXPIRES_IN:-7d}
|
|
||||||
CORS_ORIGIN: ${CORS_ORIGIN:-*}
|
|
||||||
TRUST_PROXY: '1'
|
|
||||||
RATE_LIMIT_ENABLED: 'true'
|
|
||||||
LOG_LEVEL: ${LOG_LEVEL:-info}
|
|
||||||
TERM_START_DATE: ${TERM_START_DATE:-}
|
|
||||||
INITIAL_ADMIN_USERNAME: ${INITIAL_ADMIN_USERNAME:-admin}
|
|
||||||
INITIAL_ADMIN_PASSWORD: ${INITIAL_ADMIN_PASSWORD:-admin123}
|
|
||||||
|
|
||||||
DEFAULT_CLASS_PASSWORD: ${DEFAULT_CLASS_PASSWORD:-123456}
|
|
||||||
DEFAULT_TEACHER_PASSWORD: ${DEFAULT_TEACHER_PASSWORD:-123456}
|
|
||||||
ports:
|
|
||||||
- '${SERVER_PORT:-4000}:4000'
|
|
||||||
volumes:
|
|
||||||
- classhelper-data:/app/data
|
|
||||||
|
|
||||||
volumes:
|
|
||||||
classhelper-data:
|
|
||||||
@@ -1,4 +1,4 @@
|
|||||||
# ClassHelper · 生产部署（MySQL + 服务端 + 可选 HTTPS 反代）
|
# 班级小助手 · 生产部署（MySQL + 服务端 + 可选 HTTPS 反代）
|
||||||
#
|
#
|
||||||
# 使用：
|
# 使用：
|
||||||
# 1) 复制环境变量模板并填写密钥：cp deploy/.env.example deploy/.env
|
# 1) 复制环境变量模板并填写密钥：cp deploy/.env.example deploy/.env
|
||||||
@@ -45,7 +45,7 @@ services:
|
|||||||
environment:
|
environment:
|
||||||
DATABASE_PROVIDER: mysql
|
DATABASE_PROVIDER: mysql
|
||||||
DATABASE_URL: mysql://${MYSQL_USER:-classhelper}:${MYSQL_PASSWORD}@db:3306/${MYSQL_DATABASE:-classhelper}
|
DATABASE_URL: mysql://${MYSQL_USER:-classhelper}:${MYSQL_PASSWORD}@db:3306/${MYSQL_DATABASE:-classhelper}
|
||||||
# MySQL 需要 mariadb 驱动适配器（切换数据库时按 docs/management/mysql.md 安装）
|
# MySQL 需要 mariadb 驱动适配器（切换数据库时按 docs/mysql.md 安装）
|
||||||
NODE_ENV: production
|
NODE_ENV: production
|
||||||
command: >
|
command: >
|
||||||
sh -c "pnpm --filter @classhelper/server add @prisma/adapter-mariadb &&
|
sh -c "pnpm --filter @classhelper/server add @prisma/adapter-mariadb &&
|
||||||
@@ -60,7 +60,7 @@ services:
|
|||||||
context: ..
|
context: ..
|
||||||
dockerfile: deploy/Dockerfile
|
dockerfile: deploy/Dockerfile
|
||||||
target: runtime
|
target: runtime
|
||||||
image: classhelper-server:${APP_VERSION:-1.3.3}
|
image: classhelper-server:${APP_VERSION:-0.1.0}
|
||||||
restart: unless-stopped
|
restart: unless-stopped
|
||||||
environment:
|
environment:
|
||||||
NODE_ENV: production
|
NODE_ENV: production
|
||||||
@@ -78,9 +78,6 @@ services:
|
|||||||
TERM_START_DATE: ${TERM_START_DATE:-}
|
TERM_START_DATE: ${TERM_START_DATE:-}
|
||||||
INITIAL_ADMIN_USERNAME: ${INITIAL_ADMIN_USERNAME:-admin}
|
INITIAL_ADMIN_USERNAME: ${INITIAL_ADMIN_USERNAME:-admin}
|
||||||
INITIAL_ADMIN_PASSWORD: ${INITIAL_ADMIN_PASSWORD:-admin123}
|
INITIAL_ADMIN_PASSWORD: ${INITIAL_ADMIN_PASSWORD:-admin123}
|
||||||
|
|
||||||
DEFAULT_CLASS_PASSWORD: ${DEFAULT_CLASS_PASSWORD:-123456}
|
|
||||||
DEFAULT_TEACHER_PASSWORD: ${DEFAULT_TEACHER_PASSWORD:-123456}
|
|
||||||
ports:
|
ports:
|
||||||
- '${SERVER_PORT:-4000}:4000'
|
- '${SERVER_PORT:-4000}:4000'
|
||||||
depends_on:
|
depends_on:
|
||||||
|
|||||||
@@ -1,14 +0,0 @@
|
|||||||
#!/usr/bin/env bash
|
|
||||||
# ---------------------------------------------------------------------------
|
|
||||||
# 兼容壳：早期文档、脚本与 README 里写的是 deploy/install-linux.sh，
|
|
||||||
# 现在安装器统一在 deploy/install.sh（避免两份实现漂移）。
|
|
||||||
#
|
|
||||||
# 两者参数完全一致：
|
|
||||||
# sudo bash deploy/install-linux.sh --port 8080
|
|
||||||
# 等价于
|
|
||||||
# sudo bash deploy/install.sh --port 8080
|
|
||||||
# ---------------------------------------------------------------------------
|
|
||||||
set -euo pipefail
|
|
||||||
DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
||||||
printf '\033[33m[classhelper]\033[0m install-linux.sh 已更名为 install.sh，本次自动转发（后续请直接用 install.sh）\n' >&2
|
|
||||||
exec bash "${DIR}/install.sh" "$@"
|
|
||||||
-1311
File diff suppressed because it is too large.
Load diff
@@ -1,19 +0,0 @@
|
|||||||
# ---------------------------------------------------------------------------
|
|
||||||
# ClassHelper · 日志轮转
|
|
||||||
# 由 deploy/install.sh 安装到 /etc/logrotate.d/classhelper
|
|
||||||
#
|
|
||||||
# copytruncate 而不是 create+信号：安装器与 classhelper 都是"追加写完就关"
|
|
||||||
# （`>>` 打开、写完立即关闭），没有常驻 fd 可通知，copytruncate 是这里唯一正确的做法。
|
|
||||||
# ---------------------------------------------------------------------------
|
|
||||||
|
|
||||||
/var/log/classhelper/*.log {
|
|
||||||
weekly
|
|
||||||
rotate 8
|
|
||||||
missingok
|
|
||||||
notifempty
|
|
||||||
compress
|
|
||||||
delaycompress
|
|
||||||
copytruncate
|
|
||||||
create 0600 root root
|
|
||||||
su root root
|
|
||||||
}
|
|
||||||
@@ -1,13 +1,12 @@
|
|||||||
{
|
{
|
||||||
"name": "classhelper-server-runtime",
|
"name": "classhelper-server-runtime",
|
||||||
"version": "1.3.3",
|
"version": "0.1.0",
|
||||||
"private": true,
|
"private": true,
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"description": "ClassHelper 服务端运行时（安装包 / 容器内置）",
|
"description": "班级小助手服务端运行时（安装包 / 容器内置）",
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@libsql/client": "^0.17.0",
|
"@libsql/client": "^0.17.0",
|
||||||
"@prisma/adapter-libsql": "7.10.0",
|
"@prisma/adapter-libsql": "7.10.0",
|
||||||
"@prisma/adapter-mariadb": "7.10.0",
|
|
||||||
"@prisma/client": "7.10.0",
|
"@prisma/client": "7.10.0",
|
||||||
"bcryptjs": "^3.0.3",
|
"bcryptjs": "^3.0.3",
|
||||||
"compression": "^1.8.2",
|
"compression": "^1.8.2",
|
||||||
@@ -17,10 +16,7 @@
|
|||||||
"express-rate-limit": "^8.7.0",
|
"express-rate-limit": "^8.7.0",
|
||||||
"helmet": "^8.3.0",
|
"helmet": "^8.3.0",
|
||||||
"jsonwebtoken": "^9.0.3",
|
"jsonwebtoken": "^9.0.3",
|
||||||
"prisma": "7.10.0",
|
|
||||||
"socket.io": "^4.8.3",
|
"socket.io": "^4.8.3",
|
||||||
"typescript": "~5.9.3",
|
|
||||||
"xlsx": "0.18.5",
|
|
||||||
"zod": "^4.6.2"
|
"zod": "^4.6.2"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -1,28 +0,0 @@
|
|||||||
# ---------------------------------------------------------------------------
|
|
||||||
# ClassHelper · 登录 shell 环境变量
|
|
||||||
#
|
|
||||||
# 由 deploy/install.sh 安装到 /etc/profile.d/classhelper.sh（占位符替换成真实路径）。
|
|
||||||
# 生效方式：重新登录，或 `source /etc/profile.d/classhelper.sh`。
|
|
||||||
#
|
|
||||||
# 说明：`classhelper` 命令本身装在 /usr/local/bin（软链到 $CLASSHELPER_HOME/bin/classhelper），
|
|
||||||
# 不依赖这个文件也能用；这里提供的是路径类变量，方便写脚本时引用。
|
|
||||||
# ---------------------------------------------------------------------------
|
|
||||||
|
|
||||||
# 只在目录真实存在时导出：卸载后残留的 profile.d 不应该污染别人的环境
|
|
||||||
if [ -d '__DIR__' ]; then
|
|
||||||
export CLASSHELPER_HOME='__DIR__'
|
|
||||||
export CLASSHELPER_CONFIG='__CONFIG__'
|
|
||||||
export CLASSHELPER_LOG_DIR='__LOGDIR__'
|
|
||||||
export CLASSHELPER_BACKUP_DIR='__BACKUPDIR__'
|
|
||||||
export CLASSHELPER_SERVICE='classhelper'
|
|
||||||
|
|
||||||
case ":${PATH}:" in
|
|
||||||
*":${CLASSHELPER_HOME}/bin:"*) ;;
|
|
||||||
*) export PATH="${PATH}:${CLASSHELPER_HOME}/bin" ;;
|
|
||||||
esac
|
|
||||||
fi
|
|
||||||
|
|
||||||
# 让 `classhelper` 在非 root 登录时也能补全（bash 补全由 `classhelper completion bash` 输出）
|
|
||||||
if [ -n "${BASH_VERSION:-}" ] && [ -r /usr/share/bash-completion/completions/classhelper ]; then
|
|
||||||
. /usr/share/bash-completion/completions/classhelper
|
|
||||||
fi
|
|
||||||
@@ -1,22 +0,0 @@
|
|||||||
# ---------------------------------------------------------------------------
|
|
||||||
# 班级小助手 · 定时备份（systemd timer）
|
|
||||||
# 由 `classhelper backup schedule daily|weekly` 安装（占位符 __BIN__ / __KEEP__ 由命令替换）
|
|
||||||
#
|
|
||||||
# 手工安装：
|
|
||||||
# sudo sed -e 's#__BIN__#/usr/local/bin/classhelper#' -e 's#__KEEP__#7#' \
|
|
||||||
# deploy/systemd/classhelper-backup.service > /tmp/x.service ...
|
|
||||||
# 然后 systemctl daemon-reload && systemctl enable --now classhelper-backup.timer
|
|
||||||
# ---------------------------------------------------------------------------
|
|
||||||
|
|
||||||
[Unit]
|
|
||||||
Description=ClassHelper 定时备份
|
|
||||||
Documentation=https://github.com/LoveChengke/ClassHelper
|
|
||||||
After=classhelper.service
|
|
||||||
|
|
||||||
[Service]
|
|
||||||
Type=oneshot
|
|
||||||
ExecStart=__BIN__ backup --quiet --keep __KEEP__
|
|
||||||
# 备份失败时不要静默：journalctl -u classhelper-backup 里能看到退出码与原因
|
|
||||||
StandardOutput=journal
|
|
||||||
StandardError=journal
|
|
||||||
SyslogIdentifier=classhelper-backup
|
|
||||||
@@ -1,19 +0,0 @@
|
|||||||
# ---------------------------------------------------------------------------
|
|
||||||
# 班级小助手 · 定时备份（触发器）
|
|
||||||
# 由 `classhelper backup schedule daily|weekly` 安装；OnCalendar 行由命令按选择替换
|
|
||||||
# ---------------------------------------------------------------------------
|
|
||||||
|
|
||||||
[Unit]
|
|
||||||
Description=ClassHelper 定时备份触发器
|
|
||||||
Documentation=https://github.com/LoveChengke/ClassHelper
|
|
||||||
|
|
||||||
[Timer]
|
|
||||||
OnCalendar=__ONCALENDAR__
|
|
||||||
# 错开整点：避免所有装了本服务的机器在同一秒打盘
|
|
||||||
RandomizedDelaySec=30m
|
|
||||||
# 机器关机期间错过的备份在开机后补一次
|
|
||||||
Persistent=true
|
|
||||||
Unit=classhelper-backup.service
|
|
||||||
|
|
||||||
[Install]
|
|
||||||
WantedBy=timers.target
|
|
||||||
@@ -1,335 +0,0 @@
|
|||||||
#!/usr/bin/env node
|
|
||||||
/**
|
|
||||||
* ClassHelper · 离线账号工具（随 Linux 包发布，安装在 ${INSTALL_DIR}/tools/admin-cli.mjs）
|
|
||||||
*
|
|
||||||
* 为什么不用 HTTP API 改密码：`classhelper password` 要能在**服务停机**时救急，
|
|
||||||
* 而调 API 必须先有一个能登录的账号 —— 管理员忘了密码时就是死锁。
|
|
||||||
* 因此这里直连数据库，复用服务端自己的 Prisma Client 与 bcrypt 参数（`server/dist/lib/*`），
|
|
||||||
* 保证写入的哈希与登录校验用的是同一套实现。
|
|
||||||
*
|
|
||||||
* 安全约定（务必保持）：
|
|
||||||
* - **密码只从 stdin 读**，绝不接受 argv / 环境变量形式的密码（否则会进 shell history 与 ps 输出）；
|
|
||||||
* - 本工具自己**不打印任何密码**，也不写任何日志；
|
|
||||||
* - `dump-hash` 会输出 bcrypt 哈希 —— 仅由 root 调用的 `classhelper password` 用于改前备份，
|
|
||||||
* 调用方负责把结果落到 600 权限的文件里。
|
|
||||||
*
|
|
||||||
* 用法（全部由 classhelper 封装，一般不需要手工调）：
|
|
||||||
* node tools/admin-cli.mjs info
|
|
||||||
* node tools/admin-cli.mjs list [--json]
|
|
||||||
* node tools/admin-cli.mjs dump-hash <用户名|class:班级码>
|
|
||||||
* node tools/admin-cli.mjs set-password <用户名> # 新密码从 stdin 读
|
|
||||||
* node tools/admin-cli.mjs set-class-password <班级码> # 新密码从 stdin 读
|
|
||||||
* node tools/admin-cli.mjs verify <用户名> # 待校验密码从 stdin 读
|
|
||||||
* node tools/admin-cli.mjs restore-hash <备份json路径>
|
|
||||||
* node tools/admin-cli.mjs snapshot <目标db文件> # SQLite 一致性快照（VACUUM INTO）
|
|
||||||
*
|
|
||||||
* 退出码：0 成功 / 1 通用失败 / 2 用法错误 / 3 目标不存在 / 4 密码不合规 / 5 数据库不可用
|
|
||||||
*/
|
|
||||||
import fs from 'node:fs';
|
|
||||||
import path from 'node:path';
|
|
||||||
import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
||||||
|
|
||||||
const scriptDir = path.dirname(fileURLToPath(import.meta.url));
|
|
||||||
/** 安装根目录（tools/ 的上一级） */
|
|
||||||
const installDir = path.resolve(scriptDir, '..');
|
|
||||||
const serverDist = path.join(installDir, 'server', 'dist');
|
|
||||||
|
|
||||||
const EXIT = { OK: 0, FAIL: 1, USAGE: 2, NOT_FOUND: 3, WEAK: 4, NO_DB: 5 };
|
|
||||||
|
|
||||||
function fail(message, code = EXIT.FAIL) {
|
|
||||||
process.stderr.write(`admin-cli: ${message}\n`);
|
|
||||||
process.exitCode = code;
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
|
|
||||||
/** 一次性读完 stdin（去掉行尾换行；保留内部空白，密码里可以有空格） */
|
|
||||||
async function readSecretFromStdin() {
|
|
||||||
const chunks = [];
|
|
||||||
for await (const chunk of process.stdin) chunks.push(chunk);
|
|
||||||
return Buffer.concat(chunks).toString('utf8').replace(/\r?\n$/, '');
|
|
||||||
}
|
|
||||||
|
|
||||||
/** 与服务端一致的密码强度规则（classhelper 里还有一份交互式版本，两边保持同样口径） */
|
|
||||||
function checkStrength(password, username) {
|
|
||||||
const problems = [];
|
|
||||||
if (password.length < 8) problems.push('长度至少 8 位');
|
|
||||||
if (password.length > 128) problems.push('长度不要超过 128 位');
|
|
||||||
const kinds = [/[a-z]/, /[A-Z]/, /[0-9]/, /[^A-Za-z0-9]/].filter((re) => re.test(password)).length;
|
|
||||||
if (kinds < 3) problems.push('需包含小写字母 / 大写字母 / 数字 / 符号 中至少 3 类');
|
|
||||||
if (username && password.toLowerCase() === username.toLowerCase()) problems.push('不能与用户名相同');
|
|
||||||
if (/^(123456|password|admin|classhelper|qwerty|111111|abc123)/i.test(password) && password.length < 12) {
|
|
||||||
problems.push('过于常见，请换一个');
|
|
||||||
}
|
|
||||||
return problems;
|
|
||||||
}
|
|
||||||
|
|
||||||
/** 懒加载服务端模块：先做"库在不在"的检查，避免 libSQL 在连接时凭空建出一个空库 */
|
|
||||||
async function loadServerModules() {
|
|
||||||
const envFile = path.join(serverDist, 'config', 'env.js');
|
|
||||||
if (!fs.existsSync(envFile)) {
|
|
||||||
fail(`找不到服务端产物：${envFile}`, EXIT.NO_DB);
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
const env = await import(pathToFileURL(envFile).href);
|
|
||||||
if (env.env.databaseProvider === 'sqlite') {
|
|
||||||
// classhelper 做备份时会用 CLASSHELPER_SNAPSHOT_DB 显式指定数据文件（跳过硬编码路径假设）
|
|
||||||
const dbFile = process.env.CLASSHELPER_SNAPSHOT_DB || env.env.sqliteFilePath;
|
|
||||||
if (!dbFile || !fs.existsSync(dbFile)) {
|
|
||||||
fail(
|
|
||||||
`数据库文件不存在：${dbFile || '(未配置)'}\n` +
|
|
||||||
' 提示：全新安装请先 systemctl start classhelper 完成建表（AUTO_MIGRATE）；',
|
|
||||||
EXIT.NO_DB,
|
|
||||||
);
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
const db = await import(pathToFileURL(path.join(serverDist, 'lib', 'db.js')).href);
|
|
||||||
const password = await import(pathToFileURL(path.join(serverDist, 'lib', 'password.js')).href);
|
|
||||||
return { env: env.env, prisma: db.prisma, disconnectPrisma: db.disconnectPrisma, ...password };
|
|
||||||
}
|
|
||||||
|
|
||||||
/** 目标账号：普通用户按 username，班级账号按 Class.code（ClassHelper 班级端登录用的是班级码） */
|
|
||||||
async function resolveTarget(prisma, key) {
|
|
||||||
if (key.startsWith('class:')) {
|
|
||||||
const code = key.slice('class:'.length).toUpperCase();
|
|
||||||
const klass = await prisma.class.findUnique({ where: { code } });
|
|
||||||
if (!klass) return { error: `班级码不存在：${code}`, code: EXIT.NOT_FOUND };
|
|
||||||
return { kind: 'class', id: klass.id, label: `班级 ${klass.name}（码 ${klass.code}）`, hash: klass.passwordHash };
|
|
||||||
}
|
|
||||||
const user = await prisma.user.findUnique({ where: { username: key } });
|
|
||||||
if (!user) return { error: `用户名不存在：${key}`, code: EXIT.NOT_FOUND };
|
|
||||||
if (user.role === 'STUDENT') {
|
|
||||||
return {
|
|
||||||
error: `学生没有个人账号（${key} 只是名单记录），ClassHelper 班级端用「班级码 + 班级密码」登录，请用 --class 改班级密码`,
|
|
||||||
code: EXIT.NOT_FOUND,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
return { kind: 'user', id: user.id, label: `${user.name}（${user.username} / ${user.role}）`, hash: user.passwordHash };
|
|
||||||
}
|
|
||||||
|
|
||||||
/* ------------------------------------------------------------------ 子命令 */
|
|
||||||
|
|
||||||
/**
|
|
||||||
* SQLite 一致性快照：`VACUUM INTO` 在服务运行中也能拿到自洽的副本
|
|
||||||
* （直接 cp 数据文件可能抓到写入中的中间状态）。
|
|
||||||
* 目标文件必须不存在 —— 这是 SQLite 的硬要求，先删掉。
|
|
||||||
*/
|
|
||||||
async function cmdSnapshot(modules, dest) {
|
|
||||||
const { env, prisma } = modules;
|
|
||||||
if (env.databaseProvider !== 'sqlite') {
|
|
||||||
return fail('snapshot 只支持 SQLite；MySQL 请用 mysqldump', EXIT.FAIL);
|
|
||||||
}
|
|
||||||
const target = path.resolve(dest);
|
|
||||||
fs.mkdirSync(path.dirname(target), { recursive: true });
|
|
||||||
fs.rmSync(target, { force: true });
|
|
||||||
// VACUUM INTO 不接受参数占位符，只能拼字面量 —— 单引号按 SQL 规则翻倍转义
|
|
||||||
await prisma.$executeRawUnsafe(`VACUUM INTO '${target.replace(/'/g, "''")}'`);
|
|
||||||
if (!fs.existsSync(target)) return fail('快照未生成（VACUUM INTO 未报错但没有产出文件）', EXIT.FAIL);
|
|
||||||
process.stdout.write(`${target}\n`);
|
|
||||||
}
|
|
||||||
|
|
||||||
async function cmdInfo(modules) {
|
|
||||||
const { env, prisma } = modules;
|
|
||||||
const counts = {};
|
|
||||||
for (const model of ['user', 'class', 'course', 'schedule', 'homework', 'notification', 'grade']) {
|
|
||||||
counts[model] = await prisma[model].count();
|
|
||||||
}
|
|
||||||
const payload = {
|
|
||||||
provider: env.databaseProvider,
|
|
||||||
sqliteFile: env.sqliteFilePath || null,
|
|
||||||
serverRoot: env.serverRoot,
|
|
||||||
termStartDate: env.termStartDate || null,
|
|
||||||
counts,
|
|
||||||
};
|
|
||||||
process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
|
|
||||||
}
|
|
||||||
|
|
||||||
async function cmdList(modules, asJson) {
|
|
||||||
const { prisma } = modules;
|
|
||||||
const users = await prisma.user.findMany({
|
|
||||||
where: { role: { in: ['ADMIN', 'TEACHER'] } },
|
|
||||||
select: { username: true, name: true, role: true, classId: true, updatedAt: true },
|
|
||||||
orderBy: [{ role: 'asc' }, { username: 'asc' }],
|
|
||||||
});
|
|
||||||
const classes = await prisma.class.findMany({
|
|
||||||
select: { code: true, name: true, passwordHash: true },
|
|
||||||
orderBy: { code: 'asc' },
|
|
||||||
});
|
|
||||||
|
|
||||||
if (asJson) {
|
|
||||||
process.stdout.write(
|
|
||||||
`${JSON.stringify(
|
|
||||||
{
|
|
||||||
users,
|
|
||||||
classes: classes.map((item) => ({ code: item.code, name: item.name, hasPassword: !!item.passwordHash })),
|
|
||||||
},
|
|
||||||
null,
|
|
||||||
2,
|
|
||||||
)}\n`,
|
|
||||||
);
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
process.stdout.write('可登录账号（教师 / 管理员）：\n');
|
|
||||||
for (const user of users) {
|
|
||||||
process.stdout.write(` ${user.role.padEnd(8)} ${user.username.padEnd(16)} ${user.name}\n`);
|
|
||||||
}
|
|
||||||
process.stdout.write('\n班级账号（ClassHelper 班级端用「班级码 + 班级密码」登录）：\n');
|
|
||||||
for (const item of classes) {
|
|
||||||
const state = item.passwordHash ? '已设置' : '⚠ 未设置密码（该班当前无法登录）';
|
|
||||||
process.stdout.write(` ${item.code.padEnd(8)} ${item.name.padEnd(16)} ${state}\n`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async function cmdDumpHash(modules, key) {
|
|
||||||
const { prisma } = modules;
|
|
||||||
const target = await resolveTarget(prisma, key);
|
|
||||||
if (target.error) return fail(target.error, target.code);
|
|
||||||
if (!target.hash) return fail(`${target.label} 当前没有密码（passwordHash 为空）`, EXIT.NOT_FOUND);
|
|
||||||
// 只给调用方（root）看的原始数据，不落到本工具的日志里
|
|
||||||
process.stdout.write(`${JSON.stringify({ target: key, kind: target.kind, id: target.id, hash: target.hash })}\n`);
|
|
||||||
}
|
|
||||||
|
|
||||||
async function cmdSetPassword(modules, key, readSecret) {
|
|
||||||
const { prisma, hashPassword } = modules;
|
|
||||||
const target = await resolveTarget(prisma, key);
|
|
||||||
if (target.error) return fail(target.error, target.code);
|
|
||||||
|
|
||||||
const secret = await readSecret();
|
|
||||||
const problems = checkStrength(secret, key);
|
|
||||||
if (problems.length > 0) return fail(`密码不合规：${problems.join('；')}`, EXIT.WEAK);
|
|
||||||
|
|
||||||
const hash = await hashPassword(secret);
|
|
||||||
if (target.kind === 'class') {
|
|
||||||
await prisma.class.update({ where: { id: target.id }, data: { passwordHash: hash } });
|
|
||||||
} else {
|
|
||||||
await prisma.user.update({ where: { id: target.id }, data: { passwordHash: hash } });
|
|
||||||
}
|
|
||||||
|
|
||||||
// 写完立刻复核一次：曾经出现过"bcrypt 参数不一致导致写进去的哈希验证不过"的排查成本
|
|
||||||
const ok = await modules.verifyPassword(secret, hash);
|
|
||||||
if (!ok) return fail('写入后复核失败：哈希无法通过校验，请用 restore-hash 回滚', EXIT.FAIL);
|
|
||||||
|
|
||||||
process.stdout.write(`已更新密码：${target.label}\n`);
|
|
||||||
}
|
|
||||||
|
|
||||||
async function cmdVerify(modules, key, readSecret) {
|
|
||||||
const { prisma, verifyPassword } = modules;
|
|
||||||
const target = await resolveTarget(prisma, key);
|
|
||||||
if (target.error) return fail(target.error, target.code);
|
|
||||||
const secret = await readSecret();
|
|
||||||
const ok = !!target.hash && (await verifyPassword(secret, target.hash));
|
|
||||||
process.stdout.write(`${ok ? 'match' : 'mismatch'}\n`);
|
|
||||||
if (!ok) process.exitCode = EXIT.FAIL;
|
|
||||||
}
|
|
||||||
|
|
||||||
async function cmdRestoreHash(modules, backupFile) {
|
|
||||||
const { prisma } = modules;
|
|
||||||
if (!fs.existsSync(backupFile)) return fail(`备份文件不存在：${backupFile}`, EXIT.NOT_FOUND);
|
|
||||||
let payload;
|
|
||||||
try {
|
|
||||||
payload = JSON.parse(fs.readFileSync(backupFile, 'utf8'));
|
|
||||||
} catch (error) {
|
|
||||||
return fail(`备份文件不是合法 JSON：${error.message}`);
|
|
||||||
}
|
|
||||||
const { target, hash } = payload;
|
|
||||||
if (typeof target !== 'string' || typeof hash !== 'string') {
|
|
||||||
return fail('备份文件缺少 target / hash 字段，拒绝回滚');
|
|
||||||
}
|
|
||||||
if (target.startsWith('class:')) {
|
|
||||||
await prisma.class.update({ where: { code: target.slice('class:'.length).toUpperCase() }, data: { passwordHash: hash } });
|
|
||||||
} else {
|
|
||||||
await prisma.user.update({ where: { username: target }, data: { passwordHash: hash } });
|
|
||||||
}
|
|
||||||
process.stdout.write(`已回滚密码哈希：${target}\n`);
|
|
||||||
}
|
|
||||||
|
|
||||||
/* ------------------------------------------------------------------ 入口 */
|
|
||||||
|
|
||||||
const argv = process.argv.slice(2);
|
|
||||||
const command = argv[0] ?? 'help';
|
|
||||||
const args = argv.slice(1);
|
|
||||||
const wantsJson = args.includes('--json');
|
|
||||||
const positional = args.filter((item) => !item.startsWith('--'));
|
|
||||||
|
|
||||||
function usage() {
|
|
||||||
process.stdout.write(
|
|
||||||
[
|
|
||||||
'classhelper 离线账号工具（一般由 classhelper 命令调用）',
|
|
||||||
'',
|
|
||||||
' info 输出数据库与表行数（JSON）',
|
|
||||||
' list [--json] 列出可登录账号与班级账号',
|
|
||||||
' dump-hash <用户名|class:班级码> 输出当前密码哈希（供改密前备份）',
|
|
||||||
' set-password <用户名> 从 stdin 读新密码并写入',
|
|
||||||
' set-class-password <班级码> 从 stdin 读新密码并写入班级账号',
|
|
||||||
' verify <用户名> 从 stdin 读密码，输出 match / mismatch',
|
|
||||||
' restore-hash <备份json路径> 用备份文件里的哈希回滚',
|
|
||||||
' snapshot <目标db文件> 把 SQLite 库一致性快照到指定路径（VACUUM INTO）',
|
|
||||||
'',
|
|
||||||
].join('\n'),
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
if (command === 'help' || command === '--help' || command === '-h') {
|
|
||||||
usage();
|
|
||||||
} else if (
|
|
||||||
![
|
|
||||||
'info',
|
|
||||||
'list',
|
|
||||||
'dump-hash',
|
|
||||||
'set-password',
|
|
||||||
'set-class-password',
|
|
||||||
'verify',
|
|
||||||
'restore-hash',
|
|
||||||
'snapshot',
|
|
||||||
].includes(command)
|
|
||||||
) {
|
|
||||||
fail(`未知子命令：${command}\n`, EXIT.USAGE);
|
|
||||||
usage();
|
|
||||||
} else {
|
|
||||||
const modules = await loadServerModules();
|
|
||||||
if (!modules) {
|
|
||||||
// 已经在 loadServerModules 里设了 exitCode
|
|
||||||
} else {
|
|
||||||
try {
|
|
||||||
switch (command) {
|
|
||||||
case 'info':
|
|
||||||
await cmdInfo(modules);
|
|
||||||
break;
|
|
||||||
case 'list':
|
|
||||||
await cmdList(modules, wantsJson);
|
|
||||||
break;
|
|
||||||
case 'dump-hash':
|
|
||||||
if (!positional[0]) fail('缺少目标账号', EXIT.USAGE);
|
|
||||||
else await cmdDumpHash(modules, positional[0]);
|
|
||||||
break;
|
|
||||||
case 'set-password':
|
|
||||||
case 'set-class-password': {
|
|
||||||
const key = command === 'set-class-password' ? `class:${positional[0] ?? ''}` : (positional[0] ?? '');
|
|
||||||
if (!positional[0]) fail('缺少目标账号', EXIT.USAGE);
|
|
||||||
else await cmdSetPassword(modules, key, readSecretFromStdin);
|
|
||||||
break;
|
|
||||||
}
|
|
||||||
case 'verify':
|
|
||||||
if (!positional[0]) fail('缺少目标账号', EXIT.USAGE);
|
|
||||||
else await cmdVerify(modules, positional[0], readSecretFromStdin);
|
|
||||||
break;
|
|
||||||
case 'restore-hash':
|
|
||||||
if (!positional[0]) fail('缺少备份文件路径', EXIT.USAGE);
|
|
||||||
else await cmdRestoreHash(modules, positional[0]);
|
|
||||||
break;
|
|
||||||
case 'snapshot':
|
|
||||||
if (!positional[0]) fail('缺少目标文件路径', EXIT.USAGE);
|
|
||||||
else await cmdSnapshot(modules, positional[0]);
|
|
||||||
break;
|
|
||||||
default:
|
|
||||||
usage();
|
|
||||||
}
|
|
||||||
} catch (error) {
|
|
||||||
fail(error instanceof Error ? error.message : String(error));
|
|
||||||
} finally {
|
|
||||||
// 不用 process.exit()：在顶层 await 里硬退会踩 libuv 断言（见 AGENTS.md §7）
|
|
||||||
await modules.disconnectPrisma();
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
@@ -1,307 +0,0 @@
|
|||||||
#!/usr/bin/env bash
|
|
||||||
# ---------------------------------------------------------------------------
|
|
||||||
# ClassHelper · Linux 安装与运维链路验收（在**已安装的服务器上**运行）
|
|
||||||
#
|
|
||||||
# 覆盖：安装结果 → 服务可用性 → API 登录 → 改密（含回滚与审计）→ 备份 →
|
|
||||||
# 配置读写 → key rotate →（可选）升级 / 回滚 / 卸载
|
|
||||||
#
|
|
||||||
# 用法（在服务器上，需要 root）：
|
|
||||||
# sudo bash verify-linux.sh # 基础链路
|
|
||||||
# sudo bash verify-linux.sh --full --package /tmp/xxx.tar.gz # 追加升级/回滚
|
|
||||||
# sudo bash verify-linux.sh --admin-password-stdin # 密码从 stdin 读一行（不进 argv/history）
|
|
||||||
#
|
|
||||||
# 说明：
|
|
||||||
# - 本脚本会**真的**改一次管理员密码（换成随机强密码，再改回去），并真的发一条备份；
|
|
||||||
# - 除了 --purge 的卸载测试，不会删除任何数据；
|
|
||||||
# - 全程不需要外网（升级测试用 --package 指向本地包）。
|
|
||||||
# ---------------------------------------------------------------------------
|
|
||||||
set -uo pipefail
|
|
||||||
|
|
||||||
INSTALL_DIR="/opt/classhelper"
|
|
||||||
CONFIG_FILE="/etc/classhelper/config.env"
|
|
||||||
LOG_DIR="/var/log/classhelper"
|
|
||||||
BACKUP_DIR="/var/backups/classhelper"
|
|
||||||
PORT=""
|
|
||||||
ADMIN_USER="admin"
|
|
||||||
ADMIN_PASSWORD=""
|
|
||||||
ADMIN_PASSWORD_FROM_STDIN=0
|
|
||||||
DO_FULL=0
|
|
||||||
PACKAGE=""
|
|
||||||
|
|
||||||
TOTAL=0; PASS=0; FAIL=0
|
|
||||||
FAILED=()
|
|
||||||
|
|
||||||
while [ $# -gt 0 ]; do
|
|
||||||
case "$1" in
|
|
||||||
--dir) INSTALL_DIR="$2"; shift 2 ;;
|
|
||||||
--config) CONFIG_FILE="$2"; shift 2 ;;
|
|
||||||
--port) PORT="$2"; shift 2 ;;
|
|
||||||
--user) ADMIN_USER="$2"; shift 2 ;;
|
|
||||||
--admin-password) ADMIN_PASSWORD="$2"; shift 2 ;;
|
|
||||||
--admin-password-stdin) ADMIN_PASSWORD_FROM_STDIN=1; shift ;;
|
|
||||||
--package) PACKAGE="$2"; shift 2 ;;
|
|
||||||
--full) DO_FULL=1; shift ;;
|
|
||||||
-h|--help) sed -n '2,18p' "$0"; exit 0 ;;
|
|
||||||
*) echo "未知参数：$1" >&2; exit 2 ;;
|
|
||||||
esac
|
|
||||||
done
|
|
||||||
|
|
||||||
if [ -t 1 ]; then G=$'\033[32m'; R=$'\033[31m'; Y=$'\033[33m'; D=$'\033[2m'; B=$'\033[1m'; N=$'\033[0m'; else G=; R=; Y=; D=; B=; N=; fi
|
|
||||||
|
|
||||||
section() { printf '\n%s▶ %s%s\n' "$B" "$1" "$N"; }
|
|
||||||
check() { # $1=描述 $2=0 通过
|
|
||||||
TOTAL=$((TOTAL + 1))
|
|
||||||
if [ "$2" = "0" ]; then
|
|
||||||
PASS=$((PASS + 1)); printf ' %s✔%s %s\n' "$G" "$N" "$1"
|
|
||||||
else
|
|
||||||
FAIL=$((FAIL + 1)); FAILED+=("$1"); printf ' %s✘%s %s\n' "$R" "$N" "$1"
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
note() { printf ' %s· %s%s\n' "$D" "$1" "$N"; }
|
|
||||||
|
|
||||||
[ "$(id -u)" = "0" ] || { echo "请用 root 运行：sudo bash verify-linux.sh" >&2; exit 1; }
|
|
||||||
|
|
||||||
if [ ! -f "$CONFIG_FILE" ]; then
|
|
||||||
echo "找不到安装：${CONFIG_FILE} 不存在（用 --config 指定，或先跑 install.sh）" >&2
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
read_cfg() { sed -n "s/^[[:space:]]*$1=//p" "$CONFIG_FILE" | tail -n 1 | tr -d '"'; }
|
|
||||||
[ -n "$PORT" ] || PORT="$(read_cfg PORT)"
|
|
||||||
[ -n "$PORT" ] || PORT=4000
|
|
||||||
CLASSHELPER="${INSTALL_DIR}/bin/classhelper"
|
|
||||||
API="http://127.0.0.1:${PORT}"
|
|
||||||
CURL=(curl -fsS --noproxy '*')
|
|
||||||
|
|
||||||
if [ "$ADMIN_PASSWORD_FROM_STDIN" = "1" ]; then IFS= read -r ADMIN_PASSWORD || true; fi
|
|
||||||
|
|
||||||
printf '%sClassHelper · Linux 安装验收%s\n' "$B" "$N"
|
|
||||||
note "安装目录 ${INSTALL_DIR}｜配置 ${CONFIG_FILE}｜端口 ${PORT}"
|
|
||||||
|
|
||||||
# ---------------------------------------------------------------- 1. 安装结果
|
|
||||||
|
|
||||||
section "安装结果"
|
|
||||||
check "安装目录存在且含 server/dist/index.js" "$([ -f "${INSTALL_DIR}/server/dist/index.js" ] && echo 0 || echo 1)"
|
|
||||||
check "版本文件 VERSION 可读" "$([ -s "${INSTALL_DIR}/VERSION" ] && echo 0 || echo 1)"
|
|
||||||
check "安装元数据 .installed.json 存在" "$([ -f "${INSTALL_DIR}/.installed.json" ] && echo 0 || echo 1)"
|
|
||||||
|
|
||||||
cfg_mode="$(stat -c '%a' "$CONFIG_FILE" 2>/dev/null || echo '?')"
|
|
||||||
check "配置文件权限 600（实际 ${cfg_mode}）" "$([ "$cfg_mode" = "600" ] && echo 0 || echo 1)"
|
|
||||||
dir_mode="$(stat -c '%a' "$(dirname "$CONFIG_FILE")" 2>/dev/null || echo '?')"
|
|
||||||
check "配置目录权限 700（实际 ${dir_mode}）" "$([ "$dir_mode" = "700" ] && echo 0 || echo 1)"
|
|
||||||
|
|
||||||
env_link="${INSTALL_DIR}/.env"
|
|
||||||
check "安装目录 .env 是指向配置真身的软链（Web 端切库依赖它）" \
|
|
||||||
"$([ -L "$env_link" ] && [ "$(readlink "$env_link")" = "$CONFIG_FILE" ] && echo 0 || echo 1)"
|
|
||||||
|
|
||||||
node_bin="${INSTALL_DIR}/runtime/node/bin/node"
|
|
||||||
node_ver="$([ -x "$node_bin" ] && "$node_bin" -v 2>/dev/null || echo '')"
|
|
||||||
check "内置 Node 可用（${node_ver:-未找到}）" "$([ -n "$node_ver" ] && echo 0 || echo 1)"
|
|
||||||
|
|
||||||
check "classhelper 命令已装到 /usr/local/bin" "$([ -x /usr/local/bin/classhelper ] && echo 0 || echo 1)"
|
|
||||||
check "安装日志 ${LOG_DIR}/install.log 存在" "$([ -s "${LOG_DIR}/install.log" ] && echo 0 || echo 1)"
|
|
||||||
check "审计日志 ${LOG_DIR}/audit.log 存在" "$([ -f "${LOG_DIR}/audit.log" ] && echo 0 || echo 1)"
|
|
||||||
check "审计/安装日志权限不放行他人（≤640）" \
|
|
||||||
"$([ "$(stat -c '%a' "${LOG_DIR}/audit.log" 2>/dev/null || echo 644)" -le 640 ] && echo 0 || echo 1)"
|
|
||||||
check "/etc/profile.d/classhelper.sh 已写入" "$([ -f /etc/profile.d/classhelper.sh ] && echo 0 || echo 1)"
|
|
||||||
profile_home="$(bash -lc 'echo "${CLASSHELPER_HOME:-}"' 2>/dev/null)"
|
|
||||||
check "新登录 shell 里 CLASSHELPER_HOME 生效（${profile_home:-空}）" "$([ -n "$profile_home" ] && echo 0 || echo 1)"
|
|
||||||
|
|
||||||
# ---------------------------------------------------------------- 2. 服务
|
|
||||||
|
|
||||||
section "服务与探针"
|
|
||||||
if command -v systemctl >/dev/null 2>&1 && [ -f /etc/systemd/system/classhelper.service ]; then
|
|
||||||
check "systemd 单元已安装" 0
|
|
||||||
check "服务处于 active" "$(systemctl is-active --quiet classhelper && echo 0 || echo 1)"
|
|
||||||
check "服务开机自启（enabled）" "$(systemctl is-enabled --quiet classhelper 2>/dev/null && echo 0 || echo 1)"
|
|
||||||
else
|
|
||||||
check "systemd 单元已安装" 1
|
|
||||||
fi
|
|
||||||
check "/healthz 返回 200" "$("${CURL[@]}" -o /dev/null "${API}/healthz" 2>/dev/null && echo 0 || echo 1)"
|
|
||||||
|
|
||||||
status_json="$("$CLASSHELPER" status --json 2>/dev/null || true)"
|
|
||||||
check "classhelper status --json 是合法 JSON" "$(printf '%s' "$status_json" | grep -q '"healthy"' && echo 0 || echo 1)"
|
|
||||||
check "status 报告 healthy=yes" "$(printf '%s' "$status_json" | grep -q '"healthy": "yes"' && echo 0 || echo 1)"
|
|
||||||
check "status 报告的端口与实际一致" "$(printf '%s' "$status_json" | grep -q "\"port\": ${PORT}" && echo 0 || echo 1)"
|
|
||||||
check "classhelper help 可执行（非 root 也能看）" "$("$CLASSHELPER" help >/dev/null 2>&1 && echo 0 || echo 1)"
|
|
||||||
check "classhelper completion bash 有输出" "$("$CLASSHELPER" completion bash 2>/dev/null | grep -q 'classhelper' && echo 0 || echo 1)"
|
|
||||||
|
|
||||||
doctor_out="$("$CLASSHELPER" doctor 2>&1 || true)"
|
|
||||||
check "classhelper doctor 无待处理项" "$(printf '%s' "$doctor_out" | grep -q '体检通过' && echo 0 || echo 1)"
|
|
||||||
if ! printf '%s' "$doctor_out" | grep -q '体检通过'; then
|
|
||||||
printf '%s' "$doctor_out" | sed 's/^/ /'
|
|
||||||
fi
|
|
||||||
|
|
||||||
# ---------------------------------------------------------------- 3. API
|
|
||||||
|
|
||||||
section "API 与登录"
|
|
||||||
TOKEN=""
|
|
||||||
login() { # $1=密码 → 输出 token（失败则空）
|
|
||||||
"${CURL[@]}" -X POST "${API}/api/auth/login" -H 'content-type: application/json' \
|
|
||||||
-d "{\"username\":\"${ADMIN_USER}\",\"password\":\"$1\"}" 2>/dev/null \
|
|
||||||
| sed -n 's/.*"token"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p'
|
|
||||||
}
|
|
||||||
|
|
||||||
if [ -z "$ADMIN_PASSWORD" ]; then
|
|
||||||
note "未提供 --admin-password(-stdin)，跳过登录与改密用例"
|
|
||||||
else
|
|
||||||
TOKEN="$(login "$ADMIN_PASSWORD")"
|
|
||||||
check "管理员用提供的密码能登录并拿到 token" "$([ -n "$TOKEN" ] && echo 0 || echo 1)"
|
|
||||||
if [ -n "$TOKEN" ]; then
|
|
||||||
classes="$("${CURL[@]}" -H "Authorization: Bearer ${TOKEN}" "${API}/api/classes" 2>/dev/null || true)"
|
|
||||||
check "带 token 能读业务接口 /api/classes" "$(printf '%s' "$classes" | grep -q '"data"' && echo 0 || echo 1)"
|
|
||||||
me="$("${CURL[@]}" -H "Authorization: Bearer ${TOKEN}" "${API}/api/auth/me" 2>/dev/null || true)"
|
|
||||||
check "/api/auth/me 返回的是 ADMIN" "$(printf '%s' "$me" | grep -q '"ADMIN"' && echo 0 || echo 1)"
|
|
||||||
fi
|
|
||||||
fi
|
|
||||||
|
|
||||||
# ---------------------------------------------------------------- 4. 改密
|
|
||||||
|
|
||||||
if [ -n "$TOKEN" ]; then
|
|
||||||
section "password 子命令（改密 → 回滚 → 审计）"
|
|
||||||
# 生成一个一定满足强度要求的密码（大小写+数字+符号，且不落在常见口令里）
|
|
||||||
GENERATED="Ch$(head -c 12 /dev/urandom | od -An -tx1 | tr -d ' \n')!a9Z"
|
|
||||||
before_count="$(grep -c 'action=password' "${LOG_DIR}/audit.log" 2>/dev/null || echo 0)"
|
|
||||||
|
|
||||||
# 密码经管道进 stdin，不出现在 argv / 环境变量 / shell history
|
|
||||||
out="$(printf '%s\n%s\n' "$GENERATED" "$GENERATED" | "$CLASSHELPER" password "$ADMIN_USER" 2>&1)"
|
|
||||||
check "classhelper password 执行成功" "$(printf '%s' "$out" | grep -q '密码已更新' && echo 0 || echo 1)"
|
|
||||||
|
|
||||||
new_token="$(login "$GENERATED")"
|
|
||||||
check "新密码能登录" "$([ -n "$new_token" ] && echo 0 || echo 1)"
|
|
||||||
old_token="$(login "$ADMIN_PASSWORD")"
|
|
||||||
check "旧密码已失效（登录被拒）" "$([ -z "$old_token" ] && echo 0 || echo 1)"
|
|
||||||
|
|
||||||
hash_backup="$(ls -1t "${BACKUP_DIR}"/password-*.json 2>/dev/null | head -n 1 || true)"
|
|
||||||
check "改密前备份了原哈希（${hash_backup:-无}）" "$([ -n "$hash_backup" ] && echo 0 || echo 1)"
|
|
||||||
check "哈希备份权限 600" \
|
|
||||||
"$([ -n "$hash_backup" ] && [ "$(stat -c '%a' "$hash_backup")" = "600" ] && echo 0 || echo 1)"
|
|
||||||
|
|
||||||
after_count="$(grep -c 'action=password' "${LOG_DIR}/audit.log" 2>/dev/null || echo 0)"
|
|
||||||
check "审计日志新增了 password 记录" "$([ "${after_count:-0}" -gt "${before_count:-0}" ] && echo 0 || echo 1)"
|
|
||||||
check "审计日志里没有新密码明文" "$(grep -q -- "$GENERATED" "${LOG_DIR}/audit.log" 2>/dev/null && echo 1 || echo 0)"
|
|
||||||
check "审计日志里没有原密码明文" "$(grep -q -- "$ADMIN_PASSWORD" "${LOG_DIR}/audit.log" 2>/dev/null && echo 1 || echo 0)"
|
|
||||||
|
|
||||||
# 先把输出收进变量再 grep：`外部命令 | grep -q` 在 `set -o pipefail` 下，grep 命中即退出会让
|
|
||||||
# 写端收到 SIGPIPE（退出码 141），于是"匹配到了"被算成失败
|
|
||||||
weak_out="$(printf 'abc\nabc\n' | "$CLASSHELPER" password "$ADMIN_USER" 2>&1 || true)"
|
|
||||||
check "弱密码被拒绝（长度/种数不足）" "$(printf '%s' "$weak_out" | grep -q '不合规' && echo 0 || echo 1)"
|
|
||||||
check "密码不合规时不会卡死（stdin 结束即退出）" \
|
|
||||||
"$(printf 'abc\n' | timeout 20 "$CLASSHELPER" password "$ADMIN_USER" >/dev/null 2>&1; [ $? -ne 124 ] && echo 0 || echo 1)"
|
|
||||||
list_out="$("$CLASSHELPER" password --list 2>&1 || true)"
|
|
||||||
check "password --list 能列出账号" "$(printf '%s' "$list_out" | grep -q "$ADMIN_USER" && echo 0 || echo 1)"
|
|
||||||
|
|
||||||
# 用改密前保存的哈希把账号恢复原样：比再改一次密码更可靠
|
|
||||||
# （原密码若是 admin123 这类弱口令，改回去会被强度校验挡下 —— 那是产品的正确行为）
|
|
||||||
if [ -n "$hash_backup" ]; then
|
|
||||||
restore_hash_out="$(LOG_LEVEL=error DOTENV_CONFIG_QUIET=true "$node_bin" "${INSTALL_DIR}/tools/admin-cli.mjs" restore-hash "$hash_backup" 2>&1 || true)"
|
|
||||||
check "restore-hash 能把原哈希回滚回来" "$(printf '%s' "$restore_hash_out" | grep -q '已回滚密码哈希' && echo 0 || echo 1)"
|
|
||||||
check "原密码重新可用" "$([ -n "$(login "$ADMIN_PASSWORD")" ] && echo 0 || echo 1)"
|
|
||||||
fi
|
|
||||||
else
|
|
||||||
note "跳过改密用例（没有可用的登录会话）"
|
|
||||||
fi
|
|
||||||
|
|
||||||
# ---------------------------------------------------------------- 5. 备份
|
|
||||||
|
|
||||||
section "backup 子命令"
|
|
||||||
backup_out="$("$CLASSHELPER" backup --keep 5 2>&1)"
|
|
||||||
check "classhelper backup 执行成功" "$(printf '%s' "$backup_out" | grep -q '备份完成' && echo 0 || echo 1)"
|
|
||||||
|
|
||||||
latest="$(ls -1dt "${BACKUP_DIR}"/*/ 2>/dev/null | head -n 1)"
|
|
||||||
check "生成了新的备份目录" "$([ -n "$latest" ] && echo 0 || echo 1)"
|
|
||||||
if [ -n "$latest" ]; then
|
|
||||||
check "备份含 config.env" "$([ -f "${latest}config.env" ] && echo 0 || echo 1)"
|
|
||||||
check "备份 meta.json 带版本号" "$(grep -q '"version"' "${latest}meta.json" 2>/dev/null && echo 0 || echo 1)"
|
|
||||||
db_kind="$(read_cfg DATABASE_PROVIDER)"
|
|
||||||
if [ "$db_kind" = "sqlite" ]; then
|
|
||||||
snap="${latest}classhelper.db"
|
|
||||||
check "备份含 SQLite 快照" "$([ -s "$snap" ] && echo 0 || echo 1)"
|
|
||||||
# 一致性快照必须是完整的 SQLite 文件（VACUUM INTO 产物）
|
|
||||||
check "快照是合法 SQLite 文件（文件头正确）" \
|
|
||||||
"$([ -n "$snap" ] && [ "$(head -c 15 "$snap" 2>/dev/null)" = "SQLite format 3" ] && echo 0 || echo 1)"
|
|
||||||
check "快照权限 600" "$([ -n "$snap" ] && [ "$(stat -c '%a' "$snap")" = "600" ] && echo 0 || echo 1)"
|
|
||||||
else
|
|
||||||
note "数据库是 MySQL，跳过 SQLite 快照用例"
|
|
||||||
fi
|
|
||||||
check "备份目录权限 700" "$([ "$(stat -c '%a' "${latest%/}" 2>/dev/null)" = "700" ] && echo 0 || echo 1)"
|
|
||||||
fi
|
|
||||||
backup_list_out="$("$CLASSHELPER" backup list 2>&1 || true)"
|
|
||||||
check "backup list 能列出备份" "$(printf '%s' "$backup_list_out" | grep -qE '^ [0-9]{8}-' && echo 0 || echo 1)"
|
|
||||||
|
|
||||||
# ---------------------------------------------------------------- 6. 配置
|
|
||||||
|
|
||||||
section "config 子命令"
|
|
||||||
check "config get PORT 返回当前端口" "$([ "$("$CLASSHELPER" config get PORT)" = "$PORT" ] && echo 0 || echo 1)"
|
|
||||||
masked="$("$CLASSHELPER" config show 2>/dev/null | grep '^JWT_SECRET=')"
|
|
||||||
check "config show 对 JWT_SECRET 打码" "$(printf '%s' "$masked" | grep -q '\*\*\*\*' && echo 0 || echo 1)"
|
|
||||||
check "config show 没打印出真实密钥" \
|
|
||||||
"$(secret="$(read_cfg JWT_SECRET)"; [ -n "$secret" ] && printf '%s' "$masked" | grep -q -- "$secret" && echo 1 || echo 0)"
|
|
||||||
|
|
||||||
# 用一个无害的键做读写往返（不重启服务）
|
|
||||||
printf 'CH_VERIFY_PROBE=1\n' >>"$CONFIG_FILE"
|
|
||||||
probe="$("$CLASSHELPER" config get CH_VERIFY_PROBE 2>/dev/null)"
|
|
||||||
check "config get 能读到新增键" "$([ "$probe" = "1" ] && echo 0 || echo 1)"
|
|
||||||
sed -i '/^CH_VERIFY_PROBE=/d' "$CONFIG_FILE"
|
|
||||||
|
|
||||||
# ---------------------------------------------------------------- 7. key rotate
|
|
||||||
|
|
||||||
if [ -n "$TOKEN" ]; then
|
|
||||||
section "key rotate"
|
|
||||||
if [ "${CLASSHELPER_VERIFY_SKIP_KEY_ROTATE:-0}" = "1" ]; then
|
|
||||||
note "按环境变量跳过"
|
|
||||||
else
|
|
||||||
old_secret="$(read_cfg JWT_SECRET)"
|
|
||||||
# key rotate 无 tty 时会问两次（确认轮换、是否现在重启）；只喂一个 yes 的话第二次读到 EOF，
|
|
||||||
# 重启被跳过 —— 新密钥不生效，下面「旧 token 已失效」必然失败。
|
|
||||||
# 用 CLASSHELPER_ASSUME_YES=1 跳过问答并强制重启，语义才是"轮换后旧会话立即失效"。
|
|
||||||
CLASSHELPER_NO_TTY=1 CLASSHELPER_ASSUME_YES=1 "$CLASSHELPER" key rotate >/dev/null 2>&1 || true
|
|
||||||
new_secret="$(read_cfg JWT_SECRET)"
|
|
||||||
check "key rotate 改变了 JWT_SECRET" "$([ -n "$new_secret" ] && [ "$new_secret" != "$old_secret" ] && echo 0 || echo 1)"
|
|
||||||
check "新密钥长度 ≥32" "$([ "${#new_secret}" -ge 32 ] && echo 0 || echo 1)"
|
|
||||||
check "轮换后服务仍可用" "$("${CURL[@]}" -o /dev/null "${API}/healthz" && echo 0 || echo 1)"
|
|
||||||
check "轮换前的 token 已失效（/api/auth/me 返回 401）" \
|
|
||||||
"$(code="$(curl -s --noproxy '*' -o /dev/null -w '%{http_code}' -H "Authorization: Bearer ${TOKEN}" "${API}/api/auth/me")"; [ "$code" = "401" ] && echo 0 || echo 1)"
|
|
||||||
# 轮换后要重新登录，否则后面的用例会带着失效 token 跑
|
|
||||||
TOKEN="$(login "$ADMIN_PASSWORD")"
|
|
||||||
check "轮换后重新登录成功" "$([ -n "$TOKEN" ] && echo 0 || echo 1)"
|
|
||||||
fi
|
|
||||||
fi
|
|
||||||
|
|
||||||
# ---------------------------------------------------------------- 8. 升级 / 回滚
|
|
||||||
|
|
||||||
if [ "$DO_FULL" = "1" ]; then
|
|
||||||
section "upgrade / rollback（--full）"
|
|
||||||
if [ -z "$PACKAGE" ]; then
|
|
||||||
note "未提供 --package，跳过升级用例"
|
|
||||||
else
|
|
||||||
before_version="$("$CLASSHELPER" version 2>/dev/null | awk '{print $2}')"
|
|
||||||
sha="$(sha256sum "$PACKAGE" | awk '{print $1}')"
|
|
||||||
up_out="$("$CLASSHELPER" upgrade --url "$PACKAGE" --sha256 "$sha" --force 2>&1)"
|
|
||||||
check "upgrade 执行成功" "$(printf '%s' "$up_out" | grep -q '升级完成' && echo 0 || echo 1)"
|
|
||||||
check "升级后服务仍就绪" "$("${CURL[@]}" -o /dev/null "${API}/healthz" && echo 0 || echo 1)"
|
|
||||||
check "升级后配置未被改动（JWT_SECRET 保持）" \
|
|
||||||
"$([ "$(read_cfg JWT_SECRET)" = "${new_secret:-$(read_cfg JWT_SECRET)}" ] && echo 0 || echo 1)"
|
|
||||||
check "产生了程序快照（可回滚）" "$(ls -1 "${BACKUP_DIR}/rollback" 2>/dev/null | grep -q . && echo 0 || echo 1)"
|
|
||||||
check "坏包被拒绝（sha256 不匹配时不改动任何文件）" \
|
|
||||||
"$("$CLASSHELPER" upgrade --url "$PACKAGE" --sha256 0000000000000000000000000000000000000000000000000000000000000000 2>&1 | grep -q '校验失败' && echo 0 || echo 1)"
|
|
||||||
check "校验失败后服务仍在运行" "$("${CURL[@]}" -o /dev/null "${API}/healthz" && echo 0 || echo 1)"
|
|
||||||
|
|
||||||
note "（回滚需要交互确认，这里用 yes 管道）"
|
|
||||||
rb_out="$(printf 'yes\n' | "$CLASSHELPER" rollback 2>&1)"
|
|
||||||
check "rollback 执行成功" "$(printf '%s' "$rb_out" | grep -qE '已回滚到|回滚' && echo 0 || echo 1)"
|
|
||||||
check "回滚后服务仍就绪" "$("${CURL[@]}" -o /dev/null "${API}/healthz" && echo 0 || echo 1)"
|
|
||||||
note "升级前版本 ${before_version}｜升级后 $("$CLASSHELPER" version 2>/dev/null | awk '{print $2}')"
|
|
||||||
fi
|
|
||||||
fi
|
|
||||||
|
|
||||||
# ---------------------------------------------------------------- 结果
|
|
||||||
|
|
||||||
printf '\n'
|
|
||||||
if [ "$FAIL" = "0" ]; then
|
|
||||||
printf '%s=== 结果：%s/%s 项通过 ===%s\n' "$G" "$PASS" "$TOTAL" "$N"
|
|
||||||
else
|
|
||||||
printf '%s=== 结果：%s/%s 项通过，%s 项失败 ===%s\n' "$R" "$PASS" "$TOTAL" "$FAIL" "$N"
|
|
||||||
printf '%s失败项：%s\n' "$Y" "$N"
|
|
||||||
for item in "${FAILED[@]}"; do printf ' · %s\n' "$item"; done
|
|
||||||
fi
|
|
||||||
[ "$FAIL" = "0" ] || exit 1
|
|
||||||
-147
@@ -1,147 +0,0 @@
|
|||||||
<!doctype html>
|
|
||||||
<!--
|
|
||||||
404 页 —— 不经过 docfx 模板（它只处理 .md/.yml），由 docs/build.mjs 把 {{BASE}} 换成站点根路径。
|
|
||||||
|
|
||||||
为什么要 <base>：GitHub Pages 的项目页挂在 /<仓库名>/ 子路径下，未知路径返回的是**站点根**的
|
|
||||||
404.html，而浏览器按**被请求的那个路径**解析页面里的相对链接。不钉住 base，访问
|
|
||||||
/classhelper/get-started/typo 时页面上所有链接都会指向 /classhelper/get-started/ 下面的东西。
|
|
||||||
-->
|
|
||||||
<html lang="zh-CN">
|
|
||||||
<head>
|
|
||||||
<meta charset="utf-8" />
|
|
||||||
<base href="{{BASE}}" />
|
|
||||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
||||||
<meta name="robots" content="noindex" />
|
|
||||||
<title>页面不存在 | ClassHelper文档</title>
|
|
||||||
<script>
|
|
||||||
// 与 docfx 主题选择同一套 key（theme 存 light / dark / auto），避免两边主题不一致
|
|
||||||
const theme = localStorage.getItem('theme') || 'auto';
|
|
||||||
document.documentElement.setAttribute(
|
|
||||||
'data-bs-theme',
|
|
||||||
theme === 'auto'
|
|
||||||
? window.matchMedia('(prefers-color-scheme: dark)').matches
|
|
||||||
? 'dark'
|
|
||||||
: 'light'
|
|
||||||
: theme,
|
|
||||||
);
|
|
||||||
</script>
|
|
||||||
<style>
|
|
||||||
:root {
|
|
||||||
--bg: #ffffff;
|
|
||||||
--fg: #1f2328;
|
|
||||||
--muted: #59636e;
|
|
||||||
--line: #d1d9e0;
|
|
||||||
--accent: #0f6cbd;
|
|
||||||
}
|
|
||||||
|
|
||||||
[data-bs-theme='dark'] {
|
|
||||||
--bg: #1b1f24;
|
|
||||||
--fg: #e6edf3;
|
|
||||||
--muted: #9198a1;
|
|
||||||
--line: #30363d;
|
|
||||||
--accent: #6cb8ff;
|
|
||||||
}
|
|
||||||
|
|
||||||
* {
|
|
||||||
box-sizing: border-box;
|
|
||||||
}
|
|
||||||
|
|
||||||
html {
|
|
||||||
color-scheme: light dark;
|
|
||||||
}
|
|
||||||
|
|
||||||
body {
|
|
||||||
margin: 0;
|
|
||||||
min-height: 100vh;
|
|
||||||
display: flex;
|
|
||||||
align-items: center;
|
|
||||||
justify-content: center;
|
|
||||||
padding: 32px;
|
|
||||||
background: var(--bg);
|
|
||||||
color: var(--fg);
|
|
||||||
font-family:
|
|
||||||
'Segoe UI Variable Text',
|
|
||||||
'Segoe UI',
|
|
||||||
'Microsoft YaHei UI',
|
|
||||||
'Microsoft YaHei',
|
|
||||||
-apple-system,
|
|
||||||
BlinkMacSystemFont,
|
|
||||||
'PingFang SC',
|
|
||||||
'Hiragino Sans GB',
|
|
||||||
sans-serif;
|
|
||||||
line-height: 1.7;
|
|
||||||
}
|
|
||||||
|
|
||||||
main {
|
|
||||||
max-width: 34em;
|
|
||||||
}
|
|
||||||
|
|
||||||
.code {
|
|
||||||
font-size: 4.5rem;
|
|
||||||
font-weight: 600;
|
|
||||||
line-height: 1;
|
|
||||||
letter-spacing: -0.02em;
|
|
||||||
color: var(--accent);
|
|
||||||
}
|
|
||||||
|
|
||||||
h1 {
|
|
||||||
margin: 16px 0 8px;
|
|
||||||
font-size: 1.5rem;
|
|
||||||
font-weight: 600;
|
|
||||||
}
|
|
||||||
|
|
||||||
p {
|
|
||||||
margin: 0 0 24px;
|
|
||||||
color: var(--muted);
|
|
||||||
}
|
|
||||||
|
|
||||||
.links {
|
|
||||||
display: flex;
|
|
||||||
flex-wrap: wrap;
|
|
||||||
gap: 10px;
|
|
||||||
}
|
|
||||||
|
|
||||||
a {
|
|
||||||
display: inline-block;
|
|
||||||
padding: 8px 16px;
|
|
||||||
border: 1px solid var(--line);
|
|
||||||
border-radius: 6px;
|
|
||||||
color: var(--fg);
|
|
||||||
text-decoration: none;
|
|
||||||
transition:
|
|
||||||
border-color 0.15s ease,
|
|
||||||
color 0.15s ease;
|
|
||||||
}
|
|
||||||
|
|
||||||
a:hover {
|
|
||||||
border-color: var(--accent);
|
|
||||||
color: var(--accent);
|
|
||||||
}
|
|
||||||
|
|
||||||
a.primary {
|
|
||||||
background: var(--accent);
|
|
||||||
border-color: var(--accent);
|
|
||||||
color: #fff;
|
|
||||||
}
|
|
||||||
|
|
||||||
a.primary:hover {
|
|
||||||
color: #fff;
|
|
||||||
filter: brightness(1.08);
|
|
||||||
}
|
|
||||||
</style>
|
|
||||||
</head>
|
|
||||||
<body>
|
|
||||||
<main>
|
|
||||||
<div class="code">404</div>
|
|
||||||
<h1>这里没有这一页</h1>
|
|
||||||
<p>链接可能过期了，或者这个页面已经被重写进了别的章节。从下面这两处开始找会快一些。</p>
|
|
||||||
<div class="links">
|
|
||||||
<a class="primary" href="index.html">回到首页</a>
|
|
||||||
<a href="get-started/index.html">快速上手</a>
|
|
||||||
<a href="app/index.html">应用帮助</a>
|
|
||||||
<a href="management/index.html">管理运维</a>
|
|
||||||
<a href="dev/index.html">开发文档</a>
|
|
||||||
</div>
|
|
||||||
</main>
|
|
||||||
</body>
|
|
||||||
</html>
|
|
||||||
@@ -1,97 +0,0 @@
|
|||||||
---
|
|
||||||
title: 外观、主题与动效
|
|
||||||
description: 深浅色主题、界面风格、设计令牌与动效语言，以及降低动态效果的降级行为。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 外观、主题与动效
|
|
||||||
|
|
||||||
## 深浅色主题
|
|
||||||
|
|
||||||
**两端都有深色主题，机制完全一致**：在 `<html>` 上挂 `.dark` 类，由各自的样式表覆盖**语义色令牌**，
|
|
||||||
Element Plus 的深色变量提供组件层的默认值。两端的 `main.ts` 都在挂载之前就把主题落好，
|
|
||||||
所以深色用户打开时不会"先白后黑"闪一下。
|
|
||||||
|
|
||||||
| 行为 | 说明 |
|
|
||||||
| ------------ | -------------------------------------------------------- |
|
|
||||||
| 默认 | **跟随系统**（`prefers-color-scheme`，系统改了就跟着变） |
|
|
||||||
| 手动切换之后 | 以用户的选择为准（系统的偏好是默认值，不是命令） |
|
|
||||||
| 切换入口 | 客户端在顶栏（日月按钮），Web 管理端也在顶栏 |
|
|
||||||
| 切换效果 | 从点击位置**扩散的圆**铺满整页换肤 |
|
|
||||||
|
|
||||||
**刻意不随主题的区域**：登录页的深色渐变底、桌面端的启动过渡页与全屏作业看板、灵动岛自身、
|
|
||||||
Web 管理端的侧边栏（本来就是深色），以及深色底上的白色文字。
|
|
||||||
|
|
||||||
Web 端还会同步 `<meta name="theme-color">`，并设 `color-scheme` 让**原生控件**
|
|
||||||
（滚动条、日期选择器弹层、自动填充底色）也跟着走 —— 只改 CSS 变量的话它们会仍是浅色。
|
|
||||||
|
|
||||||
## 语义色令牌
|
|
||||||
|
|
||||||
组件里**一律引用令牌，不写死颜色**：
|
|
||||||
|
|
||||||
| 令牌 | 用途 |
|
|
||||||
| ------------------------------------------------------ | -------- |
|
|
||||||
| `--ch-surface` / `-alt` / `-sunken` / `-hover` | 各种表面 |
|
|
||||||
| `--ch-text` / `-secondary` / `-muted` / `-placeholder` | 文字层级 |
|
|
||||||
| `--ch-radius-xl / lg / md / sm / pill` | 圆角 |
|
|
||||||
| `--ch-shadow-sm` / `-md` | 投影 |
|
|
||||||
|
|
||||||
`html.dark` **只覆盖颜色，绝不覆盖圆角与动效令牌** —— 两套主题的几何必须完全一致，
|
|
||||||
否则切换时会看到布局跳一下。
|
|
||||||
|
|
||||||
> 改令牌时**只改值**，不要对样式表跑批量替换。"把 `#303133` 全量替换成 `var(--ch-text)`"
|
|
||||||
> 会把令牌**定义本身**也换掉，自定义属性一旦自引用就整条失效、解析成空串，
|
|
||||||
> 全站文字颜色静默回落成继承色。
|
|
||||||
|
|
||||||
## 界面风格
|
|
||||||
|
|
||||||
- 浅色底 `#f3f3f3` + 半透明卡片（`rgba(255,255,255,.7)` + `backdrop-filter: blur(20px)`）；
|
|
||||||
- 强调色 `#0F6CBD`（悬停 `#115EA3`）；选中的导航项 = 强调色淡底 + 左侧 3px 强调条；
|
|
||||||
- 圆角统一：卡片 8px / 控件 4px；描边用半透明黑代替灰线；阴影极轻；
|
|
||||||
- 字体 `Segoe UI Variable / 微软雅黑 UI`；Element Plus 的变量整体对齐这套规范。
|
|
||||||
|
|
||||||
Web 管理端走的是另一套（1Panel 风格：深色侧边栏 + 白色圆角卡片），
|
|
||||||
圆角与投影集中定义在它的 `:root` 令牌里。
|
|
||||||
|
|
||||||
## 动效语言
|
|
||||||
|
|
||||||
两端的动画与过渡统一走一套自研的动效语言，**移植自 [beUI](https://beui.dev) 的 `lib/ease.ts`**。
|
|
||||||
beUI 的组件本身是 React，用不到这里，但它的动效语言与框架无关。
|
|
||||||
|
|
||||||
- **令牌单一来源**：`packages/shared/src/motion.ts`。三组缓动曲线 + 六组具名弹簧；
|
|
||||||
- **弹簧由数值积分算出落定时间**，再生成 CSS `linear()` 缓动字面量 ——
|
|
||||||
于是弹簧可以纯 CSS 驱动，不必给每个组件挂一个 rAF 循环；
|
|
||||||
- **运行时注入**：两端在挂载前把令牌写进 `:root` 的自定义属性。CSS 里只引用变量，不抄数值。
|
|
||||||
|
|
||||||
落地到界面上的效果：
|
|
||||||
|
|
||||||
| 位置 | 动效 |
|
|
||||||
| --------------------- | ------------------------------------------------------------------ |
|
|
||||||
| Element Plus 全站过渡 | 时长收紧到 200 / 140ms，缓动换成 EASE_OUT |
|
|
||||||
| 弹窗 / 抽屉 / 浮层 | 走弹簧；**退出一律比入场快**（用户已经决定关掉它了） |
|
|
||||||
| 按钮 | 按下 90ms 直落（跟手）、抬起弹回 |
|
|
||||||
| 侧栏激活项 | 单个"底片"在菜单项之间滑过去，取代"每项各画一块底色" |
|
|
||||||
| 页面内容 | 按块错峰浮现（30ms 一档，封顶 180ms） |
|
|
||||||
| 统计数字 | 0 → 实际值滚动 |
|
|
||||||
| 灵动岛 | **刻意只有单调缓动，不用弹簧**（任何过冲都会让"开合"看起来在震动） |
|
|
||||||
|
|
||||||
### 降低动态效果
|
|
||||||
|
|
||||||
两端各有一个 `prefers-reduced-motion` 的全局降级块，把动画压到 1ms ——
|
|
||||||
**是压短而不是删掉**（`transition: none` 会让依赖 `transitionend` 的逻辑失灵）。
|
|
||||||
|
|
||||||
唯一的例外是**加载指示旋**：它是放慢而不是停，停掉会让界面看起来像卡死。
|
|
||||||
|
|
||||||
## 客户端设置页
|
|
||||||
|
|
||||||
「设置」是一个可展开的分组，六个子页各有自己的路由：
|
|
||||||
|
|
||||||
| 子页 | 内容 |
|
|
||||||
| ------ | ----------------------------------------------------------------------------- |
|
|
||||||
| 通用 | 服务器连接、离线缓存、作业录入短语、使用引导 |
|
|
||||||
| 外观 | 浅色 / 深色 |
|
|
||||||
| 灵动岛 | 尺寸、字号、主题色、视觉风格、停靠、边距、空闲细缝（详见[灵动岛](island.md)） |
|
|
||||||
| 提醒 | 通知显示在哪一端 |
|
|
||||||
| 账号 | 当前班级信息、退出登录 |
|
|
||||||
| 关于 | 版本 / Electron / Chromium / Node、诊断信息、检查更新、鸣谢 |
|
|
||||||
|
|
||||||
`/settings` 会自动跳到「通用」。设置页的改动会**立刻生效并写进本机配置**，重启后仍保留。
|
|
||||||
@@ -1,56 +0,0 @@
|
|||||||
---
|
|
||||||
title: 叫人
|
|
||||||
description: 老师点名让学生过来：普通与紧急两档、快捷短语、谁能叫谁，以及它在教室里的表现。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 叫人
|
|
||||||
|
|
||||||
「叫人」是老师点名让某位同学来一趟 —— 它**不是**一条普通通知，因为它有一个明确的收件人和一个明确的动作
|
|
||||||
（学生会点「收到」）。
|
|
||||||
|
|
||||||
## 在哪发
|
|
||||||
|
|
||||||
| 入口 | 谁能用 |
|
|
||||||
| --------------- | ------------ |
|
|
||||||
| 通知发布 → 叫人 | 教师、管理员 |
|
|
||||||
| 学生管理 → 叫人 | 管理员 |
|
|
||||||
|
|
||||||
学生管理页是管理员专属，但班主任与科任老师同样需要叫人，所以给老师留的入口在「通知发布 → 叫人」。
|
|
||||||
|
|
||||||
## 两档
|
|
||||||
|
|
||||||
| 级别 | 落库级别 | ClassHelper 班级端行为 |
|
|
||||||
| ------------ | -------- | ----------------------------------------------------------------------------------------------------- |
|
|
||||||
| **普通叫人** | `HIGH` | 课间先显示「叫人」胶囊，点击展开；**上课时段只进队列、不打断课堂**，下课后自动弹出详情（90 秒后收起） |
|
|
||||||
| **紧急叫人** | `URGENT` | **无视上课时段立即展开**，上课时被收起后仍保留胶囊、可再次点开 |
|
|
||||||
|
|
||||||
两档的卡片都是「请 XXX 同学找 XXX 老师」+ 具体事由，徽标是「叫人」，按钮是「收到」
|
|
||||||
（复用通知的已读机制）。
|
|
||||||
|
|
||||||
> **是否立即展开只由 `priority` 决定**，与普通通知共用同一条排队 / 隐藏 / 下课弹出路径。
|
|
||||||
|
|
||||||
## 怎么说
|
|
||||||
|
|
||||||
两种输入方式，**自定义消息优先于快捷短语**：
|
|
||||||
|
|
||||||
- **快捷短语**（8 条，点击选中、再点取消）：请到办公室找我 / 请到讲台找我 / 请到实验室找我 /
|
|
||||||
请到门卫处找我 / 请带上作业本找我 / 请带上试卷找我 / 请到教室门口等我 / 请马上来一趟；
|
|
||||||
- **自定义消息**：最长 200 字，例如「带上昨天的数学作业到办公室」。
|
|
||||||
|
|
||||||
## 谁能叫谁
|
|
||||||
|
|
||||||
| 角色 | 限制 |
|
|
||||||
| ------ | ---------------------------------------------------------- |
|
|
||||||
| 学生 | 调用被拒（403） |
|
|
||||||
| 教师 | 只能叫**自己班级**的学生；跨班、或学生不在本班 → 400 / 403 |
|
|
||||||
| 管理员 | 任意班级 |
|
|
||||||
|
|
||||||
## 服务端做了什么
|
|
||||||
|
|
||||||
`POST /api/calls`（教师 / 管理员）→ `urgent: true` 落库成 `URGENT`，否则 `HIGH`，
|
|
||||||
然后广播两个事件：
|
|
||||||
|
|
||||||
- `notification:new` 到班级房间（通知中心与灵动岛都靠它）；
|
|
||||||
- `call:new` 定向到被叫学生 / 班级设备。
|
|
||||||
|
|
||||||
叫人通过实时通道送达本班客户端与灵动岛。
|
|
||||||
@@ -1,98 +0,0 @@
|
|||||||
---
|
|
||||||
title: 班级、学生与教师
|
|
||||||
description: 班级账号、学生名单、班主任与各科任课老师，以及"谁能看什么、谁能改什么"。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 班级、学生与教师
|
|
||||||
|
|
||||||
## 班级账号：ClassHelper 班级端的身份
|
|
||||||
|
|
||||||
学生**没有个人账号**。一台教室机器用一个**班级账号**登录：
|
|
||||||
|
|
||||||
```
|
|
||||||
班级码（例如 G203） + 班级密码 → 这台机器代表"高二(3)班"
|
|
||||||
```
|
|
||||||
|
|
||||||
登录之后，这台机器上的「已读 / 完成 / 未交」都是**代全班**操作的；它看到的是本班的数据。
|
|
||||||
|
|
||||||
班级码是管理员在「班级管理」里设的（新建时自动生成，可以改成好记的）。
|
|
||||||
校验时会统一按大写比对（码存大写）。
|
|
||||||
|
|
||||||
> 班级密码在新建班级时由 `.env` 的 `DEFAULT_CLASS_PASSWORD` 决定初始值，
|
|
||||||
> 之后由管理员在「班级管理 → 修改班级账号」维护。
|
|
||||||
>
|
|
||||||
> **客户端没有改密码入口**，这是刻意移除的：教室机器上误改班级密码会让别的机器登录不了。
|
|
||||||
> 教师 / 管理员本人改密码在 Web 端顶栏头像菜单里。
|
|
||||||
|
|
||||||
## 学生
|
|
||||||
|
|
||||||
**学生管理**（仅管理员）→ 新建 / 导入名单。
|
|
||||||
|
|
||||||
学生记录**只是名单**：成绩、未交名单、叫人、已读记录都按名单记录，所以名单不全这几项就不准。
|
|
||||||
|
|
||||||
| 项目 | 说明 |
|
|
||||||
| -------- | ------------------------------------------------------------------------------------ |
|
|
||||||
| 用户名 | `^[A-Za-z0-9_.-]{3,32}$`；单个新建时自动生成 |
|
|
||||||
| 密码 | **没有密码概念**。学生的 `passwordHash` 是空串占位，不能登录，也没有任何重置密码接口 |
|
|
||||||
| 所属班级 | 一个学生属于一个主班级 |
|
|
||||||
|
|
||||||
> 学生**不是账号**（`Student` 表里没有密码、没有角色），拿学号去登录只会得到 401 ——
|
|
||||||
> 否则"密码错(401)"和"密码对但学生账号已停用(403)"的差异会把学生账号密码变成可离线验证的预言机。
|
|
||||||
|
|
||||||
## 教师
|
|
||||||
|
|
||||||
| 能力 | 在哪 | 谁能做 |
|
|
||||||
| -------------------- | ------------------------------------------------ | ------------- |
|
|
||||||
| 新建 / 编辑 / 删除 | 「教师管理」 | **仅管理员** |
|
|
||||||
| 导入名单（xlsx/csv） | 「教师管理 → 导入名单」 | **仅管理员** |
|
|
||||||
| 重置密码 | 「教师管理」（可指定新密码，留空用默认初始密码） | **仅管理员** |
|
|
||||||
| 加进某个班 | 班级详情 → 任课老师（班级 + 科目 + 教师） | 管理员 |
|
|
||||||
| 换班主任 | 班级详情顶部「更换班主任」 | **仅管理员** |
|
|
||||||
|
|
||||||
> **教师录入只有管理员能做**：`/api/teachers` 整组接口都是 `requireRole('ADMIN')`，教师调用返回 403。
|
|
||||||
> 前端也只在管理员登录时显示这个菜单项。
|
|
||||||
|
|
||||||
### 删除教师有护栏
|
|
||||||
|
|
||||||
下面四种情况一律拒绝（409），因为删账号会级联删掉他在各班发过的内容：
|
|
||||||
|
|
||||||
1. 他还是某个班的**班主任**；
|
|
||||||
2. 名下有**课程**；
|
|
||||||
3. 有**任课关系**（`Course.teacherId === 他`）；
|
|
||||||
4. **发布过作业或通知**。
|
|
||||||
|
|
||||||
（后两项曾经漏检，会静默删掉该教师发过的作业与通知。）
|
|
||||||
|
|
||||||
## 角色与可见范围
|
|
||||||
|
|
||||||
班级内的角色由「账号角色 + 与该班级的关系」共同决定：
|
|
||||||
|
|
||||||
| 角色 | 怎么判定 | 可见范围 |
|
|
||||||
| ------------------ | ------------------------------ | -------------------------- |
|
|
||||||
| `ADMIN` 管理员 | `User.role = ADMIN` | 全部班级 |
|
|
||||||
| 班主任 `HEAD` | `Class.teacherId === 当前用户` | 本班 |
|
|
||||||
| 科任老师 `SUBJECT` | 该班 `Course.teacherId` 有当前用户 | 被任课的班级 |
|
|
||||||
| 学生 `STUDENT` | `User.classId` / 班级账号 | 自己的班级（只读业务数据） |
|
|
||||||
|
|
||||||
### 权限矩阵（摘要）
|
|
||||||
|
|
||||||
| 操作 | 管理员 | 班主任 | 科任老师 |
|
|
||||||
| ------------------------------------ | :----: | :----------: | :------: |
|
|
||||||
| 班级创建 / 修改 / 删除 | ✅ | ❌ | ❌ |
|
|
||||||
| 分配班主任与科任老师 | ✅ | ❌ | ❌ |
|
|
||||||
| 学生名单管理（增删 / 导入） | ✅ | ❌ | ❌ |
|
|
||||||
| 教师录入（新建 / 导入 / 改密码） | ✅ | ❌ | ❌ |
|
|
||||||
| 数据库管理（备份 / 导入导出 / 切换） | ✅ | ❌ | ❌ |
|
|
||||||
| 课表管理（增删改 / 导入） | ✅ | ✅（仅本班） | ❌ |
|
|
||||||
| 布置作业 | ✅ | ✅ | ✅ |
|
|
||||||
| 叫人 | ✅ | ✅ | ✅ |
|
|
||||||
| 发布通知 | ✅ | ✅ | ✅ |
|
|
||||||
| 成绩录入 / 修改 / 导入（仅本班） | ✅ | ✅（仅本班） | ❌ |
|
|
||||||
| 维护班级密码 | ✅ | ❌ | ❌ |
|
|
||||||
|
|
||||||
完整矩阵与实现见[角色与权限](../dev/permissions.md)。
|
|
||||||
|
|
||||||
## 学期周数
|
|
||||||
|
|
||||||
每个班有自己的学期周数（`Class.termWeeks`，默认 20，上限 30），**只有管理员**能改。
|
|
||||||
它决定"现在是第几教学周"，见[课表](schedules.md)。
|
|
||||||
@@ -1,56 +0,0 @@
|
|||||||
---
|
|
||||||
title: 成绩
|
|
||||||
description: 成绩录入与导入、等级与得分率、ClassHelper 班级端看到的全班总览。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 成绩
|
|
||||||
|
|
||||||
## 三种录入方式
|
|
||||||
|
|
||||||
Web 管理端「成绩录入」页：
|
|
||||||
|
|
||||||
| 方式 | 适合 | 说明 |
|
|
||||||
| -------- | --------------------------------- | ---------------------------------------------------------------- |
|
|
||||||
| 单条录入 | 个别缺漏补录 | 选学生、科目、考试名称、分数、总分 |
|
|
||||||
| 批量录入 | 一次录一个班的某一科 | 一屏列出全班学生，逐个填分 |
|
|
||||||
| 导入表格 | 已经有 Excel 的（期中期末最常见） | 支持列名同义词映射、先预览再提交，见[表格与课表导入](imports.md) |
|
|
||||||
|
|
||||||
**科目**下拉是全校统一的 18 科目录；选中一个该班还没有的科目时，前端会自动为该班建同名课程，
|
|
||||||
不用先去把科目建一遍。
|
|
||||||
|
|
||||||
## 谁能录
|
|
||||||
|
|
||||||
| 角色 | 权限 |
|
|
||||||
| --------------- | -------------------------------------- |
|
|
||||||
| 管理员 | ✅ 全部班级 |
|
|
||||||
| **本班班主任** | ✅ 仅本班（录入 / 修改 / 删除 / 导入） |
|
|
||||||
| 科任老师 | ❌ 403 |
|
|
||||||
| 学生 / 班级账号 | ❌ 只能看 |
|
|
||||||
|
|
||||||
权限在**服务层**兜底，前端只是按同一份矩阵隐藏按钮。
|
|
||||||
|
|
||||||
## 学生看到的是什么
|
|
||||||
|
|
||||||
ClassHelper 班级端（教室机器）用的是**班级账号**，所以它看到的不是"我的成绩"，而是**全班成绩总览**：
|
|
||||||
|
|
||||||
- 表格：分数 / **得分率** / **等级**；
|
|
||||||
- 柱状图；
|
|
||||||
- 等级分布；
|
|
||||||
- 最近更新。
|
|
||||||
|
|
||||||
图表是自研的轻量组件（柱状图是纯 HTML/CSS，折线图是 SVG），项目里**不引图表库**。
|
|
||||||
|
|
||||||
> 学生没有个人账号，所以系统里不存在"某个学生登录后看自己的成绩"这条路径。
|
|
||||||
> 成绩记录本身是按学生名单存的（`Grade.userId`），只是入口统一在班级账号上。
|
|
||||||
|
|
||||||
## 接口
|
|
||||||
|
|
||||||
| 方法 | 路径 | 权限 |
|
|
||||||
| -------------- | ---------------------------------------------- | --------------------------- |
|
|
||||||
| GET | `/grades/my` | 登录（班级会话 → 全班总览） |
|
|
||||||
| GET | `/grades?classId=&courseId=&userId=&examName=` | 教师 / 管理员 |
|
|
||||||
| GET | `/grades/stats?classId=&courseId=&examName=` | 教师 / 管理员 |
|
|
||||||
| POST | `/grades`、`/grades/bulk` | 班主任 / 管理员 |
|
|
||||||
| PATCH / DELETE | `/grades/:id` | 班主任 / 管理员 |
|
|
||||||
|
|
||||||
写入后会广播 `grade:updated`，客户端立刻刷新。
|
|
||||||
@@ -1,92 +0,0 @@
|
|||||||
---
|
|
||||||
title: 作业
|
|
||||||
description: 作业按所属日期归类、看板与全屏看板、教室机器录入作业、未交名单与附件。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 作业
|
|
||||||
|
|
||||||
## 按「所属日期」归类，不是按录入时间
|
|
||||||
|
|
||||||
每份作业有一个**所属日期**（`Homework.assignDate`，形如 `2026-10-06` 的本地日期，不带时区）。
|
|
||||||
按天查看、日期高亮、客户端的「只看今天」都看它。
|
|
||||||
|
|
||||||
> 用录入时间（`createdAt`）当"哪一天的作业"是错的：它是 UTC，晚上 8 点留的作业会被算到第二天。
|
|
||||||
> 系统里统一用「本地日期」，新增按天查询的接口也一样走 `?date=YYYY-MM-DD`。
|
|
||||||
|
|
||||||
所以老师可以给今天、明天、甚至补录上周某一天 —— 客户端按日期查得到。
|
|
||||||
|
|
||||||
## 两端各自能做什么
|
|
||||||
|
|
||||||
| 能力 | Web 管理端（老师） | 桌面客户端（教室机器） |
|
|
||||||
| ------------------ | ---------------------------------------- | ----------------------------------------------- |
|
|
||||||
| 按天查看 | 工具栏日期选择器；有作业的日期下面带圆点 | 日期选择器 + 前 / 后一天，支持 `?date=` 深链 |
|
|
||||||
| 发布 / 编辑 / 删除 | ✅（教师 / 管理员） | ✅ **录入**（班级账号也能发，归属到该班班主任） |
|
|
||||||
| 看板模式 | — | ✅ 默认视图 |
|
|
||||||
| 全屏看板 | — | ✅ |
|
|
||||||
| 完成情况 | ✅ 按名单统计完成人数 | ❌ **客户端不显示"已完成 / 待完成"** |
|
|
||||||
| 未交名单 | ✅ 作业详情抽屉里可看可改 | ✅ |
|
|
||||||
|
|
||||||
> 客户端刻意不显示完成状态：完成与否是**老师端与通知中心**的概念；
|
|
||||||
> 教室机器上只做"看作业 + 录作业"两件事。服务端的完成数据与统计接口都还在，Web 端照旧可用。
|
|
||||||
|
|
||||||
## 看板模式
|
|
||||||
|
|
||||||
客户端作业页默认按**科目**分卡片，每张卡列出该科的所有作业。工具栏可以：
|
|
||||||
|
|
||||||
- **看板 / 列表** 切换视图（列表模式有一列"作业要求"全文）；
|
|
||||||
- **只看今天** 开关（默认开）；
|
|
||||||
- **显示时间** 开关；
|
|
||||||
- **字号**滑块（11–28px 即时生效）。
|
|
||||||
|
|
||||||
这些偏好存在客户端配置里，重启后仍生效。
|
|
||||||
|
|
||||||
卡片里同时渲染**标题 + 作业要求全文**（不截断）。
|
|
||||||
|
|
||||||
### 全屏看板
|
|
||||||
|
|
||||||
点卡片或「全屏看板」进入。全屏下的排版不是简单地放大：
|
|
||||||
|
|
||||||
1. 按"可用宽 × 可用高"枚举 1..N 列，取**单卡面积最大、宽高比最接近 1.15** 的方案；
|
|
||||||
2. 再按「内容高度 / 可用高度」整体 `transform: scale()` 缩到刚好铺满 —— 所以**不用上下翻页**；
|
|
||||||
3. 标题栏中间绝对居中显示当天日期时间（受「显示时间」开关控制，每分钟刷新）。
|
|
||||||
|
|
||||||
> 字号仍由工具栏的滑块决定，缩放只负责"放得下"。工具栏上会显示当前缩放比例。
|
|
||||||
|
|
||||||
## 教室机器录入作业
|
|
||||||
|
|
||||||
教室里那台机器用**班级账号**登录，可以直接发作业。两个细节：
|
|
||||||
|
|
||||||
- 服务端拿到的是班级账号的会话（`sub` 是班级 id），写 `createdBy` 前会换成该班班主任，
|
|
||||||
否则会撞外键。
|
|
||||||
- **本机刚录入的那条不会弹到灵动岛上**——自己通知自己没意义。这条判断是在发请求**之前**
|
|
||||||
按内容登记指纹做的（服务端是先广播后回响应，等拿到 id 再登记就晚了）。
|
|
||||||
|
|
||||||
录入时可以点**快捷短语**（默认 `P` / `大本` / `小本` / `卷子` / `背诵` / `默写` / `听写` / `预习` /
|
|
||||||
`订正` / `读书`），点一下追加到标题或内容。短语可以在客户端「设置 → 通用」里增删，存在本机。
|
|
||||||
|
|
||||||
## 未交名单
|
|
||||||
|
|
||||||
在作业列表或详情里点「未交名单」→ 勾选**没交作业**的同学 → 保存。
|
|
||||||
|
|
||||||
其余同学会被自动标记为已完成（接口是 `PATCH /api/homeworks/:id/submissions`）。
|
|
||||||
Web 端作业详情抽屉里同样可看可改。
|
|
||||||
|
|
||||||
> 名单来自班级的学生名单 —— 名单不全，这项就不准。见[班级、学生与教师](classes.md)。
|
|
||||||
|
|
||||||
## 附件
|
|
||||||
|
|
||||||
作业可以带一个附件链接。**只接受 `http(s)://` 或站内相对路径**，其他 scheme（`javascript:`、
|
|
||||||
`data:text/html` 等）服务端会直接拒；Web 端渲染前还会再兜一层。
|
|
||||||
放行这些 scheme 等于给了一条存储型 XSS。
|
|
||||||
|
|
||||||
## 实时推送
|
|
||||||
|
|
||||||
发布 / 修改 / 删除作业会分别广播：
|
|
||||||
|
|
||||||
| 事件 | 客户端反应 |
|
|
||||||
| ------------------ | ------------------------------------- |
|
|
||||||
| `homework:new` | 作业列表刷新 + 灵动岛弹「新作业」胶囊 |
|
|
||||||
| `homework:updated` | 刷新；带 `deleted: true` 表示删除 |
|
|
||||||
| `homework:status` | 完成状态变化时刷新统计 |
|
|
||||||
|
|
||||||
课表、作业、通知、成绩都是同一个套路：写库 → 按班级房间广播 → 客户端更新内存状态并写回 IndexedDB。
|
|
||||||
@@ -1,115 +0,0 @@
|
|||||||
---
|
|
||||||
title: 表格与课表导入
|
|
||||||
description: 成绩、学生名单、教师名单的表格导入，以及从 ClassIsland 档案导入节次时间与课表。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 表格与课表导入
|
|
||||||
|
|
||||||
五条导入链路**都在服务端完成解析、校验与去重**，前端只负责收集文件与展示结果。
|
|
||||||
所以 Web 端、客户端与直接调接口拿到的结果是同一套规则、同一份统计。
|
|
||||||
|
|
||||||
## 通用流程
|
|
||||||
|
|
||||||
表格类导入都是三段式（成绩 / 学生 / 教师都一样）：
|
|
||||||
|
|
||||||
1. **下载模板** —— `GET /imports/template?kind=grades&format=xlsx|csv`。
|
|
||||||
CSV 带 BOM，Excel 直接双击打开不乱码。
|
|
||||||
2. **上传预览** —— 服务端返回列名、前 20 行、总行数与**建议的字段映射**，以及校验问题。
|
|
||||||
列名按同义词自动映射（「用户名→学号」「得分→分数」「满分→总分」「课程→科目」……），也可以手动改。
|
|
||||||
**缺必填列不会静默通过**，会直接给出「缺少必填列「…」」。
|
|
||||||
3. **确认导入** —— 按映射与写入模式提交：
|
|
||||||
|
|
||||||
| 模式 | 已存在的记录 |
|
|
||||||
| -------- | ------------ |
|
|
||||||
| `upsert` | 更新（默认） |
|
|
||||||
| `append` | 跳过 |
|
|
||||||
|
|
||||||
返回 `{ total, inserted, updated, skipped, failed, errors[], warnings[] }`。
|
|
||||||
`errors[].row` 是 **Excel 视角的行号（含表头）**，方便老师改完再导。
|
|
||||||
|
|
||||||
**体积限制**：文件上限 **8MB**，请求体上限 12MB（文件以 base64 放进 JSON，约 4/3 倍）。
|
|
||||||
超限返回 413 `IMPORT_TOO_LARGE` 与中文提示 —— 如果你看到一句英文的「request entity too large」，
|
|
||||||
那说明这个异常没被映射，属于 bug。
|
|
||||||
|
|
||||||
## 1. 成绩表格导入
|
|
||||||
|
|
||||||
- 入口：成绩录入 → 「导入表格」
|
|
||||||
- 模板列：`学生学号 / 学生姓名 / 考试名称 / 分数 / 总分 / 科目 / 等级`
|
|
||||||
- 支持 `.xlsx / .xls / .csv / .tsv`（自动识别分隔符）
|
|
||||||
- **重复判定**：同班级 + 同学生 + 同考试 + 同课程
|
|
||||||
- 学生按「用户名」优先、「姓名」兜底匹配
|
|
||||||
|
|
||||||
## 2. 学生名单导入
|
|
||||||
|
|
||||||
- 入口：学生管理 → 「导入名单」（仅管理员）
|
|
||||||
- 模板列：`学号 / 姓名 / 班级 / 性别 / 家长手机号` —— 学生**不是账号**，没有密码列
|
|
||||||
- 用户名必须匹配 `^[A-Za-z0-9_.-]{3,32}$`
|
|
||||||
- 用户名已经被某个教师 / 管理员账号占用时，**这一行进错误列表**，不会覆盖他人账号
|
|
||||||
|
|
||||||
## 3. 教师名单导入
|
|
||||||
|
|
||||||
- 入口：教师管理 → 「导入名单」（仅管理员）
|
|
||||||
- 模板列：`工号 / 姓名 / 手机号 / 初始密码 / 角色`
|
|
||||||
- 角色取 `ADMIN` / `TEACHER`，留空按 `TEACHER`
|
|
||||||
- 与新建教师同一套校验，导入完可以直接登录
|
|
||||||
|
|
||||||
## 4. 从 ClassIsland 导入课程表
|
|
||||||
|
|
||||||
**这是最省事的一条路**：如果教室里已经在用 ClassIsland，直接导入它的档案 JSON，
|
|
||||||
课表、节次时间、单双周会一起进来，不用排两遍。
|
|
||||||
|
|
||||||
- 入口：课表管理 → 「导入 ClassIsland 课程表」
|
|
||||||
- 输入：同一份档案 JSON（`ClassPlans` / `TimeLayouts` / `Subjects` 三个字典），
|
|
||||||
粘贴或选择 `.json` 文件
|
|
||||||
|
|
||||||
### 真实档案的形态
|
|
||||||
|
|
||||||
ClassIsland 2.x 的档案在 `Profiles/<档案名>.json`，字段是 PascalCase：
|
|
||||||
|
|
||||||
```jsonc
|
|
||||||
{
|
|
||||||
"TimeLayouts": {
|
|
||||||
"<guid>": { "Name": "…", "Layouts": [{ "StartTime": "08:00:00", "EndTime": "08:45:00", "TimeType": 0 }] },
|
|
||||||
},
|
|
||||||
"ClassPlans": { "<guid>": { "Name": "…", "Classes": [/* 与上课时间点逐位对齐 */] } },
|
|
||||||
"Subjects": { "<guid>": { "Name": "语文" } },
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
解析器同时兼容顶层数组、`{ TimeLayouts: [...] }`、`{ items | Items | Layouts | TimeLayout: [...] }`
|
|
||||||
与单个时间表对象。
|
|
||||||
|
|
||||||
| 细节 | 说明 |
|
|
||||||
| ------------ | ----------------------------------------------------------------------------------------------------------------------- |
|
|
||||||
| 时间字段 | `StartTime` / `EndTime`（`"08:00:00"`）；旧版 `StartSecond` / `EndSecond`（ISO 字符串或秒数）；`"8:0"` / `"08:00"` 都认 |
|
|
||||||
| `TimeType` | `0=上课`、`1=课间`、`2=分割线`、`3=行动`，与 ClassIsland 一致 |
|
|
||||||
| **节次对齐** | `ClassPlan.Classes[i]` 对应 `Layouts` 里**第 i 个 `TimeType === 0` 的时间点**（课间、分割线不占位） |
|
|
||||||
| 单双周 | `TimeRule.WeekCountDiv`（`0=每周`、`1=单周`、`2=双周`）+ `WeekCountDivTotal`（默认 2） |
|
|
||||||
| 星期换算 | ClassIsland 是 `0=周日 … 6=周六`，导入时换算成 `1=周一 … 7=周日` |
|
|
||||||
| 科目映射 | `Subjects[<guid>].Name`；该班还没有的科目**自动补建课程**（任课老师取该班班主任），预览里会提前列出 |
|
|
||||||
| 写入模式 | `replace` 清空该班课表后写入（事务内完成）/ `merge` 按「星期 + 开始时间 + 单双周」去重 |
|
|
||||||
|
|
||||||
**解析出 `errors` 时返回 400 且数据库完全不写入**（`IMPORT_INVALID` / `IMPORT_EMPTY`）——
|
|
||||||
先保证不写坏，再谈导入。
|
|
||||||
|
|
||||||
时间重叠、分割线没有时间这类问题只作 `warnings`，不阻断导入。
|
|
||||||
|
|
||||||
> **3 周及以上的轮换**没法用单双周表达，会给出 warning 并按"每周"处理。
|
|
||||||
|
|
||||||
## 5. 只导入节次时间（旧入口）
|
|
||||||
|
|
||||||
「导入时间配置」按钮**已经下线** —— 因为同一份档案 JSON 里的 `TimeLayouts` 已经跟着课表一起进来了。
|
|
||||||
组件与接口（`/imports/time-layout/*`）仍然保留给旧脚本调用。
|
|
||||||
|
|
||||||
它的写入模式也是 `replace`（整体替换该班同名配置）与 `merge`（以**开始时间**为槽位标识合并，
|
|
||||||
同槽位被导入项覆盖，其它旧节次保留，不静默丢数据）。
|
|
||||||
|
|
||||||
## 相关接口
|
|
||||||
|
|
||||||
| 路径 | 说明 |
|
|
||||||
| ------------------------------------------------------ | ------------------------------------------ |
|
|
||||||
| `/imports/template?kind=&format=` | 下载模板（`csv` 走 JSON，`xlsx` 走二进制） |
|
|
||||||
| `/imports/table/preview` | 上传解析预览（base64） |
|
|
||||||
| `/imports/table/commit` | 按映射与模式导入 |
|
|
||||||
| `/imports/class-plan/preview`、`/imports/class-plan` | ClassIsland 课程表预览 / 导入 |
|
|
||||||
| `/imports/time-layout/preview`、`/imports/time-layout` | 时间配置预览 / 导入（旧入口） |
|
|
||||||
@@ -1,49 +0,0 @@
|
|||||||
---
|
|
||||||
title: 应用帮助
|
|
||||||
description: ClassHelper每一项功能怎么用：课表、作业、通知、叫人、成绩、班级、灵动岛、外观与导入。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 应用帮助
|
|
||||||
|
|
||||||
这一章按功能讲，重点是**行为上的约定**——什么时段会弹、谁看得见、什么情况下不动。
|
|
||||||
很多"看起来像故障"的现象其实是设计行为，下面每一页都会点出来。
|
|
||||||
|
|
||||||
| 页面 | 讲什么 |
|
|
||||||
| --------------------------------- | ------------------------------------------------------ |
|
|
||||||
| [课表](schedules.md) | 周视图与「今天」时间轴、单双周、学期周数、课表来源 |
|
|
||||||
| [作业](homeworks.md) | 按所属日期归类、看板与全屏看板、教室机器录入、未交名单 |
|
|
||||||
| [通知与提醒](notifications.md) | 三档优先级、上课时段策略、二次确认、已读与红点 |
|
|
||||||
| [叫人](calls.md) | 普通叫人与紧急叫人的差别、快捷短语、谁能叫谁 |
|
|
||||||
| [成绩](grades.md) | 录入方式、导入、等级分布、学生看到的是什么 |
|
|
||||||
| [班级、学生与教师](classes.md) | 班级账号、名单、班主任与各科任课老师、谁看得见什么 |
|
|
||||||
| [灵动岛](island.md) | 胶囊与卡片、多条通知的竖排列表、停靠与外观、触摸屏 |
|
|
||||||
| [外观、主题与动效](appearance.md) | 深浅色、设计令牌、动效语言、降低动态效果 |
|
|
||||||
| [表格与课表导入](imports.md) | 成绩 / 名单 / 教师表格导入与 ClassIsland 档案导入 |
|
|
||||||
|
|
||||||
## 贯穿所有功能的三条规则
|
|
||||||
|
|
||||||
**一、角色决定可见范围。** 同一个页面，管理员、班主任、科任老师看到的数据与能点的按钮都不一样。
|
|
||||||
前端会按权限隐藏入口，但**真正拦人的是服务端**——直接调接口一样会被拒。完整矩阵在
|
|
||||||
[角色与权限](../dev/permissions.md)。
|
|
||||||
|
|
||||||
**二、上课时段不打扰课堂。** 「上课时段」由课表实时判定，普通通知与普通叫人只进队列、下课补弹；
|
|
||||||
紧急通知与紧急叫人才会立刻打断。客户端与灵动岛共用这套规则。
|
|
||||||
细节见[通知与提醒](notifications.md)。
|
|
||||||
|
|
||||||
**三、实时推送只走班级房间。** 老师一发内容，服务端写库后按班级房间广播，客户端立刻更新，
|
|
||||||
不靠轮询。教室机器断线重连后会自动补上漏掉的数据，灵动岛也会把上课期间暂存的通知补弹出来。
|
|
||||||
|
|
||||||
## 两端的差异
|
|
||||||
|
|
||||||
同一件事在 Web 管理端和桌面客户端上不一定完全一样，这是有意的：
|
|
||||||
|
|
||||||
| 事情 | Web 管理端（老师） | 桌面客户端（教室机器） |
|
|
||||||
| ---------- | ------------------------------- | --------------------------------------------------------- |
|
|
||||||
| 作业 | 发布 / 编辑 / 删除 / 看未交名单 | 看作业 + **录入作业** + 勾未交名单，不显示"完成 / 待完成" |
|
|
||||||
| 成绩 | 录入 / 导入 / 改 / 删，带统计 | 只看全班总览 |
|
|
||||||
| 课表 | 排课、导入、改 | 只看（周视图 + 今天时间轴） |
|
|
||||||
| 通知 | 发布 / 删除 / 看已读 | 看、标为已读 |
|
|
||||||
| 班级与人员 | 管理员可管 | 只能看本班 |
|
|
||||||
|
|
||||||
> 客户端没有"修改密码"入口，是**刻意移除的**：防止教室机器上误改班级密码后，
|
|
||||||
> 别的教室机器被锁在门外。班级密码由管理员在 Web 端维护。
|
|
||||||
@@ -1,121 +0,0 @@
|
|||||||
---
|
|
||||||
title: 灵动岛
|
|
||||||
description: 桌面客户端的通知浮窗：胶囊与卡片、多条通知的竖排列表、停靠与外观、触摸屏下的行为。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 灵动岛
|
|
||||||
|
|
||||||
灵动岛是桌面客户端上那个独立于主窗口的浮窗：无边框、透明、置顶、不占任务栏。
|
|
||||||
它是「消息到达的第一现场」—— 老师发的内容先在岛上出现，学生点开才进主界面。
|
|
||||||
|
|
||||||
视觉参照 [WinIsland](https://github.com/WinIslandProject/WinIsland)：
|
|
||||||
连续圆角（超椭圆）而不是 `border-radius`、纯黑 / 毛玻璃 / 主题色三种底、Apple 系统色强调色、
|
|
||||||
6 个停靠位、可选的「空闲细缝」。逐项设计令牌见[灵动岛设计令牌](../dev/winisland-design-tokens.md)。
|
|
||||||
|
|
||||||
## 各形态长什么样
|
|
||||||
|
|
||||||
| 形态 | 截图 | 说明 |
|
|
||||||
| ---------------------- | ----------------------------------------------------- | ------------------------------------------------- |
|
|
||||||
| 非上课时段的「新消息」 |  | 268×44，直接出现（无入场动画），点击后展开 |
|
|
||||||
| 点开后的详情卡 |  | 标题 / 内容 / 时间 + 打开应用 / 标为已读 / 知道了 |
|
|
||||||
| 下课后自动弹出 |  | 上课期间暂存的通知，下课后自动弹出 |
|
|
||||||
| 上课期间的紧急通知 |  | 卡片**内部**红色光晕 + 紧急角标，无需点击 |
|
|
||||||
| 新作业 |  | 青蓝描边 + 书本图标 |
|
|
||||||
| 叫人 |  | 琥珀金卡片 + 「叫人」徽标 + 「收到」按钮 |
|
|
||||||
|
|
||||||
## 什么时候弹、弹成什么样
|
|
||||||
|
|
||||||
| 场景 | 灵动岛行为 |
|
|
||||||
| --------------------------------- | --------------------------------------------------------------------------------------------- |
|
|
||||||
| 收到通知（非上课时段） | 直接出现胶囊：`新消息 · 共 N 条` + 发送人 + `点击查看` |
|
|
||||||
| 多条未处理消息 | 胶囊标题汇总类型：`新消息：叫人/作业/通知（共 3 条）`，右侧带类型小标签 |
|
|
||||||
| 点击胶囊（只有一条） | 展开为**详情卡**：标题、内容、时间 + 三个按钮 |
|
|
||||||
| **点击胶囊（多条）** | 展开为**竖排列表**，按重要程度排序（紧急 > 重要 > 普通 > 低，同级按时间新的在前） |
|
|
||||||
| **点「展开更多」** | 把放得下的都铺出来；铺到工作区下沿还放不下时改成「更多请前往应用内操作」 |
|
|
||||||
| **多条时的「知道了 / 标为已读」** | 都是**整批**操作 |
|
|
||||||
| 上课时段的**普通叫人** | **不自动展开**（不打断课堂），但保留胶囊并**允许学生主动点开**；下课自动展开 |
|
|
||||||
| **紧急叫人** | 上课时段也立即展开，卡片是琥珀金 + 「叫人」徽标，按钮为「收到」 |
|
|
||||||
| 上课时段的普通通知 | **完全不显示**（窗口隐藏）并进队列；下课自动弹出详情 → 收起为胶囊 |
|
|
||||||
| 上课时段的紧急通知 | **无论是否上课立刻展开**，45 秒后收起 |
|
|
||||||
| 点击卡片空白处 / 屏幕任意位置 | 回缩为**胶囊**（不直接消失，仍可再次点开） |
|
|
||||||
| **收起后胶囊常驻** | 只要还有未处理通知，胶囊就不会消失；彻底消失只在「知道了 / 标为已读」、队列清空或进入上课时段 |
|
|
||||||
|
|
||||||
> **本机刚录入的作业不会上岛** —— 自己通知自己没意义。
|
|
||||||
|
|
||||||
## 多条通知时的排版
|
|
||||||
|
|
||||||
这是最容易出问题的地方：卡片要长高，还得刚好放得下。规则是**主进程与渲染进程各算一次同一个数**
|
|
||||||
（`islandListLayout()`，在 `@classhelper/shared` 里）：
|
|
||||||
|
|
||||||
- 默认只显示前 `defaultVisibleRows`（3）条，下面是「展开更多（还有 N 条）」；
|
|
||||||
- 点开后铺到 `maxCardHeight` 为止，仍放不下的改成「更多请前往应用内操作」；
|
|
||||||
- `maxCardHeight` 是主进程按工作区 / 任务栏算出的**可用高度**，随状态下发。
|
|
||||||
|
|
||||||
窗口的包围盒会**在卡片形变之前**先长高（这一步用户看不到），否则底部的按钮会被裁掉。
|
|
||||||
|
|
||||||
## 外观设置
|
|
||||||
|
|
||||||
客户端「设置 → 灵动岛」：
|
|
||||||
|
|
||||||
| 设置项 | 区间 / 取值 | 默认 |
|
|
||||||
| --------------- | -------------------------------------- | ------------------------- |
|
|
||||||
| 高度 | 36–72px | 44 |
|
|
||||||
| 宽度 | 220–420px | 268 |
|
|
||||||
| 圆角 | 8–32px | 20 |
|
|
||||||
| 不透明度 | 40%–100% | 100% |
|
|
||||||
| **字号** | 11–20px | 13 |
|
|
||||||
| 动画速度 | 0.5×–2× | 1× |
|
|
||||||
| 主题色 | 取色器 | `#0a84ff`（Apple 系统蓝） |
|
|
||||||
| **视觉风格** | 纯黑 / 毛玻璃 / 主题色渐变 | 纯黑 |
|
|
||||||
| **显示位置** | 顶部 / 底部 × 左 / 中 / 右（6 个锚点） | 顶部居中 |
|
|
||||||
| 左右 / 上下边距 | 0–200px / 0–160px | 都是 8px |
|
|
||||||
| 跟随鼠标屏幕 | 开 / 关 | 关 |
|
|
||||||
| 动画开关 | 开 / 关 | 开 |
|
|
||||||
| 始终置顶 | 开 / 关 | 开 |
|
|
||||||
| **空闲细缝** | 开 / 关 | 关 |
|
|
||||||
|
|
||||||
几个容易困惑的点：
|
|
||||||
|
|
||||||
- **字号是"基础字号"**：岛内所有文本 = 基础字号 × 各自的排版系数（标题 1.08 / 正文 0.95 / 次要 0.78 /
|
|
||||||
徽标 0.76 / 胶囊标题 0.92 ……），所以调一个滑块就能整体放大，比例不会乱。
|
|
||||||
- **左右边距只在「左 / 右停靠」时生效**：默认是「顶部居中」，水平锚点就是屏幕中线，
|
|
||||||
这时调左右边距不会有任何变化 —— 设置页会把那个滑块置灰并写明原因。
|
|
||||||
- **「毛玻璃」不是窗口材质**，是 CSS 半透明深色卡。用系统级背景材质（`setBackgroundMaterial`）
|
|
||||||
会在卡片外那一圈垫出一块浅色"白底面板"，而且**调用过一次就再也回不去逐像素透明**。
|
|
||||||
- **「预览效果」**会本地推一条通知，立刻看到当前尺寸 / 配色 / 动画。预览是专用通道：
|
|
||||||
直接展开、失焦不收起、30 秒后自行消失。
|
|
||||||
|
|
||||||
越界的值在**主进程**统一夹紧，配置填坏了也不会让布局错乱。
|
|
||||||
|
|
||||||
## 触摸屏（希沃白板等）
|
|
||||||
|
|
||||||
触摸屏上灵动岛走的是**另一条命中链路**。
|
|
||||||
|
|
||||||
原因：常规的命中判定有两条路径 ——渲染进程转发鼠标移动、主进程读系统光标位置 ——
|
|
||||||
**两条都以"鼠标指针移动"为前提**。而手指触摸既不产生 `mousemove`、也不移动系统光标，
|
|
||||||
窗口就会永远停在"穿透"状态，**手指点不开岛**。
|
|
||||||
|
|
||||||
修法是：客户端检测到 `navigator.maxTouchPoints > 0` 后进入触摸模式，
|
|
||||||
把窗口**贴合岛体**并**始终接收输入**（Windows 上 Electron 没有窗口区域能力，这是唯一可行的办法）。
|
|
||||||
|
|
||||||
触摸模式下有三条额外的护栏，都是为了不闪、不裁：
|
|
||||||
|
|
||||||
- **窗口可见期间只缩不放**（需要变小一律等窗口隐藏之后再做）；
|
|
||||||
- 命中矩形按**窗口实际尺寸**算偏移；
|
|
||||||
- 失焦宽限期放宽到 1200ms（触摸没有光标，"假失焦"会让刚展开的岛被缩回胶囊）。
|
|
||||||
|
|
||||||
非触摸屏的机器**完全不走这条路**。
|
|
||||||
|
|
||||||
## 鼠标穿透
|
|
||||||
|
|
||||||
窗口是按最大形态创建的固定包围盒，比卡片大一圈。默认整块穿透，渲染层做命中测试，
|
|
||||||
只在指针进入岛体时打开命中 —— 所以这个"大窗口"不会吞掉桌面上的点击。
|
|
||||||
另有一层保险：主进程每 120ms 用系统光标位置校正一次命中。
|
|
||||||
|
|
||||||
## 排查"闪一下"
|
|
||||||
|
|
||||||
- **开合时底座闪一下**：卡片投影是常驻的 CSS `filter`，形态切换只改参数。
|
|
||||||
给元素增删 `filter` 会让 Chromium 重建渲染表面，首帧可能被当成空内容画出去。
|
|
||||||
- **收回一瞬间闪一下**：多半是**自动化验证实例的叠影**，不是产品的问题 ——
|
|
||||||
冒烟会真的在屏幕上放一个灵动岛，如果它和你自己的客户端叠在一起，你看到的是两个窗口。
|
|
||||||
（验证实例的岛是洋红主题色，一眼可辨。）
|
|
||||||
@@ -1,76 +0,0 @@
|
|||||||
---
|
|
||||||
title: 通知与提醒
|
|
||||||
description: 通知的三档优先级、上课时段策略、紧急通知的二次确认、提醒弹在哪个端、已读与红点。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 通知与提醒
|
|
||||||
|
|
||||||
通知是这套系统里规则最多的一项 —— 因为它要在"老师想说"和"别打断上课"之间做取舍。
|
|
||||||
这一页把规则一次讲清楚。
|
|
||||||
|
|
||||||
## 三档优先级
|
|
||||||
|
|
||||||
| 优先级 | ClassHelper 班级端表现 |
|
|
||||||
| ------ | -------------------------------------------------------------------------------------------- |
|
|
||||||
| 普通 | 课间弹「新消息」胶囊，点击展开详情；**上课时段完全不显示**（窗口隐藏）并进队列，下课自动补弹 |
|
|
||||||
| 重要 | 同上，卡片上有优先级标签 |
|
|
||||||
| 紧急 | **无论是否上课都立即展开**，卡片内部红色呼吸光晕 + 「紧急」角标，无需点击，45 秒后收起 |
|
|
||||||
|
|
||||||
紧急通知的光晕画在**卡片内部**（`inset` 阴影），因为窗口比卡片只大 2~4px，向外的阴影会被裁成硬边。
|
|
||||||
|
|
||||||
## 上课时段策略
|
|
||||||
|
|
||||||
「上课时段」由课表实时判定（见[课表](schedules.md)）。判定之后：
|
|
||||||
|
|
||||||
| ClassHelper 班级端行为 | 上课时段 | 课间 / 放学 |
|
|
||||||
| ---------------------- | ---------------------------------------- | ----------- |
|
|
||||||
| 普通通知 | 收着不弹（窗口隐藏），进待发队列 | 直接弹 |
|
|
||||||
| 紧急通知 | **立刻弹** | 立刻弹 |
|
|
||||||
| 任何点击 | 一律不响应（不会展开、也不会回缩出胶囊） | 正常 |
|
|
||||||
|
|
||||||
## 紧急通知的二次确认
|
|
||||||
|
|
||||||
上课时段发紧急通知，**服务端会拦一次**（`409 URGENT_DURING_CLASS`）：
|
|
||||||
|
|
||||||
```
|
|
||||||
POST /api/notifications { classId, title, content, priority: "URGENT" }
|
|
||||||
→ 409 URGENT_DURING_CLASS（响应体里带着正在上的那节课）
|
|
||||||
|
|
||||||
POST /api/notifications { …, priority: "URGENT", confirmDuringClass: true }
|
|
||||||
→ 201 发出去
|
|
||||||
```
|
|
||||||
|
|
||||||
Web 端在提交前会先查一次上课状态，命中就弹一个**全屏二次确认**：全屏遮罩 + 强警示配色，
|
|
||||||
文案是"现在为上课时间段……" + 正在上的课时段 + 待发布的标题。确认按钮带 **3 秒倒计时**
|
|
||||||
（圆环进度），倒计时结束前点不动，防误触。
|
|
||||||
|
|
||||||
**这个拦截在服务端，不是前端提醒。** 绕过界面直接调接口一样会被拦 —— 这是产品行为，不是可以关掉的提示。
|
|
||||||
|
|
||||||
## 提醒显示
|
|
||||||
|
|
||||||
通知通过实时通道发送到 ClassHelper 客户端与灵动岛。设置页显示本机提醒规则，旧的跨应用通知渠道已移除。
|
|
||||||
|
|
||||||
## 已读、红点与删除
|
|
||||||
|
|
||||||
| 能力 | 说明 |
|
|
||||||
| -------- | ------------------------------------------------------------------------------ |
|
|
||||||
| 未读红点 | 客户端侧边栏「通知」项右上角的徽标；数字来自 `GET /notifications/unread-count` |
|
|
||||||
| 标为已读 | 点开通知自动标为已读；也有「全部已读」 |
|
|
||||||
| 班级设备 | 教室机器的"已读"是**代全班**操作的（它用的是班级账号） |
|
|
||||||
| 删除 | 只有教师 / 管理员能删 |
|
|
||||||
|
|
||||||
## 发布入口只有一个实现
|
|
||||||
|
|
||||||
「通知发布」与叫人复用同一套服务端发布流程和实时广播。
|
|
||||||
|
|
||||||
## 接口
|
|
||||||
|
|
||||||
| 方法 | 路径 | 说明 |
|
|
||||||
| ------ | -------------------------------------------------------- | ------------------------------- |
|
|
||||||
| GET | `/notifications?classId=&priority=&unreadOnly=&keyword=` | 列表（带已读状态） |
|
|
||||||
| GET | `/notifications/unread-count` | 未读数 |
|
|
||||||
| POST | `/notifications` | 发布（广播 `notification:new`） |
|
|
||||||
| POST | `/notifications/:id/read`、`/notifications/read-all` | 标记已读 |
|
|
||||||
| DELETE | `/notifications/:id` | 删除 |
|
|
||||||
|
|
||||||
完整清单见 [REST API](../dev/api.md)。
|
|
||||||
@@ -1,70 +0,0 @@
|
|||||||
---
|
|
||||||
title: 课表
|
|
||||||
description: 周课表与「今天」时间轴、单双周、学期周数、课表来源，以及上课时段是怎么判定的。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 课表
|
|
||||||
|
|
||||||
课表不只是"给学生们看看"的表格 —— **「上课时段」的判定完全基于它**。
|
|
||||||
课表排错，提醒就会在该弹的时候不弹。所以这一页值得读完。
|
|
||||||
|
|
||||||
## 两个视图
|
|
||||||
|
|
||||||
| 视图 | 在哪 | 内容 |
|
|
||||||
| -------------- | ----------------------------------------- | -------------------------------------------------------- |
|
|
||||||
| **周视图** | Web 端「课表管理」、客户端「课表 → 本周」 | 节次 × 星期 的 7 列表格 |
|
|
||||||
| **今天时间轴** | 客户端「课表 → 今天」 | 大时钟 + 当前状态卡 + 时间轴（已结束 / 正在上 / 下一节） |
|
|
||||||
|
|
||||||
「今天」时间轴是客户端默认打开的那一屏：
|
|
||||||
|
|
||||||
- **大时钟**：时:分（大字）+ 秒（小字），下面一行是日期 / 星期 / 第 N 教学周。
|
|
||||||
- **当前状态卡**：「正在上 XXX」+ 时段地点 + **距下课 X 分钟**；没课时显示"今天的课都上完了"或"今天没有课程安排"。
|
|
||||||
- **时间轴**：左侧时间栏（开始 / 结束）+ 竖向轨道与节点 + 右侧课卡。已结束的置灰、
|
|
||||||
正在上的用强调色实底 + 进度条 + 距下课倒计时、下一节用橙色标记 + "还有多久开始"。
|
|
||||||
|
|
||||||
## 单双周
|
|
||||||
|
|
||||||
一门课可以设成**每周**（默认）、**单周**或**双周**。判定口径是 **第 1 周 = 单周**。
|
|
||||||
|
|
||||||
从 ClassIsland 导入时，`WeekCountDiv`（`0=每周 / 1=单周 / 2=双周`）会换算成这套 `ALL / ODD / EVEN`。
|
|
||||||
**3 周及以上的轮换没法用单双周表达**，导入时会给出 warning 并按"每周"处理 ——
|
|
||||||
如果学校里真的是三周轮换，目前只能用两份课表 + 手工切换的方式绕过。
|
|
||||||
|
|
||||||
## 学期周数
|
|
||||||
|
|
||||||
每个班有自己的**学期周数**（`Class.termWeeks`，默认 20，**上限 30**），只有管理员能改。
|
|
||||||
|
|
||||||
它决定三件事：课表的周次下拉能选到第几周、`weekEnd` 的默认值、以及"现在是第几教学周"。
|
|
||||||
周次换算的起点是服务端 `.env` 里的 `TERM_START_DATE`（当学期第 1 教学周的周一）。
|
|
||||||
|
|
||||||
> **`TERM_START_DATE` 设错，整套周次都错。** 它不在界面上改，要改 `.env` 后重启服务端。
|
|
||||||
> 上限三处必须一致（`MAX_TERM_WEEK`、周次校验、班级设置），曾经出现过"班级能设到 40 周、
|
|
||||||
> 而课表只到 30 周"的错位。
|
|
||||||
|
|
||||||
## 上课时段是怎么判定的
|
|
||||||
|
|
||||||
服务端有一个接口专门回答"这个班现在是不是在上课"：
|
|
||||||
|
|
||||||
```
|
|
||||||
GET /api/schedules/current?classId=<班级 id>[&at=<ISO 时间>]
|
|
||||||
```
|
|
||||||
|
|
||||||
返回 `{ inClass, current, next, week, serverTime }`。`at` 参数可以覆盖判定时刻，用来联调与测试。
|
|
||||||
|
|
||||||
判定结果被用在三处，规则完全一致：
|
|
||||||
|
|
||||||
1. 客户端灵动岛：上课时段普通通知**不显示**（窗口直接隐藏）并进队列，下课自动补弹；
|
|
||||||
2. 服务端发布接口：上课时段发紧急通知会被拦（`409 URGENT_DURING_CLASS`），确认后放行；
|
|
||||||
3. Web 端：提交紧急通知前先查一次状态，命中就弹全屏二次确认。
|
|
||||||
|
|
||||||
## 课表来源
|
|
||||||
|
|
||||||
课表由管理端维护，支持手工录入与离线 JSON 导入。升级会保留旧联动课表并将其来源归为 `manual`。
|
|
||||||
|
|
||||||
## 排课 / 改课 / 导入
|
|
||||||
|
|
||||||
- 手工排课在 **课表管理**（管理员 / 本班班主任）。科目下拉是全校统一的 18 科目录，
|
|
||||||
选中一个该班还没有的科目会自动建课。
|
|
||||||
- 从 ClassIsland 档案导入最省事，课表、节次时间、单双周会一起进来，
|
|
||||||
见[表格与课表导入](imports.md)。
|
|
||||||
- 课表变更后会广播 `schedule:updated`，客户端与灵动岛立刻刷新。
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
- name: 应用帮助
|
|
||||||
href: index.md
|
|
||||||
- name: 课表
|
|
||||||
href: schedules.md
|
|
||||||
- name: 作业
|
|
||||||
href: homeworks.md
|
|
||||||
- name: 通知与提醒
|
|
||||||
href: notifications.md
|
|
||||||
- name: 叫人
|
|
||||||
href: calls.md
|
|
||||||
- name: 成绩
|
|
||||||
href: grades.md
|
|
||||||
- name: 班级、学生与教师
|
|
||||||
href: classes.md
|
|
||||||
- name: 灵动岛
|
|
||||||
href: island.md
|
|
||||||
- name: 外观、主题与动效
|
|
||||||
href: appearance.md
|
|
||||||
- name: 表格与课表导入
|
|
||||||
href: imports.md
|
|
||||||
-128
@@ -1,128 +0,0 @@
|
|||||||
#!/usr/bin/env node
|
|
||||||
/**
|
|
||||||
* 文档站构建脚本 —— `pnpm docs:build`。
|
|
||||||
*
|
|
||||||
* 为什么不用直接跑 `docfx docs/docfx.json`：
|
|
||||||
* 1) 站点版本号取自根 package.json（单一来源），DocFX 的配置文件是静态 JSON、读不了文件，
|
|
||||||
* 只能用 CLI 的 `--metadata` 传进去（模板里以 `{{_chVersion}}` 引用）；
|
|
||||||
* 2) GitHub Pages 的项目页挂在 /<仓库名>/ 子路径下，404 页里的相对链接必须相对**站点根**
|
|
||||||
* 而不是相对被请求的那个不存在的路径，因此 404 页的 `<base>` 由这里注入（DOCS_BASE 控制）。
|
|
||||||
*
|
|
||||||
* 用法：
|
|
||||||
* node docs/build.mjs # 构建到 docs/_site
|
|
||||||
* DOCS_BASE=/classhelper/ node docs/build.mjs
|
|
||||||
* node docs/build.mjs --check # 构建并把 docfx 的警告当成错误（CI / 交付前用）
|
|
||||||
* node docs/build.mjs --serve # 构建完起本地预览（等价于再跑 docs/serve.mjs）
|
|
||||||
*/
|
|
||||||
|
|
||||||
import { spawn, spawnSync } from 'node:child_process';
|
|
||||||
import fs from 'node:fs';
|
|
||||||
import path from 'node:path';
|
|
||||||
import { fileURLToPath } from 'node:url';
|
|
||||||
|
|
||||||
const here = path.dirname(fileURLToPath(import.meta.url));
|
|
||||||
const root = path.resolve(here, '..');
|
|
||||||
const siteDir = path.join(here, '_site');
|
|
||||||
|
|
||||||
/** 站点根路径。CI 里按仓库名传进来；本地预览用 './'。 */
|
|
||||||
const BASE = process.env.DOCS_BASE ?? './';
|
|
||||||
|
|
||||||
function readVersion() {
|
|
||||||
const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
|
|
||||||
return pkg.version;
|
|
||||||
}
|
|
||||||
|
|
||||||
/** 找不到 docfx 时给出可照抄的安装命令，而不是一句 spawn ENOENT */
|
|
||||||
function ensureDocfx() {
|
|
||||||
const probe = spawnSync('docfx', ['--version'], { encoding: 'utf8', shell: process.platform === 'win32' });
|
|
||||||
if (probe.status === 0) return probe.stdout.trim();
|
|
||||||
|
|
||||||
console.error('[docs] 找不到 docfx。docfx 是 .NET 工具，安装方式：');
|
|
||||||
console.error('');
|
|
||||||
console.error(' dotnet tool install --global docfx');
|
|
||||||
console.error('');
|
|
||||||
console.error(' 需要 .NET SDK 8（判据是 `dotnet --list-sdks` 有输出）。');
|
|
||||||
console.error(' 想把工具装进仓库内（不污染全局）：');
|
|
||||||
console.error(' DOTNET_CLI_HOME=./.cache/dotnet-home NUGET_PACKAGES=./.cache/nuget \\');
|
|
||||||
console.error(' dotnet tool install --global docfx');
|
|
||||||
process.exit(2);
|
|
||||||
}
|
|
||||||
|
|
||||||
function run(command, args, options = {}) {
|
|
||||||
return new Promise((resolve, reject) => {
|
|
||||||
const child = spawn(command, args, { stdio: 'inherit', shell: process.platform === 'win32', ...options });
|
|
||||||
child.on('error', reject);
|
|
||||||
child.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`${command} 退出码 ${code}`))));
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* 清空上一轮的产物。docfx 不负责清理，旧文件（改过名 / 删掉的页面）会一直留着，
|
|
||||||
* 而 GitHub Pages 上传的是整个目录 —— 不清就会把已下线的页面继续挂在线上。
|
|
||||||
*/
|
|
||||||
function cleanSite() {
|
|
||||||
const sleep = (ms) => {
|
|
||||||
const until = Date.now() + ms;
|
|
||||||
while (Date.now() < until) {
|
|
||||||
/* 同步等待：这是构建脚本，不值得为几毫秒引入异步 */
|
|
||||||
}
|
|
||||||
};
|
|
||||||
for (let attempt = 1; attempt <= 5; attempt += 1) {
|
|
||||||
try {
|
|
||||||
fs.rmSync(siteDir, { recursive: true, force: true });
|
|
||||||
return;
|
|
||||||
} catch (error) {
|
|
||||||
if (attempt === 5) {
|
|
||||||
throw new Error(
|
|
||||||
`清不掉 ${path.relative(root, siteDir)}（${error.code ?? error.message}）。` +
|
|
||||||
' 多半是预览服务或编辑器正占用它 —— 关掉再试。',
|
|
||||||
);
|
|
||||||
}
|
|
||||||
sleep(250 * attempt);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* 生成 404 页。
|
|
||||||
* GitHub Pages 对项目页的未知路径返回站点根的 404.html，而浏览器是**按请求的路径**解析相对链接的，
|
|
||||||
* 所以页面里的 <base> 必须显式指向站点根，否则 /classhelper/get-started/typo 会去解析
|
|
||||||
* /classhelper/get-started/ 下的链接。本地预览时 BASE 为 './'，正好等价于同目录。
|
|
||||||
*/
|
|
||||||
function writeNotFound() {
|
|
||||||
const template = fs.readFileSync(path.join(here, '404.html'), 'utf8');
|
|
||||||
const html = template.replaceAll('{{BASE}}', BASE);
|
|
||||||
fs.writeFileSync(path.join(siteDir, '404.html'), html, 'utf8');
|
|
||||||
console.log(`[docs] 404.html（base = ${BASE}）`);
|
|
||||||
}
|
|
||||||
|
|
||||||
async function main() {
|
|
||||||
const version = readVersion();
|
|
||||||
const docfxVersion = ensureDocfx();
|
|
||||||
console.log(`[docs] docfx ${docfxVersion} · 站点版本 ${version}`);
|
|
||||||
|
|
||||||
// --check：把警告当错误。最常见的警告是"某个 .md 没被任何 toc.yml 引用"，
|
|
||||||
// 那种页面会被构建出来但没有侧边栏，属于必须修掉的疏漏。
|
|
||||||
const check = process.argv.includes('--check');
|
|
||||||
const args = ['build', 'docfx.json', '--metadata', `_chVersion=${version}`];
|
|
||||||
if (check) args.push('--warningsAsErrors');
|
|
||||||
|
|
||||||
// docfx 只覆盖、不清理：删掉或改名的页面会以旧文件的形式留在 _site 里，
|
|
||||||
// 而 GitHub Pages 上传的是整个目录 —— 不清理就会把已经下线的页面继续挂在线上。
|
|
||||||
// Windows 上目录偶尔会被瞬时占用（编辑器 / 索引 / 预览进程），所以重试几次再放弃。
|
|
||||||
cleanSite();
|
|
||||||
|
|
||||||
await run('docfx', args, { cwd: here });
|
|
||||||
|
|
||||||
writeNotFound();
|
|
||||||
console.log(`[docs] 完成：${path.relative(root, siteDir)}`);
|
|
||||||
|
|
||||||
if (process.argv.includes('--serve')) {
|
|
||||||
await run(process.execPath, [path.join(here, 'serve.mjs')]);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
main().catch((error) => {
|
|
||||||
console.error('[docs] 失败：', error.message);
|
|
||||||
process.exit(1);
|
|
||||||
});
|
|
||||||
-129
@@ -1,129 +0,0 @@
|
|||||||
---
|
|
||||||
title: REST API
|
|
||||||
description: ClassHelper后端全部接口一览：方法、路径、权限与说明。
|
|
||||||
---
|
|
||||||
|
|
||||||
# REST API
|
|
||||||
|
|
||||||
## 通用约定
|
|
||||||
|
|
||||||
- 所有接口前缀 `/api`（设备接口也一样）；
|
|
||||||
- 统一响应体：`{ "success": true, "data": {}, "message": "" }`，错误为 `success: false` + `code`；
|
|
||||||
- 除登录、健康检查与设备接口外，都需要 `Authorization: Bearer <token>`；
|
|
||||||
- 请求体校验走 zod（`middleware/validate.ts`），错误由 `middleware/error.ts` 统一映射。
|
|
||||||
|
|
||||||
## 接口一览
|
|
||||||
|
|
||||||
| 方法 | 路径 | 权限 | 说明 |
|
|
||||||
| --------------------------- | ------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------- |
|
|
||||||
| POST | `/auth/login` | 公开 | 登录（教师 / 管理员的**工号** + 密码）；学生不是账号，拿学号登录只会得到 401 |
|
|
||||||
| POST | `/auth/class-login` | 公开 | **班级账号登录**：班级码 + 班级密码 → 班级会话 |
|
|
||||||
| GET | `/auth/me` | 登录 | 当前用户（学生附带班级 / 年级） |
|
|
||||||
| PATCH | `/auth/password` | 登录 | 修改自己的密码（班级会话 → 班级密码） |
|
|
||||||
| POST | `/auth/logout` | 登录 | 退出（无状态，客户端丢弃 token） |
|
|
||||||
| GET | `/permissions/me` | 登录 | 当前账号的生效权限（**无权限键**；班级端会话返回空集） |
|
|
||||||
| GET | `/permissions/catalog` | `permission:manage` | 权限键目录（权限页整棵勾选树的唯一来源） |
|
|
||||||
| GET / POST | `/permissions/groups` | `permission:manage` | 权限组列表 / 新建 |
|
|
||||||
| PATCH / DELETE | `/permissions/groups/:id` | `permission:manage` | 改名 / 改描述 / 整体替换权限键；内置组不可删 |
|
|
||||||
| GET | `/permissions/users` | `permission:manage` | 成员列表（所属权限组 + 生效权限数量） |
|
|
||||||
| PUT | `/permissions/users/:id/groups` | `permission:manage` | 整体替换某账号的权限组（空数组 = 回落角色默认模板） |
|
|
||||||
| GET | `/classes` | 登录 | 班级列表（按权限收敛） |
|
|
||||||
| GET | `/classes/:id` | 班级可见 | 班级详情（学生 / 课程 / 班主任 / 各科任课老师） |
|
|
||||||
| POST | `/classes` | 管理员 | 创建班级（自动生成班级码，可指定班主任） |
|
|
||||||
| PATCH / DELETE | `/classes/:id` | 管理员 / 教师 | 编辑 / 删除班级 |
|
|
||||||
| PATCH | `/classes/:id/class-account` | 管理员 | 设置 / 重置班级账号（班级码 + 班级密码） |
|
|
||||||
| PATCH | `/classes/:id/head-teacher` | 管理员 | 设置 / 更换班主任 |
|
|
||||||
| GET / POST | `/classes/:id/students` | 班级可见 / ADMIN·TEACHER | 学生名单 / 添加学生 |
|
|
||||||
| DELETE | `/classes/:id/students/:userId` | ADMIN·TEACHER | 移出学生 |
|
|
||||||
| PUT | `/classes/:id/subject-teachers` | ADMIN | 设置各科任课老师（班级 + 科目 + 教师） |
|
|
||||||
| GET / POST / PATCH / DELETE | `/courses` | 登录（写：班主任 / 管理员） | 课程管理 |
|
|
||||||
| GET | `/schedules?classId=&week=&dayOfWeek=` | 登录 | 课表列表（`week` 过滤周次范围） |
|
|
||||||
| GET | `/schedules/grid?classId=&week=` | 登录 | 周视图（7 列结构，供客户端直接渲染） |
|
|
||||||
| GET | `/schedules/current?classId=&at=` | 登录 | 当前上课状态（`inClass` / `current` / `next`；`at` 为诊断用时间覆盖） |
|
|
||||||
| POST / PATCH / DELETE | `/schedules[/:id]` | 班主任 / 管理员 | 课表增删改（广播 `schedule:updated`） |
|
|
||||||
| GET | `/homeworks?classId=&courseId=&date=&pendingOnly=&keyword=` | 登录 | 作业列表（支持按所属日期；学生带完成状态，教师带完成人数） |
|
|
||||||
| GET | `/homeworks/days?classId=&from=&to=` | 登录 | 哪些天有作业（日期高亮） |
|
|
||||||
| GET | `/homeworks/:id` | 班级可见 | 作业详情 |
|
|
||||||
| POST | `/homeworks` | 教师 / 管理员 / **班级账号** | 发布作业（附 `assignDate`；班级账号用于教室机器录入，归属班主任） |
|
|
||||||
| PATCH / DELETE | `/homeworks/:id` | 教师 / 管理员 | 修改 / 删除（广播 `homework:new` / `homework:updated`） |
|
|
||||||
| PATCH | `/homeworks/:id/status` | 登录 | 标记完成 / 取消（广播 `homework:status`） |
|
|
||||||
| GET / PATCH | `/homeworks/:id/submissions` | 登录 | 未交名单：读名单 / 回写全班完成状态 |
|
|
||||||
| POST | `/homeworks/bulk` | `homework:write` | 一次给多个班级布置同一份作业（`subjectName` 跨班按名匹配科目；逐班结果） |
|
|
||||||
| GET | `/notifications?classId=&priority=&unreadOnly=&keyword=` | 登录 | 通知列表（带已读状态；另支持 `date` / `from` / `to` / `createdBy`） |
|
|
||||||
| GET | `/notifications/unread-count` | 登录 | 未读数（红点） |
|
|
||||||
| POST | `/notifications` | 教师 / 管理员 | 发布通知（广播 `notification:new`）；上课时段发紧急通知需 `confirmDuringClass` |
|
|
||||||
| POST | `/notifications/:id/read`、`/notifications/read-all` | 登录 | 标记已读（班级设备会写全班） |
|
|
||||||
| DELETE | `/notifications/:id` | 教师 / 管理员 | 删除通知 |
|
|
||||||
| GET | `/notifications/days?classId=&from=&to=&createdBy=` | 登录 | 通知按天归档（日期 + 条数，日期取 `assignDate`） |
|
|
||||||
| GET | `/notifications/creators?classId=&from=&to=&date=` | 登录 | 通知按发布人归档 |
|
|
||||||
| POST | `/notifications/bulk` | `notification:publish` | 一次给多个班级发同一条通知（逐班结果，**单班失败不影响整批**） |
|
|
||||||
| POST | `/calls` | 教师 / 管理员 | **叫人**（`urgent` 决定 URGENT / HIGH；广播 `notification:new` 与 `call:new`） |
|
|
||||||
| GET | `/grades/my` | 登录 | 个人成绩（班级会话 → 全班总览） |
|
|
||||||
| GET | `/grades?classId=&courseId=&userId=&examName=` | 教师 / 管理员 | 班级成绩 |
|
|
||||||
| GET | `/grades/stats?classId=&courseId=&examName=` | 教师 / 管理员 | 等级分布 + 各课程平均得分率 |
|
|
||||||
| POST | `/grades`、`/grades/bulk` | 班主任 / 管理员 | 单条 / 批量录入（广播 `grade:updated`） |
|
|
||||||
| PATCH / DELETE | `/grades/:id` | 班主任 / 管理员 | 修改 / 删除成绩 |
|
|
||||||
| GET | `/students?classId=&keyword=` | **管理员** | 学生名单 |
|
|
||||||
| POST / PATCH / DELETE | `/students[/:id]` | **管理员** | 学生名单增删改（无密码概念；重置密码接口已下线 → 404） |
|
|
||||||
| GET | `/teachers?keyword=` | **管理员** | 教师列表 |
|
|
||||||
| POST / PATCH / DELETE | `/teachers[/:id]` | **管理员** | 新建 / 编辑 / 删除教师账号 |
|
|
||||||
| POST | `/teachers/:id/reset-password` | **管理员** | 修改 / 重置教师密码（`newPassword` 可选，留空 = 默认初始密码） |
|
|
||||||
| GET | `/dashboard/summary`、`/dashboard/term` | 登录 | 仪表盘汇总 / 学期周次 |
|
|
||||||
| GET | `/imports/template?kind=&format=` | 管理员 / 班主任 | 导入模板下载（`csv` 走 JSON，`xlsx` 走二进制） |
|
|
||||||
| POST | `/imports/table/preview` | 管理员 / 班主任 | 上传表格（base64）解析预览：列名 + 前 20 行 + 校验问题 + 建议映射 |
|
|
||||||
| POST | `/imports/table/commit` | 管理员 / 班主任 | 按字段映射与写入模式导入（成绩 / 学生名单 / 教师名单） |
|
|
||||||
| POST | `/imports/time-layout/preview` | 管理员 / 本班班主任 | 解析 ClassIsland 时间配置 JSON（只解析不落库） |
|
|
||||||
| GET / POST / DELETE | `/imports/time-layout[/:id]` | 管理员 / 本班班主任 | 时间配置列表 / 导入（`replace` 覆盖、`merge` 合并）/ 删除 |
|
|
||||||
| POST | `/imports/class-plan/preview`、`/imports/class-plan` | 管理员 / 本班班主任 | ClassIsland 课程表解析预览 / 导入（支持单双周） |
|
|
||||||
| GET | `/database/status` | **管理员** | 数据库状态（连接 / 版本 / 体积 / 23 张表行数 / 备份列表 / 定时配置） |
|
|
||||||
| POST | `/database/test-connection` | **管理员** | 测试任意目标库连通性（provider 仅 sqlite / mysql） |
|
|
||||||
| GET / POST | `/database/backups` | **管理员** | 备份列表 / 立即备份（gzip JSON 快照，存 `<数据目录>/backups/`） |
|
|
||||||
| POST / DELETE | `/database/backups/:name/restore` · `/database/backups/:name` | **管理员** | 从备份恢复（整库覆盖）/ 删除备份 |
|
|
||||||
| GET | `/database/export`、`/database/sqlite-file` | **管理员** | 下载 JSON 快照 / 下载数据库文件（后者仅 SQLite） |
|
|
||||||
| POST | `/database/import` | **管理员** | 导入快照（base64，整库覆盖；可在 SQLite / MySQL 之间互迁） |
|
|
||||||
| GET / PUT | `/database/backup-schedule` | **管理员** | 定时备份配置（enabled / intervalHours / keepCount） |
|
|
||||||
| POST / GET | `/database/switch`、`/database/switch/jobs/:id` | **管理员** | **一键切换数据库**（异步任务）/ 轮询进度 |
|
|
||||||
| GET | `/update/check` | 登录 | 更新检查（服务端代查 GitHub 最新 Release；`?force=1` 绕过缓存仅管理员生效） |
|
|
||||||
| POST | `/clients/heartbeat` | 登录 | 客户端每 30 秒上报（**无权限键**）；返回更新目标 + 安装包信息 + 一条待执行命令 |
|
|
||||||
| POST | `/clients/commands/:id/ack` | 登录 | 命令执行回执（**无权限键**，靠 body 的 `deviceKey` 校验归属，幂等） |
|
|
||||||
| POST | `/clients/commands` | `remote:control` | 下发远控命令（关机 / 重启 / 注销 / 锁屏；自动撤销该机更早的未回执命令） |
|
|
||||||
| GET | `/clients/devices?classId=` | `client:manage` | 客户端设备列表（版本 / 在线 / 待执行命令） |
|
|
||||||
| POST | `/clients/updates` | `client:update-push` | 统一下发客户端更新（按设备 / 班级 / 全部） |
|
|
||||||
| DELETE | `/clients/devices/:id` | `client:manage` | 移除设备记录（换机 / 旧机器清理） |
|
|
||||||
| GET | `/update/client/releases` | `client:manage` | 服务端已缓存了哪些客户端安装包 |
|
|
||||||
| POST | `/update/client/fetch` | `client:update-push` | 服务端代教室机器从 GitHub 下载安装包并登记 sha256 + size |
|
|
||||||
| POST | `/update/client/releases` | `client:update-push` | 手工登记已放进磁盘的安装包（内网 / U 盘分发兜底） |
|
|
||||||
| DELETE | `/update/client/releases/:version` | `client:update-push` | 删除缓存的安装包（元数据 + 磁盘文件） |
|
|
||||||
| GET | `/update/client/download/:version` | 登录 | 下载安装包（**故意不挂权限键**，班级端要能下；`res.download`） |
|
|
||||||
| GET / PUT | `/ai/settings` | `ai:manage` | 大模型设置（API Key 加密存储、**只进不出**，只回 `hasApiKey` / `keyHint`） |
|
|
||||||
| POST | `/ai/interpret` | `ai:use` | 一句话解析（**只解析不落库**）；回 `action` / `params` / `preview` / `confidence` |
|
|
||||||
| GET | `/ai/audit?limit=` | `ai:manage` | 助手使用记录（每次解析写一条 `AiAudit`） |
|
|
||||||
| GET / PUT | `/system/settings` | `system:manage` | 系统设置（`developerMode`：开启后 500 响应带 `error.stack`） |
|
|
||||||
| GET / PUT | `/system/autostart` | `system:manage` | 开机自启状态 / 开关（Windows 注册表 Run 项，Linux systemd 单元） |
|
|
||||||
| GET | `/system/diagnostics` | `system:manage` | 运行诊断（版本 / Node / 运行时长 / 数据目录 / 在线客户端数 / 已加载模块） |
|
|
||||||
| GET | `/health` | 公开 | 健康检查（含版本号与已挂载模块） |
|
|
||||||
|
|
||||||
另有三个探针（不带 `/api` 前缀）：`/healthz`（存活）、`/readyz`（就绪）、以及 `/api/health`（详情）。
|
|
||||||
|
|
||||||
## 几条容易踩的接口约定
|
|
||||||
|
|
||||||
| 约定 | 说明 |
|
|
||||||
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
||||||
| **`POST /homeworks` 故意不加 `requireRole`** | 权限判在 `homeworks.service.createHomework` 里（staff 或本班班级账号），因为教室机器也要能录作业 |
|
|
||||||
| **班级账号的 `sub` 是班级 id** | 写 `createdBy` 前要换成该班班主任，否则撞 `User` 外键 |
|
|
||||||
| **登录限流挂在两个入口上** | `/auth/login` 与 `/auth/class-login` 都挂 `loginRateLimiter()` |
|
|
||||||
| **角色判定在密码校验之前** | 否则"密码错 / 密码对但账号停用"的差异会把学生账号密码变成可离线验证的预言机 |
|
|
||||||
| **会渲染成链接的字段要校验 scheme** | `Homework.attachmentUrl` 只允许 `http(s)://` 或站内相对路径 |
|
|
||||||
| **表格导入 8MB ↔ 请求体 12MB** | 文件以 base64 放进 JSON（约 4/3 倍），超限映射成 413 `IMPORT_TOO_LARGE` |
|
|
||||||
| **三个接口故意不挂权限键** | `/permissions/me`、`/clients/heartbeat`、`/update/client/download/:version` —— 前两者由班级端（`CLASS_DEVICE`，权限集为空）调用，下载接口要能装包；保护只有"已登录 + 限流" |
|
|
||||||
| **查询参数校验失败是 422** | `middleware/validate.ts` 的 zod 解析错误由错误中间件映射成 422 `VALIDATION_ERROR`（不是 400） |
|
|
||||||
| **批量发布逐班判定、不整批回滚** | `/notifications/bulk` 与 `/homeworks/bulk` 的单班失败（403 越权 / `URGENT_DURING_CLASS`）不影响其它班，成功班照常落库并实时推送 |
|
|
||||||
| **`/ai/interpret` 只解析不落库** | 助手只回结构化参数与中文预览；落库由前端确认后调既有端点 —— 权限与上课时段保护都在那条路径上 |
|
|
||||||
|
|
||||||
## 相关
|
|
||||||
|
|
||||||
- 实时事件见[实时事件（Socket.IO）](realtime.md)；
|
|
||||||
- 权限矩阵见[角色与权限](permissions.md)；
|
|
||||||
- 数据模型见[数据模型](data-model.md)。
|
|
||||||
|
|
||||||
客户端心跳可携带 `agentProtocol: 2`，业务数据读取统一响应的 `data`。未带此标记时额外返回旧版需要的顶层字段；放学后更新在到时前不向旧客户端提供安装包。推送更新支持 `mode: immediate | after-school | idle`，`afterSchoolTime` 为服务端本地时区的 `HH:mm`。
|
|
||||||
@@ -1,165 +0,0 @@
|
|||||||
---
|
|
||||||
title: 架构总览
|
|
||||||
description: 目录结构、技术栈、模块化设计与几条贯穿全局的工程约定。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 架构总览
|
|
||||||
|
|
||||||
## 技术栈
|
|
||||||
|
|
||||||
| 层 | 选型 | 版本（`package.json` 实际声明） |
|
|
||||||
| ------ | -------------------------------------------------------------------- | ---------------------------------------------------------- |
|
|
||||||
| 包管理 | pnpm workspace | 11.8.0 |
|
|
||||||
| 语言 | TypeScript | 5.9.3（`typescript-eslint` 要求 < 6.1，因此未用 7.x） |
|
|
||||||
| 后端 | Node.js + Express | ≥ 20.19 / 5.2 |
|
|
||||||
| ORM | Prisma + driver adapter | 7.10（+ `@prisma/adapter-libsql`，切 MySQL 用 `-mariadb`） |
|
|
||||||
| 实时 | Socket.IO | 4.8 |
|
|
||||||
| 认证 | jsonwebtoken + bcryptjs | 9.0 / 3.0 |
|
|
||||||
| 校验 | zod | 4.6 |
|
|
||||||
| Web 端 | Vue + Vite + Element Plus + Pinia + Vue Router + Axios | 3.5 / 8.3 / 2.14 / 4.0 / 5.3 / 1.20 |
|
|
||||||
| 客户端 | Electron + Vue + Element Plus + Pinia + Socket.IO Client + IndexedDB | 44.3 / 3.5 / 2.14 / 4.0 / 4.8 |
|
|
||||||
| 打包 | electron-builder（nsis / portable）+ NSIS | 26.15 |
|
|
||||||
| 文档站 | docfx | 2.81 |
|
|
||||||
|
|
||||||
## 目录结构
|
|
||||||
|
|
||||||
```
|
|
||||||
class-helper/
|
|
||||||
├── package.json # 根脚本（dev / build / db:* / verify:* / dist:* / docs:* / icons）
|
|
||||||
├── pnpm-workspace.yaml # workspace 定义 + allowBuilds（pnpm 11 依赖构建白名单）
|
|
||||||
├── tsconfig.base.json # 共享 TS 基础配置（ESM + NodeNext + strict）
|
|
||||||
├── eslint.config.mjs # ESLint 扁平配置（TS + Vue）
|
|
||||||
├── .prettierrc.json # 单引号 / 110 列 / LF / 尾逗号
|
|
||||||
├── build/classhelper.{png,ico} # **图标源**（设计导出、手工放入）；pnpm icons 从它派生其余全部图标
|
|
||||||
├── scripts/
|
|
||||||
│ ├── use-database.mjs # SQLite ⇄ MySQL provider 切换助手
|
|
||||||
│ ├── generate-icons.mjs # 启动 Electron 跑 icons/render.cjs（= pnpm icons）
|
|
||||||
│ ├── icons/render.cjs # 把 classhelper.png 重采样成各端图标（CommonJS）
|
|
||||||
│ ├── version.mjs # 版本号单一来源的读写与一致性校验（= pnpm version:*）
|
|
||||||
│ ├── dist-server.mjs # 服务端 + Web 管理端打包（组装运行时 → NSIS 安装程序）
|
|
||||||
│ ├── verify-packaged.mjs # 对打包后 / 已安装的客户端 EXE 复跑冒烟
|
|
||||||
│ ├── lib/ # electron-env / node-runtime / smoke-class
|
|
||||||
│ ├── nsis/server-installer.nsi# 安装程序脚本模板（版本号由 dist-server 注入）
|
|
||||||
│ └── ui-smoke/ # Web 管理端 UI 真实点击回归（Electron 驱动）
|
|
||||||
├── deploy/ # 生产部署：Dockerfile / docker-compose{,.sqlite}.yml / nginx.conf
|
|
||||||
│ ├── install.sh # Linux 一键安装器（TUI；native/docker 双形态；自带 --check 体检）
|
|
||||||
│ ├── classhelper # 运维命令本体（软链 /usr/local/bin/classhelper）
|
|
||||||
│ ├── verify-linux.sh # Linux 安装/改密/备份/升级/回滚验收（自统计 N/N 项）
|
|
||||||
│ ├── tools/admin-cli.mjs # 离线账号工具（改密、列账号、SQLite 一致性快照）
|
|
||||||
│ ├── classhelper.service # systemd 单元模板
|
|
||||||
│ └── package.runtime.json # 运行时依赖清单（安装包 / 容器 / Linux 部署共用）
|
|
||||||
├── docs/ # **文档站**（docfx 项目，发布到 GitHub Pages）
|
|
||||||
│ ├── docfx.json # docfx 配置
|
|
||||||
│ ├── toc.yml # 顶栏导航；各子目录各有一份 toc.yml 作为侧栏
|
|
||||||
│ ├── index.md # 首页
|
|
||||||
│ ├── get-started/ app/ management/ dev/ # 四个章节
|
|
||||||
│ ├── templates/classhelper/ # docfx 模板覆盖（_master.tmpl + public/main.css + 图标）
|
|
||||||
│ ├── images/ # 展示图：文档站 / README / 官网共用的同一份（1× 逻辑像素）
|
|
||||||
│ ├── screenshots/ # 回归测试留档的截图（island / client / web-mobile），页面不展示
|
|
||||||
│ ├── build.mjs # 构建入口（注入版本号与 404 的 base）
|
|
||||||
│ ├── serve.mjs # 本地预览（:5181）
|
|
||||||
│ └── _site/ # 构建产物（gitignore）
|
|
||||||
├── website/ # 产品官网（纯静态，无构建；node website/serve.mjs 本地预览）
|
|
||||||
│ └── assets/{styles.css,motion.js,main.js,icon.png,shots/}
|
|
||||||
└── packages/
|
|
||||||
├── shared/ # 三端共享：类型契约、常量、权限矩阵、动效令牌、工具函数
|
|
||||||
│ └── src/{types,constants,permissions,motion,island-layout,utils,index}.ts
|
|
||||||
├── server/ # 后端服务
|
|
||||||
│ ├── prisma/schema.prisma # 数据模型（24 个 model，只有一份，切库改 provider）
|
|
||||||
│ ├── prisma/migrations/ # 迁移历史（10 个）
|
|
||||||
│ ├── prisma/seed.ts # 种子数据（会清空业务表后重建演示数据）
|
|
||||||
│ ├── scripts/ # verify-e2e.mjs / apply-column-migrations.cjs
|
|
||||||
│ └── src/
|
|
||||||
│ ├── app.ts # Express 装配（探针 + 限流 + 模块挂载 + 静态托管 + 兜底）
|
|
||||||
│ ├── index.ts # 启动入口（自检 + HTTP + Socket.IO + 优雅退出）
|
|
||||||
│ ├── config/env.ts # 环境变量校验（zod）+ 生产配置自检
|
|
||||||
│ ├── lib/ # access(RBAC) / snapshot(全库 JSON 快照) / db / db-bootstrap /
|
|
||||||
│ │ # session / web-static / http / jwt / logger / mappers / version …
|
|
||||||
│ ├── tools/apply-snapshot.ts # 跨库迁移的子进程入口
|
|
||||||
│ ├── middleware/ # auth / error / validate / security(helmet + 限流 + 耗时日志)
|
|
||||||
│ ├── realtime/ # socket.ts（房间）+ bus.ts（事件总线）
|
|
||||||
│ └── modules/ # 15 个功能模块 + registry.ts（模块注册表）
|
|
||||||
│ ├── manifest.yml
|
|
||||||
│ ├── src/Plugin.cs
|
|
||||||
│ ├── src/Services/ # BridgeService / ScheduleMapper / ClassPlanWriter /
|
|
||||||
│ │ # ClassHelperNotificationProvider
|
|
||||||
│ ├── src/Views/ # BridgeSettingsPage.axaml（Avalonia 设置页）
|
|
||||||
│ └── src/Interop/ClassHelperClient.cs # HTTP 客户端 + 逐字段对齐服务端 zod 的 DTO
|
|
||||||
├── web-admin/ # Web 管理端（Vue 3 + Vite + Element Plus + PWA）
|
|
||||||
│ └── src/{api,stores,router,layouts,views,components,composables,styles}
|
|
||||||
└── desktop-client/ # 桌面客户端（Electron + Vue 3）
|
|
||||||
├── electron-builder.yml
|
|
||||||
├── scripts/{build-main,dev,smoke,dist-win,check-bundle-secrets}.mjs
|
|
||||||
└── src/
|
|
||||||
├── main/ # 主进程：窗口 / 单实例 / 配置持久化 / 托盘 / 灵动岛 / 冒烟
|
|
||||||
├── preload/ # contextBridge 安全桥（index.ts + island.ts）
|
|
||||||
├── island/ # 灵动岛渲染进程（独立透明置顶窗口）
|
|
||||||
├── types/desktop.d.ts # 主进程 ↔ 渲染进程契约
|
|
||||||
└── renderer/ # 渲染进程：api / stores / cache / router / views / island
|
|
||||||
```
|
|
||||||
|
|
||||||
## 模块化设计
|
|
||||||
|
|
||||||
后端每个功能是一个独立目录，统一契约：
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// packages/server/src/modules/registry.ts（当前 20 个模块）
|
|
||||||
export const apiModules: ApiModule[] = [
|
|
||||||
authModule,
|
|
||||||
aiModule, // 大模型助手（只解析不落库，见 docs/dev/api.md）
|
|
||||||
classesModule,
|
|
||||||
coursesModule,
|
|
||||||
schedulesModule,
|
|
||||||
homeworksModule,
|
|
||||||
notificationsModule,
|
|
||||||
callsModule,
|
|
||||||
importsModule,
|
|
||||||
gradesModule,
|
|
||||||
studentsModule,
|
|
||||||
teachersModule,
|
|
||||||
archivesModule,
|
|
||||||
termModule,
|
|
||||||
dashboardModule,
|
|
||||||
databaseModule, // 数据库管理（仅管理员）
|
|
||||||
updateModule, // 更新检查 + 客户端安装包缓存与统一下发
|
|
||||||
permissionsModule, // 权限组管理
|
|
||||||
clientsModule, // 客户端设备心跳 / 远控命令
|
|
||||||
systemModule, // 开发者模式 / 开机自启 / 运行诊断
|
|
||||||
].filter((module) => module.enabled !== false);
|
|
||||||
```
|
|
||||||
|
|
||||||
- **新增功能**：新建 `modules/<name>/`（`*.schemas.ts` 校验、`*.service.ts` 业务、`*.module.ts` 路由），
|
|
||||||
在 registry 里加一行即可，`app.ts` 不用改；
|
|
||||||
- **下线功能**：删掉那一行，或把 `enabled` 置为 `false`，接口立即从路由表消失；
|
|
||||||
- **实时推送解耦**：业务模块只调 `realtime/bus.ts` 的 `emitToClass/emitToUser`，不直接依赖 Socket.IO 实例；
|
|
||||||
- **共享契约**：所有 DTO 与类型集中在 `@classhelper/shared`（改完要 `pnpm build:shared`），三端共用。
|
|
||||||
|
|
||||||
## 几条贯穿全局的硬约定
|
|
||||||
|
|
||||||
这些都是长期演进中固化下来的，改代码前值得先看（完整版在 `AGENTS.md`）：
|
|
||||||
|
|
||||||
| 约定 | 为什么 |
|
|
||||||
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
||||||
| **统一响应与校验** | 用 `lib/http.ts` 的 `sendOk/sendCreated`，用 `middleware/validate.ts` 挂 zod，错误交给 `middleware/error.ts` |
|
|
||||||
| **功能级准入看权限键** | 路由挂 `requirePermission('…')` / `requireAnyPermission(…)`，角色只是默认模板（`ROLE_DEFAULT_PERMISSIONS`）—— 见 `docs/dev/permissions.md` |
|
|
||||||
| **权限判在服务层** | 权限组只管功能级；班级维度与科目维度仍用 `lib/access.ts` 的断言（`assertCanManageSubjectContent` 等），**权限组不可覆盖** —— 前端隐藏 ≠ 权限 |
|
|
||||||
| **周一为新一周的第一天** | 周次口径唯一：`resolveCurrentWeek(TERM_START_DATE, now, MAX_TERM_WEEK)` |
|
|
||||||
| **作业按 `assignDate` 归类** | 用 `createdAt`（UTC）会在晚上把作业算到第二天 |
|
|
||||||
| **新增实时事件要改三处** | 服务端 bus/socket、Web 端订阅、客户端订阅（灵动岛也依赖） |
|
|
||||||
| **跨桥接只传纯数据** | 传 Vue 的 `ref.value` 会在进入 preload 之前就抛 `could not be cloned` |
|
|
||||||
| **桌面端产物里不得有凭据** | asar 可直接解包；构建有 `check-bundle-secrets` 门禁 |
|
|
||||||
| **图标只有一个图形源** | 别改 `scripts/icons/` 的派生逻辑，换图标就换 `build/classhelper.{png,ico}` |
|
|
||||||
| **前端不写死颜色** | 深色主题靠语义令牌，写死的颜色在深色下会露馅 |
|
|
||||||
|
|
||||||
## 本地开发
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm install
|
|
||||||
cp packages/server/.env.example packages/server/.env # 至少改 JWT_SECRET
|
|
||||||
pnpm db:generate && pnpm --filter @classhelper/server db:deploy
|
|
||||||
pnpm build:shared # 必须先构建 shared，否则后续全部 ERR_MODULE_NOT_FOUND
|
|
||||||
pnpm db:seed # 演示数据（会清空业务表）
|
|
||||||
pnpm dev # shared watch + 后端 4000 + Web 端 5173
|
|
||||||
```
|
|
||||||
|
|
||||||
常用命令与端口见[安装服务端](../get-started/server.md)；验收脚本见[验收与测试](testing.md)。
|
|
||||||
@@ -1,133 +0,0 @@
|
|||||||
---
|
|
||||||
title: 数据模型
|
|
||||||
description: 24 张表的职责、跨库通用约定、迁移历史与启动时自动迁移。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 数据模型
|
|
||||||
|
|
||||||
模型定义只有一份：`packages/server/prisma/schema.prisma`。
|
|
||||||
|
|
||||||
## 跨库通用约定
|
|
||||||
|
|
||||||
- 默认是 **SQLite**（Prisma 7 的 libSQL driver adapter，数据文件 `packages/server/prisma/dev.db`）；
|
|
||||||
- 字段**只用** `String / Int / Float / Boolean / DateTime`，**不用 Prisma enum、不用 `@db.*` 原生类型**；
|
|
||||||
角色与优先级存字符串，在 API 层用 zod 校验 —— 这样 SQLite 与 MySQL 行为完全一致；
|
|
||||||
- 因此切库只需改 `provider` 与连接串（`pnpm db:switch:mysql` 就地改写它，没有第二份 schema）；
|
|
||||||
- 主键统一用 cuid 字符串，便于多端离线生成与合并。
|
|
||||||
|
|
||||||
## 两条核心不变量
|
|
||||||
|
|
||||||
这两条是 2026-10-06 那次重构立下的，后面所有表都围着它们转：
|
|
||||||
|
|
||||||
**① 学生不是账号。** `Student` 是独立的一张表，只有学号 / 姓名 / 班级 / 性别 / 家长手机号 /
|
|
||||||
状态，**没有 `passwordHash`、没有 `role`、没有登录字段** —— 「学生不能登录」由表结构保证，
|
|
||||||
不再靠"登录前先判 role === 'STUDENT' 并 403"这类代码分支维持。
|
|
||||||
`User` 因此收缩为**纯账号表**（管理员 / 教师 / ClassHelper 班级端）。
|
|
||||||
|
|
||||||
**② 任课关系的唯一来源是 `Course`。** `Course(classId, name, teacherId)` 就是
|
|
||||||
「班级 + 科目 + 教师」这条关系本身，作业与成绩都挂在它上面；班主任另由 `Class.teacherId` 表示
|
|
||||||
（每班 1 人）。历史上那张**没有科目**的 `ClassTeacher` 协作表已删除 —— 两套关系并存必然漂移。
|
|
||||||
同一位教师可以在同一个班同时是班主任和某科科任老师：两处指向同一个 `User`，不重复建号，
|
|
||||||
权限在 `@classhelper/shared` 的 `resolveClassRole()` 里合并。
|
|
||||||
|
|
||||||
## 24 张表
|
|
||||||
|
|
||||||
| 表 | 职责 | 值得注意的字段 |
|
|
||||||
| ------------------------------------------------------------------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
||||||
| `User` | **纯账号表**：管理员 / 教师 / ClassHelper 班级端 | `username`（教师即**工号**，班级端即班级码）、`role`、`phone`、`careMode`（关怀模式偏好，目前只由本机界面读写）；**学生不在这里** |
|
|
||||||
| `Student` | 学生名单记录（**没有账号**） | `studentNo`（学号，唯一，唯一标识与查询键）、`classId`、`status`、`archivedYearId` |
|
|
||||||
| `StudentClassTransfer` | 调班 / 转出历史 | 班级 id 与班级名**都存快照且不建外键**（班级删了历史仍要能读）、`mode`（single｜batch｜transfer-out） |
|
|
||||||
| `ArchivedYear` | 毕业归档的届别档案 | `enrollmentYear`（届别，唯一）、`graduationYear`、归档时的统计快照 |
|
|
||||||
| `Class` | 班级 | `name`（**「2026级1班」**，由 `enrollmentYear` + `classIndex` 生成）、`code` + `passwordHash`（班级端账号）、`termWeeks`、`termStartDate`、`studentGradeQueryEnabled`、`archivedYearId` |
|
|
||||||
| `TermWeek` | 学期逐周日期区间 | `classId`（**空串 = 全校默认**）、`weekNumber`、`startDate` / `endDate` |
|
|
||||||
| `Course` | 课程 = **「班级 + 科目 + 教师」任课关系** | `teacherId` 就是该班该科的任课老师；`@@unique([classId, name])` |
|
|
||||||
| `Schedule` | 课表条目 | `weekStart` / `weekEnd` / `weekParity`（单双周）/ `source`（manual） |
|
|
||||||
| `Homework` | 作业 | `assignDate`（所属日期）、`attachmentUrl`；`dueAt` 是已下线的遗留列 |
|
|
||||||
| `HomeworkStatus` | 学生作业完成状态 | `@@unique([homeworkId, studentId])` |
|
|
||||||
| `Notification` | 通知 | `priority`、`assignDate`（所属本地日期，禁止 UTC 切片）；`@@index([classId, assignDate])` 供按天归档 |
|
|
||||||
| `NotificationRead` | 已读记录 | `@@unique([notificationId, studentId])` |
|
|
||||||
| `TimeLayout` | 节次时间配置（ClassIsland 同款 JSON 导入得到） | `items` 是 JSON 字符串：`[{ index, name, startTime, endTime, type, skipped }]` |
|
|
||||||
| `Grade` | 成绩 | `studentId`、`score` / `totalScore`、`levelType`（percent｜letter｜custom）与 `level` |
|
|
||||||
| `PermissionGroup` | 权限组（角色之上的**默认模板**） | `name`（唯一）、`builtin`（内置组不可删）；生效集合见 [角色与权限](permissions.md) |
|
|
||||||
| `PermissionGroupItem` | 权限组里的一个权限键（一行一个键） | `@@unique([groupId, key])`；键取值必须是 shared 的 `PERMISSION_KEYS` 之一 |
|
|
||||||
| `UserPermissionGroup` | 账号 ←→ 权限组 的分配关系（可属多个组） | `@@unique([userId, groupId])`；**没有任何行 = 回落角色默认模板** |
|
|
||||||
| `AppSetting` | 全局键值设置（大模型配置 / 开发者模式） | `key` 即主键、`value` 存字符串（复杂结构存 JSON）；密钥类值做 AES-256-GCM 加密后存这里（**只进不出**） |
|
|
||||||
| `ClientDevice` | ClassHelper 客户端设备（教室 / 学生机） | `deviceKey`（唯一，客户端生成）、`classId`、`clientVersion`、`updateTargetVersion`、`lastHeartbeatAt`（**客户端在线判定看 `ClientDevice.lastHeartbeatAt`**：每 30 秒心跳，90 秒内有成功上报即在线。 |
|
|
||||||
| 更新目标、安装策略与最早安装时间持久化在设备记录中，离线设备下次上线继续领取。 |
|
|
||||||
|
|
||||||
**`Schedule.source`** —— 联动退役后历史同步课表统一归为 `manual`，保留排课数据。
|
|
||||||
|
|
||||||
**`Homework.dueAt`** —— 截止时间功能已下线，UI 与接口都不再读写它。
|
|
||||||
保留列是为了**不对已安装的库做破坏性迁移**；新库里它恒为 `null`。
|
|
||||||
|
|
||||||
**`Notification.assignDate`** —— 与 `Homework.assignDate` 同口径：**本地日期**（`YYYY-MM-DD`），
|
|
||||||
创建时用 `dayKeyLocal()` 写入，按天 / 区间归档都读它。**不要用 `createdAt` 切 UTC 当"哪一天"** ——
|
|
||||||
晚上发的通知会被算到第二天。`@@index([classId, assignDate])` 是归档查询的支撑。
|
|
||||||
|
|
||||||
**`User.careMode`** —— 关怀模式的账号级偏好列（放大正文与控件）。**目前服务端没有任何接口读写它**：
|
|
||||||
Web 端存在 `localStorage`（`classhelper.admin.careMode` + `careScale`），客户端存在本机 `config.json`。
|
|
||||||
列先建好是为了将来跨设备同步偏好时不必再迁移；别把它当成"已有服务端开关"。
|
|
||||||
|
|
||||||
**`TermWeek.classId` 用空串而不是 null 表示"全校默认"** —— SQLite 与 MySQL 的唯一约束都把
|
|
||||||
NULL 视作互不相同，`@@unique([classId, weekNumber])` 用 null 就形同虚设。
|
|
||||||
|
|
||||||
## 迁移历史（17 个）
|
|
||||||
|
|
||||||
```
|
|
||||||
init → add_time_layout → add_class_account → add_schedule_week_parity →
|
|
||||||
add_class_term_weeks → add_classisland_integration → add_class_notification_channel →
|
|
||||||
add_homework_assign_date → add_push_kind → add_schedule_source →
|
|
||||||
add_student_table → add_student_grade_query → add_grade_level →
|
|
||||||
add_classhelper_heartbeat → add_archives → add_term_weeks →
|
|
||||||
add_permission_groups_and_clients
|
|
||||||
```
|
|
||||||
|
|
||||||
`add_student_table` 是一次真正的表重构（不是加列）：新建 `Student` / `StudentClassTransfer`、
|
|
||||||
把 `User` 里 `role='STUDENT'` 的行**按 id 原样搬过去**、把 `Grade` / `HomeworkStatus` /
|
|
||||||
`NotificationRead` 的外键从 `userId` 换到 `studentId`、删掉 `Enrollment` 与 `ClassTeacher`。
|
|
||||||
因为学生行的 id 保持不变，三张个人数据表的 `userId` 可以直接当 `studentId` 用，历史一条不丢。
|
|
||||||
|
|
||||||
`add_permission_groups_and_clients` 是纯加表 / 加列：新建 `PermissionGroup` /
|
|
||||||
`PermissionGroupItem` / `UserPermissionGroup`（权限组）、`AppSetting`（全局键值设置）、
|
|
||||||
`ClientDevice` / `ClientCommand`（客户端设备与远控）、`ClientRelease`（安装包缓存）、
|
|
||||||
`AiAudit`（大模型审计），并给 `Notification` 加 `assignDate` + `[classId, assignDate]` 索引、
|
|
||||||
给 `User` 加 `careMode`。没有数据搬运，旧库直接补跑即可。
|
|
||||||
|
|
||||||
### 启动时自动迁移
|
|
||||||
|
|
||||||
`src/lib/db-bootstrap.ts` 用一张账本表 `_ch_migrations` 记录已执行的迁移目录名：
|
|
||||||
|
|
||||||
| 情况 | 行为 |
|
|
||||||
| -------- | --------------------------------------------------- |
|
|
||||||
| 全新安装 | 依次执行全部迁移并创建初始管理员 |
|
|
||||||
| 覆盖安装 | 只补跑账本里没有的迁移（已存在的表 / 索引自动跳过） |
|
|
||||||
| 已是最新 | **不做任何写操作** |
|
|
||||||
|
|
||||||
日志会写明「全新安装 / 升级安装」、应用了几个迁移、跳过了几个已存在对象。
|
|
||||||
用户因此**不需要手动执行 `prisma migrate deploy`**。
|
|
||||||
|
|
||||||
## 备份格式就是这份模型的拓扑序导出
|
|
||||||
|
|
||||||
「数据库管理」里的备份 / 导出导入 / 跨库迁移共用一种 JSON 快照：**23 张表按拓扑序导出**
|
|
||||||
（见 `lib/snapshot.ts` 的 `SNAPSHOT_TABLES`，现在共 23 项，顺序为
|
|
||||||
`User` → `PermissionGroup` → `PermissionGroupItem` → `UserPermissionGroup` → `AppSetting` →
|
|
||||||
`ArchivedYear` → `Class` → `Student` → … → `AiAudit`），恢复时**临时关闭外键检查** ——
|
|
||||||
因为 `Class.teacherId → User` 与 `Student.classId → Class` 是一条链、
|
|
||||||
`Class/Student.archivedYearId → ArchivedYear` 又是一条，任何排序都会被其中一侧卡死。
|
|
||||||
见[数据库管理](../management/database.md)。
|
|
||||||
|
|
||||||
## 开发时的模型改动
|
|
||||||
|
|
||||||
1. 改 `schema.prisma`；
|
|
||||||
2. 在 `prisma/migrations/` 下加一个迁移目录（用
|
|
||||||
`pnpm --filter @classhelper/server db:deploy` 应用，**别用 `pnpm db:migrate`** ——
|
|
||||||
它在 Windows 上不可靠）。要改已有表结构而不只是加列时，可以先用
|
|
||||||
`pnpm exec prisma migrate diff --from-config-datasource --to-schema prisma/schema.prisma --script`
|
|
||||||
生成骨架，再手工补数据搬运语句；
|
|
||||||
3. 改完核对 **`SNAPSHOT_TABLES`**（新增 / 删除表要同步）与 `deleteTeacher` 的护栏清单
|
|
||||||
（它必须覆盖 `Class.teacherId` / `Course.teacherId` / `Homework.createdBy` /
|
|
||||||
`Notification.createdBy` 四项）；
|
|
||||||
再回到 `packages/server/scripts/apply-column-migrations.cjs` 补上可 `ALTER TABLE` 的简单列。
|
|
||||||
|
|
||||||
模型总数与迁移个数会随版本增长，以 `schema.prisma` 与 `prisma/migrations/` 的实际内容为准；
|
|
||||||
本文里的数字标注的是**当前代码库**的状态。
|
|
||||||
@@ -1,52 +0,0 @@
|
|||||||
---
|
|
||||||
title: 开发文档
|
|
||||||
description: ClassHelper的架构、接口、数据模型、权限、动效层，以及验收与发版流程。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 开发文档
|
|
||||||
|
|
||||||
ClassHelper是一个 **pnpm monorepo**，一份代码产出四个交付物：
|
|
||||||
|
|
||||||
| 交付物 | 位置 | 形态 |
|
|
||||||
| ---------- | ------------------------- | --------------------------------------------------------------- |
|
|
||||||
| 后端服务 | `packages/server` | Express 5 + Prisma 7 + Socket.IO，接口前缀 `/api` |
|
|
||||||
| Web 管理端 | `packages/web-admin` | Vue 3 + Vite + Element Plus（教师 / 管理员用，PWA 可安装） |
|
|
||||||
| 桌面客户端 | `packages/desktop-client` | Electron + Vue 3（ClassHelper 班级端 / 教室机器，含灵动岛浮窗） |
|
|
||||||
| 共享契约 | `packages/shared` | 三端共用的类型 / 常量 / 权限 / 工具函数 |
|
|
||||||
|
|
||||||
核心链路：
|
|
||||||
|
|
||||||
```
|
|
||||||
教师在 Web 端发布内容
|
|
||||||
│ REST API（JWT 鉴权）
|
|
||||||
▼
|
|
||||||
后端服务（Express + Prisma）
|
|
||||||
│ 写库 + 按班级房间广播
|
|
||||||
▼
|
|
||||||
Socket.IO ──► class:{classId} 房间 ──► 学生桌面客户端实时更新 UI（含灵动岛）
|
|
||||||
|
|
||||||
▲ │
|
|
||||||
└──── 老师下发的提醒 ◄──────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
## 这一章有什么
|
|
||||||
|
|
||||||
| 页面 | 内容 |
|
|
||||||
| -------------------------------------------- | ------------------------------------------------ |
|
|
||||||
| [架构总览](architecture.md) | 目录结构、技术栈、模块化设计、几条贯穿全局的约定 |
|
|
||||||
| [REST API](api.md) | 全部接口一览（方法 / 路径 / 权限） |
|
|
||||||
| [实时事件（Socket.IO）](realtime.md) | 事件清单、房间规则、新增事件要改哪三处 |
|
|
||||||
| [数据模型](data-model.md) | 24 张表、迁移历史、跨库约定 |
|
|
||||||
| [角色与权限](permissions.md) | 权限矩阵与实现位置 |
|
|
||||||
| [动效层与主题](motion.md) | beUI 令牌、CSS `linear()` 弹簧、深色主题 |
|
|
||||||
| [灵动岛设计令牌](winisland-design-tokens.md) | 岛逐项的几何 / 配色 / 排版 token |
|
|
||||||
| [验收与测试](testing.md) | 五套验收脚本怎么跑、哪些用例是脆弱的 |
|
|
||||||
| [版本迭代与发布](release.md) | 改版本号、出安装包、发 Release 的完整流程 |
|
|
||||||
|
|
||||||
## 仓库里另外两份文档
|
|
||||||
|
|
||||||
- **[完整参考](../reference.md)** —— 产品说明书（原 README 全文），功能行为的**权威来源**；
|
|
||||||
仓库首页那份 README 是精简后的门面页，细节都在这里。
|
|
||||||
- **[`AGENTS.md`](https://github.com/LoveChengke/classhelper/blob/master/AGENTS.md)** ——
|
|
||||||
工程约定与开发环境注意事项，**改代码前必读**。里面每一条硬约定都对应一处容易踩空的地方，
|
|
||||||
比代码注释更值得先看一遍。
|
|
||||||
@@ -1,140 +0,0 @@
|
|||||||
---
|
|
||||||
title: 动效层与主题
|
|
||||||
description: beUI 动效令牌、CSS linear() 弹簧、运行时注入，以及深色主题的实现边界。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 动效层与主题
|
|
||||||
|
|
||||||
## 令牌的单一来源
|
|
||||||
|
|
||||||
两端的动画与过渡统一走一套自研的动效语言，**移植自 [beUI](https://beui.dev) 的 `lib/ease.ts`**。
|
|
||||||
beUI 的组件本身是 React（`motion/react` + Tailwind），用不到这里，**但它的动效语言与框架无关**。
|
|
||||||
|
|
||||||
令牌全部在 `packages/shared/src/motion.ts`：
|
|
||||||
|
|
||||||
| 常量 | 取值 | 用在哪 |
|
|
||||||
| --------------- | --------------------- | ------------------------------ |
|
|
||||||
| `EASE_OUT` | `[0.16, 1, 0.3, 1]` | 绝大多数进出场 |
|
|
||||||
| `EASE_IN_OUT` | `[0.77, 0, 0.175, 1]` | 对称的来回动（抽屉、内容互换） |
|
|
||||||
| `EASE_DRAWER` | `[0.32, 0.72, 0, 1]` | 侧向抽屉 |
|
|
||||||
| `SPRING_PRESS` | 500 / 30 / 0.6 | 按钮、可点表面 |
|
|
||||||
| `SPRING_SWAP` | 460 / 30 / 0.55 | 控件内的内容互换 |
|
|
||||||
| `SPRING_PANEL` | 420 / 40 / 0.5 | 弹窗、抽屉、气泡进场 |
|
|
||||||
| `SPRING_LAYOUT` | 360 / 32 / 0.6 | 共享布局滑动（指示器） |
|
|
||||||
| `SPRING_MOUSE` | 200 / 15 / 0.3 | 光标跟随类装饰动效 |
|
|
||||||
| `SPRING_GLIDE` | 700 / 50 / 0.5 | 拖拽滑块与填充（临界阻尼） |
|
|
||||||
|
|
||||||
弹簧语义与 `motion/react` 一致：`加速度 = (stiffness × 剩余距离 − damping × 当前速度) / mass`。
|
|
||||||
这六组里 PRESS / SWAP / MOUSE 是欠阻尼（有过冲），PANEL / LAYOUT / GLIDE 是过阻尼。
|
|
||||||
|
|
||||||
### 为什么这个文件必须"纯常量 + 纯函数"
|
|
||||||
|
|
||||||
`packages/shared` 会被后端（Express）一起消费，它的 tsconfig 是 `lib: ["ES2023"]`（**不含 DOM**）。
|
|
||||||
所以这里不碰 `document`、不碰 `window`、也不依赖 vue。
|
|
||||||
|
|
||||||
DOM 注入与 Vue 组合式函数在两端各自的 `composables/motion.ts` 里
|
|
||||||
（`useReducedMotion` / `useHoverCapable` / `useCountUp` / `useStaggerIn`）——
|
|
||||||
与 `ScoreBarChart.vue` 一样，两端各一份是这个仓库的既有做法。
|
|
||||||
|
|
||||||
## 弹簧怎么变成 CSS
|
|
||||||
|
|
||||||
不必给每个组件挂一个 rAF 循环：**用数值积分求出落定时间，再生成 CSS `linear()` 缓动字面量**，
|
|
||||||
弹簧就能纯 CSS 驱动。
|
|
||||||
|
|
||||||
几条实现约束：
|
|
||||||
|
|
||||||
| 约束 | 原因 |
|
|
||||||
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
||||||
| 积分步长 1ms、`linear()` 取 60 个采样点 | 60 段肉眼已看不出折线，再密只是徒增样式表体积 |
|
|
||||||
| **落定时间不能用包络公式 `6/(ζ·ω0)`** | 它只对欠阻尼成立；过阻尼要用较慢的实极点 `ω0(ζ−√(ζ²−1))`，否则曲线会被截断在 0.87/0.95 上、元素永远差一截 |
|
|
||||||
| **`--ch-spring-X` 与 `--ch-spring-X-dur` 必须成对用** | `linear()` 是把 [0,1] 进度重映射，时长给短了等于把整条曲线等比压缩 —— 形状还在，但已经不是那组参数的手感了 |
|
|
||||||
| `linear()` 的进度值可以 >1（过冲） | 只能用在不越界无害的属性上。**别用在 `opacity`** |
|
|
||||||
|
|
||||||
### 运行时注入
|
|
||||||
|
|
||||||
两端的 `main.ts` 在 `app.mount()` **之前**把令牌写进 `:root` 的自定义属性
|
|
||||||
（`--ch-ease-*` / `--ch-spring-*` / `--ch-dur-*`）。CSS 里只引用变量，**不抄数值 —— 抄了必漂**。
|
|
||||||
|
|
||||||
> **灵动岛是另一个渲染进程**，不共享主窗口的 `:root`：令牌要在 `src/island/main.ts` 里**再注入一次**。
|
|
||||||
> 漏了的话 `var(--ch-ease-out)` 解析为空、**整条 `transition` 简写作废**，比不改还差（完全没有过渡）。
|
|
||||||
|
|
||||||
## 落地到界面上的效果
|
|
||||||
|
|
||||||
| 位置 | 动效 |
|
|
||||||
| --------------------- | ---------------------------------------------------------------------------------------------- |
|
|
||||||
| Element Plus 全站过渡 | 时长 300/200ms → 200/140ms，缓动换成 `EASE_OUT`（改写 `--el-transition-*` 变量，不动组件源码） |
|
|
||||||
| 弹窗 / 抽屉 / 浮层 | 面板走 `SPRING_PANEL` / `SPRING_SWAP`；**退出一律比入场快** |
|
|
||||||
| 按钮 | 按下 90ms 直落（跟手）、抬起走 `SPRING_PRESS` 弹回 |
|
|
||||||
| 侧栏激活项 | 单个"底片"在菜单项之间滑过去（`SPRING_LAYOUT`） |
|
|
||||||
| 页面内容 | `.page > *` 按块错峰浮现（30ms 一档，封顶 180ms） |
|
|
||||||
| 统计数字 | 0 → 实际值滚动（`useCountUp`） |
|
|
||||||
| 主题切换（两端） | View Transition API：从点击位置扩散的圆整页换肤 |
|
|
||||||
| 灵动岛 | **刻意只有单调缓动，不用弹簧** |
|
|
||||||
|
|
||||||
### 灵动岛为什么不用弹簧
|
|
||||||
|
|
||||||
岛的形变由**主进程**缓动窗口尺寸，而冒烟断言「展开过程不震动」「收回过程不抖动」
|
|
||||||
是**逐帧采样岛体几何**并要求单调的 —— 任何带过冲的弹簧都会直接判红。
|
|
||||||
|
|
||||||
所以岛用 `--ch-ease-out` 这类单调曲线，壳的物理仍归它自己的 `src/island/spring.ts`（WinIsland 移植）。
|
|
||||||
**不要拿 beUI 的 `SPRING_*` 去换**。
|
|
||||||
|
|
||||||
另外岛的 `:hover` 规则必须关在 `@media (hover: hover) and (pointer: fine)` 里 ——
|
|
||||||
教室触摸屏的"幽灵 hover"会让点过「知道了」的按钮永远高亮。
|
|
||||||
|
|
||||||
## 四条硬约束
|
|
||||||
|
|
||||||
| 约束 | 后果 |
|
|
||||||
| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
||||||
| **路由层不要包 `<transition>`**，尤其不要 `mode="out-in"` | ① 点菜单后一小段时间页面上还是上一页；② 退场判定依赖 `animationend`，而**窗口被遮挡时 Chromium 冻结 CSS 动画**，事件永不触发 ⇒ 新页面永远不挂载，整个应用卡死在第一页 |
|
|
||||||
| **Vue 的 `<transition>` 一律显式给 `:duration`** | 同上，靠 `animationend` 判断的写法在窗口不可见时会永远停住 |
|
|
||||||
| **`position: fixed` 的整屏层、以及"自己量几何再据此设尺寸"的元素，不要叠位移类动画** | `getBoundingClientRect()` 包含 transform，而 `clientHeight` / `offsetHeight` 不含 —— 下移 6px 就可能溢出屏幕 |
|
|
||||||
| **弹窗面板的动画挂在 `.el-dialog` 上，不要挂在 `.el-overlay-dialog`** | Element Plus 的 `@opened` 按根元素（只有 200ms 淡入）的动画结束触发，而外层容器的弹簧要跑 463ms —— 在 `@opened` 里量尺寸会量到"还带着 `scale(0.97)` 的缩小版" |
|
|
||||||
|
|
||||||
页面切换的动效因此改成 `.page > *` 错峰入场 —— 那是随组件挂载**同步**触发的，不依赖动画事件。
|
|
||||||
|
|
||||||
## 降低动态效果
|
|
||||||
|
|
||||||
两端各有一个 `@media (prefers-reduced-motion: reduce)` 全局块，把动画压到 **1ms**。
|
|
||||||
|
|
||||||
**是压短而不是 `transition: none`** —— 后者会让依赖 `transitionend` 的逻辑失灵。
|
|
||||||
唯一的例外是**加载指示旋**：它改为放慢而不是停，停掉会让界面看起来像卡死。
|
|
||||||
|
|
||||||
## 主题
|
|
||||||
|
|
||||||
**两端机制完全一致**：在 `<html>` 上挂 `.dark` 类，由各自的样式表覆盖**语义色令牌**，
|
|
||||||
Element Plus 的 `theme-chalk/dark/css-vars.css` 提供 `--el-*` 的深色默认。
|
|
||||||
两端的 `main.ts` 都在挂载前落主题，深色用户首帧才不会看到"先白后黑"。
|
|
||||||
|
|
||||||
### 语义色令牌
|
|
||||||
|
|
||||||
| 令牌 | 用途 |
|
|
||||||
| ------------------------------------------------------ | -------- |
|
|
||||||
| `--ch-surface` / `-alt` / `-sunken` / `-hover` | 表面 |
|
|
||||||
| `--ch-text` / `-secondary` / `-muted` / `-placeholder` | 文字层级 |
|
|
||||||
|
|
||||||
组件里**一律引用这些，不要写死颜色**。自查命令：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
grep -rn "rgba(255, 255, 255\|rgba(0, 0, 0\|#fff" packages/desktop-client/src/renderer
|
|
||||||
```
|
|
||||||
|
|
||||||
除了**明确固定深色**的区域（全屏作业看板、登录页渐变、启动过渡页、灵动岛自身、
|
|
||||||
以及 accent 渐变底上的白字）之外，都应该是变量。
|
|
||||||
|
|
||||||
### 两条纪律
|
|
||||||
|
|
||||||
**`html.dark` 只覆盖颜色，绝不覆盖圆角与动效令牌。** 两套主题的几何必须完全一致，
|
|
||||||
否则切换时会看到布局跳一下。
|
|
||||||
|
|
||||||
**改令牌时只改值，不要对样式表跑批量替换。** "把 `#303133` 全量替换成 `var(--ch-text)`"
|
|
||||||
会把令牌**定义本身**也换成 `--ch-text: var(--ch-text)` —— 自定义属性一旦自引用就整条失效、
|
|
||||||
`getPropertyValue` 返回空串，全站文字颜色静默回落成继承色（浅色下看着"还行"，深色下才露馅）。
|
|
||||||
|
|
||||||
Web 端还要一并同步 `<meta name="theme-color">` 与 `color-scheme` —— 后者管**原生控件**
|
|
||||||
（滚动条、日期选择器弹层、自动填充底色），只改 CSS 变量的话它们仍是浅色。
|
|
||||||
|
|
||||||
### 刻意固定深色的区域
|
|
||||||
|
|
||||||
登录页的深色渐变底、桌面端的启动过渡页与全屏作业看板、灵动岛自身、Web 管理端的侧边栏
|
|
||||||
（本来就是深色）、以及深色底上的白色文字。**改它们会被当成回归。**
|
|
||||||
@@ -1,183 +0,0 @@
|
|||||||
---
|
|
||||||
title: 角色与权限
|
|
||||||
description: 权限矩阵、科目维度的收口规则，以及"前端隐藏 ≠ 权限"这条纪律。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 角色与权限
|
|
||||||
|
|
||||||
## 矩阵在哪
|
|
||||||
|
|
||||||
**唯一一份**在 `packages/shared/src/permissions.ts`：
|
|
||||||
|
|
||||||
- 后端 `lib/access.ts` 复用它做断言；
|
|
||||||
- 两端前端用它隐藏入口；
|
|
||||||
- 验收脚本按它逐条断言。
|
|
||||||
|
|
||||||
所以不存在"前端一套后端一套"。改权限就改这一个文件（改完记得 `pnpm build:shared`）。
|
|
||||||
|
|
||||||
## 角色判定
|
|
||||||
|
|
||||||
角色只有三种，**没有 `STUDENT`** —— 学生不是账号（见[数据模型](data-model.md)）。
|
|
||||||
班级内的角色由「账号角色 + 与该班级的关系」共同决定：
|
|
||||||
|
|
||||||
| 角色 | 判定方式 | 可见范围 |
|
|
||||||
| --------------------- | ---------------------------------------- | -------------------------- |
|
|
||||||
| `ADMIN` 管理员 | `User.role = ADMIN` | 全部班级 |
|
|
||||||
| 班主任 `HEAD` | `Class.teacherId === 当前用户` | 本班 |
|
|
||||||
| 科任老师 `SUBJECT` | 该班存在 `Course.teacherId === 当前用户` | 被任课的班级 |
|
|
||||||
| `CLASS_DEVICE` 班级端 | 班级码 + 班级密码登录（`classSession`） | 本班（代全班读写个人数据） |
|
|
||||||
| `NONE` | 与这个班没有任何关系 | 什么都看不到 |
|
|
||||||
|
|
||||||
判定函数是 `resolveClassRole()`。「科任」的判定源是 **`Course`**（班级 + 科目 + 教师），
|
|
||||||
不是那张已经没有的 `ClassTeacher` 协作表。
|
|
||||||
|
|
||||||
## 权限矩阵
|
|
||||||
|
|
||||||
下表描述角色与班级关系允许的范围；员工还必须拥有对应功能权限，管理员也不例外。
|
|
||||||
名单读取使用 `roster:read` / `teacher:read`，管理使用独立的 `roster:manage` / `teacher:manage`。
|
|
||||||
日志与客户端开发者模式不再单列无效权限键，服务端系统设置由 `system:manage` 控制。
|
|
||||||
|
|
||||||
| 操作 | 管理员 | 班主任 | 科任老师 | 班级端 |
|
|
||||||
| ----------------------------------------------------------- | :----: | :----------: | :------: | :--------: |
|
|
||||||
| 班级创建 / 修改 / 删除 | ✅ | ❌ | ❌ | ❌ |
|
|
||||||
| 分配班主任与各科任课老师 | ✅ | ❌ | ❌ | ❌ |
|
|
||||||
| 学生名单管理（增删 / 导入 / 调班 / 转出） | ✅ | ✅（仅本班） | ❌ | ❌ |
|
|
||||||
| 教师录入（新建 / 导入名单 / 修改密码） | ✅ | ❌ | ❌ | ❌ |
|
|
||||||
| 毕业归档 / 学年升级 / 学期周次 | ✅ | ❌ | ❌ | ❌ |
|
|
||||||
| 数据库管理（备份 / 导入导出 / 一键切换） | ✅ | ❌ | ❌ | ❌ |
|
|
||||||
| 课表管理（增删改 / 时间配置导入） | ✅ | ✅（仅本班） | ❌ | ❌ |
|
|
||||||
| 布置作业（**自己任教的科目**） | ✅ | ✅（本班） | ✅ | ✅ |
|
|
||||||
| 叫人 / 发布通知 | ✅ | ✅ | ✅ | ✅ |
|
|
||||||
| 成绩录入 / 修改 / 导入（**自己任教的科目**） | ✅ | ✅（本班） | ✅ | ❌ |
|
|
||||||
| 查看本班成绩汇总 | ✅ | ✅ | ✅ | ✅ |
|
|
||||||
| 按学号查询学生成绩明细 | ✅ | ✅ | ✅ | 需班级开关 |
|
|
||||||
| 查看 ClassHelper 班级端在线状态 | ✅ | ✅ | ✅ | ❌ |
|
|
||||||
| 班级密码 / 班级码维护（`PATCH /classes/:id/class-account`） | ✅ | ❌ | ❌ | ❌ |
|
|
||||||
|
|
||||||
## 科目维度的收口（本次重构的核心规则）
|
|
||||||
|
|
||||||
作业与成绩不是"凡是能进这个班就能改"，而是**再按科目收一道**：
|
|
||||||
|
|
||||||
| 情形 | 谁可以写 |
|
|
||||||
| --------------------------- | ------------------------------------------------------ |
|
|
||||||
| 管理员 | 全部 |
|
|
||||||
| 挂了科目（`courseId` 有值） | **该科的任课老师**（`Course.teacherId`） |
|
|
||||||
| 没挂科目（`courseId` 为空） | 本班**班主任** |
|
|
||||||
| ClassHelper 班级端 | 只有**作业**可以（老师在教室随手录一条）；**成绩不给** |
|
|
||||||
|
|
||||||
于是：班主任若不教这一科，就改不了这一科的作业与成绩 —— 这正是需求
|
|
||||||
「班主任不自动拥有所有科目作业成绩编辑权，只有同时是该科科任老师时才有该科权限」。
|
|
||||||
|
|
||||||
实现在 `lib/access.ts` 的 **`assertCanManageSubjectContent(user, classId, courseId, action, { allowClassDevice })`**，
|
|
||||||
作业 / 成绩 / 叫人三处写入统一走它。
|
|
||||||
|
|
||||||
## 权限键与权限组（2026-10 起：权限组驱动，角色只是默认模板）
|
|
||||||
|
|
||||||
从权限组重构开始，**功能级准入不再看角色，而看权限键**：键目录同样是
|
|
||||||
`packages/shared/src/permissions.ts` 的 `PERMISSION_KEYS`（37 个，形如 `domain:action`，
|
|
||||||
中文名在 `PERMISSION_LABELS`、分组在 `PERMISSION_CATEGORIES`）。路由上挂的是
|
|
||||||
|
|
||||||
```ts
|
|
||||||
requirePermission('notification:publish'); // 需要全部列出的键
|
|
||||||
requireAnyPermission('grade:write', 'grade:import'); // 有任意一个即可
|
|
||||||
```
|
|
||||||
|
|
||||||
**生效规则（四句话）**：
|
|
||||||
|
|
||||||
| 账号 | 有效权限 |
|
|
||||||
| ------------------------ | ----------------------------------------------------------------------- |
|
|
||||||
| `ADMIN` | 按权限组计算；其中 `permission:manage` / `system:manage` **不可被剥夺** |
|
|
||||||
| `CLASS_DEVICE`（班级端） | 空集，**不受任何分组影响**（它的能力来自班级维度断言） |
|
|
||||||
| 被分配了权限分组 | 分组键的**并集**（可以比角色默认更少 —— 这就是"能收权"） |
|
|
||||||
| 没有被分配任何分组 | 使用可编辑的角色默认权限组 |
|
|
||||||
|
|
||||||
默认模板逐条镜像重构前的 `requireRole`，所以"不动分组"= 行为与以前完全一致。
|
|
||||||
实现见 `packages/server/src/lib/permissions.ts` 的 `loadEffectivePermissions()`：它**每个请求实时查库**
|
|
||||||
（不缓存），因此管理员改完分组**立刻生效**，不需要等令牌过期 —— 与下面「鉴权中间件会回查数据库」是同一个理由。
|
|
||||||
|
|
||||||
**管理接口**（`packages/server/src/modules/permissions/`）：
|
|
||||||
|
|
||||||
| 方法与路径 | 权限要求 | 说明 |
|
|
||||||
| --------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------- |
|
|
||||||
| `GET /api/permissions/me` | 登录即可 | 当前账号的有效权限与来源（前端据此显示/隐藏入口） |
|
|
||||||
| `GET /api/permissions/catalog` | `permission:manage` | 全部权限键（含中文名、分类、默认角色、不可移除标记） |
|
|
||||||
| `GET/POST /api/permissions/groups`、`PATCH/DELETE /groups/:id` | `permission:manage` | 分组 CRUD；内置分组（`builtin=true`）可改不可删 |
|
|
||||||
| `GET /api/permissions/users`、`PUT /api/permissions/users/:id/groups` | `permission:manage` | 成员列表与「整组替换」式分配；管理员与教师可分配；班级端不参与 |
|
|
||||||
|
|
||||||
**一条不能松的边界**：权限组只管**功能/路由级**准入；**班级维度的科目规则不可被权限组覆盖**。
|
|
||||||
换句话说，给某人授了 `homework:write` 只代表"他能进布置作业这条路由"，
|
|
||||||
**具体到哪个班、哪个科目**仍然由 `assertCanManageSubjectContent` 判（下一节）。
|
|
||||||
否则「班主任能布置别人科目的作业」这个老 bug 会从权限组这条新路重新长出来。
|
|
||||||
|
|
||||||
## 实现要点
|
|
||||||
|
|
||||||
**路由级只做权限过滤**：`requirePermission('…')`（需要列出的键全有）或
|
|
||||||
`requireAnyPermission('…')`（任意一个即可）。改造前这里是 `requireRole('ADMIN','TEACHER')`，
|
|
||||||
按键目录里的 `PERMISSION_DEFAULT_ROLES` 逐条映射过来，因此**默认行为没有变化**。
|
|
||||||
403 的文案会直接点名缺哪个键：「当前账号缺少「X」权限，请联系管理员在「权限组」里分配」。
|
|
||||||
|
|
||||||
**班级维度的判断在服务层**：`src/lib/access.ts` 提供
|
|
||||||
|
|
||||||
```
|
|
||||||
assertCanManageClasses / assertCanAssignTeachers / assertCanManageRoster
|
|
||||||
assertCanManageSchedule / assertCanPublishNotification
|
|
||||||
assertCanManageGrades / assertCanManageSubjectContent
|
|
||||||
```
|
|
||||||
|
|
||||||
**列表数据用 `resolveClassScope()` 收敛**（`classId in [...]`），单条接口直接断言；
|
|
||||||
越权一律 403。
|
|
||||||
|
|
||||||
**鉴权中间件会回查数据库**（`middleware/auth.ts`）：JWT 校验之后重新读一次账号，
|
|
||||||
所以改了角色 / 班级关系会**立即生效**，不用等令牌过期。班级端会话则回查 `Class` 表。
|
|
||||||
|
|
||||||
**班级端的成绩查询开关**：`Class.studentGradeQueryEnabled`（默认开启）。
|
|
||||||
关闭后班级端调 `GET /grades/student/:studentNo` 一律 403，教师端不受影响 ——
|
|
||||||
这就是需求「是否允许学生通过班级端查看本人明细，由教师或管理员开关控制」。
|
|
||||||
|
|
||||||
## 前端隐藏 ≠ 权限
|
|
||||||
|
|
||||||
前端的隐藏只是"别让人看见入口"：
|
|
||||||
|
|
||||||
- 教师登录时侧边栏不显示「班级管理 / 学生管理 / 教师管理 / 毕业归档 / 学期周次 / 数据库管理 / 权限组 / 客户端设备」；
|
|
||||||
- 课表页的增删改按钮只对「管理员或本班班主任」显示；
|
|
||||||
- 成绩页的录入 / 删除按钮对教师显示（科任也能用，**具体到某一条由后端按科目判定**）。
|
|
||||||
|
|
||||||
**门控怎么写的**：路由 `meta.roles` 做粗筛（角色），`meta.permission` 做细筛（权限键）——
|
|
||||||
`packages/web-admin/src/router/index.ts` 的 `beforeEach` 会 `await auth.ensurePermissions()`
|
|
||||||
再问 `auth.can(key)`（管理员同样按生效集合判断，仅保留权限和系统管理入口），不通过就 **fail-closed** 回仪表盘；
|
|
||||||
侧栏菜单项同理带 `permission` 字段（`AdminLayout.vue` 的 `visibleMenuItems`）。
|
|
||||||
`auth.ensurePermissions()` 读的就是 `GET /api/permissions/me`。
|
|
||||||
|
|
||||||
但这些页面**直接输网址也进不去**（路由 `meta.roles` 会把非管理员挡回仪表盘），
|
|
||||||
而且**所有写入请求服务端都会再断言一次**。绕过菜单、绕过前端，一样 403。
|
|
||||||
|
|
||||||
> 新增视图时别忘了两处：路由的 `meta.roles` + 服务层对应 service 里的 `assertCanXxx`。
|
|
||||||
> 只做其中一个都等于没做。
|
|
||||||
|
|
||||||
## 学生没有账号的两个反向约束
|
|
||||||
|
|
||||||
1. **学生不能登录，而且根本不存在可以登录的学生账号**。`User` 表里没有学生行，
|
|
||||||
拿学号当账号登录只会得到 401（"工号或密码错误"），连"这个学号存在吗"都探测不出来。
|
|
||||||
2. **学生没有任何密码接口**。`POST /students/:id/reset-password` 已删除（调用返回 404），
|
|
||||||
新建学生也不设密码 —— `Student` 表里压根没有那一列。
|
|
||||||
|
|
||||||
## 默认权限组与客户端维护（2026-10-16）
|
|
||||||
|
|
||||||
管理员和教师各有一个默认权限组；未分配其他组时使用对应默认组，编辑后立即生效。
|
|
||||||
默认组可以改名、增减权限，但不能删除。分配多个组时取并集。
|
|
||||||
管理员始终保留 `permission:manage` 和 `system:manage`，防止失去管理入口。
|
|
||||||
班级端不参与账号权限组，班级与科目范围的检查保持生效。
|
|
||||||
|
|
||||||
「客户端」页统一显示设备心跳、版本、是否接受自动更新、最近指令结果和安装时机。
|
|
||||||
更新先从本服务器下载并校验 SHA256，再按所选时机安装：
|
|
||||||
|
|
||||||
- 立即更新：下载完成后安装并重启客户端，会中断当前客户端界面。
|
|
||||||
- 放学后更新：按服务器当天日期，等待所选最早时间与本班最后一节课结束时间的较晚者；上课中继续等待。
|
|
||||||
- 空闲时更新：不上课且主窗口隐藏满五分钟后安装。
|
|
||||||
|
|
||||||
离线设备上线后补领更新；取消下发后，已下载的安装包不再自动安装。
|
|
||||||
客户端关闭自动更新时，任何下发策略都不会强制安装。
|
|
||||||
远控关机、重启、注销和锁屏仍需管理端确认及本机确认，取消或系统执行失败都会回执。
|
|
||||||
|
|
||||||
联动插件及相关接口已下线；升级迁移会删除旧联动设备和推送记录，保留业务课表、通知及离线 JSON 导入。
|
|
||||||
服务端兼容旧客户端的心跳字段读取，旧设备可领取修复版；第一次升级仍遵循旧版空闲安装条件，新策略需修复版客户端。
|
|
||||||
@@ -1,79 +0,0 @@
|
|||||||
---
|
|
||||||
title: 实时事件（Socket.IO）
|
|
||||||
description: 事件清单、房间规则，以及新增一个实时事件要同时改哪三处。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 实时事件（Socket.IO）
|
|
||||||
|
|
||||||
## 连接
|
|
||||||
|
|
||||||
```ts
|
|
||||||
io(url, { auth: { token } }); // 握手阶段用 JWT 鉴权
|
|
||||||
```
|
|
||||||
|
|
||||||
客户端断线由 Socket.IO 自动重连。教室机器断线期间的变更，重连后靠各页重新拉取补齐
|
|
||||||
（客户端在检测到服务器恢复时会触发 `onServerRecovered`）；**灵动岛的上课时段暂存通知**由服务端保留、
|
|
||||||
下课后补发，不依赖重连。
|
|
||||||
|
|
||||||
## 事件清单
|
|
||||||
|
|
||||||
事件名定义在 `@classhelper/shared` 的 `SOCKET_EVENTS` —— **不要手写字符串**。
|
|
||||||
|
|
||||||
| 事件 | 方向 | 载荷 |
|
|
||||||
| ------------------------------------- | --------------- | ------------------------------------------------ |
|
|
||||||
| `connected` | 服务端 → 客户端 | `{ userId, role, rooms }` |
|
|
||||||
| `notification:new` | 服务端 → 客户端 | `NotificationDto` |
|
|
||||||
| `homework:new` | 服务端 → 客户端 | `HomeworkDto` |
|
|
||||||
| `homework:updated` | 服务端 → 客户端 | `HomeworkDto & { deleted?: boolean }` |
|
|
||||||
| `homework:status` | 服务端 → 客户端 | `HomeworkStatusDto & { classId }` |
|
|
||||||
| `grade:updated` | 服务端 → 客户端 | `GradeDto` |
|
|
||||||
| `schedule:updated` | 服务端 → 客户端 | `{ classId, action, schedule? }` |
|
|
||||||
| `class:updated` | 服务端 → 客户端 | `{ classId, action }` |
|
|
||||||
| `call:new` | 服务端 → 客户端 | 叫人消息（定向到 `user:{studentId}` / 班级设备） |
|
|
||||||
| `class:join` / `class:leave` / `ping` | 客户端 → 服务端 | 手动订阅班级（服务端二次校验权限） |
|
|
||||||
|
|
||||||
## 房间规则
|
|
||||||
|
|
||||||
房间名定义在 `SOCKET_ROOMS`：
|
|
||||||
|
|
||||||
| 房间 | 谁在里面 |
|
|
||||||
| --------------------- | --------------------------------- |
|
|
||||||
| `class:{classId}` | 这个班的所有在线端 |
|
|
||||||
| `user:{userId}` | 某个用户自己的连接 |
|
|
||||||
| `teacher:{teacherId}` | 某个教师 |
|
|
||||||
| `role:{role}` | 某一角色（`ADMIN` / `TEACHER` …） |
|
|
||||||
| `students` | 全部 ClassHelper 班级端连接 |
|
|
||||||
| `teachers` | 全部教师端连接 |
|
|
||||||
|
|
||||||
服务端通过 `realtime/bus.ts` 的 `emitToClass` / `emitToUser` 发事件 ——
|
|
||||||
**业务模块不直接依赖 Socket.IO 实例**，只依赖事件总线。
|
|
||||||
|
|
||||||
## 新增一个实时事件要改三处
|
|
||||||
|
|
||||||
```
|
|
||||||
① 服务端 shared/src/constants.ts 的 SOCKET_EVENTS 加常量
|
|
||||||
→ business service 调 bus.emitToXxx(...)
|
|
||||||
→ realtime/socket.ts 房间映射（如果需要新房间）
|
|
||||||
② Web 端 web-admin/src/stores/realtime.ts 订阅
|
|
||||||
③ 客户端 desktop-client/src/renderer/stores/realtime.ts 订阅
|
|
||||||
→ 灵动岛也依赖它（renderer/island/bridge.ts）
|
|
||||||
```
|
|
||||||
|
|
||||||
**只改服务端不会报错**，只是前端静静地不更新 —— 所以这三处必须一起改。
|
|
||||||
事件名一律取自共享常量，不要手写字符串（拼错一个字就是一个静默失效）。
|
|
||||||
|
|
||||||
## 事件到达之后发生什么
|
|
||||||
|
|
||||||
以通知为例：
|
|
||||||
|
|
||||||
```
|
|
||||||
服务端写库 → bus.emitToClass(classId, notification:new)
|
|
||||||
├─► Web 端 stores/realtime.ts → 通知列表刷新
|
|
||||||
└─► 客户端 stores/realtime.ts → 更新内存状态 + 写回 IndexedDB
|
|
||||||
└─► island/bridge.ts → pushNotificationToIsland()
|
|
||||||
└─► 主进程 IslandController 决定：隐藏 / 胶囊 / 详情
|
|
||||||
└─► 灵动岛渲染进程 IslandApp.vue
|
|
||||||
```
|
|
||||||
|
|
||||||
上课时段的取舍（隐藏还是立即展开）由主进程的 `IslandController` 按当前上课状态决定，
|
|
||||||
见[通知与提醒](../app/notifications.md)与[灵动岛](../app/island.md)。
|
|
||||||
@@ -1,235 +0,0 @@
|
|||||||
---
|
|
||||||
title: 版本迭代与发布
|
|
||||||
description: 改版本号、跑验收、打安装包、发 GitHub Release、发布文档站——一次完整发布的命令清单。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 版本迭代与发布
|
|
||||||
|
|
||||||
## 一条总原则
|
|
||||||
|
|
||||||
> **版本号按「发布」迭代，不按「提交」迭代。**
|
|
||||||
|
|
||||||
日常的 `feat` / `fix` 提交**不动版本号**。只有当你要产出一批安装包、在 GitHub 上开一个 Release 时，
|
|
||||||
更新检查接口全都按版本号对齐；每次提交都动它，等于每天都在发版，用户那边的「检查更新」就废了。
|
|
||||||
|
|
||||||
| 算一次发布 | 不算 |
|
|
||||||
| --------------------------------------- | ---------------------------- |
|
|
||||||
| 攒够一批功能 / 修好一个用户能感知的 bug | 改注释、改文档、重构、加测试 |
|
|
||||||
| 要给别人一份新安装包 | 只在自己机器上跑 |
|
|
||||||
|
|
||||||
## 每次发版必须一起交付的四样东西
|
|
||||||
|
|
||||||
打安装包只是其中一件。**少一样都算「发到一半」**：
|
|
||||||
|
|
||||||
| # | 交付物 | 落在哪 | 怎么做 |
|
|
||||||
| --- | ------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
||||||
| ① | **更新日志** | GitHub Release 的正文 | 手写，草稿放 `releases/ReleaseNotes-<版本>.md`，用 `--notes-file` 发布。别只挂自动生成的列表 |
|
|
||||||
| ② | **Linux 服务端包** | Release 上的 `classhelper-server-linux-x64-<版本>.tar.gz` | tag 推上去由 CI 构建；**推完去 Actions 确认没红**（见第 7 步） |
|
|
||||||
| ③ | **文档** | `docs/reference.md`（功能说明 + 验收对照表）与相关章节 | 新增功能补对应小节；改交付形态一并改第 2 章 / 第 7 章 |
|
|
||||||
| ④ | **官网与 README** | `website/index.html`、`website/download.html`、`README.md` | 新功能补进官网功能块与 README 功能清单；版本号由脚本覆盖 |
|
|
||||||
|
|
||||||
更新日志的骨架（照 1.2.0 / 1.3.0 那两份写）：
|
|
||||||
**一句话定位 → 分节讲功能 → ⚠️ 升级须知（含会自动应用的迁移）→ 验收表 → 产物表**。
|
|
||||||
验收表里**只写真跑过的数字**，没跑就直说没跑，不要照抄上一版的。
|
|
||||||
|
|
||||||
## 版本号写在哪（12 处 / 12 个文件）
|
|
||||||
|
|
||||||
同一个版本号分散在 12 个落点上，**手工改必然漏一处**，而漏掉的那处不会报错：
|
|
||||||
|
|
||||||
| 文件 | 内容 |
|
|
||||||
| ---------------------------------------------------------------- | ---------------------------------- |
|
|
||||||
| `package.json` | 单一来源（服务端运行时读它） |
|
|
||||||
| `packages/{shared,server,web-admin,desktop-client}/package.json` | 各包的版本 |
|
|
||||||
| `deploy/package.runtime.json` | 安装包 / 容器里的运行时依赖清单 |
|
|
||||||
| `deploy/docker-compose.yml`、`docker-compose.sqlite.yml` | 镜像 tag 的默认值 |
|
|
||||||
| `website/index.html` × 3 | 官网顶栏徽标 / 首屏芯片 / 页脚 |
|
|
||||||
| `website/download.html`（`<meta name="ch-version">`） | 下载页读不到版本清单时的兜底版本号 |
|
|
||||||
|
|
||||||
最后两行值得单独说：官网是**纯静态站、没有构建步骤**，没有哪段代码会去读 `package.json`，
|
|
||||||
所以那几处只能靠脚本一起改 —— 漏了的话首页会一直挂着旧版本号（而那是别人看到的第一眼），
|
|
||||||
下载页则会给离线访客一串指向**不存在版本**的直链。
|
|
||||||
|
|
||||||
所以**改版本号的唯一入口是脚本**：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm version:check # 逐处列出并比对，不一致 exit 1
|
|
||||||
pnpm version:bump patch # 1.1.2 → 1.1.3
|
|
||||||
pnpm version:bump minor # 1.1.2 → 1.2.0
|
|
||||||
pnpm version:bump major # 1.1.2 → 2.0.0
|
|
||||||
pnpm version:check # 再确认一次
|
|
||||||
```
|
|
||||||
|
|
||||||
脚本按表逐个改写，**任何一处没匹配到或匹配到多处就直接失败退出**，不做"尽力而为"的部分改写。
|
|
||||||
|
|
||||||
## 一次完整的发布
|
|
||||||
|
|
||||||
下面这一串命令就是全部流程，逐条照抄即可。
|
|
||||||
|
|
||||||
### 1. 改版本号
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm version:check
|
|
||||||
pnpm version:bump patch
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 本地体检
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm lint
|
|
||||||
pnpm typecheck
|
|
||||||
pnpm check:icons
|
|
||||||
pnpm docs:check # 文档站构建（警告即失败）
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 跑验收
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm dev:server # 另开一个终端跑着
|
|
||||||
|
|
||||||
pnpm verify:e2e
|
|
||||||
|
|
||||||
pnpm build:desktop && pnpm verify:desktop
|
|
||||||
pnpm build && pnpm verify:web
|
|
||||||
```
|
|
||||||
|
|
||||||
哪一项红了先看[验收与测试](testing.md)的「失败时先别改代码」——
|
|
||||||
里面列了几个已知脆弱的用例，它们红不代表代码坏了。
|
|
||||||
|
|
||||||
### 4. 打安装包
|
|
||||||
|
|
||||||
```bash
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
产物落在 `releases/<组件>/<版本>/`：`安装包/`（交付物）、`构建中间/`（可重新生成）。
|
|
||||||
**没有免安装目录** —— 组装/解包出来的那一份是中间物，打包脚本用完就删（见仓库根 `AGENTS.md` §4
|
|
||||||
「交付产物归集」）。
|
|
||||||
|
|
||||||
打完之后**对打包副本再验一次**（开发产物通过 ≠ 用户机器上的副本通过）：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 默认指向装好的客户端；推荐直接拿刚打出来的便携版单文件当被测副本
|
|
||||||
pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版本>-x64-portable.exe"
|
|
||||||
```
|
|
||||||
|
|
||||||
> Linux 包**只能在 Linux 上构建**（依赖是平台相关的），所以不在这条命令里 ——
|
|
||||||
> 它由 GitHub Actions 出，见第 7 步。
|
|
||||||
|
|
||||||
### 5. 生成跨组件哈希清单
|
|
||||||
|
|
||||||
`releases/SHA256SUMS-<版本>.txt` 是**人读的**（表头 + 体积 + 说明），由发布流程维护，
|
|
||||||
本地只写 Windows那几行：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd releases/client/<版本>/安装包 && sha256sum *.exe > ../../../SHA256SUMS-<版本>.txt # 按实际文件名整理
|
|
||||||
```
|
|
||||||
|
|
||||||
（Linux 那一行由 CI 在第 7 步里**合并**进去，不要手工写。）
|
|
||||||
|
|
||||||
### 6. 提交并推上去
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add -A
|
|
||||||
git commit -m "chore(release): 1.1.3"
|
|
||||||
git push origin master
|
|
||||||
```
|
|
||||||
|
|
||||||
提交信息用 Conventional Commits + 模块 scope，描述写中文，可多 scope，例如
|
|
||||||
`fix(island): 胶囊"点不动"的根因——窗口必须始终可激活`。
|
|
||||||
|
|
||||||
### 7. 开 Release
|
|
||||||
|
|
||||||
上传前先把产物改成 ASCII 名 —— 构建产物是中文名，Release 上的名字是给别人看、要贴进脚本的：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
V=1.1.3
|
|
||||||
mkdir -p .cache/release-staging
|
|
||||||
cp "releases/client/$V/安装包/"*-x64-setup.exe ".cache/release-staging/ClassHelper-$V-x64-client-setup.exe"
|
|
||||||
cp "releases/client/$V/安装包/"*-x64-portable.exe ".cache/release-staging/ClassHelper-$V-x64-client-portable.exe"
|
|
||||||
cp "releases/server/$V/安装包/"*-x64-setup.exe ".cache/release-staging/ClassHelper-$V-x64-server-setup.exe"
|
|
||||||
|
|
||||||
gh release create v$V --title "ClassHelper v$V（<一句话定位>）" --notes-file "releases/ReleaseNotes-$V.md"
|
|
||||||
gh release upload v$V .cache/release-staging/* "releases/SHA256SUMS-$V.txt" --clobber
|
|
||||||
```
|
|
||||||
|
|
||||||
| 构建产物 | Release 上的名字 |
|
|
||||||
| --------------------------- | -------------------------------------------- |
|
|
||||||
| `<客户端>-x64-setup.exe` | `ClassHelper-<版本>-x64-client-setup.exe` |
|
|
||||||
| `<客户端>-x64-portable.exe` | `ClassHelper-<版本>-x64-client-portable.exe` |
|
|
||||||
| `<服务端>-x64-setup.exe` | `ClassHelper-<版本>-x64-server-setup.exe` |
|
|
||||||
|
|
||||||
这三个名字是**外部契约**：README 的「开始使用」表、官网下载页读不到版本清单时拼的兜底直链，
|
|
||||||
都按它们写；改名要三处一起改。
|
|
||||||
|
|
||||||
`gh release create` 会**创建 tag 并推送**，这一步会自动触发
|
|
||||||
[`release-linux-server.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/release-linux-server.yml)
|
|
||||||
构建 Linux 包（ubuntu runner）。它跑完之后会：
|
|
||||||
|
|
||||||
1. 把 `classhelper-server-linux-x64-<版本>.tar.gz` 与 `.sha256` 挂到 Release 上；
|
|
||||||
2. **把 Linux 那一行合并进** `SHA256SUMS-<版本>.txt`（保留 Windows那几行）。
|
|
||||||
|
|
||||||
> **顺序很重要**：Linux workflow 是在最后一步才去合并 SHA256SUMS 的，
|
|
||||||
> 所以第 5 步那份清单必须**先上传**。万一手速反了（workflow 先跑完、你后上传），
|
|
||||||
> 重新跑一次 `gh workflow run release-linux-server.yml -f tag=v1.1.3 -f attach=true` 就能把那一行补回来。
|
|
||||||
|
|
||||||
想手动触发（比如只需要重出 Linux 包）：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
gh workflow run release-linux-server.yml -f tag=v1.1.3 -f attach=true
|
|
||||||
```
|
|
||||||
|
|
||||||
> **CI 是按 tag 的 ref 检出源码的。** 发完版又发现构建脚本（或任何影响出包的代码）要修时，
|
|
||||||
> **光推 master 不够** —— CI 仍会拿旧 tag 的源码跑，得把 tag 挪到修复后的提交：
|
|
||||||
> `git tag -f v<版本> <提交> && git push --force origin v<版本>`，tag 一变会自动重跑。
|
|
||||||
> 别拿「Windows 侧绿不绿」当判据：`pnpm dist:server` 走的是另一条分支，
|
|
||||||
> Linux 那一步红的时候本地完全看不出来。
|
|
||||||
>
|
|
||||||
> 另外，本页第 8 步的「官网与文档站」是**另一条**流水线（master 推送触发）——
|
|
||||||
> 它绿不代表 Linux 包出来了，推完 tag 要去 `gh run list --limit 5` 看一眼。
|
|
||||||
|
|
||||||
### 8. 官网与文档站
|
|
||||||
|
|
||||||
**不用做任何事。** 推送 master 时只要 `website/**`、`docs/**`、`scripts/build-pages.mjs` 或
|
|
||||||
`package.json` 变过，
|
|
||||||
[`pages.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/pages.yml)
|
|
||||||
就会把两者构建成**同一个** GitHub Pages 站点发出去：
|
|
||||||
|
|
||||||
```
|
|
||||||
https://lovechengke.github.io/ClassHelper/ ← 官网
|
|
||||||
https://lovechengke.github.io/ClassHelper/docs/ ← 文档站
|
|
||||||
```
|
|
||||||
|
|
||||||
（一个仓库在 Pages 上只有一个站点，所以是拼在一起发的 —— 官网在根、文档站在 `/docs/` 下。）
|
|
||||||
|
|
||||||
文档站顶栏的版本徽标取自根 `package.json`，所以第 1 步改完就跟着变了；
|
|
||||||
官网首屏那排芯片、顶栏徽标与页脚里的版本号，以及下载页那个兜底版本号，
|
|
||||||
也都是**由 `pnpm version:bump` 一起改的**（它们是那 12 个落点里的四个）。
|
|
||||||
|
|
||||||
> 官网的「立即下载」会跳到 `/download.html`，那一页的版本清单是**当场**从 GitHub Releases 读的
|
|
||||||
> （读不到才退回上面那个兜底版本号），所以发完 Release 不用重新部署那一页 —— 但**兜底值要跟着发版一起改**，
|
|
||||||
> 不然离线访客点到的就是旧版本的直链。
|
|
||||||
|
|
||||||
### 9. 检查
|
|
||||||
|
|
||||||
- [ ] Release 页面上三个组件都在，`SHA256SUMS-<版本>.txt` 里 Windows / Linux 三种行齐全；
|
|
||||||
- [ ] 文档站能打开，顶栏版本号是新版；
|
|
||||||
- [ ] 装一台机器试一遍（或至少跑 `pnpm verify:packaged`）。
|
|
||||||
|
|
||||||
## 回滚
|
|
||||||
|
|
||||||
发布出去之后发现严重问题：
|
|
||||||
|
|
||||||
| 情形 | 做法 |
|
|
||||||
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
||||||
| 只是文档 / Release 说明写错 | 直接改 Release 说明或重发文档站（`gh workflow run docs.yml`） |
|
|
||||||
| 二进制有问题 | 删掉 Release 与 tag（`gh release delete v1.1.3 --cleanup-tag`），修完重新发；**不要**拿同一个版本号发第二次内容不同的包 |
|
|
||||||
| 用户已经装了 | 发一个**新版本号**（`pnpm version:bump patch`）修复，不要原地改 |
|
|
||||||
|
|
||||||
> 已经发出去的版本号**不要复用**：客户端把它记进「忽略此版本」，服务端与 Web 端各有 30 分钟缓存，
|
|
||||||
> 同号换内容会让"检查更新"永久失灵。
|
|
||||||
|
|
||||||
## 相关
|
|
||||||
|
|
||||||
- 文档站本身怎么写的 → [架构总览的目录结构](architecture.md)
|
|
||||||
- 验收脚本与脆弱用例 → [验收与测试](testing.md)
|
|
||||||
- 各形态升级的**用户侧**步骤 → [更新与升级](../management/upgrade.md)
|
|
||||||
@@ -1,50 +0,0 @@
|
|||||||
---
|
|
||||||
title: 2026-10-17 审查修复记录
|
|
||||||
description: 按审查报告核对缺陷、修复行为与验收方式。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 2026-10-17 审查修复记录
|
|
||||||
|
|
||||||
本次按仓库根的代码审查报告逐项核对，保留此前联动退役与更新策略改动。
|
|
||||||
|
|
||||||
| 报告条目 | 处理结果 |
|
|
||||||
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
||||||
| 0.1 | 环境文档补充 PATH 与 Git Bash 启动方式；变更文档统一格式化。 |
|
|
||||||
| 1.1 | 恢复学期周次、毕业归档、权限组菜单，开发期检查路由是否遗漏菜单。 |
|
|
||||||
| 1.2 | 叫人通知写本地所属日期；启动时分批幂等回填旧通知，兼容 SQLite / MySQL。 |
|
|
||||||
| 1.3、2.14、3.10、3.14、4.5 | 每次建窗挂关闭隐藏处理；捕获加载失败；仅主窗口触发恢复，恢复期间等待异步加载；普通 Promise 拒绝不再重启进程，移除 activate 重复加载。 |
|
|
||||||
| 1.4、1.5 | 缓存按服务端和班级隔离，个人资料按服务端和登录名隔离；忽略跨会话的迟到响应，打开失败和版本切换后可重试 IndexedDB。旧无命名空间缓存不再直接作为新会话数据读取。 |
|
|
||||||
| 1.6 | 学期周统一加载后再取灵动岛课表，教学周变化触发重取；失败且无缓存时保留已知课表；主窗口禁用后台节流。 |
|
|
||||||
| 1.7、3.11 | IPC 拒绝渲染端改安装记录；安装只接受更新专用目录中的文件，拒绝目录外及软链接目标；取消、更换目标和更新完成后清理旧包。 |
|
|
||||||
| 2.1 | 空角色原本已保留旧值；现在未识别的非空值也保留原角色，只有明确的教师/管理员值才变更。 |
|
|
||||||
| 2.2、2.9 | 员工的成绩明细、看板、更新检查与强制检查落实权限；班级端仍由本班边界授权。增加学生/教师名单只读权限，旧管理组继承对应读取能力；下线没有独立服务端能力的日志与开发者模式权限键，系统设置仍由系统管理权限控制。 |
|
|
||||||
| 2.3 | 当前班级范围已由 CLASS_DEVICE 角色正确解析，不存在报告描述的必然拒绝，也不会查询全班学生。补齐 Socket 身份中的 classSession，保持元数据完整。 |
|
|
||||||
| 2.4、2.5 | 课表导入读取本班学期长度，创建课表按实际兜底周数做区间交叉校验。 |
|
|
||||||
| 2.6 | 姓名重复时要求正确学号，不能静默绑定到同名学生。 |
|
|
||||||
| 2.7 | 增加共享删除事件与两端订阅，并移除通知中心及灵动岛中的已删通知。 |
|
|
||||||
| 2.8 | 批量录入接口本身只接收单个 classId；真正缺口在跨班批量改等级，现已逐班广播。 |
|
|
||||||
| 2.10 | 调班历史按学生当前班级及显式班级过滤条件校验权限；未分班学生仅管理员可读。 |
|
|
||||||
| 2.11—2.13 | 引导使用主题文字变量，仅可见时响应 Esc；成绩明细优先展示保存的等级。 |
|
|
||||||
| 2.15—2.17 | 助手叫人校验非空消息；周次草稿提交前校验日期；通知日期改变后清除不再可选的发布人。发布人选择本身已有 change 处理，未重复添加。 |
|
|
||||||
| 3.1、3.4、3.9 | 列表丢弃过期响应；考试口径读写固定同一个班级/考试快照并禁用加载中的开关；切班立即清空课程候选。 |
|
|
||||||
| 3.2 | 提交函数增加互斥与 finally 释放，按钮同步显示 loading，快速双击不会重复发请求。 |
|
|
||||||
| 3.3 | 考试下拉从独立考试列表生成，不再由筛选后的成绩反推。 |
|
|
||||||
| 3.5—3.8 | 不回退到已归档届别；使用主题语义色、清理死样式；拒绝协议相对和反斜线附件地址；人数加载失败显示不可用。 |
|
|
||||||
| 3.12、3.13 | 取消确认框正常返回；列表加载与实时新增、删除、已读合并，防止快照抹掉飞行中的变更。 |
|
|
||||||
| 3.15 | 核对并修正登录、班级开关、设备权限、菜单数量、Socket 房间注释。登录限流当前已经一次挂载到两个入口并共享计数器，该条报告不成立。 |
|
|
||||||
| 4.1 | 百分制/字母制批量重算使用分数计算等级；自定义等级没有通用换算规则，禁止整批猜算，保留逐条编辑。 |
|
|
||||||
| 4.2 | 审计明确记录解析结果 interpreted / unrecognized，不再写成永远等待执行的 pending；它不宣称前端业务发布已成功。 |
|
|
||||||
| 4.3、4.4 | 助手上下文与预览参数均校验班级、科目范围；缺失通知优先级按普通通知展示。 |
|
|
||||||
| 4.6 | 外观 IPC 在一帧内合并滑块事件，读取时先刷新最后一帧，避免丢失最终值。 |
|
|
||||||
| 5 | 清理无调用的名单/课程封装和事件标签等；班级页接通既有任课关系导入。旧时间配置弹窗仍直接调用四个 API，按报告的保留要求保留组件及依赖，不盲目删除。 |
|
|
||||||
|
|
||||||
管理员的 Web 权限判断已移除全权限短路，与服务端保持一致；默认组收回的功能入口会隐藏。
|
|
||||||
日常冒烟采用后台快速模式，视觉验收显式执行；具体命令和验证范围见[验收与测试](testing.md)。
|
|
||||||
|
|
||||||
## 本次验证
|
|
||||||
|
|
||||||
- 全仓类型检查、ESLint、构建、变更格式检查通过，文档构建无警告。
|
|
||||||
- 隔离测试库端到端 243/243；审查接口回归 31/31；客户端维护接口 28/28。
|
|
||||||
- 无窗口逻辑回归 18/18；模拟远控及更新代理 15/15；旧库升级回归通过。
|
|
||||||
- 后台 Web 回归 37/37，约 38 秒；客户端联网冒烟 10/10，二次启动 9/9，总计约 15 秒。
|
|
||||||
- 本次使用独立 SQLite 测试库，没有执行真实关机或安装；未运行会占用桌面的完整视觉验收。
|
|
||||||
@@ -1,127 +0,0 @@
|
|||||||
---
|
|
||||||
title: 验收与测试
|
|
||||||
description: 验收验收脚本怎么跑、覆盖什么、哪些用例是脆弱的，以及怎么判断失败是不是真回归。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 验收与测试
|
|
||||||
|
|
||||||
验收分为后台快速冒烟、隔离的接口与逻辑回归、显式视觉验收。日常默认不显示窗口、不占用前台；
|
|
||||||
涉及动画、桌面像素和灵动岛几何时，再单独运行视觉验收。
|
|
||||||
|
|
||||||
## 验收脚本
|
|
||||||
|
|
||||||
| 命令 | 覆盖 | 需要什么 |
|
|
||||||
| ---------------------- | -------------------------------------------------------------------------------- | --------------------------- |
|
|
||||||
| `pnpm verify:e2e` | 后端 + 实时推送 + RBAC 越权 + 上课时段 + 导入 + 班级账号 + 数据库管理 + 更新检查 | **后端已启动** |
|
|
||||||
| `pnpm verify:web` | Web 管理端真实点击回归（Electron 驱动） | 后端已启动 + Web 产物已构建 |
|
|
||||||
| `pnpm verify:desktop` | 客户端冒烟（Electron，无人工点击） | 已构建的客户端产物 |
|
|
||||||
| `pnpm verify:packaged` | 对**打包后 / 已安装**的客户端 EXE 复跑同一套冒烟（`--exe` 指定路径） | 打包产物 |
|
|
||||||
|
|
||||||
条目数由脚本自行统计并打印（`=== 结果：N/N 项通过 ===`），**文档里不写死容易过期的总数** ——
|
|
||||||
每次跑完看脚本输出。
|
|
||||||
|
|
||||||
客户端维护专项回归：
|
|
||||||
|
|
||||||
- `pnpm verify:client-agent`：模拟操作系统验证远控、回执重试与安装策略，不执行真实关机或安装器。
|
|
||||||
- `pnpm verify:client-migrations`：创建临时旧库验证升级、联动移除与默认组编辑持久化。
|
|
||||||
- `pnpm verify:clients-api`：面向 `http://127.0.0.1:4199` 的演示测试库（可用 `VERIFY_BASE_URL` 指定），验证权限、远控与更新接口。会创建并清理测试记录，请使用隔离测试服务。
|
|
||||||
- `pnpm verify:review-client`：无窗口验证缓存故障恢复、通知竞态、教学周同步、管理员界面权限与崩溃恢复。
|
|
||||||
- `pnpm verify:review-api`：针对审查缺陷验证接口权限、导入边界和实时删除等，必须连接隔离测试服务。
|
|
||||||
|
|
||||||
另外三套是"门禁"而不是验收：`pnpm typecheck`、`pnpm lint`、`pnpm check:icons`。
|
|
||||||
|
|
||||||
### 一次完整的交付前检查
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm lint # ESLint，0 error 是底线
|
|
||||||
pnpm typecheck # 全仓库类型检查（含 vue-tsc）
|
|
||||||
|
|
||||||
pnpm dev:server # 另开一个终端
|
|
||||||
pnpm verify:e2e
|
|
||||||
|
|
||||||
pnpm build:desktop && pnpm verify:desktop
|
|
||||||
pnpm build && pnpm verify:web
|
|
||||||
```
|
|
||||||
|
|
||||||
改动涉及打包/交付形态时，再加 `pnpm dist:all` 与
|
|
||||||
`pnpm verify:packaged --exe "<客户端路径>"`（**开发产物通过不等于用户机器上的副本通过**）。
|
|
||||||
|
|
||||||
## 失败时先别改代码
|
|
||||||
|
|
||||||
下面这些用例**不是回归**，遇到时先看条件。完整清单在 `AGENTS.md` 的「已知脆弱用例」表。
|
|
||||||
|
|
||||||
| 用例 | 触发条件 |
|
|
||||||
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
||||||
| `verify:desktop:visual`「真实通知链路」「灵动岛标为已读」等 3 项 | 要求**当前不在上课时段**。种子课表恰有课正在进行时，客户端会**正确地**把普通通知暂存到下课 —— 这三项就会红（日志里会写 `客户端判定上课中=true`） |
|
|
||||||
| `verify:e2e`「上课状态接口（at=周一 08:10）」 | 种子把周一第 1 节限制在第 1 周，且用例把 `2026-09-07` 当第 1 周。`.env` 的 `TERM_START_DATE` 对齐即可全绿 |
|
|
||||||
| `verify:web`「课表科目为全校统一目录」 | 种子给每个班建满了全部科目，下拉里就没有可自动建课的「统一科目」分组 |
|
|
||||||
| `verify:desktop:visual`「课表今天时间轴」 | 凌晨约 00:00–03:00 时「已结束」探针被夹紧成 0 长度而被过滤 |
|
|
||||||
| `verify:desktop:visual`「作业看板全屏自适应」 | 演示数据某天有 6 条长作业、而冒烟窗口只有约 543px 高时，缩放被下限 0.45 钳住 → 必然溢出 |
|
|
||||||
| 岛交互 / 岛动画 / 岛截图留档 | 窗口被遮挡或跑在远程会话里时会间歇性失败：置顶透明小窗的 rAF 被限流、形变采样抓不到帧。**先原样重跑一次再动手改** |
|
|
||||||
|
|
||||||
## 大面积报「登录失败 / 401」时
|
|
||||||
|
|
||||||
先检查隔离服务是否启动，以及测试管理员的当前口令。不要修改真实班级密码来迁就测试。
|
|
||||||
联网客户端和 Web 回归会自行创建临时教师与班级；下面的环境变量只配置测试管理员：
|
|
||||||
|
|
||||||
| 脚本 | 管理员凭据 |
|
|
||||||
| ------------------- | -------------------------------------------------------- |
|
|
||||||
| 客户端联网/打包冒烟 | `ELECTRON_SMOKE_ADMIN` / `ELECTRON_SMOKE_ADMIN_PASSWORD` |
|
|
||||||
| Web 回归 | `UI_SMOKE_ADMIN` / `UI_SMOKE_ADMIN_PASS` |
|
|
||||||
| 后端端到端回归 | 使用隔离种子库，口令由种子脚本与验收脚本约定 |
|
|
||||||
|
|
||||||
默认离线快速冒烟不需要服务端凭据。
|
|
||||||
|
|
||||||
## 默认后台运行，视觉验收单独执行
|
|
||||||
|
|
||||||
`pnpm verify:desktop` 默认运行隐藏、不可聚焦的离屏窗口，仅检查启动、桥接白名单、缓存读写、
|
|
||||||
跨服务端/跨班级缓存隔离和关闭隐藏。二次启动也只跑快速检查，不再重复整套动画。
|
|
||||||
|
|
||||||
需要联网时运行 `pnpm verify:desktop:online`，创建临时教师与临时班级，结束后删除。
|
|
||||||
不再自动探测并复用真实班级，也不会重置真实班级密码。Web 回归同样使用隔离的验证教师与班级。
|
|
||||||
|
|
||||||
`pnpm verify:desktop:visual`（或客户端启动器 `--visual`）才运行灵动岛动画、透明度、桌面截图等完整验收，
|
|
||||||
这类用例确实需要使用桌面。`verify:packaged` 也默认快速模式，显式传 `--visual` 才跑视觉验收。
|
|
||||||
视觉验收不适合在用户操作屏幕时自动运行。截图采集命令需要传入 `--visual`（或设置 `ELECTRON_SMOKE_MODE=visual`）。
|
|
||||||
结果记录模式和耗时；启动器设置超时，避免验证进程无限等待。
|
|
||||||
|
|
||||||
## 截图留档
|
|
||||||
|
|
||||||
截图分两套，各管一件事：
|
|
||||||
|
|
||||||
| 目录 | 谁在用 | 谁产出 |
|
|
||||||
| ------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------- |
|
|
||||||
| `docs/images/` | **文档站、README、官网用的是同一份图**，页面上展示的都是它 | `capture-shots.mjs`（Web / 手机）+ 客户端冒烟（客户端 / 灵动岛） |
|
|
||||||
| `docs/screenshots/` | 回归留档，页面不展示；`verify:*` 的像素级断言比对的就是它们 | 各冒烟脚本自动写入（island / client / web-mobile 三组） |
|
|
||||||
|
|
||||||
**展示图重新采集**（保证文档站与 README、官网用的是同一份图）：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm dev:server # 后端同时托管 Web 管理端
|
|
||||||
CAPTURE_OUT=docs/images,website/assets/shots node website/tools/capture-shots.mjs # → web-*.jpg / mobile-*.jpg
|
|
||||||
|
|
||||||
# 客户端与灵动岛走的是冒烟脚本。它除了正片，还会顺手落一份「岛外留白对照图」
|
|
||||||
# （*-window.png / *-backdrop.png），所以先落到临时目录，再挑要用的拷进去。
|
|
||||||
ISLAND_SHOTS_DIR="$PWD/.cache/shots" ELECTRON_CLIENT_SHOTS_DIR="$PWD/.cache/shots" \
|
|
||||||
ELECTRON_SMOKE_ISLAND_ACCENT='#0a84ff' ELECTRON_SMOKE_ISLAND_STYLE=black \
|
|
||||||
node packages/desktop-client/scripts/smoke.mjs --visual --online
|
|
||||||
cp .cache/shots/{island-*,client-*}.png docs/images/
|
|
||||||
rm -f docs/images/*-window.png docs/images/*-backdrop.png
|
|
||||||
cp docs/images/{island-*,client-*}.png website/assets/shots/ # 官网那份保持同步
|
|
||||||
```
|
|
||||||
|
|
||||||
**回归留档重新采集**（同一套冒烟，把输出指到留档目录）：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm dev:server
|
|
||||||
ISLAND_SHOTS_DIR="$PWD/.cache/island-shots" \
|
|
||||||
ELECTRON_CLIENT_SHOTS_DIR="$PWD/.cache/client-shots" \
|
|
||||||
ELECTRON_SMOKE_ISLAND_ACCENT='#0a84ff' ELECTRON_SMOKE_ISLAND_STYLE=black \
|
|
||||||
node packages/desktop-client/scripts/smoke.mjs --visual --online
|
|
||||||
```
|
|
||||||
|
|
||||||
> 展示图都是**逻辑像素 1×**（灵动岛的 268×44、424×230 就是这个数，不再乘 2），
|
|
||||||
> 页面按原始尺寸显示即可 —— 换图时别顺手放大，否则整页的尺寸对不上。
|
|
||||||
> 采集脚本会把窗口真的弹在屏幕上。客户端留档会**临时停掉 CSS 动画**再截图 ——
|
|
||||||
> 窗口被遮挡时 Chromium 冻结动画，而页面入场动画的起始帧是 `opacity: 0`，
|
|
||||||
> 不停掉的话截出来是**整片空白**（DOM 里文本齐全，只有图是空的）。
|
|
||||||
@@ -1,22 +0,0 @@
|
|||||||
- name: 开发文档
|
|
||||||
href: index.md
|
|
||||||
- name: 架构总览
|
|
||||||
href: architecture.md
|
|
||||||
- name: REST API
|
|
||||||
href: api.md
|
|
||||||
- name: 实时事件（Socket.IO）
|
|
||||||
href: realtime.md
|
|
||||||
- name: 数据模型
|
|
||||||
href: data-model.md
|
|
||||||
- name: 角色与权限
|
|
||||||
href: permissions.md
|
|
||||||
- name: 动效层与主题
|
|
||||||
href: motion.md
|
|
||||||
- name: 灵动岛设计令牌
|
|
||||||
href: winisland-design-tokens.md
|
|
||||||
- name: 验收与测试
|
|
||||||
href: testing.md
|
|
||||||
- name: 2026-10-17 审查修复记录
|
|
||||||
href: review-2026-10-17.md
|
|
||||||
- name: 版本迭代与发布
|
|
||||||
href: release.md
|
|
||||||
@@ -1,593 +0,0 @@
|
|||||||
# WinIsland 视觉设计系统（Design Token 规格）
|
|
||||||
|
|
||||||
来源：[WinIsland](https://github.com/WinIslandProject/WinIsland) 的源码（`WinIsland-master`，只读 checkout）。
|
|
||||||
所有数值均取自代码常量，标注了「常量名 = 值 @ 文件」。未在代码中找到的项明确写「未找到」。
|
|
||||||
|
|
||||||
关键前提：**岛内所有几何尺寸都乘以 `compact_scale`（默认 1.0）或 `expanded_scale`（默认 1.0）**，
|
|
||||||
下文数值默认 scale = 1.0。文字颜色在渲染入口被硬编码为 `Color::WHITE`（`src/core/render.rs`
|
|
||||||
`draw_expanded_layer` / `draw_compact_layer` 传 `text_color: Color::WHITE`, `text_color_sec: Color::WHITE`），
|
|
||||||
所有"次级/次要"文字靠 **alpha** 或 **灰度通道值** 表达，而不是换颜色。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 几何（几何 token）
|
|
||||||
|
|
||||||
### 1.1 两个状态的尺寸
|
|
||||||
|
|
||||||
| 项 | compact / mini | expanded | 来源 |
|
|
||||||
| -------- | ------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------- |
|
|
||||||
| 宽 | `base_width = 120.0` | `expanded_width = 360.0` | `src/core/config.rs` `AppConfig::default()` |
|
|
||||||
| 高 | `base_height = 27.0` | `expanded_height = 200.0` | 同上 |
|
|
||||||
| 圆角 r | `h / 2`（=13.5）→ 胶囊/体育场形 | `min(48*scale, w/2, h/2)` = **48.0** | `src/window/app/frame.rs` `default_target_r`；`src/utils/shape.rs` `expanded_island_radius()` |
|
|
||||||
| 全局缩放 | `compact_scale = 1.0` | `expanded_scale = 1.0` | `src/core/config.rs` |
|
|
||||||
|
|
||||||
圆角函数原文（`src/utils/shape.rs`）：
|
|
||||||
|
|
||||||
```rust
|
|
||||||
pub(crate) fn expanded_island_radius(w: f32, h: f32, scale: f32) -> f32 {
|
|
||||||
(48.0 * scale).min(w / 2.0).min(h / 2.0).max(0.0)
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
compact 圆角：`IslandSprings::new` 里 `r = (base_height * compact_scale) / 2.0`（`src/window/app.rs`）；
|
|
||||||
展开时 `default_target_r = compact_content_h / 2.0`（`src/window/app/frame.rs` `update_spring_targets`）。
|
|
||||||
|
|
||||||
### 1.2 compact 宽度的动态规则（不是固定 120）
|
|
||||||
|
|
||||||
`src/window/app/layout.rs` `compute_lyric_target_width()`：
|
|
||||||
|
|
||||||
- 无媒体 / 不在播放态：宽 = `base_width` = **120**
|
|
||||||
- 有媒体但无歌词：宽 = `base_width + 35.0` = **155**
|
|
||||||
- 有歌词（不滚动）：`w = 60.0 + 文本宽`，再 `clamp(base_width+35, MAX_LYRIC_WIDTH)`
|
|
||||||
- `min_w = base_width + 35.0`、`MAX_LYRIC_WIDTH = 700.0`（`src/core/config.rs`）
|
|
||||||
- 有歌词（滚动模式，`lyrics_scroll = true`）：`natural_w = 60.0 + text_w`，超过 `lyrics_scroll_max_width`（默认
|
|
||||||
`300.0`，`default_lyrics_scroll_max_width`）则固定为该上限；内部可用文本宽 = `(fixed_w - 59.0) * compact_scale`
|
|
||||||
- 二级歌词存在时：高度 = `max(base_height*scale, mini_lyric_pair_height)`，
|
|
||||||
其中 `lyric_pair_height = 主字号*(1 + 0.85 + 0.18) + 8*scale`
|
|
||||||
（`SECONDARY_LYRIC_SCALE = 0.85`、`LYRIC_PAIR_GAP_SCALE = 0.18` @ `src/core/render/mini.rs`）
|
|
||||||
→ 默认字号 12 时 = 12×2.03 + 8 = **32.36 px 高**，r ≈ 16.18
|
|
||||||
|
|
||||||
### 1.3 挂件（compact widget）导致的最小宽度
|
|
||||||
|
|
||||||
`src/ui/widget/compact/mod.rs`：
|
|
||||||
|
|
||||||
- `CONTENT_EDGE_INSET = 9.0`、`CONTENT_GAP = 7.0`
|
|
||||||
- `widget_width()`：`Time = 48.0`、`ResourceUsage = 132.0`
|
|
||||||
- 三组对齐宽度：`aligned_layout_width = 9*2 + left + center + right + 7*(占用组数-1)`
|
|
||||||
- 单侧扩展宽：`extension_width = CONTENT_EDGE_INSET + strip_width + CONTENT_GAP`
|
|
||||||
（例：左 Time → 9+48+7 = **64**；ResourceUsage → 9+132+7 = **148**）
|
|
||||||
- 最终 compact 宽 = `max(布局宽, base_width)`
|
|
||||||
|
|
||||||
### 1.4 compact overlay（通知 / 音量）会替换 base 尺寸
|
|
||||||
|
|
||||||
| overlay | 宽 | 高 | 圆角 | 来源 |
|
|
||||||
| ------- | ------------------------------------------ | ----------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
|
|
||||||
| 通知 | `max(base_width, 330.0) * scale` = **330** | `max(base_height, 82.0) * scale` = **82** | `h/2` = **41** | `src/ui/compact/notification.rs` `target_size()`；r 取自 `src/window/app/frame.rs`（`size.height/2.0`） |
|
|
||||||
| 音量 | `(base_width + 72.0) * scale` = **192** | `(base_height + 10.0) * scale` = **37** | `h/2` = **18.5** | `src/ui/compact/volume.rs` `target_size()` |
|
|
||||||
|
|
||||||
### 1.5 隐藏态尺寸
|
|
||||||
|
|
||||||
- `hidden_width` 默认 `5.0`（`default_hidden_width` @ `src/core/config.rs`），
|
|
||||||
- `MIN_HIDDEN_WIDTH = 0.0`、`MAX_HIDDEN_WIDTH = 400.0`
|
|
||||||
- 隐藏时高度收缩到 `hidden_width * compact_scale`，并保留 `hidden_reveal_h = 1.0`（1px 可点击边）；
|
|
||||||
位移距离 `hide_distance = concealed_height + TOP_OFFSET`（`src/window/app/layout.rs`）
|
|
||||||
|
|
||||||
### 1.6 锚点（两种状态之间什么不动）
|
|
||||||
|
|
||||||
定位全部来自 `src/window/app/layout.rs` `compute_island_layout()` / `compute_window_position()`：
|
|
||||||
|
|
||||||
- **顶部居中停靠（默认）**：`island_y = TOP_OFFSET = 10.0`（**顶边固定**），
|
|
||||||
`offset_x = (os_w - w) / 2.0`（**水平中心固定**）
|
|
||||||
- **底部停靠**：`island_y = os_h - TOP_OFFSET - h`（**底边固定**，向上生长）
|
|
||||||
- **左/右停靠**：`offset_x = TOP_OFFSET` 或 `os_w - TOP_OFFSET - w`（对应侧边固定）
|
|
||||||
- `TOP_OFFSET: i32 = 10`（`src/core/config.rs`）＝ 岛顶边距屏幕顶 10 px
|
|
||||||
- 状态切换由三个弹簧同时插值：`w/h/r` 参数为 `stiffness = 0.10, damping = 0.68`（`src/window/app/frame.rs`），
|
|
||||||
页面横移 `view` 用 `0.12 / 0.68`；隐藏用 `(0.12, 0.70)` 隐藏 / `(0.08, 0.78)` 显示
|
|
||||||
- **compact 内容不跟随变大的岛做垂直居中重排**：mini 内容画在 `stable_island_y`（= 顶边）加上 `base_h` 带内居中
|
|
||||||
（`src/core/render/mini.rs`：封面 `y = stable_offset_y + (base_h - size)/2`，歌词 `center_y = stable_offset_y + base_h/2`）。
|
|
||||||
效果＝岛向下长大，胶囊内容始终贴在顶部那条带里。
|
|
||||||
- 交叉淡出：`expanded_alpha = expansion_progress² * (1-hide_progress)`，
|
|
||||||
`mini_alpha = clamp(1 - expansion_progress*1.5, 0, 1) * (1-hide_progress)`
|
|
||||||
（`MINI_FADE_RATE = 1.5` @ `src/core/render.rs`）→ 即进度 0~0.667 之间完成交叉淡出
|
|
||||||
|
|
||||||
### 1.7 有没有"挖孔/刘海"造型？
|
|
||||||
|
|
||||||
**没有。** 代码里没有 `SetWindowRgn` / `CreateRoundRectRgn` / notch / cutout 相关调用（已全仓 grep 确认），
|
|
||||||
也没有"顶部贴边 + 上方两角变直角"的特例分支。造型是：
|
|
||||||
|
|
||||||
- 一个**悬浮胶囊**（compact，r = h/2），**距屏幕顶 10 px**；
|
|
||||||
- 展开后是**四角一致的连续超椭圆**（squircle），r 最大 48。
|
|
||||||
|
|
||||||
圆角实现不是普通圆弧，而是 Flutter `RoundedSuperellipse` 的移植（`src/utils/shape.rs`，
|
|
||||||
注释标明 "Rounded-superellipse geometry adapted from Flutter under the BSD-3-Clause license"）：
|
|
||||||
|
|
||||||
- `superellipse_parameters()`：11 项查表 `PARAMETERS`（如 `(2.0, 1.13276676) … (6.43023796, 2.98020421)`），
|
|
||||||
ratio > 5 时线性外推 `exponent = 6.43023796 + 1.559599389*(ratio-5.0)`、`factor = 2.98020421 + 0.522807185*(ratio-5.0)`
|
|
||||||
- `Octant::new()`：13 项 `BEZIER_FACTORS`（`(0.7078, 8.3194) … (0.9705, 1.2880)`），用 conic + cubic 拼四分之一角
|
|
||||||
- 路径缓存 `PATH_CACHE_CAPACITY = 64`
|
|
||||||
- **Web 复刻提示**：CSS `border-radius` 是正圆角，观感会偏"软"；要还原请用 SVG path 或
|
|
||||||
`corner-shape: squircle`（若可用）/ `clip-path` 近似。**未找到**等价的简单圆角公式——真实几何就是上面那张表。
|
|
||||||
- **本仓库的落地实现**（`packages/desktop-client/src/island/squircle.ts`）：不查表，用单参数超椭圆近似
|
|
||||||
`point = center + r·(sign(cos a)·|cos a|^p, sign(sin a)·|sin a|^p)`，`p = 2/n`、`n = 4.2`，
|
|
||||||
四角分别以 `TR(w-r,r) → BR(w-r,h-r) → BL(r,h-r) → TL(r,r)`、起始角 `-π/2, 0, π/2, π` 各扫 `π/2`，
|
|
||||||
每角 14 段。**四个角必须各用自己的圆心 + 角度参数**：早期版本四个角共用同一个"偏移向量"，
|
|
||||||
左上/右下被切成缺一块（用户反馈的"左上角和右下角怎么缺一块 / 圆角边缘割裂"），
|
|
||||||
现已由 `verify:desktop` 的「连续圆角四角一致」断言（四角沿对角线边界步进两两一致 + 路径绕行 \|winding\|≈2π）长期守住。
|
|
||||||
|
|
||||||
### 1.8 窗口留白 / 裁切
|
|
||||||
|
|
||||||
- `PADDING: f32 = 80.0`（`src/core/config.rs`）；窗口尺寸 = `(岛宽 + 80, 岛高 + 80)`
|
|
||||||
（`src/window/app/layout.rs` `required_window_size()`）→ **岛四周各 40 px 透明留白**，供阴影/动画使用
|
|
||||||
- 绘制时 `canvas.clip_path(island_path, ClipOp::Intersect)`，所有内容裁在岛形内；
|
|
||||||
1px 描边在 `canvas.restore()` **之后**绘制（`src/core/render.rs` `draw_island()`）
|
|
||||||
- 挂件网格额外内缩，避免内容进圆角（`src/ui/widget/expanded/mod.rs` `widget_grid_layout`）：
|
|
||||||
```rust
|
|
||||||
corner_inset = radius * (1.0 - FRAC_1_SQRT_2); // 48 * 0.29289 = 14.06
|
|
||||||
inset = (corner_inset + 8.0*scale).max(24.0*scale); // = 24.0（scale=1）
|
|
||||||
gap = 7.0 * scale;
|
|
||||||
```
|
|
||||||
|
|
||||||
### 1.9 expanded 内容网格
|
|
||||||
|
|
||||||
- `WIDGET_GRID_COLS = 6`、`WIDGET_GRID_ROWS = 3`、`WIDGET_GRID_SLOTS = 18`（`src/core/config.rs`）
|
|
||||||
- 槽位宽 = `(inner_w - 7*5) / 6`，高 = `(inner_h - 7*2) / 3`；
|
|
||||||
用 360×200、inset 24 计算：inner = 312×152 → **slot ≈ 46.17 × 46.0**（`src/ui/widget/expanded/mod.rs`）
|
|
||||||
- 组件占格 `WidgetKind::span()`：`Clock = (2,1)`、`ResourceUsage = (2,1)`、`Calendar = (2,2)`、`Settings = (1,1)`
|
|
||||||
（`src/core/config.rs`）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 配色（颜色 token）
|
|
||||||
|
|
||||||
### 2.1 岛背景（`src/core/render/background.rs` `draw_background()`）
|
|
||||||
|
|
||||||
| 样式 | 颜色值 | 说明 |
|
|
||||||
| --------------------------- | -------------------------------------------------------------- | -------------------- |
|
|
||||||
| `default`（`SOLID_STYLE`） | `Color::BLACK` = **#000000**，完全不透明 | `bg_color` |
|
|
||||||
| `glass` + host backdrop | `Color::from_argb(150, 10, 10, 14)` = **rgba(10,10,14,0.588)** | `draw_host_glass()` |
|
|
||||||
| `glass` 无 backdrop（回退） | `Color::from_argb(205, 32, 32, 36)` = **rgba(32,32,36,0.804)** | `fallback_color` |
|
|
||||||
| `dynamic` 底色 | `Color::from_rgb(32, 32, 36)` = **#202024**，不透明 | `draw_effect_base()` |
|
|
||||||
| `dynamic` 叠加层 | `Color::from_argb(120, 20, 20, 24)` = **rgba(20,20,24,0.471)** | 盖在旋转模糊封面之上 |
|
|
||||||
| `dynamic` 无封面回退 | 同 glass 分支（150/10,10,14 或 205/32,32,36） | |
|
|
||||||
|
|
||||||
`dynamic` 封面动效参数（同一函数）：
|
|
||||||
|
|
||||||
- 集显：`rotate_speed = 0.015 rad/s, drift_speed_x = 0.075, drift_speed_y = 0.06, drift_amp_x = 10.0, drift_amp_y = 7.5`
|
|
||||||
- 独显：`rotate_speed = 0.03, drift_speed_x = 0.15, drift_speed_y = 0.12, drift_amp_x = 20.0, drift_amp_y = 15.0`
|
|
||||||
- 旋转矩形边长 `side_len = diagonal * 1.3`
|
|
||||||
|
|
||||||
**亚克力/backdrop 真实实现**（`src/window/d3d.rs` + `src/utils/win32.rs`）：
|
|
||||||
Windows 11 `DWMWA_USE_HOSTBACKDROPBRUSH`，失败时退回 `SetWindowCompositionAttribute`
|
|
||||||
（`AccentPolicy { state: 5, flags: 0, gradient_color: 0 }`，state 5 = host backdrop）；
|
|
||||||
再用 `Compositor::CreateHostBackdropBrush()` + `RoundedRectangleGeometry` 裁圆角
|
|
||||||
（`HOST_BACKDROP_INSET = 1.0`，几何 = `w-2, h-2, radius-1`）。
|
|
||||||
**未找到**任何模糊半径数值——模糊由系统 HostBackdropBrush 决定。
|
|
||||||
|
|
||||||
### 2.2 描边（`src/core/render.rs` `draw_island_border()`）
|
|
||||||
|
|
||||||
```rust
|
|
||||||
BORDER_WIDTH = 1.0; BORDER_INSET = BORDER_WIDTH / 2.0; // 0.5
|
|
||||||
SOLID_STYLE = "default"; SOLID_BORDER_ALPHA = 30; EFFECT_BORDER_ALPHA = 40;
|
|
||||||
```
|
|
||||||
|
|
||||||
- 颜色 = **纯白**，alpha：
|
|
||||||
- `default` 样式：`rgba(255,255,255, 30/255=0.118)`，**并再乘 `(1 - expansion_progress)`**（展开后描边消失）
|
|
||||||
- `glass` / `dynamic`：`rgba(255,255,255, 40/255=0.157)`，不随展开衰减
|
|
||||||
- 描边矩形 = `(x+0.5, y+0.5, w-1, h-1)`，圆角 `r-0.5`
|
|
||||||
|
|
||||||
### 2.3 阴影（`src/core/render.rs` `draw_expanded_shadow()`，仅展开时）
|
|
||||||
|
|
||||||
- 颜色 `Color::from_argb((28.0 * opacity) as u8, 0,0,0)` = **rgba(0,0,0,0.11)**
|
|
||||||
- `opacity = expansion_progress² * (1 - hide_progress)`，`opacity <= 0.01` 直接跳过
|
|
||||||
- 偏移 `offset_y = 2.0 * scale`；模糊 `sigma = min(3.0*scale, margin/3.0)`（margin = 到画布边界的余量）
|
|
||||||
- 用 `ClipOp::Difference` 只画在岛形之外
|
|
||||||
- **未找到内阴影**（没有任何 inner shadow 实现）
|
|
||||||
|
|
||||||
### 2.4 分隔线
|
|
||||||
|
|
||||||
| 位置 | 颜色 | 尺寸 | 来源 |
|
|
||||||
| -------------------- | -------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------- |
|
|
||||||
| compact 挂件之间 | `rgba(255,255,255, 0.14*alpha)` | 宽 `max(scale,1)`，从 `top+25%h` 到 `bottom-25%h` | `src/ui/widget/compact/mod.rs` `draw_separator()` |
|
|
||||||
| compact 资源占用内部 | `rgba(255,255,255, 0.10*alpha)` | 宽 `max(0.75*scale, 0.75)`，半高 `DIVIDER_HALF_HEIGHT = 6.0*scale` | `src/ui/widget/compact/resource_usage.rs` |
|
|
||||||
| expanded 资源环分隔 | `rgba(白, 0.09*alpha)` | 宽 `scale.max(0.75)`，从 `y+0.2h` 到 `y+0.8h` | `src/ui/widget/expanded/resource_usage.rs` |
|
|
||||||
| 设置窗口分隔线 | `rgba(255,255,255,26)` 暗 / `rgba(20,28,40,18)` 亮 | — | `src/utils/color.rs` |
|
|
||||||
|
|
||||||
### 2.5 文字颜色与不透明度分层
|
|
||||||
|
|
||||||
主文字一律 **#FFFFFF**；次级用 alpha：
|
|
||||||
|
|
||||||
| 元素 | 有效颜色 | 来源 |
|
|
||||||
| ------------------ | ------------------------------------------------------------ | ---------------------------------------------------- |
|
|
||||||
| 通知 app 名 | `rgba(255,255,255, 0.65*alpha)` | `src/ui/compact/notification.rs` |
|
|
||||||
| 通知标题 | `rgba(255,255,255, alpha)` | 同上 |
|
|
||||||
| 通知详情 | `rgba(255,255,255, 0.72*alpha)` | 同上 |
|
|
||||||
| 音量标签 | `rgba(255,255,255, 0.9*alpha)` | `src/ui/compact/volume.rs` |
|
|
||||||
| expanded 歌手 | `rgba(白, alpha*0.6)` | `src/ui/expanded/music_view.rs` `draw_track_text()` |
|
|
||||||
| 迷你歌词主行 | 白 alpha | `src/core/render/mini.rs` |
|
|
||||||
| 迷你歌词次行 | `rgb(176,176,176)`（`SECONDARY_LYRIC_CHANNEL = 176`） | 同上 |
|
|
||||||
| 逐字歌词"未唱"部分 | `rgb(190,190,190)`（`PENDING_LYRIC_CHANNEL = 190`） | 同上 |
|
|
||||||
| 进度条时间 | 白，`PROGRESS_TIME_IDLE_ALPHA = 0.5` → hover 1.0（线性插值） | `src/ui/expanded/music_view.rs` |
|
|
||||||
| 挂件时钟 | 白 alpha（bold） | `src/ui/widget/expanded/time.rs` |
|
|
||||||
| 挂件日历 月 | `0.78*alpha` | `src/ui/widget/expanded/calendar.rs` |
|
|
||||||
| 挂件日历 日 | `1.0*alpha` | 同上 |
|
|
||||||
| 挂件日历 星期 | `0.62*alpha` | 同上 |
|
|
||||||
| 挂件资源 数值 | `1.0*alpha`（bold） | `src/ui/widget/expanded/resource_usage.rs` |
|
|
||||||
| 挂件资源 标签 | `0.58*alpha` | 同上 |
|
|
||||||
| 封面占位块 | `rgba(白, 0.15*alpha)` | `src/ui/expanded/music_view.rs` `draw_placeholder()` |
|
|
||||||
|
|
||||||
### 2.6 强调色 / 状态色
|
|
||||||
|
|
||||||
岛内（`src/ui/widget/resource_usage.rs`）：
|
|
||||||
|
|
||||||
```rust
|
|
||||||
CPU_COLOR = rgb(50, 190, 246) // #32BEF6
|
|
||||||
RAM_COLOR = rgb(175, 82, 222) // #AF52DE
|
|
||||||
WARNING_COLOR = rgb(255, 159, 10) // #FF9F0A
|
|
||||||
CRITICAL_COLOR = rgb(255, 69, 58) // #FF453A
|
|
||||||
```
|
|
||||||
|
|
||||||
阈值曲线 `usage_color(base, usage)`：
|
|
||||||
|
|
||||||
- `usage <= 0.75` → base
|
|
||||||
- `0.75 < usage <= 0.9` → base ↔ WARNING 线性混合，`t = (usage-0.75)/0.15`
|
|
||||||
- `0.9 < usage` → WARNING ↔ CRITICAL 线性混合，`t = (usage-0.9)/0.1`
|
|
||||||
采样间隔 `SAMPLE_INTERVAL = 1s`；无数值时显示 `—`。
|
|
||||||
|
|
||||||
进度条/音量条（`src/ui/expanded/music_view.rs`、`src/ui/compact/volume.rs`）：
|
|
||||||
|
|
||||||
```rust
|
|
||||||
PROGRESS_TRACK_ALPHA = 0.15; // 轨道 rgba(白, 0.15*alpha)
|
|
||||||
PROGRESS_TIME_IDLE_ALPHA = 0.5; // 时间文字静止透明度
|
|
||||||
// 音量轨道 rgba(255,255,255, 0.28*alpha)，填充纯白 alpha
|
|
||||||
```
|
|
||||||
|
|
||||||
音量的"填充"就是**白色**（不是强调色），图标仍是白色。
|
|
||||||
|
|
||||||
可视化条颜色**来自专辑封面**（`src/ui/expanded/music_view/palette.rs`）：
|
|
||||||
|
|
||||||
- 把封面画到 8×8 的 GPU surface（`PALETTE_SAMPLE_SIZE = 8`）读回求平均 RGB
|
|
||||||
- `primary = brighten(avg, 1.3)`、`secondary = brighten(avg, 1.5)`
|
|
||||||
- `brighten` 用 BT.601 亮度 `0.299R + 0.587G + 0.114B`；若 < 80 则整体加 `80 - brightness`（抬到最低亮度 80）
|
|
||||||
- 调色板 = `[primary, secondary, primary]`，缓存上限 50 条
|
|
||||||
- 无封面默认值（`default_media_palette`）：`rgb(180,180,180)` + `rgb(100,100,100)`
|
|
||||||
- 采样完全失败的兜底：`rgb(200,200,200)`
|
|
||||||
|
|
||||||
### 2.7 不同状态是否不同配色？
|
|
||||||
|
|
||||||
- **同一套**：底 + 白字 + alpha 分层；通知 / 音量 / 音乐 / 挂件没有各自的独立配色，
|
|
||||||
视觉区分靠 **尺寸（330×82 / 192×37 / 120×27）** 与 **内容排版**，而不是换色。
|
|
||||||
- 差异只在两处：**可视化条用封面取色**（2.6），**资源占用用 CPU/RAM/警告/危险四色**（2.6）。
|
|
||||||
- 岛背景三样式（default/glass/dynamic）才是真正的配色分支（2.1）。
|
|
||||||
|
|
||||||
### 2.8 设置窗口色板（另一套，`src/utils/color.rs`，供参考）
|
|
||||||
|
|
||||||
暗色主题 `dark_settings_theme()`：
|
|
||||||
|
|
||||||
```
|
|
||||||
win_bg #1C1C1E sidebar_bg #242426 group_bg #2C2C2E card_highlight #48484A
|
|
||||||
accent #0A84FF text_pri #F5F5F7 text_sec #AEAEB2 disabled #636366
|
|
||||||
danger #E6372D toggle_on #30D158 toggle_off #636366
|
|
||||||
sidebar_hover rgba(255,255,255,20) separator rgba(255,255,255,26)
|
|
||||||
popup_bg #323234 popup_border rgba(255,255,255,40) popup_shadow rgba(0,0,0,60)
|
|
||||||
popup_separator rgba(255,255,255,30) control_bg #3A3A3C control_hover #48484A
|
|
||||||
control_disabled #303032 control_border rgba(255,255,255,36)
|
|
||||||
group_border rgba(255,255,255,24) shadow rgba(0,0,0,45) scrollbar rgba(255,255,255,60)
|
|
||||||
```
|
|
||||||
|
|
||||||
亮色主题 `light_settings_theme()`：
|
|
||||||
|
|
||||||
```
|
|
||||||
win_bg #F4F5F7 sidebar_bg #FAFAFC group_bg #FFFFFF card_highlight #EFF2F7
|
|
||||||
text_pri #1F2228 text_sec #5B626E disabled #9297A1 accent #0067C0
|
|
||||||
danger #C42B1C toggle_on #0078D4 toggle_off #B0B5BE
|
|
||||||
selection_bg #E0EEFA selection_text #005599
|
|
||||||
sidebar_hover rgba(20,32,48,14) separator rgba(24,32,44,18)
|
|
||||||
popup_bg #FFFFFF popup_border rgba(20,28,40,24) popup_shadow rgba(20,28,40,20)
|
|
||||||
control_bg #F7F8FA control_hover #EBEFF4 control_disabled #F1F2F5
|
|
||||||
control_border rgba(20,28,40,24) group_border rgba(20,28,40,14)
|
|
||||||
shadow rgba(20,28,40,20) scrollbar rgba(52,58,68,52)
|
|
||||||
```
|
|
||||||
|
|
||||||
设置窗口另有"岛预览"配色（与真实渲染略有差异，`src/utils/settings_ui/renderer/widget_preview.rs`）：
|
|
||||||
glass 预览 `rgba(24,24,28,220)`；dynamic 预览为线性渐变 **`rgb(18,12,36)` → `rgb(8,24,48)`**（左上→右下）；
|
|
||||||
default 预览 `rgb(10,10,10)`；预览描边 alpha `52`(glass) / `38`(其他)；预览阴影 `rgba(0,0,0,72)`，偏移 +4。
|
|
||||||
→ 若前端需要一张**静态渐变**替代 `dynamic`，这两个色值就是现成可抄的。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 排版（字体 token）
|
|
||||||
|
|
||||||
### 3.1 字体族（`src/utils/font.rs`）
|
|
||||||
|
|
||||||
1. 用户自定义字体：`config.custom_font_path` → `FontMgr::new_from_data()`（优先于全部）
|
|
||||||
2. ASCII 文本：`"Microsoft YaHei"` → `"Segoe UI"` → 系统默认（`legacy_make_typeface`）
|
|
||||||
3. 非 ASCII：逐字符匹配 `match_family_style_character("", style, &["zh-CN","ja-JP","en-US"], ch)`，
|
|
||||||
再依次尝试 `"Segoe UI Emoji"` → `"Microsoft YaHei"` → `"Segoe UI Symbol"` → `"Segoe UI"`
|
|
||||||
4. 合成粗体：`needs_synthetic_bold()` = 请求 `weight >= 600` 且字体本身 `weight < 600` → `font.set_embolden(true)`
|
|
||||||
5. 亚像素渲染始终开启 `font.set_subpixel(true)`
|
|
||||||
|
|
||||||
字重只有两档：`FontStyle::bold()`（700）与 `FontStyle::normal()`（400）；
|
|
||||||
滚动文本判定粗体用 `style.weight() >= 700`（`src/utils/scroll.rs`）。
|
|
||||||
|
|
||||||
**字距 / 行高**：代码里**未找到** letter-spacing 或 line-height 参数；
|
|
||||||
行距全部通过显式 y 偏移实现（见下表）。文本绘制走 Skia `draw_str`，
|
|
||||||
大字文本（标题/歌手）`render_as_paths = true`（`src/utils/scroll.rs` 调用点）。
|
|
||||||
|
|
||||||
### 3.2 字号表（默认 `config.font_size = 0.0` 时用内置值；>0 时用户值参与计算）
|
|
||||||
|
|
||||||
| 用途 | 字号 | 字重 | 说明 / 来源 |
|
|
||||||
| -------------------- | -------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------- |
|
|
||||||
| mini 歌词主行 | `font_size*0.8*scale` 或 **12.0\*scale** | normal | `src/core/render/mini.rs` `lyric_font_size()` |
|
|
||||||
| mini 歌词次行 | 主字号 × `SECONDARY_LYRIC_SCALE = 0.85` | normal | 同上 |
|
|
||||||
| mini 歌词对高度 | `主*(1+0.85+0.18) + 8*scale` | — | `lyric_pair_height()` |
|
|
||||||
| mini 插件文字（主） | `font_size*0.7*scale` 或 **11.0\*scale** | **bold** | `PLUGIN_FONT_SCALE = 0.7`、`DEFAULT_PLUGIN_FONT_SIZE = 11.0` |
|
|
||||||
| mini 插件文字（次） | 主 × `0.8` | normal | `PLUGIN_SECONDARY_FONT_SCALE = 0.8`，行距 `font_size*1.3`（`PLUGIN_SECONDARY_LINE_SPACING = 1.3`） |
|
|
||||||
| expanded 曲名 | `font_size*scale` 或 **15.0\*scale** | **bold** | `src/ui/expanded/music_view.rs` |
|
|
||||||
| expanded 歌手 | 同上 **15.0\*scale** | normal | 基线 = 曲名基线 + `22.0*scale` |
|
|
||||||
| 进度时间 | `font_size*0.67*scale` 或 **10.0\*scale** | normal | `PROGRESS_TIME_FONT_SCALE = 0.67`、`DEFAULT_PROGRESS_TIME_FONT_SIZE = 10.0` |
|
|
||||||
| 通知 app 名 | **11.0\*scale** | normal | `src/ui/compact/notification.rs` |
|
|
||||||
| 通知标题 | **13.0\*scale** | **bold** | 同上 |
|
|
||||||
| 通知详情 | **11.0\*scale** | normal | 行间距 `DETAIL_LINE_GAP = 21.0*scale` |
|
|
||||||
| 音量标签 | **12.0\*scale** | normal | `src/ui/compact/volume.rs` |
|
|
||||||
| compact 时钟挂件 | `clamp(h*0.43, 10, 12)` | **bold** | `src/ui/widget/compact/time.rs` |
|
|
||||||
| compact 资源—标签 | `METRIC_LABEL_SIZE = 7.0*scale` | **bold** | `src/ui/widget/compact/resource_usage.rs` |
|
|
||||||
| compact 资源—数值 | `METRIC_VALUE_SIZE = 10.0*scale` | **bold** | 同上 |
|
|
||||||
| expanded 时钟挂件 | `min(h*0.60, w*0.31)`，最小 `13.0*scale` | **bold** | `src/ui/widget/expanded/time.rs` |
|
|
||||||
| expanded 日历—月 | `clamp(h*0.14, 9, 15)*scale` | **bold** | `src/ui/widget/expanded/calendar.rs` |
|
|
||||||
| expanded 日历—日 | `min(h*0.53, w*0.70)`，最小 `26.0*scale` | **bold** | 同上 |
|
|
||||||
| expanded 日历—星期 | `clamp(h*0.12, 8, 12)*scale` | normal | 同上 |
|
|
||||||
| expanded 资源—圆环值 | `clamp(d*0.27, 7, 10.5*scale)`，d = 圆环直径 | **bold** | `src/ui/widget/expanded/resource_usage.rs` |
|
|
||||||
| expanded 资源—标签 | `clamp(h*0.12, 6, 8*scale)` | **bold** | 同上 |
|
|
||||||
| 设置窗口—行标签/值 | **13.0** | normal | `src/utils/settings_ui/renderer/items.rs` |
|
|
||||||
| 设置窗口—页签标签 | **11.5** | normal（选中为 bold） | `src/window/settings/renderer.rs` |
|
|
||||||
| 设置窗口—弹窗项 | **12.0** | normal | 同上 |
|
|
||||||
| 设置窗口—Markdown | `BODY_SIZE = 12.0`，`LINE_HEIGHT = 18.0` | — | `src/window/settings/pages/plugins/markdown.rs` |
|
|
||||||
|
|
||||||
字体基线规则（值得照抄）：
|
|
||||||
|
|
||||||
- 居中对齐用 **字形包围盒** 居中：`baseline_y = bounds.top + (bounds.h - glyph.h)/2 - glyph.top`
|
|
||||||
（`src/ui/widget/expanded/mod.rs` `draw_widget_text_centered()`）
|
|
||||||
- 时间文字基线 = 进度条中心 + `0.35*字号`（`PROGRESS_TIME_BASELINE_SCALE = 0.35`）
|
|
||||||
- 迷你歌词单行时 `primary_y = center_y + size/3`；双行时按堆叠高度对齐（见 5.1）
|
|
||||||
|
|
||||||
### 3.3 是否随窗口尺寸 / 用户设置缩放
|
|
||||||
|
|
||||||
- 随 `compact_scale` / `expanded_scale` 缩放（乘在所有尺寸上）
|
|
||||||
- 字号受 `config.font_size`（默认 0 = 用内置值）影响：只有 mini 歌词、mini 插件、expanded 曲名/歌手、进度时间用它
|
|
||||||
- 挂件字号是**几何驱动**的（按自身矩形宽高 clamp），与 `font_size` 无关
|
|
||||||
- 设置窗口有自己的 `settings_theme`（`system` / 暗 / 亮）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 层级与效果
|
|
||||||
|
|
||||||
### 4.1 圆角
|
|
||||||
|
|
||||||
见 1.7。总结：连续超椭圆（squircle），compact 满圆角（h/2），expanded 最大 48。
|
|
||||||
挂件卡片 `widget_corner_radius = min(12.0*scale, min(w,h)/2)`（`src/ui/widget/expanded/mod.rs`）。
|
|
||||||
迷你封面 `MINI_COVER_RADIUS = 5.0`，expanded 封面 `16.0*scale`，通知图标 `11.0*scale`。
|
|
||||||
|
|
||||||
### 4.2 阴影 / 发光
|
|
||||||
|
|
||||||
- **外阴影**：仅 expanded，`rgba(0,0,0,0.11)`，y+2，blur σ = `min(3*scale, margin/3)`（见 2.3）
|
|
||||||
- **内阴影**：**未找到**
|
|
||||||
- **发光**：只出现在资源占用圆环——`glow` 圆半径 `diameter*0.57`，颜色 `accent`，alpha `0.07*alpha`
|
|
||||||
（`src/ui/widget/expanded/resource_usage.rs`）
|
|
||||||
- 设置窗口：窗口阴影 `rgba(0,0,0,90)`、弹出菜单阴影 `theme.popup_shadow` + 偏移 +2（`src/window/settings/renderer.rs`）；
|
|
||||||
拖拽幽灵阴影 `rgba(0,0,0,90)`，偏移 +4
|
|
||||||
|
|
||||||
### 4.3 模糊半径（全部数值）
|
|
||||||
|
|
||||||
| 场景 | 参数 | 来源 |
|
|
||||||
| ----------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------- |
|
|
||||||
| 运动模糊（整体） | 横向 = ` | w速度 | *0.3 + | view速度 | *w*0.4`，纵向 = ` | h速度 | *0.3`；上限集显 `(4.0, 3.5)`、独显 `(12.0, 10.0)`；仅在 σ>0.1 时 `saveLayer` | `src/utils/blur.rs` `calculate_blur_sigmas()`、`src/core/render.rs` `MIN_BLUR_SIGMA = 0.1` |
|
|
||||||
| 封面翻转 | `σ = (1- | cos | )^0.6 * 8.0 * scale`，x 方向再 ×0.3 | `src/ui/expanded/music_view.rs` |
|
|
||||||
| 暂停按钮速度模糊 | ` | 弹簧速度 | * 16.0 * scale`，上限 `2.5*scale` | `PAUSE_CONTROL_BLUR_SCALE = 16.0`、`PAUSE_CONTROL_MAX_BLUR = 2.5` |
|
|
||||||
| 快进/快退按钮 | `(1 - t/0.3).max(0) * 6.0 * scale`，x×0.3 | 同文件 `draw_skip_button()` |
|
|
||||||
| 歌词切换（Blur 模式） | `σ = 6.0*scale`，x 压缩 `LYRIC_TRANSITION_BLUR_X_SCALE = 0.25`，位移 `LYRIC_TRANSITION_OFFSET = 10.0*scale` | `src/core/render/mini.rs` |
|
|
||||||
| dynamic 背景封面 | 先降采样到 **64×64**，再 `image_filters::blur((8.0, 8.0), TileMode::Clamp)` | `src/utils/backdrop.rs` |
|
|
||||||
| host backdrop（亚克力） | **未找到数值**（由系统 HostBackdropBrush 决定，仅 `HOST_BACKDROP_INSET = 1.0`） | `src/window/d3d.rs` |
|
|
||||||
|
|
||||||
### 4.4 不透明度分层与可见性阈值
|
|
||||||
|
|
||||||
```
|
|
||||||
MIN_VISIBLE_OPACITY = 0.01 // 低于此不绘制
|
|
||||||
MIN_BLUR_SIGMA = 0.1
|
|
||||||
MINI_FADE_RATE = 1.5 // mini 淡出速率
|
|
||||||
COLLAPSED_VISUALIZER_HEIGHT_SCALE = 0.45 // 收起时可视化高度 = 45%
|
|
||||||
```
|
|
||||||
|
|
||||||
- `expanded_alpha = expansion_progress² * (1 - hide_progress)`（平方 → 展开"迟入场"）
|
|
||||||
- `mini_alpha = clamp(1 - expansion_progress*1.5, 0, 1) * (1 - hide_progress)`
|
|
||||||
- 可视化高度比例 `visualizer_height_scale = 0.45 + 0.55 * expansion_progress`
|
|
||||||
- 歌词额外淡出 `LYRIC_EXPANSION_FADE_RATE = 2.5`（`src/core/render/mini.rs`）
|
|
||||||
- 展开页横向滑动：`page_shift = view_offset * current_w`；
|
|
||||||
音乐页 `translate(-page_shift)`，挂件页 `translate(current_w - page_shift)`
|
|
||||||
（`src/core/render/expanded.rs`）；`view` 弹簧 `0.12/0.68`
|
|
||||||
|
|
||||||
### 4.5 卡片四周留白 / 裁切
|
|
||||||
|
|
||||||
见 1.8：窗口 = 岛 + 80（每侧 40 透明）；内容 `clip_path(Intersect)`；
|
|
||||||
描边在裁切外画；挂件网格 inset 24。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. 布局骨架
|
|
||||||
|
|
||||||
### 5.1 compact（mini）120×27
|
|
||||||
|
|
||||||
`src/core/render/mini.rs`：
|
|
||||||
|
|
||||||
```
|
|
||||||
MIN_MINI_CONTENT_WIDTH = 45.0 // 可用宽小于此不画内容
|
|
||||||
MINI_COVER_SIZE = 18.0 // 封面尺寸
|
|
||||||
MINI_COVER_LEFT_INSET = 10.0 // 封面左边距
|
|
||||||
MINI_COVER_RADIUS = 5.0 // 封面圆角
|
|
||||||
MINI_VISUALIZER_RIGHT_INSET = 17.0
|
|
||||||
MINI_VISUALIZER_WIDTH_SCALE = 0.55
|
|
||||||
MINI_VISUALIZER_SMOOTHING = (0.6, 0.08) // (上升, 下降)
|
|
||||||
LYRIC_LEFT_INSET = 30.0
|
|
||||||
LYRIC_RIGHT_INSET = 29.0
|
|
||||||
```
|
|
||||||
|
|
||||||
- **左**：18×18 封面，x = 10，y 垂直居中（`(base_h - 18)/2 = 4.5`），圆角 5，中心裁剪
|
|
||||||
- **中**：歌词，可用区 x ∈ [30, w-29]，垂直居中；主行居中（滚动模式改为左对齐并从 x=30 起滚动），
|
|
||||||
次行始终水平居中；主行单行时 `y = center_y + size/3`，双行时
|
|
||||||
`stack_h = size + size*0.85 + size*0.18`，主行 `y = center_y - stack_h/2 + size*0.8`，
|
|
||||||
次行 `y = center_y + stack_h/2 - secondary*0.2`
|
|
||||||
- **右**：可视化条，中心 x = `w - 17`，中心 y = `base_h/2`
|
|
||||||
- 无媒体时改由 compact 挂件条接管：Left / Center / Right 三组；
|
|
||||||
有 mini 内容时只画 Left 与（Center+Right）两组并贴两端，并在内容两侧画竖分隔线
|
|
||||||
（`src/ui/widget/compact/mod.rs` `draw()`）
|
|
||||||
- 挂件宽：时间 **48**、资源 **132**；边缘 inset **9**；组内间距 **7**
|
|
||||||
|
|
||||||
### 5.2 expanded 音乐页 360×200
|
|
||||||
|
|
||||||
`src/ui/expanded/music_view.rs` 常量全表：
|
|
||||||
|
|
||||||
```
|
|
||||||
CONTENT_PADDING = 24.0 // 四周内边距
|
|
||||||
COVER_SIZE = 64.0 // 封面 64×64，圆角 16.0*scale，位置 (24,24)
|
|
||||||
TRACK_TEXT_GAP = 18.0 // 封面右到文字左
|
|
||||||
TRACK_TEXT_RIGHT_INSET = 70.0 // 文字右侧预留（给可视化条）
|
|
||||||
TRACK_TITLE_BASELINE_OFFSET= 26.0 // 曲名基线 y = 24 + 26 = 50
|
|
||||||
PROGRESS_TOP_GAP = 24.0 // 进度条中心 y = 24 + 64 + 24 = 112
|
|
||||||
PROGRESS_TIME_WIDTH = 28.0 // 两端时间文字预留宽
|
|
||||||
PROGRESS_TIME_GAP = 4.0
|
|
||||||
PROGRESS_BAR_HEIGHT = 6.5 // 常态条高
|
|
||||||
PROGRESS_BAR_HOVER_GROWTH = 3.5 // hover 增至 10.0
|
|
||||||
PLAYBACK_CONTROLS_TOP_GAP = 42.0 // 控制行中心 y = 112 + bar_h/2 + 42 ≈ 157.25
|
|
||||||
SKIP_BUTTON_GAP = 75.0 // 上一首/下一首中心距播放键 75
|
|
||||||
PAGE_ARROW_RIGHT_INSET = 7.5 // 右侧翻页条 x = w - 7.5，y = h/2
|
|
||||||
PAGE_ARROW_FADE_RATE = 5.0
|
|
||||||
COLLAPSED_VISUALIZER_INSET = 17.0 // 视觉条右侧 inset 随展开 17 → 37
|
|
||||||
EXPANDED_VISUALIZER_INSET = 37.0
|
|
||||||
VISUALIZER_TITLE_OFFSET = 4.0 // 视觉条中心 y = 曲名基线 - 4
|
|
||||||
```
|
|
||||||
|
|
||||||
- **左**：64 封面；**中**：曲名(15 bold)/歌手(15, α0.6) 两行，x = 24+64+18 = **106**；**右**：可视化条
|
|
||||||
- 进度条：左右各内缩 24，两端 28 宽时间 + 4 间距；条圆角 = bar_h/2；
|
|
||||||
填充宽度 `max(bar_total_w*progress, bar_h)`；填充只圆左端（RRect 左上/左下半径 = bar_h/2，右侧 0）
|
|
||||||
- 控制行中心 x = 180；播放键在中心、上一首 105、下一首 255
|
|
||||||
- 点击热区（`src/ui/expanded/music_view/controls.rs`）：播放 **40×40**，上/下一首 **36×36**，
|
|
||||||
进度条热区高 **16.0\*scale**，封面整块可双击（激活媒体 App）
|
|
||||||
- 动画参数：`PROGRESS_SMOOTHING = 0.15`、`PROGRESS_HOVER_SMOOTHING = 0.18`、
|
|
||||||
`PROGRESS_HOVER_SNAP_THRESHOLD = 0.005`、`PROGRESS_START_THRESHOLD = 0.02`、`PROGRESS_JUMP_THRESHOLD = 0.3`、
|
|
||||||
`PLAY_STATE_RESPONSE = 0.18`、`SKIP_ANIMATION_DURATION_SECS = 0.5`、封面翻转 0.6s、
|
|
||||||
`PAUSE_CONTROL_STIFFNESS = 0.18`、`PAUSE_CONTROL_DAMPING = 0.64`、`PAUSE_CONTROL_MIN_SCALE = 0.8`、
|
|
||||||
`PAUSE_CONTROL_MAX_SCALE = 1.03`、`PAUSE_CONTROL_PRESS_VELOCITY = -0.18`
|
|
||||||
- 播放/暂停过渡：`cover_scale = 0.85 + 0.15*pause_t`、`cover_brightness = 0.75 + 0.25*pause_t`
|
|
||||||
（即暂停时封面缩小到 85% 并压暗到 75%），图标用 `smoothstep` 交叉淡出
|
|
||||||
|
|
||||||
### 5.3 expanded 挂件页（同 360×200）
|
|
||||||
|
|
||||||
- 6×3 网格，inset 24，gap 7（见 1.9）
|
|
||||||
- 卡片：背景 `rgba(28,28,30, 0.05*alpha)`，描边 `1px rgba(255,255,255, 0.16*alpha)`，圆角 `min(12*scale, min(w,h)/2)`
|
|
||||||
- 左侧翻页条 x = **7.5**，y = `h/2`（3×14 圆角矩形，α0.4）；右侧同（x = w-7.5）
|
|
||||||
- 内置挂件各视图排布：
|
|
||||||
- **时钟**：整卡居中，字号 `min(h*0.6, w*0.31)`（≥13），bold，`HH:MM` 格式
|
|
||||||
- **日历**：月 `y+0.08h..0.26h`（bold，α0.78）／日 `y+0.27h..0.75h`（bold，字号 `min(0.53h,0.70w)`，≥26）／
|
|
||||||
星期 `y+0.78h..0.92h`（normal，α0.62）
|
|
||||||
- **资源占用（2×1）**：中间竖分隔（α0.09，`y+0.2h..0.8h`）；两个圆环各占一半：
|
|
||||||
环心 `(center_x, top+0.43h)`，直径 `min(0.58h, 0.62w)`（≥20），描边 `min(3*scale, d*0.12)` 圆头，
|
|
||||||
底环 α0.13，进度弧从 **-90°** 起扫 `usage*360°`（α0.92），值文字 bold 居中，标签在 `top+0.76h`（α0.58）
|
|
||||||
- **设置（1×1）**：整卡居中齿轮图标，`icon_scale = min(w,h)*0.38/24`，α0.72
|
|
||||||
|
|
||||||
### 5.4 compact 各业务视图差异
|
|
||||||
|
|
||||||
| 视图 | 尺寸 | 排布 |
|
|
||||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
||||||
| 时间挂件 | 48×27 | 居中 `HH:MM`，字号 `clamp(0.43h, 10..12)` bold，基线 `center_y + size*0.36` |
|
|
||||||
| 资源挂件 | 132×27 | 两个 metric 各 `(w-8)/2` 宽；标签 7px bold 在左（accent α0.78），数值 10px bold 在右（白）； |
|
|
||||||
| 文字基线 `center_y + scale`；下方 2px 进度轨（y = 基线+5），轨 α0.13，填充 accent α0.9；中间分隔 α0.1，半高 6 |
|
|
||||||
| 通知 | 330×82 | 图标 42×42 圆角 11 @ x+18 垂直居中；文本左 = 有图标 `x+72` / 无图标 `x+20`；右内缩 18； |
|
|
||||||
| app 名基线 `top+22`（11px α0.65）；标题 13px bold，基线 `top+34`（无 app 名）/ `top+43`（有 app 名）/ 垂直居中 `top+(h+13)/2`（两者皆无）；详情 11px α0.72 在标题下 21px |
|
|
||||||
| 音量 | 192×37 | 喇叭图标 20px，中心 `x = left+21`；标签 12px @ `left+37`（α0.9）；轨道从 `label_x + label_w + 26` 到 `right-14`，高 4 圆角 2，轨 α0.28，填充白 α1.0 |
|
|
||||||
|
|
||||||
### 5.5 动画时长（通知 / 音量）
|
|
||||||
|
|
||||||
- 通知：`DISPLAY_DURATION = 5s`，`ENTER_DURATION = 220ms`（`ease_out_cubic = 1-(1-t)³`），
|
|
||||||
`FADE_DURATION = 280ms`；入场位移 `(1-enter)*7.0*scale`（从上滑下 7px）
|
|
||||||
- 音量：`DISPLAY_DURATION = 1600ms`，`FADE_DURATION = 240ms`，
|
|
||||||
`VOLUME_CHANGE_THRESHOLD = 0.002`（音量变化阈值，低于此不显示）
|
|
||||||
- 歌词切换进度用 `smoothstep`：`p*p*(3-2p)`（`src/core/render/mini.rs`）
|
|
||||||
- 长文本跑马灯（`src/utils/scroll.rs`）：先停 **2.0s**，再以 **35.0\*scale px/s** 滚动，
|
|
||||||
循环间隔 `full_w + 50*scale`，裁剪区 `(x, y-size*1.2, max_w, size*1.5)`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. 图标
|
|
||||||
|
|
||||||
**体系**：全部是 Skia 内的 **SVG path 数据 + 填充（`PaintStyle::Fill`）**，没有线性描边图标体系，
|
|
||||||
也没有 icon font。颜色一律单色：由 `text_color`（= 白）+ alpha 决定；只有资源环用 accent 色。
|
|
||||||
**未找到**线宽（stroke-width）概念——唯一的描边图标是设置窗口的翻页箭头（`1.8px`, round cap/join）。
|
|
||||||
|
|
||||||
| 图标 | 路径坐标系 | 缩放 | 实际视觉尺寸 | 来源 |
|
|
||||||
| ---------------- | ------------------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
||||||
| 播放 ▶ | 640 单位（128..544） | `0.083 * scale` | ≈ 34.5 × 37 px | `src/icons/controls.rs` `draw_play_button` |
|
|
||||||
| 暂停 ⏸ | 640 单位 | `0.083 * scale` | ≈ 34.5 × 37 px | `draw_pause_button` |
|
|
||||||
| 快退/快进三角 | 640 单位（中心 336,320） | `path_scale * global_scale`，静止 `0.050`（左）与 `0.055`（右）；动画中 `0.050~0.055` | 约 21 × 22 px | `draw_control_triangle`，`src/ui/expanded/music_view.rs` `draw_skip_button`（中心 ±10.92*scale） |
|
|
||||||
| 音乐（封面占位） | 1024 单位 | `scale*1.8`，内部 `0.024` | 随卡片 | `src/icons/music.rs` |
|
|
||||||
| 设置齿轮 | 1024 单位 | `min(w,h)*0.38/24`，内部 `0.024` | 卡片 38% 短边 | `src/icons/settings.rs` |
|
|
||||||
| 音量（4 档） | 25.75 单位 | `size / 25.75`，偏移 `(-11.089286, -7.883929)` | 传 20.0*scale | `src/icons/volume.rs`；档位 `level<=0→静音, <=1/3→低, <=2/3→中, else→高` |
|
|
||||||
| 翻页指示条 | 不是 path | — | `3.0*scale × 14.0*scale` 圆角矩形，圆角 `2.0*scale`，α×0.4 | `src/icons/arrows.rs` |
|
|
||||||
|
|
||||||
其他图标使用点：
|
|
||||||
|
|
||||||
- 通知 App 图标：`AppDisplayInfo::GetLogo(Size{64,64})`，按 alpha>8 计算可见包围盒，等比缩放塞进 42×42，圆角 11 裁切
|
|
||||||
- 封面：64×64（expanded）与 18×18（mini），中心裁剪，`FilterMode::Linear + MipmapMode::Linear`
|
|
||||||
- 迷你封面圆角 5、expanded 封面圆角 16（连续超椭圆路径，不是普通 `clip_rrect`）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. 明确「未找到」的项
|
|
||||||
|
|
||||||
1. **刘海/挖孔造型**：不存在（无 `SetWindowRgn`、无顶部直角特例）
|
|
||||||
2. **内阴影 / inset shadow**：代码中无任何实现
|
|
||||||
3. **字距（letter-spacing）与行高倍数**：无；行距全靠显式 y 偏移
|
|
||||||
4. **亚克力的模糊半径/透明度数值**：由 Windows `HostBackdropBrush` 系统决定，代码只给 `HOST_BACKDROP_INSET = 1.0`
|
|
||||||
→ Electron 侧**没有**等价物：`setBackgroundMaterial('acrylic')` 是整窗系统材质（跟随应用主题、覆盖窗口矩形），
|
|
||||||
不能像 `DWMWA_USE_HOSTBACKDROPBRUSH` 那样只画在圆角形状里；本项目因此改用无 backdrop 的降级色（见 §8）
|
|
||||||
5. **强调色用于岛内 UI**：岛内几乎没有强调色（只有资源占用的 CPU/RAM/警告/危险色）；
|
|
||||||
统一强调色 `#0A84FF` 仅存在于**设置窗口**（`COLOR_ACCENT`）
|
|
||||||
6. **岛自身的亮/暗主题**：岛屿永远是深底白字；明暗主题只在设置窗口
|
|
||||||
7. **固定渐变色背景**：真实 `dynamic` 背景是封面图，没有固定渐变；
|
|
||||||
仅设置页预览用 `rgb(18,12,36) → rgb(8,24,48)`（可当静态替代）
|
|
||||||
8. **CSS 等价的超椭圆圆角公式**：真实实现是 Flutter 超椭圆查表（`src/utils/shape.rs`），没有简单的 border-radius 参数
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. 给 Web/Electron 复刻的映射速查
|
|
||||||
|
|
||||||
- 岛容器：定位在屏幕顶上 `top: 10px`、水平居中，尺寸与圆角用 spring 插值
|
|
||||||
（`cubic-bezier` 或 JS 弹簧，参考 `stiffness 0.10 / damping 0.68`）；`overflow: hidden` 做裁切
|
|
||||||
- compact：`120×27`（有歌词时宽度跟着文本走，上限 700；只有媒体无歌词时 155），`border-radius: 13.5px`（胶囊）
|
|
||||||
- expanded：`360×200`，`border-radius: 48px`（想要 iOS 味请用 SVG 超椭圆路径）
|
|
||||||
- 背景：`#000` 不透明；"glass" **不要**照搬 WinIsland 的 host backdrop —— Electron 的
|
|
||||||
`setBackgroundMaterial()` 是"整窗系统材质"，覆盖范围是窗口矩形而不是卡片形状，且明暗跟随应用主题，
|
|
||||||
在浅色主题下会给卡片垫出一圈浅色面板（详见 `packages/desktop-client/src/main/island.ts`）；
|
|
||||||
我们改用 WinIsland 自己的**无 backdrop 降级色** `rgba(32,32,36,.804)` 画在卡片上；
|
|
||||||
"dynamic" 用封面模糊层 + `rgba(20,20,24,.471)` 叠加
|
|
||||||
- 描边：`1px solid rgba(255,255,255,.118)`（纯色样式，展开时淡出）/ `.157`（glass、dynamic）
|
|
||||||
- 阴影：仅展开 `0 2px σ rgba(0,0,0,.11)`（σ ≈ 3px）
|
|
||||||
- 文字：`-apple-system / "Microsoft YaHei" / "Segoe UI"`，白 + alpha 分层（.65 / .72 / .9 / .6 / .5 / .58 / .62）
|
|
||||||
- 图标：内联 SVG，`fill: currentColor`，播放/暂停按 640 坐标系、尺寸 ≈ 34.5×37
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 附：ClassHelper实际采纳了哪些（本次重写对照表）
|
|
||||||
|
|
||||||
| WinIsland 做法 | 出处 | 我们的落地 | 验证 |
|
|
||||||
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
|
|
||||||
| **窗口一次建大包围盒，形变发生在窗口内** | `window/app/layout.rs` `required_window_size()` + `PADDING=80` | 窗口固定为「最大形态 + `ISLAND_SHADOW_PAD(10)`」，开合期间**一帧都不 setBounds** | 逐帧窗口签名恒为 `476x282@482,-2`（只有 1 种） |
|
|
||||||
| 尺寸/圆角由弹簧驱动 | `utils/physics.rs` + `app.rs` `IslandSprings`（w/h/r = `0.10/0.68`） | `src/island/spring.ts` 同参数同更新式（dt 以帧计、`damping^dt`、换向保留 35% 动量 + 20% 距离上限），并加**零过冲钳制** | 岛中心/边缘波动 0.00px、无过冲 |
|
|
||||||
| 连续圆角（超椭圆） | `utils/shape.rs` `continuous_rounded_rect_path` / `expanded_island_radius = min(48*scale, w/2, h/2)` | `src/island/squircle.ts` 超椭圆角路径；展开半径 `min(48×圆角/20, w/2, h/2)` | 形状 bbox 与卡片框一致（±2px） |
|
|
||||||
| 内容交叉淡入 `expanded=progress²`、`mini=1-1.5×progress` | `core/render.rs`（`MINI_FADE_RATE=1.5`） | 两层常驻、透明度按同一公式 | 截图与 DOM 断言 |
|
|
||||||
| 描边 1px 白 alpha 30（纯色）/ 40（glass） | `core/render.rs` `BORDER_*_ALPHA` | `--wn-border` 取同值（`.118` / `.157`） | 计算样式断言 |
|
|
||||||
| 展开投影 `rgba(0,0,0,.11)`、y+2、σ=3 | `draw_expanded_shadow` | `drop-shadow(0 2px 3px rgba(0,0,0,.11))` | 截图 |
|
|
||||||
| 纯黑底 / 亚克力（HostBackdropBrush） | `background.rs` + `win32.rs` `DWMWA_USE_HOSTBACKDROPBRUSH` | 纯黑底 / **glass 用 CSS 半透明深色卡**（WinIsland 无 backdrop 降级色 `rgba(32,32,36,.804)`）；**不调用** `setBackgroundMaterial()` | 计算样式 + 「卡片外圈透出桌面」整屏截图像素断言 |
|
|
||||||
| `set_cursor_hittest` 命中控制 | `frame.rs`（`set_cursor_hittest`） | 默认 `setIgnoreMouseEvents(true,{forward:true})`，渲染层命中测试后切换 | 岛内 true / 岛外 false |
|
|
||||||
| 空闲细缝 `hidden_width = 5` | `core/config.rs` | 6px 宽竖条（窗口固定，不再受 Windows 最小窗口高度限制） | 空闲 `6x22` → 来消息 `268x44` |
|
|
||||||
| 6 个停靠位 `DockPosition` | `core/config.rs` | 顶/底 × 左/中/右 6 锚点，岛（而非窗口）精确落在锚点 | 6 锚点坐标断言 |
|
|
||||||
| `font_size` = 基础字号 × 各文本系数 | `core/render/mini.rs`、`ui/expanded/music_view.rs` | 基础字号 11–20px × 系数表（标题 1.08/正文 0.95/次要 0.78/徽标与按钮 0.76/胶囊 0.92、0.74） | 13→19px 全部文本倍率 1.462 |
|
|
||||||
| 未采纳：音乐/歌词/小组件/音量浮窗 | `ui/expanded/**`、`ui/widget/**` | 业务不同（我们做通知/作业/叫人/紧急） | — |
|
|
||||||
@@ -1,38 +0,0 @@
|
|||||||
{
|
|
||||||
"$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
|
|
||||||
"build": {
|
|
||||||
"content": [
|
|
||||||
{
|
|
||||||
"files": ["**/*.{md,yml}"],
|
|
||||||
"exclude": ["_site/**", "obj/**", "templates/**", "node_modules/**", "404.html"]
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"resource": [
|
|
||||||
{
|
|
||||||
"files": ["screenshots/**", "images/**"],
|
|
||||||
"exclude": ["**/*.md"]
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"output": "_site",
|
|
||||||
"template": ["default", "modern", "templates/classhelper"],
|
|
||||||
"globalMetadata": {
|
|
||||||
"_appName": "ClassHelper",
|
|
||||||
"_appTitle": "ClassHelper文档",
|
|
||||||
"_appLogoPath": "logo.png",
|
|
||||||
"_appLogoUrl": "",
|
|
||||||
"_appFaviconPath": "favicon.png",
|
|
||||||
"_enableSearch": true,
|
|
||||||
"_disableContribution": false,
|
|
||||||
"_gitContribute": {
|
|
||||||
"repo": "https://github.com/LoveChengke/classhelper",
|
|
||||||
"branch": "master"
|
|
||||||
},
|
|
||||||
"_appFooter": "<div class=\"ch-footer\"><span>ClassHelper（Class Helper）· 文档</span><span class=\"ch-footer-sep\">·</span><a href=\"https://github.com/LoveChengke/classhelper\">GitHub 仓库</a><span class=\"ch-footer-sep\">·</span><a href=\"https://github.com/LoveChengke/classhelper/releases\">下载与更新日志</a><span class=\"ch-footer-sep\">·</span><span>构建于 docfx</span></div>"
|
|
||||||
},
|
|
||||||
"sitemap": {
|
|
||||||
"baseUrl": "https://lovechengke.github.io/ClassHelper/docs/",
|
|
||||||
"changefreq": "weekly",
|
|
||||||
"priority": 0.5
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
-137
@@ -1,137 +0,0 @@
|
|||||||
---
|
|
||||||
title: 常见问题
|
|
||||||
description: 装不上、连不上、改了不生效——最常被问到的那些问题。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 常见问题
|
|
||||||
|
|
||||||
## 安装与启动
|
|
||||||
|
|
||||||
### 双击客户端"点了没反应"
|
|
||||||
|
|
||||||
**关窗只是隐藏到托盘，进程还在。** 再双击 EXE 会被单实例锁秒退（看起来像没反应），
|
|
||||||
安装包也会因为"应用正在运行"装不上。先**从托盘右键退出**。
|
|
||||||
|
|
||||||
### 安装包装不上，说应用正在运行
|
|
||||||
|
|
||||||
同上。托盘 → 退出 ClassHelper。
|
|
||||||
|
|
||||||
## 连接与登录
|
|
||||||
|
|
||||||
### 后端明明在跑，`Invoke-WebRequest` 却返回别人的 404
|
|
||||||
|
|
||||||
**系统代理拦住了 `127.0.0.1`**。自测请加 `-NoProxy`（`curl.exe` 用 `--noproxy '*'`）。
|
|
||||||
项目内的 Node 脚本直连，不受影响。
|
|
||||||
|
|
||||||
### 客户端连不上服务器
|
|
||||||
|
|
||||||
1. 服务器地址要填**局域网 IP**（`http://192.168.1.10:4000`），不要写 `localhost`（那是客户端自己）；
|
|
||||||
2. 服务器防火墙放行 **4000**；
|
|
||||||
3. 服务器上如果开了系统代理，内网地址可能被代理接管 —— 浏览器与客户端**不会**自动绕过
|
|
||||||
请在系统代理中为内网服务端设置绕过规则；
|
|
||||||
4. 在服务器本机 `curl.exe --noproxy '*' http://127.0.0.1:4000/healthz` 是不是 200？
|
|
||||||
|
|
||||||
### 页面能打开，但接口全 401
|
|
||||||
|
|
||||||
令牌过期，或者 `.env` 里的 `JWT_SECRET` 被换过（换过之后所有人的令牌都失效）。重新登录即可。
|
|
||||||
|
|
||||||
### 提示「无法连接 GitHub」/ 检查更新查不到
|
|
||||||
|
|
||||||
**这是设计内的结果**，不是错误。机房与教室机器常常只有内网，请求会超时；
|
|
||||||
界面按"暂时查不到更新"呈现。失败结果同样进缓存，不会每点一次都白等一个超时。
|
|
||||||
|
|
||||||
### 反向代理后面所有请求都被限流
|
|
||||||
|
|
||||||
反向代理没设 `TRUST_PROXY=1`，导致所有请求都被算作代理那一个 IP。
|
|
||||||
|
|
||||||
## 功能行为
|
|
||||||
|
|
||||||
### 上课时段发的通知学生看不到
|
|
||||||
|
|
||||||
**这是设计行为。** 上课时段普通通知只进队列、不打断课堂，**下课自动补弹**。
|
|
||||||
紧急通知与叫人则立刻弹。规则见[通知与提醒](app/notifications.md)。
|
|
||||||
|
|
||||||
### 老师说发了通知，教室机器上什么都没弹
|
|
||||||
|
|
||||||
按顺序排查：
|
|
||||||
|
|
||||||
1. 客户端顶栏的实时通道是不是"已连接"？
|
|
||||||
2. 现在是上课时段吗？（同上，是设计行为）
|
|
||||||
3. 确认客户端登录的是这条通知对应的班级。
|
|
||||||
4. 反向代理放行 `/socket.io/` 的 WebSocket 升级了吗？
|
|
||||||
|
|
||||||
### 屏幕上出现了第二个灵动岛，点它反应不对
|
|
||||||
|
|
||||||
那是**自动化验证实例**的岛 —— `pnpm verify:desktop` / `verify:packaged` 会真的在屏幕上放一个，
|
|
||||||
而且它归脚本控制，会自己展开 / 收起 / 消失。验证实例的岛是**洋红主题色**，一眼可辨。
|
|
||||||
|
|
||||||
### 灵动岛上的文字往右跳一下再缩回
|
|
||||||
|
|
||||||
那是早期的布局问题（胶囊内容跟着卡片重排），已经修掉了。如果你的版本还有，
|
|
||||||
说明用的是旧产物 —— 参考[更新与升级](management/upgrade.md)。
|
|
||||||
|
|
||||||
### 灵动岛调"左右边距"没反应
|
|
||||||
|
|
||||||
**左右边距只在「左 / 右停靠」时生效。** 默认是「顶部居中」，水平锚点就是屏幕中线，
|
|
||||||
这时调它不会有任何变化 —— 设置页会把那个滑块置灰并写明原因。
|
|
||||||
|
|
||||||
### 触摸屏上点不开灵动岛
|
|
||||||
|
|
||||||
触摸屏（希沃白板等）会自动走「触摸模式」，正常情况不用手动开。
|
|
||||||
如果确实点不开，到「设置 → 关于」看一眼诊断信息，并把客户端版本反馈出来。
|
|
||||||
|
|
||||||
### 教室机器上刚录的作业又要弹一次？
|
|
||||||
|
|
||||||
**本机录入的作业不会上岛**（自己通知自己没意义）。如果弹了，说明这条不是这台机器录的。
|
|
||||||
|
|
||||||
### 学生登录不了
|
|
||||||
|
|
||||||
**学生没有个人账号。** ClassHelper 班级端统一用**班级码 + 班级密码**登录（见[装 ClassHelper 班级端](get-started/client.md)）。
|
|
||||||
用学生用户名去登录一定会失败，这是设计。
|
|
||||||
|
|
||||||
### 客户端里找不到"修改密码"
|
|
||||||
|
|
||||||
**是刻意移除的。** 防止教室机器上误改班级密码后，别的教室机器被锁在门外。
|
|
||||||
班级密码由管理员在 Web 端「班级管理」维护；教师 / 管理员本人密码在 Web 端顶栏头像菜单里改。
|
|
||||||
|
|
||||||
## 开发与运维
|
|
||||||
|
|
||||||
### `pnpm db:seed` 报 `Cannot find module '.../@classhelper/shared/dist/index.js'`
|
|
||||||
|
|
||||||
`packages/shared` 还没构建（它产出 `dist`，三端与 seed 都依赖）。先 `pnpm build:shared`。
|
|
||||||
|
|
||||||
### 根目录跑 `pnpm db:deploy` 说不存在
|
|
||||||
|
|
||||||
根 `package.json` 没有这个脚本。正确写法：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm --filter @classhelper/server db:deploy
|
|
||||||
```
|
|
||||||
|
|
||||||
### 后端改了代码不生效
|
|
||||||
|
|
||||||
`tsx src/index.ts` **不热载**。用 `pnpm dev:server`（watch），或重启服务端。
|
|
||||||
**切换数据库之后必须重启**才会连上新库。
|
|
||||||
|
|
||||||
### 上传表格报「服务器内部错误：request entity too large」
|
|
||||||
|
|
||||||
表格导入的文件上限是 **8MB**（请求体 12MB），超限应返回 **413 `IMPORT_TOO_LARGE`** 与中文提示。
|
|
||||||
如果你看到的是英文兜底错误，说明这个异常没被映射 —— 那是 bug，不是你的文件太大。
|
|
||||||
|
|
||||||
### 切了 MySQL 之后重启又连回旧库
|
|
||||||
|
|
||||||
服务端安装形态里，安装目录的 `.env` **必须是指向 `/etc/classhelper/config.env` 的软链**。
|
|
||||||
两处不是同一个文件时，一键切换会"看起来成功、重启后又连回旧库"。
|
|
||||||
Linux 上跑 `sudo classhelper doctor` 有专门一条断言盯着这个软链。
|
|
||||||
|
|
||||||
### SQLite 报 `database is locked`
|
|
||||||
|
|
||||||
同一个数据库文件只允许一个服务实例。确认没有重复启动；需要并发就换 MySQL。
|
|
||||||
|
|
||||||
## 还没解决？
|
|
||||||
|
|
||||||
- **开发与构建环境**的问题（命令、代理与 TLS、ClassIsland 路径与日志编码……）
|
|
||||||
记在仓库的 [`AGENTS.md`](https://github.com/LoveChengke/classhelper/blob/master/AGENTS.md) 里；
|
|
||||||
- 功能行为的权威说明在[完整参考](reference.md)；
|
|
||||||
- 都不是的话，去 [Issues](https://github.com/LoveChengke/classhelper/issues) 提一个，
|
|
||||||
附上版本号（Web 端顶栏 / 客户端「设置 → 关于」里都有）和日志。
|
|
||||||
@@ -1,85 +0,0 @@
|
|||||||
---
|
|
||||||
title: 装 ClassHelper 班级端
|
|
||||||
description: 在教室机器上安装 ClassHelper桌面客户端，用班级码登录，并第一次跑通实时通知。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 装 ClassHelper 班级端
|
|
||||||
|
|
||||||
桌面客户端装在**教室的那台机器**上（教室大屏、讲台电脑）。它是学生看课表作业的地方，
|
|
||||||
也是「消息到达的第一现场」—— 灵动岛就长在这一端。
|
|
||||||
|
|
||||||
## 1. 下载与安装
|
|
||||||
|
|
||||||
从 [Releases](https://github.com/LoveChengke/classhelper/releases) 取：
|
|
||||||
|
|
||||||
| 产物 | 用途 |
|
|
||||||
| ------------------------------------- | ------------------------------------------ |
|
|
||||||
| `ClassHelper-<版本>-x64-setup.exe` | 安装包（约 98 MB），装到本机并建快捷方式 |
|
|
||||||
| `ClassHelper-<版本>-x64-portable.exe` | 单文件便携版，双击即用，适合不改动机房机器 |
|
|
||||||
|
|
||||||
要自己打：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm dist:win # 安装包 + 便携版（两个都是成品，没有中间的解包目录）
|
|
||||||
```
|
|
||||||
|
|
||||||
> **双击没反应？** 关窗只是隐藏到托盘，进程还在，再双击会因单实例锁秒退 —— 先从托盘右键退出。
|
|
||||||
|
|
||||||
## 2. 登录
|
|
||||||
|
|
||||||
打开客户端 → 填三项：
|
|
||||||
|
|
||||||
| 字段 | 填什么 |
|
|
||||||
| ---------- | ------------------------------------------------------------- |
|
|
||||||
| 服务器地址 | `http://<服务器IP>:4000`（局域网用内网 IP，别用 `localhost`） |
|
|
||||||
| 班级码 | 管理员在「班级管理」里给这个班设的码，例如 `G203` |
|
|
||||||
| 班级密码 | 建班级时设的密码 |
|
|
||||||
|
|
||||||
旁边的「测试连接」可以先确认网络通。**已登录过但服务器暂时不可达时**，登录页会给一个「离线进入」——
|
|
||||||
进去后看到的是上次缓存的课表 / 作业 / 通知（顶部会标「离线缓存」），网络恢复后自动刷新。
|
|
||||||
|
|
||||||
> 客户端**没有改密码入口**，这是刻意的：教室机器上误改班级密码会把别的机器锁在门外。
|
|
||||||
> 班级密码由管理员在 Web 端「班级管理 → 修改班级账号」维护。
|
|
||||||
|
|
||||||
## 3. 首次启动的六步向导
|
|
||||||
|
|
||||||
第一次启动会在登录页上自动弹一个向导：欢迎 → 连接服务器 → 登录班级 → 登录之后（主界面与离线缓存）→
|
|
||||||
灵动岛提醒 → 完成。走完或跳过都会记为已完成，之后不再自动弹。
|
|
||||||
|
|
||||||
想重看：登录页的**「查看使用引导」**，或进去之后 **设置 → 通用 → 使用引导**。
|
|
||||||
|
|
||||||
## 4. 认一认主界面
|
|
||||||
|
|
||||||
左侧是四个一级项（**课表 / 作业 / 通知 / 成绩**）加上一个可展开的**设置**分组，
|
|
||||||
顶部汉堡按钮把整栏收成 64px 的图标导轨（折叠状态会记住）。「通知」项上有未读红点。
|
|
||||||
|
|
||||||
| 页面 | 一句话 |
|
|
||||||
| ---- | -------------------------------------------------------------- |
|
|
||||||
| 课表 | 周视图 + 「今天」时间轴（大时钟 / 正在上什么 / 下一节） |
|
|
||||||
| 作业 | 看板模式（按科目卡片、可全屏）/ 列表模式；教室机器还能录入作业 |
|
|
||||||
| 通知 | 未读红点、优先级标签、点开自动标为已读 |
|
|
||||||
| 成绩 | 班级账号看到的是全班总览（表格 + 柱状图 + 等级分布） |
|
|
||||||
| 设置 | 通用 / 外观 / 灵动岛 / 提醒 / 账号 / 关于，六个子页 |
|
|
||||||
|
|
||||||
细节见[应用帮助](../app/index.md)。
|
|
||||||
|
|
||||||
## 5. 在教室机器上把它调成"能看"的样子
|
|
||||||
|
|
||||||
教室大屏的观看距离和角度跟办公桌不一样，装完建议顺手做三件事：
|
|
||||||
|
|
||||||
1. **开全屏作业看板** —— 作业页「全屏看板」，按屏幕尺寸自动排版，整个屏幕刚好放得下、不用滚动。
|
|
||||||
2. **调灵动岛** —— 设置 → 灵动岛：高度、宽度、字号、主题色、停靠位置、视觉风格。
|
|
||||||
讲台机器上通常把字号调大一点、位置放到顶部居中。
|
|
||||||
触摸屏（希沃白板等）走的是另一套命中逻辑，客户端会自动识别，不用手动开。
|
|
||||||
3. **查看提醒规则** —— 设置 → 提醒：普通通知下课显示，紧急提醒立即显示。
|
|
||||||
这个选择会同步到班级记录，服务端据此决定要不要广播到客户端。
|
|
||||||
|
|
||||||
## 6. 确认实时链路是通的
|
|
||||||
|
|
||||||
在 Web 管理端给这个班发一条普通通知，教室机器上应该几秒内出现灵动岛胶囊。如果没有：
|
|
||||||
|
|
||||||
- 客户端顶栏的实时通道状态是不是"已连接"？
|
|
||||||
- 现在是上课时段吗？上课时段的普通通知**只进队列、下课才弹**，这是设计行为，不是故障。
|
|
||||||
- 服务器与教室机器之间能互相 ping 通吗？防火墙放行 4000 了吗？
|
|
||||||
|
|
||||||
排查清单见[常见问题](../faq.md)。
|
|
||||||
@@ -1,60 +0,0 @@
|
|||||||
---
|
|
||||||
title: 发布第一条内容
|
|
||||||
description: 发通知、布置作业、叫人、录成绩——把 ClassHelper真正用起来的第一轮操作。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 发布第一条内容
|
|
||||||
|
|
||||||
前面几步做完，系统就完整了。这一页走一遍四件最常用的事，每件都点出**它会不会弹、弹在哪个端**。
|
|
||||||
|
|
||||||
## 发一条通知
|
|
||||||
|
|
||||||
**通知发布** → 选班级 → 填标题和内容 → 选优先级 → 发布。
|
|
||||||
|
|
||||||
| 优先级 | ClassHelper 班级端表现 |
|
|
||||||
| ------ | -------------------------------------------------------------------------- |
|
|
||||||
| 普通 | 课间弹胶囊，点击展开；**上课时段只进队列**，下课自动补弹 |
|
|
||||||
| 重要 | 同上，卡片上带优先级标签 |
|
|
||||||
| 紧急 | **无论是否上课都立即展开**（卡片内部红色呼吸光晕 + 紧急角标），45 秒后收起 |
|
|
||||||
|
|
||||||
**上课时段发紧急通知会被拦一次。** 服务端返回 `409 URGENT_DURING_CLASS`，前端弹一个全屏二次确认，
|
|
||||||
上面写着"现在为上课时间段……"、正在上的那节课，还有待发布的标题；确认按钮带 **3 秒倒计时**，
|
|
||||||
倒计时结束前点不动。确认之后才真的发出去。
|
|
||||||
|
|
||||||
这个拦截是**服务端做的**，绕过界面直接调接口一样会被拦 —— 它是产品行为，不是前端提醒。
|
|
||||||
|
|
||||||
## 布置一份作业
|
|
||||||
|
|
||||||
**作业发布** → 选班级 / 科目 → 填标题与要求 → 选**所属日期** → 发布。
|
|
||||||
|
|
||||||
> 作业按**所属日期**归类，不是按录入时间。晚上 8 点留的作业算今天。
|
|
||||||
> 老师可以给今天、明天甚至上周补录一份作业，客户端按日期查得到。
|
|
||||||
|
|
||||||
附件支持站内相对路径或 `http(s)://` 链接（其他 scheme 服务端会拒，避免被当成脚本执行）。
|
|
||||||
|
|
||||||
ClassHelper 班级端那边默认是**看板模式**：按科目分卡片、每条作业完整显示要求、整个看板缩放到刚好铺满屏幕；
|
|
||||||
老师也可以在教室机器上直接**录入作业**、勾选**未交名单**（教室机器用的是班级账号）。
|
|
||||||
|
|
||||||
## 叫一位同学
|
|
||||||
|
|
||||||
**通知发布 → 叫人**（或管理员在**学生管理 → 叫人**）→ 选学生 → 点一个快捷短语或自己写一句 → 发送。
|
|
||||||
|
|
||||||
| 级别 | ClassHelper 班级端 |
|
|
||||||
| -------- | ------------------------------------------------------------------ |
|
|
||||||
| 普通叫人 | 课间显示「叫人」胶囊，点击展开；**上课时段只进队列**，下课自动弹出 |
|
|
||||||
| 紧急叫人 | **无视上课时段立即展开**，上课时被收起后仍保留胶囊、可再次点开 |
|
|
||||||
|
|
||||||
文案是「请 XXX 同学找 XXX 老师」，卡片上是「收到」按钮（复用通知的已读机制）。
|
|
||||||
|
|
||||||
> 学生管理页是管理员专属，但班主任与科任老师同样需要叫人，所以给老师留的入口在「通知发布 → 叫人」。
|
|
||||||
|
|
||||||
## 录一次成绩
|
|
||||||
|
|
||||||
**成绩录入** → 选班级与考试名称 → 单条录入 / 批量录入 / 导入表格。
|
|
||||||
|
|
||||||
- **科目**下拉同样是全校统一目录，选一个该班还没有的科目会自动建课。
|
|
||||||
- 导入表格支持 `.xlsx / .xls / .csv / .tsv`，列名按同义词自动映射（「用户名→学号」「得分→分数」），
|
|
||||||
也可以手动改。**文件上限 8MB**，超了会返回明确的 413 而不是一句英文的内部错误。
|
|
||||||
- 导入结果会给逐行的错误与警告，`errors[].row` 是 **Excel 视角的行号**（含表头），改完可以再导。
|
|
||||||
|
|
||||||
ClassHelper 班级端看到的是**全班总览**：表格（分数 / 得分率 / 等级）+ 柱状图 + 等级分布 + 最近更新。
|
|
||||||
@@ -1,38 +0,0 @@
|
|||||||
---
|
|
||||||
title: 快速上手
|
|
||||||
description: 从零把 ClassHelper跑起来：装服务端、认管理端、建班级排课、装 ClassHelper 班级端、发第一条内容。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 快速上手
|
|
||||||
|
|
||||||
ClassHelper不是一个单机软件，它由三部分组成，**必须先有服务端，管理端与客户端才有内容可看**：
|
|
||||||
|
|
||||||
| 组成部分 | 装在哪 | 谁用 | 必须先装？ |
|
|
||||||
| -------------- | --------------------------------------- | -------------------------- | ---------------- |
|
|
||||||
| **服务端** | 一台能一直开着的机器（服务器/办公电脑） | —（它同时托管 Web 管理端） | ✅ 是 |
|
|
||||||
| **Web 管理端** | 不用装 —— 浏览器打开服务端地址即可 | 老师、班主任、管理员 | 跟着服务端一起有 |
|
|
||||||
| **桌面客户端** | 教室的电脑 / 教室大屏 | 学生看课表作业、老师录作业 | 服务端就绪之后 |
|
|
||||||
|
|
||||||
按顺序走下面这几页就行，全程大约半小时（不含下载时间）：
|
|
||||||
|
|
||||||
1. [系统要求](requirements.md) —— 先确认机器和网络够用
|
|
||||||
2. [安装服务端](server.md) —— Windows 安装包 / Linux 一键脚本 / Docker / 源码跑
|
|
||||||
3. [认识 Web 管理端](web-admin.md) —— 登录进去，认一认界面
|
|
||||||
4. [建班级、排课表](setup-class.md) —— 这是后面所有功能的前提
|
|
||||||
5. [装 ClassHelper 班级端](client.md) —— 教室机器用班级码登录
|
|
||||||
6. [发布第一条内容](first-content.md) —— 通知 / 作业 / 叫人 / 成绩
|
|
||||||
|
|
||||||
## 只想先看看它长什么样？
|
|
||||||
|
|
||||||
不用装任何东西也能看出来它在干什么：
|
|
||||||
|
|
||||||
- **看界面**：本页文档里各处嵌的都是实机截图，比如[灵动岛](../app/island.md)、[课表](../app/schedules.md)。
|
|
||||||
- **本地跑一套演示数据**：装好 Node 20.19+ 与 pnpm 之后，
|
|
||||||
`pnpm install && pnpm build:shared && pnpm db:seed && pnpm dev` 会在本地拉起一套带演示班级的后端与
|
|
||||||
Web 管理端（详见[安装服务端](server.md#从源码跑开发模式)）。
|
|
||||||
|
|
||||||
## 装完之后呢
|
|
||||||
|
|
||||||
- 日常怎么用 → [应用帮助](../app/index.md)
|
|
||||||
- 服务器怎么维护（备份、换库、升级） → [管理运维](../management/index.md)
|
|
||||||
- 出问题了 → [常见问题](../faq.md)
|
|
||||||
@@ -1,75 +0,0 @@
|
|||||||
---
|
|
||||||
title: 系统要求
|
|
||||||
description: ClassHelper 服务端、Web 管理端、桌面客户端的运行环境与网络要求。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 系统要求
|
|
||||||
|
|
||||||
## 服务端
|
|
||||||
|
|
||||||
服务端的安装包**自带 Node 运行时**，目标机器不需要另外装 Node.js，也不需要数据库软件
|
|
||||||
（默认用内嵌的 SQLite）。
|
|
||||||
|
|
||||||
| 项目 | 要求 |
|
|
||||||
| -------- | --------------------------------------------------------------------------- |
|
|
||||||
| 操作系统 | Windows 10 / 11 / Server 2016+（x64）；Linux（glibc 2.28+，见下）；Docker |
|
|
||||||
| 内存 | 512 MB 起步，2 GB 以上更稳（Node + SQLite 常驻约 120–200 MB） |
|
|
||||||
| 磁盘 | 程序约 340 MB（免安装目录）/ 安装后约 400 MB；数据按班级量增长，通常几十 MB |
|
|
||||||
| CPU | 任意 x64；不需要独显 |
|
|
||||||
|
|
||||||
**Linux 的 glibc 要求**：内置的 Node 官方 linux-x64 构建要求 glibc ≥ 2.28。
|
|
||||||
CentOS 7 是 2.17，一键安装器会检测并自动换成 `-glibc-217` 变体（尽力而为，未做长期验证）。
|
|
||||||
判据：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ldd --version | head -1
|
|
||||||
```
|
|
||||||
|
|
||||||
**外网**：服务端只在「检查更新」时访问 GitHub，且失败是设计内的结果（返回"查不到"，不报错）。
|
|
||||||
内网机器可以完全不连通外网。
|
|
||||||
|
|
||||||
## Web 管理端
|
|
||||||
|
|
||||||
不需要安装，用浏览器打开服务端地址即可。
|
|
||||||
|
|
||||||
| 项目 | 要求 |
|
|
||||||
| -------- | --------------------------------------------------------------------------- |
|
|
||||||
| 浏览器 | Chrome / Edge 100+、Firefox 100+、Safari 15+（要支持 CSS 容器查询） |
|
|
||||||
| 屏幕 | 桌面 1280×720 以上；手机（≤768px）有一套独立的抽屉式布局，同样可用 |
|
|
||||||
| 安装 PWA | 手机 / 桌面 Chrome 里「添加到主屏幕」可当 App 用（需要 HTTPS 或 localhost） |
|
|
||||||
|
|
||||||
## 桌面客户端（ClassHelper 班级端 / 教室机器）
|
|
||||||
|
|
||||||
| 项目 | 要求 |
|
|
||||||
| -------- | ---------------------------------------------------------------------------- |
|
|
||||||
| 操作系统 | Windows 10 / 11（x64） |
|
|
||||||
| 内存 | 4 GB 以上（Electron 常驻约 250–400 MB） |
|
|
||||||
| 磁盘 | 安装后约 330 MB |
|
|
||||||
| 显卡 | 有 D3D11 即可；希沃一体机、老显卡、虚拟机都做过兼容（没有裁剪 GPU 回退组件） |
|
|
||||||
| 触摸屏 | 支持，会自动进入[触摸模式](../app/island.md)（希沃白板等） |
|
|
||||||
|
|
||||||
> 客户端**只有 Windows 版**。Linux / macOS 上目前只能用 Web 管理端。
|
|
||||||
|
|
||||||
## 网络
|
|
||||||
|
|
||||||
三端的通信都指向服务端的 **HTTP 端口（默认 4000）**，其中：
|
|
||||||
|
|
||||||
- REST 接口：`/api/*`
|
|
||||||
- 实时推送（Socket.IO）：`/socket.io/`
|
|
||||||
- Web 管理端静态资源：`/`（由服务端托管）
|
|
||||||
|
|
||||||
| 场景 | 要做什么 |
|
|
||||||
| ------------------------- | --------------------------------------------------------------------------------------- |
|
|
||||||
| 只在服务器本机用 | 什么都不用做，`http://127.0.0.1:4000` |
|
|
||||||
| 教室机器 / 老师电脑也要用 | 客户端与管理端填服务器的**局域网 IP**（如 `http://192.168.1.10:4000`），防火墙放行 4000 |
|
|
||||||
| 公网访问 | 前面加 Nginx / Caddy 反代并启用 HTTPS，见[生产部署指南](../management/production.md) |
|
|
||||||
|
|
||||||
> **别用代理**。自测时用 `curl.exe --noproxy '*'`，PowerShell 用 `-NoProxy`；
|
|
||||||
> 教室机器上如果开了系统代理，填服务端地址后可能拿到代理返回的 404。请检查系统代理绕过列表是否包含服务端的局域网地址。
|
|
||||||
|
|
||||||
## 卸载 / 重置
|
|
||||||
|
|
||||||
- 服务端：开始菜单 → 卸载。卸载会保留数据库（`data` 目录改名为 `data.backup`）。
|
|
||||||
- 客户端：从托盘退出后卸载；重置配置删 `%APPDATA%\class-helper`（或客户端「关于」页显示的数据目录）。
|
|
||||||
|
|
||||||
下一步：[安装服务端](server.md)。
|
|
||||||
@@ -1,142 +0,0 @@
|
|||||||
---
|
|
||||||
title: 安装服务端
|
|
||||||
description: 用 Windows 安装包、Linux 一键脚本、Docker 或源码把 ClassHelper 服务端跑起来。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 安装服务端
|
|
||||||
|
|
||||||
服务端是整个系统的中心：它存数据、发实时推送，**并且顺带托管 Web 管理端**（所以老师那一端不用单独装东西）。
|
|
||||||
|
|
||||||
四种装法按场景选，任选一种即可：
|
|
||||||
|
|
||||||
| 方式 | 适合 | 一句话 |
|
|
||||||
| --------------------------------- | -------------------------------------- | ------------------------------- |
|
|
||||||
| [Windows 安装包](#windows-安装包) | 学校机房、教师办公电脑、单机即完整系统 | 双击 exe，装完自动启动 |
|
|
||||||
| [Linux 一键安装](#linux-一键安装) | 学校已有 Linux 服务器 | 一条命令，带 systemd 与运维命令 |
|
|
||||||
| [Docker](#docker) | 云服务器、想跟别的服务共用一台机器 | `docker compose up -d` |
|
|
||||||
| [源码跑](#从源码跑开发模式) | 想改代码、想先看看它长什么样 | `pnpm dev` |
|
|
||||||
|
|
||||||
## Windows 安装包
|
|
||||||
|
|
||||||
### 生成安装包
|
|
||||||
|
|
||||||
安装包不入库（体积大），从 [Releases](https://github.com/LoveChengke/classhelper/releases) 直接下载
|
|
||||||
`ClassHelper 服务端-<版本>-x64-setup.exe` 即可。要自己打：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm dist:server # 首次会执行一次 npm install（约 2 分钟）
|
|
||||||
pnpm dist:server -- --reuse-deps # 迭代打包：复用已装依赖，跳过 npm install
|
|
||||||
```
|
|
||||||
|
|
||||||
产物：
|
|
||||||
|
|
||||||
| 路径 | 说明 |
|
|
||||||
| ----------------------------------------------------------------------- | -------------------------- |
|
|
||||||
| `releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe` | 安装程序（约 62 MB，NSIS） |
|
|
||||||
|
|
||||||
> 交付产物只有安装程序。组装出来的那份运行时（内置 Node + 依赖 + 后端与 Web 产物，约 335 MB）
|
|
||||||
> 只是打安装包的中间物，落在 `.cache/server-staging/<版本>/` 下，打完脚本就删掉了 ——
|
|
||||||
> 想留一份可直接双击运行的副本，见本文末「不用安装程序的手动部署」。
|
|
||||||
|
|
||||||
包内自带 Node 运行时、后端产物、Web 管理端产物、生产依赖、迁移 SQL、随机 `JWT_SECRET` 的 `.env`
|
|
||||||
与启停脚本。目标机器**不需要预先安装 Node.js**。
|
|
||||||
|
|
||||||
### 安装与启动
|
|
||||||
|
|
||||||
双击安装程序即可，**不需要管理员权限**（当前用户级安装）。
|
|
||||||
|
|
||||||
- 安装目录：`%LOCALAPPDATA%\Programs\ClassHelperServer`
|
|
||||||
- 静默安装：`"ClassHelper 服务端-<版本>-x64-setup.exe" /S`
|
|
||||||
- 开始菜单：启动服务 / 停止服务 / 重启服务 / 打开管理端 / 使用说明 / 卸载
|
|
||||||
- 自动加入当前用户开机自启
|
|
||||||
|
|
||||||
装完服务会自动启动并完成首次初始化：数据库为空则执行随包迁移建表 → 创建管理员账号 →
|
|
||||||
`http://127.0.0.1:4000/` 就是 Web 管理端。
|
|
||||||
|
|
||||||
常用脚本（都在安装目录里）：
|
|
||||||
|
|
||||||
```cmd
|
|
||||||
start.cmd :: 启动并等待就绪（已在运行则直接返回）
|
|
||||||
stop.cmd :: 按 PID 精确停止
|
|
||||||
restart.cmd :: 重启
|
|
||||||
status.cmd :: 查看状态与 HTTP 探针结果
|
|
||||||
```
|
|
||||||
|
|
||||||
机房主机这种无人值守的机器，建议以**管理员身份**跑一次 `install-service.cmd`，
|
|
||||||
把服务注册成开机启动的计划任务（比注册表 Run 更稳）：
|
|
||||||
|
|
||||||
```cmd
|
|
||||||
install-service.cmd :: schtasks /Create /SC ONSTART /RL HIGHEST
|
|
||||||
uninstall-service.cmd :: 删除计划任务
|
|
||||||
```
|
|
||||||
|
|
||||||
安装目录结构与配置见[生产部署指南](../management/production.md)；
|
|
||||||
安装程序里的默认管理员口令**第一次登录后必须改掉**。
|
|
||||||
|
|
||||||
## Linux 一键安装
|
|
||||||
|
|
||||||
从 Release 下载 `classhelper-server-linux-x64-<版本>.tar.gz`（以及旁边的 `.sha256`），连同
|
|
||||||
`install.sh` 一起拷到服务器：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
scp releases/server/<版本>/linux-x64/classhelper-server-linux-x64-*.tar.gz \
|
|
||||||
install.sh verify-linux.sh root@<主机>:/tmp/
|
|
||||||
|
|
||||||
ssh root@<主机> 'bash /tmp/install.sh --check' # 先体检，不改任何东西
|
|
||||||
ssh root@<主机> "printf '%s\n' '<管理员密码>' | bash /tmp/install.sh --yes --admin-password-stdin \
|
|
||||||
--package /tmp/classhelper-server-linux-x64-*.tar.gz"
|
|
||||||
```
|
|
||||||
|
|
||||||
安装器会装好内置 Node、把程序放到 `/opt/classhelper`、写好 systemd 单元、
|
|
||||||
把 `classhelper` 运维命令软链到 `/usr/local/bin/`。之后：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
classhelper status # 服务状态
|
|
||||||
classhelper doctor # 一整套自检（配置软链、权限、依赖完整性…）
|
|
||||||
classhelper backup # 立即备份
|
|
||||||
classhelper upgrade # 升级到最新 Release（自动校验 sha256）
|
|
||||||
```
|
|
||||||
|
|
||||||
完整的目录布局、配置项、升级回滚、反向代理与故障排查见 [Linux 部署与运维](../management/linux-deploy.md)。
|
|
||||||
|
|
||||||
## Docker
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd deploy
|
|
||||||
cp .env.example .env # 至少改 JWT_SECRET
|
|
||||||
docker compose up -d # 默认 SQLite 单容器，数据卷挂在本机
|
|
||||||
```
|
|
||||||
|
|
||||||
要 MySQL 就用 `docker-compose.yml`（带一个 MySQL 服务），只想要单容器 SQLite 用
|
|
||||||
`docker-compose.sqlite.yml`。细节见[生产部署指南](../management/production.md)。
|
|
||||||
|
|
||||||
## 从源码跑（开发模式）
|
|
||||||
|
|
||||||
想改代码或只想先看看，用这条路。需要 **Node ≥ 20.19** 与 **pnpm 11**。
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm install
|
|
||||||
cp packages/server/.env.example packages/server/.env # 至少改 JWT_SECRET
|
|
||||||
pnpm db:generate
|
|
||||||
pnpm --filter @classhelper/server db:deploy # 应用数据库迁移
|
|
||||||
pnpm build:shared # 必须先构建 shared，否则后面会 ERR_MODULE_NOT_FOUND
|
|
||||||
pnpm db:seed # 写演示数据（会清空业务表）
|
|
||||||
pnpm dev # 后端 4000 + Web 端 5173 一起起
|
|
||||||
```
|
|
||||||
|
|
||||||
演示账号见 [README 的「默认账号与种子数据」](https://github.com/LoveChengke/classhelper#readme)；
|
|
||||||
**演示口令只用于本地开发，别带到真实环境**。
|
|
||||||
|
|
||||||
| 端口 | 用途 |
|
|
||||||
| ---- | -------------------------------------------------------- |
|
|
||||||
| 4000 | 后端 REST + Socket.IO + （构建后）Web 管理端静态托管 |
|
|
||||||
| 5173 | Web 管理端开发服务器（`/api`、`/socket.io` 代理到 4000） |
|
|
||||||
| 5174 | 桌面客户端渲染进程开发服务器 |
|
|
||||||
|
|
||||||
> 改动 `packages/shared` 之后必须 `pnpm build:shared`（或让它跑着 watch）——
|
|
||||||
> 三端都从它的 `dist` 导入。
|
|
||||||
|
|
||||||
## 装完之后
|
|
||||||
|
|
||||||
打开 `http://<服务器地址>:4000/`，用管理员账号登录。下一页：
|
|
||||||
[认识 Web 管理端](web-admin.md)。
|
|
||||||
@@ -1,71 +0,0 @@
|
|||||||
---
|
|
||||||
title: 建班级、排课表
|
|
||||||
description: 建第一个班级、配班级账号、加学生与老师、排课表——后面所有功能的前提。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 建班级、排课表
|
|
||||||
|
|
||||||
后面所有功能（发通知、布置作业、录成绩）都挂在**班级**上，所以先把班级建出来。
|
|
||||||
|
|
||||||
## 1. 建班级（仅管理员）
|
|
||||||
|
|
||||||
Web 管理端 → **班级管理** → 「新建班级」：
|
|
||||||
|
|
||||||
| 字段 | 说明 |
|
|
||||||
| -------- | ----------------------------------------------------------------------- |
|
|
||||||
| 班级名称 | 例如「高二(3)班」 |
|
|
||||||
| 年级 | 用于分组与统计 |
|
|
||||||
| 班主任 | 从教师账号里选，默认是自己；之后随时可在班级详情顶部「更换班主任」改 |
|
|
||||||
| 学期周数 | 默认 20，**上限 30**。课表的周次选择与周次范围都以它为准 |
|
|
||||||
| 班级码 | 保存时自动生成（字母数字 4–16 位，存大写），可以改成好记的，例如 `G203` |
|
|
||||||
| 班级密码 | 新建班级时的初始密码就是它 —— 学生在教室机器上要用这个登录 |
|
|
||||||
|
|
||||||
> **班级码 + 班级密码 = ClassHelper 班级端的登录凭据。** ClassHelper 班级端没有个人账号，一台教室机器用班级账号登录后，
|
|
||||||
> 那台机器上的「已读 / 完成」是**代全班**操作的。
|
|
||||||
>
|
|
||||||
> 学期周数只有管理员能改：它决定"现在是第几教学周"，乱改会让课表的周次过滤和上课时段判定错位。
|
|
||||||
|
|
||||||
## 2. 加学生（仅管理员）
|
|
||||||
|
|
||||||
**学生管理** → 「新建」或「导入名单」：
|
|
||||||
|
|
||||||
- **单个新建**：填姓名即可，登录名会自动生成。
|
|
||||||
- **导入名单**：下载模板（列是 `学号 / 姓名 / 班级 / 性别 / 家长手机号`，学生**不是账号**，没有密码列），填好上传。
|
|
||||||
用户名要匹配 `^[A-Za-z0-9_.-]{3,32}$`；重复用户名在 `append` 模式下跳过、`upsert` 模式下更新姓名。
|
|
||||||
用户名已经属于某个教师 / 管理员账号时，这一行会进错误列表，不会覆盖别人的账号。
|
|
||||||
|
|
||||||
学生的用途是：**成绩、未交名单、叫人、已读记录都按名单记录**。所以名单不全，这几项就不准。
|
|
||||||
|
|
||||||
## 3. 加科任老师
|
|
||||||
|
|
||||||
教师的**录入**只有管理员能做（**教师管理**页，支持单个录入与导入名单）。班级层面的**分配**在班级详情里：
|
|
||||||
在「班级详情 → 任课老师」里给某位老师配一门课，他就能看到这个班，并**只能改自己任教科目**的作业与成绩。
|
|
||||||
|
|
||||||
角色与可见范围见[班级、学生与教师](../app/classes.md)与[角色与权限](../dev/permissions.md)。
|
|
||||||
|
|
||||||
## 4. 排课表
|
|
||||||
|
|
||||||
**课表管理** → 选中班级 → 「新增课表」：
|
|
||||||
|
|
||||||
- **科目**下拉直接列出全校统一的 18 科目录（语文 / 数学 / 英语 / 政治 / 历史 / 物理 / 化学 / 地理 /
|
|
||||||
生物 / 信息技术 / 体育 / 美术 / 音乐 / 班会 / 早读 / 晚读 / 通用技术 / 听力）。
|
|
||||||
选中一个该班还没有的科目时，前端会**自动为该班建同名课程**，不用先去把科目的建一遍。
|
|
||||||
- 填星期、开始 / 结束时间、周次范围（第几周到第几周）、单双周（每周 / 单周 / 双周）。
|
|
||||||
- 一节课**必须同时有开始时间和结束时间** —— 「上课时段」的判定就是拿这两个时间比对的。
|
|
||||||
|
|
||||||
排完在**课表管理**里能看到周视图（7 列），客户端那边则多一个「今天」时间轴视图。
|
|
||||||
|
|
||||||
### 从 ClassIsland 导入更省事
|
|
||||||
|
|
||||||
如果教室里已经在用 ClassIsland，直接导入它的档案 JSON 就行：课表、节次时间、单双周都会一起进来，
|
|
||||||
不用排两遍。见[表格与课表导入](../app/imports.md)。
|
|
||||||
|
|
||||||
## 5. 确认「上课时段」判定是对的
|
|
||||||
|
|
||||||
ClassHelper有一整套「上课时段策略」：普通通知在上课时段只进队列、下课自动补弹，紧急通知与叫人则立刻弹。
|
|
||||||
这套判定完全基于课表，所以**课表排错，提醒就会在该弹的时候不弹**。
|
|
||||||
|
|
||||||
排完课之后建议立刻验一下：在**通知发布**页选这个班，随便发一条普通通知，
|
|
||||||
看客户端是不是在课间弹出来、上课时是不是安静地收着。规则详见[通知与提醒](../app/notifications.md)。
|
|
||||||
|
|
||||||
下一步：[装 ClassHelper 班级端](client.md)。
|
|
||||||
@@ -1,14 +0,0 @@
|
|||||||
- name: 快速上手
|
|
||||||
href: index.md
|
|
||||||
- name: 系统要求
|
|
||||||
href: requirements.md
|
|
||||||
- name: 安装服务端
|
|
||||||
href: server.md
|
|
||||||
- name: 认识 Web 管理端
|
|
||||||
href: web-admin.md
|
|
||||||
- name: 建班级、排课表
|
|
||||||
href: setup-class.md
|
|
||||||
- name: 装 ClassHelper 班级端
|
|
||||||
href: client.md
|
|
||||||
- name: 发布第一条内容
|
|
||||||
href: first-content.md
|
|
||||||
@@ -1,58 +0,0 @@
|
|||||||
---
|
|
||||||
title: 认识 Web 管理端
|
|
||||||
description: 登录 ClassHelper Web 管理端，认一认 12 个页面、新手引导与手机端布局。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 认识 Web 管理端
|
|
||||||
|
|
||||||
Web 管理端不用装：服务端起来之后，浏览器打开 `http://<服务器地址>:4000/` 就是它。
|
|
||||||
|
|
||||||
## 登录
|
|
||||||
|
|
||||||
用**教师 / 管理员账号**登录（用户名 + 密码）。学生没有个人账号，学生那一端走
|
|
||||||
[班级码 + 班级密码](client.md)，见[班级、学生与教师](../app/classes.md)。
|
|
||||||
|
|
||||||
- 新装的服务端只有安装时创建的那一个管理员账号。**第一次登录后请立刻在顶栏头像菜单 → 修改密码里改掉它。**
|
|
||||||
- 登录页**不含任何演示内容**（没有"点击填充示例账号"之类的按钮），也不会提示种子口令。
|
|
||||||
- 连不上服务器时页面会直接失败，不会静默重试 —— 先确认服务端在跑、端口对、没走代理。
|
|
||||||
|
|
||||||
## 界面
|
|
||||||
|
|
||||||
布局沿用 1Panel 那一套：左边固定深色侧边栏，右边浅灰底 + 白色圆角卡片。
|
|
||||||
|
|
||||||
| 页面 | 干什么 | 谁能进 |
|
|
||||||
| ---------- | ---------------------------------------------- | ---------------------- |
|
|
||||||
| 仪表盘 | 全校 / 本班的汇总数字与最近动态 | 所有登录用户 |
|
|
||||||
| 课表管理 | 排课、导入 ClassIsland 课表、节次时间 | 管理员、本班班主任 |
|
|
||||||
| 作业发布 | 发作业、按天查看、看未交名单 | 教师、管理员、班级账号 |
|
|
||||||
| 通知发布 | 发通知、发叫人 | 教师、管理员 |
|
|
||||||
| 成绩录入 | 单条 / 批量录成绩、导入表格、看统计 | 管理员、本班班主任 |
|
|
||||||
| 客户端管理 | 看设备状态、下发远控与更新 | 管理员、教师 |
|
|
||||||
| 班级管理 | 建班级、换班主任、改班级账号 | **仅管理员** |
|
|
||||||
| 学生管理 | 学生名单增删、导入 | **仅管理员** |
|
|
||||||
| 教师管理 | 教师账号增删改、导入名单、重置密码 | **仅管理员** |
|
|
||||||
| 数据库管理 | 备份 / 恢复、导出导入、一键切换 SQLite ⇄ MySQL | **仅管理员** |
|
|
||||||
| 检查更新 | 顶栏头像菜单里，查 GitHub 上有没有新版本 | 所有登录用户 |
|
|
||||||
|
|
||||||
> **前端隐藏 ≠ 权限**。上面这张表只是"入口藏不藏"，每一条写入请求服务端都会再判一次
|
|
||||||
> （见[角色与权限](../dev/permissions.md)）。直接输网址绕过菜单，一样会被挡回仪表盘。
|
|
||||||
|
|
||||||
## 第一次登录的引导
|
|
||||||
|
|
||||||
首次登录进入主布局后会自动弹一次聚焦式引导，依次指出：侧边菜单 → 实时通道状态 → 账号菜单 → 完成。
|
|
||||||
走完或跳过（右上角 × 或 Esc）都记作"已看过"，之后不再自动弹。
|
|
||||||
|
|
||||||
想重看：**右上角头像菜单 →「使用引导」**。
|
|
||||||
|
|
||||||
## 手机 / 平板
|
|
||||||
|
|
||||||
| 屏幕宽度 | 布局 |
|
|
||||||
| --------- | ------------------------------------------------------ |
|
|
||||||
| > 992px | 常驻 210px 深色侧边栏 + 顶栏显示连接状态与实时事件计数 |
|
|
||||||
| 769–992px | 保留侧边栏，内容区内边距压缩 |
|
|
||||||
| ≤ 768px | 侧边栏收进抽屉，顶栏汉堡按钮唤出；表格在卡片内横向滚动 |
|
|
||||||
|
|
||||||
手机上（与电脑同一局域网）用 `http://<主机IP>:4000` 打开，可以「添加到主屏幕」当 App 用（PWA）。
|
|
||||||
做成 HTTPS 之后 PWA 才能完全离线化，见[生产部署指南](../management/production.md)。
|
|
||||||
|
|
||||||
下一步：[建班级、排课表](setup-class.md)。
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 53 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 69 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 53 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 43 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 46 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 2.5 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 24 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 46 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 31 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 76 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 106 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 109 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 120 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 88 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 105 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 141 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 141 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 73 KiB |
@@ -1,69 +0,0 @@
|
|||||||
---
|
|
||||||
title: 首页
|
|
||||||
description: ClassHelper（Class Helper）的官方文档：安装部署、功能说明、运维手册与开发参考。
|
|
||||||
---
|
|
||||||
|
|
||||||
# ClassHelper文档
|
|
||||||
|
|
||||||
ClassHelper（Class Helper）是给中小学班级用的一套信息管理系统。**一份代码，三个交付物**：
|
|
||||||
装在服务器上的后端、给老师用的 Web 管理端、装在教室机器的桌面客户端（ClassHelper 班级端 / 教室大屏）。
|
|
||||||
|
|
||||||
<p class="ch-tagline">
|
|
||||||
老师发一条通知，教室那台机器上的客户端和灵动岛会实时显示；学生打开客户端就能看到当天的课表和作业。
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<div class="ch-cards">
|
|
||||||
<a class="ch-card" href="get-started/index.md">
|
|
||||||
<span class="ch-card-title">第一次装</span>
|
|
||||||
<span class="ch-card-desc">从零把服务端、管理端、ClassHelper 班级端跑起来，大约半小时。</span>
|
|
||||||
</a>
|
|
||||||
<a class="ch-card" href="app/index.md">
|
|
||||||
<span class="ch-card-title">已经在用了</span>
|
|
||||||
<span class="ch-card-desc">课表、作业、通知、叫人、成绩、灵动岛，每一项具体怎么用。</span>
|
|
||||||
</a>
|
|
||||||
<a class="ch-card" href="management/index.md">
|
|
||||||
<span class="ch-card-title">负责运维</span>
|
|
||||||
<span class="ch-card-desc">部署形态怎么选、备份与恢复、换数据库、升级与回滚。</span>
|
|
||||||
</a>
|
|
||||||
<a class="ch-card" href="dev/index.md">
|
|
||||||
<span class="ch-card-title">要改代码</span>
|
|
||||||
<span class="ch-card-desc">架构、接口、数据模型、动效层，以及版本迭代与发布流程。</span>
|
|
||||||
</a>
|
|
||||||
</div>
|
|
||||||
|
|
||||||
## 它长什么样
|
|
||||||
|
|
||||||
<div class="ch-shots">
|
|
||||||
<img src="images/client-schedule.png" alt="桌面客户端 · 课表「今天」时间轴" />
|
|
||||||
<img src="images/island-5-clicked.png" alt="灵动岛 · 点开通知后的详情卡" />
|
|
||||||
<img src="images/mobile-notifications.jpg" alt="Web 管理端 · 手机上的抽屉导航与通知发布页" />
|
|
||||||
</div>
|
|
||||||
|
|
||||||
> 这些图都是脚本把程序真的跑起来截的，不是示意图。采集方式见 [验收与测试](dev/testing.md)。
|
|
||||||
|
|
||||||
## 目录
|
|
||||||
|
|
||||||
| 章节 | 里面有什么 | 谁看 |
|
|
||||||
| -------------------------------- | -------------------------------------------------------- | -------------------- |
|
|
||||||
| [快速上手](get-started/index.md) | 系统要求、安装、第一次配置、发布第一条内容 | 第一次部署的人 |
|
|
||||||
| [应用帮助](app/index.md) | 逐个功能怎么用，以及行为上的约定（什么时段弹、谁看得见） | 老师、班主任、管理员 |
|
|
||||||
| [管理运维](management/index.md) | 部署形态、Linux 运维命令、备份、换库、升级 | 管服务器的人 |
|
|
||||||
| [开发文档](dev/index.md) | 架构、REST API、实时事件、数据模型、权限、发布流程 | 改代码的人 |
|
|
||||||
| [常见问题](faq.md) | 装不上、连不上、改了不生效…… | 所有人 |
|
|
||||||
|
|
||||||
## 这套系统的三件事
|
|
||||||
|
|
||||||
**一、老师发，教室弹。** Web 端发布的内容通过 Socket.IO 按班级房间广播，客户端与灵动岛实时更新。
|
|
||||||
|
|
||||||
**二、上课时段不打扰。** 「上课时段」由课表实时判定，普通通知只进队列、下课自动补弹，
|
|
||||||
紧急通知和叫人则立刻弹出来 —— 服务端强制拦截，绕开界面直接调接口一样会被拦。
|
|
||||||
|
|
||||||
**三、离线可用。** 客户端先写 IndexedDB，断网时回退缓存并在顶部提示；
|
|
||||||
恢复连接后自动重新拉取，教室网络抖一下不会让大屏变白。
|
|
||||||
|
|
||||||
## 关于本文档
|
|
||||||
|
|
||||||
- 文档站的源码就在仓库里（`docs/`），用 [docfx](https://github.com/dotnet/docfx) 生成，发布在 GitHub Pages 上。
|
|
||||||
每页右下角有「在 GitHub 上编辑这一页」，发现写错或写漏可以直接改。
|
|
||||||
- 版本号取自仓库根 `package.json`，显示在顶栏，与 [Releases](https://github.com/LoveChengke/classhelper/releases) 对齐。
|
|
||||||
- 想在自己机器上预览：`pnpm docs:build --serve`。
|
|
||||||
@@ -1,78 +0,0 @@
|
|||||||
---
|
|
||||||
title: 数据库管理
|
|
||||||
description: 备份与恢复、导出导入、定时备份，以及 Web 管理端里的「数据库管理」模块。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 数据库管理
|
|
||||||
|
|
||||||
Web 管理端有一个「数据库管理」页（`/database`，**仅管理员可见**，后端同样 `requireRole('ADMIN')`），
|
|
||||||
把过去要手工做的数据库运维都收进了界面。
|
|
||||||
|
|
||||||
## 它能做什么
|
|
||||||
|
|
||||||
| 能力 | 说明 |
|
|
||||||
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
||||||
| 连接状态检测 | 当前类型（SQLite / MySQL）、连通性与延迟、引擎版本、数据体积、23 张表的行数、连接串（MySQL 密码脱敏） |
|
|
||||||
| 连接测试 | 对任意目标库试连（切换前的第一步） |
|
|
||||||
| **一键切换** | SQLite ⇄ MySQL：自动「备份当前库 → 改写 schema provider → 生成客户端 / 建表 → 子进程迁移全部数据 → 改写 `.env`」，异步任务带步骤进度，**失败自动回滚** |
|
|
||||||
| 备份 / 恢复 | gzip JSON 快照存在 `<数据目录>/backups/`；手动备份 / 从备份恢复（整库覆盖）/ 删除 |
|
|
||||||
| 定时备份 | enabled + 间隔小时数 + 保留份数，配置存在 `data/database-settings.json`；服务端每 10 分钟检查一次到点任务（**进程不运行不补跑**） |
|
|
||||||
| 快捷导入导出 | 下载快照 JSON（跨库通用）/ 下载数据库文件（仅 SQLite）/ 导入快照（整库覆盖，base64 上传） |
|
|
||||||
|
|
||||||
## 关键设计：只有一种快照格式
|
|
||||||
|
|
||||||
**备份、导入导出、跨库迁移共用同一种「JSON 快照」**：
|
|
||||||
|
|
||||||
- 23 张表按**拓扑序**导出；
|
|
||||||
- 恢复时临时**关闭外键检查** —— 因为 `User.classId → Class` 与 `Class.teacherId → User`
|
|
||||||
是**互相引用**的，任何排序都会被其中一侧卡死；
|
|
||||||
- 分批 `createMany` 写入。
|
|
||||||
|
|
||||||
因此**任意一份备份都能恢复回任意一种受支持的数据库**（SQLite 备份可以恢复进 MySQL，反之亦然）。
|
|
||||||
|
|
||||||
MySQL 的连接测试 / 建表 / 写入依赖随包内置的 `@prisma/adapter-mariadb`，不需要额外安装。
|
|
||||||
|
|
||||||
## 三条边界
|
|
||||||
|
|
||||||
1. **主库只支持 SQLite 与 MySQL**。Redis 这类内存键值库 Prisma 不支持建表 / 迁移，
|
|
||||||
接口层直接 422 拒绝；PostgreSQL 暂未纳入。
|
|
||||||
2. **切换完成后必须重启服务端**（安装版跑 `restart.cmd`，开发模式重跑 `pnpm dev:server`）才会连上新库。
|
|
||||||
切换失败会自动回滚 `schema.prisma`，`.env` 只在**数据全部迁移成功后**才改写。
|
|
||||||
3. **目标库必须为空**（有表就拒绝）。
|
|
||||||
|
|
||||||
> 安装包体积因此从约 34MB 涨到约 62MB：切换需要随包带上 prisma CLI 与 TypeScript 编译器
|
|
||||||
> （Prisma 7 的生成器产出 `.ts` 源码，切换后要在目标机上编译进 `dist`）。
|
|
||||||
|
|
||||||
## 命令行 / SSH 场景的备份
|
|
||||||
|
|
||||||
Web 界面适合日常；服务器上更适合用命令。Linux 安装形态有一套现成的：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo classhelper backup # 备份配置 + 数据库
|
|
||||||
sudo classhelper backup --note "升级前" --keep 7
|
|
||||||
sudo classhelper backup list
|
|
||||||
sudo classhelper backup restore 20261005-033000 # 用某个备份覆盖当前配置与数据（会先停服务）
|
|
||||||
sudo classhelper backup schedule daily # 每天 03:30 自动备份（systemd timer，保留 7 份）
|
|
||||||
sudo classhelper backup schedule off
|
|
||||||
```
|
|
||||||
|
|
||||||
备份落在 `/var/backups/classhelper/<时间戳>[-说明]/`：`config.env` + `classhelper.db` + `meta.json`，
|
|
||||||
目录权限 700、文件 600。
|
|
||||||
|
|
||||||
- SQLite 用 `VACUUM INTO` 做**一致性快照** —— 服务在跑也安全，比直接 `cp` 可靠得多；
|
|
||||||
- MySQL 用 `mysqldump --single-transaction`，密码经环境变量传给子进程，**不进 argv**；
|
|
||||||
- `restore` 前会先自动备份现状；恢复的对象是**配置与数据**，不是程序。
|
|
||||||
|
|
||||||
## 其它形态怎么备份
|
|
||||||
|
|
||||||
| 形态 | 备份 | 恢复 |
|
|
||||||
| ----------------- | ------------------------------------------------------ | ---------------------------- |
|
|
||||||
| Windows 安装包 | 停服务后复制 `data\` 目录（里面有 `classhelper.db`） | 替换后启动 |
|
|
||||||
| Linux | `classhelper backup`（见上） | `classhelper backup restore` |
|
|
||||||
| Docker | 备份挂载出来的数据卷 | 还原数据卷 |
|
|
||||||
| MySQL（任意形态） | `mysqldump -u classhelper -p classhelper > backup.sql` | `mysql … < backup.sql` |
|
|
||||||
|
|
||||||
**建议**：每日自动备份 + 保留 7 份，并且**定期真的恢复一次**验证备份可用。
|
|
||||||
|
|
||||||
> 变更 `JWT_SECRET` 会让所有用户重新登录，无必要时不要换。
|
|
||||||
> Linux 上换用 `sudo classhelper key rotate`。
|
|
||||||
@@ -1,76 +0,0 @@
|
|||||||
---
|
|
||||||
title: 管理运维
|
|
||||||
description: 部署形态怎么选、备份与恢复、换数据库、升级与回滚，以及上线前要逐项确认的清单。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 管理运维
|
|
||||||
|
|
||||||
这一章写给管服务器的人。如果你只是要用它，看[应用帮助](../app/index.md)就够了。
|
|
||||||
|
|
||||||
## 先选部署形态
|
|
||||||
|
|
||||||
| 形态 | 适合 | 产物 | 详细 |
|
|
||||||
| ------------------------ | ---------------------------------------- | ----------------------------------- | ----------------------------------- |
|
|
||||||
| **Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统） | NSIS 安装程序，内置 Node 运行时 | [生产部署指南](production.md) |
|
|
||||||
| **Linux 原生 + systemd** | 学校已有 Linux 服务器 | 一键安装器 + `classhelper` 运维命令 | [Linux 部署与运维](linux-deploy.md) |
|
|
||||||
| **Docker** | 云服务器、跟别的服务共用一台机器 | `deploy/docker-compose*.yml` | [生产部署指南](production.md) |
|
|
||||||
| **手动部署** | 已有 Node 环境、需要自定义 | 仓库源码（`pnpm build` 后直接跑） | [生产部署指南](production.md) |
|
|
||||||
|
|
||||||
一句话的取舍：
|
|
||||||
|
|
||||||
- **只有一台 Windows 机器** → 安装包形态，装完就能用，卸载也不留东西。
|
|
||||||
- **有 Linux 服务器** → 一键安装器，之后所有维护都在 `classhelper` 这一条命令里。
|
|
||||||
- **要对外提供服务** → Docker 或 Linux + Nginx 反代 + HTTPS（公网部署**必须**有 TLS）。
|
|
||||||
|
|
||||||
## 数据库：默认 SQLite，可以换 MySQL
|
|
||||||
|
|
||||||
默认用内嵌的 SQLite，**单校规模完全够用**，而且备份就是复制一个文件。
|
|
||||||
多校区 / 高并发 / 需要多实例再换 MySQL：
|
|
||||||
|
|
||||||
- 换法见[切换到 MySQL](mysql.md)（Web 端一键切换 / 命令行手工切换两条路）；
|
|
||||||
- 备份、导出导入与跨库迁移共用同一种 JSON 快照格式，**任意备份能恢复回任意一种受支持的库**；
|
|
||||||
- 见[数据库管理](database.md)。
|
|
||||||
|
|
||||||
> 主库**只支持 SQLite 与 MySQL**。Redis 是内存键值库，Prisma 不支持它建表 / 迁移，接口层直接拒绝。
|
|
||||||
|
|
||||||
## 升级
|
|
||||||
|
|
||||||
不同形态的升级方式不一样，共同点是：**升级数据不会丢，但升级前一定先备份**。
|
|
||||||
|
|
||||||
| 形态 | 升级方式 |
|
|
||||||
| ----------- | -------------------------------------------------------------- |
|
|
||||||
| Windows | 停服务 → 备份 `data` → 跑新版本安装程序（覆盖安装保留 `.env`） |
|
|
||||||
| Linux | `sudo classhelper upgrade`（自动下载、校验、快照、失败回滚） |
|
|
||||||
| Docker | `docker compose pull && docker compose up -d` |
|
|
||||||
| 手动 / 源码 | 替换程序目录，启动时自动补跑数据库迁移 |
|
|
||||||
|
|
||||||
完整流程、回滚与注意事项见[更新与升级](upgrade.md)。
|
|
||||||
|
|
||||||
## 上线前逐项确认
|
|
||||||
|
|
||||||
- [ ] 改掉 `admin` 与教师账号的默认密码；
|
|
||||||
- [ ] `JWT_SECRET` 是随机值（≥ 48 字节）并妥善保管 —— **换它会让所有人重新登录**；
|
|
||||||
- [ ] 公网访问走 HTTPS 反向代理（`deploy/nginx.conf` 可直接用）；
|
|
||||||
- [ ] `CORS_ORIGIN` 收敛到具体域名，不要留 `*`；
|
|
||||||
- [ ] `TRUST_PROXY=1` 并确认限流按真实 IP 生效（`/api` 响应头有 `RateLimit`）；
|
|
||||||
- [ ] 反向代理**放行 `/socket.io/` 的 WebSocket 升级**（否则实时推送静默失效）；
|
|
||||||
- [ ] 数据库账号用最小权限，只授权业务库；
|
|
||||||
- [ ] 配好定时备份，并且**验证过能恢复**；
|
|
||||||
- [ ] 关注 `/readyz` 与日志里的 5xx。
|
|
||||||
|
|
||||||
## 监控与日志
|
|
||||||
|
|
||||||
| 端点 | 用途 |
|
|
||||||
| ------------- | ---------------------------------------- |
|
|
||||||
| `/healthz` | 存活探针：进程活着即 200 |
|
|
||||||
| `/readyz` | 就绪探针：数据库可连才 200，否则 503 |
|
|
||||||
| `/api/health` | 详情：环境、数据库、已挂载模块、运行时长 |
|
|
||||||
|
|
||||||
日志输出到 stdout/stderr；安装包形态由启停脚本重定向到 `logs/server.log`（UTF-8）。
|
|
||||||
访问日志含方法、路径、状态码与耗时，5xx 记 error、4xx 记 warn。
|
|
||||||
|
|
||||||
## 故障排查
|
|
||||||
|
|
||||||
常见现象与排查方向列在[生产部署指南](production.md)的最后一节，
|
|
||||||
以及[常见问题](../faq.md)。Linux 特有的问题（`systemctl` 启动即退出、`EACCES`、
|
|
||||||
SQLite `database is locked`）在 [Linux 部署与运维](linux-deploy.md) 的故障排查一节。
|
|
||||||
@@ -1,560 +0,0 @@
|
|||||||
# Linux 部署与运维指南
|
|
||||||
|
|
||||||
本文覆盖服务端在 Linux 上的**一键安装**与日常运维（`classhelper` 命令）。
|
|
||||||
适用：Ubuntu 20.04+ / Debian 11+ / CentOS 7+ / Rocky Linux / AlmaLinux 8+（自动识别 apt / yum / dnf）。
|
|
||||||
|
|
||||||
不想看长文的话，最短路径就是这**一行**（在服务器上执行）：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -fsSL -o /tmp/classhelper-install.sh https://raw.githubusercontent.com/LoveChengke/ClassHelper/master/deploy/install.sh && sudo bash /tmp/classhelper-install.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
它自己会把整套流程走完：识别发行版 → 补依赖 → 建系统用户 → **从 GitHub Release 取最新版服务端包
|
|
||||||
并校验发布页上的 `.sha256`** → 下载内置 Node 运行时 → 建库建号 → 装成 systemd 服务。装完直接：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo classhelper status
|
|
||||||
```
|
|
||||||
|
|
||||||
参数接在最后即可，例如先只体检（不需要 root、不改动系统）：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -fsSL -o /tmp/classhelper-install.sh https://raw.githubusercontent.com/LoveChengke/ClassHelper/master/deploy/install.sh && bash /tmp/classhelper-install.sh --check
|
|
||||||
```
|
|
||||||
|
|
||||||
> **别写成 `bash -c "$(curl …)" --check`**：`bash -c '代码' 第一个参数` 里那个参数会变成 `$0`，
|
|
||||||
> 不是 `$1` —— 脚本收不到它（想体检却会走进交互式安装）。
|
|
||||||
> 先落盘再执行没这个问题，也不会因为下载中断而执行到半个脚本。
|
|
||||||
|
|
||||||
以下是"已有安装包 / 内网离线"的用法：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo bash install.sh --package /path/to/classhelper-server-linux-x64-1.1.2.tar.gz
|
|
||||||
sudo classhelper status
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 三种形态怎么选
|
|
||||||
|
|
||||||
| 形态 | 适合 | 命令 | 说明 |
|
|
||||||
| --- | --- | --- | --- |
|
|
||||||
| **直接安装（native）** | 有一台 Linux 服务器/Mini 主机，单机跑 | `install.sh` 选 1 | systemd 管理，自带 Node 运行时，SQLite 或 MySQL |
|
|
||||||
| **直接安装 + MySQL** | 多终端共享数据、已有 MySQL | `install.sh` 选 2 | 连接串写在配置里；库要先建好 |
|
|
||||||
| **Docker** | 机器上已有 Docker、想与其他服务隔离 | `install.sh` 选 3 | 用安装包里随带的 Dockerfile 构建镜像 + compose 起容器 |
|
|
||||||
|
|
||||||
> 只想先看看这台机器能不能装：`bash install.sh --check`（**不需要 root**，不改动任何东西）。
|
|
||||||
> Windows 机器用服务端安装包（`pnpm dist:server` 的产物），不需要本文。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 安装包从哪来
|
|
||||||
|
|
||||||
Linux 安装包命名固定为：
|
|
||||||
|
|
||||||
```
|
|
||||||
classhelper-server-linux-x64-<版本>.tar.gz ← install.sh / classhelper upgrade 都认这个名字
|
|
||||||
classhelper-server-linux-x64-<版本>.tar.gz.sha256 ← 旁边那份校验值
|
|
||||||
```
|
|
||||||
|
|
||||||
它发布在 [GitHub Releases](https://github.com/LoveChengke/ClassHelper/releases) 上。
|
|
||||||
|
|
||||||
**为什么 Linux 包要单独出一个**：`@libsql/linux-x64-gnu`、`@prisma/adapter-libsql` 这些依赖是平台相关的，
|
|
||||||
Windows 开发机上 `npm install` 出来的 `node_modules` 拷到 Linux 跑不起来，因此 Linux 包必须在 Linux 上构建。
|
|
||||||
仓库里的 [`.github/workflows/release-linux-server.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/release-linux-server.yml)
|
|
||||||
就是干这个的（拿 ubuntu runner 跑 `pnpm dist:server:linux`，再把产物挂到对应 Release 上）：
|
|
||||||
|
|
||||||
1. 本地照惯例发 Windows 包的 Release（tag 形如 `v1.1.2`）；
|
|
||||||
2. GitHub → Actions → 「发布 Linux 服务端安装包」→ Run workflow → 填 tag → 运行；
|
|
||||||
3. 跑完 Release 里会多出 Linux 包与更新后的 `SHA256SUMS-<版本>.txt`。
|
|
||||||
|
|
||||||
内网离线分发也可以：在能上网的机器上 `pnpm dist:server:linux`，把 tar.gz 拷进去，
|
|
||||||
用 `install.sh --package /path/to/xxx.tar.gz --sha256 <哈希>` 安装。
|
|
||||||
|
|
||||||
### 没有 Linux 机器时（交叉构建）
|
|
||||||
|
|
||||||
`pnpm dist:server:linux` 在非 Linux 上也**能跑**：脚本会用 npm 的 `--os=linux --cpu=x64`
|
|
||||||
按目标平台解析可选依赖，所以 `@libsql/linux-x64-gnu` 这些"按平台分发"的包会被正确装进来。
|
|
||||||
适合本地快速打一个包去验证安装与运维流程。逐项核对过的结论：
|
|
||||||
|
|
||||||
| 项 | 结论 |
|
|
||||||
| --- | --- |
|
|
||||||
| SQLite 驱动 | ✅ 包内是 `@libsql/linux-x64-gnu` + `linux-x64-musl`，**没有任何 win32 残留** |
|
|
||||||
| 服务端本体 | ✅ Node + libsql + express + socket.io 都是纯 JS 或已就位的 Linux 原生包 |
|
|
||||||
| 运维命令 | ✅ `status` / `doctor` / `password` / `backup` / `upgrade` / `rollback` 都不依赖平台差异 |
|
|
||||||
| Web 端「一键切换数据库」 | ⚠ **可能失败**：这条链路要调 prisma CLI 的 schema engine，CLI 在运行期按平台扫 `@prisma/engines/schema-engine-debian-openssl-3.0.x` 这类路径，而交叉包里只有宿主平台的 `schema-engine-windows.exe` |
|
|
||||||
|
|
||||||
所以交叉包**能装、能跑、能验收**，只是那一个 Web 端功能存疑 —— 它会在包内写入 `.cross-built` 标记，
|
|
||||||
`classhelper doctor` 会据此提示你（不会静默）。**正式发布一律用 GitHub Actions 那条路。**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 开发机（Windows 也可以）
|
|
||||||
pnpm dist:server:linux
|
|
||||||
# → releases/server/<版本>/linux-x64/classhelper-server-linux-x64-<版本>.tar.gz（+ .sha256）
|
|
||||||
# 重跑很快：node scripts/dist-server.mjs --platform linux --reuse-deps（复用已装的 node_modules）
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 一键安装
|
|
||||||
|
|
||||||
### 3.1 交互式（推荐第一次用）
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo bash install.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
TUI 会依次问：形态 → 安装目录 → 端口 → 数据库 → 初始管理员密码 → 是否要 Nginx 配置 / 放行防火墙。
|
|
||||||
每一问都有默认值，直接回车即可。
|
|
||||||
|
|
||||||
### 3.2 非交互（自动化 / 批量部署）
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 全部默认：/opt/classhelper、4000 端口、SQLite、内置 Node
|
|
||||||
sudo bash install.sh --yes --package ./classhelper-server-linux-x64-1.1.2.tar.gz
|
|
||||||
|
|
||||||
# 指定目录与端口，从 stdin 传初始管理员密码（不进 argv / shell history）
|
|
||||||
printf '%s\n' 'MyStrongPass!2026' | sudo bash install.sh --yes \
|
|
||||||
--dir /srv/classhelper --port 8080 --admin-password-stdin \
|
|
||||||
--package ./classhelper-server-linux-x64-1.1.2.tar.gz
|
|
||||||
|
|
||||||
# MySQL 形态
|
|
||||||
sudo bash install.sh --yes --database mysql --mysql-host 10.0.0.5 --mysql-db classhelper \
|
|
||||||
--mysql-user classhelper --mysql-password-stdin \
|
|
||||||
--package ./classhelper-server-linux-x64-1.1.2.tar.gz <<< 'MySQL密码'
|
|
||||||
```
|
|
||||||
|
|
||||||
完整参数见 `bash install.sh --help`。要点：
|
|
||||||
|
|
||||||
| 参数 | 作用 |
|
|
||||||
| --- | --- |
|
|
||||||
| `--package <url｜file://路径>` | 安装包地址（默认从 GitHub Release 取最新版） |
|
|
||||||
| `--sha256 <哈希>` | 强制校验安装包哈希 |
|
|
||||||
| `--admin-password-stdin` | 从 stdin 读一行作为初始管理员密码 |
|
|
||||||
| `--node-source bundled｜system｜tarball` | 内置 Node / 系统 Node / 指定压缩包 |
|
|
||||||
| `--node-mirror <url>` | Node 下载镜像（默认 `https://npmmirror.com/mirrors/node`） |
|
|
||||||
| `--node-tarball <url｜路径>` | 内网离线时直接用本地 Node 包 |
|
|
||||||
| `--with-nginx` / `--open-firewall` | 顺带生成反代配置 / 放行端口 |
|
|
||||||
| `--yes` | 全默认、不再交互 |
|
|
||||||
| `--check` | 只体检（无需 root） |
|
|
||||||
| `--force` | 覆盖已有配置；在无 systemd 的机器上只铺文件不装服务 |
|
|
||||||
|
|
||||||
**幂等性**：重复执行就是覆盖安装。已有的 `config.env`（含 `JWT_SECRET`）与 `data/` 一律保留，
|
|
||||||
用户不会被踢下线；端口与数据库形态也沿用旧配置，不会被改回默认值。
|
|
||||||
|
|
||||||
### 3.3 安装器做了什么
|
|
||||||
|
|
||||||
1. 识别发行版与包管理器，补齐 `curl / tar / gzip / ca-certificates`（只装缺的）；
|
|
||||||
2. 创建系统用户与组 `classhelper`（`--system`，nologin）；
|
|
||||||
3. 建目录、收权限（见下一节）；
|
|
||||||
4. 下载安装包 → 校验 sha256 → 解压铺文件；
|
|
||||||
5. 下载 Node（默认走 npmmirror 镜像，从 `SHASUMS256.txt` 同时取版本号与哈希）；
|
|
||||||
6. 生成 `/etc/classhelper/config.env`（随机 `JWT_SECRET`，权限 600）；
|
|
||||||
7. 装 systemd 单元、`/usr/local/bin/classhelper`、`/etc/profile.d/classhelper.sh`、logrotate；
|
|
||||||
8. 启动服务并轮询 `/healthz`，通过后才算安装成功；
|
|
||||||
9. 全过程写 `/var/log/classhelper/install.log`。
|
|
||||||
|
|
||||||
### 3.4 Docker 形态
|
|
||||||
|
|
||||||
`install.sh` 选 3（或 `--mode docker`）：用安装包里随带的 `Dockerfile` 直接构建镜像
|
|
||||||
（包的 `node_modules` 已经是 linux 的真实目录，**构建时不需要联网装依赖**，几十秒出镜像），
|
|
||||||
然后写一份 `/etc/classhelper/compose.yml` 拉起容器。
|
|
||||||
|
|
||||||
```bash
|
|
||||||
classhelper status # 走 docker compose ps / logs
|
|
||||||
classhelper restart # 重建容器
|
|
||||||
classhelper password admin # 通过 docker exec 在容器里执行同一份 admin-cli
|
|
||||||
classhelper backup # 容器内做一致性快照再取出来
|
|
||||||
```
|
|
||||||
|
|
||||||
Docker 形态与直接安装的差异：
|
|
||||||
|
|
||||||
| | 直接安装 | Docker |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| 数据位置 | `<安装目录>/data` | Docker 卷 `classhelper-data` |
|
|
||||||
| 配置 | `/etc/classhelper/config.env`（systemd 注入） | 同一份文件（compose `env_file`） |
|
|
||||||
| 升级 / 回滚 | 替换程序文件后重启服务 | 同一套流程：替换构建上下文 → 重建镜像（`classhelper-server:local`）→ `compose up -d --force-recreate` |
|
|
||||||
| 恢复数据 | `classhelper backup restore <目录>` | 需手工 `docker cp` 回容器（命令里有提示） |
|
|
||||||
| `backup schedule` | 支持（systemd timer） | 用宿主机 cron 调 `classhelper backup --quiet` |
|
|
||||||
|
|
||||||
> Docker 形态的镜像用**稳定标签** `classhelper-server:local`（另打一个 `classhelper-server:<版本>` 便于追溯）。
|
|
||||||
> 版本号写在 compose 里的话，升级替换完程序文件后那个标签就过期了，`compose up` 会一直沿用旧镜像 ——
|
|
||||||
> 表现为"升级成功但行为没变"。`classhelper` 自己按 `VERSION` 决定要不要重建镜像。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 目录、权限与配置
|
|
||||||
|
|
||||||
```
|
|
||||||
/opt/classhelper/ 安装目录（--dir 可改）
|
|
||||||
├── server/ 后端程序（入口 server/dist/index.js）
|
|
||||||
│ ├── dist/ prisma/ 产物 + 迁移 SQL（首启动 AUTO_MIGRATE 自动执行）
|
|
||||||
│ ├── prisma.config.ts tsconfig.generate.json 数据库「一键切换」用
|
|
||||||
├── web/ Web 管理端（由后端托管）
|
|
||||||
├── node_modules/ 生产依赖（真实目录，非软链）
|
|
||||||
├── tools/admin-cli.mjs 离线改密 / 数据库快照工具
|
|
||||||
├── bin/classhelper 运维命令本体（/usr/local/bin/classhelper 软链到它）
|
|
||||||
├── runtime/node/ 内置 Node 运行时
|
|
||||||
├── systemd/ logrotate.d/ profile.d/ 模板（安装时拷到 /etc 下）
|
|
||||||
├── Dockerfile Docker 形态构建用
|
|
||||||
├── data/ 数据库 + Web 端自建快照（备份就是拷这里）
|
|
||||||
├── logs/ 预留
|
|
||||||
├── VERSION 当前版本
|
|
||||||
├── .installed.json 安装元数据（形态/版本/端口，classhelper 靠它决策）
|
|
||||||
└── .env → /etc/classhelper/config.env （软链，见下）
|
|
||||||
|
|
||||||
/etc/classhelper/ 目录 700，属主 classhelper
|
|
||||||
└── config.env 配置文件，**权限 600**，唯一真身
|
|
||||||
/var/log/classhelper/ 安装日志 install.log + 审计日志 audit.log
|
|
||||||
/var/backups/classhelper/ 备份 + 程序快照（回滚用）
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4.1 为什么安装目录里的 `.env` 是软链
|
|
||||||
|
|
||||||
Web 端「数据库管理 → 一键切换数据库」在运行中改写的是 **`<安装目录>/.env`**
|
|
||||||
（`packages/server/src/modules/database/database.service.ts`），而 systemd 是通过
|
|
||||||
`EnvironmentFile=/etc/classhelper/config.env` 注入环境变量的。dotenv 不覆盖已存在的环境变量 →
|
|
||||||
如果这两处不是同一份文件，**切换看起来成功、重启后又连回旧库**。
|
|
||||||
|
|
||||||
所以安装器把 `<安装目录>/.env` 做成指向 `config.env` 的软链：两种读法落到同一个真身。
|
|
||||||
`classhelper doctor` 会专门检查这条软链，别手工删掉。
|
|
||||||
|
|
||||||
### 4.2 配置项
|
|
||||||
|
|
||||||
配置就是一份 `KEY=VALUE` 的 env 文件，systemd / dotenv / `source` 三种读法都兼容
|
|
||||||
（含空白或 `#` 的值请加双引号）。最常见的几项：
|
|
||||||
|
|
||||||
| KEY | 默认 | 说明 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| `PORT` / `HOST` | `4000` / `0.0.0.0` | 监听端口与地址 |
|
|
||||||
| `DATABASE_PROVIDER` | `sqlite` | `sqlite` 或 `mysql` |
|
|
||||||
| `DATABASE_URL` | `file:../data/classhelper.db` | SQLite 相对 `<安装目录>/server` 解析；MySQL 是连接串 |
|
|
||||||
| `JWT_SECRET` | 随机 | 登录令牌签名密钥。**换掉＝所有用户重新登录**（`classhelper key rotate`） |
|
|
||||||
| `JWT_EXPIRES_IN` | `7d` | 令牌有效期 |
|
|
||||||
| `CORS_ORIGIN` | `*` | 走域名/反代时建议收敛成 `https://你的域名` |
|
|
||||||
| `TRUST_PROXY` | `1` | 前面有 Nginx 时保持 1，限流才按真实 IP 统计 |
|
|
||||||
| `AUTO_MIGRATE` | `true` | 空库首启动自动建表 + 建管理员 |
|
|
||||||
| `INITIAL_ADMIN_USERNAME` / `INITIAL_ADMIN_PASSWORD` | `admin` / `admin123` | **只在空库首次初始化时生效**，之后改密码用 `classhelper password` |
|
|
||||||
| `DEFAULT_CLASS_PASSWORD` / `DEFAULT_TEACHER_PASSWORD` | `123456` | 新建班级 / 重置教师时的初始密码 |
|
|
||||||
| `TERM_START_DATE` | 空 | 第 1 教学周的周一（`YYYY-MM-DD`），影响"当前周次" |
|
|
||||||
|
|
||||||
改配置的三种方式（都会先自动备份、改完问你是否重启）：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo classhelper config show # 敏感值打码查看
|
|
||||||
sudo classhelper config get PORT
|
|
||||||
sudo classhelper config set CORS_ORIGIN https://class.example.com # 敏感项会改成交互输入
|
|
||||||
sudo classhelper config edit # 用 $EDITOR 直接编辑
|
|
||||||
sudo classhelper port 8080 # 改端口的快捷方式
|
|
||||||
```
|
|
||||||
|
|
||||||
> 手工改也可以（`vim /etc/classhelper/config.env`），但记得改完 `classhelper restart`，
|
|
||||||
> 并确认权限仍是 600。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. `classhelper` 运维命令
|
|
||||||
|
|
||||||
安装后可直接使用（`/usr/local/bin/classhelper`）。除 `help` / `version` / `completion` 外都需要 root。
|
|
||||||
|
|
||||||
### 5.1 查看与诊断
|
|
||||||
|
|
||||||
```bash
|
|
||||||
classhelper status # 服务状态、版本、端口、数据库、各类路径
|
|
||||||
classhelper status --json # 同上，机器可读（接监控用）
|
|
||||||
classhelper doctor # 完整体检：权限 / Node / 服务单元 / 探针 / 数据库 / 磁盘 / 备份
|
|
||||||
classhelper logs -f # 实时日志（= journalctl -u classhelper -f）
|
|
||||||
classhelper logs -n 200 --since "1 hour ago"
|
|
||||||
classhelper logs --unit classhelper-backup # 看定时备份的日志
|
|
||||||
```
|
|
||||||
|
|
||||||
`doctor` 会把每一项标成 `✔` / `✘`，失败项后面直接跟修复建议，例如：
|
|
||||||
|
|
||||||
```
|
|
||||||
✘ 安装目录 .env 是指向配置真身的软链
|
|
||||||
✔ Node 运行时可用且 ≥20.19（v22.20.0）
|
|
||||||
✘ 最近 7 天内有备份（无）
|
|
||||||
建议依次处理：
|
|
||||||
· ln -sfn /etc/classhelper/config.env /opt/classhelper/.env（Web 端「一键切换数据库」依赖它）
|
|
||||||
· classhelper backup；长期可用 classhelper backup schedule daily
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5.2 改密码
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo classhelper password # 改 admin
|
|
||||||
sudo classhelper password teacher1 # 改指定教师
|
|
||||||
sudo classhelper password --list # 列出可登录账号与班级账号（含是否已设密码）
|
|
||||||
sudo classhelper password --class G101 # 改某个班的班级密码（ClassHelper 班级端登录用）
|
|
||||||
```
|
|
||||||
|
|
||||||
安全约定（照要求逐条落实）：
|
|
||||||
|
|
||||||
- 密码**交互输入、不回显**；不接受命令行传参，因此不会进 shell history、也不出现在 `ps` 里；
|
|
||||||
- 强度校验：≥8 位，小写/大写/数字/符号至少 3 类，不得与用户名相同，常见弱口令直接拒绝；
|
|
||||||
需二次确认，连续 3 次不合规即退出（密码不变）；
|
|
||||||
- 改前把**原密码哈希**备份到 `/var/backups/classhelper/password-<时间戳>.json`（权限 600），
|
|
||||||
写入失败或写入后复核不通过会**自动回滚**原哈希；
|
|
||||||
- 全过程写审计日志，**审计里只有"谁对谁做了什么、结果如何"，没有密码**；
|
|
||||||
- 自动化可以用管道传入（仍不进 history）：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
printf '%s\n%s\n' "$NEW_PW" "$NEW_PW" | sudo classhelper password admin
|
|
||||||
```
|
|
||||||
|
|
||||||
> 顺带说明：改密码不需要重启服务（登录时读库校验）；已登录的会话仍有效，
|
|
||||||
> 要让所有会话立刻失效用 `classhelper key rotate`。
|
|
||||||
|
|
||||||
### 5.3 备份与恢复
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo classhelper backup # 备份配置 + 数据库
|
|
||||||
sudo classhelper backup --note "升级前" --keep 7
|
|
||||||
sudo classhelper backup list
|
|
||||||
sudo classhelper backup restore 20261005-033000 # 用某个备份覆盖当前配置与数据（会先停服务）
|
|
||||||
sudo classhelper backup schedule daily # 每天 03:30 自动备份（systemd timer，保留 7 份）
|
|
||||||
sudo classhelper backup schedule off
|
|
||||||
```
|
|
||||||
|
|
||||||
- 备份落在 `/var/backups/classhelper/<时间戳>[-说明]/`：`config.env` + `classhelper.db` + `meta.json`，
|
|
||||||
目录 700、文件 600；
|
|
||||||
- SQLite 用 `VACUUM INTO` 做**一致性快照**（服务在跑也安全，比直接 `cp` 可靠）；
|
|
||||||
- MySQL 用 `mysqldump --single-transaction`（密码经 `MYSQL_PWD` 传给子进程，不进 argv）；
|
|
||||||
- `restore` 前会先自动备份现状，恢复对象是配置与数据（不是程序）；
|
|
||||||
- 程序文件快照（回滚用）在 `/var/backups/classhelper/rollback/`，是另一类东西，`backup list` 会分开列。
|
|
||||||
|
|
||||||
### 5.4 升级与回滚
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo classhelper upgrade --check # 只检查有没有新版本（查 GitHub Release）
|
|
||||||
sudo classhelper upgrade # 升到最新版
|
|
||||||
sudo classhelper upgrade --version 1.2.0 # 升到指定版本
|
|
||||||
sudo classhelper upgrade --url ./classhelper-server-linux-x64-1.0.1.tar.gz --sha256 <哈希> # 内网离线
|
|
||||||
sudo classhelper upgrade --url <包> --force # 强制重装同一版本
|
|
||||||
|
|
||||||
sudo classhelper rollback --list # 看有哪些程序快照
|
|
||||||
sudo classhelper rollback # 回滚到最近一份（会问一次确认）
|
|
||||||
```
|
|
||||||
|
|
||||||
`upgrade` 的完整链路（任一步失败都不改动程序文件）：
|
|
||||||
|
|
||||||
```
|
|
||||||
解析目标版本 → 下载 → 校验 sha256 → 备份数据与配置 → 快照当前程序文件 →
|
|
||||||
停服 → 替换程序文件（mv 原子替换，data/ 配置/ 运行时原地不动）→ 起服 → 轮询 /healthz
|
|
||||||
↘ 失败：自动用刚才的快照回滚并重新起服，再告诉你失败原因
|
|
||||||
```
|
|
||||||
|
|
||||||
两点必须知道：
|
|
||||||
|
|
||||||
1. **升级不会回滚数据库结构**。如果新版执行过迁移，回滚程序前要确认旧版还能读新库，
|
|
||||||
必要时用 `classhelper backup restore` 连数据一起回退；
|
|
||||||
2. 替换程序文件用的是"改名 + 就位"而不是删除重写 —— 升级时正在运行的就是 `bin/classhelper` 自己，
|
|
||||||
必须先改名再放新文件，运行中的进程继续读旧 inode，否则会读到半个脚本。
|
|
||||||
|
|
||||||
### 5.5 服务与配置
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo classhelper start | stop | restart | reload # reload 与 restart 同义（服务端不支持热重载）
|
|
||||||
sudo classhelper port # 看当前端口
|
|
||||||
sudo classhelper port 8080 # 改端口（顺带提示放行防火墙）
|
|
||||||
sudo classhelper config show [--reveal]
|
|
||||||
sudo classhelper config set KEY VALUE
|
|
||||||
sudo classhelper key rotate # 轮换 JWT_SECRET（所有用户需重新登录）
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5.6 其它
|
|
||||||
|
|
||||||
```bash
|
|
||||||
classhelper version
|
|
||||||
classhelper help
|
|
||||||
source <(classhelper completion bash) # 补全（安装时已装到 /usr/share/bash-completion）
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5.7 卸载
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo classhelper uninstall
|
|
||||||
```
|
|
||||||
|
|
||||||
会依次问：保留配置？保留数据？保留备份？默认全部保留 —— 数据与配置会被**搬到**
|
|
||||||
`/var/backups/classhelper/uninstall-<时间戳>/`，然后才删除程序目录，不会悄悄丢数据。
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo classhelper uninstall --yes # 不问，用默认（保留配置/数据/备份）
|
|
||||||
sudo classhelper uninstall --purge # 全删（含备份与数据），不可恢复
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. 环境变量文件
|
|
||||||
|
|
||||||
安装器会写 `/etc/profile.d/classhelper.sh`（内容见
|
|
||||||
[`deploy/profile.d/classhelper.sh`](https://github.com/LoveChengke/classhelper/blob/master/deploy/profile.d/classhelper.sh)）：
|
|
||||||
|
|
||||||
```sh
|
|
||||||
export CLASSHELPER_HOME=/opt/classhelper
|
|
||||||
export CLASSHELPER_CONFIG=/etc/classhelper/config.env
|
|
||||||
export CLASSHELPER_LOG_DIR=/var/log/classhelper
|
|
||||||
export CLASSHELPER_BACKUP_DIR=/var/backups/classhelper
|
|
||||||
export PATH=$PATH:$CLASSHELPER_HOME/bin
|
|
||||||
```
|
|
||||||
|
|
||||||
新登录的 shell 自动生效；当前会话要手工 `source /etc/profile.d/classhelper.sh`。
|
|
||||||
`classhelper` 命令本身装在 `/usr/local/bin`（软链），所以**不登录也照样能用**。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. 反向代理与 HTTPS（公网部署必做）
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo bash install.sh --with-nginx # 或者安装后手工：
|
|
||||||
sudo cp deploy/nginx.conf /etc/nginx/conf.d/classhelper.conf
|
|
||||||
```
|
|
||||||
|
|
||||||
要点：
|
|
||||||
|
|
||||||
- `client_max_body_size 12m`（表格导入最大 8MB，base64 后约 11MB）；
|
|
||||||
- Socket.IO 需要 `Upgrade` / `Connection` 头与较长的 `proxy_read_timeout`（模板里已配）；
|
|
||||||
- 配置里保持 `TRUST_PROXY=1`，并把 `CORS_ORIGIN` 收敛成你的域名；
|
|
||||||
- 证书用 certbot 或你自己的证书，装好后 `nginx -t && nginx -s reload`。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. 故障排查
|
|
||||||
|
|
||||||
| 现象 | 先查什么 |
|
|
||||||
| --- | --- |
|
|
||||||
| 服务起不来 | `classhelper doctor` → `classhelper logs -n 100`。常见：端口被占用、MySQL 连接串错、`data/` 权限 |
|
|
||||||
| 装完打不开页面 | `classhelper status` 看探针与监听地址；云服务器还要在**安全组**放行端口 |
|
|
||||||
| 页面能打开但是**空白** | 1.1.0 的服务端在 HTTP 直连访问时会下发 CSP `upgrade-insecure-requests`，浏览器把所有子资源改写成 https 加载而服务器没有 TLS，于是整页空白（HTML/接口都正常）。已修复的版本按请求协议条件下发；若暂不能升级，唯一正解是上 HTTPS 反代 |
|
|
||||||
| 改了配置没生效 | 是否重启过（`classhelper config set` 会问）；`EnvironmentFile` 的值优先于文件里的同项 |
|
|
||||||
| Web 端切库后还是连旧库 | `classhelper doctor` 看 `.env` 软链是否被破坏（`ln -sfn /etc/classhelper/config.env <安装目录>/.env`） |
|
|
||||||
| 升级卡住/失败 | 失败会自动回滚；看 `classhelper logs -n 100`，确认磁盘余量 ≥1GB |
|
|
||||||
| `classhelper` 命令找不到 | `ls -l /usr/local/bin/classhelper`；被删了就重装或 `ln -sfn <安装目录>/bin/classhelper /usr/local/bin/classhelper` |
|
|
||||||
| 忘记管理员密码 | `sudo classhelper password admin`（直连数据库，不需要登录） |
|
|
||||||
| ClassHelper 班级端连不上 | 客户端「服务器地址」填 `http://IP:端口` 或域名；确认没有多余路径与斜杠 |
|
|
||||||
| CentOS 7 装完立刻退出 | glibc < 2.28，见下面的"已知限制" |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. 已知限制
|
|
||||||
|
|
||||||
### CentOS 7 / glibc < 2.28
|
|
||||||
|
|
||||||
Node 官方的 linux-x64 二进制要求 **glibc ≥ 2.28**，而 CentOS 7 是 2.17 —— 直接装官方包会表现成
|
|
||||||
"装完服务立刻退出、日志里什么也没有"。安装器会自动检测 glibc，低于 2.28 时改用
|
|
||||||
[unofficial-builds](https://unofficial-builds.nodejs.org/) 的 **glibc-217** 构建（功能一致，只是编译基线更低）。
|
|
||||||
|
|
||||||
但即便这样，个别原生依赖仍可能不兼容，CentOS 7 支持属于**尽力而为**：
|
|
||||||
|
|
||||||
- CentOS 7 已于 2024-06 EOL，**新部署请用 Rocky Linux 9 / AlmaLinux 9 / Ubuntu 22.04+**；
|
|
||||||
- 若坚持用 CentOS 7，建议装完立刻跑一遍 `classhelper doctor` 与本文第 10 节的验收清单。
|
|
||||||
|
|
||||||
### 其它
|
|
||||||
|
|
||||||
- 直接安装形态要求 **systemd**（容器里没有 `/run/systemd/system` 时会明确拒绝；
|
|
||||||
容器场景请用 Docker 形态）。
|
|
||||||
- Docker 形态的数据恢复需要手工 `docker cp`（数据在容器卷里，宿主机上看不到那个文件）；
|
|
||||||
`classhelper backup restore` 会给出具体命令。
|
|
||||||
- `classhelper reload` 等价于 restart（服务端没有 SIGHUP 处理）。
|
|
||||||
- 升级包只发 x64；arm64 需要自行构建（`node scripts/dist-server.mjs --platform linux` 跑在 arm64 机器上）。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 10. 验收清单
|
|
||||||
|
|
||||||
下面这套在干净的 **Ubuntu 22.04** 与 **Rocky Linux 9** 上各跑一遍。
|
|
||||||
`deploy/verify-linux.sh` 会把第 3~8 步自动跑完并打印 `=== 结果：N/N 项通过 ===`。
|
|
||||||
|
|
||||||
### 10.0 准备
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 在开发机：做出 Linux 包（或在 Actions 里下载）
|
|
||||||
pnpm dist:server:linux
|
|
||||||
scp releases/server/*/linux-x64/classhelper-server-linux-x64-*.tar.gz root@<服务器>:/tmp/
|
|
||||||
scp deploy/install.sh deploy/verify-linux.sh root@<服务器>:/tmp/
|
|
||||||
```
|
|
||||||
|
|
||||||
### 10.1 体检（不需要 root）
|
|
||||||
|
|
||||||
```bash
|
|
||||||
bash /tmp/install.sh --check
|
|
||||||
```
|
|
||||||
|
|
||||||
期望：系统/包管理器/glibc/docker/端口/磁盘逐项列出，末尾「体检通过」。
|
|
||||||
端口被占用、缺 curl、没有 systemd 都会在这里被点出来。
|
|
||||||
|
|
||||||
### 10.2 安装
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo bash /tmp/install.sh --yes \
|
|
||||||
--package /tmp/classhelper-server-linux-x64-1.1.2.tar.gz \
|
|
||||||
--admin-password-stdin <<< 'Verify-Pass-2026!'
|
|
||||||
```
|
|
||||||
|
|
||||||
期望：末尾出现「安装完成」与「服务已就绪 ✅」，并打印管理端地址。
|
|
||||||
|
|
||||||
### 10.3 自动验收
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo bash /tmp/verify-linux.sh --admin-password-stdin <<< 'Verify-Pass-2026!'
|
|
||||||
```
|
|
||||||
|
|
||||||
覆盖项：
|
|
||||||
|
|
||||||
| 分组 | 检查内容 |
|
|
||||||
| --- | --- |
|
|
||||||
| 安装结果 | 程序文件、`VERSION`、`.installed.json`、`config.env` 600、配置目录 700、`.env` 软链、内置 Node、`/usr/local/bin/classhelper`、安装/审计日志、profile.d 生效 |
|
|
||||||
| 服务 | systemd 单元、active、enabled、`/healthz` 200、`status --json` 合法且 healthy |
|
|
||||||
| 体检 | `classhelper doctor` 无待处理项、`help` / `completion` 可用 |
|
|
||||||
| API | 用初始密码登录拿 token、带 token 读 `/api/classes` 与 `/api/auth/me` |
|
|
||||||
| 改密 | 改密成功 → 新密码可登录 → **旧密码被拒** → 原哈希已备份且 600 → 审计有记录且**不含密码明文** → 弱密码被拒 → stdin 结束不卡死 → `restore-hash` 把原密码回滚回来 |
|
|
||||||
| 备份 | 备份目录/文件/权限、SQLite 快照是合法库文件、`backup list` |
|
|
||||||
| 配置 | `config get/show`、敏感值打码、读写往返 |
|
|
||||||
| key rotate | 密钥确实变了且 ≥32 位、服务仍可用、**旧 token 变 401**、重新登录成功 |
|
|
||||||
|
|
||||||
追加升级/回滚链路（会真的替换一次程序文件）：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo bash /tmp/verify-linux.sh --full --package /tmp/classhelper-server-linux-x64-1.0.1.tar.gz \
|
|
||||||
--admin-password-stdin <<< 'Verify-Pass-2026!'
|
|
||||||
```
|
|
||||||
|
|
||||||
覆盖：升级成功 → 服务恢复 → 配置未被改动 → 产生程序快照 → **坏哈希被拒绝且服务不受影响** →
|
|
||||||
`rollback` 回到旧版且服务可用。
|
|
||||||
|
|
||||||
### 10.4 手工补验（自动化覆盖不到的）
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# ① 浏览器打开 http://<IP>:4000/ ，用 admin 登录，改一次密码再登录
|
|
||||||
# ② ClassHelper 班级端客户端填 http://<IP>:4000 用班级码 G101/123456 登录，收到一条老师发的通知
|
|
||||||
# ③ 重跑安装器（幂等性）：sudo bash /tmp/install.sh --yes --package <同一个包>
|
|
||||||
# 期望：配置与数据保留、JWT_SECRET 不变（已登录用户不被踢下线）
|
|
||||||
# ④ 卸载：sudo classhelper uninstall --yes
|
|
||||||
# 期望：服务停止、单元删除、/usr/local/bin/classhelper 消失、
|
|
||||||
# 数据与配置被搬到 /var/backups/classhelper/uninstall-*/
|
|
||||||
# ⑤ 重启机器后服务自动起来（systemctl is-enabled classhelper）
|
|
||||||
```
|
|
||||||
|
|
||||||
### 10.5 Rocky 9 的差异点
|
|
||||||
|
|
||||||
- 包管理器走 `dnf`，依赖包名与 apt 不同（`install.sh` 已按 `PKG` 分支处理）；
|
|
||||||
- 默认没有 `curl` 之外的工具时会被补装，注意首次安装需要能访问 dnf 源；
|
|
||||||
- 防火墙默认是 `firewalld`：用 `--open-firewall` 或手工
|
|
||||||
`firewall-cmd --add-port=4000/tcp --permanent && firewall-cmd --reload`；
|
|
||||||
- SELinux（Enforcing）：服务读写 `/opt/classhelper` 与 `/etc/classhelper` 一般不受影响，
|
|
||||||
若日志里出现 `Permission denied` 且路径正常，先 `ausearch -m avc -ts recent` 看是不是 SELinux，
|
|
||||||
可以用 `semanage fcontext` 加规则，或临时 `setenforce 0` 验证判断。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 11. 安全清单
|
|
||||||
|
|
||||||
- [ ] 改掉默认管理员密码：`classhelper password admin`（**公网部署第一件事**）
|
|
||||||
- [ ] 公网服务前面加 Nginx + HTTPS，`CORS_ORIGIN` 收敛到具体域名
|
|
||||||
- [ ] 定期备份：`classhelper backup schedule daily`，并确认备份能恢复（`backup restore` 演练一次）
|
|
||||||
- [ ] 配置与备份权限：`config.env` 600、`/etc/classhelper` 700、备份目录 700
|
|
||||||
- [ ] `classhelper doctor` 无待处理项；关注"最近 7 天内有备份"
|
|
||||||
- [ ] 审计日志（`/var/log/classhelper/audit.log`）随日志轮转保留，必要时接集中日志
|
|
||||||
- [ ] 只在需要时使用 `--purge`；卸载默认保留数据与备份
|
|
||||||
- [ ] 升级包一律校验 sha256（`upgrade` 内网分发时也要带 `--sha256`）
|
|
||||||
@@ -1,12 +0,0 @@
|
|||||||
- name: 管理运维
|
|
||||||
href: index.md
|
|
||||||
- name: 生产部署指南
|
|
||||||
href: production.md
|
|
||||||
- name: Linux 部署与运维
|
|
||||||
href: linux-deploy.md
|
|
||||||
- name: 数据库管理
|
|
||||||
href: database.md
|
|
||||||
- name: 切换到 MySQL
|
|
||||||
href: mysql.md
|
|
||||||
- name: 更新与升级
|
|
||||||
href: upgrade.md
|
|
||||||
@@ -1,131 +0,0 @@
|
|||||||
---
|
|
||||||
title: 更新与升级
|
|
||||||
description: 检查更新与各形态的升级步骤、Linux 的升级回滚链路，以及升级前必须做的准备。
|
|
||||||
---
|
|
||||||
|
|
||||||
# 更新与升级
|
|
||||||
|
|
||||||
## 先知道版本是怎么回事
|
|
||||||
|
|
||||||
三端**共用一套版本口径**：
|
|
||||||
|
|
||||||
- 版本号的单一来源是仓库根 `package.json`。服务端在运行时读它（打包后读的是运行时清单），
|
|
||||||
不在代码里写死；
|
|
||||||
- 比较逻辑放在 `@classhelper/shared` 的 `compareVersions` / `isNewerVersion`，三端共用 ——
|
|
||||||
避免出现"客户端说有新版、服务端说没有"；
|
|
||||||
- 数字相同、只有后缀不同时，**带后缀的算更新**（对应 `v0.1.0-fix` 这种"同版本号的修复发布"）。
|
|
||||||
|
|
||||||
## 检查更新
|
|
||||||
|
|
||||||
| 端 | 入口 | 检查路径 |
|
|
||||||
| ------------------- | --------------------------------------------------------------- | ------------------------------------------------ |
|
|
||||||
| 服务端 / Web 管理端 | 顶栏用户菜单 →「检查更新」 | 浏览器 → 服务端 `GET /api/update/check` → GitHub |
|
|
||||||
| 桌面客户端 | 启动后自动一次（延迟 5 秒）+「设置 → 关于」里的「检查更新」按钮 | 主进程 → GitHub（不经后端） |
|
|
||||||
|
|
||||||
两端的路径不同是**被约束逼出来的**：
|
|
||||||
|
|
||||||
- **Web 端不能直连 GitHub**。服务端下发的 CSP 里 `connect-src` 只放行 `'self'` 与 WebSocket，
|
|
||||||
浏览器发往 `api.github.com` 的请求会直接被拦掉。走服务端转发还有个好处：所有管理员共享同一份缓存
|
|
||||||
（GitHub 匿名限流是 60 次/小时/IP）。
|
|
||||||
- **客户端在主进程做**。渲染进程的 CSP 与导航防线是安全模型里最要紧的一层，
|
|
||||||
不让它去连外部域名、解析外部 JSON。
|
|
||||||
|
|
||||||
### "查不到"是设计内的结果
|
|
||||||
|
|
||||||
机房服务器与教室机器常常只有内网，请求会超时或失败。这时接口返回 `ok: false` + 一句人话
|
|
||||||
（「无法连接 GitHub，本机可能没有外网」），界面按"暂时查不到更新"呈现并给重试入口，
|
|
||||||
**而不是弹红字报错**。
|
|
||||||
|
|
||||||
失败结果同样进缓存 —— 否则断网时每点一次按钮都要白等一个超时。
|
|
||||||
|
|
||||||
| 细节 | 说明 |
|
|
||||||
| ---------- | ----------------------------------------------------------------------------------------------------- |
|
|
||||||
| 缓存 | 两端各缓存 30 分钟；`?force=1` 绕过服务端缓存，但**仅管理员生效**（否则任意登录用户都能刷爆匿名限流） |
|
|
||||||
| 权限 | 任何已登录用户都能查（信息来自公开仓库）；`force` 除外 |
|
|
||||||
| 只提示一次 | 客户端启动检查发现新版才推提示；点「忽略此版本」记进配置，同一版本不再提示 |
|
|
||||||
|
|
||||||
更新**只提示，不自动下载、不自动安装**。安装包仍由人从 [Releases](https://github.com/LoveChengke/classhelper/releases)
|
|
||||||
页面取，可用 `SHA256SUMS-<版本>.txt` 核对。
|
|
||||||
|
|
||||||
## 升级步骤
|
|
||||||
|
|
||||||
### Windows 安装包
|
|
||||||
|
|
||||||
1. `stop.cmd` 停止服务；
|
|
||||||
2. **备份 `data` 目录**；
|
|
||||||
3. 运行新版本安装程序 —— 覆盖安装会**保留原有 `.env`**，JWT 密钥与端口设置不变，
|
|
||||||
用户不需要重新登录；
|
|
||||||
4. `start.cmd` 启动。数据库结构如有变更，会在首次启动时自动补跑迁移。
|
|
||||||
|
|
||||||
如果升级后需要重新登录，说明 `.env` 被覆盖了（JWT 密钥变了），检查安装目录权限。
|
|
||||||
|
|
||||||
### Linux
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo classhelper upgrade --check # 只检查有没有新版本
|
|
||||||
sudo classhelper upgrade # 升到最新版
|
|
||||||
sudo classhelper upgrade --version 1.2.0 # 升到指定版本
|
|
||||||
sudo classhelper upgrade --url ./classhelper-server-linux-x64-1.0.1.tar.gz --sha256 <哈希> # 内网离线
|
|
||||||
sudo classhelper upgrade --url <包> --force # 强制重装同一版本
|
|
||||||
|
|
||||||
sudo classhelper rollback --list # 看有哪些程序快照
|
|
||||||
sudo classhelper rollback # 回滚到最近一份（会问一次确认）
|
|
||||||
```
|
|
||||||
|
|
||||||
`upgrade` 的完整链路（**任一步失败都不改动程序文件**）：
|
|
||||||
|
|
||||||
```
|
|
||||||
解析目标版本 → 下载 → 校验 sha256 → 备份数据与配置 → 快照当前程序文件 →
|
|
||||||
停服 → 替换程序文件（改名 + 就位，data/ 与配置原地不动）→ 起服 → 轮询 /healthz
|
|
||||||
↘ 失败：自动用刚才的快照回滚并重新起服，再告诉你失败原因
|
|
||||||
```
|
|
||||||
|
|
||||||
两点必须知道：
|
|
||||||
|
|
||||||
1. **升级不会回滚数据库结构**。如果新版执行过迁移，回滚程序前要确认旧版还能读新库，
|
|
||||||
必要时用 `classhelper backup restore` 连数据一起回退。
|
|
||||||
2. 替换程序文件用的是"改名 + 就位"而不是删除重写：升级时**正在运行的就是 `bin/classhelper` 自己**，
|
|
||||||
必须先改名再放新文件，运行中的进程继续读旧 inode，否则 bash 会读到半个脚本。
|
|
||||||
|
|
||||||
### Docker
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker compose pull
|
|
||||||
docker compose up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
数据库迁移在启动时自动补跑。
|
|
||||||
|
|
||||||
### 手动 / 源码
|
|
||||||
|
|
||||||
拉新代码（或覆盖安装新的服务端程序）→ 重启服务端。启动时 `db-bootstrap` 会用账本表 `_ch_migrations`
|
|
||||||
对比已执行的迁移，只补跑缺的那些：
|
|
||||||
|
|
||||||
- 全新安装：依次执行全部迁移并创建初始管理员；
|
|
||||||
- 覆盖安装：只补跑账本里没有的迁移（已存在的表 / 索引自动跳过）；
|
|
||||||
- 已是最新：**不做任何写操作**。
|
|
||||||
|
|
||||||
日志里会明确写出「全新安装 / 升级安装」、应用了几个迁移、跳过了几个已存在对象。
|
|
||||||
|
|
||||||
### 客户端（ClassHelper 班级端）
|
|
||||||
|
|
||||||
从 Releases 取新的 `setup.exe` 覆盖安装即可，配置在 `%APPDATA%`，不受影响。
|
|
||||||
|
|
||||||
> 如果你是在**自己维护的机器**上只替换了 `releases/` 里的产物、而没有同步到安装目录，
|
|
||||||
> 用户打开的还是旧的 `resources/app.asar` —— 表现为"改了但界面不生效"。
|
|
||||||
> 覆盖升级时用 `robocopy ... /E` 推一遍，再对**那个副本**跑一次打包版冒烟确认。
|
|
||||||
|
|
||||||
## 升级前的准备清单
|
|
||||||
|
|
||||||
- [ ] 备份数据（`classhelper backup` / 复制 `data` 目录 / `mysqldump`）；
|
|
||||||
- [ ] 记下当前版本号，必要时能回滚到它；
|
|
||||||
- [ ] 挑一个没课的时间 —— 升级期间实时推送会中断；
|
|
||||||
- [ ] 升级后确认 `/readyz` 是 200，并且客户端顶栏的实时通道显示"已连接"。
|
|
||||||
|
|
||||||
## 给维护者
|
|
||||||
|
|
||||||
打版本、出安装包、发 Release 的完整流程见[版本迭代与发布](../dev/release.md)。
|
|
||||||
|
|
||||||
### 客户端远控与更新修复
|
|
||||||
|
|
||||||
先升级服务端，再推送修复后的客户端安装包。服务端兼容旧客户端读取顶层心跳字段，旧设备也可领取更新；第一次升级前仍遵循旧客户端的空闲安装条件。新客户端支持立即、放学后和空闲安装三种策略。放学后取指定的最早时间与当天最后一节课结束时间中的较晚者；设备离线时在再次上线后处理。
|
|
||||||
@@ -19,62 +19,28 @@ MySQL 兼容方式设计，可平滑切换到云端 MySQL / MariaDB 统一存储
|
|||||||
| 唯一约束仅使用 `@@unique` / `@unique` | SQLite 与 MySQL 语义一致 |
|
| 唯一约束仅使用 `@@unique` / `@unique` | SQLite 与 MySQL 语义一致 |
|
||||||
| 级联删除使用 Prisma 的 `onDelete` | 由 Prisma 生成对应外键动作 |
|
| 级联删除使用 Prisma 的 `onDelete` | 由 Prisma 生成对应外键动作 |
|
||||||
|
|
||||||
## 切换到 MySQL
|
## 切换步骤
|
||||||
|
|
||||||
### 方式一：Web 管理端「数据库管理 → 一键切换」（推荐，v1.0.0 新增）
|
### 1. 修改 provider
|
||||||
|
|
||||||
管理员在 Web 管理端打开 **数据库管理** 页（`/database`，仅 ADMIN 可见），在「一键切换数据库」卡片里：
|
|
||||||
|
|
||||||
1. 选目标类型（SQLite ⇄ MySQL）并填**空库**连接串（有表的库会被拒绝，防误覆盖）；
|
|
||||||
2. 输入「确认迁移」→ 点「开始迁移」。
|
|
||||||
|
|
||||||
界面会自动依次执行（带步骤进度条）：
|
|
||||||
|
|
||||||
1. **备份当前数据库**（gzip JSON 快照存 `<数据目录>/backups/`，失败可回滚）；
|
|
||||||
2. 导出当前数据为快照；
|
|
||||||
3. 测试目标库连接；
|
|
||||||
4. 检查目标库为空；
|
|
||||||
5. 改写 `schema.prisma` 的 provider；
|
|
||||||
6. 子进程 `prisma generate` 生成新方言的 Prisma 客户端；
|
|
||||||
7. （打包形态）把生成的 `.ts` 客户端编译进 `dist/generated`；
|
|
||||||
8. 子进程 `prisma db push` 在目标库建表；
|
|
||||||
9. 子进程 `dist/tools/apply-snapshot.js` 把快照写入目标库；
|
|
||||||
10. 全部成功后改写 `.env` 的 `DATABASE_PROVIDER` / `DATABASE_URL`。
|
|
||||||
|
|
||||||
**完成后必须重启服务端**（安装版运行 `restart.cmd`，开发模式重跑 `pnpm dev:server`）才会连接新库。
|
|
||||||
中途任一步失败会**回滚 `schema.prisma`**，`.env` 不被改写 —— 现有数据库与配置保持可用。
|
|
||||||
|
|
||||||
> 同一页还提供：连接状态检测（版本 / 体积 / 各表行数）、连接测试、手动与**定时备份**、
|
|
||||||
> 备份恢复、快照导出导入、SQLite 数据库文件下载。备份与导入导出共用同一种 JSON 快照格式，
|
|
||||||
> 因此**任意备份都能恢复回任意一种受支持的数据库**。
|
|
||||||
>
|
|
||||||
> 只支持 SQLite 与 MySQL 两种主库：Redis 等键值库不是 Prisma 支持的主数据库（无法建表/迁移），
|
|
||||||
> 接口层直接拒绝。
|
|
||||||
|
|
||||||
### 方式二：命令行手工切换
|
|
||||||
|
|
||||||
#### 1. 修改 provider
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 自动把 prisma/schema.prisma 的 provider 改成 mysql
|
# 自动把 prisma/schema.prisma 的 provider 改成 mysql
|
||||||
node scripts/use-database.mjs mysql
|
node scripts/use-database.mjs mysql
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 2. MySQL 驱动适配器（自 v1.0.0 起已随包内置）
|
### 2. 安装 MySQL 驱动适配器
|
||||||
|
|
||||||
Prisma 7 要求所有数据库都通过 driver adapter 接入，MySQL 对应 `@prisma/adapter-mariadb`
|
Prisma 7 要求所有数据库都通过 driver adapter 接入，MySQL 对应 `@prisma/adapter-mariadb`
|
||||||
（该适配器基于 `mariadb` 驱动，兼容 MySQL 8）。**它已在 `packages/server/package.json` 的
|
（该适配器基于 `mariadb` 驱动，兼容 MySQL 8）。
|
||||||
依赖里**（数据库管理模块的连接测试/迁移需要），因此无需再手动安装：
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 仅当从旧版本升级、依赖里还没有时才需要
|
|
||||||
pnpm --filter @classhelper/server add @prisma/adapter-mariadb
|
pnpm --filter @classhelper/server add @prisma/adapter-mariadb
|
||||||
```
|
```
|
||||||
|
|
||||||
`packages/server/src/lib/db.ts` 内置分支：当 `DATABASE_PROVIDER=mysql` 时会动态加载该适配器，
|
`packages/server/src/lib/db.ts` 已经内置分支：当 `DATABASE_PROVIDER=mysql` 时会动态加载该适配器，
|
||||||
服务端代码无需改动。
|
因此只需要安装依赖 + 配置环境变量，服务端代码无需改动。
|
||||||
|
|
||||||
#### 3. 配置环境变量
|
### 3. 配置环境变量
|
||||||
|
|
||||||
编辑 `packages/server/.env`：
|
编辑 `packages/server/.env`：
|
||||||
|
|
||||||
@@ -86,7 +52,7 @@ DATABASE_URL="mysql://classhelper:your-password@127.0.0.1:3306/classhelper"
|
|||||||
> 云端部署时把 `127.0.0.1` 换成云数据库内网/公网地址；
|
> 云端部署时把 `127.0.0.1` 换成云数据库内网/公网地址；
|
||||||
> 生产环境请同时修改 `JWT_SECRET` 与 `CORS_ORIGIN`。
|
> 生产环境请同时修改 `JWT_SECRET` 与 `CORS_ORIGIN`。
|
||||||
|
|
||||||
#### 4. 重建迁移并生成客户端
|
### 4. 重建迁移并生成客户端
|
||||||
|
|
||||||
SQLite 与 MySQL 的 DDL 方言不同，**必须重新生成迁移文件**：
|
SQLite 与 MySQL 的 DDL 方言不同，**必须重新生成迁移文件**：
|
||||||
|
|
||||||
@@ -105,11 +71,7 @@ pnpm db:seed
|
|||||||
pnpm --filter @classhelper/server exec prisma migrate dev --create-only --name init_mysql
|
pnpm --filter @classhelper/server exec prisma migrate dev --create-only --name init_mysql
|
||||||
```
|
```
|
||||||
|
|
||||||
> 只搬数据、不要演示数据时，用界面的「下载快照 / 导入快照」更省事：
|
### 5. 回到 SQLite
|
||||||
> 旧库导出 JSON → 切库建表 → 新库导入，一份快照也可用 CLI 迁移：
|
|
||||||
> `node server/dist/tools/apply-snapshot.js --provider mysql --url "mysql://..." --file snapshot.json`
|
|
||||||
|
|
||||||
#### 5. 回到 SQLite
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
node scripts/use-database.mjs sqlite
|
node scripts/use-database.mjs sqlite
|
||||||
@@ -118,8 +80,6 @@ rm -rf packages/server/prisma/migrations # 若之前已切换成 MySQL 迁移
|
|||||||
pnpm db:migrate
|
pnpm db:migrate
|
||||||
```
|
```
|
||||||
|
|
||||||
> 用界面「一键切换」回 SQLite 时，目标库同样必须是空文件：删除旧 `.db` 或指定一个新路径。
|
|
||||||
|
|
||||||
## 生产部署注意事项
|
## 生产部署注意事项
|
||||||
|
|
||||||
1. **连接池**：Prisma 7 的 driver adapter 使用底层驱动（`mariadb`）的连接池设置，
|
1. **连接池**：Prisma 7 的 driver adapter 使用底层驱动（`mariadb`）的连接池设置，
|
||||||
@@ -128,7 +88,3 @@ pnpm db:migrate
|
|||||||
三端展示时再按本地时区格式化（前端使用 `@classhelper/shared` 的 `formatDate`）。
|
三端展示时再按本地时区格式化（前端使用 `@classhelper/shared` 的 `formatDate`）。
|
||||||
3. **迁移部署**：CI/CD 中使用 `prisma migrate deploy`（对应 `pnpm db:deploy`）而不是 `migrate dev`。
|
3. **迁移部署**：CI/CD 中使用 `prisma migrate deploy`（对应 `pnpm db:deploy`）而不是 `migrate dev`。
|
||||||
4. **备份**：切换云数据库后，`packages/server/prisma/dev.db` 不再被使用，可从 `.gitignore` 之外移除。
|
4. **备份**：切换云数据库后，`packages/server/prisma/dev.db` 不再被使用，可从 `.gitignore` 之外移除。
|
||||||
界面「定时备份」把快照写进 `<数据目录>/backups/`（MySQL 模式下即安装根 `data/backups/`），
|
|
||||||
**服务端进程不运行时不会补跑**；关键环境建议同时用数据库自带的备份策略。
|
|
||||||
5. **安装包体积**：切换链路需要随包内置 `prisma` CLI 与 `typescript` 编译器（Prisma 7 生成器产出
|
|
||||||
`.ts`，切换后需在目标机编译进 `dist/generated`），服务端安装包因此约 34MB → 71MB。
|
|
||||||
@@ -2,12 +2,11 @@
|
|||||||
|
|
||||||
本文档覆盖三种上线形态，按适用场景选择：
|
本文档覆盖三种上线形态，按适用场景选择：
|
||||||
|
|
||||||
| 形态 | 适用场景 | 产物 | 验证状态 |
|
| 形态 | 适用场景 | 产物 | 本机验证情况 |
|
||||||
| --------------------- | -------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------- |
|
| --------------------- | -------------------------------------------- | ------------------------------------------------------ | -------------------------------------- |
|
||||||
| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统） | `releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe` | ✅ 已验证（静默安装 / 启停 / 卸载 / UI） |
|
| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统） | `release-server/班级小助手服务端-<版本>-x64-setup.exe` | ✅ 已完整实测（静默安装/启停/卸载/UI） |
|
||||||
| **B. Docker + MySQL** | 云服务器、多终端共享一套数据（推荐长期方案） | `deploy/Dockerfile` + `deploy/docker-compose.yml` | ⚠️ 文件已提供，尚未实机验证 |
|
| **B. Docker + MySQL** | 云服务器、多终端共享一套数据（推荐长期方案） | `deploy/Dockerfile` + `deploy/docker-compose.yml` | ⚠️ 文件已提供，本机无 Docker 未实测 |
|
||||||
| **C. Linux 原生部署** | 已有 Linux 服务器（systemd，SQLite 或 MySQL） | [`deploy/install.sh`](https://github.com/LoveChengke/classhelper/blob/master/deploy/install.sh) + `classhelper` 运维命令 | ⚠️ 实机验收清单见 [linux-deploy.md](linux-deploy.md) §10 |
|
| **C. 手动部署** | 已有 Node 环境的服务器、需要自定义 | `pnpm dist:server` 的免安装目录 | ✅ 免安装目录已实测（54 项端到端） |
|
||||||
| **D. 手动部署** | 已有 Node 环境的服务器、需要自定义 | 在仓库里构建后直接跑（见第四节） | ✅ 已验证（端到端验收通过） |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -22,13 +21,10 @@ pnpm dist:server -- --reuse-deps # 迭代打包：复用已安装依赖，跳
|
|||||||
|
|
||||||
产物：
|
产物：
|
||||||
|
|
||||||
| 路径 | 说明 |
|
| 路径 | 说明 |
|
||||||
| ----------------------------------------------------------------------- | -------------------------- |
|
| ----------------------------------------------------- | ----------------------------------------------- |
|
||||||
| `releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe` | 安装程序（约 62 MB，NSIS） |
|
| `release-server/classhelper-server/` | 免安装目录，可直接拷到任意 Windows x64 机器运行 |
|
||||||
|
| `release-server/班级小助手服务端-0.1.0-x64-setup.exe` | 安装程序（约 34 MB，NSIS） |
|
||||||
> 组装出来的运行时（内置 Node + 生产依赖 + 后端与 Web 产物，约 335 MB）是打安装包的中间物，
|
|
||||||
> 落在 `.cache/server-staging/<版本>/`，脚本打完就删 —— 交付目录里只留安装程序。
|
|
||||||
> 需要在有 Node 的机器上手动跑，见第四节。
|
|
||||||
|
|
||||||
打包内容：内置 **Node 运行时**（目标机无需安装 Node.js）、后端产物、Web 管理端产物、
|
打包内容：内置 **Node 运行时**（目标机无需安装 Node.js）、后端产物、Web 管理端产物、
|
||||||
生产依赖（真实目录，非软链）、迁移 SQL、`.env`（随机 JWT 密钥）、启停脚本。
|
生产依赖（真实目录，非软链）、迁移 SQL、`.env`（随机 JWT 密钥）、启停脚本。
|
||||||
@@ -38,11 +34,10 @@ pnpm dist:server -- --reuse-deps # 迭代打包：复用已安装依赖，跳
|
|||||||
双击安装程序即可，**无需管理员权限**（当前用户级安装）：
|
双击安装程序即可，**无需管理员权限**（当前用户级安装）：
|
||||||
|
|
||||||
- 安装目录：`%LOCALAPPDATA%\Programs\ClassHelperServer`
|
- 安装目录：`%LOCALAPPDATA%\Programs\ClassHelperServer`
|
||||||
- 静默安装：`"ClassHelper 服务端-1.2.0-x64-setup.exe" /S`
|
- 静默安装：`"班级小助手服务端-0.1.0-x64-setup.exe" /S`
|
||||||
- 开始菜单：启动服务 / 停止服务 / 重启服务 / 打开管理端 / 使用说明 / 卸载
|
- 开始菜单：启动服务 / 停止服务 / 重启服务 / 打开管理端 / 使用说明 / 卸载
|
||||||
- 桌面：`ClassHelper 服务端.lnk`（打开管理端）
|
- 桌面：`班级小助手服务端.lnk`（打开管理端）
|
||||||
- **开机自启动可选**：安装向导的组件页里勾选（默认勾选），装完之后还能在管理端「系统设置」里随时开关
|
- 自动加入当前用户开机自启（`HKCU\...\CurrentVersion\Run`）
|
||||||
（`GET/PUT /api/system/autostart`）；勾选时写的是 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run\ClassHelperServer`
|
|
||||||
- 卸载信息注册到「应用和功能」
|
- 卸载信息注册到「应用和功能」
|
||||||
|
|
||||||
安装完成后服务会自动启动并完成首次初始化：
|
安装完成后服务会自动启动并完成首次初始化：
|
||||||
@@ -101,8 +96,8 @@ uninstall-service.cmd :: 删除计划任务
|
|||||||
|
|
||||||
## 二、Docker + MySQL（形态 B，云部署推荐）
|
## 二、Docker + MySQL（形态 B，云部署推荐）
|
||||||
|
|
||||||
> 这套文件与已验证的产物结构一致（依赖清单、目录布局、迁移方式与服务端完全相同），
|
> 本机没有 Docker，因此这套文件未在本机实测；结构经过与已验证的产物对照（依赖清单、
|
||||||
> 但**尚未在真实 Docker 环境跑过**。第一次上线请先在测试机走一遍。
|
> 目录布局、迁移方式与服务端完全一致）。
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cp deploy/.env.example deploy/.env
|
cp deploy/.env.example deploy/.env
|
||||||
@@ -129,176 +124,25 @@ docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d --build
|
|||||||
- 反向代理上启用 HTTPS：见 `deploy/nginx.conf`，并在服务端环境变量中设置
|
- 反向代理上启用 HTTPS：见 `deploy/nginx.conf`，并在服务端环境变量中设置
|
||||||
`TRUST_PROXY=1`、`CORS_ORIGIN=https://你的域名`。
|
`TRUST_PROXY=1`、`CORS_ORIGIN=https://你的域名`。
|
||||||
|
|
||||||
### 2.1 单容器变体（SQLite，推荐给内存小的机器 / 与别的服务共用一台机器）
|
|
||||||
|
|
||||||
`deploy/docker-compose.sqlite.yml` 只跑**服务端一个容器**，不额外起 MySQL：数据落在 Docker 卷
|
|
||||||
`classhelper-data` 的 `/app/data/classhelper.db`，首次启动由 `AUTO_MIGRATE=true` 自动建表并创建管理员
|
|
||||||
（`packages/server/src/lib/db-bootstrap.ts` 的"空数据卷"分支）。
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cp deploy/.env.sqlite.example deploy/.env.sqlite # 填 JWT_SECRET、管理员密码、端口
|
|
||||||
docker compose -f deploy/docker-compose.sqlite.yml --env-file deploy/.env.sqlite up -d --build
|
|
||||||
```
|
|
||||||
|
|
||||||
适用场景与注意点：
|
|
||||||
|
|
||||||
- 机器内存紧张（比如 2G 小机器上还跑着别的服务）时，比 MySQL 变体少一个数据库进程；
|
|
||||||
- 端口用 `SERVER_PORT` 指定，**别抢占 80/443**（那通常是同机反代占用的）；
|
|
||||||
- 生产自检会拒绝 `dev.db` 与过短的 `JWT_SECRET`，因此 `DATABASE_URL` 必须是绝对路径且不含 `dev.db`；
|
|
||||||
- 备份就是整个卷：`docker run --rm -v classhelper-sqlite_classhelper-data:/data -v "$PWD":/backup alpine tar czf /backup/classhelper-db.tar.gz -C /data .`
|
|
||||||
|
|
||||||
> `deploy/Dockerfile` 的构建阶段会先跑 `pnpm --filter @classhelper/server run db:generate`：
|
|
||||||
> 生成产物 `packages/server/src/generated/prisma` 是 gitignored 的，而 `--ignore-scripts` 跳过了
|
|
||||||
> postinstall，少了这一步 `tsc` 会直接编译失败。
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 三、Linux 部署（形态 C，推荐一键安装器）
|
## 三、手动部署（形态 C）
|
||||||
|
|
||||||
适用：Ubuntu 20.04+ / Debian 11+ / CentOS 7+ / Rocky / AlmaLinux，任何有 systemd 的服务器
|
|
||||||
（容器环境用下面的 Docker 形态）。**完整指南见 [linux-deploy.md](linux-deploy.md)**，这里是速查。
|
|
||||||
|
|
||||||
### 3.1 一键安装（推荐）
|
|
||||||
|
|
||||||
Linux 包由 GitHub Actions 在 ubuntu runner 上构建（平台相关的依赖只能在 Linux 上装），
|
|
||||||
产物挂在 Release 上；也可以本地 `pnpm dist:server:linux` 后把 tar.gz 拷到服务器。
|
|
||||||
安装器脚本两个文件都在仓库的 `deploy/` 下：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 开发机：做出 Linux 包并连同脚本一起拷到服务器
|
|
||||||
pnpm dist:server:linux
|
|
||||||
scp releases/server/*/linux-x64/classhelper-server-linux-x64-*.tar.gz deploy/install.sh deploy/verify-linux.sh \
|
|
||||||
root@<服务器>:/tmp/
|
|
||||||
|
|
||||||
# 服务器上
|
|
||||||
bash /tmp/install.sh --check # 只体检（不需要 root，不改动系统）
|
|
||||||
sudo bash /tmp/install.sh # 交互式：选形态 → 选目录 → 选库 → 设初始管理员密码
|
|
||||||
```
|
|
||||||
|
|
||||||
非交互（批量部署 / 验收用）：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
printf '%s\n' 'StrongPass!2026' | sudo bash /tmp/install.sh --yes \
|
|
||||||
--dir /srv/classhelper --port 8080 --admin-password-stdin \
|
|
||||||
--package /tmp/classhelper-server-linux-x64-1.1.2.tar.gz
|
|
||||||
```
|
|
||||||
|
|
||||||
安装器做的事：识别发行版与包管理器补依赖 → 建系统用户 `classhelper` → 下载包并校验 sha256 →
|
|
||||||
铺文件（`server/` `web/` `node_modules/` `tools/` `bin/`）→ 下载内置 Node 运行时 →
|
|
||||||
写 `/etc/classhelper/config.env`（随机 `JWT_SECRET`，权限 600）→ 装 systemd 单元与
|
|
||||||
`/usr/local/bin/classhelper` → 启动并轮询 `/healthz` 通过为止。全过程写
|
|
||||||
`/var/log/classhelper/install.log`。
|
|
||||||
|
|
||||||
重跑就是**覆盖安装**：`config.env`（含密钥）与 `data/` 保留，已登录用户不会被踢下线。
|
|
||||||
|
|
||||||
### 3.2 安装后的布局与运维
|
|
||||||
|
|
||||||
```
|
|
||||||
/opt/classhelper/ 程序、node_modules、内置 Node、data/、tools/、bin/
|
|
||||||
/etc/classhelper/config.env 唯一配置真身（600）；安装目录里的 .env 是指向它的软链
|
|
||||||
/var/log/classhelper/ install.log + audit.log
|
|
||||||
/var/backups/classhelper/ 备份与程序快照（回滚用）
|
|
||||||
```
|
|
||||||
|
|
||||||
> 为什么安装目录的 `.env` 是软链：Web 端「数据库管理 → 一键切换」改写的是 `<安装目录>/.env`，
|
|
||||||
> 而 systemd 用 `EnvironmentFile=` 注入同一份配置；两处不是同一个文件时，切换会"看起来成功、
|
|
||||||
> 重启后又连回旧库"。软链把两者收成一份真身（`classhelper doctor` 会检查它）。
|
|
||||||
|
|
||||||
日常运维全部走 `classhelper`（`classhelper help` 看全部）：
|
|
||||||
|
|
||||||
| 事项 | 命令 |
|
|
||||||
| ------ | --------------------------------------------------------------------------------------- |
|
|
||||||
| 状态 | `classhelper status [--json]` |
|
|
||||||
| 体检 | `classhelper doctor`（权限 / Node / 服务单元 / 探针 / 数据库 / 磁盘 / 备份） |
|
|
||||||
| 改密码 | `classhelper password [用户名]`（交互输入、不回显、不进 shell history） |
|
|
||||||
| 备份 | `classhelper backup`；每日自动：`classhelper backup schedule daily` |
|
|
||||||
| 升级 | `classhelper upgrade [--check]`（下载 + 校验 sha256 + 备份 + 替换 + 探针，失败自动回滚） |
|
|
||||||
| 回滚 | `classhelper rollback [--list]` |
|
|
||||||
| 日志 | `classhelper logs -f` |
|
|
||||||
| 改配置 | `classhelper config set KEY VALUE` / `config show` / `port 8080` |
|
|
||||||
| 换密钥 | `classhelper key rotate`（所有用户需重新登录） |
|
|
||||||
| 卸载 | `classhelper uninstall`（默认保留配置、数据与备份） |
|
|
||||||
| 服务 | `classhelper start｜stop｜restart｜reload` |
|
|
||||||
|
|
||||||
### 3.3 手动部署（不想用安装器 / 没有 systemd）
|
|
||||||
|
|
||||||
没有 systemd 的容器里可以用安装器的"只铺文件"模式，再自己托管进程：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo bash /tmp/install.sh --yes --force --package /tmp/classhelper-server-linux-x64-1.1.2.tar.gz
|
|
||||||
sudo -u classhelper /opt/classhelper/runtime/node/bin/node /opt/classhelper/server/dist/index.js
|
|
||||||
```
|
|
||||||
|
|
||||||
完全手工也可以（等价步骤，便于排查）：解包后把 `server/` `web/` `node_modules/` `tools/` 铺到安装目录，
|
|
||||||
配置写到 `/etc/classhelper/config.env`（`JWT_SECRET` 用 `openssl rand -hex 48`），再用
|
|
||||||
`deploy/classhelper.service` 模板生成单元 —— 注意模板有 5 个占位符
|
|
||||||
（`__NODE__` `__DIR__` `__USER__` `__CONFIG__` `__CONFIGDIR__`）：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo sed -e "s#__NODE__#/opt/classhelper/runtime/node/bin/node#" \
|
|
||||||
-e "s#__DIR__#/opt/classhelper#" -e "s#__USER__#classhelper#" \
|
|
||||||
-e "s#__CONFIG__#/etc/classhelper/config.env#" -e "s#__CONFIGDIR__#/etc/classhelper#" \
|
|
||||||
deploy/classhelper.service > /tmp/classhelper.service
|
|
||||||
sudo install -m 644 /tmp/classhelper.service /etc/systemd/system/classhelper.service
|
|
||||||
sudo systemctl daemon-reload && sudo systemctl enable --now classhelper
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3.4 Nginx + HTTPS
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo cp deploy/nginx.conf /etc/nginx/conf.d/classhelper.conf
|
|
||||||
sudo nano /etc/nginx/conf.d/classhelper.conf # 改 server_name 与证书路径
|
|
||||||
sudo nginx -t && sudo systemctl reload nginx
|
|
||||||
```
|
|
||||||
|
|
||||||
`deploy/nginx.conf` 已经处理了最容易踩的两点：`/socket.io/` 的 WebSocket 升级头，
|
|
||||||
以及 `X-Forwarded-For/X-Forwarded-Proto` 透传（配合配置里的 `TRUST_PROXY=1`，限流才会按真实 IP 统计）。
|
|
||||||
用 certbot 签证书：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo apt install -y certbot python3-certbot-nginx
|
|
||||||
sudo certbot --nginx -d class.example.com
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3.5 验收
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo bash /tmp/verify-linux.sh --admin-password-stdin <<< 'StrongPass!2026'
|
|
||||||
# 追加升级 / 回滚链路（会真的替换一次程序文件）：
|
|
||||||
sudo bash /tmp/verify-linux.sh --full --package /tmp/classhelper-server-linux-x64-1.0.1.tar.gz \
|
|
||||||
--admin-password-stdin <<< 'StrongPass!2026'
|
|
||||||
```
|
|
||||||
|
|
||||||
覆盖安装结果、服务探针、API 登录、改密（含审计与回滚）、备份、配置读写、key rotate、
|
|
||||||
升级与回滚整条链路，末尾打印 `=== 结果：N/N 项通过 ===`。逐条清单见
|
|
||||||
[linux-deploy.md](linux-deploy.md) 第 10 节。
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 四、手动部署（形态 D）
|
|
||||||
|
|
||||||
目标机已有 Node.js（≥ 20.19）时，不需要任何安装包，直接在仓库里构建后跑：
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pnpm install
|
pnpm install
|
||||||
pnpm build:shared
|
pnpm build:shared
|
||||||
pnpm --filter @classhelper/server build
|
pnpm --filter @classhelper/server build
|
||||||
pnpm --filter @classhelper/web-admin build
|
pnpm --filter @classhelper/web-admin build
|
||||||
|
pnpm dist:server -- --reuse-deps # 得到 release-server/classhelper-server 免安装目录
|
||||||
```
|
```
|
||||||
|
|
||||||
按目标机的实际情况写好 `packages/server/.env`（端口、数据库、密钥、跨域），然后：
|
把该目录拷贝到目标机，编辑 `.env`（端口、数据库、密钥、跨域），然后：
|
||||||
|
|
||||||
```bash
|
```cmd
|
||||||
pnpm --filter @classhelper/server start # 或 node packages/server/dist/index.js
|
start.cmd :: Windows
|
||||||
|
# 或直接：node server/dist/index.js （Linux/macOS 用系统 node）
|
||||||
```
|
```
|
||||||
|
|
||||||
> 想把这份构建结果整体拷到另一台机器，就自己带上这四样：
|
|
||||||
> `packages/server/dist`、`packages/server/node_modules`（含 `src/generated/prisma`）、
|
|
||||||
> `packages/web-admin/dist`（服务端按 `web/` 静态托管）、以及 `packages/shared/dist`。
|
|
||||||
> `pnpm dist:server` 组装的正是这套东西，只是它现在把结果当中间物用、打完即删 ——
|
|
||||||
> 需要留档时把 `.cache/server-staging/<版本>/win/` 在打包过程中拷出来即可。
|
|
||||||
|
|
||||||
数据库初始化二选一：
|
数据库初始化二选一：
|
||||||
|
|
||||||
- 让服务自愈：`.env` 中 `AUTO_MIGRATE=true`（SQLite 首次启动自动建表 + 建管理员）
|
- 让服务自愈：`.env` 中 `AUTO_MIGRATE=true`（SQLite 首次启动自动建表 + 建管理员）
|
||||||
@@ -306,7 +150,7 @@ pnpm --filter @classhelper/server start # 或 node packages/server/dist/ind
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 五、环境变量清单
|
## 四、环境变量清单
|
||||||
|
|
||||||
| 变量 | 默认 | 说明 |
|
| 变量 | 默认 | 说明 |
|
||||||
| --------------------------------------------------- | ---------------------- | --------------------------------------------------------- |
|
| --------------------------------------------------- | ---------------------- | --------------------------------------------------------- |
|
||||||
@@ -324,16 +168,15 @@ pnpm --filter @classhelper/server start # 或 node packages/server/dist/ind
|
|||||||
| `PID_FILE` | — | PID 文件路径（安装包启停脚本依赖），相对 `server` 根 |
|
| `PID_FILE` | — | PID 文件路径（安装包启停脚本依赖），相对 `server` 根 |
|
||||||
| `WEB_DIST_DIR` | 自动探测 | Web 管理端产物目录（`../web-admin/dist` 或 `./web`） |
|
| `WEB_DIST_DIR` | 自动探测 | Web 管理端产物目录（`../web-admin/dist` 或 `./web`） |
|
||||||
| `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` |
|
| `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` |
|
||||||
| `DEFAULT_CLASS_PASSWORD` | `123456` | 新建班级时班级账号（ClassHelper 班级端登录）的默认密码 |
|
| `DEFAULT_STUDENT_PASSWORD` | `123456` | 新增学生的默认密码 |
|
||||||
| `DEFAULT_TEACHER_PASSWORD` | `123456` | 新增/重置教师账号的默认密码（管理员录入教师用） |
|
|
||||||
| `TERM_START_DATE` | — | 第 1 教学周的周一，用于"当前周次"与课表默认视图 |
|
| `TERM_START_DATE` | — | 第 1 教学周的周一，用于"当前周次"与课表默认视图 |
|
||||||
| `INITIAL_ADMIN_USERNAME` / `INITIAL_ADMIN_PASSWORD` | `admin` / `admin123` | 空库首启动创建的管理员 |
|
| `INITIAL_ADMIN_USERNAME` / `INITIAL_ADMIN_PASSWORD` | `admin` / `admin123` | 空库首启动创建的管理员 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 六、运维
|
## 五、运维
|
||||||
|
|
||||||
### 6.1 探针与监控
|
### 5.1 探针与监控
|
||||||
|
|
||||||
| 端点 | 用途 |
|
| 端点 | 用途 |
|
||||||
| ------------- | ---------------------------------------------------- |
|
| ------------- | ---------------------------------------------------- |
|
||||||
@@ -341,22 +184,22 @@ pnpm --filter @classhelper/server start # 或 node packages/server/dist/ind
|
|||||||
| `/readyz` | 就绪探针：数据库可连才 200，否则 503（负载均衡摘流） |
|
| `/readyz` | 就绪探针：数据库可连才 200，否则 503（负载均衡摘流） |
|
||||||
| `/api/health` | 详情：环境、数据库、已挂载模块、运行时长 |
|
| `/api/health` | 详情：环境、数据库、已挂载模块、运行时长 |
|
||||||
|
|
||||||
### 6.2 日志
|
### 5.2 日志
|
||||||
|
|
||||||
- 输出到 stdout/stderr，安装包形态由启停脚本重定向到 `logs\server.log`（UTF-8）。
|
- 输出到 stdout/stderr，安装包形态由启停脚本重定向到 `logs\server.log`（UTF-8）。
|
||||||
- 访问日志含方法、路径、状态码与耗时；5xx 记 error、4xx 记 warn。
|
- 访问日志含方法、路径、状态码与耗时；5xx 记 error、4xx 记 warn。
|
||||||
- 容器形态建议交给 Docker 日志驱动或采集到 ELK/Loki。
|
- 容器形态建议交给 Docker 日志驱动或采集到 ELK/Loki。
|
||||||
|
|
||||||
### 6.3 备份与恢复
|
### 5.3 备份与恢复
|
||||||
|
|
||||||
| 形态 | 备份 | 恢复 |
|
| 形态 | 备份 | 恢复 |
|
||||||
| ------ | ---------------------------------------------------------------------- | ------------------------ |
|
| ------ | ------------------------------------------------------ | ------------------------ |
|
||||||
| SQLite | 停止服务后复制 `data/classhelper.db`（Linux：`/opt/classhelper/data`） | 替换该文件后启动 |
|
| SQLite | 停止服务后复制 `data/classhelper.db` | 替换该文件后启动 |
|
||||||
| MySQL | `mysqldump -u classhelper -p classhelper > backup.sql` | `mysql ... < backup.sql` |
|
| MySQL | `mysqldump -u classhelper -p classhelper > backup.sql` | `mysql ... < backup.sql` |
|
||||||
|
|
||||||
建议：每日自动备份 + 保留 7 份；变更 `JWT_SECRET` 会导致所有用户重新登录，请勿在无必要时更换。
|
建议：每日自动备份 + 保留 7 份；变更 `JWT_SECRET` 会导致所有用户重新登录，请勿在无必要时更换。
|
||||||
|
|
||||||
### 6.4 安全清单（上线前逐项确认）
|
### 5.4 安全清单（上线前逐项确认）
|
||||||
|
|
||||||
- [ ] 修改 `admin` 与教师账号的默认密码
|
- [ ] 修改 `admin` 与教师账号的默认密码
|
||||||
- [ ] `JWT_SECRET` 使用随机值（≥48 字节），且妥善保管
|
- [ ] `JWT_SECRET` 使用随机值（≥48 字节），且妥善保管
|
||||||
@@ -369,7 +212,7 @@ pnpm --filter @classhelper/server start # 或 node packages/server/dist/ind
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 七、故障排查
|
## 六、故障排查
|
||||||
|
|
||||||
| 现象 | 排查方向 |
|
| 现象 | 排查方向 |
|
||||||
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
@@ -383,16 +226,12 @@ pnpm --filter @classhelper/server start # 或 node packages/server/dist/ind
|
|||||||
| 升级后需要重新登录 | 说明 `.env` 被覆盖（JWT 密钥变化）；覆盖安装应保留 `.env`，请检查安装目录权限 |
|
| 升级后需要重新登录 | 说明 `.env` 被覆盖（JWT 密钥变化）；覆盖安装应保留 `.env`，请检查安装目录权限 |
|
||||||
| 报 `does not provide an export named ...` | 安装包内的 `node_modules/@classhelper/shared/dist` 是旧构建（打包机没有先构建 shared）。重新执行 `pnpm dist:server`，该脚本会先构建 shared/server/web 并校验产物新鲜度 |
|
| 报 `does not provide an export named ...` | 安装包内的 `node_modules/@classhelper/shared/dist` 是旧构建（打包机没有先构建 shared）。重新执行 `pnpm dist:server`，该脚本会先构建 shared/server/web 并校验产物新鲜度 |
|
||||||
| 报 `node.exe` 不是有效应用 / 服务启动即退出 | 安装包内置的 `node.exe` 被误打成 Electron 可执行文件（打包机在 Electron 宿主里跑 pnpm 时会取到 `process.execPath`）。已由 `scripts/lib/node-runtime.mjs` 修正；可用 `install\node.exe -v` 确认能打印 Node 版本 |
|
| 报 `node.exe` 不是有效应用 / 服务启动即退出 | 安装包内置的 `node.exe` 被误打成 Electron 可执行文件（打包机在 Electron 宿主里跑 pnpm 时会取到 `process.execPath`）。已由 `scripts/lib/node-runtime.mjs` 修正；可用 `install\node.exe -v` 确认能打印 Node 版本 |
|
||||||
| **Linux**：`systemctl start` 后立刻退出 | `journalctl -u classhelper -n 50`；常见原因：`.env` 里 `JWT_SECRET` 为空/太短、`node` 路径在 unit 里不对（脚本用 `command -v node` 的结果）、`data/` 不可写（`chown classhelper:classhelper`） |
|
|
||||||
| **Linux**：403/500 且日志提示 `EACCES` | `ProtectSystem=full` 下服务只能写 `ReadWritePaths`；若自定义了数据目录，记得同步改 unit 里的这两项 |
|
|
||||||
| **Linux**：`npm install` 报网络/代理错误 | 目标机需要能访问 npm registry；离线环境可在别的机器 `npm install --omit=dev` 后把整个 `node_modules` 一起拷过去 |
|
|
||||||
| **Linux**：SQLite 提示 `database is locked` | 同一数据库文件只允许一个服务实例；确认没有重复启动（`systemctl status` + `pgrep -af 'server/dist/index.js'`），需要并发就换 MySQL |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 八、性能与容量参考
|
## 七、性能与容量参考
|
||||||
|
|
||||||
- 单机 SQLite 形态适合**单校规模**（数千用户、每天数百次写操作），接口与实时推送均已通过端到端验收。
|
- 单机 SQLite 形态适合**单校规模**（数千用户、每天数百次写操作），实测 62 项接口与实时推送全部达标。
|
||||||
- 多校区 / 高并发建议切 MySQL，并横向扩容服务端（Socket.IO 需要配置 Redis adapter 才能多实例广播，
|
- 多校区 / 高并发建议切 MySQL，并横向扩容服务端（Socket.IO 需要配置 Redis adapter 才能多实例广播，
|
||||||
当前为单实例广播；如需多实例请参考 `packages/server/src/realtime/socket.ts` 引入 `@socket.io/redis-adapter`）。
|
当前为单实例广播；如需多实例请参考 `packages/server/src/realtime/socket.ts` 引入 `@socket.io/redis-adapter`）。
|
||||||
- 静态资源已设置 immutable 长缓存 + gzip；Web 管理端为 SPA，首屏包体约 900 KB（gzip 约 290 KB），
|
- 静态资源已设置 immutable 长缓存 + gzip；Web 管理端为 SPA，首屏包体约 900 KB（gzip 约 290 KB），
|
||||||
-1561
File diff suppressed because it is too large.
Load diff
Binary file not shown.
|
Before Width: | Height: | Size: 312 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 312 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 362 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 312 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 277 KiB |
Loaded 100 of 416 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user