Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 LoveChengke
|
6347d1e5aa | ||
|
LoveChengke
|
2612a912ef | ||
|
LoveChengke
|
c7f215a09c | ||
|
LoveChengke
|
536379036a | ||
|
LoveChengke
|
3379eb975c | ||
|
LoveChengke
|
e84e43544a | ||
|
LoveChengke
|
05848570d1 | ||
|
LoveChengke
|
7f7d3925b2 | ||
|
LoveChengke
|
c83b03d8e6 | ||
|
LoveChengke
|
ead66f0b93 | ||
|
LoveChengke
|
57069a9a75 | ||
|
LoveChengke
|
b990701cde | ||
|
LoveChengke
|
35b252249d | ||
|
LoveChengke
|
4dc824c283 | ||
|
LoveChengke
|
66ef878a71 | ||
|
LoveChengke
|
c0ebf88138 | ||
|
LoveChengke
|
b7cdc7c9ea | ||
|
LoveChengke
|
227117ccb3 | ||
|
LoveChengke
|
3236d3ad83 | ||
|
LoveChengke
|
0b9a321bc9 | ||
|
LoveChengke
|
966c8f9b5d | ||
|
LoveChengke
|
817af02357 | ||
|
LoveChengke
|
e51879667a | ||
|
LoveChengke
|
9d5ac7adf9 | ||
|
LoveChengke
|
17f55864bf | ||
|
LoveChengke
|
0ea6bd887f | ||
|
LoveChengke
|
ded10118f5 | ||
|
LoveChengke
|
19c2aa07b2 | ||
|
LoveChengke
|
5b002a4f0b | ||
|
LoveChengke
|
580f5bed16 | ||
|
LoveChengke
|
ce9bed73f4 | ||
|
LoveChengke
|
82c85b59c1 | ||
|
LoveChengke
|
7b1ae29774 | ||
|
LoveChengke
|
9e52cfad4d | ||
|
LoveChengke
|
79d73c5889 | ||
|
LoveChengke
|
48e0c89394 | ||
|
LoveChengke
|
5d2fa2d6b4 | ||
|
LoveChengke
|
2be8d30376 | ||
|
LoveChengke
|
f6edfa5ea1 | ||
|
LoveChengke
|
985e602012 | ||
|
LoveChengke
|
d820926491 | ||
|
LoveChengke
|
f1edb42665 | ||
|
LoveChengke
|
67e3961e55 | ||
|
LoveChengke
|
9a38f86cd3 |
No files matched your search
@@ -0,0 +1,93 @@
|
||||
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
|
||||
@@ -0,0 +1,132 @@
|
||||
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"
|
||||
+6
-1
@@ -39,7 +39,7 @@ eslint-report.json
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# 参考用的第三方源码包（设计 token 已提取到 docs/winisland-design-tokens.md）
|
||||
# 设计参考压缩包（令牌见 docs/dev/winisland-design-tokens.md）
|
||||
WinIsland-master.zip
|
||||
releases/
|
||||
|
||||
@@ -48,3 +48,8 @@ releases/
|
||||
.zcodeignore
|
||||
packages/server/prisma/backups/
|
||||
packages/server/prisma/database-settings.json
|
||||
|
||||
# 文档站构建产物（pnpm docs:build 生成，由 GitHub Pages 发布；见 docs/）
|
||||
docs/_site/
|
||||
|
||||
packages/data/courseware/
|
||||
@@ -7,3 +7,4 @@ pnpm-lock.yaml
|
||||
.cache
|
||||
.pnpm-store
|
||||
.probe
|
||||
docs/_site
|
||||
@@ -1,780 +1,131 @@
|
||||
# AGENTS.md — 班级小助手（Class Helper）
|
||||
|
||||
本文件写给在本仓库里干活的 AI 编码代理。先读这里，再动代码。
|
||||
文中「本机环境」「已知坑」两节按**实测**写成；若与本机现状不符，以本机实测为准并顺手改掉这里。
|
||||
|
||||
---
|
||||
|
||||
## 1. 这是什么
|
||||
|
||||
班级信息管理系统，**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（学生用，含「灵动岛」浮窗） |
|
||||
| 共享契约 | `packages/shared` | 三端共用的类型 / 常量 / 权限 / 工具函数 |
|
||||
| ClassIsland 联动插件 | `packages/classisland-plugin` | .NET 8 / C#（装在教室的 ClassIsland 上：上报课表与上课状态、弹出老师发的提醒） |
|
||||
|
||||
核心链路：
|
||||
|
||||
```
|
||||
教师在 Web 端发布内容
|
||||
│ REST API（JWT 鉴权）
|
||||
▼
|
||||
后端服务（Express + Prisma）
|
||||
│ 写库 + 按班级房间广播
|
||||
▼
|
||||
Socket.IO ──► class:{classId} 房间 ──► 学生桌面客户端实时更新 UI
|
||||
|
||||
ClassIsland（教室机器）──► 班级小助手联动插件 ──► /api/integrations/classisland/*（设备令牌鉴权）
|
||||
▲ │
|
||||
└──── 老师下发的提醒（上报返回值里顺带带回）◄┘
|
||||
```
|
||||
|
||||
- 远端：`LoveChengke/ClassHelper`（仓库名大小写不敏感，本地 remote 存的是小写 `classhelper.git`）
|
||||
- 默认分支：`master`
|
||||
- 语言：**文档、注释、提交信息、界面文案一律中文**
|
||||
|
||||
---
|
||||
|
||||
## 2. 目录速查
|
||||
|
||||
```
|
||||
package.json 根脚本（dev / build / db:* / verify:* / dist:* / icons）
|
||||
pnpm-workspace.yaml workspace + allowBuilds（pnpm 11 依赖构建白名单，勿随手删条目）
|
||||
tsconfig.base.json 共享 TS 基础配置（ESM + NodeNext + strict）
|
||||
eslint.config.mjs ESLint 扁平配置（TS + Vue）；ignores 含 releases/ / release-server/ / src/generated/
|
||||
.prettierrc.json 单引号 / printWidth 110 / trailingComma all / LF / 2 空格
|
||||
build/icon.{ico,png} 应用图标（由 pnpm icons 生成）
|
||||
scripts/
|
||||
use-database.mjs SQLite ⇄ MySQL 切换（**改写 schema.prisma 里的 provider**，没有第二份 schema）
|
||||
generate-icons.mjs Electron 渲染 SVG → PNG/ICO
|
||||
icons/render.cjs 图标渲染（CommonJS）
|
||||
dist-server.mjs 服务端 + Web 管理端打包（产物落在 release-server/）
|
||||
nsis/server-installer.nsi 服务端 NSIS 安装脚本
|
||||
verify-packaged.mjs 对**打包后/已安装**的客户端 EXE 复跑冒烟
|
||||
ui-smoke/{run,main.cjs,live-probe.mjs} Web 管理端真实点击回归（Electron 驱动）
|
||||
lib/{electron-env,node-runtime}.mjs 启动 Electron / 定位真实 node.exe
|
||||
deploy/ Dockerfile / docker-compose{,.sqlite}.yml / nginx.conf / install-linux.sh
|
||||
classhelper.service / package.runtime.json / .env{,.sqlite}.example
|
||||
docs/ production.md（生产部署）/ mysql.md（MySQL 切换）/ winisland-design-tokens.md
|
||||
screenshots/{island,client,web-mobile,classisland}/
|
||||
packages/shared/src/ types.ts / constants.ts / permissions.ts / utils.ts / index.ts
|
||||
packages/server/
|
||||
prisma/schema.prisma 数据模型（14 个 model，无 enum、无 @db.*；连接串在 prisma.config.ts）
|
||||
prisma/migrations/ 10 个迁移（init / time_layout / class_account / schedule_week_parity /
|
||||
class_term_weeks / classisland_integration / class_notification_channel /
|
||||
homework_assign_date / push_kind / schedule_source）
|
||||
prisma/seed.ts 种子数据（会清空业务表后重建演示数据）
|
||||
prisma.config.ts Prisma 7 配置：schema / migrations / seed / 连接串
|
||||
scripts/verify-e2e.mjs 后端端到端验收（条数由脚本统计，实测 173 项）
|
||||
scripts/verify-classisland.mjs 联动链路验收（实测 42 项）
|
||||
scripts/apply-column-migrations.cjs 旧库补列（手工覆盖 dist 部署时用）
|
||||
src/app.ts Express 装配（探针 → 限流 → 模块挂载 → 静态托管 → 兜底）
|
||||
src/index.ts 启动入口（自检 + HTTP + Socket.IO + 优雅退出）
|
||||
src/config/env.ts zod 环境变量校验 + 生产自检
|
||||
src/lib/ access(RBAC) class-account db db-bootstrap http jwt logger mappers
|
||||
password schemas session term web-static
|
||||
src/middleware/ auth validate error security
|
||||
src/realtime/ socket.ts（房间）+ bus.ts（事件总线）
|
||||
src/modules/ 13 个功能模块 + registry.ts + module.types.ts
|
||||
packages/web-admin/src/ api stores router layouts views(11) components(4) composables styles config.ts
|
||||
packages/desktop-client/
|
||||
src/main/ 主进程：index / config（含作业短语与看板偏好）/ ipc / island / tray / logger / smoke
|
||||
src/preload/ contextBridge 白名单桥（index.ts + island.ts，**不暴露 ipcRenderer 本体**）
|
||||
src/island/ 灵动岛渲染进程：IslandApp.vue / spring.ts / squircle.ts / main.ts
|
||||
src/renderer/ 学生端渲染进程：api / cache(IndexedDB) / stores / views / island / router
|
||||
src/types/desktop.d.ts 主进程 ↔ 渲染进程契约
|
||||
scripts/ build-main / dev / smoke / dist-win
|
||||
packages/classisland-plugin/ .NET 8 插件（独立于 pnpm workspace，不参与 pnpm install）
|
||||
manifest.yml 清单：id=classhelper.classisland.bridge / apiVersion=2.0.0.0 / version=1.0.0.0
|
||||
ClassHelper.ClassIslandPlugin.csproj（TargetFramework=net8.0）
|
||||
src/Plugin.cs 入口：读配置 → 注册提醒提供方 / 设置页 / BridgeService
|
||||
src/Models/PluginSettings.cs
|
||||
src/Services/ BridgeService（上报·接收·镜像）/ ScheduleMapper / ClassPlanWriter
|
||||
ClassHelperNotificationProvider（把提醒显示到 ClassIsland 上）
|
||||
src/Views/BridgeSettingsPage.axaml(.cs)：Avalonia 设置页
|
||||
src/Interop/ClassHelperClient.cs：HTTP 客户端 + 与服务端逐个字段对齐的 DTO
|
||||
scripts/ build.mjs（编译 / 打包 .cipx）/ verify.mjs（静态契约校验，实测 68 项）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 本机环境（2026-09-30 实测）
|
||||
|
||||
| 项 | 状态 |
|
||||
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Node | **v24.19.0**（`D:\nodejs\node.exe`；要求 ≥ 20.19，Prisma 7 硬性要求） |
|
||||
| pnpm | 11.8.0（`packageManager` 锁定 11.8.0），宿主就是上面这个 node |
|
||||
| npm registry | `https://registry.npmjs.org/`（仓库内无 `.npmrc`，取全局配置） |
|
||||
| 依赖 | 已装（707 包，`pnpm install` 实测 2m45s） |
|
||||
| 后端 `.env` | 已由 `.env.example` 生成（**gitignored**），`JWT_SECRET` 为本机随机值，`TERM_START_DATE=2026-09-07` |
|
||||
| Prisma Client | 已生成到 `packages/server/src/generated/prisma`（gitignored） |
|
||||
| 数据库 | SQLite `packages/server/prisma/dev.db`：10 个迁移已应用、种子已写入（用户 18 / 班级 3 / 课程 54 / 课表 93 / 作业 15 / 通知 12 / 成绩 90） |
|
||||
| `shared/dist` | 已构建（`pnpm build:shared`）—— **它是三端与 seed 的前置产物，缺了会 `ERR_MODULE_NOT_FOUND`** |
|
||||
| Electron 二进制 | 已手动装好（`node_modules/.pnpm/electron@44.3.0/node_modules/electron/dist/electron.exe`，246 MB） |
|
||||
| .NET SDK | ✅ **8.0.425**（`C:\Program Files\dotnet\sdk`，`dotnet --list-sdks` 有输出）⇒ 插件可编译/打包；**别再照旧文档说"没装"**（`dotnet` 在 PATH 里，`--list-sdks` 才是权威判据） |
|
||||
| ClassIsland | **2.1.0.1，装在 `D:\Classisland`**（启动器 `D:\Classisland\ClassIsland.exe`，实际进程 `D:\Classisland\app-2.1.0.1-0\ClassIsland.Desktop.exe`） |
|
||||
| ClassIsland 数据 | 数据根 **`D:\Classisland\data`**：`Config/`、`Profiles/`、`Plugins/`（当前为空，尚未装本插件）、`Logs/`、`Cache/`、`Settings.json` |
|
||||
| 桌面会话 | 有（`ClassIsland.Desktop.exe` 跑在 session 1）；**Electron GUI 在 AI 会话里也能跑**（需先修完整性标签，见 §7 第 7 条） |
|
||||
|
||||
> **旧文档里的 `F:\classisland` / `F:\data` 已失效**：本机只有 `C:` 与 `D:`，`F:` 盘不存在。
|
||||
> 另有一份旧副本在 `C:\Users\胡\Desktop\classisland`（数据在它自己的 `data/` 下，2026-09-18 用过），当前以 `D:\Classisland` 为准。
|
||||
|
||||
### 从零重建环境（本机实测可行的顺序）
|
||||
|
||||
```bash
|
||||
pnpm install # 需要下载 Electron 时加 NODE_OPTIONS=--use-system-ca
|
||||
|
||||
# 后端环境变量（.env 不入库，必须自己生成）
|
||||
cp packages/server/.env.example packages/server/.env # 至少改 JWT_SECRET；TERM_START_DATE 建议 2026-09-07
|
||||
|
||||
pnpm db:generate # 生成 Prisma Client
|
||||
pnpm --filter @classhelper/server db:deploy # 应用迁移（根 scripts 里没有 db:deploy，见 §7）
|
||||
pnpm build:shared # 必须先构建 shared，否则 seed / 服务端启动会失败
|
||||
pnpm db:seed # 写演示数据
|
||||
|
||||
# Electron 二进制不会随 pnpm install 下载，需要手动补：
|
||||
# 工作目录 node_modules/.pnpm/electron@44.3.0/node_modules/electron
|
||||
ELECTRON_MIRROR=https://cdn.npmmirror.com/binaries/electron/ node install.js
|
||||
|
||||
# ClassIsland 插件（.NET 8 SDK 已装：8.0.425）
|
||||
pnpm build:classisland-plugin
|
||||
```
|
||||
|
||||
### 演示账号（`pnpm db:seed` 产出）
|
||||
|
||||
| 角色 | 用户名 | 密码 |
|
||||
| -------------- | ------------------------------- | ------------ |
|
||||
| 管理员 | `admin` | `admin123` |
|
||||
| 教师 | `teacher1` / `teacher2` | `teacher123` |
|
||||
| 学生端班级账号 | 班级码 `G101` / `G102` / `G203` | `123456` |
|
||||
|
||||
> 密码是**种子脚本里硬编码**的（`admin123` / `teacher123` / 班级 `123456`）；
|
||||
> `.env` 的 `DEFAULT_CLASS_PASSWORD` 只影响**新建**班级时的初始班级密码。
|
||||
> **学生没有个人账号**（2026-10-01 清理）：`student01…15` 只是名单记录（成绩/未交/叫人/已读按名单），
|
||||
> `User.passwordHash` 为空串、不能登录，也没有任何密码接口；学生端统一用班级码 + 班级密码。
|
||||
> 班级码 `G203` 是「高二(3)班」，不是 `G103`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 常用命令
|
||||
|
||||
| 命令 | 说明 |
|
||||
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| `pnpm dev` | 并行启动 shared(tsc watch) + 后端(4000) + Web 端(5173) |
|
||||
| `pnpm dev:server` / `pnpm dev:web` | 只启动后端 / 只启动 Web 端 |
|
||||
| `pnpm dev:desktop` | 客户端开发模式（Vite 5174 + Electron，热更新） |
|
||||
| `pnpm build` | 构建 shared + 后端 + Web 端 + 客户端 |
|
||||
| `pnpm build:shared` | 只构建 shared（改完 `packages/shared` 必须跑） |
|
||||
| `pnpm build:desktop` | 只构建客户端（esbuild 主进程/preload + Vite 渲染进程） |
|
||||
| `pnpm build:classisland-plugin` | 构建 ClassIsland 联动插件（.NET 8；缓存/临时目录自动指到 `.cache/`） |
|
||||
| `pnpm dist:classisland-plugin` | 打包插件为 `.cipx` 并归集到 `releases/classisland-plugin/` |
|
||||
| `pnpm typecheck` | 全仓库类型检查（含 `vue-tsc`） |
|
||||
| `pnpm lint` / `pnpm lint:fix` | ESLint |
|
||||
| `pnpm format` / `pnpm format:check` | Prettier（`format:check` 在 master 基线上本就失败，见 §7 第 21 条） |
|
||||
| `pnpm db:generate` | 生成 Prisma Client |
|
||||
| `pnpm db:migrate` | `prisma migrate dev`（本机不可靠，别用；见 §7） |
|
||||
| `pnpm --filter @classhelper/server db:deploy` | 应用已有迁移（**本机推荐**；根 scripts 里没有 `db:deploy`） |
|
||||
| `pnpm db:seed` / `pnpm db:reset` | 写种子 / 重置并重播种子 |
|
||||
| `pnpm db:studio` | Prisma Studio |
|
||||
| `pnpm db:switch:mysql` / `db:switch:sqlite` | 改写 `schema.prisma` 的 provider（配合 `docs/mysql.md`） |
|
||||
| `pnpm verify:e2e` | 后端端到端验收（**需后端已启动**；2026-09-30 实测 173 项全过） |
|
||||
| `pnpm verify:web` | Web 管理端真实点击回归（Electron 驱动，需后端已启动且 Web 产物已构建） |
|
||||
| `pnpm verify:desktop` | 客户端冒烟（Electron，无人工点击） |
|
||||
| `pnpm verify:packaged` | 对**打包后/已安装**的客户端 EXE 跑同一套冒烟（`--exe` 指定路径） |
|
||||
| `pnpm verify:classisland` | ClassIsland 联动链路（设备令牌 / 上报 / 提醒下发与回执 / 镜像契约 / 幽灵行清理；实测 42 项） |
|
||||
| `pnpm verify:classisland-plugin` | 插件静态契约校验（清单一致性 / 注册完整性 / C# DTO ↔ 服务端 zod 与路由 / 已修复坑的护栏；实测 68 项） |
|
||||
| `pnpm dist:server` / `dist:win` / `dist:dir` / `dist:all` | 打包服务端安装程序 / 客户端安装包 / 免安装目录 / 全部 |
|
||||
| `pnpm icons` | 生成应用图标（Electron 渲染 SVG → PNG/ICO） |
|
||||
|
||||
### 端口
|
||||
|
||||
| 端口 | 用途 |
|
||||
| ---- | --------------------------------------------------------- |
|
||||
| 4000 | 后端 REST + Socket.IO + （生产/构建后）Web 管理端静态托管 |
|
||||
| 5173 | Web 管理端开发服务器（`/api`、`/socket.io` 代理到 4000） |
|
||||
| 5174 | 桌面客户端渲染进程开发服务器 |
|
||||
|
||||
### 交付产物归集
|
||||
|
||||
打包脚本各自输出到固定目录，**归集到仓库根 `releases/` 是本仓库的人工约定**（该目录 gitignore + eslint ignore）：
|
||||
|
||||
```
|
||||
release-server/ pnpm dist:server 的输出（免安装目录 + NSIS 安装程序）
|
||||
packages/desktop-client/release/ pnpm dist:win / dist:dir 的输出（win-unpacked + setup.exe + portable.exe）
|
||||
releases/ 本仓库约定的归集处（把上面的产物拷进 client/ server/ classisland-plugin/）
|
||||
```
|
||||
|
||||
```bash
|
||||
# 客户端：electron-builder 支持指定输出目录（dist-win.mjs 会把额外参数透传）
|
||||
node packages/desktop-client/scripts/dist-win.mjs -c.directories.output=<绝对路径>\releases\client
|
||||
|
||||
# 服务端：输出路径写死在 release-server/，打完自行移进 releases/server/
|
||||
pnpm dist:server # 首次会跑一次 npm install；重试可加 --reuse-deps 跳过
|
||||
|
||||
# ClassIsland 插件：构建脚本自己归集到 releases/classisland-plugin/
|
||||
pnpm dist:classisland-plugin
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 架构硬约定（改代码前必须知道）
|
||||
|
||||
1. **模块注册表是唯一入口。** 服务端每个功能是 `src/modules/<name>/`（`*.module.ts` 路由、
|
||||
`*.schemas.ts` zod 校验、`*.service.ts` 业务）。当前 13 个：`auth / classes / courses / schedules /
|
||||
homeworks / notifications / calls / imports / integrations / grades / students / teachers / dashboard`。
|
||||
新增/下线功能**只改 `src/modules/registry.ts`**（加一行 / 改 `enabled: false`），不要动 `app.ts`。
|
||||
2. **统一响应与校验。** 用 `src/lib/http.ts` 的 `sendOk / sendCreated / …` 返回，用
|
||||
`middleware/validate.ts` 挂 zod schema；错误交给 `middleware/error.ts`，不要各写一套。
|
||||
3. **鉴权 = JWT + RBAC + 班级内角色。** 路由级用 `requireRole('ADMIN', 'TEACHER')`；班级维度用
|
||||
`@classhelper/shared` 的 `resolveClassRole` → `ADMIN / HEAD（班主任）/ SUBJECT（科任）/ STUDENT / NONE`，
|
||||
权限判 `canManageSchedule` / `canPublishContent` / `canManageRoster` / `canManageGrades` 等
|
||||
（人类可读矩阵是 `PERMISSION_MATRIX`，README 直接引用它），**不要在页面里另写一套规则**。
|
||||
4. **学生端主体是「班级账号」。** 班级码 + 班级密码登录后，`classId` 即身份；该设备的「已读 / 完成」
|
||||
代全班操作，个人学生登录已停用。API 里对此有专门分支，别按个人账号语义改。
|
||||
5. **实时推送只走房间。** 服务端 `src/realtime/`（`SOCKET_ROOMS`：`class:{classId}`、`user:{id}`、
|
||||
`teacher:{id}`、`role:{role}`、`students`、`teachers`；`bus.ts` 事件总线），客户端
|
||||
`renderer/stores/realtime.ts` 订阅。**新增实时事件要同时改三处**：服务端 bus/socket、Web 端订阅、
|
||||
客户端订阅（灵动岛也依赖它）。事件名一律取自共享常量 `SOCKET_EVENTS`，不要手写字符串。
|
||||
6. **共享契约只在 `packages/shared`。** 三端都 `import ... from '@classhelper/shared'`；它产出 `dist`，
|
||||
改完要 `pnpm build:shared`（或跑着 `pnpm dev` 的 watch）。类型/常量**不要在两端各写一份**。
|
||||
7. **数据模型跨库通用。** `schema.prisma` 只用 String / Int / Float / Boolean / DateTime，不用 Prisma enum、
|
||||
不用 `@db.*`；角色与优先级存字符串并在 API 层用 zod 校验（这样 SQLite / MySQL 行为一致）。
|
||||
**只有一份 `schema.prisma`**：切库是改写它的 `provider`（`pnpm db:switch:mysql`），没有 `schema.mysql.prisma`。
|
||||
改模型要同步 `prisma/migrations/`（本机用 `pnpm --filter @classhelper/server db:deploy` 应用）。
|
||||
8. **周次口径唯一。** 当前教学周 = `shared.resolveCurrentWeek(TERM_START_DATE, now, MAX_TERM_WEEK)`，
|
||||
`MAX_TERM_WEEK = 30`，班级还有自己的 `Class.termWeeks`（默认 20，**上限也是 30**）。别在别处重新实现周次换算。
|
||||
周次上限三处必须一致：`MAX_TERM_WEEK`、`lib/schemas.ts` 的 `weekNumberSchema`、`classes.schemas.ts` 的 `termWeeks`
|
||||
（曾经班级能设到 40 而课表只到 30，等于对外承诺了系统兑现不了的学期长度）。
|
||||
`Class.termWeeks` 只有**管理员**能改（`assertCanManageClasses`），班主任不行。
|
||||
9. **Electron 安全边界。** `src/preload/` 只通过 contextBridge 暴露白名单方法，**不要暴露 `ipcRenderer` 本体**；
|
||||
主进程 ↔ 渲染进程的类型统一写在 `src/types/desktop.d.ts`。
|
||||
|
||||
**跨桥接只能传纯数据。** contextBridge 在参数跨越「主窗口 → 隔离世界」时就做结构化克隆，
|
||||
传 Vue 的 `ref.value` / `reactive()` 对象（Proxy）会抛 `An object could not be cloned.`——
|
||||
而且它在**进入 preload 函数体之前**就失败了，所以桥接层**无法兜底**，只能由调用方展开成
|
||||
字面量再传（`saveConfig({ island: { ...island.value } })`）。这类失败是"半静默"的：
|
||||
界面数字照常变化、只多一行 console error，看起来就是"设置不生效"。设置页曾因此翻车，
|
||||
`verify:desktop` 里的「设置页真实 UI：拖拽滑块即时改变灵动岛外观」就是为它加的回归。
|
||||
|
||||
10. **客户端离线优先。** 渲染进程数据先落 IndexedDB（`renderer/cache/`），断网回退缓存并在顶部提示离线；
|
||||
新增页面/数据源要按这个模式接。
|
||||
11. **Web 端设计令牌集中。** 圆角/投影写在 `packages/web-admin/src/styles/index.css` 的 `:root`
|
||||
（`--ch-radius-xl/lg/md/sm/pill`、`--ch-shadow-sm/md`），组件里**不要写死数值**；Element Plus 通过覆盖它的
|
||||
CSS 变量对齐。手机小屏（≤768px）用抽屉导航 + 卡片内横向滚动，新增页面沿用 `useResponsive.ts` + `.table-card`。
|
||||
12. **ClassIsland 联动是独立鉴权通道，不要塞进 JWT。** 插件用设备令牌（`X-ClassIsland-Token`，库里只存 sha256，
|
||||
明文前缀为 `chci_`）调 `/api/integrations/classisland/*`；Web 端管理设备仍走 JWT + `requireRole`。
|
||||
新增插件接口时，路由挂 `integrations.module.ts`，并在 `integrations.schemas.ts` 里写 zod —— 插件侧的 C# DTO
|
||||
必须**逐字段对齐**（`pnpm verify:classisland-plugin` 会校验字段名与路由）。
|
||||
13. **课表镜像契约必须带 `startTime`/`endTime`。** ClassIsland 的 `ClassPlan.Classes[i]` 强制与时间表里
|
||||
**第 i 个 `TimeType == 0`（上课）的时间点**对齐：镜像下发少一个时间点，整份课表就会错位，
|
||||
而且表现为"课表看着有内容、每节课都对不上"，极难排查。
|
||||
14. **所有发布入口共用同一份 ClassIsland 推送实现**（`integrations.service.ts` 的 `pushToClassIsland`）：
|
||||
通知发布 / 叫人 / 联动页的下发都走它。新增「发通知」类入口时**必须**复用，不要再各写一套 ——
|
||||
否则又会出现「某个页面发的通知不联动 ClassIsland」。
|
||||
15. **提醒弹在哪个端由教室客户端选**，值存在 `Class.notificationChannel`（`both` / `client` / `classisland`）：
|
||||
客户端设置页写它（班级账号也有写权限，见 `PATCH /api/classes/:id/notification-channel`），
|
||||
服务端据此决定是否推 ClassIsland（`shouldPushToClassIsland`）。改动这条链路要同时动三处：
|
||||
客户端设置页与本地配置、`lib/mappers` 的 DTO、服务端推送判断。
|
||||
16. **灵动岛的左右边距只在「左/右停靠」时生效**：默认是「顶部居中」，水平锚点就是屏幕中线，
|
||||
此时调 marginX 不会有任何变化（设置页会把滑块置灰并说明，别把这个提示删掉 ——
|
||||
用户就是因此以为「调了不生效」）。上下边距与所有停靠位置都相关，不受影响。
|
||||
17. **镜像进 ClassIsland 的课表要带课间**：每两节之间补一段（上一节下课 → 下一节上课），
|
||||
**最后一节之后不补**（放学）。实现见 `ClassPlanWriter.BuildTimeLayout`（自己按课目时间算），
|
||||
服务端合成节次时间表同口径。
|
||||
18. **提醒分两类，决定"上课时段弹不弹"**：`ClassIslandPush.kind` = `notification`（通知类，上课时段
|
||||
客户端与插件都**暂存**、下课补弹）/`call`（叫人，算「主动通知」，立刻弹）；紧急（`URGENT`）同样立刻弹。
|
||||
插件侧的实现在 `ClassHelperNotificationProvider`（`_deferred` + `FlushDeferred`，订阅课程事件），
|
||||
客户端的实现在 `renderer/island/bridge.ts`。改这条规则要两端一起改。
|
||||
19. **作业按「所属日期」归类，不要用 createdAt 当"哪一天"**：`Homework.assignDate` 是本地日期
|
||||
（`YYYY-MM-DD`，不带时区），按天查看 / 日期高亮 / 客户端"今天"都看它。
|
||||
UTC 切片（`toISOString().slice(0,10)`）在晚上的录入会算到第二天 —— 统一用 `@classhelper/shared` 的
|
||||
`dayKeyLocal / isDayKey / shiftDayKey`。新增按天接口时同样用 `?date=YYYY-MM-DD` + zod 的 `isDayKey` 校验。
|
||||
20. **教室机器能录入作业**：`POST /homeworks` 的路由**故意不加 `requireRole`**，权限在
|
||||
`homeworks.service.createHomework` 里判（staff 或本班班级账号）。班级账号的 `sub` 是**班级 id**，
|
||||
写 `createdBy` 前要换成该班班主任，否则撞 `User` 外键。
|
||||
21. **灵动岛不要用窗口背景材质（`win.setBackgroundMaterial()`）**。它看起来像 WinIsland 的
|
||||
`DWMWA_USE_HOSTBACKDROPBRUSH`，其实是**整窗系统材质**：刷在整个窗口矩形上（岛是"固定大包围盒窗口"，
|
||||
卡片之外还有留白），且明暗跟随应用主题（本客户端是浅色 Fluent 主题 ⇒ 材质必然是浅色），
|
||||
于是卡片周围会出现一圈浅色"白底面板"。更坑的是**调用过一次就再也回不去逐像素透明**
|
||||
（含 `'none'`：Electron 会让窗口回落到默认不透明底色 `#FFF`），所以从 `glass` 切到
|
||||
`black`/`tinted` 后会永久留一圈**纯白**。CSS `backdrop-filter` 也替代不了（透明窗口里采样不到桌面）。
|
||||
`glass` 因此用 CSS 半透明深色卡（WinIsland 无 backdrop 时的降级色 `rgba(32,32,36,.804)`）。
|
||||
回归用例：「个性设置：卡片外圈透出桌面（三种风格都没有白底面板）」—— 它**整屏截图**取样
|
||||
（`webContents.capturePage()` 拍不到窗口之后的材质，是当初漏掉这个 bug 的原因），
|
||||
并在岛底下垫一块已知颜色的底板窗口，好让"环 = 底板色"可以被精确断言。
|
||||
22. **灵动岛位置由「屏幕工作区 + 边距」算，默认边距 8px（`DEFAULT_ISLAND_APPEARANCE.marginX/marginY`）**：
|
||||
改默认值会直接改外观，`verify:desktop` 的「停靠位置生效（6 个锚点）」断言的是像素坐标，一动就红。
|
||||
新增边距类设置请只改"可调范围"，别动默认值（夹紧规则收口在主进程 `normalizeIslandAppearance`）。
|
||||
23. **课表行有"来源"字段 `Schedule.source`**（`manual` / `classisland`）。插件每次全量上报时，
|
||||
服务端只清理「`source='classisland'` 且本次未再上报」的行 —— 这样老师在 ClassIsland 里删掉/挪动一节
|
||||
能真正同步下来（原先 merge 只 upsert，服务端会永远留着幽灵课），**老师在小助手这边手排的课一律不删**。
|
||||
因此：**新增写课表的入口要显式定 source**（Web 端录入/导入保持默认 `manual`，只有插件上报用 `classisland`），
|
||||
否则要么幽灵课清不掉，要么手排的课被误删。回归用例见 `verify:classisland` 的「幽灵行清理」两条。
|
||||
**`source` 只在 create 时确定，update 一律保持原值。** merge 的去重键是「星期 + 开始时间 + 单双周」，
|
||||
老师在 Web 端手排的同一时间槽会被上报"收养"；若收养时把来源改成 `classisland`，
|
||||
下一次清理就会把这行手排的课删掉 —— 这个坑踩过一次：种子课表被删掉 2 行，
|
||||
`verify:e2e` 的「上课状态接口」用例（AGENTS.md §7 已列为脆弱用例）随即报红。
|
||||
同步时**不要**覆盖 `weekStart/weekEnd`：插件上报契约里没有周次范围，硬写"整学期"会把老师设的「第 1~10 周」抹掉。
|
||||
24. **两个登录入口都必须挂 `loginRateLimiter()`**（`app.ts` 用数组形式同时挂 `/auth/login` 与 `/auth/class-login`）。
|
||||
班级密码默认是 `123456`、班级码是固定字符集，班级登录曾是唯一没有暴力破解防护的入口。
|
||||
另外 `auth.service.login` 里**角色判定必须在密码校验之前**：否则"密码错(401) / 密码对但学生账号已停用(403)"
|
||||
的差异会把学生账号密码变成可离线验证的预言机。
|
||||
25. **凡是会渲染成链接的字段都要校验 scheme。** `Homework.attachmentUrl` 在服务端用
|
||||
`attachmentUrlSchema`（只允许 `http(s)://` 或 `/` 开头的站内相对路径），Web 端渲染前再兜一层
|
||||
（`HomeworksView.vue` 的 `attachmentHref`）。放行 `javascript:` / `data:text/html` 就是一条存储型 XSS。
|
||||
26. **桌面端必须保留 CSP**（`index.html` / `island.html` 的 `meta http-equiv="Content-Security-Policy"`）。
|
||||
渲染进程通过 preload 能拿到 `getConfig()` 的**明文 token**（代表全班身份），CSP 是唯一能拦住
|
||||
"加载并执行远程脚本"的一层。配套的两条导航防线也别删：主窗口 `isAllowedNavigation`（按同源/同一文件精确比对，
|
||||
不要退回 `startsWith`）、灵动岛窗口的 `setWindowOpenHandler` + `will-navigate` 全拒。
|
||||
|
||||
27. **桌面端产物里不得出现任何凭据，构建有门禁。** `dist/main/index.js` 与 `dist/renderer/assets/*.js`
|
||||
会被 electron-builder 打进 `app.asar` 发给每台学生机，而 asar 可直接解包
|
||||
（历史问题：冒烟/自检代码里写死了 `teacher1/teacher123`，`grep` 产物即命中）。
|
||||
冒烟与自检用的账号口令、班级码/班级密码**一律通过环境变量注入**
|
||||
（`ELECTRON_SMOKE_USER` / `ELECTRON_SMOKE_PASSWORD` / `ELECTRON_SMOKE_CLASS_CODE` / `..._CLASS_PASSWORD`）：
|
||||
preload 读环境变量 → `window.desktop.smokeCredentials` → `setSmokeTeacherCredentials()`，
|
||||
由 `scripts/smoke.mjs` 与 `scripts/verify-packaged.mjs` 提供（那两个脚本不进安装包）。
|
||||
**把静态 import 改成 `await import('./smoke.js')` 解决不了这个问题**：esbuild 在
|
||||
`format:'cjs'` + `bundle:true` 下不做代码分割，动态 import 同样被内联进同一个产物（已实测）。
|
||||
`pnpm build:desktop` 结尾会跑 `check-bundle-secrets`（`packages/desktop-client/scripts/check-bundle-secrets.mjs`），
|
||||
产物里出现种子口令/把种子班级码当凭据的写法即构建失败 —— 别把这条门禁摘掉。
|
||||
28. **表格导入的体积上限是"请求体 12MB ↔ 文件 8MB"**：文件以 base64 放进 JSON（约 4/3 倍），
|
||||
因此 `express.json({ limit: '12mb' })` 必须留够余量，否则声明了 8MB 却连 1.5MB 的文件都传不进来。
|
||||
超限由 `middleware/error.ts` 映射成 413 `IMPORT_TOO_LARGE`（**不要**让它落进 500 兜底分支：
|
||||
原先用户看到的是一句英文的「服务器内部错误：request entity too large」）。
|
||||
29. **删除类接口的护栏要与 schema 的级联关系对齐。** `deleteTeacher` 的检查项必须覆盖
|
||||
`Class.teacherId` / `Course.teacherId` / `ClassTeacher.teacherId` / `Homework.createdBy` /
|
||||
`Notification.createdBy` 五项（后两项曾经漏检，会静默删掉该教师在各班发过的作业与通知；
|
||||
回归用例见 `verify:e2e` 的「删除教师护栏覆盖"发布过作业/通知"的账号」）。
|
||||
**改 schema 时先看哪些外键指向 `User` 且是 Cascade，再回来核对这个清单。**
|
||||
30. **灵动岛在触摸屏上必须走「触摸模式」（`touchMode`）。** 打开命中的两条链路
|
||||
（渲染进程的 mousemove 转发、主进程读 `screen.getCursorScreenPoint()`）**都以"鼠标指针移动"
|
||||
为前提**，而手指触摸既不产生 mousemove、也不移动系统光标 ⇒ 窗口永远停在
|
||||
`setIgnoreMouseEvents(true)` 的穿透态，**手指点不开岛**（用户反馈：希沃白板）。
|
||||
触摸屏上唯一的解法是"触摸点处窗口可命中"：Electron 没有 `SetWindowRgn`，
|
||||
所以渲染进程按 `navigator.maxTouchPoints > 0` 上报（`island:set-touch-mode`）后，
|
||||
主进程把窗口**贴合岛体**（`windowBox` = 当前形态 + 2×阴影留白）并**始终接收输入**
|
||||
（`setInteractive` 在触摸模式下把入参强制为 true）。三条护栏别动：
|
||||
|
||||
- **变小要等岛真的收小**（`cardFitsFormSize` + 渲染进程上报的岛体矩形）—— 立刻缩小会把形变中的卡片裁掉；
|
||||
- `expectedHitRect` 必须按**窗口实际尺寸**算偏移（触摸模式下窗口不再是固定包围盒）；
|
||||
- 失焦宽限期用 `BLUR_GRACE_TOUCH_MS`（1200ms）：触摸没有光标，`isCursorOnIsland()` 恒为 false，
|
||||
而实测假失焦出现在 70~520ms（跨过 500ms 边界 ⇒ 会把刚展开的岛缩回胶囊）。
|
||||
非触摸屏机器**完全不走这条路**（窗口仍是固定大包围盒 + 按光标命中），
|
||||
`verify:desktop` 会先 `setTouchMode(false)` 再跑既有的光标注入用例，末尾单独断言触摸模式。
|
||||
|
||||
31. **"改密码"的入口只剩 Web 管理端两处，客户端一个都没有。** 教师/管理员改本人密码走
|
||||
Web 顶栏下拉（`PATCH /api/auth/password`）；班级密码由管理员在「班级管理 → 修改班级账号」
|
||||
（`PATCH /classes/:id/class-account`）维护；教师设指定新密码用
|
||||
`POST /teachers/:id/reset-password`（可选 `newPassword`，留空 = 默认初始密码）。
|
||||
**2026-10-01 起学生个人账号整体清理**：学生只是名单（成绩/未交/叫人/已读按名单记录），
|
||||
`POST /students/:id/reset-password` 已删除（调用返回 404，e2e 有负断言）、新建学生不设密码
|
||||
（`User.passwordHash` 空串占位，`STUDENT` 的 403 登录判定在密码校验之前）、
|
||||
`DEFAULT_STUDENT_PASSWORD` 已删；客户端设置页的「修改密码」按钮**是按用户要求主动移除的**
|
||||
（防教室机器误改班级密码）——别当成"丢入口"的回归补回来。
|
||||
32. **灵动岛卡片的投影（CSS `filter`）必须常驻，形态切换只能改参数。**
|
||||
不要把 `filter: drop-shadow(...)` 只挂在 `.island-card.expanded` 上：**给元素增删 CSS filter**
|
||||
会让 Chromium 新建/销毁它的渲染表面（effect node），首帧的合成可能早于新表面栅格化完成，
|
||||
那一帧被当成空内容画出去 —— 而**卡片的底色恰好画在这个被过滤的元素上**（`.shape path` 的 `fill`），
|
||||
于是开/合的那一瞬间底座会闪掉一帧、只剩未过滤的文字层（用户反馈的"开合时一瞬间的闪动"）。
|
||||
正确写法见 `IslandApp.vue` 的 `.shape path`：filter 常驻，胶囊态用 `0 0 0` 的退化投影
|
||||
（硬轮廓正好压在路径底下，肉眼等同无投影，与 WinIsland「只有展开态有投影」的观感一致）。
|
||||
回归用例：`verify:desktop` / `verify:packaged` 的「灵动岛任意形态的投影都常驻」。
|
||||
|
||||
33. **多条通知时展开是「竖排列表」，卡片高度由主进程与渲染进程**各算一次同一个数**。**
|
||||
`@classhelper/shared` 的 `islandListLayout()`（度量表 `ISLAND_LIST_METRICS`）是唯一算法：
|
||||
默认只显示 `defaultVisibleRows`（3）条 + `展开更多（还有 N 条）`，按重要程度排序
|
||||
（`PRIORITY_RANK`，同级按时间新的在前）；点"展开更多"后铺到 `maxCardHeight` 为止，
|
||||
仍然放不下的改成「更多请前往应用内操作」——`maxCardHeight` 是主进程按工作区/任务栏算出的可用高度，
|
||||
随状态下发。两条硬约束：
|
||||
- **窗口包围盒必须跟着列表长高**（`IslandApp.vue` 的列表比任何普通形态都高，窗口不够高会把底部按钮裁掉）；
|
||||
长高发生在卡片形变**之前**（`setState` 里先 `relayout()` 再 `emit()`），用户看不到这一步；
|
||||
- 列表态 CSS 的每个尺寸（行高/行距/内边距/标题行/提示行/按钮行）都要与那份度量**一一对应**，
|
||||
改 CSS 必须改常量，否则"最后一行被切掉"这类问题会以"看着有内容、按钮点不到"的形式出现。
|
||||
回归用例：`verify:desktop` 的「多条通知竖向排列…」「点展开更多…」「通知多到屏幕放不下…」。
|
||||
写这类用例时注意：**断言"单条卡片"的用例（紧急卡/叫人卡/截图比例）必须先 `drainIsland()` 排空队列**，
|
||||
否则量到的是列表高度。
|
||||
|
||||
34. **"知道了 / 标为已读"之后是「状态同步落地 + 窗口淡出」，没有跨进程的收回握手。**
|
||||
收起一律是**主进程单向**的：`handleAction()` 收到 `dismiss` / `dismiss-all` / `mark-read` /
|
||||
`mark-all-read` → `dismissActive()`（还有下一条则退胶囊）或 `clearPendingForClose()`
|
||||
→ `hide()` → `fadeOut()`（每帧 `setOpacity(-0.2)`，到 0.02 后 `win.hide()`）。
|
||||
状态在**同一帧就写成** `hidden` / 清空，**不等渲染进程任何回执** —— 调用方与冒烟按"同步语义"断言
|
||||
（`island.ts` 的 `clearPendingForClose()` 注释：「状态同步落地（渲染进程随之收起卡片，窗口由 `hide()` 淡出）」）。
|
||||
渲染进程那侧只有本地弹簧形变（`spring.ts` 的 `targetSize/progress`），是纯视觉动画，不参与淡出时机。
|
||||
|
||||
**曾经有过一层自研的"收回快照"动画，已按用户要求整体删除。** 它叫 `closing` / `closingSnapshot`：
|
||||
点"知道了"后把卡片按"胶囊摘要"收回再淡出，是自研的形变状态机，**实测在触摸屏上会露出旧帧/重影**
|
||||
（触摸模式窗口贴合岛体、卡片形变时窗口跟着动），用户明确要求"动画就用仓库里那套"，于是整段删掉 ——
|
||||
现状见 `IslandApp.vue` 顶部注释。**别照着一份不存在的握手机制去改代码。**
|
||||
（`smoke.ts` 里"收回动画是渲染进程收敛上报 → 主进程淡出"只是一句过时注释，代码里没有这条链路。）
|
||||
|
||||
多条通知时这两个按钮都是**整批**操作：`dismiss-all` / `mark-all-read`（作业卡的合成 id
|
||||
`homework-<id>` 要在主进程按 kind 过滤掉，否则通知中心会去查一条不存在的通知 ——
|
||||
见 `handleAction()` 里 `mark-all-read` 分支的 `.filter((item) => item.kind !== 'homework')`）。
|
||||
回归用例：`verify:desktop` 的「多条通知点「知道了」：整批关闭（状态同步清空，窗口淡出隐藏）」。
|
||||
|
||||
排查"收回时闪一下"这类反馈时注意：**先看是不是自动化验证实例的叠影**（见第 41、42 条），
|
||||
别往这套已经不存在的握手机制上找原因。
|
||||
|
||||
35. **本机录入的作业不再上灵动岛。** 服务端是**先广播 `homework:new`、后回响应**的，
|
||||
等响应拿到 id 再登记就晚了（事件可能已经到了、岛已经弹出来了）——所以
|
||||
`renderer/island/bridge.ts` 在**发请求之前**按内容登记指纹（班级 + 日期 + 标题 + 正文），
|
||||
回执拿到 id 后再补记一次，投递前用 id / 指纹双重判定。改作业录入入口时别忘了在请求前调
|
||||
`markHomeworkCreatedLocally()`。回归用例：「本机录入的作业不再上灵动岛」。
|
||||
|
||||
36. **触摸模式下收回动画期间，窗口必须一动不动**（`syncTouchLayout()` 开头 `if (this.closing) return;`）。
|
||||
触摸模式窗口是"贴合岛体"的，而收回时卡片正在缩小：若跟着缩窗口，**中心停靠下窗口 x 还要右移**，
|
||||
"让出去"的那块区域会留着上一帧（DWM 还没重画桌面）——同一帧里能看到"旧展开卡的左半截 + 新胶囊"
|
||||
两份画面（用户拍照反馈的"收回一瞬间闪一下"）。窗口尺寸一律等**隐藏之后**再对齐
|
||||
（`syncWindow` 里"不可见时对齐包围盒"那条，不可见时改尺寸不会有残影）。
|
||||
回归用例：「触摸模式收回：动画期间窗口不动」逐帧采样窗口矩形（只在"窗口可见 / 正在收回"时追究，
|
||||
收完隐藏后对齐尺寸是正常的）；「收回动画期间卡片不被窗口裁切」。
|
||||
另：`cardFitsFormSize()` 的判据里**不能**再塞 `closing` —— 那条早退已经把收回整个排除了，
|
||||
早先漏掉这一条时窗口会在卡片还很大时就缩成胶囊尺寸，卡片底部被平切（"上半剩圆角、下半截断"）；
|
||||
而"隐藏态改边距不生效"那条修法仍要保留：`this.win.isVisible() && (mode !== 'hidden' || idleSliver)`。
|
||||
|
||||
37. **开合时胶囊内容禁止跟着卡片重排/横移。** 卡片在 268 ⇄ 424 之间变宽变窄，中心停靠下左右边都在动；
|
||||
胶囊内容若按卡片宽度布局，就会出现"文字先按宽卡片铺开、再随卡片收窄被省略号收回"
|
||||
（用户反馈的"新消息那行字往右跳一下再缩回"）。所以 `IslandApp.vue` 的胶囊层里套了一层
|
||||
`.pill-inner`，**固定成胶囊自己的几何**（`width: var(--island-w)`），并按停靠方式对齐
|
||||
（`data-anchor` = left/center/right → `justify-content` flex-start/center/flex-end）：
|
||||
左/右停靠贴对应边，居中则居中 —— 静止态外观与之前完全一致，动画全程文字位置与省略号都不变。
|
||||
回归用例：「灵动岛开合时胶囊内容不横移」，逐帧采样 `.pill-title` 左右边缘，波动必须 ≤ 2px。
|
||||
|
||||
38. **跑自动化验证时，验证实例的岛要挪到左上角 + 真实输入穿透。**
|
||||
`verify:desktop` / `verify:packaged` 会真的在屏幕上放一个灵动岛窗口（顶部居中），而用户自己的客户端
|
||||
默认也在同一位置（他的设置常是 `top-center` + 较大 `marginY`）—— 两个岛一高一低叠在一起，用户会以为
|
||||
**"屏幕上出现了第二个灵动岛"**，而且点它"反应不对"（它归验证脚本控制，会自己展开/收起/消失）。
|
||||
实测踩过：用户连续两条反馈（"收回去的时候闪一下/下半被截断"）其实都是这个叠影造成的。
|
||||
所以 `runIslandChecks` 开头把验证实例的岛做成**一眼可辨**：
|
||||
`island.setAppearance({ accent: '#e91e8c', style: 'tinted' })`（洋红 = 验证实例；跑完不必还原，
|
||||
验证用的是独立 profile），并且全程 `island.setTestInputPassthrough(true)` 让真实点击穿透。
|
||||
**只改颜色、不要改停靠位置**：命中/几何断言都是按默认位置写的，把岛挪到角落会把
|
||||
「空闲细缝态命中跟随光标」这类用例弄红（实测踩过）。
|
||||
另外：冒烟会**真发通知**给当前班级（实时链路用例必须打到客户端所在班），所以验证期间用户的通知列表/
|
||||
岛上会短暂出现几条「张老师 · _自检_」——它们用完即删（`createSmokeNotification` / `islandRealtimeCleanup`），
|
||||
若验证被中途 kill 会留下残条，收尾时顺手清一下（标题里带「自检 / 红点位置校验」的那几条）。
|
||||
|
||||
39. **冒烟期间要让真实鼠标点击穿透（`island.setTestInputPassthrough(true)`）。** 自动化要跑几分钟，
|
||||
而用户很可能正在同一块屏幕上 —— 他的客户端那个岛和冒烟这个窗口都在屏幕顶部居中、互相叠着，
|
||||
他点到的是**冒烟这个窗口**：实测冒烟收到了人发出的 `collapse` / `mark-read`，把「点胶囊展开」
|
||||
「点空白处收起」等用例整片弄红。开关只忽略**真实**输入：`cursorOverride`（`setHitTestCursor`）
|
||||
一旦注入就照常按注入位置判定，所以「光标轮询校正命中」「岛外穿透」「触摸模式始终接收输入」
|
||||
这些断言不受影响（触摸模式那条会临时关掉开关）。跑完在收尾处恢复。
|
||||
|
||||
40. **作业页的 `?date=` 深链必须在"已在作业页"时也生效。** `route.query.date` 只在组件 setup 里读
|
||||
一次的话，同路由再推 query（冒烟切到"最近有作业的日期"、用户从别处深链回来）会被复用的组件
|
||||
无视，看板停在原日期 —— 表现为"看板明明有历史作业却显示空"。修法是 watch `route.query.date`
|
||||
（`HomeworkView.vue`，与 `selectDate` 的 `router.replace` 形成环时靠"值相同就跳过"防死循环）。
|
||||
同理，冒烟里"切到有作业的日期"的判据是**看板里没有 `.board-card`**，不是"没有 `.board-host`"
|
||||
（空看板照样渲染容器，拿容器当判据兜底永远不会触发）。
|
||||
|
||||
41. **打包版冒烟自检发的通知要"任何时段都可见"**：用 `priority: 'URGENT'` + `confirmDuringClass: true`
|
||||
（上课时段普通通知会被**正确地**暂存到下课、紧急通知不带确认会被 409 `URGENT_DURING_CLASS` 拒掉 ——
|
||||
两个都是产品功能，别为了测试去改产品行为）。凡是断言"窗口已隐藏"的用例一律**轮询**等待，
|
||||
不要写死 sleep：`dismiss` 现在带 ~360ms 收回动画再淡出，机器忙时固定 sleep 会间歇性踩空
|
||||
（「关闭空闲细缝后空闲再次完全隐藏」曾因此 4 连红）。
|
||||
|
||||
42. **用户报"打包版用不了/装不上"先查两件事，别急着怀疑产物**（2026-10-01 实测，两次全是环境）：
|
||||
① **后端起没起** —— 客户端配置指向 `127.0.0.1:4000`，后端不在就进离线模式、数据全空，
|
||||
观感就是"软件坏了"；② **托盘单实例锁** —— 关窗是隐藏到托盘、进程还在，再双击 EXE 会被
|
||||
单实例锁秒退（看起来"点了没反应"），安装包也会因"应用正在运行"装不上：先从托盘退出。
|
||||
完整性标签（§7 第 7 条）用 `icacls | findstr Mandatory` 一眼可辨，优先排除。
|
||||
|
||||
43. **Web 端新手引导（`el-tour`）在自动化里的判据有三条坑**（2026-10-02 实测，`verify:web`
|
||||
「首次登录展示新手引导且可跳过」踩过）：
|
||||
① **外壳先出现、内容晚一拍** —— `document.querySelector('.el-tour')` 先于步骤卡片渲染成立，
|
||||
急着找 `.el-tour__closebtn` 会拿到 null；出现判据要等 **× 按钮渲染出来**（等 10s 不为过）。
|
||||
② **关闭后内容元素残留** —— 和 el-dialog 一样（本表第 22 条），点 × 生效后 `.el-tour` 仍在 DOM
|
||||
（父级 `.el-popper` 被隐藏，computed display 仍是 block）；**关闭判据是 `.el-tour__mask` 卸载**，
|
||||
不是 `.el-tour` 消失。跳过 / 走完都会写 `classhelper.onboarding`（版本号），可顺带断言。
|
||||
③ **全高元素（侧边栏）作锚点必须显式 `placement: 'right'`** —— 默认 bottom 会把卡片推到
|
||||
视口外（表现为"遮罩挖了洞、卡片不见了"）。
|
||||
另外 `ui-smoke` 管理员用例里的 `localStorage.clear()` 会把「已看过」标记一并清掉，管理员登录后
|
||||
引导会再次弹出 —— 该用例里必须先跳过它再继续，别只处理首次登录那一次。
|
||||
|
||||
44. **数据库管理模块（服务端）** 见 §5 第 36 条；做"切库/备份/迁移"类改动前先读那一条，
|
||||
那里写清了快照格式、外键陷阱、切换为什么必须走子进程、以及打包为何要带上 prisma CLI + tsc。
|
||||
|
||||
45. **客户端设置页已拆成子路由**（2026-10-02）：`/settings/{general,appearance,island,reminder,account,about}`，
|
||||
`/settings` 重定向到 `/settings/general`；旧的单一 `views/SettingsView.vue` **已删除**。
|
||||
改设置相关冒烟用例时必须改到对应子路由（`smoke.ts` 里 `location.hash = '#/settings'` 已全部改掉），
|
||||
否则会停在通用页、找不到灵动岛滑块或「ClassIsland 联动」卡片而误报失败。
|
||||
|
||||
46. **深色主题的实现边界**：颜色一律走 `--ch-*` / `--el-*` 变量（`styles/index.css` 的 `:root`
|
||||
是浅色值、`html.dark` 是深色值），**组件里不要写死颜色**。已知的固定深色区域（灵动岛、
|
||||
登录页、App 启动过渡页、全屏作业看板）刻意不随主题 —— 改它们会被当成回归。
|
||||
主题状态在 `stores/ui.ts`（持久化到主进程配置 `theme`），主窗口 `backgroundColor` 也按主题设置
|
||||
（深色下若仍用浅色底会"先白后黑"闪一下）。
|
||||
|
||||
47. **数据库管理模块（`/api/database/*`，仅 ADMIN）——改它之前必须知道的四件事**：
|
||||
① **一切都建立在 `lib/snapshot.ts` 的 JSON 快照上**（备份 / 导入导出 / 跨库迁移共用一种格式，
|
||||
14 张表按拓扑序导出、恢复时临时关外键检查、分批 `createMany`）。恢复时**必须**先关外键检查：
|
||||
schema 里 `User.classId → Class` 与 `Class.teacherId → User` **互相引用**，任何排序都会被一侧卡死。
|
||||
② **一键切换必须走子进程**：运行中的服务进程缓存的是旧方言的 Prisma Client，改完 provider 后
|
||||
只有**新进程**才能加载重新生成的客户端 —— 因此 `generate` / `db push` / 写数据分别用
|
||||
`spawn(process.execPath, ...)` 拉起（数据写入走 `dist/tools/apply-snapshot.js`）。
|
||||
**顺序不能换**：备份 → 导出 → 测试连接 → 校验目标库为空 → 改 schema → generate → 编译 → db push → 写数据 → 改 .env；
|
||||
`.env` 只在**全部成功后**才改写，中途失败回滚 `schema.prisma`（现有库不受影响）。
|
||||
③ **`prisma generate` 的产物是 `.ts`**（`prisma-client` 生成器），所以：dev 由 tsx 直接跑 src；
|
||||
**打包形态必须再跑一次 `tsc -p tsconfig.generate.json`** 把新客户端编进 `dist/generated`，
|
||||
生产包因此要随包带上 `prisma` CLI、`typescript` 与 `schema.prisma`/`prisma.config.ts`
|
||||
（`scripts/dist-server.mjs` 的 `buildRuntime` 已拷；安装包 ~34MB → ~71MB）。
|
||||
④ **主库只支持 SQLite / MySQL**：Redis 等键值库 Prisma 不支持（无法建表/迁移），
|
||||
schema 层直接 422 拒绝；这是产品口径，别"顺手"加上。
|
||||
e2e 只覆盖校验分支（同库 400 / 非法 provider 422 / 目标库非空），**不真跑切换**（会改写 .env）；
|
||||
真实切换用子进程链路单独实测（快照 728 行逐表一致）。切换后**必须重启服务端**才生效。
|
||||
|
||||
48. **客户端主窗口初始尺寸与 ClassIsland 对齐（1242×582）**。这个数不是拍的：用
|
||||
`GetWindowRect` + `DwmGetWindowAttribute(DWMWA_EXTENDED_FRAME_BOUNDS)` 量运行中的
|
||||
`ClassIsland.Desktop` 主窗口（实测可视区 1242×582，屏幕工作区 1600×852、DPI 100%）。
|
||||
`main/index.ts` 的 `createWindow` 按它设 width/height + `center: true`，
|
||||
**`minHeight` 必须 ≤ 582**（否则窗口达不到目标高度，用户会看到"设置不了那个大小"）。
|
||||
冒烟断言：「初始窗口尺寸与 ClassIsland 对齐（1242x582）」（`win.getSize()`），改尺寸即红。
|
||||
|
||||
49. **侧栏（分组折叠菜单）的三条硬要求**，都是用户报过的问题固化的：
|
||||
① **折叠态文字必须 `display: none`** —— Element Plus 自己的隐藏方式是"把 span 的宽高压成 0 +
|
||||
overflow"，外层只要有缩进/margin/transition 干扰，文字就会以"0 宽溢出"留在画面上
|
||||
（用户截图里的半截字）。规则写在 `styles/index.css` 的 `.ch-nav .el-menu--collapse ... > span:not(.menu-icon-slot)`。
|
||||
② **折叠态图标必须与顶部汉堡按钮同一竖列**（冒烟断言中心差 ≤ 2px）—— 一个居中、一个偏左就会
|
||||
看起来"没对齐"。汉堡在 `.brand` 里也是居中的，两边都在 64/2 = 32px。
|
||||
③ **菜单区必须 `min-height: 0` + `overflow-y: auto`** —— 否则菜单项多时会把底部
|
||||
「第 N 周 / 最近同步」挤出窗口（窗口 582px 高、两组全展开时必然发生）。footer 是 aside 的
|
||||
兄弟 flex 子项，菜单区滚动后它恒定可见（冒烟断言「侧栏底部可见」）。
|
||||
另：分组**默认只展开当前路由所在分组**（ClassIsland 同款，也让小窗口侧栏不溢出）；
|
||||
`el-sub-menu__title` 的点击是 **toggle**，自动化里要先判"子项是否可见"再决定点不点标题
|
||||
（盲点会把已展开的组收起来，后续点不到子项）。
|
||||
|
||||
50. **深色主题：渲染进程里除固定深色区域外，颜色一律走 `--ch-*` 变量。**
|
||||
§5 第 46 条讲了机制，这里补具体踩坑：课表页时间轴卡片曾写死 `rgba(255, 255, 255, 0.6)`，
|
||||
深色主题下变成"浅灰卡 + 近白字"几乎不可读（用户截图）。自查命令：
|
||||
`grep -rn "rgba(255, 255, 255\|rgba(0, 0, 0\|#fff" packages/desktop-client/src/renderer`，
|
||||
除**明确固定深色**的区域（全屏作业看板、登录页渐变、App 启动过渡页、灵动岛自身、
|
||||
以及 accent 渐变底上的白字）外，都应该是变量。
|
||||
|
||||
51. **跑 `verify:desktop` / `verify:packaged` 若大面积报"教师登录失败"，先核对本机 teacher1 的密码**：
|
||||
本机实测是 **`123456`**，不是种子默认的 `teacher123` —— 因为「修改密码」弹窗留空会落到
|
||||
`DEFAULT_TEACHER_PASSWORD`（=123456），某次人工/脚本操作就会把演示账号改成它。
|
||||
处理方式是用环境变量传实际凭据（脚本原生支持，**不要去改数据**）：
|
||||
`set "ELECTRON_SMOKE_USER=teacher1" && set "ELECTRON_SMOKE_PASSWORD=123456" && pnpm verify:desktop`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 代码风格
|
||||
|
||||
- **TypeScript ESM + NodeNext**：`package.json` 全是 `"type": "module"`，相对导入**必须带 `.js` 后缀**
|
||||
（写 `./foo.js`，即使源文件是 `foo.ts`）。`strict` 开启。
|
||||
- **Prettier**（`.prettierrc.json`）：单引号、`printWidth: 110`、`trailingComma: all`、`arrowParens: always`、
|
||||
行尾 LF、缩进 2 空格。
|
||||
- **ESLint**（`eslint.config.mjs`）：`no-explicit-any` 为 warn；未使用变量为 warn，可用 `_` 前缀豁免；
|
||||
`consistent-type-imports` 建议用 `import type`。`.cjs`（Electron 图标渲染、UI 冒烟）允许 `require`。
|
||||
- **Vue**：视图命名 `XxxView.vue`，组件多单词；路由入口用 `meta.roles` 控制（如 `['ADMIN']`），
|
||||
隐藏入口之外服务端也必须拦（前端隐藏 ≠ 权限）。
|
||||
- **提交信息**：Conventional Commits + 模块 scope，描述用中文，可多 scope，例如
|
||||
`fix(island): 胶囊"点不动"的根因——窗口必须始终可激活`、
|
||||
`feat(teachers,classes,schedules,web): 教师录入（仅管理员）`。
|
||||
- **改动交付形态 / 新增功能后**，同步更新 `README.md`（它兼作产品说明书与验收对照表）。
|
||||
|
||||
---
|
||||
|
||||
## 7. 本机环境已知坑（踩过，别再踩）
|
||||
|
||||
1. **系统代理会拦截 `127.0.0.1` 的自测请求。**
|
||||
`Invoke-WebRequest http://127.0.0.1:4000/api/health` 会返回**别人的 404**（响应带 `Alt-Svc: h3=…`、空 body），
|
||||
看起来像后端路由没挂上。实际是走了代理。自测请加 `-NoProxy`（`curl.exe` 用 `--noproxy '*'`）。
|
||||
项目内的 Node 脚本（`verify:*`）直连，不受影响。
|
||||
**同一个坑对 ClassIsland 插件同样成立**：.NET 的 `HttpClient` 默认跟随系统代理，
|
||||
教室机器上表现为"填好令牌后立刻 HTTP 404"（其实是代理的错误页）。插件里
|
||||
`ClassHelperClient` 用 `LocalAwareProxy` 对本地/内网地址强制直连，
|
||||
`verify:classisland-plugin` 有 4 项断言盯着这段逻辑，别删。
|
||||
2. **`db:deploy` 只在 `packages/server` 包里，根 `package.json` 没有这个脚本。**
|
||||
根上跑 `pnpm db:deploy` 会报 `Command "db:deploy" not found`（还会附带一句莫名其妙的
|
||||
`文件名、目录名或卷标语法不正确。`）。正确写法：`pnpm --filter @classhelper/server db:deploy`。
|
||||
根上只有 `db:generate / db:migrate / db:seed / db:reset / db:studio`。
|
||||
3. **`pnpm db:migrate`（= `prisma migrate dev`）在本机不可靠**：首次报 `Schema engine error:`（空消息），
|
||||
数据库建好后再跑会**长时间挂起**（无输出，需手动结束进程）。日常用 `db:deploy`；
|
||||
要写种子直接 `pnpm db:seed`，或 `node ./node_modules/tsx/dist/cli.mjs prisma/seed.ts`（cwd 为 `packages/server`）。
|
||||
4. **先 `pnpm build:shared`，否则后面全崩**：`packages/shared/dist` 不存在时，`pnpm db:seed` 与任何
|
||||
消费 `@classhelper/shared` 的进程都会 `ERR_MODULE_NOT_FOUND`（报错指向
|
||||
`packages/server/node_modules/@classhelper/shared/dist/index.js`）。`pnpm dev*` / `build` / `typecheck`
|
||||
脚本已内联 `build:shared`，单独跑 `db:seed` 时记得自己先构建。
|
||||
5. **Electron 二进制要手动装**：`pnpm install` 实测**不会**下载它（`allowBuilds` 里虽然写了 `electron: true`，
|
||||
但 postinstall 没跑；日志里只看到 esbuild / prisma）。缺失时 `pnpm dev:desktop` / `verify:desktop` /
|
||||
`verify:web` / `dist:win` 全部失败。装法（本机已装好）：
|
||||
|
||||
```bash
|
||||
cd node_modules/.pnpm/electron@44.3.0/node_modules/electron
|
||||
ELECTRON_MIRROR=https://cdn.npmmirror.com/binaries/electron/ NODE_OPTIONS=--use-system-ca node install.js
|
||||
```
|
||||
|
||||
6. **"AI 会话里启动 Electron GUI 会崩"是一个误诊 —— 真凶是下一条的 Low 完整性标签。**
|
||||
2026-09-30 实测：把 Electron 发行目录的标签从 Low 改成 Medium 后，同一个 `electron.exe`
|
||||
在 AI 会话里**正常启动**（窗口标题 `Electron`、userData 目录正常创建），
|
||||
`pnpm verify:packaged` 也能完整跑完并出结果（86/90、77/78）。
|
||||
⇒ `verify:desktop` / `verify:web` / `verify:packaged` / `dist:win` 在 AI 会话里**都能跑**；
|
||||
一旦它们又"启动即崩"，先按第 7 条查完整性标签，别急着甩锅给"会话环境"。
|
||||
7. **交付物被打了 Low 完整性标签 ⇒ 客户端装不上、便捷版双击没反应、应用 0x80000003 秒崩。**
|
||||
症状极易误判：`electron.exe --version` 都不打印就退出（0x80000003 STATUS_BREAKPOINT），
|
||||
加 `--no-sandbox` 变成 0xC0000005，任何日志都写不出来（崩在日志初始化之前），
|
||||
但 `ELECTRON_RUN_AS_NODE=1` 跑同一个 exe 完全正常、Edge 等系统 Chromium 也正常。
|
||||
根因：**本仓库目录树被宿主沙箱打上了 `Mandatory Label\Low Mandatory Level:(OI)(CI)`（可继承）**，
|
||||
于是仓库内构建出的一切都继承 Low 标签。后果是双重的：
|
||||
- Windows 会把带 Low 标签的 exe **降级到 Low 完整性运行**：`setup.exe` 写不进 `%LOCALAPPDATA%`
|
||||
（报"拒绝访问"→ 用户看到"装不上"）、便捷版解不出 `%TEMP%`（→ 双击没反应）；
|
||||
- 即便装上了，落在 Low 标签目录里的应用文件也**读不了** —— Chromium 的 GPU/渲染子进程跑在
|
||||
AppContainer（更低完整性）里，按"不能向上读"直接秒崩。
|
||||
|
||||
判据与修法（都是实测过的）：
|
||||
|
||||
```bash
|
||||
# 判据：看交付物（以及 node_modules/electron/dist）有没有 Low 标签
|
||||
icacls packages\desktop-client\release\win-unpacked\班级小助手.exe | findstr Mandatory
|
||||
# 修法：把交付物改成 Medium。dist-win.mjs 收尾会自动做，手工补救用：
|
||||
icacls packages\desktop-client\release /setintegritylevel Medium /T /C
|
||||
# 目录自身要还原成继承，否则下次构建时自带 Low 标签的 7za / makensis 写不进去
|
||||
icacls packages\desktop-client\release /setintegritylevel "(OI)(CI)Low"
|
||||
```
|
||||
|
||||
连带的三条经验：**归档内部的载荷标签无所谓**（装到仓库外得到的是默认 Medium 文件），
|
||||
所以修标签必须在**打包完成之后**做，打包前改 appOutDir 反而会让 7za 读不到而失败；
|
||||
**别把安装测试装进仓库树**（`install-test` 之类），那里的文件又会继承 Low；
|
||||
**覆盖已存在的产物会被沙箱 ACL 拒绝**（`Can't open output file` / `拒绝访问`），
|
||||
`dist-win.mjs` 因此会先清掉上一轮的 `*.exe / *.7z / *.blockmap` 再打包。
|
||||
|
||||
8. **.NET 8 SDK 已装（8.0.425）**，`pnpm build:classisland-plugin` / `pnpm dist:classisland-plugin` 都能跑
|
||||
（2026-09-30 实测：`-t:Rebuild` 全量编译 8.8s，**1 个警告 0 个错误**；`.cipx` 打包成功，
|
||||
包内 DLL 的 sha256 与 `bin/Release` 产物一致）。脚本会自动把
|
||||
`NUGET_PACKAGES / TEMP / TMP / DOTNET_CLI_HOME` 指到仓库内 `.cache/`（`dotnet` 默认往 C 盘写，
|
||||
C 盘紧张时会构建失败）；手敲 `dotnet build` 时请自己带上这几个变量。
|
||||
|
||||
两个容易自我欺骗的地方：
|
||||
- **光看输出会误判"编译通过"**：源码没变时 `dotnet build` 是**空转**（打印
|
||||
`所有项目均是最新的，无法还原` + `已成功生成 / 0 警告 0 错误`），`CoreCompile` 根本没执行 ——
|
||||
那行 `ClassHelper.ClassIslandPlugin -> …dll` 是拷贝回执，不是编译证据。
|
||||
要证明"真的编译过"，用 `node packages/classisland-plugin/scripts/build.mjs -t:Rebuild -v:n`
|
||||
看有没有 `csc.dll` 调用，并核对 DLL 的 mtime 晚于所有 `.cs`。
|
||||
- **那 1 个警告是预期的，别去"修"**：`AVLN3001: XAML resource
|
||||
"…/BridgeSettingsPage.axaml" won't be reachable via runtime loader, as no public constructor was found`
|
||||
—— 设置页只有 `BridgeSettingsPage(PluginSettings, BridgeService)` 这个 DI 构造函数、
|
||||
没有公开无参构造，Avalonia 于是警告它无法走**运行时**加载器；本插件走的是编译期 XAML +
|
||||
ClassIsland 的 DI 实例化，加个无参构造反而会把 DI 弄坏。
|
||||
|
||||
9. **`.cipx` 打包最后一步要 PowerShell**：SDK 的 `CreateCipx` 目标默认调 `pwsh`，
|
||||
本机 PATH 里没有 pwsh 时会失败。构建脚本会探测并把结果透传给 MSBuild
|
||||
（`-p:PowershellBinaryName=…`），直接跑 `dotnet build -p:CreateCipx=true` 则要自己加。
|
||||
10. **仓库根 `.gitignore` 的第 42 行是 GBK 编码**（整文件 CRLF，只有那一行是 GBK 注释），
|
||||
`apply_patch` 与 Prettier 都读不了它，按 UTF-8 读会看到 `\uFFFD`。要补忽略规则**只能用追加的方式**
|
||||
（`printf 'xxx\n' >> .gitignore`，原有字节一个都别动），别试图整文件重写；临时性的可写
|
||||
`.git/info/exclude`（本地生效、不入库）。
|
||||
（`packages/classisland-plugin/.gitignore` 是本仓库里唯一能正常编辑的 .gitignore。）
|
||||
11. **`releases/`（复数）必须在 ESLint 忽略列表里**：本地跑过 `pnpm dist:*` 之后，
|
||||
这个目录里是构建后的压缩 JS，不忽略的话 `pnpm lint` 会报出几千条与源码无关的 error
|
||||
（`eslint.config.mjs` 里已补 `**/releases/**`，别再删掉；`release-server/` 同理）。
|
||||
**它一度只在 ESLint 里被忽略、`.gitignore` 里漏了**（后者只有单数的 `release/` 和 `release-server/`）：
|
||||
归集一次客户端产物就有 225MB 的 EXE 变成未跟踪文件，`git add -A` 会直接把安装包提交入库。
|
||||
2026-09-30 已在 `.gitignore` 末尾补上 `releases/`。
|
||||
12. **ClassIsland 的数据根是 `D:\Classisland\data`**（**不是**旧文档写的 `F:\data`，F 盘已不存在）：
|
||||
- 插件 DLL 覆盖到 `D:\Classisland\data\Plugins\classhelper.classisland.bridge\`（**ClassIsland 运行时会锁住
|
||||
DLL，必须先退出它再覆盖**：`Get-Process ClassIsland.Desktop | Stop-Process -Force`）；
|
||||
- 插件配置在 `D:\Classisland\data\Config\Plugins\<id>\Settings.json`，**ClassIsland 运行中改会被内存里的
|
||||
副本随时回写覆盖**，要改请趁它退出时改；该文件里存着这台机器的服务器地址与设备令牌，**别覆盖**；
|
||||
- 改完 DLL 或配置都要重启 ClassIsland，否则跑的还是旧副本。
|
||||
13. **读 ClassIsland 控制台日志要用 GBK**：`.NET` 的控制台输出是**系统 ANSI（GBK）**编码，
|
||||
用 `-Encoding UTF8` 读会变成乱码、**中文关键字一条都搜不到**（只能搜到 ASCII 的类名）。
|
||||
正确姿势：`[System.IO.File]::ReadAllLines($path, [System.Text.Encoding]::GetEncoding(936))`；
|
||||
日志文件被运行中的进程占用时先 `Copy-Item` 一份再读。
|
||||
14. **服务端改了代码要重启才生效**（`tsx src/index.ts` 不热载，`pnpm dev:server` 才有 watch）。
|
||||
验证脚本报「某个断言突然不对」时，先确认后端跑的是不是最新代码 —— 这个坑踩过一次。
|
||||
15. **后端启动时才发现 Web 产物**：`packages/web-admin/dist` 不存在就跳过静态托管，`http://127.0.0.1:4000/`
|
||||
只会返回服务首页（文案「Web 管理端未随本服务托管」）。要跑 `verify:web`，先 `pnpm build` 再重启后端。
|
||||
16. **打包版服务端有生产自检**：`NODE_ENV=production` 时拒绝 `dev.db`（"生产环境仍在使用 dev.db"）、
|
||||
拒绝短 `JWT_SECRET` 与示例密钥；想用演示数据跑打包版就把库**复制**成 `data/classhelper.db` 再启动。
|
||||
17. **makensis 建不了临时文件时，NSIS 那一步会失败（`dist:server` 与 `dist:win` 都会踩）。** 两种根因、
|
||||
同一个排查动作 —— 先把 `TEMP` 指到仓库内一个**真实存在的 Windows 绝对路径**再重试：
|
||||
- `pnpm dist:server` 报 `Internal compiler error #12345: error creating mmap the size of N`：模板用了
|
||||
`SetCompressor /SOLID lzma`，makensis 会在 **`%TEMP%` 所在的盘**建一个上百 MB 的 mmap 临时文件，盘紧就失败
|
||||
（免安装目录其实已生成好，只是最后一步打不出安装包）。加 `--reuse-deps` 还能跳过依赖安装。
|
||||
- `pnpm dist:win` 报 `!tempfile: Unable to create temporary file!` / `Error in macro _Switch`：**不是空间不足**，
|
||||
而是 Git Bash 里 `TEMP=TMP=/tmp` —— makensis 是原生程序，把 `/tmp` 当成「当前盘根下的 tmp」解析成
|
||||
`D:\tmp`，该目录不存在。`/c` 有 79G、`/d` 有 124G 也会照样失败（2026-09-30 实测）。
|
||||
`win-unpacked` 与 `release/*.nsis.7z` 此时都已生成，**只需重跑 electron-builder，不必重建前端**：
|
||||
|
||||
```bash
|
||||
mkdir -p .cache/tmp
|
||||
TEMP='D:\classhelper\.cache\tmp' TMP='D:\classhelper\.cache\tmp' \
|
||||
node packages/desktop-client/scripts/dist-win.mjs
|
||||
```
|
||||
18. **依赖二进制下载需要 `NODE_OPTIONS=--use-system-ca`**（本机 TLS 中间人证书），否则报
|
||||
`unable to verify the first certificate`。
|
||||
19. **Prisma 版本锁死 7.10.0**：npm `latest` 已指向 8.x；生成器是 `prisma-client`，输出到
|
||||
`src/generated/prisma`（gitignored），连接串在 `prisma.config.ts`，并且**必须走 driver adapter**
|
||||
（`@prisma/adapter-libsql` + 预编译的 `@libsql/win32-x64-msvc`，避开 electron ABI 的原生编译坑）。
|
||||
20. **服务端安装包里的 `.cmd` 提示是英文**：cmd.exe 按 GBK 解析脚本，中文会乱码，属有意为之
|
||||
（中文在安装向导与 `README.txt`）。
|
||||
21. **`pnpm format:check` 在 master 基线上本来就是失败的**（含 `tsconfig.base.json` 与 `scripts/*`），
|
||||
不要拿它当门禁、也不要为了让它变绿去批量格式化。只检查你改过的文件：
|
||||
`pnpm exec prettier --check <file>`。
|
||||
**注意它会因为 CRLF 而"全面误报"**：`core.autocrlf=true` 让 git 里存 LF、工作区签出成 CRLF，
|
||||
而 Prettier 配的是 `endOfLine: lf`，于是几乎每个文件都被标红。要判断是不是**你的**代码不合风格，
|
||||
用 `sed 's/\r$//' <file> | pnpm exec prettier --check --stdin-filepath <file>`。
|
||||
22. **写冒烟断言时别用"元素还在不在"判断 Element Plus 的弹框关没关。** `el-dialog` 关闭后
|
||||
**DOM 会留在文档里**（Element Plus 只把 `.el-overlay` 置成 `display: none`），
|
||||
`document.querySelector('.el-dialog')` 恒为真 —— `verify:desktop` / `verify:packaged` 里
|
||||
「设置页『修改密码』对话框取消后未关闭」就是这么误报出来的。正确判据：
|
||||
`getComputedStyle(dialog.closest('.el-overlay')).display !== 'none'`。
|
||||
同理，断言岛体尺寸别写死"胶囊尺寸 + 留白"：那一刻是胶囊还是卡片取决于前面用例留下的状态，
|
||||
应改成**与形态无关的不变量**（如"窗口 = 卡片实测尺寸 + 2×阴影留白"）。
|
||||
|
||||
### 已知脆弱用例（不是环境问题，别去"修环境"）
|
||||
|
||||
| 用例 | 触发条件 |
|
||||
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `verify:e2e`「上课状态接口（at=周一 08:10）」 | 种子把「周一第 1 节」限制在第 1 周，且用例把 `2026-09-07` 当第 1 周。`TERM_START_DATE` 对齐到 `2026-09-07` 即全绿（本机 `.env` 已这样配；`.env.example` 仍是 `2026-02-23`，重置 `.env` 时记得改回来） |
|
||||
| `verify:desktop`「课表今天时间轴」 | 凌晨约 00:00–03:00 时「已结束」探针被夹紧成 0 长度而被过滤，`已结束=false` 判定失败 |
|
||||
| `verify:web`「课表科目为全校统一目录」 | 种子给每个班建满了全部科目，下拉里没有可自动建课的「统一科目」分组 |
|
||||
| 岛交互 / 岛动画 / 岛截图留档这几个用例 | **AI 会话里会间歇性失败**：同一份产物连跑两次，失败项会在「点击展开 / 紧急展开动画 / 各状态截图留档」之间跳（2026-09-30 实测三轮结果各不相同）。根因是置顶透明小窗的 rAF 被限流、形变采样抓不到帧，属时序敏感；**先原样重跑一次再动手改代码**，别把偶发当成回归 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 交付前检查
|
||||
|
||||
```bash
|
||||
pnpm lint # ESLint（0 error 为底线）
|
||||
pnpm typecheck # 全仓库类型检查
|
||||
|
||||
pnpm dev:server # 另开终端
|
||||
pnpm verify:e2e # 后端端到端（2026-09-30 实测 173 项全过）
|
||||
pnpm verify:classisland # ClassIsland 联动链路（实测 42 项）
|
||||
pnpm verify:classisland-plugin # 插件静态契约（不需要后端，实测 68 项）
|
||||
pnpm build:desktop && pnpm verify:desktop # 客户端冒烟（AI 会话可跑，先看 §7 第 7 条）
|
||||
pnpm build && pnpm verify:web # Web 端真实点击回归（同上）
|
||||
```
|
||||
|
||||
条目数由脚本自行统计并打印（`=== 结果：N/N 项通过 ===`、`ClassIsland 联动插件静态校验：N/N 项通过`），
|
||||
文档不要写死容易过期的总数。
|
||||
|
||||
改动到 ClassIsland 插件时，额外跑 `pnpm dist:classisland-plugin` 确认能打出 `.cipx`；
|
||||
本机已装 ClassIsland 2.1.0.1（`D:\Classisland`）与 .NET 8 SDK（8.0.425），因此**真机验证是可行的**
|
||||
（直接 `pnpm build:classisland-plugin` 编译，再按 §7 第 12 条部署）：
|
||||
# AGENTS.md — ClassHelper（Class Helper）
|
||||
|
||||
本文件供本仓库的 AI 编码代理使用。先读这里，再改代码。当前工作目录为 `F:\ClassHelper`。
|
||||
现行规则按工作区源码维护；产品说明见 `docs/app/`，开发契约见 `docs/dev/`，部署见 `docs/management/`。
|
||||
查证路径见 `docs/reference.md`。文档与代码冲突时，阅读实现及其校验规则后同步修正文档，不沿用历史报告中的结论。
|
||||
|
||||
## 1. 项目与目录
|
||||
|
||||
pnpm monorepo，根 `package.json` 是版本单一来源。文档、注释、界面文案及提交描述使用中文。
|
||||
远端为 `LoveChengke/ClassHelper`，默认分支 `master`。
|
||||
|
||||
| 目录 | 用途 |
|
||||
| -------------------------- | --------------------------------------------------------- |
|
||||
| `packages/shared/src/` | 三端共享类型、权限、常量、动效、岛方案与课件契约 |
|
||||
| `packages/server/` | Express、Prisma、Socket.IO；API 前缀 `/api` |
|
||||
| `packages/web-admin/` | Vue Web 管理端，PWA |
|
||||
| `packages/desktop-client/` | Electron 主进程、preload、主窗口与独立灵动岛渲染进程 |
|
||||
| `scripts/` | 版本、构建、验证、打包、图标与 Pages 脚本 |
|
||||
| `deploy/` | Windows/Linux/Docker 部署与运维模板 |
|
||||
| `docs/` | docfx 文档；`images/` 为展示图，`screenshots/` 为回归截图 |
|
||||
| `website/` | 纯静态官网与下载页 |
|
||||
| `releases/` | 按组件和版本存放本地交付物，gitignored |
|
||||
|
||||
不要在文档中手抄模块、表、权限键、测试用例的总数；分别查注册表、schema、共享目录与本次验证输出。
|
||||
|
||||
## 2. 服务端与数据边界
|
||||
|
||||
- 模块由 `packages/server/src/modules/registry.ts` 注册；新增或下线功能改注册表，不另改 `app.ts` 挂载。
|
||||
- 路由用 `middleware/validate.ts` 与 zod；响应复用 `lib/http.ts`，错误交给统一中间件。
|
||||
- 学生是 `Student` 名单记录，没有账号、角色或密码。教师/管理员存 `User`；班级登录读取 `Class.code/passwordHash`，会话角色 `CLASS_DEVICE`，主体 id 为班级 id。
|
||||
- 任课关系只在 `Course(classId, name, teacherId)`。班主任不自动获得别的科目的作业、成绩写权限，统一走 `assertCanManageSubjectContent`。班级端可录作业，不可写成绩；员工还须对应功能权限。
|
||||
- 功能权限取 `lib/permissions.ts` 的 `loadEffectivePermissions()`：已分组取并集；未分组使用数据库对应角色的可编辑默认组；管理员永远保留 `permission:manage/system:manage`；班级端为空集。
|
||||
- 岗位组不新增 `User.role`。班主任/教师/级长/部长仍为 TEACHER；范围在 `PermissionGroup.scope/scopeValue`，由 `lib/permission-scope.ts` 收口，空年级/部范围拒绝。设备写权限只合并含对应键的分组范围，范围不替代科目授权。
|
||||
- 只有一份 `prisma/schema.prisma`，切库改 provider；保持 SQLite/MySQL 通用，不加 Prisma enum 或 `@db.*`。模型变动同步迁移、`lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 与旧库兼容逻辑。
|
||||
- `deleteTeacher` 必须保护班主任、课程任课、发布的作业/通知和所属课件，避免级联删除业务内容。
|
||||
- 作业和通知按本地 `assignDate` 归类，使用 `dayKeyLocal/isDayKey/shiftDayKey`，不用 UTC 日期切片。
|
||||
- 批量通知/作业逐班返回结果；跨班作业按科目名匹配既有课程，找不到则该班失败，不自动把发布者设为任课老师。
|
||||
- 两个登录接口共用登录限流。附件链接校验 scheme；表格文件上限 8 MB、JSON 请求体 12 MB，超限映射 413。
|
||||
- AI 助手只解析待确认动作，前端确认后调既有发布接口；参数重新校验，Key 加密存储且不回传。自动化用 mock，不访问外网。
|
||||
|
||||
## 3. 课表、周次、成绩与学年
|
||||
|
||||
- 课表真值是 `ClassPlan/ClassPlanEntry/TimeLayoutItem`；旧 `Schedule` 与 `TimeLayout.items` 保留迁移审计用途，不双写或回读复活旧业务。
|
||||
- `/api/schedules/*` 是新模型兼容门面。启用解析统一走 `lib/class-plan.ts`，在线客户端不得另写启用优先级。
|
||||
- 时间点有上课、课间、分割线、行动四种；课程显式引用时间点外键。排序不能靠数组下标代替关联。
|
||||
- 支持 1–9 周轮换、群组、预定及临时层；完整档案导入走 `profile-import.service.ts`，不经过单双周有损格式。
|
||||
- 全校时间表写入用 `timetable:manage`；班级日课表写入还须班主任/管理员断言。离线整套课表导入可建立班级自有作息，不把 JSON 的 TeacherName 当授权。
|
||||
- 周次统一 `loadTermContext/resolveCurrentWeek`：班级逐周区间优先于全校区间，缺省再线性推算。开学日会参考班级设置、第 1 周区间、全校设置与环境兜底，详见 `lib/term.ts`。
|
||||
- 全校周数上限存 `term.maxWeeks`，默认 30、范围 1–60；服务端 `getMaxTermWeeks()`，shared 做归一化与离线兜底。班级周数不超全校上限。
|
||||
- 关闭个人成绩查询后，班级端仍可看服务端集体聚合；个人明细、原始全班成绩和排名拒绝读取。稀疏样本及补集抑制，不下发原始成绩后在客户端聚合。
|
||||
- 总分开关属于 `Exam`；排名同学生同科取最高分，并列排名为 1、2、2、4。客户端只展示，不能修改成绩查询或考试配置。
|
||||
- 年度升级由 `term.promotionAt` 配置，`PromotionRun.year` 保证幂等，升级前保存快照。运行期到点自动执行，启动漏跑先预览补跑；开发机启动不得擅自升级业务数据。
|
||||
- 高三归档，其余升一级；新班仅建骨架，不复制班主任/任课关系。转出过滤复用 `lib/students.ts`，学号不复用，归档页保留历史与撤回转出。
|
||||
|
||||
## 4. 客户端、灵动岛与课件
|
||||
|
||||
- preload 仅暴露 contextBridge 白名单，不暴露 ipcRenderer；跨桥接传纯数据，不传 Vue Proxy。契约写在 `src/types/desktop.d.ts`。
|
||||
- 保留 CSP、导航同源校验与弹窗限制。安装包不能含凭据，保留 `check-bundle-secrets` 构建门禁。
|
||||
- 离线缓存按服务端与班级隔离，缓存故障不应阻断在线读取。退出、切服务器时清理会话状态，设备 `deviceKey` 保持不变，渲染层不能改写它。
|
||||
- 设备维护只走 `/api/clients/*`，管理页 `ClientsView.vue`。心跳约 30 秒，90 秒窗口判在线；未登录不报，401/403 退避，切配置重置计时并隔离迟到响应。
|
||||
- 远控须 `remote:control`，只允许 shutdown/restart/logoff/lock，客户端立即执行、持久去重并回执。冒烟始终假执行，不得真关机/重启/注销/锁屏。
|
||||
- 更新写入口用 `client:update`；服务端缓存包并登记 SHA256，教室机从本服务下载；无哈希拒收，按立即/放学后/空闲策略执行，关闭自动更新不得强装。冒烟不运行安装器。
|
||||
- 灵动岛方案保存在本机 `config.json.islandLayout`，默认 `layout=fixed`；`custom` 当前即常驻模式，旧 `residentEnabled` 是兼容字段。新尺寸上报仅在 custom 模式执行。
|
||||
- `LayoutIslandApp.vue` 选择经典 `IslandApp.vue` 或 `CustomIslandRuntime.vue`，共用一个原生岛窗口；课件传输状态优先显示 `CoursewareTransfer.vue`。
|
||||
- 经典模式：普通通知/作业上课暂存；普通叫人保留可点击胶囊；紧急消息立即展开。自定义常驻模式：消息先提示铃铛数量，用户主动展开；上课也可主动查看。不要把两个模式规则混写。
|
||||
- 自定义方案的常态 `rows` 与无消息展开 `expandedRows` 分开编辑。课程、时钟、容器等使用 shared 组件契约；测量自然内容并按工作区约束适配。
|
||||
- 保留经典岛连续圆角、投影常驻、触摸输入、失焦宽限与固定窗口几何护栏。不要调用 `setBackgroundMaterial()` 破坏逐像素透明。左右边距仅左/右停靠生效。
|
||||
- 消息按 id 去重，通知/叫人双播不得重复；列表布局复用 shared 度量。崩溃恢复保持限流，冒烟不得自重启。
|
||||
- 课件权限和任课范围独立校验：拥有文件、文件可见范围与本人授课班级共同约束推送，岗位范围不代替任课授权。
|
||||
- 课件最大 512 MB，流式收发、临时文件、SHA256 校验；客户端不自动运行文件，每设备独立回执。JSON 快照只含元数据，完整备份另带文件目录。
|
||||
|
||||
## 5. 实时、界面与资源
|
||||
|
||||
- 事件名与房间名取 shared 常量。业务用 `emitToClass/emitToSession`，不直接依赖 Socket.IO 实例。
|
||||
- 会话房间为 `session:{id}`；教师/管理员 id 为账号 id，班级端为班级 id。`students` 是班级端广播房间，不是个人学生账号房间。
|
||||
- 新实时事件同步服务端、Web 订阅、客户端订阅。成绩实时载荷不可泄漏个人成绩。
|
||||
- Web 菜单分组在 `config/navigation.ts`，标题/图标/权限取路由；守卫与服务端都检查权限，前端隐藏不能代替鉴权。
|
||||
- 侧栏折叠用 CSS 保持 DOM，关怀模式放大字号/控件，不改变几何令牌。使用语义色，动效统一 shared 令牌；图标新增后检查注册表。
|
||||
- 图标源是 `build/classhelper.png` 与设计导出的 `.ico`，`pnpm icons` 派生其余资源。ICO 原样透传，客户端兜底 `build/icon.*` 同步保留。
|
||||
- Web 品牌图用 `/logo.png`，客户端用 `BRAND_LOGO_URL`，避免 file:// 绝对路径问题。
|
||||
- 官网和文档站共用一个 Pages 站点，`scripts/build-pages.mjs` 拼装根站与 `/docs/`；文档不写指向 docs 树外的相对链接，源码用 GitHub 绝对链接。
|
||||
- 展示图引用 `docs/images/`，回归图放 `docs/screenshots/`。官网 `.reveal-grad` 不拆逐字节点，动效改 token 表。
|
||||
- ClassIsland 联动插件、设备令牌、提醒渠道与镜像接口已退役；保留离线 JSON 导入和设计参考，不恢复在线联动依赖。
|
||||
|
||||
## 6. 本机命令与验证
|
||||
|
||||
脚本以根/各包 `package.json` 为准；端口：后端 4000，Web dev 5173，客户端 dev 5174，官网 5180，文档 5181。
|
||||
先构建 shared 再启动下游。新环境按需执行 install → db:generate → server db:deploy → build:shared；`db:seed/db:reset` 会清业务表，只用于明确选择的演示/隔离库。
|
||||
|
||||
本机 Node 路径为 `D:\Node.js\node.exe`。受限终端的 pnpm 可能解析到运行时兜底版本，先看 `Get-Command pnpm` 与 `pnpm --version`。
|
||||
仓库锁定 pnpm 11.8.0，可用 `C:\Users\hck16\AppData\Local\node\corepack\v1\pnpm\11.8.0\bin\pnpm.cjs`。
|
||||
经 DSH 转发壳时可设置：
|
||||
|
||||
```powershell
|
||||
# 1) 退出 ClassIsland（DLL 被占用时无法覆盖）→ 2) 覆盖插件 → 3) 重新启动
|
||||
Get-Process ClassIsland.Desktop | Stop-Process -Force
|
||||
Copy-Item packages\classisland-plugin\bin\Release\ClassHelper.ClassIslandPlugin.dll D:\Classisland\data\Plugins\classhelper.classisland.bridge\ -Force
|
||||
Start-Process D:\Classisland\ClassIsland.exe -WorkingDirectory D:\Classisland
|
||||
# 4) 在 Web 端「ClassIsland 联动」发一条提醒，看日志里依次出现：
|
||||
# 取到待弹出提醒 → 已弹出提醒 →（播完）已确认提醒
|
||||
$env:PATH = 'C:\Users\hck16\AppData\Local\deepseek-harness\bin;' + $env:PATH
|
||||
$env:DSH_NODE = 'D:\Node.js\node.exe'
|
||||
$env:DSH_PNPM_BIN = 'C:\Users\hck16\AppData\Local\node\corepack\v1\pnpm\11.8.0\bin\pnpm.cjs'
|
||||
Remove-Item Env:DSH_PNPM -ErrorAction SilentlyContinue
|
||||
pnpm --version
|
||||
```
|
||||
|
||||
交付时要说明"编译 / 打包 / 静态契约已过，运行期需在装了 ClassIsland 的机器上实测"。
|
||||
受限 electron-builder 调 pnpm list 曾报 `ERR_SQLITE_ERROR`，这是进程访问限制，不据此认定依赖缺失。
|
||||
Prisma 使用 driver adapter；本机优先应用已有迁移，不用 `migrate dev` 排查 Windows 初始化问题。
|
||||
本地 HTTP 探测绕过代理；运行中数据库及 WAL/SHM 不按临时文件清理。
|
||||
|
||||
改动涉及打包/交付形态时，额外跑 `pnpm dist:all`（或 `dist:server` + `dist:win`），
|
||||
并用 `pnpm verify:packaged --exe "<客户端路径>"` 对**打包后的副本**复验 ——
|
||||
开发产物通过不等于用户机器上的副本通过。
|
||||
| 命令 | 范围 |
|
||||
| ----------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| `pnpm lint` / `pnpm typecheck` / `pnpm check:icons` | 代码静态门禁；按改动范围执行 |
|
||||
| `pnpm docs:check` | 文档严格构建，警告即失败 |
|
||||
| `pnpm verify:e2e` | 自动创建临时 SQLite 和账号，无需先开开发服务，禁止外网 |
|
||||
| `pnpm verify:web:isolated` | 构建 Web 后运行隔离服务和隐藏 UI 回归 |
|
||||
| `pnpm verify:courseware` / `pnpm verify:v14` | 课件/课表等隔离专项 |
|
||||
| `pnpm verify:desktop` / `pnpm verify:packaged --exe <路径>` | 默认后台快速检查，不创建可见岛或托盘 |
|
||||
| `pnpm verify:desktop:online` | 显式联网，使用临时教师和班级 |
|
||||
| `pnpm verify:desktop:visual` / packaged 的 `--visual` | 显式视觉模式，动画、透明度、截图；会使用桌面 |
|
||||
|
||||
自测本地接口记得绕过代理（见 §7 第 1 条）。
|
||||
禁止为验收回退到真实班级、重置其密码或发送测试通知。验收数量只记录本次实际输出。
|
||||
仅文档修改做格式、链接、构建检查，不为此反复占用桌面或重打安装包。
|
||||
Prettier 用 LF，只格式化本次改动；不要为旧基线批量格式化源码。
|
||||
改 Linux 交付脚本还要 bash 语法检查和 Linux 真机/CI 验证；改打包逻辑需打包后副本复验。
|
||||
|
||||
## 7. 发布与工作区清理
|
||||
|
||||
- 版本只由 `scripts/version.mjs` 修改；日常维护不涨版，指定固定版本重构建时保持该版本。发布流程见 `docs/dev/release.md`。
|
||||
- 本地 `pnpm dist:all` 产出 Windows 服务端和客户端；Linux 正式包由 `release-linux-server.yml` 在 Linux runner 构建，非 Linux 交叉构建仅供验证。
|
||||
- 本地文件名与 Release 的 ASCII 上传名不同，校验清单应明确映射；保留当前版本清单、更新日志及最新包。
|
||||
- `releases/` 只放交付物及少量构建信息，不留 win-unpacked、服务端 staging、解包副本；staging 在 `.cache/server-staging/`，成功后脚本删除。
|
||||
- 2026-10-18 按用户要求清除 1.4.0 旧重构建归档，只保留 `client/1.4.0`、`server/1.4.0` 与当前清单/说明。以后同号重构建可临时留回滚副本，最新包验证完成且用户要求清理时再删除。
|
||||
- 递归删除/移动前核实绝对路径在指定工作区，禁止误删源代码、真实数据库、配置、凭据、工具缓存或其他版本交付物。
|
||||
- 不清理 `node_modules`、`.pnpm-store`、`.cache/{nuget,npm-cache,dotnet-home,mingit}`、`packages/*/dist`、生成的 Prisma Client，除非任务明确要求。
|
||||
- 保留已有未提交工作；提交前查看 diff，中文 Conventional Commits 描述。只有用户要求发布/同步时才执行远端发布链。
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 422 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 109 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 264 KiB |
+2
-2
@@ -7,7 +7,7 @@
|
||||
SERVER_PORT=4000
|
||||
|
||||
# 应用版本（镜像标签）
|
||||
APP_VERSION=1.0.0
|
||||
APP_VERSION=1.1.2
|
||||
|
||||
# MySQL 配置
|
||||
MYSQL_ROOT_PASSWORD=请改成强密码_root
|
||||
@@ -31,7 +31,7 @@ INITIAL_ADMIN_USERNAME=admin
|
||||
INITIAL_ADMIN_PASSWORD=admin123
|
||||
|
||||
# 各类账号的默认初始密码（新增/重置时使用）
|
||||
DEFAULT_STUDENT_PASSWORD=123456
|
||||
|
||||
DEFAULT_CLASS_PASSWORD=123456
|
||||
DEFAULT_TEACHER_PASSWORD=123456
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
SERVER_PORT=4000
|
||||
|
||||
# 应用版本（镜像标签）
|
||||
APP_VERSION=1.0.0
|
||||
APP_VERSION=1.1.2
|
||||
|
||||
# JWT 签名密钥（必填，必须 ≥32 位；不能包含 secret / change-me 等示例词）
|
||||
# 生成：node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
|
||||
@@ -25,7 +25,7 @@ INITIAL_ADMIN_USERNAME=admin
|
||||
INITIAL_ADMIN_PASSWORD=admin123
|
||||
|
||||
# 各类账号的默认初始密码（新增/重置时使用）
|
||||
DEFAULT_STUDENT_PASSWORD=123456
|
||||
|
||||
DEFAULT_CLASS_PASSWORD=123456
|
||||
DEFAULT_TEACHER_PASSWORD=123456
|
||||
|
||||
|
||||
+3
-3
@@ -1,17 +1,17 @@
|
||||
# 班级小助手服务端 · 生产镜像
|
||||
# ClassHelper 服务端 · 生产镜像
|
||||
#
|
||||
# 两阶段构建：
|
||||
# build —— 安装依赖并编译 shared / server / web-admin
|
||||
# runtime —— 仅保留运行时所需内容（生产依赖 + 构建产物），镜像更小
|
||||
#
|
||||
# 构建（在仓库根目录执行）：
|
||||
# docker build -f deploy/Dockerfile -t classhelper-server:1.0.0 .
|
||||
# docker build -f deploy/Dockerfile -t classhelper-server:1.1.0 .
|
||||
#
|
||||
# 运行（SQLite + 数据卷）：
|
||||
# docker run -d --name classhelper -p 4000:4000 \
|
||||
# -e JWT_SECRET=<48字节随机串> \
|
||||
# -v classhelper-data:/app/data \
|
||||
# classhelper-server:1.0.0
|
||||
# classhelper-server:1.1.0
|
||||
#
|
||||
# 生产推荐用 docker compose（见 deploy/docker-compose.yml，含 MySQL 与 HTTPS 反代）
|
||||
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
# ---------------------------------------------------------------------------
|
||||
# 班级小助手服务端 · 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
+41
-15
@@ -1,24 +1,33 @@
|
||||
# ---------------------------------------------------------------------------
|
||||
# 班级小助手 · 服务端 systemd 单元（Linux）
|
||||
#
|
||||
# 这是**模板**：deploy/install-linux.sh 会把 __NODE__ / __DIR__ / __USER__ 替换成真实值后
|
||||
# 安装到 /etc/systemd/system/classhelper.service。手动部署时直接改这三处即可：
|
||||
# 这是**模板**：`deploy/install.sh` 会把占位符替换成真实值后安装到
|
||||
# /etc/systemd/system/classhelper.service。手动部署时照着替换这四处即可：
|
||||
#
|
||||
# sudo sed -e 's#__NODE__#/usr/bin/node#' \
|
||||
# __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#' \
|
||||
# deploy/classhelper.service | sudo tee /etc/systemd/system/classhelper.service
|
||||
# -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 # 实时日志
|
||||
# systemctl restart classhelper # 重启（改完 .env 需要）
|
||||
# journalctl -u classhelper -f
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
[Unit]
|
||||
Description=ClassHelper Server (班级小助手服务端)
|
||||
Documentation=file://__DIR__/README.txt
|
||||
Documentation=https://github.com/LoveChengke/ClassHelper
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
@@ -27,15 +36,18 @@ Type=simple
|
||||
User=__USER__
|
||||
Group=__USER__
|
||||
WorkingDirectory=__DIR__
|
||||
# .env 由服务端自己从 WorkingDirectory 加载（工作目录即安装根目录）
|
||||
|
||||
# 配置从这里注入（唯一的配置真身；安装目录里的 .env 是指向它的软链，见 docs/linux-deploy.md）。
|
||||
# systemd 会剥掉值两侧的引号，所以同一份文件给 dotenv / shell source / systemd 三种读法都能用。
|
||||
# 前面不加 "-"：文件被删掉时直接启动失败，比拿着一份假配置跑起来更容易发现。
|
||||
EnvironmentFile=__CONFIG__
|
||||
ExecStart=__NODE__ server/dist/index.js
|
||||
Environment=NODE_ENV=production
|
||||
|
||||
Restart=always
|
||||
RestartSec=3
|
||||
# Socket.IO 长连接较多：提高文件描述符上限
|
||||
LimitNOFILE=65535
|
||||
# 优雅退出：给在途请求与 websocket 收尾时间
|
||||
# 优雅退出：给在途请求与 websocket 收尾时间（index.ts 处理 SIGTERM/SIGINT）
|
||||
KillSignal=SIGTERM
|
||||
TimeoutStopSec=20
|
||||
|
||||
@@ -44,12 +56,26 @@ StandardOutput=journal
|
||||
StandardError=journal
|
||||
SyslogIdentifier=classhelper
|
||||
|
||||
# 基础加固（服务只需要读程序、写 data/logs）
|
||||
NoNewPrivileges=true
|
||||
PrivateTmp=true
|
||||
# ---------------------------------------------------------------- 加固
|
||||
# 为什么 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
|
||||
ReadWritePaths=__DIR__/data __DIR__/logs
|
||||
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,4 +1,4 @@
|
||||
# 班级小助手 · Docker 单容器部署（SQLite + 数据卷）
|
||||
# ClassHelper · Docker 单容器部署（SQLite + 数据卷）
|
||||
#
|
||||
# 适用：云服务器 / 与别的服务共用一台机器。相比 deploy/docker-compose.yml（MySQL 变体）
|
||||
# 少跑一个数据库容器，内存占用小很多；数据落在 Docker 卷 classhelper-data 里。
|
||||
@@ -23,7 +23,7 @@ services:
|
||||
context: ..
|
||||
dockerfile: deploy/Dockerfile
|
||||
target: runtime
|
||||
image: classhelper-server:${APP_VERSION:-1.0.0}
|
||||
image: classhelper-server:${APP_VERSION:-1.4.1}
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
NODE_ENV: production
|
||||
@@ -44,7 +44,7 @@ services:
|
||||
TERM_START_DATE: ${TERM_START_DATE:-}
|
||||
INITIAL_ADMIN_USERNAME: ${INITIAL_ADMIN_USERNAME:-admin}
|
||||
INITIAL_ADMIN_PASSWORD: ${INITIAL_ADMIN_PASSWORD:-admin123}
|
||||
DEFAULT_STUDENT_PASSWORD: ${DEFAULT_STUDENT_PASSWORD:-123456}
|
||||
|
||||
DEFAULT_CLASS_PASSWORD: ${DEFAULT_CLASS_PASSWORD:-123456}
|
||||
DEFAULT_TEACHER_PASSWORD: ${DEFAULT_TEACHER_PASSWORD:-123456}
|
||||
ports:
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# 班级小助手 · 生产部署（MySQL + 服务端 + 可选 HTTPS 反代）
|
||||
# ClassHelper · 生产部署（MySQL + 服务端 + 可选 HTTPS 反代）
|
||||
#
|
||||
# 使用：
|
||||
# 1) 复制环境变量模板并填写密钥：cp deploy/.env.example deploy/.env
|
||||
@@ -45,7 +45,7 @@ services:
|
||||
environment:
|
||||
DATABASE_PROVIDER: mysql
|
||||
DATABASE_URL: mysql://${MYSQL_USER:-classhelper}:${MYSQL_PASSWORD}@db:3306/${MYSQL_DATABASE:-classhelper}
|
||||
# MySQL 需要 mariadb 驱动适配器（切换数据库时按 docs/mysql.md 安装）
|
||||
# MySQL 需要 mariadb 驱动适配器（切换数据库时按 docs/management/mysql.md 安装）
|
||||
NODE_ENV: production
|
||||
command: >
|
||||
sh -c "pnpm --filter @classhelper/server add @prisma/adapter-mariadb &&
|
||||
@@ -60,7 +60,7 @@ services:
|
||||
context: ..
|
||||
dockerfile: deploy/Dockerfile
|
||||
target: runtime
|
||||
image: classhelper-server:${APP_VERSION:-1.0.0}
|
||||
image: classhelper-server:${APP_VERSION:-1.4.1}
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
NODE_ENV: production
|
||||
@@ -78,11 +78,13 @@ services:
|
||||
TERM_START_DATE: ${TERM_START_DATE:-}
|
||||
INITIAL_ADMIN_USERNAME: ${INITIAL_ADMIN_USERNAME:-admin}
|
||||
INITIAL_ADMIN_PASSWORD: ${INITIAL_ADMIN_PASSWORD:-admin123}
|
||||
DEFAULT_STUDENT_PASSWORD: ${DEFAULT_STUDENT_PASSWORD:-123456}
|
||||
|
||||
DEFAULT_CLASS_PASSWORD: ${DEFAULT_CLASS_PASSWORD:-123456}
|
||||
DEFAULT_TEACHER_PASSWORD: ${DEFAULT_TEACHER_PASSWORD:-123456}
|
||||
ports:
|
||||
- '${SERVER_PORT:-4000}:4000'
|
||||
volumes:
|
||||
- server-data:/app/data
|
||||
depends_on:
|
||||
db: { condition: service_healthy }
|
||||
migrate: { condition: service_completed_successfully }
|
||||
@@ -93,4 +95,5 @@ networks:
|
||||
driver: bridge
|
||||
|
||||
volumes:
|
||||
server-data:
|
||||
db-data:
|
||||
+9
-274
@@ -1,279 +1,14 @@
|
||||
#!/usr/bin/env bash
|
||||
# ---------------------------------------------------------------------------
|
||||
# 班级小助手 · 服务端 Linux 一键部署（systemd + SQLite，单机单实例）
|
||||
# 兼容壳：早期文档、脚本与 README 里写的是 deploy/install-linux.sh，
|
||||
# 现在安装器统一在 deploy/install.sh（避免两份实现漂移）。
|
||||
#
|
||||
# 干什么：
|
||||
# 在 Linux 服务器上把服务端装成 systemd 服务，布局与已验证的 Windows 免安装目录完全一致：
|
||||
# /opt/classhelper/
|
||||
# ├── .env 全部配置（首次安装随机生成 JWT_SECRET）
|
||||
# ├── server/dist 后端程序（入口 index.js）
|
||||
# ├── server/prisma 迁移 SQL（AUTO_MIGRATE=true 时首启动自动执行）
|
||||
# ├── web/ Web 管理端（由后端托管，单端口 4000）
|
||||
# ├── node_modules/ 仅生产依赖（npm install --omit=dev）
|
||||
# ├── data/ classhelper.db + server.pid
|
||||
# └── logs/ 预留（日志默认进 journald）
|
||||
#
|
||||
# 前置条件：
|
||||
# - 在**仓库根目录**已执行过构建：pnpm build:shared && pnpm --filter @classhelper/server build \
|
||||
# && pnpm --filter @classhelper/web-admin build
|
||||
# - 目标机装好 Node.js ≥ 20.19（推荐 22 LTS）；本脚本不代装 Node
|
||||
#
|
||||
# 用法（在仓库根目录执行，需要 root）：
|
||||
# sudo bash deploy/install-linux.sh # 安装/升级，默认端口 4000、目录 /opt/classhelper
|
||||
# sudo bash deploy/install-linux.sh --port 8080 # 换端口
|
||||
# sudo bash deploy/install-linux.sh --dir /srv/classhelper
|
||||
# sudo bash deploy/install-linux.sh --no-service # 只铺文件，不装 systemd（自己接管进程）
|
||||
# bash deploy/install-linux.sh --check # 只体检（不需要 root）：校验构建产物/Node 版本/端口探针
|
||||
# sudo bash deploy/install-linux.sh --uninstall # 停止并禁用服务（保留 data 与 .env）
|
||||
#
|
||||
# 升级：把新代码构建好后**再跑一次同样的命令**即可。脚本不会覆盖已有 .env（JWT 密钥与端口保持
|
||||
# 不变，用户不用重新登录），只会补齐缺失项并覆盖程序文件。
|
||||
#
|
||||
# 注意：本脚本未在 Linux 实机验证过（开发机是 Windows，无 Docker/WSL 发行版）。
|
||||
# 它复用的是**已验证**的两套布局：Windows 免安装目录（install/ 结构）与 deploy/Dockerfile
|
||||
# 的 runtime 阶段（package.runtime.json + prisma/migrations + web/）。
|
||||
# 两者参数完全一致：
|
||||
# sudo bash deploy/install-linux.sh --port 8080
|
||||
# 等价于
|
||||
# sudo bash deploy/install.sh --port 8080
|
||||
# ---------------------------------------------------------------------------
|
||||
set -euo pipefail
|
||||
|
||||
TARGET_DIR="/opt/classhelper"
|
||||
SERVICE_USER="classhelper"
|
||||
PORT="4000"
|
||||
WITH_SERVICE=1
|
||||
UNINSTALL=0
|
||||
CHECK_ONLY=0
|
||||
SERVICE_NAME="classhelper"
|
||||
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--dir) TARGET_DIR="$2"; shift 2 ;;
|
||||
--port) PORT="$2"; shift 2 ;;
|
||||
--user) SERVICE_USER="$2"; shift 2 ;;
|
||||
--no-service) WITH_SERVICE=0; shift ;;
|
||||
--check) CHECK_ONLY=1; shift ;;
|
||||
--uninstall) UNINSTALL=1; shift ;;
|
||||
-h|--help) sed -n '2,40p' "$0"; exit 0 ;;
|
||||
*) echo "未知参数：$1（用 --help 看用法）" >&2; exit 2 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
log() { printf '\033[32m[classhelper]\033[0m %s\n' "$*"; }
|
||||
warn() { printf '\033[33m[classhelper]\033[0m %s\n' "$*" >&2; }
|
||||
die() { printf '\033[31m[classhelper]\033[0m %s\n' "$*" >&2; exit 1; }
|
||||
|
||||
# 就绪探针：优先 curl（几乎每台 Linux 都有），否则退回 node。
|
||||
# 注意不要用 `node -e "...process.exit()"` —— 在部分 Node 版本上于 promise 回调里硬退会触发
|
||||
# libuv 断言崩溃（本机 Windows 实测退出码 -1073740791），改成设置 process.exitCode 让事件循环自然结束。
|
||||
probe_ready() {
|
||||
if command -v curl >/dev/null 2>&1; then
|
||||
curl -fsS -o /dev/null --max-time 3 "http://127.0.0.1:${PORT}/healthz" >/dev/null 2>&1
|
||||
return $?
|
||||
fi
|
||||
"$NODE_BIN" -e "fetch('http://127.0.0.1:${PORT}/healthz').then(r=>{process.exitCode=r.ok?0:1}).catch(()=>{process.exitCode=1})" >/dev/null 2>&1
|
||||
}
|
||||
|
||||
[ "$(id -u)" = "0" ] || { [ "$CHECK_ONLY" = "1" ] || die "请用 root 执行：sudo bash deploy/install-linux.sh"; }
|
||||
|
||||
# ---------------------------------------------------------------- 卸载分支
|
||||
if [ "$UNINSTALL" = "1" ]; then
|
||||
if systemctl list-unit-files | grep -q "^${SERVICE_NAME}.service"; then
|
||||
systemctl disable --now "$SERVICE_NAME" || true
|
||||
rm -f "/etc/systemd/system/${SERVICE_NAME}.service"
|
||||
systemctl daemon-reload
|
||||
log "已停止并移除 systemd 服务 ${SERVICE_NAME}"
|
||||
else
|
||||
warn "没有找到 ${SERVICE_NAME}.service（可能没装成服务）"
|
||||
fi
|
||||
log "程序文件与数据保留在 ${TARGET_DIR}；确认不需要后再手动删除"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------- 定位仓库与产物
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
|
||||
cd "$REPO_ROOT"
|
||||
|
||||
SERVER_DIST="packages/server/dist/index.js"
|
||||
SERVER_PRISMA="packages/server/prisma"
|
||||
WEB_DIST="packages/web-admin/dist/index.html"
|
||||
SHARED_DIST="packages/shared/dist/index.js"
|
||||
RUNTIME_PKG="deploy/package.runtime.json"
|
||||
|
||||
for f in "$SERVER_DIST" "$WEB_DIST" "$SHARED_DIST" "$RUNTIME_PKG"; do
|
||||
[ -e "$f" ] || die "缺少构建产物：$f
|
||||
请先在仓库根目录执行：
|
||||
pnpm build:shared && pnpm --filter @classhelper/server build && pnpm --filter @classhelper/web-admin build"
|
||||
done
|
||||
[ -d "$SERVER_PRISMA/migrations" ] || die "缺少迁移文件目录：$SERVER_PRISMA/migrations"
|
||||
|
||||
# ---------------------------------------------------------------- Node 检查
|
||||
NODE_BIN="$(command -v node || true)"
|
||||
[ -n "$NODE_BIN" ] || die "未找到 node，请先安装 Node.js ≥ 20.19（推荐 22 LTS）"
|
||||
NODE_MAJOR="$("$NODE_BIN" -p 'process.versions.node.split(".")[0]')"
|
||||
NODE_MINOR="$("$NODE_BIN" -p 'process.versions.node.split(".")[1]')"
|
||||
if [ "$NODE_MAJOR" -lt 20 ] || { [ "$NODE_MAJOR" -eq 20 ] && [ "$NODE_MINOR" -lt 19 ]; }; then
|
||||
die "Node 版本过低：$("$NODE_BIN" -v)（要求 ≥ 20.19）"
|
||||
fi
|
||||
NPM_BIN="$(command -v npm || true)"
|
||||
[ -n "$NPM_BIN" ] || die "未找到 npm（随 Node 一起安装）"
|
||||
log "Node $("$NODE_BIN" -v) → $NODE_BIN"
|
||||
|
||||
# ---------------------------------------------------------------- 只体检
|
||||
if [ "$CHECK_ONLY" = "1" ]; then
|
||||
echo
|
||||
echo "构建产物："
|
||||
for f in "$SERVER_DIST" "$WEB_DIST" "$SHARED_DIST" "$RUNTIME_PKG" "$SERVER_PRISMA/migrations"; do
|
||||
printf ' %-42s %s\n' "$f" "OK"
|
||||
done
|
||||
printf ' %-42s %s\n' "迁移文件数量" "$(find "$SERVER_PRISMA/migrations" -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ')"
|
||||
echo
|
||||
echo "运行环境："
|
||||
printf ' %-42s %s\n' "node" "$("$NODE_BIN" -v)（要求 ≥ 20.19）"
|
||||
printf ' %-42s %s\n' "npm" "$("$NPM_BIN" -v)"
|
||||
printf ' %-42s %s\n' "systemd" "$(command -v systemctl >/dev/null 2>&1 && echo 可用 || echo '不可用（用 --no-service）')"
|
||||
printf ' %-42s %s\n' "目标目录 ${TARGET_DIR}" "$([ -e "$TARGET_DIR" ] && echo '已存在（会就地升级，保留 .env）' || echo 尚未创建)"
|
||||
printf ' %-42s %s\n' "端口 ${PORT} 上的既有服务" "$(probe_ready && echo '健康（就绪）' || echo '无响应')"
|
||||
echo
|
||||
log "--check 通过：构建产物与运行环境都满足，可以执行安装（sudo bash deploy/install-linux.sh）"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------- 用户与目录
|
||||
if ! id -u "$SERVICE_USER" >/dev/null 2>&1; then
|
||||
useradd --system --create-home --shell /usr/sbin/nologin "$SERVICE_USER" 2>/dev/null \
|
||||
|| useradd --system --shell /sbin/nologin "$SERVICE_USER"
|
||||
log "已创建系统用户 ${SERVICE_USER}"
|
||||
fi
|
||||
|
||||
mkdir -p "${TARGET_DIR}/server" "${TARGET_DIR}/web" "${TARGET_DIR}/data" "${TARGET_DIR}/logs"
|
||||
log "安装目录：${TARGET_DIR}"
|
||||
|
||||
# ---------------------------------------------------------------- 拷贝产物
|
||||
rm -rf "${TARGET_DIR}/server/dist"
|
||||
cp -R "packages/server/dist" "${TARGET_DIR}/server/dist"
|
||||
rm -rf "${TARGET_DIR}/server/prisma"
|
||||
cp -R "$SERVER_PRISMA" "${TARGET_DIR}/server/prisma"
|
||||
# 运行时不读 schema，但保留一份便于排查
|
||||
[ -f packages/server/prisma/schema.prisma ] && cp packages/server/prisma/schema.prisma "${TARGET_DIR}/server/prisma/schema.prisma"
|
||||
|
||||
rm -rf "${TARGET_DIR}/web"
|
||||
cp -R "packages/web-admin/dist" "${TARGET_DIR}/web"
|
||||
|
||||
cp "$RUNTIME_PKG" "${TARGET_DIR}/package.json"
|
||||
cp -R deploy/classhelper.service "${TARGET_DIR}/classhelper.service.template"
|
||||
|
||||
# 生产依赖（与 Dockerfile 的 runtime 阶段同一份清单）
|
||||
if [ ! -d "${TARGET_DIR}/node_modules" ] || [ "${FORCE_NPM_INSTALL:-0}" = "1" ]; then
|
||||
log "安装生产依赖（npm install --omit=dev，约 1~3 分钟）..."
|
||||
( cd "$TARGET_DIR" && "$NPM_BIN" install --omit=dev --no-audit --no-fund )
|
||||
else
|
||||
log "复用已有 node_modules（如需强制重装：FORCE_NPM_INSTALL=1 再跑一次）"
|
||||
fi
|
||||
|
||||
# workspace 共享包（后端 import '@classhelper/shared'）：拷进 node_modules 里
|
||||
mkdir -p "${TARGET_DIR}/node_modules/@classhelper/shared"
|
||||
rm -rf "${TARGET_DIR}/node_modules/@classhelper/shared/dist"
|
||||
cp -R "packages/shared/dist" "${TARGET_DIR}/node_modules/@classhelper/shared/dist"
|
||||
cp packages/shared/package.json "${TARGET_DIR}/node_modules/@classhelper/shared/package.json"
|
||||
|
||||
# ---------------------------------------------------------------- .env（已存在则不覆盖）
|
||||
ENV_FILE="${TARGET_DIR}/.env"
|
||||
if [ -f "$ENV_FILE" ]; then
|
||||
log "检测到已有 .env：保留现有配置（含 JWT_SECRET），只补齐缺失项"
|
||||
else
|
||||
JWT_SECRET="$("$NODE_BIN" -e 'console.log(require("crypto").randomBytes(48).toString("hex"))')"
|
||||
cat > "$ENV_FILE" <<EOF
|
||||
# 班级小助手服务端（install-linux.sh 生成，请妥善保管）
|
||||
# 修改后重启服务生效：systemctl restart ${SERVICE_NAME}
|
||||
|
||||
NODE_ENV=production
|
||||
HOST=0.0.0.0
|
||||
PORT=${PORT}
|
||||
|
||||
# 数据库：SQLite 文件放在安装根目录的 data 下（备份只需复制该目录）
|
||||
DATABASE_PROVIDER=sqlite
|
||||
DATABASE_URL="file:../data/classhelper.db"
|
||||
# 空库首启动自动执行随包迁移并创建管理员
|
||||
AUTO_MIGRATE=true
|
||||
|
||||
# 令牌签名密钥（随机生成；更换后所有用户需重新登录）
|
||||
JWT_SECRET=${JWT_SECRET}
|
||||
JWT_EXPIRES_IN=7d
|
||||
|
||||
# 允许的跨域来源：走域名/反代时建议改成具体来源，例如 https://class.example.com
|
||||
CORS_ORIGIN=*
|
||||
# 前面有 Nginx 等反向代理时设为 1，限流才会按真实客户端 IP 统计
|
||||
TRUST_PROXY=1
|
||||
|
||||
RATE_LIMIT_ENABLED=true
|
||||
STARTUP_DB_CHECK=true
|
||||
PID_FILE=../data/server.pid
|
||||
LOG_LEVEL=info
|
||||
|
||||
BCRYPT_ROUNDS=10
|
||||
DEFAULT_STUDENT_PASSWORD=123456
|
||||
DEFAULT_CLASS_PASSWORD=123456
|
||||
DEFAULT_TEACHER_PASSWORD=123456
|
||||
TERM_START_DATE=
|
||||
EOF
|
||||
log "已生成 ${ENV_FILE}（含随机 JWT_SECRET）"
|
||||
fi
|
||||
|
||||
# data/logs 必须可写；程序文件只读即可
|
||||
chown -R "${SERVICE_USER}:${SERVICE_USER}" "${TARGET_DIR}/data" "${TARGET_DIR}/logs"
|
||||
chown -R "${SERVICE_USER}:${SERVICE_USER}" "${TARGET_DIR}/node_modules"
|
||||
chown "${SERVICE_USER}:${SERVICE_USER}" "$ENV_FILE"
|
||||
chown -R root:root "${TARGET_DIR}/server" "${TARGET_DIR}/web"
|
||||
chmod 600 "$ENV_FILE"
|
||||
|
||||
# ---------------------------------------------------------------- systemd
|
||||
if [ "$WITH_SERVICE" = "1" ]; then
|
||||
command -v systemctl >/dev/null 2>&1 || die "本机没有 systemd；请加 --no-service 自行托管进程"
|
||||
|
||||
sed -e "s#__NODE__#${NODE_BIN}#g" \
|
||||
-e "s#__DIR__#${TARGET_DIR}#g" \
|
||||
-e "s#__USER__#${SERVICE_USER}#g" \
|
||||
deploy/classhelper.service > "/etc/systemd/system/${SERVICE_NAME}.service"
|
||||
systemctl daemon-reload
|
||||
systemctl enable "$SERVICE_NAME" >/dev/null
|
||||
systemctl restart "$SERVICE_NAME"
|
||||
|
||||
log "等待服务就绪..."
|
||||
ready=0
|
||||
for _ in $(seq 1 60); do
|
||||
if probe_ready; then
|
||||
ready=1
|
||||
break
|
||||
fi
|
||||
sleep 1
|
||||
done
|
||||
|
||||
if [ "$ready" != "1" ]; then
|
||||
warn "60 秒内没通过 /healthz，最近日志："
|
||||
journalctl -u "$SERVICE_NAME" -n 50 --no-pager || true
|
||||
die "启动失败，请按上面的日志排查（常见：端口被占用、数据目录权限、JWT_SECRET 未生成）"
|
||||
fi
|
||||
|
||||
log "服务已就绪 ✅"
|
||||
else
|
||||
log "已跳过 systemd（--no-service）。手动启动："
|
||||
echo " sudo -u ${SERVICE_USER} sh -c 'cd ${TARGET_DIR} && ${NODE_BIN} server/dist/index.js'"
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------- 结果
|
||||
cat <<EOF
|
||||
|
||||
------------------------------------------------------------------
|
||||
安装完成
|
||||
访问管理端：http://<服务器IP>:${PORT}/
|
||||
健康探针： http://<服务器IP>:${PORT}/healthz · /readyz
|
||||
配置文件： ${ENV_FILE}
|
||||
数据目录： ${TARGET_DIR}/data（备份只需复制这里）
|
||||
查看日志： journalctl -u ${SERVICE_NAME} -f
|
||||
重启服务： systemctl restart ${SERVICE_NAME}
|
||||
|
||||
首次启动会自动建表并创建管理员：admin / admin123（登录后请立即在右上角「修改密码」改掉）。
|
||||
公网部署请在前面加 Nginx + HTTPS（deploy/nginx.conf 可直接用），并把 .env 里的
|
||||
TRUST_PROXY 设为 1、CORS_ORIGIN 收敛到你的域名。
|
||||
学生端客户端登录时填的「服务器地址」就是 https://你的域名（或 http://IP:${PORT}）。
|
||||
------------------------------------------------------------------
|
||||
EOF
|
||||
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
@@ -0,0 +1,19 @@
|
||||
# ---------------------------------------------------------------------------
|
||||
# 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
|
||||
}
|
||||
@@ -92,6 +92,20 @@ server {
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------- 接口与页面
|
||||
# 课件流式上传（其余接口继续沿用 8 MB 限制）
|
||||
location /api/courseware/ {
|
||||
client_max_body_size 512m;
|
||||
proxy_pass http://classhelper_backend;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_request_buffering off;
|
||||
proxy_buffering off;
|
||||
proxy_read_timeout 1800s;
|
||||
proxy_send_timeout 1800s;
|
||||
}
|
||||
|
||||
location / {
|
||||
proxy_pass http://classhelper_backend;
|
||||
proxy_http_version 1.1;
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
{
|
||||
"name": "classhelper-server-runtime",
|
||||
"version": "1.0.0",
|
||||
"version": "1.4.1",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"description": "班级小助手服务端运行时（安装包 / 容器内置）",
|
||||
"description": "ClassHelper 服务端运行时（安装包 / 容器内置）",
|
||||
"dependencies": {
|
||||
"@libsql/client": "^0.17.0",
|
||||
"@prisma/adapter-libsql": "7.10.0",
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
# ---------------------------------------------------------------------------
|
||||
# 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
|
||||
@@ -0,0 +1,22 @@
|
||||
# ---------------------------------------------------------------------------
|
||||
# 班级小助手 · 定时备份（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
|
||||
@@ -0,0 +1,19 @@
|
||||
# ---------------------------------------------------------------------------
|
||||
# 班级小助手 · 定时备份（触发器）
|
||||
# 由 `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
|
||||
@@ -0,0 +1,335 @@
|
||||
#!/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 的现行工程约定）
|
||||
await modules.disconnectPrisma();
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,307 @@
|
||||
#!/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
@@ -0,0 +1,147 @@
|
||||
<!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>
|
||||
@@ -0,0 +1,99 @@
|
||||
---
|
||||
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)。
|
||||
|
||||
## 客户端设置页
|
||||
|
||||
「设置」是可展开分组，常用子页如下；开发者模式还提供开发者页，自定义岛编辑为灵动岛子路由：
|
||||
|
||||
| 子页 | 内容 |
|
||||
| ------ | ----------------------------------------------------------------------------- |
|
||||
| 通用 | 服务器连接、离线缓存、作业录入短语、使用引导 |
|
||||
| 外观 | 浅色 / 深色 |
|
||||
| 灵动岛 | 尺寸、字号、主题色、视觉风格、停靠、边距、空闲细缝（详见[灵动岛](island.md)） |
|
||||
| 提醒 | 本机课程等提醒开关与行为 |
|
||||
| 账号 | 当前班级信息、退出登录 |
|
||||
| 关于 | 版本 / Electron / Chromium / Node、诊断信息、检查更新、鸣谢 |
|
||||
|
||||
`/settings` 会自动跳到「通用」。设置页的改动会**立刻生效并写进本机配置**，重启后仍保留。
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: 叫人
|
||||
description: 点名、优先级、可见范围和客户端展示。
|
||||
---
|
||||
|
||||
# 叫人
|
||||
|
||||
在 Web“通知发布 → 叫人”选学生，填写事由或选择快捷短语，需 call:create 和班级范围权限。
|
||||
可调用的学生必须属于相应在读班级且未转出；岗位范围、任课或班主任关系由服务端检查。
|
||||
学生没有账号，无法以个人身份调用接口。
|
||||
|
||||
| 级别 | 落库优先级 | 经典 fixed 展示 |
|
||||
| -------- | ---------- | ------------------------------------------------------------------ |
|
||||
| 普通叫人 | HIGH | 胶囊可点击，上课也允许主动查看；不自动展开打断课堂，下课可自动展开 |
|
||||
| 紧急叫人 | URGENT | 上课也立即展开，收起后仍可主动再打开 |
|
||||
|
||||
自定义 custom 是常驻模式，两种叫人都先提示铃铛，由用户主动查看；详见[通知与提醒](notifications.md)。
|
||||
卡片内容包括被叫学生、教师和事由，“收到”复用通知已读机制。
|
||||
自定义消息优先于快捷短语，消息长度以接口 schema 校验为准。
|
||||
|
||||
`POST /api/calls` 保存为 Notification，带本地所属日期；随后发送 notification:new 班级广播和 call:new 班级会话定向事件。
|
||||
定向主体是班级会话，学生本身没有 Socket 房间；双播按消息 id 合并去重。
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: 班级、学生与教师
|
||||
description: 名单、班级会话、任课关系与年度升级。
|
||||
---
|
||||
|
||||
# 班级、学生与教师
|
||||
|
||||
## 班级账号
|
||||
|
||||
教室客户端使用班级码和班级密码登录，形成 CLASS_DEVICE 会话，主体是班级。
|
||||
班级码保存时统一大写；管理员在“班级管理”维护班级码、密码与班主任。
|
||||
班级端的已读、作业完成等操作代表全班，学生没有个人登录账号。
|
||||
客户端没有修改密码入口；员工本人改密码在 Web 顶栏菜单。
|
||||
|
||||
班级名由入学年份和班号组成，例如“2026级1班”；年级独立保存，学年升级时班名不随之改写。
|
||||
班主任可以暂空，新学年自动创建的高一班级仅有骨架，需要管理员后续分配教师。
|
||||
|
||||
## 学生名单
|
||||
|
||||
Student 存学号、姓名、班级、性别、家长电话和状态，没有密码或角色字段。
|
||||
学号为必填唯一标识，格式为 1–32 位字母、数字或 . _ -；不会自动生成登录名。
|
||||
管理员或本班班主任在具备名单管理权限后管理学生，教师也可按授权范围只读名单。
|
||||
名单表格导入仍要求管理员及相应导入权限；学号查重在 Student 表完成，不当成 User 用户名。
|
||||
调班保留历史内容原归属；转出独立记账并从现行业务名单过滤，学号不可复用。
|
||||
|
||||
## 教师与科目
|
||||
|
||||
教师使用工号和密码登录，管理入口受 teacher:read/teacher:manage 等功能权限控制。
|
||||
教师名单导入还要求管理员身份和相应导入权限。班主任关系在 Class.teacherId；
|
||||
科任关系唯一存于 Course(classId, name, teacherId)，分配任课关系由班级管理权限及服务端断言限制。
|
||||
班主任不任教某科就不能修改该科作业/成绩；科任老师有相应权限时可以管理自己任教科目。
|
||||
|
||||
删除教师前，服务端检查其负责的班级、任课课程、发布过的作业/通知与所属课件；仍有业务内容则返回冲突，避免级联丢失。
|
||||
教师本人改密码、管理员修改教师密码、班级账号密码是不同入口；学生没有密码接口。
|
||||
|
||||
## 权限、学年与归档
|
||||
|
||||
角色给默认权限模板，实际入口由可编辑权限组决定；岗位组还能配置年级或部范围。
|
||||
范围不代替科目写权限，详见[角色与权限](../dev/permissions.md)。
|
||||
学期周数受全校可配置上限约束，默认上限 30、允许 1–60，见[课表](schedules.md)。
|
||||
学年升级按计划时间运行，执行前保存快照，以年份幂等；启动发现漏跑需管理员预览补跑。
|
||||
高三归档、高一/高二升一级，新高一不复制任课关系。归档页查看届别历史与转出记录，
|
||||
不再通过手动创建归档来代替年度升级。撤回转出等操作仍受归档与管理员业务检查约束。
|
||||
@@ -0,0 +1,42 @@
|
||||
# 课件上传与传输
|
||||
|
||||
教师可在 Web 管理端的「教学事务 → 课件」上传演示文稿、文档、表格、图片、音视频、压缩包等文件，单文件上限为 **512 MB**。
|
||||
|
||||
## 上传与可见范围
|
||||
|
||||
1. 选择本地文件。
|
||||
2. 选择可以查看课件的班级。候选项只包含本人担任任课教师的在读班级；仅担任班主任、级长或部长不会额外获得上传到这些班级的权限。
|
||||
3. 可新建分类文件夹，使用 `/` 分隔多层目录，例如 `地理/必修一`；不选文件夹时直接按日期归档。
|
||||
4. 选择「仅保存云端」或「保存后推送所选班级」，点击上传。
|
||||
|
||||
不选择班级时，课件仅自己可见。仅保存云端并指定可见班级后，这些班级可在客户端自主下载。推送模式会先把文件完整保存到服务端，再给所选班级创建下载任务；不会从教师电脑直接传到教室电脑。
|
||||
|
||||
教师可在列表中按文件名、教师、归档日期和文件类型筛选，修改自己课件的可见范围，或再次推送。再次推送时只能选择「本人授课班级」与「该文件可见范围」的交集。管理员可查看归档列表，但上传和推送自己的文件同样遵守任课关系。
|
||||
|
||||
「查看与下载课件」和「上传、设置可见范围与推送自己的课件」为独立权限，可在权限组中分配。默认教师与管理员、内置教师与班主任岗位包含这两项权限；升级时自定义权限组需管理员按需授权。
|
||||
|
||||
「日期归档」按教师、年、月、日和上传时间选择目录；「文件夹分类」按自建目录筛选，已有文件可随时调整分类。文件夹按教师隔离，分类本身不授予班级下载权限。
|
||||
|
||||
## 班级客户端
|
||||
|
||||
客户端侧栏新增「课件」，仅列出本班可见的文件，显示文件名、类型、上传教师、日期与大小。点击「下载」将课件保存到本机，点击「打开文件夹」定位已下载文件。客户端不会自动运行文件。
|
||||
|
||||
「本机归档」独立列出已经接收的课件，离线时也可按教师和日期目录查找。每个服务端与班级会话有独立归档根目录，文件路径采用 `Teachers\老师名字\上传年份\上传月\上传日\上传时间\文件名`，例如 `Teachers\Wanghong\2026\10\18\15-30-42\大气环流.pptx`。目录时间取上传时间，重复推送会复用已校验的文件；同秒同名的不同课件会添加编号，避免覆盖。
|
||||
|
||||
收到教师推送后，客户端自动下载；离线时任务保留在服务端，上线后的心跳会补拉，每台设备独立回执。实时通道正常时会立即触发检查；断线时通过心跳继续补收。传输失败会显示原因，推送任务在后续心跳中重试，不会影响远控和在线状态上报。
|
||||
|
||||
下载期间，固定岛和自定义常驻岛都会显示文件名、文件类型、传输教师、接收字节数和进度条。下载完成后校验 SHA256，再保存正式文件并回执。断网时可以查看已缓存的课件目录与已经下载的本地文件；重新联网后同步当前可见范围。
|
||||
|
||||
修改可见范围后，被移除班级无法再获取文件，尚未完成的推送任务同步取消。已经下载到教室电脑的文件无法远程撤回，需要在本机自行删除。
|
||||
|
||||
## 服务端归档与备份
|
||||
|
||||
默认文件实体目录为 `<服务端根目录的上一级>/data/courseware/<随机编号>/Teachers/<教师>/<年>/<月>/<日>/<时间>/<文件名>`，随机编号隔离同名教师和同秒上传，旧课件保留原存储位置。可通过环境变量 `COURSEWARE_DIR` 指定文件目录。上传使用流式写入，未完成文件使用 `.part` 临时文件；失败或上传中断时清理。只有完整收到文件并完成摘要计算后才记录元数据和创建推送任务。
|
||||
|
||||
数据库迁移新增课件、可见班级、推送、设备回执和分类目录，并记录上传归档路径。SQLite 安装部署按现有自动迁移流程更新；源码开发部署执行 `pnpm --filter @classhelper/server db:deploy`。MySQL 按现有换库流程基于更新后的 schema 建模。
|
||||
|
||||
数据库 JSON 备份包含课件元数据和分类目录，但**不包含二进制文件本身**。完整备份必须同时备份 `data/courseware`（自定义目录时备份对应目录）。SQLite Docker 的现有数据卷覆盖此目录；MySQL Docker 配置增加 `server-data:/app/data` 数据卷。复制到新机器时需同时恢复数据库和文件目录。
|
||||
|
||||
使用反向代理时，需允许课件上传大小和足够的读写超时。仓库的 Nginx 样例单独为 `/api/courseware/` 配置 512 MB 和 1800 秒超时，其他接口维持原有大小限制。
|
||||
|
||||
开发验收：`pnpm verify:courseware` 自动使用隔离数据库和临时文件目录，不读取或向真实班级发送课件。
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: 成绩
|
||||
description: 录入、按学号查询、排名与关闭个人查询后的集体分析。
|
||||
---
|
||||
|
||||
# 成绩
|
||||
|
||||
Web 管理端支持单条、批量和表格导入成绩；记录通过 Grade.studentId 关联学生名单。
|
||||
科目来自班级课程与共享科目目录，分数、总分和等级按录入规则校验。
|
||||
成绩写入需 grade:write 或相应导入权限，并通过班级和科目检查：
|
||||
管理员可管理，教师只能编辑自己任课科目，无科目内容按班主任规则；班级端不能写成绩。
|
||||
表格导入另有管理员/本班班主任门槛，班主任也只能导入符合科目权限的行；它与单条/批量录入的准入不同。
|
||||
|
||||
## 查看、排名与隐私
|
||||
|
||||
班级客户端可显示本班考试、成绩总览、等级分布，以及按学号查询明细。
|
||||
是否允许读取个人数据由 Class.studentGradeQueryEnabled 控制，班级端只读该设置。
|
||||
|
||||
| 状态 | 班级端可读取内容 |
|
||||
| ------------ | -------------------------------------------------------------------- |
|
||||
| 个人查询开启 | 本班原始成绩、个人明细、考试及排名，仍检查班级归属 |
|
||||
| 个人查询关闭 | 页面可打开，只返回服务端集体聚合；个人明细、原始全班成绩和排名被拒绝 |
|
||||
|
||||
聚合对少于 5 名学生的样本、稀疏分段及补集抑制，不提供最高/最低分。
|
||||
客户端不会先拿个人成绩再做隐藏或聚合；教师/管理员按自身权限读取，不受班级端个人查询开关限制。
|
||||
|
||||
考试“是否计入总分”属于 Exam，教师在管理端设置，客户端只展示。
|
||||
同一学生同一科多条成绩取最高分，排名并列用 1、2、2、4；总分只在开启时显示。
|
||||
图表使用本地 HTML/CSS/SVG 组件。
|
||||
|
||||
## 接口入口
|
||||
|
||||
以下省略 /api 前缀，详情与参数以 grades.module.ts、grades.schemas.ts 为准。
|
||||
|
||||
| 方法与路径 | 用途 |
|
||||
| ----------------------------------------------------- | -------------------------------------------------- |
|
||||
| GET /grades/overview | 班级端按开关返回原始总览或集体聚合 |
|
||||
| GET /grades/my | 班级端原始成绩，关闭个人查询时拒绝；员工返回空数组 |
|
||||
| GET /grades/collective?classId= | 服务端集体分析 |
|
||||
| GET /grades/student/:studentNo | 按学号查询，班级端受班级开关控制 |
|
||||
| GET /grades?classId=&courseId=&studentId=&examName= | 员工列表，功能键与范围检查 |
|
||||
| GET /grades/stats | 员工统计 |
|
||||
| GET/PUT /grades/exams | 考试列表 / 设置总分口径 |
|
||||
| GET /grades/ranking | 考试排名，班级端受个人查询开关控制 |
|
||||
| POST /grades、/grades/bulk | 单条或批量录入 |
|
||||
| PATCH /grades/levels、/grades/:id；DELETE /grades/:id | 等级与成绩维护 |
|
||||
|
||||
变更发送 grade:updated，事件载荷同样须遵守个人数据保护，客户端按需重新读取。
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
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。
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: 表格与课表导入
|
||||
description: 表格预览、名单与成绩校验，以及完整离线档案导入。
|
||||
---
|
||||
|
||||
# 表格与课表导入
|
||||
|
||||
解析与写入均在服务端完成，Web 收集文件、展示预览和逐行结果。
|
||||
表格支持成绩、学生、教师与班级任课关系等 kind，类型和模板以 shared/imports 模块为准。
|
||||
|
||||
## 表格流程
|
||||
|
||||
下载模板 → 选择 xlsx/xls/csv/tsv → 预览列名与映射 → 确认模式并提交。
|
||||
文件上限 8 MB，JSON 请求体 12 MB，超限 413 IMPORT_TOO_LARGE；结果含新增/更新/跳过/失败、errors/warnings。
|
||||
错误行号包含表头，便于在 Excel 定位。
|
||||
|
||||
- 学生成绩按学号匹配，姓名兜底要求同班唯一；转出学生不参与匹配，重复记录和写入模式由服务校验。
|
||||
- 学生模板使用学号、姓名、班级、性别、家长电话，无密码；学号 1–32 位字母/数字/._-，在 Student 表查重。
|
||||
- 教师模板使用工号、姓名、手机号、初始密码、角色；学生/教师名单导入仍要求管理员和导入权限。
|
||||
- 成绩表格导入当前先要求管理员或本班班主任，再校验每行科目任课关系；科任老师的单条/批量成绩写入权限不代表能走表格导入。
|
||||
- 任课关系导入用于既有班级、科目和教师的对应关系，不把档案中的 TeacherName 当账号授权。
|
||||
|
||||
## 完整 ClassIsland 档案
|
||||
|
||||
在“课表档案 → 导入档案”选择或粘贴 JSON，先预览再导入。
|
||||
完整输入包含 TimeLayouts、ClassPlans、Subjects 字典，可包含 ClassPlanGroups 和 OrderedSchedules 等配置。
|
||||
JSON 只作为离线文件导入，不依赖在线联动插件。
|
||||
|
||||
现行写入由 class-plans/profile-import.service.ts 完成：
|
||||
|
||||
| 项目 | 写入规则 |
|
||||
| --------- | ----------------------------------------------------------------------- |
|
||||
| 时间类型 | 0/1/2/3 对应 LESSON/BREAK/DIVIDER/ACTION，保存为关系化时间点 |
|
||||
| 课程对齐 | Classes[i] 引用第 i 个上课时间点，课间/分割线不占课位，数据库用显式外键 |
|
||||
| 星期 | 完整导入 0=不按天、1–7=周一至周日 |
|
||||
| 轮换 | 原样保留 WeekCountDiv/WeekCountDivTotal，支持 1–9 周，不降级成每周 |
|
||||
| 状态 | 保留空课、停用、临时换课标记和关联层 |
|
||||
| 群组/预定 | 保存群组及可识别的预定/临时选择 |
|
||||
| 缺失科目 | 复用该班课程；新建需该班已有班主任，教师名不授予权限 |
|
||||
| merge | 基于班级与来源 id 生成稳定 id，重复导入更新同一套对象 |
|
||||
| replace | 事务内删除该班预定和日课表后写入，保留的对象以实现为准 |
|
||||
|
||||
日课表导入需本班班主任/管理员检查。旧 /imports/class-plan/preview 是扁平预览，
|
||||
不完整展示群组/空课/停用等结构；提交直接调用完整导入，不能把预览的单双周列当作实际数据模型。
|
||||
完整导入失败时事务回滚；部分缺失引用可能返回 warnings，须检查导入结果和日课表编辑器。
|
||||
|
||||
## 时间配置兼容入口
|
||||
|
||||
旧 /imports/time-layout 接口保留，写入和删除需 timetable:manage，现行写入同步关系化时间点。
|
||||
常规使用时间表/日课表编辑器或整套档案导入；旧预览解析兼容性不代表完整导入接受所有旧输入形态。
|
||||
|
||||
接口索引见[REST API](../dev/api.md)，迁移边界见[当前实现约定](../dev/implementation.md)。
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: 应用帮助
|
||||
description: ClassHelper每一项功能怎么用：课表、作业、通知、叫人、成绩、班级、灵动岛、外观与导入。
|
||||
---
|
||||
|
||||
# 应用帮助
|
||||
|
||||
这一章按功能讲，重点是**行为上的约定**——什么时段会弹、谁看得见、什么情况下不动。
|
||||
很多"看起来像故障"的现象其实是设计行为，下面每一页都会点出来。
|
||||
|
||||
| 页面 | 讲什么 |
|
||||
| --------------------------------- | ---------------------------------------------------------- |
|
||||
| [课表](schedules.md) | 周视图与「今天」时间轴、单双周、学期周数、课表来源 |
|
||||
| [课件](courseware.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 端维护。
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: 灵动岛
|
||||
description: 经典提醒、自定义常驻方案、课程与课件传输。
|
||||
---
|
||||
|
||||
# 灵动岛
|
||||
|
||||
灵动岛是客户端的独立透明窗口，不占任务栏。设置中可选择经典 fixed 或自定义 custom，默认 fixed。
|
||||
自定义当前即常驻模式；旧 residentEnabled 字段只作兼容，不是另一个独立开关。
|
||||
两种布局共用一个原生窗口，切布局不会新开第二个岛。
|
||||
|
||||
## 两种消息展示
|
||||
|
||||
| 场景 | 经典 fixed | 自定义 custom |
|
||||
| ----------------- | ------------------------------ | -------------------------- |
|
||||
| 空闲 | 默认隐藏，可选细缝 | 显示常态组件行 |
|
||||
| 课间普通通知/作业 | 胶囊，点击详情 | 铃铛和未处理数量，点击查看 |
|
||||
| 课堂普通通知/作业 | 暂存，下课补弹 | 铃铛提示，允许主动查看 |
|
||||
| 普通叫人 | 课堂也保留可点胶囊，不自动展开 | 铃铛提示，主动查看 |
|
||||
| 紧急通知/紧急叫人 | 无论课堂状态立即展开 | 铃铛提示，由用户主动展开 |
|
||||
| 无消息时点击 | 按经典空闲状态处理 | 展示方案的无通知展开内容 |
|
||||
| 处理完成 | 队列清空后隐藏或细缝 | 回到常态组件行 |
|
||||
|
||||
多条消息按 id 去重，按优先级和时间排序；详情显示列表与“展开更多”，超出工作区提示到应用中操作。
|
||||
“知道了/标为已读”按当前列表语义处理；本机刚录的作业通过指纹避免重复提醒自己。
|
||||
课堂发布紧急通知的二次确认是服务端规则，见[通知](notifications.md)，不因本机布局改变。
|
||||
|
||||
经典布局的历史展示图（供外观参考，具体行为以上表和当前设置为准）：
|
||||
|
||||
| 场景 | 展示图 |
|
||||
| -------- | --------------------------------------- |
|
||||
| 经典胶囊 |  |
|
||||
| 展开详情 |  |
|
||||
| 紧急通知 |  |
|
||||
|
||||
## 编辑自定义方案
|
||||
|
||||
“设置 → 灵动岛 → 自定义 → 编辑岛内组件”进入主窗口设置页。
|
||||
方案支持复制、删除、JSON 导入导出；组件支持日期、时钟、倒计时、课程、文本、分隔符、通知/作业/叫人及组合容器。
|
||||
分别编辑常态 rows 与无消息展开 expandedRows，拖动调整结构，设置内容、外观、尺寸与隐藏条件。
|
||||
方案保存到本机 config.json.islandLayout，不增加服务端同步。
|
||||
编辑预览不创建额外桌面窗口；打开编辑页不自动切布局，应用后启用自定义方案。
|
||||
保存按序进行，失败可重试，主题与关怀模式沿用客户端设置。
|
||||
|
||||
## 外观、位置与输入
|
||||
|
||||
经典模式可调宽高、字号、主题色、黑色/半透明/渐变、停靠与边距；自定义内容根据实际测量适配工作区。
|
||||
自定义方案可配置缩放、圆角、颜色和行间距，默认值与范围在 shared/island-layout.ts。
|
||||
左右边距只在左/右停靠时生效，居中锚点仍在屏幕中线。
|
||||
触摸屏自动进入触摸模式，保留触摸命中和失焦宽限；鼠标模式按光标控制输入穿透。
|
||||
自定义常驻内容支持鼠标避让淡化及反转，交互入口、展开/编辑和触摸操作按实现暂停避让。
|
||||
应用内动画开关决定岛动画，不能用主窗口的减少动态效果说明替代岛自身规则。
|
||||
|
||||
经典几何与配色参考见[设计令牌](../dev/winisland-design-tokens.md)，实现入口见[当前实现约定](../dev/implementation.md)。
|
||||
|
||||
## 课程与课件
|
||||
|
||||
准备、上课、下课、下课前倒数和课中进度等提醒在本机配置独立开关，课程依据服务端解析后的课表。
|
||||
课件接收时显示文件名、类型、教师、字节和进度，覆盖当前固定/自定义内容；完成后校验 SHA256 并回执。
|
||||
客户端不会自动执行收到的文件，见[课件](courseware.md)。
|
||||
|
||||
## 验证与排查
|
||||
|
||||
默认 verify:desktop/verify:packaged 是后台快速检查，不显示岛或托盘。
|
||||
只有显式 --visual 或 verify:desktop:visual 才进行桌面像素、透明度、动画和截图验收。
|
||||
若出现多岛，先确认是否存在用户实例与显式视觉验证实例；不要把默认后台冒烟解释成可见验证岛。
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: 通知与提醒
|
||||
description: 优先级、课堂确认与经典/自定义常驻模式的提醒区别。
|
||||
---
|
||||
|
||||
# 通知与提醒
|
||||
|
||||
Web 发布通知需 notification:publish 和班级范围权限。通知按本地 assignDate 归档，支持按日期、发布人查看与批量发布。
|
||||
服务端保存后立即广播；上课暂存与是否自动展开是客户端本机展示规则。
|
||||
|
||||
## 优先级与本机展示
|
||||
|
||||
共享优先级为 LOW（低）、NORMAL（普通）、HIGH（重要）、URGENT（紧急）。
|
||||
经典固定模式和自定义常驻模式有不同展示：
|
||||
|
||||
| 场景 | 经典 fixed | 自定义 custom |
|
||||
| ---------------------- | ------------------------------------------ | -------------------------------------- |
|
||||
| 普通/重要/低通知、作业 | 课间显示胶囊；上课暂存，下课补弹 | 常驻内容旁提示铃铛与去重数量，点击查看 |
|
||||
| 紧急通知/紧急叫人 | 无论是否上课立即展开 | 提示铃铛，由用户主动展开 |
|
||||
| 普通叫人 | 上课保留可点击胶囊，不自动展开；课间可展开 | 提示铃铛，可主动查看 |
|
||||
| 主动查看 | 普通通知受课堂状态限制，叫人和紧急可点开 | 上课也可主动展开 |
|
||||
|
||||
经典紧急通知默认约 45 秒收起；列表与消息处理见[灵动岛](island.md)。课件传输另显示专用进度。
|
||||
|
||||
## 课堂发布紧急通知
|
||||
|
||||
上课时发布 URGENT，服务端先返回 409 URGENT_DURING_CLASS。
|
||||
Web 显示全屏确认和倒计时，再次请求带 confirmDuringClass:true 才放行。
|
||||
这是服务端发布校验，不受客户端选择 fixed/custom 影响；普通叫人和紧急叫人走[叫人](calls.md)的接口规则。
|
||||
|
||||
## 已读与撤回
|
||||
|
||||
客户端通知页有未读数，打开详情可标已读；班级会话的已读操作代表全班在读学生。
|
||||
删除需相应员工权限和范围，实时撤回会清理客户端列表、缓存与岛队列。
|
||||
同 id 的通知与叫人双播合并，不重复计数。
|
||||
|
||||
## 接口入口
|
||||
|
||||
以下省略 /api，均先鉴权；具体功能键及范围见[REST API](../dev/api.md)。
|
||||
|
||||
| 方法与路径 | 用途 |
|
||||
| ----------------------------------------------------- | --------------------------------------------------------------------- |
|
||||
| GET /notifications | 列表；classId、priority、unreadOnly、keyword、date/from/to、createdBy |
|
||||
| GET /notifications/days、/notifications/creators | 日期与发布人归档 |
|
||||
| GET /notifications/unread-count | 未读数 |
|
||||
| POST /notifications、/notifications/bulk | 单班/批量发布，批量逐班返回结果 |
|
||||
| POST /notifications/:id/read、/notifications/read-all | 标记已读 |
|
||||
| DELETE /notifications/:id | 撤回 |
|
||||
|
||||
ClassIsland 在线提醒渠道已移除；本机提醒设置不会写回旧渠道字段。
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: 课表
|
||||
description: 日课表、共享作息、轮换、临时换课和教学周。
|
||||
---
|
||||
|
||||
# 课表
|
||||
|
||||
Web 管理端统一从「教学事务 → 课表档案」查看周课表并编辑时间表与日课表，客户端提供“今天”时间轴和“本周”视图。
|
||||
上课状态、灵动岛课程提醒和紧急通知确认共用服务端的课表判定。
|
||||
|
||||
编辑工作区参照 [CsesWebEditor](https://github.com/SmartTeachCN/CsesWebEditor) 的资源列表、设置卡片、课时列表与快速选科布局实现。左侧集中切换课程表、时间表、科目、群组与预定、整周预览和文件预览。旧管理页地址 `/schedules` 自动进入同一工作区。
|
||||
|
||||
点击课时后可用右侧科目按钮快速填充；拖动课时交换课程，拖动时间点调整时间表顺序，完成后保存。时间表支持任意分钟输入；设置的课程/课间分钟数会用于新建时间点的默认起止时间。完整档案可在页头导入或导出 JSON，保留轮换、时间点类型、空课、停用、群组和预定。
|
||||
|
||||
## 日课表与时间表
|
||||
|
||||
时间表保存时间点：上课、课间、分割线、行动；日课表引用时间表，每节课程通过外键关联时间点。
|
||||
可以维护多套班级作息或共享作息、复制日课表、调整课程、配置启用规则和群组。
|
||||
时间点排序不会改变课程关联。行动配置当前保存数据，不执行外部动作。
|
||||
|
||||
日课表按星期、周次范围和轮换规则启用，支持 1–9 周轮换；单双周是 2 周轮换的特例，第 1 教学周为单周。
|
||||
可以预定某天使用某张表，临时换课/叠加层保留原表。相同日期的最终启用选择由服务端唯一解析器完成。
|
||||
|
||||
## 教学周
|
||||
|
||||
班级有自己的学期周数；全校上限由“学期周次”设置，默认 30、可设 1–60，班级不能超过该上限。
|
||||
默认班级周数为 20。管理员可在界面修改全校开学日和逐周起止区间，班级可有独立设置。
|
||||
计算优先使用班级逐周区间、再全校区间；无适用区间时按开学日线性计算。
|
||||
开学日解析还会参考第 1 周起点，环境变量 TERM_START_DATE 是兜底，具体顺序见 `lib/term.ts`。
|
||||
|
||||
## 上课状态与提醒
|
||||
|
||||
`GET /api/schedules/current?classId=<id>&at=<ISO时间>` 返回 inClass/current/next/week/serverTime 等状态；at 用于诊断。
|
||||
`/schedules` 是新模型的兼容门面，旧 Schedule 只保留迁移审计记录。
|
||||
经典岛普通通知上课暂存、下课补弹；普通叫人保留可点击胶囊，紧急消息立即展开。
|
||||
自定义常驻岛先显示铃铛，由用户主动查看。紧急通知在课堂发布仍需服务端二次确认。
|
||||
|
||||
## 权限与导入
|
||||
|
||||
日课表写入需 schedule:write，并通过管理员或本班班主任检查；时间表写入需 timetable:manage。
|
||||
离线导入完整 ClassIsland 档案可创建班级自有作息，不依赖在线联动插件。
|
||||
完整导入保留 1–9 周轮换、空课、停用、群组和预定；旧预览界面的单双周展示不代表新模型只能表达双周。
|
||||
见[表格与课表导入](imports.md)。修改后广播 schedule:updated，客户端刷新。
|
||||
@@ -0,0 +1,22 @@
|
||||
- name: 应用帮助
|
||||
href: index.md
|
||||
- name: 课表
|
||||
href: schedules.md
|
||||
- name: 作业
|
||||
href: homeworks.md
|
||||
- name: 课件上传与传输
|
||||
href: courseware.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
@@ -0,0 +1,128 @@
|
||||
#!/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);
|
||||
});
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
title: REST API
|
||||
description: 现行接口分组、关键路径和权限边界。
|
||||
---
|
||||
|
||||
# REST API
|
||||
|
||||
API 前缀 /api，JWT 使用 Authorization: Bearer。成功/失败结构以 `lib/http.ts` 为准，
|
||||
校验错误映射 422 VALIDATION_ERROR，表格体积超限为 413 IMPORT_TOO_LARGE。
|
||||
全部挂载入口以 `modules/registry.ts` 为准；完整参数、返回类型、权限和枚举以模块的 module/schemas/service 与 shared 契约为准。
|
||||
本页列常用入口，不重复复制每条路由实现。
|
||||
|
||||
## 身份与班级
|
||||
|
||||
| 方法与路径（省略 /api） | 行为及边界 |
|
||||
| ----------------------------------------------------------------------- | -------------------------------------------------------------- |
|
||||
| POST /auth/login、/auth/class-login | 员工/班级登录，共享登录限流；学生无账号 |
|
||||
| GET /auth/me；POST /auth/logout；PATCH /auth/password | 当前身份、退出、员工本人改密码 |
|
||||
| GET/POST /classes；GET/PATCH/DELETE /classes/:id | 班级查询/管理，写入需 class:manage 与管理员业务断言 |
|
||||
| PATCH /classes/:id/class-account、/classes/:id/head-teacher | 班级凭据/班主任维护 |
|
||||
| PUT /classes/:id/subject-teachers | 任课关系设置，Course 为唯一来源 |
|
||||
| GET/PATCH /classes/:id/student-grade-query | 查看/修改班级个人成绩查询开关，班级端不能修改 |
|
||||
| GET/POST /classes/:id/students；DELETE /classes/:id/students/:studentId | 本班名单及维护，受名单功能权限和班级关系约束 |
|
||||
| /students、/teachers | 名单与账号 CRUD；读/写使用不同权限键，具体角色限制读取对应模块 |
|
||||
| POST /teachers/:id/reset-password | 指定新密码或默认重置；学生无对应接口 |
|
||||
| /permissions/me、/catalog、/groups、/users | 当前有效权限、目录、组与账号分组 |
|
||||
|
||||
## 教学与文件
|
||||
|
||||
| 路径/动作 | 行为及边界 |
|
||||
| ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
||||
| /courses | 班级科目与任课关系 |
|
||||
| GET /schedules、/grid、/current、/active-week | 新关系模型的兼容投影，按班级范围读取 |
|
||||
| POST/PATCH/DELETE /schedules[/:id] | 兼容 CRUD，写新模型，不双写旧 Schedule |
|
||||
| POST /schedules/swap、/overlay、/scheduled；GET /schedules/scheduled；DELETE /schedules/scheduled/:id | 换课、临时层、预定 |
|
||||
| /time-layouts；POST /time-layouts/:id/clone、/:id/import | 时间表 CRUD/克隆/导入，写入 timetable:manage |
|
||||
| /class-plans；PUT /class-plans/:id/entries；PATCH /class-plans/:id/enabled | 日课表 CRUD、整表保存、启用，写入 schedule:write + 班主任/管理员 |
|
||||
| POST /class-plans/:id/clone、/class-plans/import、/class-plans/import/profile；GET /class-plans/:id/export | 复制、导入导出及完整档案导入 |
|
||||
| /class-plan-groups；GET /class-plan-groups/selection；POST /class-plan-groups/select | 群组及当前/临时选择 |
|
||||
| /homeworks、/homeworks/bulk、/:id/status、/:id/submissions | 作业、批量、完成与未交；员工功能键+科目检查，班级端可录作业 |
|
||||
| /notifications、/notifications/bulk、/days、/creators、/unread-count、/:id/read、/read-all | 通知、归档和已读；发布需 notification:publish，课堂紧急须确认 |
|
||||
| POST /calls | 叫人，call:create + 范围检查 |
|
||||
| /grades、/grades/bulk、/stats、/levels、/my、/overview、/collective、/student/:studentNo、/exams、/ranking | [成绩与隐私](../app/grades.md)，查询列表参数用 studentId，写入仍按科目 |
|
||||
| /imports/template、/table/preview、/table/commit | 表格导入，按 kind 再检查角色、导入权限、班级和科目 |
|
||||
| /imports/class-plan/preview、/imports/class-plan | 旧预览与完整档案提交；提交走关系化导入 |
|
||||
| /imports/time-layout[/:id]、/time-layout/preview | 时间配置兼容入口，写入/删除需 timetable:manage |
|
||||
| GET /class-plans/profile?classId= | 完整档案导出，按班级范围读取，保留时间点与课表关联 |
|
||||
| GET /courseware、/courseware/:id、/:id/download | 课件目录/详情/下载；员工需 courseware:read，班级端按可见范围 |
|
||||
| POST /courseware/upload、/:id/push；PATCH /courseware/:id/visibility；DELETE /courseware/:id | 写入 courseware:write + 员工身份；本人文件、任课班级与可见范围限制 |
|
||||
| GET/POST /courseware/folders；PATCH /courseware/:id/folder | 员工 courseware:write；目录与课件均限本人 |
|
||||
| GET /courseware/transfers；POST /courseware/transfers/:id/ack | 班级端补领、逐设备回执 |
|
||||
|
||||
## 设备、系统与运维
|
||||
|
||||
| 路径/动作 | 行为及边界 |
|
||||
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
|
||||
| POST /clients/heartbeat、/clients/commands/:id/ack | 登录设备心跳/回执，校验 deviceKey 和归属 |
|
||||
| POST /clients/update-progress | 设备上传下载、校验、等待、安装和失败状态，校验设备班级归属 |
|
||||
| GET /clients/devices；DELETE /clients/devices/:id | 设备读取/维护，分别检查功能键和范围 |
|
||||
| POST /clients/commands | remote:control + 对应范围，白名单动作 |
|
||||
| POST /clients/updates | client:update，安装策略 immediate/after-school/idle |
|
||||
| GET /update/check | 员工需 update:check；强制刷新另检查 update:force |
|
||||
| GET /update/client/releases | 缓存版本读取，按路由允许的读取权限 |
|
||||
| POST /update/client/fetch、/update/client/releases；DELETE /update/client/releases/:version | 安装包写入口统一 client:update |
|
||||
| GET /update/client/download/:version | 已登录下载，不挂员工权限键，供班级端更新 |
|
||||
| /term；POST /term/auto；GET /term/holidays | 学期读取/编辑/假日建议，term:read/term:write |
|
||||
| GET/PUT /term/promotion；POST /term/promotion/run | 升级计划、预览和执行，system:manage，执行还做业务校验 |
|
||||
| /archives、/archives/transferred、/archives/transferred/:id/restore | 历史归档与撤回转出，archive:manage；不提供创建归档代替年度升级的入口 |
|
||||
| /database/status、/test-connection、/backups、/export、/import、/sqlite-file、/backup-schedule、/switch | database:manage；目标空库、快照及换库子进程保护 |
|
||||
| /system/settings、/autostart、/diagnostics | system:manage，非安装形态自启动返回不可用原因 |
|
||||
| /ai/settings、/interpret、/audit | ai:manage/ai:use；只解析待确认动作，密钥只进不出 |
|
||||
| /dashboard/summary、/dashboard/term | 按范围读取看板与周次 |
|
||||
|
||||
探针 /healthz 和 /readyz 不带 API 前缀；/api/health 提供版本与模块详情。
|
||||
课件上传是原始文件流，512 MB 限制独立于表格 JSON 的 12 MB 限制；metadata 走上传查询 schema。
|
||||
心跳 agentProtocol:2 使用统一响应 data，旧协议兼容字段只用于升级过渡。
|
||||
更多说明见[权限](permissions.md)、[实时事件](realtime.md)、[数据模型](data-model.md)。
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: 架构总览
|
||||
description: 工作区结构、模块注册、共享契约与数据流。
|
||||
---
|
||||
|
||||
# 架构总览
|
||||
|
||||
ClassHelper 是 pnpm workspace：Express/Prisma/Socket.IO 服务端、Vue Web 管理端、Electron 桌面客户端与共享包。
|
||||
依赖版本以根和各包的 `package.json`、`pnpm-lock.yaml` 为准。文档站和纯静态官网不在 workspace 内。
|
||||
|
||||
## 目录与入口
|
||||
|
||||
| 路径 | 职责 |
|
||||
| --------------------------------------------- | ------------------------------------------- |
|
||||
| `packages/shared/src/` | 类型、权限目录、动效、课表/岛/课件契约 |
|
||||
| `packages/server/src/app.ts` | 探针、限流、中间件、模块挂载、静态 Web 托管 |
|
||||
| `packages/server/src/index.ts` | 启动、自检、HTTP、Socket.IO 与退出清理 |
|
||||
| `packages/server/src/modules/registry.ts` | 全部启用模块的唯一注册表 |
|
||||
| `packages/server/src/lib/` | 鉴权范围、日课表解析、周次、快照与系统设置 |
|
||||
| `packages/server/prisma/` | 单一 schema、SQLite 迁移、演示 seed |
|
||||
| `packages/web-admin/src/router/` | Web 路由、标题、图标、权限 |
|
||||
| `packages/web-admin/src/config/navigation.ts` | 菜单分组，页面属性读取路由 |
|
||||
| `packages/desktop-client/src/main/` | 窗口、配置、岛、设备代理、更新、课件下载 |
|
||||
| `packages/desktop-client/src/preload/` | contextBridge 白名单 |
|
||||
| `packages/desktop-client/src/island/` | 经典岛、自定义运行时、课程与课件提醒 |
|
||||
| `packages/desktop-client/src/renderer/` | 主窗口页面、状态、IndexedDB 与岛桥接 |
|
||||
| `scripts/` / `deploy/` | 验证、版本、打包、部署与运维 |
|
||||
| `docs/` / `website/` | 文档站与官网，Pages 构建时拼接 |
|
||||
|
||||
## 模块与数据流
|
||||
|
||||
功能模块使用 `*.module.ts` 路由、`*.schemas.ts` 校验、`*.service.ts` 业务；新增/下线改 `registry.ts`。
|
||||
注册表包含教学业务、课件、日课表/时间表/群组、权限、客户端、系统、AI、升级和数据管理模块。
|
||||
路由与模块总数直接读取注册表，不在文档复制另一份数组。
|
||||
|
||||
教师在 Web 提交 → 服务端校验权限、班级和科目范围 → 写数据库 → 事件总线按房间广播 → Web/客户端刷新。
|
||||
客户端先维护 IndexedDB 缓存，断网读取缓存；主窗口通过 preload 与主进程通信，主进程管理唯一原生岛窗口。
|
||||
课件先流式上传到服务端文件目录，再由客户端下载、验摘要并独立回执。
|
||||
|
||||
## 工程边界
|
||||
|
||||
- 三端契约只放 shared，改后先 `pnpm build:shared`。
|
||||
- 学生不是账号；班级会话读取 `Class`，教师/管理员读取 `User`。
|
||||
- 功能权限在路由判定，范围与科目权限在 service 判定；前端同规则隐藏入口。
|
||||
- 课表以关系模型为真值，所有在线启用选择走 `lib/class-plan.ts`；周次走 `lib/term.ts`。
|
||||
- 作业/通知使用本地 `assignDate`；实时使用 `SOCKET_EVENTS/SOCKET_ROOMS` 和 `emitToClass/emitToSession`。
|
||||
- 数据库备份清单随模型维护，课件文件另行备份。
|
||||
- Electron 保留 CSP 与导航限制，桥接只传纯数据；打包凭据门禁不能取消。
|
||||
- ClassIsland 在线联动已退役，仅保留离线 JSON 导入与设计参考。
|
||||
|
||||
完整规则见 [AGENTS.md](https://github.com/LoveChengke/ClassHelper/blob/master/AGENTS.md)。
|
||||
|
||||
## 开发启动
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
# 复制 packages/server/.env.example 为 .env，并配置独立 JWT_SECRET 与数据库
|
||||
pnpm db:generate
|
||||
pnpm --filter @classhelper/server db:deploy
|
||||
pnpm build:shared
|
||||
# 只有明确需要重建演示数据时才运行 pnpm db:seed（会清空业务表）
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
后端 4000、Web dev 5173、桌面 dev 5174、官网 5180、文档预览 5181。
|
||||
生产服务端托管已构建的 Web 管理端；详见[安装服务端](../get-started/server.md)和[验收](testing.md)。
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: 数据模型
|
||||
description: 现行模型职责、迁移与快照边界。
|
||||
---
|
||||
|
||||
# 数据模型
|
||||
|
||||
模型定义以 `packages/server/prisma/schema.prisma` 为准，迁移以 `prisma/migrations/` 为准。
|
||||
仅维护一份 schema，SQLite/MySQL 切换改 provider；不使用 Prisma enum 和 `@db.*`。
|
||||
|
||||
## 模型职责
|
||||
|
||||
| 模型 | 职责 |
|
||||
| ---------------------- | -------------------------------------------------- |
|
||||
| `User` | 教师与管理员账号；学生不在此表，班级凭据在 Class |
|
||||
| `Student` | 学生名单、学号、在读/转出/毕业状态，无密码和角色 |
|
||||
| `StudentClassTransfer` | 调班与转出历史，保留班级/姓名快照 |
|
||||
| `ArchivedYear` | 毕业届别与统计快照 |
|
||||
| `TermWeek` | 逐周日期区间，classId 空串为全校默认 |
|
||||
| `Class` | 班级、班级码/密码、班主任、周数与成绩查询开关 |
|
||||
| `Course` | 班级+科目+教师任课关系，含简称和室外标记 |
|
||||
| `Schedule` | 旧课表迁移审计来源，现行接口不再以它为业务真值 |
|
||||
| `Homework` | 作业与本地 assignDate；dueAt 为遗留列 |
|
||||
| `HomeworkStatus` | 按 studentId 记录作业完成状态 |
|
||||
| `Notification` | 通知/叫人记录、优先级与本地 assignDate |
|
||||
| `NotificationRead` | 按 studentId 记录已读 |
|
||||
| `TimeLayout` | 共享或班级自有时间表；旧 items JSON 保留迁移审计 |
|
||||
| `Grade` | studentId、课程、考试、分数和等级 |
|
||||
| `PermissionGroup` | 默认/自定义/岗位组及 scope/scopeValue |
|
||||
| `PermissionGroupItem` | 组内权限键 |
|
||||
| `UserPermissionGroup` | 账号与组的多对多分配 |
|
||||
| `AppSetting` | 周次、升级、AI 和系统设置 |
|
||||
| `ClientDevice` | deviceKey、心跳、更新目标与状态 |
|
||||
| `ClientCommand` | 白名单远控、有效期与执行回执 |
|
||||
| `ClientRelease` | 服务端缓存安装包、SHA256 与大小 |
|
||||
| `AiAudit` | 助手解析审计，不保存 API Key |
|
||||
| `Exam` | 考试名称与是否计入总分 |
|
||||
| `TimeLayoutItem` | 有序时间点及类型，被课程显式引用 |
|
||||
| `ClassPlanGroup` | 班级课表群组、全局/默认标记 |
|
||||
| `ClassPlan` | 日课表、时间表、轮换、启用与临时层规则 |
|
||||
| `ClassPlanEntry` | 日课表与时间点、课程的外键关联、空课/停用/换课标记 |
|
||||
| `ScheduledClassPlan` | 按本地日期预定日课表 |
|
||||
| `PromotionRun` | 年度升级幂等与审计 |
|
||||
| `Courseware` | 文件元数据、上传教师、存储路径与 SHA256 |
|
||||
| `CoursewareFolder` | 教师自建分类目录，按上传者隔离 |
|
||||
| `CoursewareVisibility` | 课件可见班级 |
|
||||
| `CoursewarePush` | 按班级的推送任务 |
|
||||
| `CoursewareReceipt` | 按设备的课件接收回执 |
|
||||
|
||||
学生和账号分离：Student 没有密码/角色；教师/管理员存 User，CLASS_DEVICE 只是 Class 登录形成的会话。
|
||||
任课关系只在 Course；班主任关系在 Class.teacherId，可以与任课关系指向同一账号。
|
||||
课表真值是 ClassPlan/ClassPlanEntry/TimeLayoutItem，旧 Schedule 与 TimeLayout.items 不再参与现行业务写入。
|
||||
周次口径见[课表](../app/schedules.md)，成绩限制见[成绩](../app/grades.md)。
|
||||
|
||||
## 迁移与启动
|
||||
|
||||
不要删除或重写已应用的 SQLite 迁移目录。源码开发使用 `pnpm --filter @classhelper/server db:deploy`。
|
||||
安装形态由 `lib/db-bootstrap.ts` 执行启动迁移，账本 `_ch_migrations` 记录已执行目录。
|
||||
升级迁移包含学生表拆分、联动退役、关系化课表、权限范围、年度升级和课件表；具体顺序读取 migrations。
|
||||
历史学生迁移中的 STUDENT 只用于搬运旧数据，不是现行账号角色。
|
||||
MySQL 建模走受支持的换库流程，不能直接执行 SQLite SQL，详见[MySQL](../management/mysql.md)。
|
||||
|
||||
## 快照与文件
|
||||
|
||||
`lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 是备份/导入/跨库迁移表清单，按依赖顺序导出，恢复阶段临时关闭外键检查并分批写入。
|
||||
模型新增或删除必须同步此清单；不要在文档复制固定表数。
|
||||
JSON 快照包含课件元数据、可见范围、推送与回执，**不含文件实体**；完整备份需带上课件目录。
|
||||
User.careMode 是预留列；当前 Web 偏好在 localStorage，客户端偏好在本机 config.json，不宣称已有跨设备同步。
|
||||
|
||||
## 修改模型时
|
||||
|
||||
1. 同步 schema、迁移、shared 契约、服务层、相关前端与快照清单。
|
||||
2. 核对外键级联与删除护栏，特别是教师的班级、课程、作业、通知和课件。
|
||||
3. 在临时库验证新建和旧库升级；不对真实业务库运行 seed/reset。
|
||||
4. 重新生成 Prisma Client，并按修改范围执行[验收](testing.md)。
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: 当前实现约定
|
||||
description: 课表、周次、学年、岛、设备与课件的现行实现入口。
|
||||
---
|
||||
|
||||
# 当前实现约定
|
||||
|
||||
本页维护当前工作区的实现契约，不汇总多批构建的验收数字。验证命令与实际范围见[验收与测试](testing.md)。
|
||||
|
||||
## 关系化课表
|
||||
|
||||
`ClassPlan/ClassPlanEntry/TimeLayoutItem` 是业务真值。时间点外键独立于排序，`Schedule` 与旧 JSON 列仅保留迁移审计来源。
|
||||
兼容 `/schedules` 写入新模型，日课表、周视图和上课状态共用 `lib/class-plan.ts`。
|
||||
解析顺序是预定、当日临时课表、同日临时层、有效临时群/选定或默认群的规则匹配、全局群、无群默认。
|
||||
轮换使用 weekday/weekCountDiv/weekCountDivTotal 与周次范围，支持 1–9 周；没有新增 Profile 实体。
|
||||
完整档案导入直接保留轮换、空课、停用、时间类型、群组与预定，不经过单双周中间格式。
|
||||
旧数据同班同日同周同时间冲突仅最小 id 进入新表，旧行保留；缺失的历史群组、临时层与时间点名称无法恢复。
|
||||
|
||||
## 权限、成绩与年度升级
|
||||
|
||||
默认权限组、岗位范围、科目写权限分别由 permissions/permission-scope/access 维护，范围并集不授予任课权。
|
||||
全校周数上限在 `term.maxWeeks`，默认 30、允许 1–60；开学日和逐周区间支持全校与班级设置。
|
||||
个人成绩查询关闭后只返回服务端集体聚合，个人明细、原始全班成绩与排名拒绝读取；样本不足或稀疏分段抑制。
|
||||
年度升级由 `term.promotionAt` 和 `PromotionRun.year` 管理，先存快照；运行期到点执行，启动漏跑需管理员预览补跑。
|
||||
毕业班归档，其余升一级，新班不复制任课关系。转出学生由 `lib/students.ts` 统一过滤。
|
||||
|
||||
## 岛与本机配置
|
||||
|
||||
方案存 `config.json.islandLayout`，默认 fixed。当前 custom 即常驻，归一化将兼容字段 residentEnabled 与 custom 对齐。
|
||||
`LayoutIslandApp.vue` 选择经典 `IslandApp.vue` 或 `CustomIslandRuntime.vue`，只有一个原生岛窗口。
|
||||
自定义常态行与无消息展开行独立编辑，通知列表复用 `ClassicNotifications.vue`；编辑页是主窗口设置子路由。
|
||||
自定义模式通过铃铛提示新消息，点击查看；经典模式普通通知上课暂存、普通叫人可点开胶囊、紧急消息自动展开。
|
||||
课程提醒配置独立保存，课件传输期间由 `CoursewareTransfer.vue` 显示进度。
|
||||
|
||||
## 设备维护与文件
|
||||
|
||||
设备心跳和命令只走 `/api/clients/*`。切服务端或登录状态变化要重置代理计时，并隔离迟到响应；deviceKey 不变。
|
||||
更新从服务端缓存下载，客户端验 SHA256，按下发策略安装；远控白名单动作执行后回执，测试只用假执行器。
|
||||
课件上限 512 MB，服务端流式落盘后创建元数据和推送，客户端逐设备验摘要并回执，不自动运行文件。
|
||||
JSON 快照含课件表，完整恢复还必须带文件实体目录。细节见[课件](../app/courseware.md)。
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
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) | 模型职责、迁移与快照边界 |
|
||||
| [角色与权限](permissions.md) | 权限矩阵与实现位置 |
|
||||
| [动效层与主题](motion.md) | beUI 令牌、CSS `linear()` 弹簧、深色主题 |
|
||||
| [灵动岛设计令牌](winisland-design-tokens.md) | 岛逐项的几何 / 配色 / 排版 token |
|
||||
| [验收与测试](testing.md) | 隔离验收、后台冒烟与显式视觉模式 |
|
||||
| [版本迭代与发布](release.md) | 改版本号、出安装包、发 Release 的完整流程 |
|
||||
|
||||
## 仓库里另外两份文档
|
||||
|
||||
- **[功能与源码索引](../reference.md)** —— 各帮助章节与源码入口的统一索引；功能行为在对应章节维护，按源码核验。
|
||||
- **[`AGENTS.md`](https://github.com/LoveChengke/classhelper/blob/master/AGENTS.md)** ——
|
||||
工程约定与开发环境注意事项，**改代码前必读**。里面每一条硬约定都对应一处容易踩空的地方，
|
||||
规则与实际实现冲突时应查源码并同步修正。
|
||||
@@ -0,0 +1,138 @@
|
||||
---
|
||||
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：从点击位置扩散的圆整页换肤 |
|
||||
| 灵动岛 | 独立 SpringValue 帧积分与过冲钳制，见设计令牌 |
|
||||
|
||||
### 灵动岛使用独立弹簧
|
||||
|
||||
经典与自定义岛的形变使用 `src/island/spring.ts` 的 SpringValue，渲染层驱动岛体几何，主进程管理原生窗口与命中。
|
||||
它与 shared/motion.ts 的 CSS 弹簧是不同实现，不能互相替换参数。默认阻尼、换向与过冲钳制见[设计令牌](winisland-design-tokens.md)。
|
||||
岛动画由应用开关及可见性控制，主窗口 prefers-reduced-motion 规则不直接替代岛自身设置。
|
||||
|
||||
另外岛的 `: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 管理端的侧边栏
|
||||
（本来就是深色）、以及深色底上的白色文字。**改它们会被当成回归。**
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: 角色与权限
|
||||
description: 功能权限、岗位范围与班级科目边界。
|
||||
---
|
||||
|
||||
# 角色与权限
|
||||
|
||||
授权分为功能权限、数据范围和业务关系三层，任何一层拒绝都不能操作。
|
||||
shared 的 `permissions.ts` 定义键、标签、默认模板与班级关系规则；服务端 `lib/permissions.ts`、
|
||||
`lib/permission-scope.ts`、`lib/access.ts` 分别计算生效键、查询范围和具体业务断言。
|
||||
|
||||
## 身份与权限组
|
||||
|
||||
账号角色为 ADMIN、TEACHER；班级登录形成 CLASS_DEVICE 会话。学生是 Student 名单，不是账号。
|
||||
HEAD/SUBJECT 是班级关系，级长/部长是岗位组，均不新增 User.role。
|
||||
|
||||
| 情况 | 有效功能权限 |
|
||||
| ------------ | ----------------------------------------------------- |
|
||||
| 已分配权限组 | 所有分组键的并集，可以比角色默认更少 |
|
||||
| 没有分组 | 数据库对应角色的可编辑默认组 |
|
||||
| ADMIN | 同上，始终额外保留 permission:manage 与 system:manage |
|
||||
| CLASS_DEVICE | 空集；通过明确允许班级会话的接口与业务断言操作 |
|
||||
|
||||
每请求读取生效权限，编辑后无需等待令牌过期。内置组可改不可删，默认组不是写死的全权限快捷方式。
|
||||
路由使用 requirePermission（AND）、requireAnyPermission（OR），员工与班级端共享读取入口按 requireStaffPermission 等规则检查。
|
||||
具体 API 的额外角色限制以模块路由和服务断言为准，不能把“默认只分配给管理员”写成所有接口硬编码 ADMIN。
|
||||
|
||||
## 数据范围与科目
|
||||
|
||||
| 岗位/身份 | 范围 |
|
||||
| ----------- | --------------------------------------------- |
|
||||
| 管理员 | 全部班级；仍须功能键 |
|
||||
| 班主任/教师 | 自己担任班主任或任课的班级，按分组 scope 收敛 |
|
||||
| 级长 | 配置年级 |
|
||||
| 部长 | 配置的一组年级，scopeValue 用逗号分隔 |
|
||||
| 班级端 | 登录绑定班级 |
|
||||
|
||||
空年级/部配置不放行。设备写操作只合并含对应功能键的分组范围，不能借只读组扩权。
|
||||
科目编辑再由 `assertCanManageSubjectContent` 检查：管理员可管理，教师仅自己任课科目，无科目内容归班主任。
|
||||
班主任不任教某科就不能改该科的作业或成绩；班级端只允许作业写入，不能写成绩。
|
||||
|
||||
| 业务 | 主要功能键与额外边界 |
|
||||
| ---------------- | ---------------------------------------------------------------------------- |
|
||||
| 名单读取/管理 | roster:read / roster:manage；管理仍须管理员或本班班主任断言 |
|
||||
| 教师列表/维护 | teacher:read / teacher:manage；导入名单另检查导入权限和角色 |
|
||||
| 日课表写入 | schedule:write + 管理员/本班班主任 |
|
||||
| 全校时间表写入 | timetable:manage；默认给 ADMIN |
|
||||
| 作业/成绩 | homework:write / grade:write 或 grade:import，再按班级科目收口 |
|
||||
| 通知/叫人 | notification:publish / call:create，再检查班级范围 |
|
||||
| 课件 | courseware:read / courseware:write，上传和推送自己的文件还受本人授课班级约束 |
|
||||
| 客户端维护/远控 | client:read、client:manage、remote:control，写操作按对应键范围 |
|
||||
| 版本与安装包写入 | client:update；旧 client:update-push 不再作为写入口要求 |
|
||||
| 数据库/系统/权限 | database:manage / system:manage / permission:manage |
|
||||
|
||||
完整键目录读取 `PERMISSION_KEYS`，不在文档维护固定键数。
|
||||
|
||||
## 前端门控与成绩隐私
|
||||
|
||||
Web 菜单属性来自路由，`meta.roles` 粗筛、`meta.permission` 细筛；先 ensurePermissions 再按生效集合判断。
|
||||
服务端仍检查功能、范围与业务关系，直接构造请求不能绕过。
|
||||
岗位范围可以扩大读范围，不能自动扩大科目写权限，也不能替代课件的本人任课关系。
|
||||
班级成绩查询开关仅员工按业务权限修改；关闭后班级端仍看集体聚合，个人明细、原始全班成绩和排名返回拒绝。
|
||||
稀疏分段与补集抑制，服务端不向客户端下发个人原始成绩再聚合。
|
||||
|
||||
## 设备维护
|
||||
|
||||
`/api/clients/heartbeat` 和命令回执供已登录设备使用，不依赖班级端的空权限集合；服务端校验 deviceKey 与班级归属。
|
||||
远控从管理端确认下发，客户端执行后回传真实结果。更新文件由服务端缓存，教室机验 SHA256，
|
||||
按立即、放学后、空闲策略安装；关闭自动更新不会强制安装。详见[更新与升级](../management/upgrade.md)。
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: 实时事件（Socket.IO）
|
||||
description: 实际事件与房间、断线恢复和客户端提醒分工。
|
||||
---
|
||||
|
||||
# 实时事件（Socket.IO）
|
||||
|
||||
连接使用 `io(url, { auth: { token } })`，服务端在握手校验 JWT。
|
||||
事件与房间定义在 shared 的 `constants.ts`，载荷类型在 shared 的 `types.ts`，以这些契约和发送点为准。
|
||||
|
||||
## 房间与定向推送
|
||||
|
||||
| 房间 | 作用 |
|
||||
| --------------- | -------------------------------------------------- |
|
||||
| class:{classId} | 某班级的业务广播 |
|
||||
| session:{id} | 会话定向名；员工 id 为账号 id，班级端 id 为班级 id |
|
||||
| role:{role} | 角色房间名，定义在共享常量 |
|
||||
| teacher:{id} | 教师房间名，定义在共享常量 |
|
||||
| students | 班级端连接的广播房间，代表全班，不是个人学生账号 |
|
||||
| teachers | 教师和管理员连接的广播房间 |
|
||||
|
||||
`realtime/socket.ts` 当前显式 join 可访问的 class 房间与 students/teachers 广播房间；
|
||||
同时在 connected 载荷列出 session/role 名。不能把共享常量或该列表当成所有房间均已成功 join 的证明，实际订阅以 join 调用为准。
|
||||
业务经 `realtime/bus.ts` 的 emitToClass/emitToSession/emitToRooms 推送。
|
||||
叫人记录属于班级通知，并发送班级广播与班级会话定向事件；学生本身没有连接和个人房间。
|
||||
|
||||
## 主要事件
|
||||
|
||||
| 事件 | 内容 |
|
||||
| ------------------------------------------------- | ---------------------------------------------------------- |
|
||||
| connected | `{ sessionId, role, rooms }` |
|
||||
| notification:new / notification:deleted | 通知新增/撤回；客户端同步列表、缓存和岛队列 |
|
||||
| homework:new / homework:updated / homework:status | 作业新增、修改/删除与完成状态 |
|
||||
| grade:updated | 成绩变化通知；载荷按范围与隐私规则发送，客户端按需重新读取 |
|
||||
| schedule:updated / class:updated | 课表/班级变化，重新加载对应数据 |
|
||||
| courseware:changed | 课件列表/可见范围/推送变化，触发客户端检查 |
|
||||
| client:release-progress | 服务端缓存客户端安装包的进度 |
|
||||
| call:new | 叫人内容，与 notification:new 按同 id 合并去重 |
|
||||
| class:join / class:leave / ping | 客户端订阅/离开班级、探活；join 重新校验范围 |
|
||||
|
||||
事件没有持久离线消息队列保证。重连后由页面和恢复钩子重新拉取业务数据。
|
||||
普通通知上课暂存是客户端岛控制器的本机行为，服务端仍即时落库广播；
|
||||
断线通知补弹由客户端未读读取逻辑处理，课件未收任务由服务端保存、客户端心跳补领。
|
||||
经典/自定义模式的展示差异见[通知与提醒](../app/notifications.md)。
|
||||
|
||||
## 修改事件
|
||||
|
||||
同步修改共享事件名与载荷、服务端发送点、Web `stores/realtime.ts`、客户端 `stores/realtime.ts` 及相关缓存/岛逻辑。
|
||||
不要手写事件名；只改服务端会导致前端静默不刷新。涉及成绩时另检查隐私载荷和班级范围。
|
||||
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: 版本迭代与发布
|
||||
description: 版本单一来源、本地与发布文件名、验证和发布同步。
|
||||
---
|
||||
|
||||
# 版本迭代与发布
|
||||
|
||||
日常文档/代码维护不自动改版本。版本唯一修改入口是 scripts/version.mjs；先执行 pnpm version:check。
|
||||
正式新发布执行 pnpm version:bump patch|minor|major，指定固定版本的本地重构建保持版本不变。
|
||||
版本落点由脚本清单决定，不另维护“文件数/落点数”。
|
||||
|
||||
## 构建与验证
|
||||
|
||||
```bash
|
||||
pnpm version:check
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
pnpm check:icons
|
||||
pnpm docs:check
|
||||
pnpm verify:e2e
|
||||
pnpm verify:v14
|
||||
pnpm verify:courseware
|
||||
pnpm build:desktop
|
||||
pnpm verify:desktop
|
||||
pnpm --filter @classhelper/web-admin build
|
||||
pnpm verify:web:isolated
|
||||
pnpm dist:all
|
||||
pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版本>-x64-portable.exe" --offline
|
||||
```
|
||||
|
||||
以上按发布改动范围执行；显式 --visual 才是桌面视觉验收。测试数量和结果必须来自本次输出。
|
||||
完整边界见[验收](testing.md)。同号本地重构建先保留可恢复副本，最新包核验完成后按用户要求清理旧归档。
|
||||
2026-10-18 工作区清理后，1.4.0 仅保留当前 client/server 目录和当前更新日志/校验清单。
|
||||
|
||||
## 产物与文件名
|
||||
|
||||
| 本地构建产物 | GitHub Release 上传名 |
|
||||
| --------------------------------------------------------------------------- | ------------------------------------------ |
|
||||
| releases/client/<版本>/安装包/ClassHelper-<版本>-x64-setup.exe | ClassHelper-<版本>-x64-client-setup.exe |
|
||||
| releases/client/<版本>/安装包/ClassHelper-<版本>-x64-portable.exe | ClassHelper-<版本>-x64-client-portable.exe |
|
||||
| releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe | ClassHelper-<版本>-x64-server-setup.exe |
|
||||
| releases/server/<版本>/linux-x64/classhelper-server-linux-x64-<版本>.tar.gz | 同名 |
|
||||
|
||||
Linux 还需同名 .tar.gz.sha256。正式 Linux 包在 Linux runner 运行 pnpm dist:server:linux；
|
||||
Windows 上的交叉构建仅作验证，可能缺目标平台的 Prisma engine。
|
||||
构建中间物可再生成，不将 win-unpacked、server staging 或解包副本当交付物保留。
|
||||
|
||||
## 更新日志与校验
|
||||
|
||||
releases/ReleaseNotes-<版本>.md 维护本批包的功能、升级须知、实际验证范围与文件清单。
|
||||
它描述该构建批次，不能把之后的源码功能写成旧包已经包含。
|
||||
SHA256SUMS-<版本>.txt 用上传名记录各文件哈希；本地查验必须先按上表映射，不能因为本地文件没带 client/server 后缀就判断丢包。
|
||||
可在 PowerShell 对 client/server 安装包运行 Get-FileHash -Algorithm SHA256，将三项实际结果按上传名写入清单。
|
||||
不要仅对客户端目录做重定向而漏掉服务端；Linux 行待 CI 完成后同步。
|
||||
|
||||
## 发布同步
|
||||
|
||||
完成验证和本地更新日志后，检查 diff，按用户授权提交和推送 master；不要把其他未完成改动一并提交。
|
||||
将三个 Windows 包复制到独立的 .cache/release-staging/<版本>/，使用上传名，避免通配符混入别的版本。
|
||||
先准备当前 Windows SHA256 清单并随 Release 上传。创建 Release 时显式 --target master 或明确提交，说明用 --notes-file。
|
||||
ClassIsland 插件已退役，不再上传插件资产。
|
||||
|
||||
```bash
|
||||
# <版本> 和提交均替换为本次实际值
|
||||
gh release create v<版本> --target master --title "ClassHelper v<版本>" --notes-file releases/ReleaseNotes-<版本>.md
|
||||
gh release upload v<版本> <三个已按上传名暂存的EXE> releases/SHA256SUMS-<版本>.txt
|
||||
```
|
||||
|
||||
推送 v* tag 触发 release-linux-server.yml，按 tag 检出，在 Ubuntu 构建并上传 Linux 包、独立 .sha256，合并跨组件清单。
|
||||
等待 Actions 成功，再下载 Linux 文件和最终 SHA256SUMS 同步回本地；检查清单的 Windows 行仍与本次文件一致。
|
||||
如需重跑，可手动运行该 workflow，指定准确 tag 和 attach=true。master 修复不会自动改变旧 tag 指向。
|
||||
|
||||
官网和文档站由 pages.yml 拼装同一个站点：官网根、文档 /docs/。文档版本徽标读根 package.json，
|
||||
官网和下载页兜底版本由 version 脚本维护。Linux workflow 与 Pages 是独立流水线，分别确认结果。
|
||||
官网行为变化同步 README 与相应帮助章节，功能索引放[源码索引](../reference.md)。
|
||||
|
||||
## 已发布版本与回滚
|
||||
|
||||
已公开且用户安装的版本建议发补丁版本修复，避免同号不同内容使更新缓存/忽略版本与摘要失配。
|
||||
用户明确要求固定版本重构建时，按要求保持版本，并清楚区分本地包和远端资产；不自动改远端 tag/Release。
|
||||
仅说明或文档错误直接修改说明/文档；线上故障按对应部署形态从完整备份恢复。
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: 验收与测试
|
||||
description: 隔离 API、隐藏 UI、后台客户端与显式视觉验收。
|
||||
---
|
||||
|
||||
# 验收与测试
|
||||
|
||||
按改动范围选择验证；数量和结果读取本次输出，不沿用历史报告数字。
|
||||
默认客户端冒烟为后台快速模式；动画、透明度、桌面截图必须显式视觉模式。
|
||||
|
||||
## 命令与前置条件
|
||||
|
||||
| 命令 | 覆盖/前置条件 |
|
||||
| ------------------------------------------------ | ----------------------------------------------------------------- |
|
||||
| pnpm lint / pnpm typecheck / pnpm check:icons | 静态检查；typecheck 会先构建 shared |
|
||||
| pnpm docs:check | docfx 严格构建，需 .NET SDK 与 docfx |
|
||||
| pnpm verify:e2e | 自动临时 SQLite、种子和带前缀账号，启动随机端口服务；无需真实服务 |
|
||||
| pnpm verify:web:isolated | 同上隔离服务，隐藏 Electron UI 回归；先构建 Web 产物 |
|
||||
| pnpm verify:web | 连接已准备测试服务，需 Web 产物和测试管理员；不应指向业务服务 |
|
||||
| pnpm verify:v14 | 临时库验证关系课表、周次、范围、隐私与升级等 |
|
||||
| pnpm verify:courseware | 临时库和文件目录的课件专项，不向真实班级推送 |
|
||||
| pnpm verify:client-agent | 假系统适配器验证命令、回执和更新策略 |
|
||||
| pnpm verify:client-migrations | 临时旧库验证迁移、联动退役与默认组持久化 |
|
||||
| pnpm verify:review-client | 无窗口逻辑回归 |
|
||||
| pnpm verify:review-api / pnpm verify:clients-api | 需明确准备的隔离测试服务，使用 VERIFY_BASE_URL 等脚本参数 |
|
||||
| pnpm verify:desktop | 先 pnpm build:desktop；隐藏快速检查，独立 userData |
|
||||
| pnpm verify:desktop:online | 显式联网，需要测试管理员并创建临时教师/班级 |
|
||||
| pnpm verify:desktop:visual | 显式使用桌面，完整岛几何/动画/透明度/截图检查 |
|
||||
| pnpm verify:packaged --exe <客户端EXE> | 默认快速离线，两次启动、packaged=true；--visual 才使用桌面 |
|
||||
|
||||
联网 packaged 使用 --online；调用方须预先准备隔离服务、临时教师和班级并显式注入凭据，该启动器不会自动创建它们。
|
||||
开发版 verify:desktop:online 则通过 provisionSmokeClass 创建和清理临时身份。--offline 保持离线。
|
||||
不得回退到真实班级、重置真实密码或向真实班级发测试通知；远控与安装器使用假执行器。
|
||||
桌面进程超时和失败日志先定位，不能因为一个历史脆弱用例名称就断言当前失败必然正常。
|
||||
|
||||
## 常用检查顺序
|
||||
|
||||
```bash
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
pnpm check:icons
|
||||
pnpm docs:check
|
||||
pnpm verify:e2e
|
||||
pnpm verify:v14
|
||||
pnpm verify:courseware
|
||||
pnpm build:desktop
|
||||
pnpm verify:desktop
|
||||
pnpm --filter @classhelper/web-admin build
|
||||
pnpm verify:web:isolated
|
||||
```
|
||||
|
||||
仅文档修改只需格式、链接与 docs:check；不因此重打包或占用桌面。
|
||||
改打包/运行时裁剪还要构建实际副本并跑 packaged；Linux 交付修改需 Linux 真机/CI 验证和 bash 语法检查。
|
||||
|
||||
## 故障定位
|
||||
|
||||
- 临时服务失败查 .cache/v14-verification 下本次日志；不要改业务 .env 或密码迁就测试。
|
||||
- 显式联网管理员变量：桌面 ELECTRON_SMOKE_ADMIN/ELECTRON_SMOKE_ADMIN_PASSWORD，Web UI_SMOKE_ADMIN/UI_SMOKE_ADMIN_PASS。
|
||||
- 视觉用例需要真实桌面与稳定帧，先区分状态未稳定、窗口遮挡和实际回归，再针对原因重跑。
|
||||
- Element Plus dialog 关闭后 DOM 仍保留，应检查 overlay 的可见状态。
|
||||
- 本地 HTTP 探测绕过代理；Prisma 生成物和 shared/dist 缺失时先补前置构建。
|
||||
|
||||
## 截图
|
||||
|
||||
docs/images 为 README/文档展示图；docs/screenshots 为回归留档；website/assets/shots 为官网素材。
|
||||
只把显式视觉验收采集、人工确认过的正片用作展示，不把窗口对照图或旧失败截图直接发布。
|
||||
Web 采集入口 `website/tools/capture-shots.mjs`，先准备隔离测试服务和数据。
|
||||
岛/客户端采集使用 smoke.mjs --visual，并按需 --online；ISLAND_SHOTS_DIR 与 ELECTRON_CLIENT_SHOTS_DIR 指向临时目录。
|
||||
日常 quick 模式不会生成完整视觉截图，不能把 quick 通过表述为动画/透明度已验证。
|
||||
@@ -0,0 +1,23 @@
|
||||
- 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: 版本迭代与发布
|
||||
href: release.md
|
||||
|
||||
- name: 当前实现约定
|
||||
href: implementation.md
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: 灵动岛设计令牌
|
||||
description: 本地经典/自定义岛的几何、外观与动画入口。
|
||||
---
|
||||
|
||||
# 灵动岛设计令牌
|
||||
|
||||
经典岛以 WinIsland 的连续圆角和形变为设计参考，自定义组件行以 ClassIsland 为参考。
|
||||
当前数值与行为以本仓库 shared 常量和渲染实现为准；本页不把上游音乐/歌词/媒体功能列为 ClassHelper 功能。
|
||||
|
||||
## 经典几何与外观
|
||||
|
||||
| 来源 | 内容 |
|
||||
| ---------------------------------------------------- | ----------------------------------------------------- |
|
||||
| shared/src/constants.ts 的 DEFAULT_ISLAND_APPEARANCE | 默认宽 268、高 44、圆角 20、字号 13、边距 8，顶部居中 |
|
||||
| ISLAND_APPEARANCE_RANGES | 滑块与主进程归一化共用的范围 |
|
||||
| ISLAND_SIZE_DELTA | 展开、紧急与叫人相对尺寸 |
|
||||
| ISLAND_SHADOW_PAD | 窗口边界的透明留白 |
|
||||
| ISLAND_LIST_METRICS / islandListLayout | 主进程和渲染层共用列表度量，控制行数与工作区高度 |
|
||||
| desktop-client/src/island/squircle.ts | 超椭圆路径 |
|
||||
| desktop-client/src/island/classic-island.css | 经典底色、文字、图形与状态样式 |
|
||||
|
||||
classic 的 black/glass/tinted 是本地 CSS 外观；glass 使用半透明色，不采样桌面模糊。
|
||||
不要对透明岛调用 setBackgroundMaterial：系统材质作用于整窗矩形，可能破坏逐像素透明。
|
||||
投影常驻，只随形态改参数，避免切换 filter 创建合成表面的闪帧。
|
||||
默认停靠中线不受左右边距影响，只有左/右停靠使用水平边距。
|
||||
|
||||
## 自定义常驻行
|
||||
|
||||
CLASSISLAND_ISLAND_METRICS 位于 shared/src/island-layout.ts：
|
||||
|
||||
| 参数 | 本地值 |
|
||||
| ----------------------- | -------------------- |
|
||||
| 单行基准高度 / 水平留白 | 40 / 12 px |
|
||||
| 次要/正文/强调/大字号 | 14 / 16 / 18 / 20 px |
|
||||
| 默认缩放 / 范围 | 1 / 0.75–2.5 |
|
||||
| 默认圆角 / 最大 | 8 / 20 px |
|
||||
| 默认不透明度 / 行距 | 0.5 / 5 px |
|
||||
| 鼠标避让淡化比例 | 0.05 |
|
||||
|
||||
方案有常态 rows 和无通知展开 expandedRows，运行时由 CustomIslandRuntime.vue 测量自然内容，
|
||||
再按屏幕工作区与方案缩放适配。字体与外观覆盖按组件契约生效，不能拿经典固定宽高解释自定义内容尺寸。
|
||||
|
||||
## 动画与命中
|
||||
|
||||
经典与自定义岛的形变都使用 src/island/spring.ts 的 SpringValue；默认 stiffness=0.10、damping=0.68，
|
||||
换向保留部分动量，按剩余距离限速并钳制过冲。不同用途可能覆盖 snapThreshold 等参数，以调用点为准。
|
||||
这是独立的帧积分，不等同于主窗口 shared/motion.ts 的 CSS 弹簧。
|
||||
应用内动画开关、原生窗口可见性与文档可见性控制运行时动画和静止落定。
|
||||
|
||||
鼠标模式按光标命中控制穿透；触摸模式处理贴合、输入区域与失焦宽限，自定义常驻模式还维护独立交互入口和窗口形状。
|
||||
几何改变时同步实际窗口、命中矩形和测量，不在动画中反推自然尺寸。
|
||||
视觉验收必须显式 --visual；本页数值不代表本次已完成像素验收。
|
||||
|
||||
## 修改入口
|
||||
|
||||
外观范围改 shared，经典样式改 classic-island.css，自定义样式改 custom-runtime.css 和 custom-island.css，
|
||||
原生窗口与命中改 main/island.ts。组件结构/设置改 shared/island-layout.ts 并同步编辑器和运行时。
|
||||
展示行为见[灵动岛](../app/island.md)，测试见[验收与测试](testing.md)。
|
||||
@@ -0,0 +1,38 @@
|
||||
{
|
||||
"$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
@@ -0,0 +1,137 @@
|
||||
---
|
||||
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 升级了吗？
|
||||
|
||||
### 屏幕上出现了第二个灵动岛，点它反应不对
|
||||
|
||||
先确认是否有人显式运行了 `verify:desktop:visual` 或 `verify:packaged --visual`；视觉实例由脚本控制，会自行开合。
|
||||
默认 `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 与日志编码等）
|
||||
记在仓库的 [`AGENTS.md`](https://github.com/LoveChengke/classhelper/blob/master/AGENTS.md) 里；
|
||||
- 功能行为的权威说明在[完整参考](reference.md)；
|
||||
- 都不是的话，去 [Issues](https://github.com/LoveChengke/classhelper/issues) 提一个，
|
||||
附上版本号（Web 端顶栏 / 客户端「设置 → 关于」里都有）和日志。
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
title: 装 ClassHelper 班级端
|
||||
description: 在教室机器上安装 ClassHelper桌面客户端，用班级码登录，并第一次跑通实时通知。
|
||||
---
|
||||
|
||||
# 装 ClassHelper 班级端
|
||||
|
||||
桌面客户端装在**教室的那台机器**上（教室大屏、讲台电脑）。它是学生看课表作业的地方，
|
||||
也是「消息到达的第一现场」—— 灵动岛就长在这一端。
|
||||
|
||||
## 1. 下载与安装
|
||||
|
||||
从 [Releases](https://github.com/LoveChengke/classhelper/releases) 取：
|
||||
|
||||
| 产物 | 用途 |
|
||||
| --------------------------------------------------------------------- | ------------------------------------------ |
|
||||
| `ClassHelper-<版本>-x64-client-setup.exe`（本地构建名不带 client） | 安装包（约 98 MB），装到本机并建快捷方式 |
|
||||
| `ClassHelper-<版本>-x64-client-portable.exe`（本地构建名不带 client） | 单文件便携版，双击即用，适合不改动机房机器 |
|
||||
|
||||
要自己打：
|
||||
|
||||
```bash
|
||||
pnpm dist:win # 安装包 + 便携版（两个都是成品，没有中间的解包目录）
|
||||
```
|
||||
|
||||
> **双击没反应？** 关窗只是隐藏到托盘，进程还在，再双击会因单实例锁秒退 —— 先从托盘右键退出。
|
||||
|
||||
## 2. 登录
|
||||
|
||||
打开客户端 → 填三项：
|
||||
|
||||
| 字段 | 填什么 |
|
||||
| ---------- | ------------------------------------------------------------- |
|
||||
| 服务器地址 | `http://<服务器IP>:4000`（局域网用内网 IP，别用 `localhost`） |
|
||||
| 班级码 | 管理员在「班级管理」里给这个班设的码，例如 `G203` |
|
||||
| 班级密码 | 建班级时设的密码 |
|
||||
|
||||
旁边的「测试连接」可以先确认网络通。**已登录过但服务器暂时不可达时**，登录页会给一个「离线进入」——
|
||||
进去后看到的是上次缓存的课表 / 作业 / 通知（顶部会标「离线缓存」），网络恢复后自动刷新。
|
||||
|
||||
> 客户端**没有改密码入口**，这是刻意的：教室机器上误改班级密码会把别的机器锁在门外。
|
||||
> 班级密码由管理员在 Web 端「班级管理 → 修改班级账号」维护。
|
||||
|
||||
## 3. 首次启动的六步向导
|
||||
|
||||
第一次启动会在登录页上自动弹一个向导：欢迎 → 连接服务器 → 登录班级 → 登录之后（主界面与离线缓存）→
|
||||
灵动岛提醒 → 完成。走完或跳过都会记为已完成，之后不再自动弹。
|
||||
|
||||
想重看：登录页的**「查看使用引导」**，或进去之后 **设置 → 通用 → 使用引导**。
|
||||
|
||||
## 4. 认一认主界面
|
||||
|
||||
左侧是业务项（**课表 / 作业 / 通知 / 课件 / 成绩**）加上一个可展开的**设置**分组，
|
||||
顶部汉堡按钮把整栏收成 64px 的图标导轨（折叠状态会记住）。「通知」项上有未读红点。
|
||||
|
||||
| 页面 | 一句话 |
|
||||
| ---- | -------------------------------------------------------------- |
|
||||
| 课表 | 周视图 + 「今天」时间轴（大时钟 / 正在上什么 / 下一节） |
|
||||
| 作业 | 看板模式（按科目卡片、可全屏）/ 列表模式；教室机器还能录入作业 |
|
||||
| 课件 | 查看本班可见文件、下载和打开本地文件夹 |
|
||||
| 通知 | 未读红点、优先级标签、点开自动标为已读 |
|
||||
| 成绩 | 个人查询开启时看本班成绩，关闭后只看服务端集体分析 |
|
||||
| 设置 | 通用 / 外观 / 灵动岛 / 提醒 / 账号 / 关于，六个子页 |
|
||||
|
||||
细节见[应用帮助](../app/index.md)。
|
||||
|
||||
## 5. 在教室机器上把它调成"能看"的样子
|
||||
|
||||
教室大屏的观看距离和角度跟办公桌不一样，装完建议顺手做三件事：
|
||||
|
||||
1. **开全屏作业看板** —— 作业页「全屏看板」，按屏幕尺寸自动排版，整个屏幕刚好放得下、不用滚动。
|
||||
2. **调灵动岛** —— 设置 → 灵动岛：高度、宽度、字号、主题色、停靠位置、视觉风格。
|
||||
讲台机器上通常把字号调大一点、位置放到顶部居中。
|
||||
触摸屏（希沃白板等）走的是另一套命中逻辑，客户端会自动识别，不用手动开。
|
||||
3. **查看提醒规则** —— 设置 → 提醒维护本机课程等提醒设置；经典通知模式上课暂存普通消息，
|
||||
自定义常驻模式提示铃铛并主动查看。规则保存在本机，服务端仍即时广播。
|
||||
|
||||
## 6. 确认实时链路是通的
|
||||
|
||||
在隔离测试服务中给临时验证班级发一条普通通知，经典岛课间应出现胶囊，自定义常驻岛应出现铃铛数量提示。如果没有：
|
||||
|
||||
- 客户端顶栏的实时通道状态是不是"已连接"？
|
||||
- 现在是上课时段吗？经典模式普通通知上课暂存；自定义常驻模式看铃铛并主动展开。
|
||||
- 服务器与教室机器之间能互相 ping 通吗？防火墙放行 4000 了吗？
|
||||
|
||||
排查清单见[常见问题](../faq.md)。
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: 发布第一条内容
|
||||
description: 通知、作业、叫人、成绩与课件的首次操作。
|
||||
---
|
||||
|
||||
# 发布第一条内容
|
||||
|
||||
先完成班级、学生与任课关系配置。页面是否可见及能否发布，由实际功能权限、班级范围和科目关系共同决定。
|
||||
|
||||
## 通知与叫人
|
||||
|
||||
在“通知发布”选班、填写标题/内容、选择优先级后发布；叫人使用该页叫人入口，选择学生和事由。
|
||||
通知有低/普通/重要/紧急四档，叫人分普通 HIGH 与紧急 URGENT。
|
||||
经典岛普通通知上课暂存，普通叫人保留可点击胶囊，紧急消息立即展开；自定义常驻岛先提示铃铛，主动查看。
|
||||
上课发布紧急通知需服务端二次确认，Web 确认框倒计时结束后才能再次提交。
|
||||
完整行为见[通知](../app/notifications.md)和[叫人](../app/calls.md)。
|
||||
|
||||
## 作业
|
||||
|
||||
在“作业发布”选班、科目、所属日期，填写标题与要求；附件为受校验的 http(s) 或站内链接。
|
||||
作业按所属日期展示，可补录历史日期；科目写权限以本人任课关系为准。
|
||||
教室客户端可录作业和维护未交名单；本机录入的内容不会再提醒自己。
|
||||
可选全屏看板与字号/日期等偏好，详见[作业](../app/homeworks.md)。
|
||||
|
||||
## 成绩
|
||||
|
||||
在“成绩录入”选择班级、考试，单条/批量录入或导入表格。
|
||||
具备功能权限后，仍只能写自己任教科目；表格导入还要求管理员/本班班主任，按行返回错误和警告，文件上限 8 MB。
|
||||
班级端个人查询开关开启时可看本班明细与排名，关闭后只看服务端集体分析。
|
||||
见[成绩](../app/grades.md)和[导入](../app/imports.md)。
|
||||
|
||||
## 课件
|
||||
|
||||
在“教学事务 → 课件”上传文件，选择本人授课班级并设置“仅保存”或“保存后推送”。
|
||||
文件先保存到服务端，班级端按可见范围下载；推送离线补领、逐设备回执，客户端不自动运行文件。
|
||||
单文件上限 512 MB，详见[课件上传与传输](../app/courseware.md)。
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
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)
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: 系统要求
|
||||
description: ClassHelper 服务端、Web 管理端、桌面客户端的运行环境与网络要求。
|
||||
---
|
||||
|
||||
# 系统要求
|
||||
|
||||
## 服务端
|
||||
|
||||
Windows 服务端安装包自带 Node；Linux 包不内置 Node，一键安装器检测或安装兼容运行时。
|
||||
默认使用内嵌 SQLite，无需另装数据库服务；MySQL 形态需可用数据库。
|
||||
|
||||
| 项目 | 要求 |
|
||||
| -------- | -------------------------------------------------------------------------- |
|
||||
| 操作系统 | Windows 10 / 11 / Server 2016+（x64）；Linux（glibc 2.28+，见下）；Docker |
|
||||
| 内存 | 512 MB 起步，2 GB 以上更稳（Node + SQLite 常驻约 120–200 MB） |
|
||||
| 磁盘 | 预留程序、数据库、备份和课件文件空间；课件最多 512 MB/文件，按实际使用增长 |
|
||||
| CPU | 任意 x64；不需要独显 |
|
||||
|
||||
**Linux 的运行时要求**：安装器下载的官方 Node linux-x64 运行时通常要求 glibc ≥ 2.28。
|
||||
CentOS 7 是 2.17，一键安装器会检测并自动换成 `-glibc-217` 变体（尽力而为，未做长期验证）。
|
||||
判据：
|
||||
|
||||
```bash
|
||||
ldd --version | head -1
|
||||
```
|
||||
|
||||
**外网**：更新检查/下载安装包、假日建议和配置的在线 AI 服务等功能可能访问外网。
|
||||
基础教学业务可在内网运行；使用离线包、手工周次和 mock/关闭在线 AI，相关联网失败按接口返回原因处理。
|
||||
|
||||
## 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)。
|
||||
@@ -0,0 +1,142 @@
|
||||
---
|
||||
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)。
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: 建班级、排课表
|
||||
description: 班级、名单、任课关系与日课表的首次配置。
|
||||
---
|
||||
|
||||
# 建班级、排课表
|
||||
|
||||
## 创建班级
|
||||
|
||||
管理员在“班级管理”填写入学年份、班号、年级等资料；班级名称按年份和班号生成，如“2026级1班”。
|
||||
设置班主任、学期周数及班级凭据；班主任可暂空，但发布依赖教师归属的内容前需先完成配置。
|
||||
班级周数默认 20，受全校可配置上限限制，全校默认上限 30、范围 1–60。
|
||||
保存班级码与密码，教室客户端用它登录；已读和作业状态操作代表全班。
|
||||
|
||||
## 录入学生与教师
|
||||
|
||||
学生是名单，填写学号和姓名，不创建账号、密码或自动登录名。
|
||||
学号 1–32 位字母/数字/._-，不能复用；支持管理员表格导入，班主任有名单管理权限时可维护本班。
|
||||
教师使用工号账号，管理员在教师管理录入或导入。
|
||||
在班级详情按科目配置任课老师：任课关系只存 Course，决定该科作业/成绩写权限。
|
||||
班主任不任教某科就不能改该科内容，详见[班级与人员](../app/classes.md)。
|
||||
|
||||
## 配置作息与日课表
|
||||
|
||||
先在“时间表与课表编辑”维护时间表的上课/课间等时间点，再创建班级日课表并为时间点选择课程。
|
||||
按星期、周次范围和 1–9 周轮换设置启用规则，也可复制、临时换课或预定某天。
|
||||
时间表写入需 timetable:manage；日课表写入需 schedule:write 并通过本班班主任/管理员检查。
|
||||
可以从 ClassIsland 完整 JSON 离线导入作息、日课表、群组与预定，见[导入](../app/imports.md)。
|
||||
|
||||
## 校对周次与提醒
|
||||
|
||||
管理员在“学期周次”设置开学日、全校上限和逐周日期，班级可以有独立区间。
|
||||
在周视图和客户端今天时间轴核对当前课程、下一节、上下课时刻。
|
||||
经典岛普通通知上课暂存、普通叫人保留可点胶囊、紧急消息立即展开；自定义常驻岛先提示铃铛，主动点击查看。
|
||||
验证应使用独立测试班级，详见[验收](../dev/testing.md)，不要给业务班级发送测试通知。
|
||||
|
||||
下一步：[装班级端](client.md)。
|
||||
@@ -0,0 +1,14 @@
|
||||
- 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
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: 认识 Web 管理端
|
||||
description: 登录、菜单分组、权限与移动布局。
|
||||
---
|
||||
|
||||
# 认识 Web 管理端
|
||||
|
||||
服务端启动后，用浏览器打开 http://<服务器地址>:4000/，教师或管理员以工号和密码登录。
|
||||
学生无个人账号，教室客户端使用[班级登录](client.md)。新安装按部署配置创建初始管理员，首次使用后修改初始密码。
|
||||
|
||||
## 菜单与权限
|
||||
|
||||
侧栏按以下分组组织，具体页面由路由权限筛选，并支持浅色/深色和关怀模式。
|
||||
|
||||
| 分组 | 主要页面 |
|
||||
| ---------- | -------------------------------------------------- |
|
||||
| 工作台 | 仪表盘、AI 助手 |
|
||||
| 教学事务 | 课表、时间表与日课表编辑、作业、通知、课件、成绩 |
|
||||
| 班级与人员 | 班级、学生、教师、只读学生名单、学期周次、毕业归档 |
|
||||
| 设备运维 | 客户端在线状态、命令、更新与安装策略 |
|
||||
| 系统管理 | 权限组、系统设置、大模型设置、数据库管理 |
|
||||
|
||||
班级/学生/教师管理、学期周次、归档和数据库页面还有管理员角色门槛；
|
||||
教师只读名单、教学页与设备页按权限键和数据范围开放。
|
||||
每次操作服务端继续校验，不是显示菜单就能改所有班和科目。详见[角色与权限](../dev/permissions.md)。
|
||||
顶栏提供本人密码、使用引导、检查更新与退出等入口。
|
||||
|
||||
## 引导与手机
|
||||
|
||||
首次登录展示使用引导，完成/跳过后记住；可从顶栏“使用引导”重看。
|
||||
小屏侧栏收进抽屉，表格在卡片内横向滚动；支持安装 PWA，需要 HTTPS 或 localhost 安全上下文。
|
||||
同局域网手机填写服务器局域网地址，不用 localhost；公网反代见[生产部署](../management/production.md)。
|
||||
|
||||
下一步：[建班级、排课表](setup-class.md)。
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 69 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 46 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 2.5 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 46 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 76 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 106 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 109 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 120 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 88 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 105 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 141 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 141 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 73 KiB |
@@ -0,0 +1,69 @@
|
||||
---
|
||||
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`。
|
||||
@@ -0,0 +1,78 @@
|
||||
---
|
||||
title: 数据库管理
|
||||
description: 备份与恢复、导出导入、定时备份，以及 Web 管理端里的「数据库管理」模块。
|
||||
---
|
||||
|
||||
# 数据库管理
|
||||
|
||||
Web 管理端有一个「数据库管理」页（`/database`，**仅管理员可见**，接口要求 `database:manage`），
|
||||
把过去要手工做的数据库运维都收进了界面。
|
||||
|
||||
## 它能做什么
|
||||
|
||||
| 能力 | 说明 |
|
||||
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| 连接状态检测 | 当前类型（SQLite / MySQL）、连通性与延迟、引擎版本、数据体积、快照清单中各表的行数、连接串（MySQL 密码脱敏） |
|
||||
| 连接测试 | 对任意目标库试连（切换前的第一步） |
|
||||
| **一键切换** | SQLite ⇄ MySQL：自动「备份当前库 → 改写 schema provider → 生成客户端 / 建表 → 子进程迁移全部数据 → 改写 `.env`」，异步任务带步骤进度，**失败自动回滚** |
|
||||
| 备份 / 恢复 | gzip JSON 快照存在 `<数据目录>/backups/`；手动备份 / 从备份恢复（整库覆盖）/ 删除 |
|
||||
| 定时备份 | enabled + 间隔小时数 + 保留份数，配置存在 `data/database-settings.json`；服务端每 10 分钟检查一次到点任务（**进程不运行不补跑**） |
|
||||
| 快捷导入导出 | 下载快照 JSON（跨库通用）/ 下载数据库文件（仅 SQLite）/ 导入快照（整库覆盖，base64 上传） |
|
||||
|
||||
## 关键设计：只有一种快照格式
|
||||
|
||||
**备份、导入导出、跨库迁移共用同一种「JSON 快照」**：
|
||||
|
||||
- 按 `lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 依赖顺序导出；
|
||||
- 恢复时临时**关闭外键检查** —— 用于处理跨表外键关联，表清单与恢复顺序由 `lib/snapshot.ts` 统一维护；
|
||||
- 分批 `createMany` 写入。
|
||||
|
||||
相容版本的快照可以在受支持的 SQLite/MySQL 之间恢复；格式与缺失表由快照校验器检查。
|
||||
课件元数据包含在快照中，文件实体不包含，完整备份需另带 `data/courseware` 或 COURSEWARE_DIR 指定目录。
|
||||
|
||||
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`。
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
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) 的故障排查一节。
|
||||
@@ -0,0 +1,560 @@
|
||||
# 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. 推送 v* tag 会自动触发；也可在 Actions 的「发布 Linux 服务端安装包」中手动指定 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 登录，改一次密码再登录
|
||||
# ② 在隔离测试服务创建临时教师和班级，用其班级凭据登录客户端，验证提醒后清理临时数据
|
||||
# ③ 重跑安装器（幂等性）：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`）
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: MySQL 切换指南
|
||||
description: 通过快照和受支持的换库流程切换 SQLite/MySQL，保留迁移历史。
|
||||
---
|
||||
|
||||
# MySQL 切换指南
|
||||
|
||||
默认数据库为 SQLite，服务端也支持 MySQL/MariaDB。唯一 schema 为 packages/server/prisma/schema.prisma；
|
||||
Prisma 通过 libSQL 或 MariaDB driver adapter 访问，两种适配器已随运行时依赖内置。
|
||||
角色、优先级等以 String 加 API 校验存储，不用 Prisma enum 或 @db.*。
|
||||
|
||||
## 已有数据的切换
|
||||
|
||||
管理员在“数据库管理 → 一键切换数据库”填写**空目标库**连接串，并完成界面确认。
|
||||
还须 database:manage；页面和具体接口各自检查权限。
|
||||
|
||||
1. 备份并导出当前数据库为 JSON 快照。
|
||||
2. 测试目标连接，确认目标为空。
|
||||
3. 改写 schema provider，子进程生成对应 Prisma Client。
|
||||
4. 打包形态编译生成的 TypeScript 客户端。
|
||||
5. 子进程基于当前 schema 建表，并用 apply-snapshot 写入快照。
|
||||
6. 成功后写入 .env 的 DATABASE_PROVIDER/DATABASE_URL；重启服务端连接新库。
|
||||
|
||||
失败时回滚 schema，环境配置仅在成功后写入。快照覆盖的表以 lib/snapshot.ts 为准。
|
||||
目标已有表时拒绝；回到 SQLite 也应指定新空文件，不能删除正在使用的数据库。
|
||||
旧源库请保留到验证完成。课件实体不在 JSON 内，换主机时需另复制文件目录，见[课件](../app/courseware.md)。
|
||||
|
||||
## 源码开发与配置
|
||||
|
||||
scripts/use-database.mjs 只切换 schema provider，不迁移数据、不改 .env、不替代完整换库流程。
|
||||
如果只准备一个全新的开发环境，可用 pnpm db:switch:mysql，再配置独立空库并生成客户端；
|
||||
建模和导入仍按受支持流程完成。配置示例：
|
||||
|
||||
```dotenv
|
||||
DATABASE_PROVIDER=mysql
|
||||
DATABASE_URL="mysql://classhelper:your-password@127.0.0.1:3306/classhelper"
|
||||
```
|
||||
|
||||
SQLite 迁移目录属于仓库升级历史，不要为了切库删除它，也不要对已有数据运行 db:seed/db:reset。
|
||||
SQLite SQL 不直接应用到 MySQL；换库流程基于当前 schema 建表，保留原迁移用于 SQLite 升级。
|
||||
Prisma Client 与实际 provider 必须一致；切换后未重启时旧进程仍连接旧库。
|
||||
|
||||
## 部署核验
|
||||
|
||||
确认新库连接、表行数、班级登录、课表和成绩读取；保留切换前快照。
|
||||
生产凭据放 .env 或部署密钥中，不提交 Git。完整备份和各形态命令见[数据库管理](database.md)。
|
||||
Linux 正式包应在 Linux 构建，否则 Prisma engine 可能是宿主平台版本，见[Linux 部署](linux-deploy.md)。
|
||||
@@ -2,12 +2,12 @@
|
||||
|
||||
本文档覆盖三种上线形态，按适用场景选择：
|
||||
|
||||
| 形态 | 适用场景 | 产物 | 本机验证情况 |
|
||||
| --------------------- | -------------------------------------------- | -------------------------------------------------------- | -------------------------------------- |
|
||||
| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统） | `release-server/班级小助手服务端-<版本>-x64-setup.exe` | ✅ 已完整实测（静默安装/启停/卸载/UI） |
|
||||
| **B. Docker + MySQL** | 云服务器、多终端共享一套数据（推荐长期方案） | `deploy/Dockerfile` + `deploy/docker-compose.yml` | ⚠️ 文件已提供，本机无 Docker 未实测 |
|
||||
| **C. Linux 原生部署** | 已有 Linux 服务器（systemd + SQLite） | `deploy/install-linux.sh` + `deploy/classhelper.service` | ⚠️ 脚本已提供，本机无 Linux 未实测 |
|
||||
| **D. 手动部署** | 已有 Node 环境的服务器、需要自定义 | `pnpm dist:server` 的免安装目录 | ✅ 免安装目录已实测（163 项端到端） |
|
||||
| 形态 | 适用场景 | 产物 | 验证状态 |
|
||||
| --------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
|
||||
| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统） | `releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe` | ✅ 已验证（静默安装 / 启停 / 卸载 / UI） |
|
||||
| **B. Docker + MySQL** | 云服务器、多终端共享一套数据（推荐长期方案） | `deploy/Dockerfile` + `deploy/docker-compose.yml` | ⚠️ 文件已提供，尚未实机验证 |
|
||||
| **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 |
|
||||
| **D. 手动部署** | 已有 Node 环境的服务器、需要自定义 | 在仓库里构建后直接跑（见第四节） | ✅ 已验证（端到端验收通过） |
|
||||
|
||||
---
|
||||
|
||||
@@ -23,9 +23,12 @@ pnpm dist:server -- --reuse-deps # 迭代打包：复用已安装依赖，跳
|
||||
产物：
|
||||
|
||||
| 路径 | 说明 |
|
||||
| ----------------------------------------------------- | ----------------------------------------------- |
|
||||
| `release-server/classhelper-server/` | 免安装目录，可直接拷到任意 Windows x64 机器运行 |
|
||||
| `release-server/班级小助手服务端-1.0.0-x64-setup.exe` | 安装程序（约 34 MB，NSIS） |
|
||||
| ----------------------------------------------------------------------- | -------------------------- |
|
||||
| `releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe` | 安装程序（约 62 MB，NSIS） |
|
||||
|
||||
> 组装出来的运行时（内置 Node + 生产依赖 + 后端与 Web 产物，约 335 MB）是打安装包的中间物，
|
||||
> 落在 `.cache/server-staging/<版本>/`，脚本打完就删 —— 交付目录里只留安装程序。
|
||||
> 需要在有 Node 的机器上手动跑，见第四节。
|
||||
|
||||
打包内容：内置 **Node 运行时**（目标机无需安装 Node.js）、后端产物、Web 管理端产物、
|
||||
生产依赖（真实目录，非软链）、迁移 SQL、`.env`（随机 JWT 密钥）、启停脚本。
|
||||
@@ -35,10 +38,11 @@ pnpm dist:server -- --reuse-deps # 迭代打包：复用已安装依赖，跳
|
||||
双击安装程序即可，**无需管理员权限**（当前用户级安装）：
|
||||
|
||||
- 安装目录：`%LOCALAPPDATA%\Programs\ClassHelperServer`
|
||||
- 静默安装：`"班级小助手服务端-1.0.0-x64-setup.exe" /S`
|
||||
- 静默安装：`"ClassHelper 服务端-1.2.0-x64-setup.exe" /S`
|
||||
- 开始菜单：启动服务 / 停止服务 / 重启服务 / 打开管理端 / 使用说明 / 卸载
|
||||
- 桌面：`班级小助手服务端.lnk`（打开管理端）
|
||||
- 自动加入当前用户开机自启（`HKCU\...\CurrentVersion\Run`）
|
||||
- 桌面：`ClassHelper 服务端.lnk`（打开管理端）
|
||||
- **开机自启动可选**：安装向导的组件页里勾选（默认勾选），装完之后还能在管理端「系统设置」里随时开关
|
||||
（`GET/PUT /api/system/autostart`）；勾选时写的是 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run\ClassHelperServer`
|
||||
- 卸载信息注册到「应用和功能」
|
||||
|
||||
安装完成后服务会自动启动并完成首次初始化：
|
||||
@@ -55,7 +59,7 @@ pnpm dist:server -- --reuse-deps # 迭代打包：复用已安装依赖，跳
|
||||
├── server\dist\ 后端程序（入口 index.js）
|
||||
├── server\prisma\ 迁移 SQL（首启动自动执行）
|
||||
├── web\ Web 管理端（由后端托管）
|
||||
├── data\ classhelper.db + server.pid（备份只需复制此目录）
|
||||
├── data\ 数据库、课件与其他持久化文件（完整备份另含 .env）
|
||||
├── logs\server.log UTF-8 日志（含请求耗时）
|
||||
├── .env 全部配置
|
||||
├── start.cmd / stop.cmd / restart.cmd / status.cmd
|
||||
@@ -97,8 +101,8 @@ uninstall-service.cmd :: 删除计划任务
|
||||
|
||||
## 二、Docker + MySQL（形态 B，云部署推荐）
|
||||
|
||||
> 本机没有 Docker，因此这套文件未在本机实测；结构经过与已验证的产物对照（依赖清单、
|
||||
> 目录布局、迁移方式与服务端完全一致）。
|
||||
> 这套文件与已验证的产物结构一致（依赖清单、目录布局、迁移方式与服务端完全相同），
|
||||
> 但**尚未在真实 Docker 环境跑过**。第一次上线请先在测试机走一遍。
|
||||
|
||||
```bash
|
||||
cp deploy/.env.example deploy/.env
|
||||
@@ -149,108 +153,97 @@ docker compose -f deploy/docker-compose.sqlite.yml --env-file deploy/.env.sqlite
|
||||
|
||||
---
|
||||
|
||||
## 三、Linux 原生部署（形态 C，systemd + SQLite）
|
||||
## 三、Linux 部署（形态 C，推荐一键安装器）
|
||||
|
||||
适用：Ubuntu / Debian / CentOS / Rocky 等有 systemd 的服务器，单机跑一套（SQLite），
|
||||
用 Nginx 挂 HTTPS 给校内网/公网访问。
|
||||
适用：Ubuntu 20.04+ / Debian 11+ / CentOS 7+ / Rocky / AlmaLinux，任何有 systemd 的服务器
|
||||
（容器环境用下面的 Docker 形态）。**完整指南见 [linux-deploy.md](linux-deploy.md)**，这里是速查。
|
||||
|
||||
### 3.1 一键脚本（推荐）
|
||||
### 3.1 一键安装（推荐）
|
||||
|
||||
在**仓库根目录**先构建，然后执行脚本（需要 root）：
|
||||
Linux 包由 GitHub Actions 在 ubuntu runner 上构建（平台相关的依赖只能在 Linux 上装），
|
||||
产物挂在 Release 上；也可以本地 `pnpm dist:server:linux` 后把 tar.gz 拷到服务器。
|
||||
安装器脚本两个文件都在仓库的 `deploy/` 下：
|
||||
|
||||
```bash
|
||||
# 1) 构建（Node ≥ 20.19，推荐 22 LTS；目标机没有 pnpm 时可在别的机器上构建后拷仓库过来）
|
||||
corepack enable && corepack prepare pnpm@11.8.0 --activate
|
||||
pnpm install
|
||||
pnpm build:shared
|
||||
pnpm --filter @classhelper/server build
|
||||
pnpm --filter @classhelper/web-admin build
|
||||
# 开发机：做出 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/
|
||||
|
||||
# 2) 安装成 systemd 服务
|
||||
sudo bash deploy/install-linux.sh # 默认端口 4000、目录 /opt/classhelper
|
||||
# 常用变体：
|
||||
# bash deploy/install-linux.sh --check # 只体检（不需要 root）：校验构建产物/Node/端口探针
|
||||
# sudo bash deploy/install-linux.sh --port 8080
|
||||
# sudo bash deploy/install-linux.sh --dir /srv/classhelper
|
||||
# sudo bash deploy/install-linux.sh --no-service # 只铺文件，自己托管进程
|
||||
# sudo bash deploy/install-linux.sh --uninstall # 停服务并移除 unit（保留 data 与 .env）
|
||||
# 服务器上
|
||||
bash /tmp/install.sh --check # 只体检（不需要 root，不改动系统）
|
||||
sudo bash /tmp/install.sh # 交互式：选形态 → 选目录 → 选库 → 设初始管理员密码
|
||||
```
|
||||
|
||||
> 建议先跑一次 `--check`：它只读地校验"构建产物齐不齐、Node 版本够不够、目标端口上有没有旧实例"，
|
||||
> 不需要 root，也不会改任何东西。输出示例见 `deploy/install-linux.sh` 头部注释。
|
||||
|
||||
脚本做的事：建系统用户 `classhelper` → 把后端产物、`prisma/migrations`、Web 管理端拷到
|
||||
`/opt/classhelper` → `npm install --omit=dev`（清单就是 `deploy/package.runtime.json`，与
|
||||
容器运行时同一份）→ 生成 `.env`（随机 `JWT_SECRET`、`AUTO_MIGRATE=true`）→ 装 systemd unit →
|
||||
`enable --now` → 轮询 `/healthz` 就绪后打印地址与初始管理员。
|
||||
|
||||
安装后的目录（与已验证的 Windows 免安装目录同构，因此 `.env` 里的相对路径语义一致）：
|
||||
|
||||
```
|
||||
/opt/classhelper/
|
||||
├── .env 全部配置（权限 600）
|
||||
├── server/dist 后端程序（入口 index.js）
|
||||
├── server/prisma 迁移 SQL（首启动自动执行）
|
||||
├── web/ Web 管理端（后端托管，单端口）
|
||||
├── node_modules/ 仅生产依赖
|
||||
├── data/ classhelper.db + server.pid（备份只复制这里）
|
||||
└── logs/
|
||||
```
|
||||
|
||||
首次启动会自动建表并创建管理员 `admin / admin123`（**登录后立刻改密码**）。
|
||||
|
||||
### 3.2 手动部署（不想用脚本 / 没有 systemd）
|
||||
|
||||
等价的手工步骤，便于排查：
|
||||
非交互（批量部署 / 验收用）：
|
||||
|
||||
```bash
|
||||
sudo useradd --system --shell /usr/sbin/nologin classhelper
|
||||
sudo mkdir -p /opt/classhelper/{server,web,data,logs}
|
||||
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
|
||||
```
|
||||
|
||||
# 程序产物
|
||||
sudo cp -R packages/server/dist /opt/classhelper/server/dist
|
||||
sudo cp -R packages/server/prisma /opt/classhelper/server/prisma
|
||||
sudo cp -R packages/web-admin/dist /opt/classhelper/web
|
||||
sudo cp deploy/package.runtime.json /opt/classhelper/package.json
|
||||
安装器做的事：识别发行版与包管理器补依赖 → 建系统用户 `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`。
|
||||
|
||||
# 生产依赖 + 工作区共享包
|
||||
cd /opt/classhelper && sudo npm install --omit=dev --no-audit --no-fund
|
||||
sudo mkdir -p /opt/classhelper/node_modules/@classhelper/shared
|
||||
sudo cp -R packages/shared/dist /opt/classhelper/node_modules/@classhelper/shared/dist
|
||||
sudo cp packages/shared/package.json /opt/classhelper/node_modules/@classhelper/shared/package.json
|
||||
重跑就是**覆盖安装**：`config.env`（含密钥）与 `data/` 保留，已登录用户不会被踢下线。
|
||||
|
||||
# 配置（参考脚本生成的 .env，务必自己生成 JWT_SECRET）
|
||||
sudo tee /opt/classhelper/.env >/dev/null <<'EOF'
|
||||
NODE_ENV=production
|
||||
HOST=0.0.0.0
|
||||
PORT=4000
|
||||
DATABASE_PROVIDER=sqlite
|
||||
DATABASE_URL="file:../data/classhelper.db"
|
||||
AUTO_MIGRATE=true
|
||||
JWT_SECRET=换成 openssl rand -hex 48 的输出
|
||||
JWT_EXPIRES_IN=7d
|
||||
CORS_ORIGIN=https://class.example.com
|
||||
TRUST_PROXY=1
|
||||
RATE_LIMIT_ENABLED=true
|
||||
STARTUP_DB_CHECK=true
|
||||
PID_FILE=../data/server.pid
|
||||
LOG_LEVEL=info
|
||||
EOF
|
||||
### 3.2 安装后的布局与运维
|
||||
|
||||
sudo chown -R classhelper:classhelper /opt/classhelper/{data,logs,node_modules} /opt/classhelper/.env
|
||||
sudo chmod 600 /opt/classhelper/.env
|
||||
```
|
||||
/opt/classhelper/ 程序、node_modules、内置 Node、data/、tools/、bin/
|
||||
/etc/classhelper/config.env 唯一配置真身（600）；安装目录里的 .env 是指向它的软链
|
||||
/var/log/classhelper/ install.log + audit.log
|
||||
/var/backups/classhelper/ 备份与程序快照（回滚用）
|
||||
```
|
||||
|
||||
# systemd
|
||||
sudo sed -e 's#__NODE__#/usr/bin/node#' -e 's#__DIR__#/opt/classhelper#' -e 's#__USER__#classhelper#' \
|
||||
deploy/classhelper.service | sudo tee /etc/systemd/system/classhelper.service
|
||||
> 为什么安装目录的 `.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
|
||||
systemctl status classhelper --no-pager
|
||||
```
|
||||
|
||||
也可以用 PM2 之类托管（`pm2 start /opt/classhelper/server/dist/index.js --name classhelper`），
|
||||
但 systemd 更省心：`Restart=always`、日志进 journald、开机自启一次配好。
|
||||
|
||||
### 3.3 Nginx + HTTPS
|
||||
### 3.4 Nginx + HTTPS
|
||||
|
||||
```bash
|
||||
sudo cp deploy/nginx.conf /etc/nginx/conf.d/classhelper.conf
|
||||
@@ -259,7 +252,7 @@ sudo nginx -t && sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
`deploy/nginx.conf` 已经处理了最容易踩的两点：`/socket.io/` 的 WebSocket 升级头，
|
||||
以及 `X-Forwarded-For/X-Forwarded-Proto` 透传（配合 `.env` 里 `TRUST_PROXY=1`，限流才会按真实 IP 统计）。
|
||||
以及 `X-Forwarded-For/X-Forwarded-Proto` 透传（配合配置里的 `TRUST_PROXY=1`，限流才会按真实 IP 统计）。
|
||||
用 certbot 签证书：
|
||||
|
||||
```bash
|
||||
@@ -267,51 +260,44 @@ sudo apt install -y certbot python3-certbot-nginx
|
||||
sudo certbot --nginx -d class.example.com
|
||||
```
|
||||
|
||||
### 3.4 升级 / 备份 / 排障
|
||||
|
||||
升级（不会动 `.env`，JWT 密钥不变，学生端不用重新登录）：
|
||||
### 3.5 验收
|
||||
|
||||
```bash
|
||||
git pull && pnpm install
|
||||
pnpm build:shared && pnpm --filter @classhelper/server build && pnpm --filter @classhelper/web-admin build
|
||||
sudo bash deploy/install-linux.sh # 覆盖程序文件 + 自动补迁移（AUTO_MIGRATE）
|
||||
journalctl -u classhelper -n 30 --no-pager
|
||||
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'
|
||||
```
|
||||
|
||||
| 事项 | 命令 |
|
||||
| -------- | ---------------------------------------------------------------------------------------------------------- |
|
||||
| 备份 | `systemctl stop classhelper && cp -a /opt/classhelper/data /root/classhelper-data-$(date +%F)`（然后启动） |
|
||||
| 恢复 | 停服务 → 用备份覆盖 `data/` → 启动 |
|
||||
| 看日志 | `journalctl -u classhelper -f` |
|
||||
| 重启 | `systemctl restart classhelper`（改 `.env` 后必须重启） |
|
||||
| 探针 | `curl -s localhost:4000/healthz` / `/readyz`（就绪 200，数据库不可用 503） |
|
||||
| 换端口 | 改 `.env` 的 `PORT` → 重启；同时改 Nginx 的 `upstream` |
|
||||
| 换数据库 | 见 `docs/mysql.md`：切 provider + 装 `@prisma/adapter-mariadb` + `npx prisma migrate deploy` |
|
||||
|
||||
> 注意：本机（开发环境）是 Windows 且无 Docker/WSL 发行版，因此 **3.1 的脚本没有在 Linux 实机跑过**。
|
||||
> 它复用的两套东西都已验证：Windows 免安装目录（同样的目录结构、`.env` 相对路径与
|
||||
> `AUTO_MIGRATE` 首启动行为）和 `deploy/Dockerfile` 的 runtime 阶段（同样的依赖清单与产物布局）。
|
||||
> 首次在服务器上执行后请按 3.4 的探针 + Web 登录 + `pnpm verify:e2e`（把 `VERIFY_BASE_URL` 指向服务器）确认。
|
||||
覆盖安装结果、服务探针、API 登录、改密（含审计与回滚）、备份、配置读写、key rotate、
|
||||
升级与回滚整条链路，末尾打印 `=== 结果：N/N 项通过 ===`。逐条清单见
|
||||
[linux-deploy.md](linux-deploy.md) 第 10 节。
|
||||
|
||||
---
|
||||
|
||||
## 四、手动部署（形态 D）
|
||||
|
||||
目标机已有 Node.js（≥ 20.19）时，不需要任何安装包，直接在仓库里构建后跑：
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm build:shared
|
||||
pnpm --filter @classhelper/server build
|
||||
pnpm --filter @classhelper/web-admin build
|
||||
pnpm dist:server -- --reuse-deps # 得到 release-server/classhelper-server 免安装目录
|
||||
```
|
||||
|
||||
把该目录拷贝到目标机，编辑 `.env`（端口、数据库、密钥、跨域），然后：
|
||||
按目标机的实际情况写好 `packages/server/.env`（端口、数据库、密钥、跨域），然后：
|
||||
|
||||
```cmd
|
||||
start.cmd :: Windows
|
||||
# 或直接：node server/dist/index.js （Linux/macOS 用系统 node，见上面的形态 C）
|
||||
```bash
|
||||
pnpm --filter @classhelper/server start # 或 node packages/server/dist/index.js
|
||||
```
|
||||
|
||||
> 想把这份构建结果整体拷到另一台机器，就自己带上这四样：
|
||||
> `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 首次启动自动建表 + 建管理员）
|
||||
@@ -322,13 +308,13 @@ start.cmd :: Windows
|
||||
## 五、环境变量清单
|
||||
|
||||
| 变量 | 默认 | 说明 |
|
||||
| --------------------------------------------------- | ---------------------- | --------------------------------------------------------- |
|
||||
| --------------------------------------------------- | ---------------------- | ----------------------------------------------------------- |
|
||||
| `NODE_ENV` | `development` | `production` 会启用生产校验、HSTS、更严的限流 |
|
||||
| `HOST` / `PORT` | `0.0.0.0` / `4000` | 监听地址与端口 |
|
||||
| `DATABASE_PROVIDER` | `sqlite` | `sqlite` 或 `mysql` |
|
||||
| `DATABASE_URL` | `file:./prisma/dev.db` | SQLite 相对路径以 `server` 根为基准；MySQL 用连接串 |
|
||||
| `AUTO_MIGRATE` | `false` | SQLite 空库时自动执行随包迁移并创建管理员 |
|
||||
| `JWT_SECRET` | — | **必填**，≥32 位；生产环境仍为示例值会拒绝启动 |
|
||||
| `AUTO_MIGRATE` | `false` | SQLite 启动时补跑随包迁移，空库另创建管理员 |
|
||||
| `JWT_SECRET` | — | **必填**，至少 16 位；生产需 ≥32 位且拒绝示例密钥 |
|
||||
| `JWT_EXPIRES_IN` | `7d` | 令牌有效期 |
|
||||
| `CORS_ORIGIN` | `*` | 允许来源，多个用逗号分隔；生产建议写具体域名 |
|
||||
| `TRUST_PROXY` | `false` | 反向代理层数（Nginx 填 `1`），影响限流与日志中的真实 IP |
|
||||
@@ -337,10 +323,10 @@ start.cmd :: Windows
|
||||
| `PID_FILE` | — | PID 文件路径（安装包启停脚本依赖），相对 `server` 根 |
|
||||
| `WEB_DIST_DIR` | 自动探测 | Web 管理端产物目录（`../web-admin/dist` 或 `./web`） |
|
||||
| `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` |
|
||||
| `DEFAULT_STUDENT_PASSWORD` | `123456` | 新增/重置学生账号的默认密码 |
|
||||
| `DEFAULT_CLASS_PASSWORD` | `123456` | 新建班级时班级账号（学生端登录）的默认密码 |
|
||||
| `DEFAULT_CLASS_PASSWORD` | `123456` | 新建班级时班级账号（ClassHelper 班级端登录）的默认密码 |
|
||||
| `DEFAULT_TEACHER_PASSWORD` | `123456` | 新增/重置教师账号的默认密码（管理员录入教师用） |
|
||||
| `TERM_START_DATE` | — | 第 1 教学周的周一，用于"当前周次"与课表默认视图 |
|
||||
| `COURSEWARE_DIR` | 默认 data/courseware | 课件文件实体目录；需纳入完整备份 |
|
||||
| `TERM_START_DATE` | — | 开学日环境兜底；界面全校/班级设置与逐周区间优先，见课表帮助 |
|
||||
| `INITIAL_ADMIN_USERNAME` / `INITIAL_ADMIN_PASSWORD` | `admin` / `admin123` | 空库首启动创建的管理员 |
|
||||
|
||||
---
|
||||
@@ -368,6 +354,8 @@ start.cmd :: Windows
|
||||
| SQLite | 停止服务后复制 `data/classhelper.db`（Linux：`/opt/classhelper/data`） | 替换该文件后启动 |
|
||||
| MySQL | `mysqldump -u classhelper -p classhelper > backup.sql` | `mysql ... < backup.sql` |
|
||||
|
||||
课件文件实体不在 JSON/SQL 数据快照里，完整备份还需 `data/courseware` 或 `COURSEWARE_DIR` 指定目录。
|
||||
|
||||
建议：每日自动备份 + 保留 7 份；变更 `JWT_SECRET` 会导致所有用户重新登录，请勿在无必要时更换。
|
||||
|
||||
### 6.4 安全清单（上线前逐项确认）
|
||||
@@ -406,7 +394,7 @@ start.cmd :: Windows
|
||||
|
||||
## 八、性能与容量参考
|
||||
|
||||
- 单机 SQLite 形态适合**单校规模**（数千用户、每天数百次写操作），实测 62 项接口与实时推送全部达标。
|
||||
- 单机 SQLite 形态适合**单校规模**（数千用户、每天数百次写操作），接口与实时推送均已通过端到端验收。
|
||||
- 多校区 / 高并发建议切 MySQL，并横向扩容服务端（Socket.IO 需要配置 Redis adapter 才能多实例广播，
|
||||
当前为单实例广播；如需多实例请参考 `packages/server/src/realtime/socket.ts` 引入 `@socket.io/redis-adapter`）。
|
||||
- 静态资源已设置 immutable 长缓存 + gzip；Web 管理端为 SPA，首屏包体约 900 KB（gzip 约 290 KB），
|
||||
@@ -0,0 +1,12 @@
|
||||
- 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
|
||||
@@ -0,0 +1,133 @@
|
||||
---
|
||||
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 班级端）
|
||||
|
||||
Web「客户端」可缓存安装包并推送目标版本，客户端从本服务下载并校验 SHA256，按立即、放学后或空闲策略安装。管理页显示下载字节与百分比、校验中、等待安装、安装中和失败原因。安装前先上报「正在更新，将会短暂离线」，新版上线后的心跳确认「已完成更新，版本 xxxx」；仅离线不会被判为更新成功。关闭自动更新的客户端会显示原因。
|
||||
|
||||
从 Releases 取新的 `setup.exe` 覆盖安装即可，配置在 `%APPDATA%`，不受影响。
|
||||
|
||||
> 如果你是在**自己维护的机器**上只替换了 `releases/` 里的产物、而没有同步到安装目录，
|
||||
> 用户打开的还是旧的 `resources/app.asar` —— 表现为"改了但界面不生效"。
|
||||
> 停止客户端后使用新安装程序覆盖安装，再对**实际安装副本**跑一次打包版冒烟确认。
|
||||
|
||||
## 升级前的准备清单
|
||||
|
||||
- [ ] 备份数据库、配置与课件实体（完整复制 `data`/`COURSEWARE_DIR`，数据库用对应快照或 dump）；
|
||||
- [ ] 记下当前版本号，必要时能回滚到它；
|
||||
- [ ] 挑一个没课的时间 —— 升级期间实时推送会中断；
|
||||
- [ ] 升级后确认 `/readyz` 是 200，并且客户端顶栏的实时通道显示"已连接"。
|
||||
|
||||
## 给维护者
|
||||
|
||||
打版本、出安装包、发 Release 的完整流程见[版本迭代与发布](../dev/release.md)。
|
||||
|
||||
### 客户端远控与更新修复
|
||||
|
||||
先升级服务端，再推送修复后的客户端安装包。服务端兼容旧客户端读取顶层心跳字段，旧设备也可领取更新；第一次升级前仍遵循旧客户端的空闲安装条件。新客户端支持立即、放学后和空闲安装三种策略。放学后取指定的最早时间与当天最后一节课结束时间中的较晚者；设备离线时在再次上线后处理。
|
||||
-134
@@ -1,134 +0,0 @@
|
||||
# MySQL 切换指南
|
||||
|
||||
本项目默认使用 **SQLite（libSQL 内嵌模式）** 跑本地开发，数据模型与访问层已按
|
||||
MySQL 兼容方式设计，可平滑切换到云端 MySQL / MariaDB 统一存储。
|
||||
|
||||
## 为什么默认是 SQLite
|
||||
|
||||
- 本地零依赖即可跑通全部功能（无需安装数据库服务）
|
||||
- `schema.prisma` 刻意只使用跨库通用类型
|
||||
（`String` / `Int` / `Float` / `Boolean` / `DateTime`，无 `enum`、无 `@db.*` 原生类型）
|
||||
|
||||
## 设计上的兼容约定
|
||||
|
||||
| 约定 | 说明 |
|
||||
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 不使用 Prisma `enum` | 角色（`ADMIN/TEACHER/STUDENT`）与优先级（`LOW/NORMAL/HIGH/URGENT`）以 `String` 存储，由 zod 在 API 层校验，两种数据库行为完全一致 |
|
||||
| 主键为 `String @default(cuid())` | 不依赖自增，便于多端离线生成与合并 |
|
||||
| 时间统一 `DateTime` | 由应用层与驱动适配器负责时区，不使用数据库原生时间函数 |
|
||||
| 唯一约束仅使用 `@@unique` / `@unique` | SQLite 与 MySQL 语义一致 |
|
||||
| 级联删除使用 Prisma 的 `onDelete` | 由 Prisma 生成对应外键动作 |
|
||||
|
||||
## 切换到 MySQL
|
||||
|
||||
### 方式一：Web 管理端「数据库管理 → 一键切换」（推荐，v1.0.0 新增）
|
||||
|
||||
管理员在 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
|
||||
# 自动把 prisma/schema.prisma 的 provider 改成 mysql
|
||||
node scripts/use-database.mjs mysql
|
||||
```
|
||||
|
||||
#### 2. MySQL 驱动适配器（自 v1.0.0 起已随包内置）
|
||||
|
||||
Prisma 7 要求所有数据库都通过 driver adapter 接入，MySQL 对应 `@prisma/adapter-mariadb`
|
||||
（该适配器基于 `mariadb` 驱动，兼容 MySQL 8）。**它已在 `packages/server/package.json` 的
|
||||
依赖里**（数据库管理模块的连接测试/迁移需要），因此无需再手动安装：
|
||||
|
||||
```bash
|
||||
# 仅当从旧版本升级、依赖里还没有时才需要
|
||||
pnpm --filter @classhelper/server add @prisma/adapter-mariadb
|
||||
```
|
||||
|
||||
`packages/server/src/lib/db.ts` 内置分支：当 `DATABASE_PROVIDER=mysql` 时会动态加载该适配器，
|
||||
服务端代码无需改动。
|
||||
|
||||
#### 3. 配置环境变量
|
||||
|
||||
编辑 `packages/server/.env`：
|
||||
|
||||
```dotenv
|
||||
DATABASE_PROVIDER=mysql
|
||||
DATABASE_URL="mysql://classhelper:your-password@127.0.0.1:3306/classhelper"
|
||||
```
|
||||
|
||||
> 云端部署时把 `127.0.0.1` 换成云数据库内网/公网地址；
|
||||
> 生产环境请同时修改 `JWT_SECRET` 与 `CORS_ORIGIN`。
|
||||
|
||||
#### 4. 重建迁移并生成客户端
|
||||
|
||||
SQLite 与 MySQL 的 DDL 方言不同，**必须重新生成迁移文件**：
|
||||
|
||||
```bash
|
||||
# 删除 SQLite 迁移历史（迁移文件是方言相关的）
|
||||
rm -rf packages/server/prisma/migrations
|
||||
# 重新生成并应用（需要目标库可连接，且账号有建表权限）
|
||||
pnpm db:migrate
|
||||
# 初始化演示数据
|
||||
pnpm db:seed
|
||||
```
|
||||
|
||||
也可以先只生成 SQL 供 DBA 审核：
|
||||
|
||||
```bash
|
||||
pnpm --filter @classhelper/server exec prisma migrate dev --create-only --name init_mysql
|
||||
```
|
||||
|
||||
> 只搬数据、不要演示数据时，用界面的「下载快照 / 导入快照」更省事：
|
||||
> 旧库导出 JSON → 切库建表 → 新库导入，一份快照也可用 CLI 迁移：
|
||||
> `node server/dist/tools/apply-snapshot.js --provider mysql --url "mysql://..." --file snapshot.json`
|
||||
|
||||
#### 5. 回到 SQLite
|
||||
|
||||
```bash
|
||||
node scripts/use-database.mjs sqlite
|
||||
# 同步 .env：DATABASE_PROVIDER=sqlite、DATABASE_URL="file:./prisma/dev.db"
|
||||
rm -rf packages/server/prisma/migrations # 若之前已切换成 MySQL 迁移
|
||||
pnpm db:migrate
|
||||
```
|
||||
|
||||
> 用界面「一键切换」回 SQLite 时，目标库同样必须是空文件：删除旧 `.db` 或指定一个新路径。
|
||||
|
||||
## 生产部署注意事项
|
||||
|
||||
1. **连接池**：Prisma 7 的 driver adapter 使用底层驱动（`mariadb`）的连接池设置，
|
||||
与 Prisma 6 默认值不同（例如默认无连接超时）。建议通过适配器参数显式设置连接上限与时区。
|
||||
2. **时区**：`Grade.publishedAt`、`Homework.dueAt` 等字段建议在数据库会话中统一为 UTC，
|
||||
三端展示时再按本地时区格式化（前端使用 `@classhelper/shared` 的 `formatDate`）。
|
||||
3. **迁移部署**：CI/CD 中使用 `prisma migrate deploy`（对应 `pnpm db:deploy`）而不是 `migrate dev`。
|
||||
4. **备份**：切换云数据库后，`packages/server/prisma/dev.db` 不再被使用，可从 `.gitignore` 之外移除。
|
||||
界面「定时备份」把快照写进 `<数据目录>/backups/`（MySQL 模式下即安装根 `data/backups/`），
|
||||
**服务端进程不运行时不会补跑**；关键环境建议同时用数据库自带的备份策略。
|
||||
5. **安装包体积**：切换链路需要随包内置 `prisma` CLI 与 `typescript` 编译器（Prisma 7 生成器产出
|
||||
`.ts`，切换后需在目标机编译进 `dist/generated`），服务端安装包因此约 34MB → 71MB。
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: 功能与源码索引
|
||||
description: 当前功能说明、开发契约与实现入口，避免重复维护多份产品说明书。
|
||||
---
|
||||
|
||||
# 功能与源码索引
|
||||
|
||||
本文为现行文档入口。功能规则在对应章节维护；源码行为发生变化时，同步修改对应章节。
|
||||
旧任务书、历史审查结论和旧构建验收数字不作为当前功能依据。
|
||||
|
||||
| 主题 | 文档 | 工作区源码入口 |
|
||||
| ------------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| 架构与模块 | [架构总览](dev/architecture.md) | `server/src/modules/registry.ts` |
|
||||
| 日课表、作息与轮换 | [课表](app/schedules.md) | `server/src/lib/class-plan.ts`、`modules/class-plans/` |
|
||||
| 学生、教师、班级 | [班级、学生与教师](app/classes.md) | `server/src/lib/access.ts`、`modules/students/` |
|
||||
| 权限组与岗位范围 | [角色与权限](dev/permissions.md) | `shared/src/permissions.ts`、`server/src/lib/permission-scope.ts` |
|
||||
| 作业 | [作业](app/homeworks.md) | `server/src/modules/homeworks/` |
|
||||
| 通知与叫人 | [通知](app/notifications.md)、[叫人](app/calls.md) | `server/src/modules/notifications/`、`calls/` |
|
||||
| 课件 | [课件上传与传输](app/courseware.md) | 三端 `courseware` 模块与 `shared/src/courseware.ts` |
|
||||
| 成绩与隐私 | [成绩](app/grades.md) | `server/src/modules/grades/` |
|
||||
| 经典与自定义常驻岛 | [灵动岛](app/island.md) | `desktop-client/src/island/LayoutIslandApp.vue`、`CustomIslandRuntime.vue` |
|
||||
| 导入 | [表格与课表导入](app/imports.md) | `server/src/modules/imports/`、`class-plans/profile-import.service.ts` |
|
||||
| API 与实时 | [REST API](dev/api.md)、[实时事件](dev/realtime.md) | `server/src/modules/`、`realtime/`、`shared/src/constants.ts` |
|
||||
| 数据模型与迁移 | [数据模型](dev/data-model.md) | `server/prisma/schema.prisma`、`migrations/` |
|
||||
| 数据库管理 | [数据库管理](management/database.md)、[MySQL](management/mysql.md) | `server/src/lib/snapshot.ts`、`modules/database/` |
|
||||
| 安装与升级 | [生产部署](management/production.md)、[Linux](management/linux-deploy.md)、[更新](management/upgrade.md) | `deploy/`、`scripts/dist-server.mjs` |
|
||||
| 验证与发布 | [验收](dev/testing.md)、[发布](dev/release.md) | 根 `package.json`、`scripts/`、`.github/workflows/` |
|
||||
| 当前实现约定 | [实现约定](dev/implementation.md) | 课表、升级、岛、课件与设备维护的关键边界 |
|
||||
|
||||
表中的包路径均相对仓库 `packages/`；脚本和部署目录相对仓库根。
|
||||
源码总入口：[GitHub 仓库](https://github.com/LoveChengke/ClassHelper)。
|
||||
代理工程规则见 [AGENTS.md](https://github.com/LoveChengke/ClassHelper/blob/master/AGENTS.md)。
|
||||
ClassIsland 仅保留离线 JSON 导入与设计参考，在线联动插件及相关接口已退役。
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 108 KiB |
@@ -0,0 +1,69 @@
|
||||
/**
|
||||
* 文档站本地预览用的最小静态服务器（构建产物 docs/_site）。
|
||||
* 正式发布走 GitHub Pages（.github/workflows/pages.yml：官网在根、文档站在 /docs/），不需要这个文件。
|
||||
*
|
||||
* node docs/build.mjs --serve → 构建后直接预览（推荐）
|
||||
* node docs/serve.mjs → http://127.0.0.1:5181（要求已经构建过）
|
||||
* PORT=8080 node docs/serve.mjs
|
||||
*/
|
||||
|
||||
import { createServer } from 'node:http';
|
||||
import { readFile, stat } from 'node:fs/promises';
|
||||
import { existsSync } from 'node:fs';
|
||||
import { extname, join, normalize, resolve, sep } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const ROOT = resolve(fileURLToPath(new URL('_site/', import.meta.url)));
|
||||
const PORT = Number(process.env.PORT ?? 5181);
|
||||
|
||||
const MIME = {
|
||||
'.html': 'text/html; charset=utf-8',
|
||||
'.css': 'text/css; charset=utf-8',
|
||||
'.js': 'text/javascript; charset=utf-8',
|
||||
'.json': 'application/json; charset=utf-8',
|
||||
'.svg': 'image/svg+xml',
|
||||
'.png': 'image/png',
|
||||
'.jpg': 'image/jpeg',
|
||||
'.ico': 'image/x-icon',
|
||||
'.woff': 'font/woff',
|
||||
'.woff2': 'font/woff2',
|
||||
'.map': 'application/json',
|
||||
};
|
||||
|
||||
const server = createServer(async (request, response) => {
|
||||
const url = new URL(request.url ?? '/', 'http://localhost');
|
||||
const requested = decodeURIComponent(url.pathname);
|
||||
const target = normalize(join(ROOT, requested === '/' ? 'index.html' : requested));
|
||||
|
||||
// 目录穿越防护：解析结果必须仍在 ROOT 里
|
||||
if (target !== ROOT && !target.startsWith(ROOT + sep)) {
|
||||
response.writeHead(403).end('Forbidden');
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
const info = await stat(target);
|
||||
const file = info.isDirectory() ? join(target, 'index.html') : target;
|
||||
const body = await readFile(file);
|
||||
response.writeHead(200, {
|
||||
'content-type': MIME[extname(file)] ?? 'application/octet-stream',
|
||||
'cache-control': 'no-store',
|
||||
});
|
||||
response.end(body);
|
||||
} catch {
|
||||
// 与 GitHub Pages 行为对齐：未知路径给站点根的 404.html
|
||||
const fallback = join(ROOT, '404.html');
|
||||
if (existsSync(fallback)) {
|
||||
response.writeHead(404, { 'content-type': MIME['.html'] }).end(await readFile(fallback));
|
||||
return;
|
||||
}
|
||||
response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('404');
|
||||
}
|
||||
});
|
||||
|
||||
server.listen(PORT, '127.0.0.1', () => {
|
||||
if (!existsSync(ROOT)) {
|
||||
console.warn('还没有构建产物，先跑 `node docs/build.mjs`');
|
||||
}
|
||||
console.log(`文档站预览：http://127.0.0.1:${PORT}`);
|
||||
});
|
||||
Loaded 100 of 470 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user