Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 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,131 @@
|
||||
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.0）；
|
||||
# 3. 跑完 Release 里会多出 Linux 包与更新后的 SHA256SUMS-<版本>.txt。
|
||||
#
|
||||
# 也可以只跑构建不挂 Release（attach=false），产物在 workflow 的 Artifacts 里。
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
tag:
|
||||
description: '要构建并挂载的 Release tag（例如 v1.1.0）'
|
||||
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 release-server/
|
||||
|
||||
- name: 上传构建产物（Artifacts）
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: classhelper-server-linux-x64
|
||||
path: |
|
||||
release-server/classhelper-server-linux-x64-*.tar.gz
|
||||
release-server/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}"
|
||||
TARBALL="release-server/classhelper-server-linux-x64-${VERSION}.tar.gz"
|
||||
SHAFILE="${TARBALL}.sha256"
|
||||
SUMS="release-server/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#release-server/##" > "$SHAFILE"
|
||||
fi
|
||||
|
||||
# 取回已有的校验清单（Windows 包那几行），只替换/追加本包这一行，其余内容原样保留。
|
||||
# 注意**不要**用 `sort -u` 去重：那份文件是人读的（表头 + 体积 + 说明），排序会把它们打散。
|
||||
gh release download "$TAG" --pattern "SHA256SUMS-*.txt" --dir release-server --clobber || true
|
||||
DOWNLOADED="$(ls release-server/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"
|
||||
@@ -55,11 +55,18 @@ scripts/
|
||||
dist-server.mjs 服务端 + Web 管理端打包（产物落在 release-server/）
|
||||
nsis/server-installer.nsi 服务端 NSIS 安装脚本
|
||||
verify-packaged.mjs 对**打包后/已安装**的客户端 EXE 复跑冒烟
|
||||
check-icons.mjs 图标注册表静态门禁（漏注册会静默渲染空白，见 §5 第 53 条）
|
||||
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
|
||||
deploy/ Dockerfile / docker-compose{,.sqlite}.yml / nginx.conf / package.runtime.json
|
||||
install.sh（Linux 一键安装器，TUI）/ install-linux.sh（转发壳）
|
||||
classhelper（运维命令本体）/ verify-linux.sh（Linux 验收，自统计 N/N）
|
||||
tools/admin-cli.mjs（离线改密 / SQLite 一致性快照）
|
||||
profile.d/ logrotate.d/ systemd/（装到 /etc 的模板）
|
||||
Dockerfile.linux-package（安装包内那份，--mode docker 用）
|
||||
classhelper.service（systemd 模板，5 个占位符）/ .env{,.sqlite}.example
|
||||
docs/ production.md（生产部署）/ linux-deploy.md（Linux 部署与运维）
|
||||
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/
|
||||
@@ -69,27 +76,27 @@ packages/server/
|
||||
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-e2e.mjs 后端端到端验收（条数由脚本统计，2026-10-05 实测 190 项）
|
||||
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
|
||||
password schemas session term version(读 package.json) 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
|
||||
src/modules/ 15 个功能模块 + registry.ts + module.types.ts
|
||||
packages/web-admin/src/ api stores router layouts views(12) components(5) composables styles config.ts
|
||||
packages/desktop-client/
|
||||
src/main/ 主进程：index / config（含作业短语与看板偏好）/ ipc / island / tray / logger / smoke
|
||||
src/main/ 主进程：index / config（含作业短语与看板偏好）/ ipc / island / tray / update / 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
|
||||
manifest.yml 清单：id=classhelper.classisland.bridge / apiVersion=2.0.0.0 / version=1.1.0.0
|
||||
ClassHelper.ClassIslandPlugin.csproj（TargetFramework=net8.0）
|
||||
src/Plugin.cs 入口：读配置 → 注册提醒提供方 / 设置页 / BridgeService
|
||||
src/Models/PluginSettings.cs
|
||||
@@ -174,6 +181,7 @@ pnpm build:classisland-plugin
|
||||
| `pnpm dist:classisland-plugin` | 打包插件为 `.cipx` 并归集到 `releases/classisland-plugin/` |
|
||||
| `pnpm typecheck` | 全仓库类型检查（含 `vue-tsc`） |
|
||||
| `pnpm lint` / `pnpm lint:fix` | ESLint |
|
||||
| `pnpm check:icons` | 图标注册表门禁（两端 build 已内联，这里可单独跑；见 §5 第 53 条） |
|
||||
| `pnpm format` / `pnpm format:check` | Prettier（`format:check` 在 master 基线上本就失败，见 §7 第 21 条） |
|
||||
| `pnpm db:generate` | 生成 Prisma Client |
|
||||
| `pnpm db:migrate` | `prisma migrate dev`（本机不可靠，别用；见 §7） |
|
||||
@@ -181,13 +189,14 @@ pnpm build:classisland-plugin
|
||||
| `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:e2e` | 后端端到端验收（**需后端已启动**；2026-10-05 实测 190 项全过） |
|
||||
| `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 dist:server:linux` | 打包 **Linux 服务端安装包**（`classhelper-server-linux-x64-<版本>.tar.gz` + `.sha256`）—— 见 §5 第 59 条 |
|
||||
| `pnpm icons` | 生成应用图标（Electron 渲染 SVG → PNG/ICO） |
|
||||
|
||||
### 端口
|
||||
@@ -204,6 +213,7 @@ pnpm build:classisland-plugin
|
||||
|
||||
```
|
||||
release-server/ pnpm dist:server 的输出（免安装目录 + NSIS 安装程序）
|
||||
pnpm dist:server:linux 的输出（classhelper-server-linux-x64-<版本>.tar.gz + .sha256）
|
||||
packages/desktop-client/release/ pnpm dist:win / dist:dir 的输出（win-unpacked + setup.exe + portable.exe）
|
||||
releases/ 本仓库约定的归集处（把上面的产物拷进 client/ server/ classisland-plugin/）
|
||||
```
|
||||
@@ -214,6 +224,7 @@ node packages/desktop-client/scripts/dist-win.mjs -c.directories.output=<绝对
|
||||
|
||||
# 服务端：输出路径写死在 release-server/，打完自行移进 releases/server/
|
||||
pnpm dist:server # 首次会跑一次 npm install；重试可加 --reuse-deps 跳过
|
||||
pnpm dist:server:linux # Linux 安装包（**必须在 Linux 上跑**，见 §5 第 59 条 ④）
|
||||
|
||||
# ClassIsland 插件：构建脚本自己归集到 releases/classisland-plugin/
|
||||
pnpm dist:classisland-plugin
|
||||
@@ -224,8 +235,9 @@ 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`。
|
||||
`*.schemas.ts` zod 校验、`*.service.ts` 业务）。当前 15 个：`auth / classes / courses / schedules /
|
||||
homeworks / notifications / calls / imports / integrations / grades / students / teachers / dashboard /
|
||||
database / update`。
|
||||
新增/下线功能**只改 `src/modules/registry.ts`**（加一行 / 改 `enabled: false`），不要动 `app.ts`。
|
||||
2. **统一响应与校验。** 用 `src/lib/http.ts` 的 `sendOk / sendCreated / …` 返回，用
|
||||
`middleware/validate.ts` 挂 zod schema；错误交给 `middleware/error.ts`，不要各写一套。
|
||||
@@ -360,7 +372,10 @@ homeworks / notifications / calls / imports / integrations / grades / students /
|
||||
主进程把窗口**贴合岛体**（`windowBox` = 当前形态 + 2×阴影留白）并**始终接收输入**
|
||||
（`setInteractive` 在触摸模式下把入参强制为 true）。三条护栏别动：
|
||||
|
||||
- **变小要等岛真的收小**（`cardFitsFormSize` + 渲染进程上报的岛体矩形）—— 立刻缩小会把形变中的卡片裁掉；
|
||||
- **窗口可见期间只增不减**：`syncTouchLayout()` 里 `if (shrinking && this.win.isVisible()) return;`
|
||||
—— 需要变小一律等窗口隐藏之后再做（`syncWindow()` 的"不可见时对齐包围盒"那条）。立刻缩小既会裁掉
|
||||
形变中的卡片，又会因为 DWM 还没重画桌面而留下上一帧（用户拍照反馈过"收回一瞬间闪一下"）；
|
||||
（注：`cardFitsFormSize()` 这个"按岛体矩形判断能不能缩"的旧判据**已无调用**，别再照它理解现状。）
|
||||
- `expectedHitRect` 必须按**窗口实际尺寸**算偏移（触摸模式下窗口不再是固定包围盒）；
|
||||
- 失焦宽限期用 `BLUR_GRACE_TOUCH_MS`（1200ms）：触摸没有光标，`isCursorOnIsland()` 恒为 false，
|
||||
而实测假失焦出现在 70~520ms（跨过 500ms 边界 ⇒ 会把刚展开的岛缩回胶囊）。
|
||||
@@ -427,16 +442,17 @@ homeworks / notifications / calls / imports / integrations / grades / students /
|
||||
回执拿到 id 后再补记一次，投递前用 id / 指纹双重判定。改作业录入入口时别忘了在请求前调
|
||||
`markHomeworkCreatedLocally()`。回归用例：「本机录入的作业不再上灵动岛」。
|
||||
|
||||
36. **触摸模式下收回动画期间，窗口必须一动不动**（`syncTouchLayout()` 开头 `if (this.closing) return;`）。
|
||||
36. **触摸模式下收回动画期间，窗口必须一动不动**（窗口可见期间一律不缩窗口，见 `syncTouchLayout()`）。
|
||||
触摸模式窗口是"贴合岛体"的，而收回时卡片正在缩小：若跟着缩窗口，**中心停靠下窗口 x 还要右移**，
|
||||
"让出去"的那块区域会留着上一帧（DWM 还没重画桌面）——同一帧里能看到"旧展开卡的左半截 + 新胶囊"
|
||||
两份画面（用户拍照反馈的"收回一瞬间闪一下"）。窗口尺寸一律等**隐藏之后**再对齐
|
||||
（`syncWindow` 里"不可见时对齐包围盒"那条，不可见时改尺寸不会有残影）。
|
||||
回归用例：「触摸模式收回：动画期间窗口不动」逐帧采样窗口矩形（只在"窗口可见 / 正在收回"时追究，
|
||||
收完隐藏后对齐尺寸是正常的）；「收回动画期间卡片不被窗口裁切」。
|
||||
另：`cardFitsFormSize()` 的判据里**不能**再塞 `closing` —— 那条早退已经把收回整个排除了，
|
||||
早先漏掉这一条时窗口会在卡片还很大时就缩成胶囊尺寸，卡片底部被平切（"上半剩圆角、下半截断"）；
|
||||
而"隐藏态改边距不生效"那条修法仍要保留：`this.win.isVisible() && (mode !== 'hidden' || idleSliver)`。
|
||||
另：**别再去代码里找 `closing` 或 `cardFitsFormSize()`** —— 自研的那层"收回快照"（§5 第 34 条已说明
|
||||
整体删除）与"按岛体矩形判断能否缩小"这个旧判据都已不在调用链上，最终判据只有上面那条
|
||||
`shrinking && isVisible` 早退。"隐藏态改边距不生效"则是由 `setAppearance()` 无条件 `relayout()`
|
||||
加 `applyWindowLayout()` 的"矩形没变就不调 setBounds"守卫保证的，同样不需要额外的可见性判断。
|
||||
|
||||
37. **开合时胶囊内容禁止跟着卡片重排/横移。** 卡片在 268 ⇄ 424 之间变宽变窄，中心停靠下左右边都在动；
|
||||
胶囊内容若按卡片宽度布局，就会出现"文字先按宽卡片铺开、再随卡片收窄被省略号收回"
|
||||
@@ -537,16 +553,44 @@ homeworks / notifications / calls / imports / integrations / grades / students /
|
||||
**`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 同款，也让小窗口侧栏不溢出）；
|
||||
49. **侧栏是"一级项 + 一个设置分组"，折叠后是图标导轨 —— 五条硬要求**，都是用户报过的问题固化的：
|
||||
① **菜单结构**：课表 / 作业 / 通知 / 成绩是**一级 `el-menu-item`**（2026-10-05 按用户要求把原来的
|
||||
「学习」分组拆掉：分组标题白占一行、还得多点一次展开，折叠成导轨时尤其明显）；只有「设置」
|
||||
保留 `el-sub-menu`（6 个子项平铺太长）。`layoutNavigationSelfTest` 里有断言盯着
|
||||
"一级项不能还挂在任何 `.el-sub-menu` 里"。
|
||||
② **折叠是 CSS 收拢动画，不用 `el-menu` 的 `:collapse`** —— 那个 prop 会把每个分组的子项
|
||||
卸载进浮层（一次结构切换）并让整条菜单重排一遍：既做不出连续形变，也是"点汉堡卡一下"的渲染侧来源。
|
||||
现在折叠只做三件事：栏宽（`.aside` 的 `width` 过渡）、文字（`min-width:0` 让 flex 压得动 +
|
||||
`overflow:hidden` 裁切 + `opacity` 淡出）、图标位置（`padding-left` 过渡）。**全程没有结构变化、
|
||||
没有 `v-if` 增删**，导轨里分组标题与子项都以图标列出（**不再有悬停浮层**）。
|
||||
时长/缓动/图标-文字间距统一在 `styles/index.css` 的 `--nav-dur` / `--nav-ease` / `--nav-gap`。
|
||||
③ **折叠态图标必须与顶部汉堡按钮同一竖列**（冒烟断言中心差 ≤ 2px，实测 11 个图标全 0.0px）。
|
||||
几何：64px 栏、菜单项左右各 8px margin、折叠后 padding 左右各 12px ⇒ 图标中心 = 8+12+12 = 32px
|
||||
= 64/2；汉堡靠 `padding-left: 18px` 位移到位（**不能用 `justify-content: center`**，它不可过渡）。
|
||||
④ **导轨必须"一眼看全"，不许出现滚动**（用户要求"不要用滚轮、删掉滚动条"）：
|
||||
- 折叠态页脚要**把高度也收掉**（`.is-collapsed .aside-footer` 的 `max-height: 0` +
|
||||
**`min-height: 0`** —— flex 子项默认 `min-height: auto`，而 CSS 里 min-height 优先于 max-height，
|
||||
不显式归零就压不下去）。留着那 ~70px 的话，11 行图标（462px）在 540px 的最小窗口里放不下。
|
||||
- 导轨里用 `.is-collapsed .menu { scrollbar-width: none }` 隐藏滚动条；展开态**不隐藏** ——
|
||||
那一栏确实会超（设置组展开约 606px > 582px），滚动条是"下面还有内容"的唯一提示。
|
||||
- 冒烟断言「导轨无溢出」（先展开设置组造出 11 行的最坏情况，再断言 `scrollHeight ≤ clientHeight`）。
|
||||
⑤ **折叠态文字不能"看得见"** —— 判据已从"没被布局"（老的 `display:none`）改成"看得见"
|
||||
（有宽度且未透明）：现在靠 `overflow:hidden` 裁切，文字仍参与布局。冒烟断言「文字残影=无」。
|
||||
（另：菜单区仍要 `min-height: 0` + `overflow-y: auto`，footer 是 aside 的兄弟 flex 子项，
|
||||
菜单区滚动后它恒定可见 —— 冒烟断言「侧栏底部可见」。）
|
||||
|
||||
改折叠相关样式时的两个坑：
|
||||
- **压 Element Plus 的层级缩进必须照抄它的选择器形状**：EP 用**三个不同选择器**分别算
|
||||
「一级项 20px / 分组标题 20px / 分组内子项 40px」（特异度 0-4-0 / 0-4-0 / 0-5-0）：
|
||||
`.el-menu--vertical:not(.el-menu--collapse):not(.el-menu--popup-container) .el-menu-item`
|
||||
（把 `…__title`、以及多加一层 `.el-sub-menu` 的变体都算上）。写成
|
||||
`.ch-nav.is-collapsed .el-sub-menu__title` 这种 0-3-0 的一条都压不住 —— **踩过两次**：
|
||||
第一版漏了分组标题（偏 8.0px），把「学习」拆成一级项后又漏了一级项（同样偏 8.0px）。
|
||||
现在 `index.css` 里那两条（0-5-0 / 0-6-0）把三种形状全覆盖。
|
||||
- 图标与文字的间距放在**文字的 `margin-left`** 上，别用 EP 给图标挂的 `margin-right: 5px`
|
||||
（那会让图标在 24px 的槽里偏左 2.5px）。
|
||||
|
||||
另：分组**默认只展开当前路由所在分组**（落在四个一级项上时一个都不展开）；
|
||||
`el-sub-menu__title` 的点击是 **toggle**，自动化里要先判"子项是否可见"再决定点不点标题
|
||||
（盲点会把已展开的组收起来，后续点不到子项）。
|
||||
|
||||
@@ -563,6 +607,165 @@ homeworks / notifications / calls / imports / integrations / grades / students /
|
||||
处理方式是用环境变量传实际凭据（脚本原生支持，**不要去改数据**）：
|
||||
`set "ELECTRON_SMOKE_USER=teacher1" && set "ELECTRON_SMOKE_PASSWORD=123456" && pnpm verify:desktop`。
|
||||
|
||||
**注意两个演示账号的口令不一定一起漂**（2026-10-04 实测）：本机 `teacher1 = 123456`、
|
||||
`teacher2` **仍是 `teacher123`**。因此 `verify:e2e`（口令硬编码、不支持环境变量）不能简单地
|
||||
全局替换 `teacher123` —— 那样 teacher2 会 401，直接挂掉 9 条科任老师用例。
|
||||
正确做法是**只替换 teacher1 那一行**的临时副本，跑完即删：
|
||||
|
||||
```bash
|
||||
sed "/username: 'teacher1'/s/'teacher123'/'123456'/" packages/server/scripts/verify-e2e.mjs \
|
||||
> packages/server/scripts/.verify-e2e-local.tmp.mjs
|
||||
node packages/server/scripts/.verify-e2e-local.tmp.mjs # 副本必须放在 scripts/ 内
|
||||
rm packages/server/scripts/.verify-e2e-local.tmp.mjs
|
||||
```
|
||||
|
||||
副本**必须放在 `packages/server/scripts/` 里**（不能放 `.cache/`）：脚本要 `import 'socket.io-client'`，
|
||||
换个目录就 `ERR_MODULE_NOT_FOUND`。
|
||||
|
||||
52. **更新检查：三端共用一套版本口径，但检查路径与"失败即正常"是硬约束。**
|
||||
① **版本号单一来源**：服务端版本由 `lib/version.ts` 读 package.json 得到
|
||||
（打包后读的是运行时清单，即 `dist-server.mjs` 用根 package.json 写的那个），
|
||||
`app.ts` 里**不要再写字面量版本号**（原先有三处 `'1.0.0'`，而仓库里有 5 份 package.json，必漂）。
|
||||
比较逻辑放 `@classhelper/shared` 的 `compareVersions` / `isNewerVersion`，三端共用。
|
||||
② **检查路径不对称是 CSP 逼的，不是随手选的**：Web 端**不能**直连 GitHub
|
||||
（`securityHeaders()` 的 `connect-src` 只有 `'self'` / ws / CORS_ORIGIN），必须走
|
||||
`GET /api/update/check`；客户端在主进程直连 GitHub（渲染进程的 CSP 与导航防线不要为这个开洞）。
|
||||
③ **`ok:false` 是设计内的结果**：机房与教室机器常常只有内网，离线/超时/限流一律收敛成
|
||||
`ok:false` + 一句人话，**失败结果同样进缓存**（否则断网点一次按钮就白等一个超时）。
|
||||
④ **自动化里绝不查外网**：冒烟跳过启动自动检查，`verify:*` 的断言只验"结构完整 + 能降级"，
|
||||
断言"一定有新版本"会把用例绑死在外网可达上。`?force=1` 绕过缓存**只对管理员生效**，
|
||||
否则任意登录用户都能刷爆 GitHub 匿名限流（60 次/小时/IP）。
|
||||
|
||||
53. **Element Plus 图标按需注册，漏注册有构建门禁。** 两端都不再 `import * as ElementPlusIconsVue`
|
||||
全量注册 293 个图标（实测全量打包 minified 203KB，实际只用 22 / 33 个），而是各有一份
|
||||
`packages/web-admin/src/icons.ts` 与 `packages/desktop-client/src/renderer/icons.ts` 显式列名单。
|
||||
**不能改成"模板里逐个 import"**：本项目的图标是按**字符串名**引用的（菜单/路由配置里的
|
||||
`icon: 'Odometer'`、`:icon="'Search'"`、`<component :is="item.icon">`），Element Plus 会用
|
||||
`<component :is="'Odometer'">` 去解析**全局组件名**，图标必须以全局组件存在。
|
||||
漏注册的后果是**界面静默渲染成空白**（只在控制台一条 warning），所以在构建前加了静态门禁
|
||||
`scripts/check-icons.mjs`（已挂进两端 `build` 脚本，根上也可 `pnpm check:icons`）：
|
||||
它对比"源码里用到的图标 ∪"与"注册表里的名单"，有遗漏即 exit 1 并指出出现位置。
|
||||
新增视图时直接用图标名即可，忘了加进注册表会在构建阶段被拦下。
|
||||
|
||||
54. **服务端 dist 是运行产物，不带声明与 sourcemap。** `packages/server/tsconfig.build.json` 与
|
||||
`tsconfig.generate.json` 都显式关掉 `declaration / declarationMap / sourceMap` 并开 `removeComments`
|
||||
—— 根 `tsconfig.base.json` 默认是给"库"用的（三个都开），照搬到服务端会让 dist 从约 0.7MB
|
||||
膨胀到 3.8MB（其中 `.d.ts` 1.5MB + `.d.ts.map` 1.1MB + `.js.map` 0.5MB，全是运行时用不到的）。
|
||||
需要 sourcemap 调试时用 `tsconfig.json`（`noEmit`）即可。
|
||||
**`tsconfig.generate.json` 还必须是自包含的（不 extends 任何配置）**：它随包发布到安装目录的
|
||||
`server/` 一层，而 `tsconfig.json` / `tsconfig.base.json` 两级基配置都不在包里 —— 一旦 extends
|
||||
就会在打包形态下报 `TS5083 Cannot read file .../server/tsconfig.json`，数据库「一键切换」
|
||||
走到"编译新客户端"这一步直接失败（2026-10-05 实测踩到并修掉）。
|
||||
|
||||
55. **服务端安装包的体积靠"运行时裁剪"压，规则写在 `scripts/dist-server.mjs` 的 `pruneRuntime()`。**
|
||||
打包顺序是 `installDependencies() → buildRuntime() → pruneRuntime() → buildInstaller()`，
|
||||
裁剪在最后一份文件就位、打包之前做。当前四条规则与收益（实测删 2329 项 / 省 101MB）：
|
||||
|
||||
| 规则 | 省 | 依据（改之前先看这里） |
|
||||
| ---------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `@prisma/client/runtime` 白名单，只留 sqlite/mysql 的 ESM 方言包 | 61.4MB | 生成的客户端按 **provider 写死**动态 import（`internal/class.ts`），换库重新 generate 只会指向对应方言；`_small_bg` 与 CJS 版永不加载 |
|
||||
| `node_modules/**/*.map` | 19.0MB | Node 没开 `--enable-source-maps` |
|
||||
| `prisma/build/` 只留 sqlite/mysql 查询编译器 | 15.0MB | 部署形态里 CLI 只被用于 `generate` 与 `db push` |
|
||||
| 文档（保留 LICENSE/NOTICE）与测试/示例目录 | 5.2MB | 不会被 require |
|
||||
|
||||
**两条硬护栏（都踩过）**：① 整棵 `@types/**` 不参与裁剪 —— 类型包里的 `test/`、`docs/` 是真实声明
|
||||
文件（`@types/node/test/reporters.d.ts` 被 `test.d.ts` 引用），按"测试目录"删掉会让数据库切换的
|
||||
`tsc` 报 TS6053；② 名字命中 `DROP_DIRS` 的目录，只要里面含 `*.d.ts` 就跳过。
|
||||
改完必须按下面的清单复验（尤其数据库管理模块，它是唯一会调 Prisma CLI 的地方）。
|
||||
|
||||
56. **`verify:classisland` 开头会先"抽干"本班的历史积压提醒。** `/integrations/classisland/pending`
|
||||
是「本班全部未确认提醒，按时间升序取**前 20 条**」，而 `verify:desktop` / `verify:web` 等冒烟会
|
||||
**真的往演示班发通知**（见 §5 第 38 条）——那些条没被确认就会一直堆着，攒够 20 条之后
|
||||
本脚本刚发的提醒会被挤出窗口，表现为「待提醒里找不到刚发的那条」，跟代码对不对毫无关系
|
||||
（2026-10-05 实测：库里积了 45 条历次冒烟残条，本脚本从 42/42 掉到 35/40）。
|
||||
现在脚本用 `drainPending()` 按**真实插件重连后的行为**（补弹并逐条确认）先清空，再开始断言，
|
||||
可见范围与插件一致（只看 `deviceId` 为空的本班广播 + 本设备自己的推送）。
|
||||
**别把这个 drain 删掉**，否则这个门禁会重新变成"跑几次就红"的随机失败。
|
||||
|
||||
57. **桌面端配置（`config.json`）是"常驻内存 + 异步合并落盘"，别再当成同步写。**
|
||||
`main/config.ts` 里配置**只读一次盘**（懒初始化），`getConfig()` / `saveConfig()` 之后一律走内存缓存
|
||||
（连已解密的 token 一起缓存，不再每次过一遍 DPAPI）；落盘改成"记下待写 → 120ms 合并窗口 →
|
||||
`fs.promises.writeFile`"，同一拍内的多次改动只写最后一次，多次写入之间串行、不会互相覆盖；
|
||||
退出前由 `flushConfigSync()`（挂在 `main/index.ts` 的 `shutdownResources()` 里）同步兜底写一次。
|
||||
|
||||
**为什么必须这样**：侧栏折叠、主题切换、通知渠道、作业看板偏好、登录/登出**全都走 `saveConfig`**，
|
||||
而它原先一次调用要在**主进程主线程**上做「`readFileSync` + `JSON.parse` + 8 个 normalize」**两遍**
|
||||
（开头读一遍、结尾 `getConfig()` 又读一遍）+ `writeFileSync` + DPAPI 解密一遍 —— 主进程是 Electron 的
|
||||
消息泵进程，被它摁住的那一拍渲染进程也跟着掉帧。用户反馈的「点侧栏汉堡展开/收回时卡一下」
|
||||
就是这一拍（2026-10-05 定位并修掉；当时先误查到灵动岛，那块与它无关）。
|
||||
|
||||
三条硬约束：
|
||||
① **缓存必须懒初始化**：`main/index.ts` 会先 `app.setPath('userData', smokeProfile)` 再读配置，
|
||||
在模块顶层立即读盘会读错文件；
|
||||
② **`saveConfig()` 返回时数据可能还没落盘**（最多晚 120ms）。要"读回刚存的值"一律用 `getConfig()`
|
||||
（读的就是缓存里的最新值），别去读文件；正常退出（托盘 → 退出）会 flush，只有进程被强杀才会丢
|
||||
最后 120ms 内的改动；
|
||||
③ 别把落盘写成"每次保存挂一个 promise 链"—— 拖滑块/连点会排队几十次写。`clearConfig()`（退出登录）
|
||||
走 `immediate` 分支，不参与合并窗口。
|
||||
|
||||
58. **顶栏右侧（主题切换按钮 + 用户名下拉）必须是 flex 容器。** Element Plus 给 `.el-button` 的是
|
||||
`vertical-align: middle`、给 `.el-dropdown` 的是 `vertical-align: top` —— 两个 inline-level
|
||||
子元素放在普通 block 容器里会各按各的垂直对齐规则落位，错开几像素（用户反馈的"**深色模式没对齐**"，
|
||||
其实两种主题下都偏，只是深色下更显眼）。`.header-right` 必须写
|
||||
`display:flex; align-items:center; gap`，与 Web 管理端 `AdminLayout` 的同名容器同一套写法
|
||||
（那边一开始就是对的，桌面端当初漏了这条规则）。回归断言在 `layoutChromeSelfTest` 里：
|
||||
量主题按钮与 `.user-chip` 的**中线差**，要求 ≤ 1.5px（实测 0.0px）。
|
||||
|
||||
59. **Linux 交付链有六条硬约定**（`deploy/install.sh`、`deploy/classhelper`、`scripts/dist-server.mjs`
|
||||
的 `--platform linux`、`deploy/verify-linux.sh`）。改这条链路前先读这一节，每条都对应一个踩过的坑：
|
||||
|
||||
① **配置真身在 `/etc/classhelper/config.env`，安装目录里的 `.env` 必须是指向它的软链。**
|
||||
Web 端「数据库管理 → 一键切换」在运行中改写的是 **`<安装目录>/.env`**（`database.service.ts`），
|
||||
而 systemd 是通过 `EnvironmentFile=` 注入同一份配置的；dotenv 不覆盖已存在的环境变量，
|
||||
所以两处一旦不是同一个文件，切换就会**看起来成功、重启后又连回旧库**（极难排查）。
|
||||
权限同时满足"配置文件 600 / 配置目录 700"与服务进程可读写（属主给 `classhelper`）。
|
||||
`classhelper doctor` 里有专门一条断言盯着这条软链。
|
||||
|
||||
② **systemd 单元的 `ReadWritePaths` 必须同时包含安装目录与配置目录。**
|
||||
服务端不是只写 `data/`：一键切库会改写 `server/prisma/schema.prisma`、把新客户端编译进
|
||||
`server/dist/generated`，并改写 `config.env`。`ProtectSystem=full` 下不显式放行就会失败。
|
||||
占位符有 5 个：`__NODE__ __DIR__ __USER__ __CONFIG__ __CONFIGDIR__`（少替换一个，
|
||||
systemd 会拿字面量当路径）。
|
||||
|
||||
③ **升级/回滚替换程序文件必须用"改名 + 就位"，不能 `rm -rf` 再 `cp`。**
|
||||
升级时正在运行的就是 `bin/classhelper` 自己：先 `mv bin bin.old-…` 再放新目录，
|
||||
运行中的进程继续读旧 inode；直接删掉同名文件会让 bash 读到半个脚本（报莫名其妙的语法错误）。
|
||||
|
||||
④ **Linux 包只能在 Linux 上构建，产物名固定。** `@libsql/linux-x64-gnu`、`@prisma/adapter-libsql`
|
||||
是平台相关依赖，Windows 上装的 `node_modules` 拷过去跑不起来 ⇒ 由
|
||||
`.github/workflows/release-linux-server.yml`（ubuntu runner）出包。命名约定
|
||||
`classhelper-server-linux-<arch>-<版本>.tar.gz` + 同名 `.sha256`（旁边那份、以及 Release 里的
|
||||
`SHA256SUMS-<版本>.txt`），`classhelper upgrade` 按这个名字拼下载地址，**改名即断升级链路**。
|
||||
非 Linux 上 `--platform linux` 也能跑（会加 npm 的 `--os=linux --cpu=x64` 按目标平台解析依赖），
|
||||
但那是**应急**，已在 2026-10-05 实测核对过包内容：`@libsql/linux-x64-gnu`/`-musl` 就位、无 win32 残留、
|
||||
服务端与全部运维命令可用；**只有 Web 端「一键切换数据库」存疑** —— 那条链路要 prisma CLI 的原生
|
||||
schema engine，CLI 运行期按平台扫 `@prisma/engines/schema-engine-debian-openssl-3.0.x` 这类路径，
|
||||
而交叉包里只有 `schema-engine-windows.exe`。交叉构建会写入 `.cross-built` 标记，
|
||||
`classhelper doctor` 据此提示（别改成静默），`upgrade` 替换程序文件时会按新包有无该标记来增删。
|
||||
正式产物仍走 CI。
|
||||
|
||||
⑤ **密码永远走 stdin，命令行一律不接受密码；调用服务端模块的工具必须压掉它的 stdout 噪声。**
|
||||
`classhelper password` 用 `read -s` 优先读 `/dev/tty`、无 tty 回退 stdin（这样既能交互，
|
||||
也能被验收脚本用管道喂 —— 都不进 history/ps）。输入循环**必须有界**：stdin 结束时 `read`
|
||||
返回非 0，不看这个标记就会在 EOF 上死循环（`verify-linux.sh` 里有一条"不合规时不卡死"的回归）。
|
||||
写配置（`config set`）同理：值经临时文件传给 `awk`，不进 argv；敏感键强制交互输入，
|
||||
`key rotate` 自己生成的密钥走内部写函数。另外 `tools/admin-cli.mjs` 复用了服务端的
|
||||
`config/env.ts` 与 `lib/logger.ts`，**这两个模块会往 stdout 打日志**（dotenv 的
|
||||
`◇ injected env …` 提示、Prisma 初始化一行）—— 调它时必须带上
|
||||
`LOG_LEVEL=error DOTENV_CONFIG_QUIET=true`，否则 `dump-hash` 写出的"原哈希备份"里会多一行日志，
|
||||
变成非法 JSON，**改密失败自动回滚整条链路静默失效**（dotenv 不覆盖已有环境变量，所以这两个
|
||||
变量能生效，已实测）。
|
||||
|
||||
⑥ **内置 Node 要按 glibc 选构建。** Node 官方 linux-x64 二进制要求 glibc ≥ 2.28，
|
||||
CentOS 7 是 2.17 —— 装上去的表现为"服务起来就退出、日志什么都没有"。安装器检测 glibc，
|
||||
低于 2.28 时自动改用 unofficial-builds 的 `-glibc-217` 变体。CentOS 7 仍属尽力而为。
|
||||
|
||||
两条写这类脚本时的通用坑（本仓库踩过）：**`set -e` 下 `[ cond ] && 可能失败的命令` 会
|
||||
在条件为假时……其实不会退出**（bash 对 `&&` 列表里非最后一条失败是豁免的），但
|
||||
`A && B` 里 B 失败、以及**用 `$(函数)` 捕获输出时把日志一起捕获**（所以安装器用全局
|
||||
`STAGE_DIR` 而不是 `echo` 返回路径）这两类是实打实的 bug；`die` 要先 `trap - ERR` 再退出，
|
||||
免得 ERR 钩子再补一句误导的"第 N 行执行失败"。
|
||||
|
||||
---
|
||||
|
||||
## 6. 代码风格
|
||||
@@ -578,6 +781,14 @@ homeworks / notifications / calls / imports / integrations / grades / students /
|
||||
- **提交信息**：Conventional Commits + 模块 scope，描述用中文，可多 scope，例如
|
||||
`fix(island): 胶囊"点不动"的根因——窗口必须始终可激活`、
|
||||
`feat(teachers,classes,schedules,web): 教师录入（仅管理员）`。
|
||||
- **图表不引第三方库。** 全项目只有三张图（桌面端成绩页 1 张柱状图；Web 端成绩页柱状 + 折线各 1 张），
|
||||
历史上用 echarts 全量引入，占了桌面端渲染产物 1.12MB（35%）与 Web 端 1.13MB。现在换成
|
||||
自包含的轻量组件：`packages/desktop-client/src/renderer/components/ScoreBarChart.vue`、
|
||||
`packages/web-admin/src/components/{ScoreBarChart,ScoreLineChart}.vue` ——
|
||||
柱状图是纯 HTML/CSS（柱高走百分比、刻度与网格线用**零高度 flex 行 + space-between** 对齐），
|
||||
折线图是 `viewBox="0 0 100 100" + preserveAspectRatio="none"` 的 SVG（数据点用 HTML 绝对定位，
|
||||
免得非等比拉伸把圆点压成椭圆）。两者都是响应式的，**不要给它们加重算尺寸的 resize 监听**。
|
||||
新增图表请沿用这个做法，不要重新引入图表库。
|
||||
- **改动交付形态 / 新增功能后**，同步更新 `README.md`（它兼作产品说明书与验收对照表）。
|
||||
|
||||
---
|
||||
@@ -730,6 +941,24 @@ homeworks / notifications / calls / imports / integrations / grades / students /
|
||||
同理，断言岛体尺寸别写死"胶囊尺寸 + 留白"：那一刻是胶囊还是卡片取决于前面用例留下的状态，
|
||||
应改成**与形态无关的不变量**（如"窗口 = 卡片实测尺寸 + 2×阴影留白"）。
|
||||
|
||||
23. **客户端安装包有硬底：`班级小助手.exe` 单独压缩后就有 85~90MB，"压到 60MB"做不到 —— 别再为这个反复折腾。**
|
||||
实测（2026-10-05，Electron 44.3.0）：`win-unpacked` 372MB，其中 `班级小助手.exe`（就是 electron.exe，
|
||||
rcedit 只加了 74KB）**234.7MB**；brotli-9 抽样压缩后估算它单独就有 85~90MB。也就是说把渲染产物
|
||||
从 3.2MB 压到 2.1MB、把图标从 293 个减到 42 个，对安装包只影响约 1MB。
|
||||
剩下能动的只有这些（合计约 12MB，风险不成比例，**当前一律不做**）：
|
||||
`dxcompiler.dll + dxil.dll` 26MB（D3D12 着色器编译）、`vk_swiftshader + vulkan-1` 6.2MB、
|
||||
`d3dcompiler_47.dll` 4.5MB（D3D11 回退）、`chrome_200_percent.pak` 1.2MB（高 DPI）、`ffmpeg.dll` 3MB。
|
||||
教室机器多是老显卡 / 希沃一体机 / 虚拟机，删掉这些就是拿渲染可靠性换体积。
|
||||
**唯一做的一条**是语言包：`electron-builder.yml` 的 `electronLanguages: [zh-CN]`
|
||||
（官方选项，`app-builder-lib` 的 `removeUnusedLanguagesIfNeeded()` 会精确删掉其余 54 个
|
||||
`locales/*.pak`）。实测 `win-unpacked` 372MB → **323MB**、`setup.exe`/`portable.exe`
|
||||
107.2MB → **98.7MB / 98.4MB**（表中口径均为 MiB，与本机 `ls -la` / `du` 一致）。
|
||||
|
||||
要真正做到 60MB 只能换渲染运行时（WebView2 / Tauri，安装包可到 5~15MB），代价是把
|
||||
`src/main/island.ts`（1840 行）里全部原生窗口行为重写一遍 —— 逐像素透明、鼠标穿透、
|
||||
窗口贴合岛体、触摸模式、多屏/DPI，全是 §5 第 10/16/21/22/30/32/36/37 条踩过坑的地方，
|
||||
且 `verify:desktop` / `verify:packaged` 的整套回归要重做。属于独立立项，不是顺手优化。
|
||||
|
||||
### 已知脆弱用例（不是环境问题，别去"修环境"）
|
||||
|
||||
| 用例 | 触发条件 |
|
||||
@@ -748,7 +977,7 @@ pnpm lint # ESLint（0 error 为底线）
|
||||
pnpm typecheck # 全仓库类型检查
|
||||
|
||||
pnpm dev:server # 另开终端
|
||||
pnpm verify:e2e # 后端端到端（2026-09-30 实测 173 项全过）
|
||||
pnpm verify:e2e # 后端端到端（2026-10-05 实测 190 项全过）
|
||||
pnpm verify:classisland # ClassIsland 联动链路（实测 42 项）
|
||||
pnpm verify:classisland-plugin # 插件静态契约（不需要后端，实测 68 项）
|
||||
pnpm build:desktop && pnpm verify:desktop # 客户端冒烟（AI 会话可跑，先看 §7 第 7 条）
|
||||
@@ -758,6 +987,25 @@ pnpm build && pnpm verify:web # Web 端真实点击回归（同上
|
||||
条目数由脚本自行统计并打印（`=== 结果：N/N 项通过 ===`、`ClassIsland 联动插件静态校验：N/N 项通过`），
|
||||
文档不要写死容易过期的总数。
|
||||
|
||||
改动到 **Linux 交付链**（`deploy/install.sh`、`deploy/classhelper`、`deploy/tools/`、
|
||||
`scripts/dist-server.mjs` 的 linux 分支、systemd/profile.d/logrotate 模板）时：
|
||||
|
||||
```bash
|
||||
bash -n deploy/install.sh deploy/classhelper deploy/verify-linux.sh deploy/install-linux.sh # 语法（Windows 上就能跑）
|
||||
pnpm dist:server:linux # 只能在 Linux 上跑；开发机是 Windows 时到服务器/CI 上验证
|
||||
|
||||
# 真机（任意一台能 SSH 的 Linux，容器也行但 systemd 用例会跳过）
|
||||
scp release-server/classhelper-server-linux-x64-*.tar.gz deploy/{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"
|
||||
ssh root@<主机> "bash /tmp/verify-linux.sh --admin-password-stdin" < <(printf '%s\n' '<密码>')
|
||||
```
|
||||
|
||||
`verify-linux.sh` 会**真的**改一次管理员密码再回滚、真的发一条备份，跑完机器仍是可用状态；
|
||||
升级/回滚链路要加 `--full --package <新版本包>`（会真的替换一次程序文件）。
|
||||
**改过这条链路就要在真机上跑一遍**——脚本写在 Windows 上跑不出问题，`set -e` 的坑、
|
||||
systemd 的 `EnvironmentFile` 解析、glibc 差异都只有在 Linux 上才暴露。
|
||||
|
||||
改动到 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 条部署）：
|
||||
@@ -777,4 +1025,28 @@ Start-Process D:\Classisland\ClassIsland.exe -WorkingDirectory D:\Classisland
|
||||
并用 `pnpm verify:packaged --exe "<客户端路径>"` 对**打包后的副本**复验 ——
|
||||
开发产物通过不等于用户机器上的副本通过。
|
||||
|
||||
**改过 `pruneRuntime()`（§5 第 55 条）时，还要对免安装目录本身跑一遍**（开发形态跑通不代表裁剪后跑通）。
|
||||
从 `release-server/classhelper-server/` 起，用**自带的 node.exe**：
|
||||
|
||||
```bash
|
||||
# ① 起服务：探针通 + 能真实查表（AUTO_MIGRATE 会建库；PORT 用环境变量避开开发端口）
|
||||
cd release-server/classhelper-server && PORT=4100 ./node.exe server/dist/index.js
|
||||
curl.exe -s --noproxy '*' http://127.0.0.1:4100/healthz
|
||||
curl.exe -s --noproxy '*' -X POST http://127.0.0.1:4100/api/auth/login \
|
||||
-H "content-type: application/json" -d '{"username":"admin","password":"admin123"}'
|
||||
|
||||
# ② 数据库「一键切换」的三步子进程链路（唯一会调用 Prisma CLI 的地方）
|
||||
cd server
|
||||
DATABASE_PROVIDER=sqlite DATABASE_URL="file:./prune-test.db" \
|
||||
../node.exe ../node_modules/prisma/build/index.js generate
|
||||
../node.exe ../node_modules/typescript/lib/tsc.js -p tsconfig.generate.json
|
||||
DATABASE_PROVIDER=sqlite DATABASE_URL="file:./prune-test.db" \
|
||||
../node.exe ../node_modules/prisma/build/index.js db push --accept-data-loss
|
||||
```
|
||||
|
||||
跑完把这几个测试残留删掉，别带进交付目录：`server/src`、`server/prune-test.db`，
|
||||
并把 `data/`、`logs/` 清空。
|
||||
（`prisma db push` 是破坏性命令，Prisma 7.10 的 AI 代理护栏会要求显式同意；
|
||||
这里的目标是脚本刚建出来的空临时库，不是真实数据。）
|
||||
|
||||
自测本地接口记得绕过代理（见 §7 第 1 条）。
|
||||
@@ -1,7 +1,7 @@
|
||||
# 班级小助手（Class Helper）
|
||||
|
||||
班级信息管理系统。一个 pnpm monorepo，一份代码产出四个交付物：**后端服务**、**Web 管理端**（教师 / 管理员）、
|
||||
**桌面客户端**（学生端 / 教室机器）与 **ClassIsland 联动插件**（装在教室的 ClassIsland 上）。**当前版本 1.0.0**。
|
||||
**桌面客户端**（学生端 / 教室机器）与 **ClassIsland 联动插件**（装在教室的 ClassIsland 上）。**当前版本 1.1.1**。
|
||||
|
||||
核心链路：
|
||||
|
||||
@@ -40,6 +40,7 @@ ClassIsland（教室机器）──► 联动插件 ──► /api/integrations/
|
||||
- [4.7 表格与 ClassIsland 导入](#47-表格与-classisland-导入)
|
||||
- [4.8 ClassIsland 联动](#48-classisland-联动)
|
||||
- [4.9 数据库管理](#49-数据库管理仅管理员)
|
||||
- [4.10 更新检查](#410-更新检查)
|
||||
- [5. 技术参考](#5-技术参考)
|
||||
- [5.1 目录结构](#51-目录结构)
|
||||
- [5.2 技术栈](#52-技术栈)
|
||||
@@ -72,25 +73,41 @@ ClassIsland（教室机器）──► 联动插件 ──► /api/integrations/
|
||||
|
||||
## 2. 交付产物与部署形态
|
||||
|
||||
| 产物 | 产物文件位置（打包后） | 用途 |
|
||||
| ------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| **服务端 + Web 管理端安装程序** | `release-server/班级小助手服务端-<版本>-x64-setup.exe` | 装到教师电脑 / 校服务器即完整系统，**内置 Node 运行时**，双击安装、开机自启、自动建库建号 |
|
||||
| **学生客户端安装程序** | `packages/desktop-client/release/班级小助手-<版本>-x64-setup.exe` | 学生机安装（NSIS） |
|
||||
| **学生客户端单文件版** | `packages/desktop-client/release/班级小助手-<版本>-x64-portable.exe` | 免安装直接运行（U 盘分发） |
|
||||
| Web 管理端（PWA） | 由服务端在 `/` 直接托管 | 浏览器打开即用，可在 Edge/Chrome 中「安装为应用」；已适配手机小屏 |
|
||||
| **ClassIsland 联动插件** | `releases/classisland-plugin/ClassHelper.ClassIslandPlugin.cipx` | 装在教室机器的 ClassIsland 上（也可把 `ClassHelper.ClassIslandPlugin/` 目录丢进 Plugins） |
|
||||
| 产物 | 产物文件位置（打包后） | 用途 |
|
||||
| ------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| **服务端 + Web 管理端安装程序** | `releases/server/<版本>/安装包/班级小助手服务端-<版本>-x64-setup.exe` | 装到教师电脑 / 校服务器即完整系统，**内置 Node 运行时**，双击安装、开机自启、自动建库建号 |
|
||||
| **服务端 Linux 安装包** | `releases/server/<版本>/linux-x64/classhelper-server-linux-x64-<版本>.tar.gz` | 给 `deploy/install.sh` 用（另见同名 `.sha256`）；由 Actions 在 Linux 上构建后挂 Release |
|
||||
| **学生客户端安装程序** | `releases/client/<版本>/安装包/班级小助手-<版本>-x64-setup.exe` | 学生机安装（NSIS） |
|
||||
| **学生客户端单文件版** | `releases/client/<版本>/安装包/班级小助手-<版本>-x64-portable.exe` | 免安装直接运行（U 盘分发） |
|
||||
| Web 管理端（PWA） | 由服务端在 `/` 直接托管 | 浏览器打开即用，可在 Edge/Chrome 中「安装为应用」；已适配手机小屏 |
|
||||
| **ClassIsland 联动插件** | `releases/classisland-plugin/<版本>/安装包/ClassHelper.ClassIslandPlugin.cipx` | 装在教室机器的 ClassIsland 上（也可把 `ClassHelper.ClassIslandPlugin/` 目录丢进 Plugins） |
|
||||
|
||||
> 这些产物**都不入库**（`release-server/`、`packages/*/release/`、`releases/` 均已忽略）。
|
||||
> 仓库约定是把它们归集到根目录 `releases/`（`client/`、`server/`、`classisland-plugin/`），详见 [AGENTS.md](AGENTS.md) §4。
|
||||
> 这些产物**都不入库**（`releases/` 已 gitignore + eslint ignore）。三个打包脚本**直接输出**到
|
||||
> `releases/<组件>/<版本>/`，每个版本目录下按 `安装包/`、`免安装/`、`构建中间/` 分层，
|
||||
> 历史版本原样保留 —— 详见 [AGENTS.md](AGENTS.md) §4。
|
||||
|
||||
四种部署形态按场景选（完整步骤见 [docs/production.md](docs/production.md)）：
|
||||
四种部署形态按场景选（Linux 完整步骤见 [docs/linux-deploy.md](docs/linux-deploy.md)，
|
||||
其余见 [docs/production.md](docs/production.md)）：
|
||||
|
||||
| 场景 | 形态 | 入口 |
|
||||
| ----------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
||||
| 学校机房 / 教师电脑（Windows 单机） | Windows 服务端安装程序（内置 Node，双击即用） | `release-server/班级小助手服务端-<版本>-x64-setup.exe` |
|
||||
| 云服务器 / 多终端共享（推荐长期） | Docker Compose + MySQL（另有 SQLite 单容器版） | `deploy/Dockerfile`、`deploy/docker-compose{,.sqlite}.yml` |
|
||||
| 已有 Linux 服务器 | systemd + SQLite 一键脚本（含 Nginx 反代与 WebSocket 配置） | `sudo bash deploy/install-linux.sh`（先 `--check` 体检）、`deploy/classhelper.service` |
|
||||
| 自定义 / 已有 Node 环境 | 手动部署免安装目录 | `pnpm dist:server` → `release-server/classhelper-server/` |
|
||||
| 场景 | 形态 | 入口 |
|
||||
| ----------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| 学校机房 / 教师电脑（Windows 单机） | Windows 服务端安装程序（内置 Node，双击即用） | `releases/server/<版本>/安装包/班级小助手服务端-<版本>-x64-setup.exe` |
|
||||
| 云服务器 / 多终端共享（推荐长期） | Docker Compose + MySQL（另有 SQLite 单容器版） | `deploy/Dockerfile`、`deploy/docker-compose{,.sqlite}.yml` |
|
||||
| 已有 Linux 服务器 | **一键安装器 + `classhelper` 运维命令**（systemd / docker） | `sudo bash deploy/install.sh`（先 `--check` 体检）；运维见 `classhelper help` |
|
||||
| 自定义 / 已有 Node 环境 | 手动部署免安装目录 | `pnpm dist:server` → `releases/server/<版本>/免安装/` |
|
||||
|
||||
**Linux 服务器最快路径是一行命令**：脚本会自己从 GitHub Release 取最新版服务端包、取发布页上的
|
||||
`.sha256` 校验，再装成 systemd 服务并带上 `classhelper` 运维命令。完整步骤与验收清单见
|
||||
[docs/linux-deploy.md](docs/linux-deploy.md)。
|
||||
|
||||
```bash
|
||||
curl -fsSL -o /tmp/classhelper-install.sh https://raw.githubusercontent.com/LoveChengke/ClassHelper/master/deploy/install.sh && sudo bash /tmp/classhelper-install.sh
|
||||
```
|
||||
|
||||
> 参数接在最后即可，例如先只体检（不需要 root、不改动系统）：把末尾换成
|
||||
> `sudo bash /tmp/classhelper-install.sh --check`。
|
||||
> **别写成 `bash -c "$(curl …)" --check`**：`bash -c '代码' 第一个参数` 里那个参数会变成 `$0`
|
||||
> 而不是 `$1`，脚本收不到（实测踩到：想体检却走进了交互式安装）。
|
||||
|
||||
## 3. 快速开始
|
||||
|
||||
@@ -184,7 +201,7 @@ pnpm verify:desktop
|
||||
| `pnpm build:shared` | 只构建 shared（改完 `packages/shared` 必须跑） |
|
||||
| `pnpm build:desktop` | 只构建客户端（esbuild 主进程 / preload + Vite 渲染进程，末尾跑产物凭据门禁） |
|
||||
| `pnpm build:classisland-plugin` | 构建 ClassIsland 联动插件（.NET 8） |
|
||||
| `pnpm dist:classisland-plugin` | 打包插件为 `.cipx` 并归集到 `releases/classisland-plugin/` |
|
||||
| `pnpm dist:classisland-plugin` | 打包插件为 `.cipx` 并归集到 `releases/classisland-plugin/<版本>/` |
|
||||
| `pnpm icons` | 生成应用图标（Electron 渲染 SVG → PNG/ICO） |
|
||||
| `pnpm dist:server` | 打包服务端 + Web 管理端（免安装目录 + NSIS 安装程序，内置 Node） |
|
||||
| `pnpm dist:dir` | 打包客户端免安装目录 `release/win-unpacked`（最快） |
|
||||
@@ -320,16 +337,17 @@ Element Plus 也通过对齐它的 `--el-border-radius-*` 一并改造：
|
||||
| 课表 | 按周展示 7 列课表（周次下拉 + 单双周标签），另有「今天」时间轴视图（大时钟 + 当前状态卡 + 已结束 / 正在上 / 下一节） |
|
||||
| 作业 | **看板模式**（按科目卡片、全屏放大、显示时间开关、看板字号）＋列表模式、详情抽屉、附件链接（只接受 `http(s)://` 或站内相对路径）；教室设备可**录入作业**与勾选**未交名单** |
|
||||
| 通知 | 未读红点（侧边栏徽标）、优先级标签、点击自动标为已读、全部已读、未读过滤、详情抽屉 |
|
||||
| 成绩 | 班级账号看到**全班成绩总览**：表格（分数 / 得分率 / 等级）+ ECharts 柱状图 + 等级分布 + 最近更新 |
|
||||
| 成绩 | 班级账号看到**全班成绩总览**：表格（分数 / 得分率 / 等级）+ 柱状图 + 等级分布 + 最近更新（图表为内置 HTML/SVG 实现，不引图表库） |
|
||||
| 设置 | 六个子页：通用、外观、灵动岛、提醒、账号、关于（见下） |
|
||||
|
||||
#### 设置改版：分组侧边栏 + 子页 + 深色模式 + 关于页
|
||||
|
||||
**侧边栏（ClassIsland 同款 NavigationView）**：主侧边栏改为「学习」「设置」两个**可展开分组**
|
||||
（学习 = 课表 / 作业 / 通知 / 成绩；设置 = 通用 / 外观 / 灵动岛 / 提醒 / 账号 / 关于，每个子项是独立路由
|
||||
`/settings/*`）；顶部**汉堡按钮**把整栏折叠成 64px 图标栏（折叠状态持久化到主进程配置，重启仍记忆）。
|
||||
折叠态隐藏文字、图标与汉堡按钮同一竖列、菜单区可滚动（底部「第 N 周 / 最近同步」恒定可见）。
|
||||
红点徽标仍挂在「通知」项图标右上方。
|
||||
**侧边栏（ClassIsland 同款 NavigationView）**：主侧边栏是**四个一级项**（课表 / 作业 / 通知 / 成绩）
|
||||
加上一个**可展开分组**「设置」（通用 / 外观 / 灵动岛 / 提醒 / 账号 / 关于，每个子项是独立路由
|
||||
`/settings/*`）；顶部**汉堡按钮**把整栏收成 64px **图标导轨**（折叠状态持久化到主进程配置，重启仍记忆）。
|
||||
收放是连续的 CSS 过渡（栏宽 + 文字收放 + 图标位移，260ms），全程没有结构切换；导轨里文字淡出、
|
||||
分组子项与一级项都以图标列出、图标与汉堡按钮同一竖列，**整条导轨一眼看全、不出滚动条**
|
||||
（页脚在折叠态连高度一起收掉）。红点徽标仍挂在「通知」项图标右上方。
|
||||
|
||||
**设置子页**：原单页设置按卡片拆为 6 个子页 —— 通用（服务器连接 + 离线缓存 + 作业录入短语 +「使用引导」）、
|
||||
外观、灵动岛、提醒、账号、关于；`/settings` 重定向到 `/settings/general`。
|
||||
@@ -750,11 +768,48 @@ MySQL 的连接测试 / 建表 / 写入依赖随包内置的 `@prisma/adapter-ma
|
||||
> （422，e2e 有断言）；PostgreSQL 暂未纳入。
|
||||
> - **切换完成后必须重启服务端**（安装版运行 `restart.cmd`，开发模式重跑 `pnpm dev:server`）才会连接新库；
|
||||
> 切换失败会自动回滚 `schema.prisma`，`.env` 只在数据全部迁移成功后才改写；**目标库必须为空**（有表即拒绝）。
|
||||
> - 安装包体积因此增大约 37MB（~34MB → ~71MB）：切换需要随包内置 prisma CLI 与 TypeScript 编译器
|
||||
> - 安装包体积因此增大（约 34MB → **62MB**）：切换需要随包内置 prisma CLI 与 TypeScript 编译器
|
||||
> （Prisma 7 的生成器产出 .ts 源码，切换后要在目标机编译进 dist）。
|
||||
> 打包末尾会做一次**运行时裁剪**（删掉 Prisma 为其它数据库方言准备的查询编译器副本等死载荷，
|
||||
> 见 `scripts/dist-server.mjs` 的 `pruneRuntime()`），免安装目录 469MB → 335MB。
|
||||
> - 真实切换（SQLite→MySQL）已在本机用完整子进程链路实测（快照 728 行逐表一致）；e2e 只覆盖校验分支
|
||||
> （同库 400 / 非法 provider 422 / 目标库非空拒绝），避免测试改写 `.env`。
|
||||
|
||||
### 4.10 更新检查
|
||||
|
||||
交付物是通过 **GitHub Releases** 分发的（服务端 / 客户端安装包、便携版、插件 `.cipx`），
|
||||
因此"有没有新版本"就是问那条 Release：拉 `releases/latest`（不含草稿与预发布）、
|
||||
把 `tag_name` 与本机版本比一下，比本机新就提示并给一个「前往下载」。
|
||||
|
||||
| 端 | 入口 | 检查路径 |
|
||||
| ------------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
|
||||
| 服务端 / Web 管理端 | 顶栏用户菜单 →「检查更新」 | 浏览器 **→ 服务端 `GET /api/update/check` → GitHub** |
|
||||
| 桌面客户端 | 启动后自动一次（延迟 5 秒）+「设置 → 关于」里的「检查更新」按钮 | 主进程 **→ GitHub**（不经后端） |
|
||||
|
||||
两端的检查路径不同是**被约束逼出来的**，不是随手选的：
|
||||
|
||||
- **Web 端不能直连 GitHub**。服务端下发的 CSP（`middleware/security.ts`）里 `connect-src`
|
||||
只放行 `'self'` 与 WebSocket，浏览器发往 `api.github.com` 的请求会被直接拦掉。
|
||||
走服务端转发还有个好处：所有管理员共享同一份缓存（GitHub 匿名限流是 60 次/小时/IP）。
|
||||
- **客户端在主进程做**。渲染进程的 CSP 与导航防线是安全模型里最要紧的一层，
|
||||
不让它去连外部域名、解析外部 JSON；主进程本来就在做网络与文件。
|
||||
|
||||
**"查不到"是设计内的结果，不是错误**：机房服务器与教室机器常常只有内网，请求会超时/失败。
|
||||
此时接口返回 `ok: false` + 一句人话（「无法连接 GitHub，本机可能没有外网」），
|
||||
界面按"暂时查不到更新"呈现并给重试入口，而不是弹红字报错。**失败结果同样进缓存**，
|
||||
否则断网时每点一次按钮都要白等一个超时。
|
||||
|
||||
| 细节 | 说明 |
|
||||
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 版本比较 | `@classhelper/shared` 的 `compareVersions` / `isNewerVersion`，三端共用一套口径（避免"客户端说有新版、服务端说没有"）。数字相同、只有后缀不同时**带后缀的算更新** —— 对应 `v0.1.0-fix` 这种"同版本号的修复发布" |
|
||||
| 缓存 | 两端各缓存 30 分钟；`?force=1` 绕过服务端缓存，但**仅管理员生效**（否则任意登录用户都能刷爆匿名限流） |
|
||||
| 权限 | 任何已登录用户都能查（信息来自公开仓库）；`force` 除外 |
|
||||
| 提示一次就够 | 客户端启动检查发现新版才推提示；点「忽略此版本」记进 `config.json`，同一版本不再提示（「关于」页仍可手动查） |
|
||||
| 版本号单一来源 | 服务端版本由 `lib/version.ts` 读 package.json 得到（原先 `app.ts` 里硬编码了三处 `'1.0.0'`，与 5 份 package.json 一定会漂移） |
|
||||
| **自动化里不查外网** | 冒烟模式跳过启动自动检查；`verify:e2e` / `verify:desktop` / `verify:web` 的断言都只验"结构完整 + 能降级"，**不断言"一定有新版本"**（那会把用例绑死在外网可达上） |
|
||||
|
||||
只提示、不自动下载、不自动安装 —— 安装包仍由人从 Release 页取（`SHA256SUMS-<版本>.txt` 可核对）。
|
||||
|
||||
## 5. 技术参考
|
||||
|
||||
### 5.1 目录结构
|
||||
@@ -779,11 +834,18 @@ class-helper/
|
||||
│ ├── nsis/server-installer.nsi# 安装程序脚本模板（版本号由 dist-server 注入）
|
||||
│ └── ui-smoke/ # Web 管理端 UI 真实点击回归（Electron 驱动 + 上课时段探针）
|
||||
├── deploy/ # 生产部署：Dockerfile / docker-compose{,.sqlite}.yml / nginx.conf
|
||||
│ ├── install-linux.sh # Linux 一键部署（systemd + SQLite，含 .env 生成与就绪探针）
|
||||
│ ├── classhelper.service # systemd 单元模板（脚本会替换 __NODE__/__DIR__/__USER__）
|
||||
│ ├── install.sh # Linux 一键安装器（TUI；native/docker 双形态；自带 --check 体检）
|
||||
│ ├── install-linux.sh # 兼容壳：转发到 install.sh（旧命令仍可用）
|
||||
│ ├── classhelper # 运维命令本体（装到 <安装目录>/bin，软链 /usr/local/bin/classhelper）
|
||||
│ ├── verify-linux.sh # Linux 安装/改密/备份/升级/回滚验收（自统计 N/N 项）
|
||||
│ ├── tools/admin-cli.mjs # 离线账号工具（改密、列账号、SQLite 一致性快照）
|
||||
│ ├── profile.d/ logrotate.d/ systemd/ # /etc 下的环境变量、日志轮转、定时备份模板
|
||||
│ ├── Dockerfile.linux-package # 安装包内那份 Dockerfile（--mode docker 用它构建镜像）
|
||||
│ ├── classhelper.service # systemd 单元模板（替换 __NODE__/__DIR__/__USER__/__CONFIG__）
|
||||
│ ├── package.runtime.json # 运行时依赖清单（安装包 / 容器 / Linux 部署共用）
|
||||
│ └── .env.example / .env.sqlite.example
|
||||
├── docs/
|
||||
│ ├── linux-deploy.md # Linux 部署与运维指南（安装/命令/升级回滚/备份/验收/安全清单）
|
||||
│ ├── production.md # 生产部署指南（四种形态 + Linux systemd + 运维 + 安全清单）
|
||||
│ ├── mysql.md # MySQL 切换指南
|
||||
│ ├── winisland-design-tokens.md # 灵动岛照 WinIsland 提取的设计 token
|
||||
@@ -807,12 +869,13 @@ class-helper/
|
||||
│ ├── config/env.ts # 环境变量校验（zod）+ 生产配置自检
|
||||
│ ├── lib/ # access(RBAC) / class-account / session / db / db-bootstrap /
|
||||
│ │ # snapshot(全库 JSON 快照) / web-static / http / jwt / logger /
|
||||
│ │ # mappers / password / schemas / term
|
||||
│ │ # mappers / password / schemas / term / version(读 package.json)
|
||||
│ ├── tools/apply-snapshot.ts # 跨库迁移的子进程入口（编译到 dist/tools/）
|
||||
│ ├── middleware/ # auth / error / validate / security(helmet+限流+耗时日志)
|
||||
│ ├── realtime/ # socket.ts + bus.ts（事件总线）
|
||||
│ └── modules/ # 14 个功能模块 + registry.ts（模块注册表）
|
||||
│ └── database/ # 数据库管理（状态/备份/导入导出/定时/一键切换，仅管理员）
|
||||
│ └── modules/ # 15 个功能模块 + registry.ts（模块注册表）
|
||||
│ ├── database/ # 数据库管理（状态/备份/导入导出/定时/一键切换，仅管理员）
|
||||
│ └── update/ # 更新检查（查 GitHub 最新 Release，服务端唯一出网请求）
|
||||
├── classisland-plugin/ # ClassIsland 联动插件（.NET 8 / C#，独立于 pnpm workspace）
|
||||
│ ├── manifest.yml # 清单（id / version / apiVersion / entranceAssembly）
|
||||
│ ├── src/Plugin.cs # 入口（读配置 → 注册提醒提供方 / 设置页 / 联动服务）
|
||||
@@ -852,7 +915,7 @@ class-helper/
|
||||
| 实时 | Socket.IO | 4.8 |
|
||||
| 认证 | jsonwebtoken + bcryptjs | 9.0 / 3.0 |
|
||||
| 校验 | zod | 4.6 |
|
||||
| Web 端 | Vue + Vite + Element Plus + Pinia + Vue Router + Axios + ECharts | 3.5 / 8.3 / 2.14 / 4.0 / 5.3 / 1.20 / 6.1 |
|
||||
| Web 端 | Vue + Vite + Element Plus + Pinia + Vue Router + Axios | 3.5 / 8.3 / 2.14 / 4.0 / 5.3 / 1.20 |
|
||||
| 客户端 | Electron + Vue + Element Plus + Pinia + Socket.IO Client + IndexedDB | 44.3 / 3.5 / 2.14 / 4.0 / 4.8 |
|
||||
| 插件 | .NET 8 / C# + Avalonia（ClassIsland 插件 API 2.0） | net8.0（本机 SDK 8.0.425） |
|
||||
| 打包 | electron-builder（nsis / portable）+ NSIS | 26.15 |
|
||||
@@ -933,6 +996,7 @@ class-helper/
|
||||
| GET | `/integrations/classisland/pending` | **设备令牌** | 插件拉取尚未确认的提醒（离线期间老师发的通知，重连后补齐） |
|
||||
| POST | `/integrations/classisland/ack` | **设备令牌** | 插件确认提醒已弹出（确认后不再补发） |
|
||||
| GET | `/integrations/classisland/class-plan` | **设备令牌** | 插件拉取本班课表（开启镜像时）用于写回 ClassIsland |
|
||||
| GET | `/update/check` | 登录 | 更新检查（服务端代查 GitHub 最新 Release；`?force=1` 绕过缓存仅管理员生效） |
|
||||
| GET | `/health` | 公开 | 健康检查（含版本号与已挂载模块）；另有 `/healthz` 存活与 `/readyz` 就绪探针 |
|
||||
|
||||
### 5.4 WebSocket 事件
|
||||
@@ -1004,7 +1068,7 @@ class-helper/
|
||||
后端每个功能是一个独立目录，统一契约 `ApiModule = { name, basePath, router, enabled? }`：
|
||||
|
||||
```ts
|
||||
// packages/server/src/modules/registry.ts（当前 14 个模块）
|
||||
// packages/server/src/modules/registry.ts（当前 15 个模块）
|
||||
export const apiModules: ApiModule[] = [
|
||||
authModule,
|
||||
classesModule,
|
||||
@@ -1020,6 +1084,7 @@ export const apiModules: ApiModule[] = [
|
||||
teachersModule,
|
||||
dashboardModule,
|
||||
databaseModule, // ← 数据库管理（仅管理员）
|
||||
updateModule, // ← 更新检查（查 GitHub 最新 Release）
|
||||
].filter((module) => module.enabled !== false);
|
||||
```
|
||||
|
||||
@@ -1062,67 +1127,71 @@ pnpm db:generate && pnpm --filter @classhelper/server db:deploy && pnpm db:seed
|
||||
|
||||
### 6.1 验收标准对照
|
||||
|
||||
| 验收项 | 结果 | 证据 |
|
||||
| ------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 教师 Web 端发布通知，学生端 5 秒内收到 | ✅ | `verify:e2e`：`notification:new` 实测 30–50ms 到达（要求 < 5 秒） |
|
||||
| 教师发布作业，学生能查看并标记完成 | ✅ | `homework:new` 实时到达，`PATCH /homeworks/:id/status` 200 且列表回显 `completed=true` |
|
||||
| 教师录入成绩，学生能查看个人成绩 | ✅ | `grade:updated` 实时到达，`/grades/my` 返回记录；批量录入与统计接口通过 |
|
||||
| 学生能查看课表，支持按周切换 | ✅ | `/schedules/grid?week=1` 返回周视图条目，`week` 过滤 `weekStart ≤ week ≤ weekEnd`，单双周按第 1 周 = 单周过滤 |
|
||||
| 断网后客户端可查看缓存数据 | ✅ | 客户端冒烟：`断网时回退到本地缓存 → fromCache=true`；离线横幅 + 缓存统计页可用 |
|
||||
| 权限隔离：学生不能访问其他班级数据 | ✅ | e2e 中 10 余项越权断言全部 403/401（学生跨班 / 跨班作业 / 跨班课表、教师跨班发布、未登录访问…） |
|
||||
| 上课时段发布紧急通知必须二次确认 | ✅ | 服务端 409 `URGENT_DURING_CLASS`（`confirmDuringClass` 后 201）；Web 端全屏警告 + 3 秒倒计时 |
|
||||
| 客户端灵动岛：上课隐藏 / 下课弹出 / 紧急立即展开 | ✅ | `verify:desktop` 状态断言 + 像素级截图（`docs/screenshots/island/`） |
|
||||
| 灵动岛：收回无「方框」闪烁 / 点击任意处收回 | ✅ | 逐帧采样卡片尺寸恒定（窗口固定包围盒）+ 失焦自动收回 |
|
||||
| 灵动岛「标为已读」同步通知中心 | ✅ | 真实链路：点击后 `read=false → true`、未读数减少 |
|
||||
| **多条通知展开为竖排列表** | ✅ | `verify:desktop`：按重要程度排序、默认 3 行 + `展开更多（还有 N 条）`、卡片高度与 `islandListLayout()` 一致；放不下时提示 `更多请前往应用内操作` |
|
||||
| **多条通知的整批操作** | ✅ | `verify:desktop`：`知道了` 整批关闭且状态同步清空、窗口随后淡出隐藏；`标为已读` 经真实链路把两条通知都标为已读 |
|
||||
| **本机录入的作业不再上岛** | ✅ | `verify:desktop`：按 id 与内容指纹双重判定，投递后灵动岛状态不变；别的作业照常上岛 |
|
||||
| 作业发布也上岛（「新作业」胶囊） | ✅ | `kind=homework` + 展开显示作业要求；**截止时间功能已下线**（接口不再返回 `dueAt`，e2e 有断言） |
|
||||
| **灵动岛收起后始终可再次打开** | ✅ | `verify:desktop`：收起后胶囊常驻、「收起态点击可再次展开」、「空闲细缝态保持可交互」 |
|
||||
| **触摸屏触摸灵动岛可展开（希沃白板）** | ⏳ | 触摸模式下窗口贴合岛体 + 始终接收输入；`verify:desktop` 断言「窗口 = 岛体 + 2×阴影留白、`interactive=true`、退出后恢复固定包围盒」。**真机（触摸屏）需人工复验** |
|
||||
| 叫人（老师点名，分紧急 / 普通两级） | ✅ | `verify:e2e` 8 项（普通 HIGH / 紧急 URGENT）+ `verify:desktop`「紧急叫人上课也立即展开」「普通叫人上课只进队列、下课弹出」 |
|
||||
| 成绩 / 名单表格导入（xlsx·xls·csv） | ✅ | 模板下载 + 预览映射 + 重复处理 + 行号级错误：`verify:e2e` 覆盖 20 余项，`verify:web` 弹窗实测 |
|
||||
| ClassIsland 时间配置导入（覆盖 / 合并 / 回滚） | ✅ | 合法 200、非法 400 `IMPORT_INVALID` 且原配置仍在、merge 覆盖与保留行为符合预期 |
|
||||
| 安装版覆盖升级自动补迁移 | ✅ | 真实旧库升级日志：`升级安装：已应用 N 个迁移文件，跳过 M 个已存在对象`，新表自动建好 |
|
||||
| 学生端主体 = 班级（班级码 + 班级密码登录） | ✅ | `verify:e2e` 班级账号 19 项：登录 / 错误密码 401 / 跨班 403 / 发布 403 / 班级码重复 400 / 密码重置 / 班级码用后还原 |
|
||||
| 班级设备代全班操作（已读 · 完成 · 成绩总览） | ✅ | 标记已读写入全班、教师端 `readCount` = 班级学生数、`completedCount` 一致、`/grades/my` 返回全班成绩 |
|
||||
| 客户端只保留班级登录入口 | ✅ | `verify:desktop`：导航「成绩」标题变为「本班成绩」；个人学生登录 403 |
|
||||
| **教师录入（仅管理员）** | ✅ | `verify:e2e`：教师读 / 建教师 403、管理员建 201 → 编辑 → 重置密码（新密码 200 / 旧密码 401）→ 删除（有职责 409 / 无职责 200）；`verify:web`：管理员真人点「教师管理 → 新建教师 → 保存 → 列表出现 → 删除」 |
|
||||
| **教师名单表格导入（仅管理员）** | ✅ | `verify:e2e`：教师预览 403、管理员预览 / 提交 200（`inserted=1`）、导入账号可登录；模板列＝用户名 / 姓名 / 初始密码 / 角色 |
|
||||
| **教师修改密码（管理员）** | ✅ | 服务端 `POST /teachers/:id/reset-password` 收可选 `newPassword`，界面「修改密码」填了就设成填的值、留空才是默认初始密码（`123456`）。**学生没有账号，`POST /students/:id/reset-password` 已下线（404，e2e 有负断言）** |
|
||||
| **客户端不提供改密入口（有意为之）** | ✅ | 按用户要求移除：防教室机器误改班级密码把其他机器锁在门外。`verify:desktop` 断言账号页「修改密码」按钮不存在、只有「退出登录」；班级密码由管理员在 Web 端维护 |
|
||||
| **创建班级仅管理员 + 设置 / 更改班主任** | ✅ | `verify:e2e`：教师建班 403；管理员建班可带 `teacherId`、`PATCH /classes/:id/head-teacher` 落库生效；`verify:web`：教师直接访问 `/teachers` 被挡回仪表盘 |
|
||||
| **授课科目统一（18 科固定目录）** | ✅ | `verify:web`：新增课表的科目下拉出现「统一科目（选中后自动建课）」，选中 → 自动建课 → 写入课表成功（收尾删除该条课表） |
|
||||
| **登录页无示例内容** | ✅ | `verify:web`（管理端）与 `verify:desktop`（客户端）都断言登录页正文 / 占位符不含 `演示 / 示例 / admin123 / teacher123 / G101` |
|
||||
| **新手引导（首启弹出 + 随时重看）** | ✅ | Web 管理端：首次登录弹出 `el-tour` 聚焦引导，头像菜单「使用引导」重看（`verify:web`）；客户端：首启六步向导，登录页 / 设置页可重看（`verify:desktop`） |
|
||||
| **客户端设置改版（分组侧栏 / 深色模式 / 关于页）** | ✅ | `verify:desktop`：「侧边栏点击导航」适配「学习 / 设置」分组；「主题切换与侧边栏折叠（真实点击、写回配置）」——`html.dark` 翻转 + 折叠宽度 200→64 + 双双落盘；「关于页渲染」含 configPath |
|
||||
| **数据库管理（仅管理员：状态 / 备份 / 导入导出 / 一键切换）** | ✅ | `verify:e2e` 13 项：状态与 14 表行数、教师全端点 403、连接测试（当前库可达 / 不可达 MySQL ok=false）、**Redis 主库 422**、切换校验分支（同库 400）、备份 → 快照导入 → 备份恢复 roundtrip（临时数据被清除）、定时配置校验、SQLite 文件下载；**切换子进程链路真机实测**：快照 728 行 → generate → db push → apply-snapshot 逐表一致；`verify:web`：数据库管理页（仅管理员）状态卡与备份表渲染 |
|
||||
| **其他页面发通知也会联动 ClassIsland** | ✅ | `verify:classisland`：「通知发布页发的通知也会推送」「叫人也会推送」；真机实测截图 [03-from-notify-page](docs/screenshots/classisland/03-from-notify-page.png) |
|
||||
| **作业按天查看（日期选择器 + 有作业日期高亮）** | ✅ | `verify:e2e`：`assignDate` 默认服务器当天、`?date=` 只返回该天、`/homeworks/days` 返回有作业日期、非法日期 422 |
|
||||
| **支持在客户端录入作业（含自定义快捷短语）** | ✅ | `verify:e2e`：班级账号录入 201（归属班主任）、跨班 403；客户端录入弹窗 + 「设置 → 通用」管理短语 |
|
||||
| **提醒弹在哪个端由客户端自行选择** | ✅ | 客户端「设置 → 提醒」三选一（`verify:desktop`：设置页真实点击 → 写回本地配置）；服务端按班级设置决定是否推送（`verify:classisland`：`client` 时通知与联动页下发都被跳过） |
|
||||
| **班级小助手能读取 ClassIsland 的课表** | ✅ | `verify:classisland`：插件上报课表 → 本班课表新增 / 更新（重复上报幂等）、节次时间写入、设备状态快照可在 Web 端展示；`verify:web`：教师在「ClassIsland 联动」页真实签发设备令牌 |
|
||||
| **用户可选择通知是否在 ClassIsland 上显示** | ✅ | 插件设置页开关「接收班级小助手提醒」（本机总闸）+ Web 端「下发提醒」（标题 / 内容 / 时长 / 优先级 / 语音朗读 / 是否同步通知中心）；`verify:classisland`：提醒落库 → 待提醒 → 回执 → 确认后不补发 |
|
||||
| 能成功打包 Windows EXE | ✅ | `-x64-setup.exe` / `-x64-portable.exe` / `win-unpacked/*.exe`（见 [7. 打包与交付](#7-打包与交付)） |
|
||||
| 提供完整 README（启动、构建、打包、默认账号） | ✅ | 本文档含快速开始、命令表、API、WebSocket、RBAC、模块化、数据库、打包与常见问题 |
|
||||
| 验收项 | 结果 | 证据 |
|
||||
| ------------------------------------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 教师 Web 端发布通知，学生端 5 秒内收到 | ✅ | `verify:e2e`：`notification:new` 实测 30–50ms 到达（要求 < 5 秒） |
|
||||
| 教师发布作业，学生能查看并标记完成 | ✅ | `homework:new` 实时到达，`PATCH /homeworks/:id/status` 200 且列表回显 `completed=true` |
|
||||
| 教师录入成绩，学生能查看个人成绩 | ✅ | `grade:updated` 实时到达，`/grades/my` 返回记录；批量录入与统计接口通过 |
|
||||
| 学生能查看课表，支持按周切换 | ✅ | `/schedules/grid?week=1` 返回周视图条目，`week` 过滤 `weekStart ≤ week ≤ weekEnd`，单双周按第 1 周 = 单周过滤 |
|
||||
| 断网后客户端可查看缓存数据 | ✅ | 客户端冒烟：`断网时回退到本地缓存 → fromCache=true`；离线横幅 + 缓存统计页可用 |
|
||||
| 权限隔离：学生不能访问其他班级数据 | ✅ | e2e 中 10 余项越权断言全部 403/401（学生跨班 / 跨班作业 / 跨班课表、教师跨班发布、未登录访问…） |
|
||||
| 上课时段发布紧急通知必须二次确认 | ✅ | 服务端 409 `URGENT_DURING_CLASS`（`confirmDuringClass` 后 201）；Web 端全屏警告 + 3 秒倒计时 |
|
||||
| 客户端灵动岛：上课隐藏 / 下课弹出 / 紧急立即展开 | ✅ | `verify:desktop` 状态断言 + 像素级截图（`docs/screenshots/island/`） |
|
||||
| 灵动岛：收回无「方框」闪烁 / 点击任意处收回 | ✅ | 逐帧采样卡片尺寸恒定（窗口固定包围盒）+ 失焦自动收回 |
|
||||
| 灵动岛「标为已读」同步通知中心 | ✅ | 真实链路：点击后 `read=false → true`、未读数减少 |
|
||||
| **多条通知展开为竖排列表** | ✅ | `verify:desktop`：按重要程度排序、默认 3 行 + `展开更多（还有 N 条）`、卡片高度与 `islandListLayout()` 一致；放不下时提示 `更多请前往应用内操作` |
|
||||
| **多条通知的整批操作** | ✅ | `verify:desktop`：`知道了` 整批关闭且状态同步清空、窗口随后淡出隐藏；`标为已读` 经真实链路把两条通知都标为已读 |
|
||||
| **本机录入的作业不再上岛** | ✅ | `verify:desktop`：按 id 与内容指纹双重判定，投递后灵动岛状态不变；别的作业照常上岛 |
|
||||
| 作业发布也上岛（「新作业」胶囊） | ✅ | `kind=homework` + 展开显示作业要求；**截止时间功能已下线**（接口不再返回 `dueAt`，e2e 有断言） |
|
||||
| **灵动岛收起后始终可再次打开** | ✅ | `verify:desktop`：收起后胶囊常驻、「收起态点击可再次展开」、「空闲细缝态保持可交互」 |
|
||||
| **触摸屏触摸灵动岛可展开（希沃白板）** | ⏳ | 触摸模式下窗口贴合岛体 + 始终接收输入；`verify:desktop` 断言「窗口 = 岛体 + 2×阴影留白、`interactive=true`、退出后恢复固定包围盒」。**真机（触摸屏）需人工复验** |
|
||||
| 叫人（老师点名，分紧急 / 普通两级） | ✅ | `verify:e2e` 8 项（普通 HIGH / 紧急 URGENT）+ `verify:desktop`「紧急叫人上课也立即展开」「普通叫人上课只进队列、下课弹出」 |
|
||||
| 成绩 / 名单表格导入（xlsx·xls·csv） | ✅ | 模板下载 + 预览映射 + 重复处理 + 行号级错误：`verify:e2e` 覆盖 20 余项，`verify:web` 弹窗实测 |
|
||||
| ClassIsland 时间配置导入（覆盖 / 合并 / 回滚） | ✅ | 合法 200、非法 400 `IMPORT_INVALID` 且原配置仍在、merge 覆盖与保留行为符合预期 |
|
||||
| 安装版覆盖升级自动补迁移 | ✅ | 真实旧库升级日志：`升级安装：已应用 N 个迁移文件，跳过 M 个已存在对象`，新表自动建好 |
|
||||
| 学生端主体 = 班级（班级码 + 班级密码登录） | ✅ | `verify:e2e` 班级账号 19 项：登录 / 错误密码 401 / 跨班 403 / 发布 403 / 班级码重复 400 / 密码重置 / 班级码用后还原 |
|
||||
| 班级设备代全班操作（已读 · 完成 · 成绩总览） | ✅ | 标记已读写入全班、教师端 `readCount` = 班级学生数、`completedCount` 一致、`/grades/my` 返回全班成绩 |
|
||||
| 客户端只保留班级登录入口 | ✅ | `verify:desktop`：导航「成绩」标题变为「本班成绩」；个人学生登录 403 |
|
||||
| **教师录入（仅管理员）** | ✅ | `verify:e2e`：教师读 / 建教师 403、管理员建 201 → 编辑 → 重置密码（新密码 200 / 旧密码 401）→ 删除（有职责 409 / 无职责 200）；`verify:web`：管理员真人点「教师管理 → 新建教师 → 保存 → 列表出现 → 删除」 |
|
||||
| **教师名单表格导入（仅管理员）** | ✅ | `verify:e2e`：教师预览 403、管理员预览 / 提交 200（`inserted=1`）、导入账号可登录；模板列＝用户名 / 姓名 / 初始密码 / 角色 |
|
||||
| **教师修改密码（管理员）** | ✅ | 服务端 `POST /teachers/:id/reset-password` 收可选 `newPassword`，界面「修改密码」填了就设成填的值、留空才是默认初始密码（`123456`）。**学生没有账号，`POST /students/:id/reset-password` 已下线（404，e2e 有负断言）** |
|
||||
| **客户端不提供改密入口（有意为之）** | ✅ | 按用户要求移除：防教室机器误改班级密码把其他机器锁在门外。`verify:desktop` 断言账号页「修改密码」按钮不存在、只有「退出登录」；班级密码由管理员在 Web 端维护 |
|
||||
| **创建班级仅管理员 + 设置 / 更改班主任** | ✅ | `verify:e2e`：教师建班 403；管理员建班可带 `teacherId`、`PATCH /classes/:id/head-teacher` 落库生效；`verify:web`：教师直接访问 `/teachers` 被挡回仪表盘 |
|
||||
| **授课科目统一（18 科固定目录）** | ✅ | `verify:web`：新增课表的科目下拉出现「统一科目（选中后自动建课）」，选中 → 自动建课 → 写入课表成功（收尾删除该条课表） |
|
||||
| **登录页无示例内容** | ✅ | `verify:web`（管理端）与 `verify:desktop`（客户端）都断言登录页正文 / 占位符不含 `演示 / 示例 / admin123 / teacher123 / G101` |
|
||||
| **新手引导（首启弹出 + 随时重看）** | ✅ | Web 管理端：首次登录弹出 `el-tour` 聚焦引导，头像菜单「使用引导」重看（`verify:web`）；客户端：首启六步向导，登录页 / 设置页可重看（`verify:desktop`） |
|
||||
| **客户端设置改版（分组侧栏 / 深色模式 / 关于页）** | ✅ | `verify:desktop`：「侧边栏点击导航」适配「学习 / 设置」分组；「主题切换与侧边栏折叠（真实点击、写回配置）」——`html.dark` 翻转 + 折叠宽度 200→64 + 双双落盘；「关于页渲染」含 configPath |
|
||||
| **数据库管理（仅管理员：状态 / 备份 / 导入导出 / 一键切换）** | ✅ | `verify:e2e` 13 项：状态与 14 表行数、教师全端点 403、连接测试（当前库可达 / 不可达 MySQL ok=false）、**Redis 主库 422**、切换校验分支（同库 400）、备份 → 快照导入 → 备份恢复 roundtrip（临时数据被清除）、定时配置校验、SQLite 文件下载；**切换子进程链路真机实测**：快照 728 行 → generate → db push → apply-snapshot 逐表一致；`verify:web`：数据库管理页（仅管理员）状态卡与备份表渲染 |
|
||||
| **更新检查（服务端 / Web 端 / 客户端）** | ✅ | `verify:e2e` 4 项：未登录 401、管理员结构完整且本机版本取自 package.json、教师可查但 `force` 仅管理员生效、健康检查暴露版本号与 15 个模块；`verify:desktop` 4 项：IPC 返回结构正确（无外网时降级 `ok=false` 且带原因）、结果带缓存、冒烟模式跳过启动自动检查、关于页出现「检查更新」；`verify:web`：「顶栏用户菜单 → 弹窗给出结论并可关闭」。**真机联网实测**：`GET /api/update/check` → `ok=true`、`latestVersion=1.0.0`、5 个附件、更新说明 1358 字 |
|
||||
| **其他页面发通知也会联动 ClassIsland** | ✅ | `verify:classisland`：「通知发布页发的通知也会推送」「叫人也会推送」；真机实测截图 [03-from-notify-page](docs/screenshots/classisland/03-from-notify-page.png) |
|
||||
| **作业按天查看（日期选择器 + 有作业日期高亮）** | ✅ | `verify:e2e`：`assignDate` 默认服务器当天、`?date=` 只返回该天、`/homeworks/days` 返回有作业日期、非法日期 422 |
|
||||
| **支持在客户端录入作业（含自定义快捷短语）** | ✅ | `verify:e2e`：班级账号录入 201（归属班主任）、跨班 403；客户端录入弹窗 + 「设置 → 通用」管理短语 |
|
||||
| **提醒弹在哪个端由客户端自行选择** | ✅ | 客户端「设置 → 提醒」三选一（`verify:desktop`：设置页真实点击 → 写回本地配置）；服务端按班级设置决定是否推送（`verify:classisland`：`client` 时通知与联动页下发都被跳过） |
|
||||
| **班级小助手能读取 ClassIsland 的课表** | ✅ | `verify:classisland`：插件上报课表 → 本班课表新增 / 更新（重复上报幂等）、节次时间写入、设备状态快照可在 Web 端展示；`verify:web`：教师在「ClassIsland 联动」页真实签发设备令牌 |
|
||||
| **用户可选择通知是否在 ClassIsland 上显示** | ✅ | 插件设置页开关「接收班级小助手提醒」（本机总闸）+ Web 端「下发提醒」（标题 / 内容 / 时长 / 优先级 / 语音朗读 / 是否同步通知中心）；`verify:classisland`：提醒落库 → 待提醒 → 回执 → 确认后不补发 |
|
||||
| 能成功打包 Windows EXE | ✅ | `-x64-setup.exe` / `-x64-portable.exe` / `win-unpacked/*.exe`（见 [7. 打包与交付](#7-打包与交付)） |
|
||||
| 提供完整 README（启动、构建、打包、默认账号） | ✅ | 本文档含快速开始、命令表、API、WebSocket、RBAC、模块化、数据库、打包与常见问题 |
|
||||
|
||||
### 6.2 最近一次实测
|
||||
|
||||
| 验证 | 结果 |
|
||||
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
||||
| `pnpm verify:e2e`（后端 + 实时 + RBAC + 上课时段 + 导入 + 班级账号 + 数据库管理） | **186/186** ✅（2026-10-02 实测） |
|
||||
| `pnpm verify:desktop`（客户端冒烟，不弹窗） | **99/102**（2026-10-02 实测；3 项为上课时段下的时序相关用例，见下） |
|
||||
| `pnpm verify:web`（Web 管理端真实点击回归） | **30/31**（2026-10-02 实测；未过的 1 项是既有脆弱用例「课表科目为全校统一目录」，见下） |
|
||||
| `pnpm verify:classisland`（设备令牌 / 上报 / 提醒下发与回执 / 镜像契约） | **42/42** ✅ |
|
||||
| `pnpm verify:classisland-plugin`（插件静态契约） | **68/68** ✅ |
|
||||
| `pnpm typecheck` / `pnpm lint` | 全过 ✅（lint 0 error，1 条既有 warning） |
|
||||
| `pnpm build:desktop`（含产物凭据门禁 `check-bundle-secrets`） | 通过 ✅（60 个产物文件里无种子凭据字面量） |
|
||||
| 插件 `dotnet` 编译（`pnpm build:classisland-plugin`） | 0 错误 ✅（1 条预期内的 Avalonia `AVLN3001` 警告） |
|
||||
| 数据库切换子进程链路（快照 → generate → db push → 写入目标库） | ✅ 实测：728 行逐表一致（users / schedules / grades 抽查一致） |
|
||||
| `pnpm dist:server`（服务端安装包 + Web 端） | ✅ 打出 ~71MB 安装程序（体积增大是因随包内置切换链路所需的 prisma CLI 与 tsc） |
|
||||
| 安装程序完整生命周期（静默安装 → 启动 → 卸载） | 通过 ✅（安装到 `%LOCALAPPDATA%\Programs`，卸载干净） |
|
||||
| 便捷版（单文件）解包启动 | 通过 ✅（wrapper + 多个进程，主窗口正常） |
|
||||
| Docker / Nginx 部署样例 | 文件已提供（含 Linux systemd 脚本），本机无 Docker / Linux 未实测 ⚠️ |
|
||||
| 验证 | 结果 |
|
||||
| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
||||
| `pnpm verify:e2e`（后端 + 实时 + RBAC + 上课时段 + 导入 + 班级账号 + 数据库管理 + 更新检查） | **190/190** ✅（2026-10-05 实测） |
|
||||
| `pnpm verify:desktop`（客户端冒烟，不弹窗） | **105/105** ✅（在线轮）+ **89/89** ✅（二次启动轮），0 失败（2026-10-05 实测） |
|
||||
| `pnpm verify:web`（Web 管理端真实点击回归） | **32/33**（2026-10-05 实测；未过的 1 项是既有脆弱用例「课表科目为全校统一目录」，见下） |
|
||||
| `pnpm verify:classisland`（设备令牌 / 上报 / 提醒下发与回执 / 镜像契约） | **42/42** ✅（2026-10-05 实测） |
|
||||
| `pnpm verify:classisland-plugin`（插件静态契约） | **68/68** ✅ |
|
||||
| `pnpm typecheck` / `pnpm lint` / `pnpm check:icons` | 全过 ✅（lint 0 error **0 warning**） |
|
||||
| `pnpm build:desktop`（含产物凭据门禁 `check-bundle-secrets`） | 通过 ✅（61 个产物文件里无种子凭据字面量） |
|
||||
| `pnpm verify:packaged --exe …`（对打包副本复验） | **105/105** ✅ + **89/89** ✅（2026-10-05 实测，0 失败） |
|
||||
| 裁剪后的服务端运行时（起服务 → 登录查表 → `prisma generate` → `tsc` → `db push`） | 通过 ✅（2026-10-05 实测，建出 14 张表；详见 AGENTS.md §8） |
|
||||
| 插件 `dotnet` 编译（`pnpm build:classisland-plugin`） | 0 错误 ✅（1 条预期内的 Avalonia `AVLN3001` 警告） |
|
||||
| 数据库切换子进程链路（快照 → generate → db push → 写入目标库） | ✅ 实测：728 行逐表一致（users / schedules / grades 抽查一致） |
|
||||
| `pnpm dist:server`（服务端安装包 + Web 端） | ✅ 打出 ~62MB 安装程序（随包内置切换链路所需的 prisma CLI 与 tsc，并在打包末尾做运行时裁剪） |
|
||||
| 安装程序完整生命周期（静默安装 → 启动 → 卸载） | 通过 ✅（安装到 `%LOCALAPPDATA%\Programs`，卸载干净） |
|
||||
| 便捷版（单文件）解包启动 | 通过 ✅（wrapper + 多个进程，主窗口正常） |
|
||||
| Docker / Nginx 部署样例 | 文件已提供；本机无 Docker 未实测 ⚠️ |
|
||||
| Linux 一键安装 + `classhelper` 运维命令（`deploy/install.sh` / `deploy/classhelper` / `pnpm dist:server:linux`） | 脚本与文档已交付，本地静态检查通过（`bash -n`、ESLint 0 error）；**Linux 实机验收待做** ⚠️（清单见 [linux-deploy.md](docs/linux-deploy.md) §10，`deploy/verify-linux.sh` 可自动跑） |
|
||||
|
||||
### 6.3 已知的时序 / 环境相关用例
|
||||
|
||||
@@ -1148,22 +1217,43 @@ pnpm db:generate && pnpm --filter @classhelper/server db:deploy && pnpm db:seed
|
||||
|
||||
## 7. 打包与交付
|
||||
|
||||
### 体积与性能（2026-10-05 优化后实测）
|
||||
|
||||
| 产物 / 指标 | 优化前 | 优化后 | 做了什么 |
|
||||
| ----------------------------------- | -------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 客户端渲染产物 `dist/renderer` | 3.2MB | **2.1MB** | 成绩页图表从 echarts 全量（1.12MB，占 35%）换成内置 HTML/SVG 组件；Element Plus 图标从全量注册 293 个改为按需 42/33 个 |
|
||||
| 客户端主进程产物体积 | 242KB | 242KB | 未变（冒烟代码拆分会重复 `island`/`config` 单例，esbuild 的 CJS 打包无法代码分割，故保留） |
|
||||
| 客户端 `win-unpacked` | 372MB | **323MB** | `electronLanguages: [zh-CN]`，只留中文语言包（其余 54 个 `locales/*.pak` 共 48MB） |
|
||||
| 客户端 `setup.exe` / `portable.exe` | 107MB | **98MB** | 同上。**安装包有硬底**：`班级小助手.exe`（electron.exe）压缩后本身就有 85~90MB，60MB 不可达 |
|
||||
| 服务端 `dist` | 3.8MB | **0.6MB** | `tsconfig.build.json` 关掉 `declaration`/`declarationMap`/`sourceMap`（占原体积 82%） |
|
||||
| 服务端免安装目录 | 436MB | **335MB** | 打包末尾的运行时裁剪：删掉 Prisma 为 postgresql/cockroachdb/sqlserver 准备的查询编译器副本、`*.map`、文档与测试夹具（共 2329 项 / 101MB） |
|
||||
| 服务端安装程序 | 71MB | **62MB** | 同上 |
|
||||
| Web 端前端产物 | 3.3MB | **2.1MB** | 同样是 echarts → 内置 SVG/CSS 图表 + 图标按需 |
|
||||
| 灵动岛主进程常驻开销 | 每 60ms 2 次系统调用 | 每 60ms 1 次 | 光标位置每跳只读一次（命中判定与"跟随鼠标屏幕"共用）；窗口不可见时整跳 |
|
||||
|
||||
> 没有做的事，以及为什么：Element Plus 仍全量引入（按需引入要改所有视图的样式引入方式与 locale 配置，
|
||||
> 收益约 200 到 350KB JS，风险不成比例）；服务端静态资源不做预压缩；客户端不再删 GPU 回退组件
|
||||
> （dxcompiler / swiftshader / d3dcompiler，共约 37MB 未压缩，教室老显卡与虚拟机靠它们）。
|
||||
> 详见 [AGENTS.md](AGENTS.md) 的 §5 第 53 至 56 条与 §7 第 23 条。
|
||||
|
||||
### 客户端（Windows EXE）
|
||||
|
||||
```bash
|
||||
pnpm dist:dir # 免安装目录：packages/desktop-client/release/win-unpacked/班级小助手.exe
|
||||
pnpm dist:dir # 免安装目录：releases/client/<版本>/免安装/班级小助手.exe
|
||||
pnpm dist:win # nsis 安装包 + portable 单文件（需联网下载 NSIS 工具，可用镜像）
|
||||
```
|
||||
|
||||
打包脚本 `packages/desktop-client/scripts/dist-win.mjs` 做了几件事以规避常见问题：复用本地已解压的 Electron
|
||||
（`--config.electronDist`，不重复下载 150MB+）；默认走国内镜像（`ELECTRON_MIRROR`、
|
||||
`ELECTRON_BUILDER_BINARIES_MIRROR`，可用环境变量覆盖）；构建缓存固定到仓库内 `.cache/`；
|
||||
用 `--config.directories.output` 把输出目录覆盖成 `releases/client/<版本>/`，打包成功后再把
|
||||
electron-builder 的原始布局整理成 `安装包/`、`免安装/`、`构建中间/`；
|
||||
收尾把交付物完整性标签改成 Medium（Low 标签会导致装不上 / 双击没反应，见 [8. 常见问题](#8-常见问题)）。
|
||||
|
||||
产物结构：`release/win-unpacked/班级小助手.exe`（Electron 运行时）+ `resources/app.asar`
|
||||
产物结构：`免安装/班级小助手.exe`（Electron 运行时）+ `resources/app.asar`
|
||||
（仅含 `dist/` 与 `package.json`，运行时不需要 node_modules）。
|
||||
|
||||
> **把修复交付到「已安装的客户端」**：`pnpm dist:win` 只产出 `packages/desktop-client/release/`。
|
||||
> **把修复交付到「已安装的客户端」**：`pnpm dist:win` 只产出 `releases/client/<版本>/`。
|
||||
> 若学生机上是**安装版**（例如装在 `D:\class\@classhelperdesktop-client`），只更新 release 而不同步安装目录，
|
||||
> 用户打开的还是旧 `resources/app.asar`，会出现「改了但界面不生效」。覆盖升级（用户配置在 `%APPDATA%`，不受影响）：
|
||||
>
|
||||
@@ -1179,17 +1269,17 @@ pnpm dist:win # nsis 安装包 + portable 单文件（需联网下载 NSIS
|
||||
|
||||
| 产物 | 大小 | 冒烟结果 |
|
||||
| -------------------------------------- | ------ | -------------------------------------------------------------------- |
|
||||
| 服务端安装程序（内置 Node + Web 端） | ~71MB | ✅ 静默安装（升级保留 `.env` 与数据库）→ 自动建库建号 → 服务就绪 |
|
||||
| `release/win-unpacked/班级小助手.exe` | ~235MB | ✅ 打包版冒烟全绿，`packaged: true`，退出码 0 |
|
||||
| `release/…-x64-portable.exe`（单文件） | ~107MB | ✅ 打包后冒烟全绿，`packaged: true`，退出码 0 |
|
||||
| `release/…-x64-setup.exe`（客户端） | ~107MB | ✅ 构建成功，已嵌入自定义图标 |
|
||||
| `releases/classisland-plugin/….cipx` | ~88KB | ✅ 全量编译通过（1 警告 0 错误），包内 DLL 哈希与 `bin/Release` 一致 |
|
||||
| 服务端安装程序（内置 Node + Web 端） | ~62MB | ✅ 静默安装（升级保留 `.env` 与数据库）→ 自动建库建号 → 服务就绪 |
|
||||
| `releases/client/<版本>/免安装/班级小助手.exe` | ~235MB | ✅ 打包版冒烟全绿，`packaged: true`，退出码 0 |
|
||||
| `releases/client/<版本>/安装包/…-portable.exe` | ~98MB | ✅ 打包后冒烟全绿，`packaged: true`，退出码 0 |
|
||||
| `releases/client/<版本>/安装包/…-setup.exe` | ~98MB | ✅ 构建成功，已嵌入自定义图标 |
|
||||
| `releases/classisland-plugin/<版本>/…cipx` | ~88KB | ✅ 全量编译通过（1 警告 0 错误），包内 DLL 哈希与 `bin/Release` 一致 |
|
||||
|
||||
### ClassIsland 插件
|
||||
|
||||
```bash
|
||||
pnpm build:classisland-plugin # 编译（.NET 8，缓存与临时目录自动指到仓库内 .cache/）
|
||||
pnpm dist:classisland-plugin # 打包 .cipx 并归集到 releases/classisland-plugin/
|
||||
pnpm dist:classisland-plugin # 打包 .cipx 并归集到 releases/classisland-plugin/<版本>/
|
||||
pnpm verify:classisland-plugin # 静态契约校验（不需要 .NET，不需要服务端）
|
||||
```
|
||||
|
||||
|
||||
+2
-2
@@ -7,7 +7,7 @@
|
||||
SERVER_PORT=4000
|
||||
|
||||
# 应用版本（镜像标签）
|
||||
APP_VERSION=1.0.0
|
||||
APP_VERSION=1.1.1
|
||||
|
||||
# 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.1
|
||||
|
||||
# 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
|
||||
|
||||
|
||||
+2
-2
@@ -5,13 +5,13 @@
|
||||
# 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
|
||||
@@ -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.1.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:
|
||||
|
||||
@@ -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.1.1}
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
NODE_ENV: production
|
||||
@@ -78,7 +78,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:
|
||||
|
||||
+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" "$@"
|
||||
+1293
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,19 @@
|
||||
# ---------------------------------------------------------------------------
|
||||
# 班级小助手 · 日志轮转
|
||||
# 由 deploy/install.sh 安装到 /etc/logrotate.d/classhelper
|
||||
#
|
||||
# copytruncate 而不是 create+信号：安装器与 classhelper 都是"追加写完就关"
|
||||
# （`>>` 打开、写完立即关闭），没有常驻 fd 可通知，copytruncate 是这里唯一正确的做法。
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
/var/log/classhelper/*.log {
|
||||
weekly
|
||||
rotate 8
|
||||
missingok
|
||||
notifempty
|
||||
compress
|
||||
delaycompress
|
||||
copytruncate
|
||||
create 0600 root root
|
||||
su root root
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "classhelper-server-runtime",
|
||||
"version": "1.0.0",
|
||||
"version": "1.1.1",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"description": "班级小助手服务端运行时（安装包 / 容器内置）",
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
# ---------------------------------------------------------------------------
|
||||
# 班级小助手 · 登录 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
|
||||
/**
|
||||
* 班级小助手 · 离线账号工具（随 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（学生端登录用的是班级码） */
|
||||
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} 只是名单记录），学生端用「班级码 + 班级密码」登录，请用 --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班级账号（学生端用「班级码 + 班级密码」登录）：\n');
|
||||
for (const item of classes) {
|
||||
const state = item.passwordHash ? '已设置' : '⚠ 未设置密码（该班当前无法登录）';
|
||||
process.stdout.write(` ${item.code.padEnd(8)} ${item.name.padEnd(16)} ${state}\n`);
|
||||
}
|
||||
}
|
||||
|
||||
async function cmdDumpHash(modules, key) {
|
||||
const { prisma } = modules;
|
||||
const target = await resolveTarget(prisma, key);
|
||||
if (target.error) return fail(target.error, target.code);
|
||||
if (!target.hash) return fail(`${target.label} 当前没有密码（passwordHash 为空）`, EXIT.NOT_FOUND);
|
||||
// 只给调用方（root）看的原始数据，不落到本工具的日志里
|
||||
process.stdout.write(`${JSON.stringify({ target: key, kind: target.kind, id: target.id, hash: target.hash })}\n`);
|
||||
}
|
||||
|
||||
async function cmdSetPassword(modules, key, readSecret) {
|
||||
const { prisma, hashPassword } = modules;
|
||||
const target = await resolveTarget(prisma, key);
|
||||
if (target.error) return fail(target.error, target.code);
|
||||
|
||||
const secret = await readSecret();
|
||||
const problems = checkStrength(secret, key);
|
||||
if (problems.length > 0) return fail(`密码不合规：${problems.join('；')}`, EXIT.WEAK);
|
||||
|
||||
const hash = await hashPassword(secret);
|
||||
if (target.kind === 'class') {
|
||||
await prisma.class.update({ where: { id: target.id }, data: { passwordHash: hash } });
|
||||
} else {
|
||||
await prisma.user.update({ where: { id: target.id }, data: { passwordHash: hash } });
|
||||
}
|
||||
|
||||
// 写完立刻复核一次：曾经出现过"bcrypt 参数不一致导致写进去的哈希验证不过"的排查成本
|
||||
const ok = await modules.verifyPassword(secret, hash);
|
||||
if (!ok) return fail('写入后复核失败：哈希无法通过校验，请用 restore-hash 回滚', EXIT.FAIL);
|
||||
|
||||
process.stdout.write(`已更新密码：${target.label}\n`);
|
||||
}
|
||||
|
||||
async function cmdVerify(modules, key, readSecret) {
|
||||
const { prisma, verifyPassword } = modules;
|
||||
const target = await resolveTarget(prisma, key);
|
||||
if (target.error) return fail(target.error, target.code);
|
||||
const secret = await readSecret();
|
||||
const ok = !!target.hash && (await verifyPassword(secret, target.hash));
|
||||
process.stdout.write(`${ok ? 'match' : 'mismatch'}\n`);
|
||||
if (!ok) process.exitCode = EXIT.FAIL;
|
||||
}
|
||||
|
||||
async function cmdRestoreHash(modules, backupFile) {
|
||||
const { prisma } = modules;
|
||||
if (!fs.existsSync(backupFile)) return fail(`备份文件不存在：${backupFile}`, EXIT.NOT_FOUND);
|
||||
let payload;
|
||||
try {
|
||||
payload = JSON.parse(fs.readFileSync(backupFile, 'utf8'));
|
||||
} catch (error) {
|
||||
return fail(`备份文件不是合法 JSON：${error.message}`);
|
||||
}
|
||||
const { target, hash } = payload;
|
||||
if (typeof target !== 'string' || typeof hash !== 'string') {
|
||||
return fail('备份文件缺少 target / hash 字段，拒绝回滚');
|
||||
}
|
||||
if (target.startsWith('class:')) {
|
||||
await prisma.class.update({ where: { code: target.slice('class:'.length).toUpperCase() }, data: { passwordHash: hash } });
|
||||
} else {
|
||||
await prisma.user.update({ where: { username: target }, data: { passwordHash: hash } });
|
||||
}
|
||||
process.stdout.write(`已回滚密码哈希：${target}\n`);
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ 入口 */
|
||||
|
||||
const argv = process.argv.slice(2);
|
||||
const command = argv[0] ?? 'help';
|
||||
const args = argv.slice(1);
|
||||
const wantsJson = args.includes('--json');
|
||||
const positional = args.filter((item) => !item.startsWith('--'));
|
||||
|
||||
function usage() {
|
||||
process.stdout.write(
|
||||
[
|
||||
'classhelper 离线账号工具（一般由 classhelper 命令调用）',
|
||||
'',
|
||||
' info 输出数据库与表行数（JSON）',
|
||||
' list [--json] 列出可登录账号与班级账号',
|
||||
' dump-hash <用户名|class:班级码> 输出当前密码哈希（供改密前备份）',
|
||||
' set-password <用户名> 从 stdin 读新密码并写入',
|
||||
' set-class-password <班级码> 从 stdin 读新密码并写入班级账号',
|
||||
' verify <用户名> 从 stdin 读密码，输出 match / mismatch',
|
||||
' restore-hash <备份json路径> 用备份文件里的哈希回滚',
|
||||
' snapshot <目标db文件> 把 SQLite 库一致性快照到指定路径（VACUUM INTO）',
|
||||
'',
|
||||
].join('\n'),
|
||||
);
|
||||
}
|
||||
|
||||
if (command === 'help' || command === '--help' || command === '-h') {
|
||||
usage();
|
||||
} else if (
|
||||
![
|
||||
'info',
|
||||
'list',
|
||||
'dump-hash',
|
||||
'set-password',
|
||||
'set-class-password',
|
||||
'verify',
|
||||
'restore-hash',
|
||||
'snapshot',
|
||||
].includes(command)
|
||||
) {
|
||||
fail(`未知子命令：${command}\n`, EXIT.USAGE);
|
||||
usage();
|
||||
} else {
|
||||
const modules = await loadServerModules();
|
||||
if (!modules) {
|
||||
// 已经在 loadServerModules 里设了 exitCode
|
||||
} else {
|
||||
try {
|
||||
switch (command) {
|
||||
case 'info':
|
||||
await cmdInfo(modules);
|
||||
break;
|
||||
case 'list':
|
||||
await cmdList(modules, wantsJson);
|
||||
break;
|
||||
case 'dump-hash':
|
||||
if (!positional[0]) fail('缺少目标账号', EXIT.USAGE);
|
||||
else await cmdDumpHash(modules, positional[0]);
|
||||
break;
|
||||
case 'set-password':
|
||||
case 'set-class-password': {
|
||||
const key = command === 'set-class-password' ? `class:${positional[0] ?? ''}` : (positional[0] ?? '');
|
||||
if (!positional[0]) fail('缺少目标账号', EXIT.USAGE);
|
||||
else await cmdSetPassword(modules, key, readSecretFromStdin);
|
||||
break;
|
||||
}
|
||||
case 'verify':
|
||||
if (!positional[0]) fail('缺少目标账号', EXIT.USAGE);
|
||||
else await cmdVerify(modules, positional[0], readSecretFromStdin);
|
||||
break;
|
||||
case 'restore-hash':
|
||||
if (!positional[0]) fail('缺少备份文件路径', EXIT.USAGE);
|
||||
else await cmdRestoreHash(modules, positional[0]);
|
||||
break;
|
||||
case 'snapshot':
|
||||
if (!positional[0]) fail('缺少目标文件路径', EXIT.USAGE);
|
||||
else await cmdSnapshot(modules, positional[0]);
|
||||
break;
|
||||
default:
|
||||
usage();
|
||||
}
|
||||
} catch (error) {
|
||||
fail(error instanceof Error ? error.message : String(error));
|
||||
} finally {
|
||||
// 不用 process.exit()：在顶层 await 里硬退会踩 libuv 断言（见 AGENTS.md §7）
|
||||
await modules.disconnectPrisma();
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,302 @@
|
||||
#!/usr/bin/env bash
|
||||
# ---------------------------------------------------------------------------
|
||||
# 班级小助手 · 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 '%s班级小助手 · 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)"
|
||||
|
||||
check "弱密码被拒绝（长度/种数不足）" \
|
||||
"$(printf 'abc\nabc\n' | "$CLASSHELPER" password "$ADMIN_USER" 2>&1 | 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)"
|
||||
check "password --list 能列出账号" \
|
||||
"$("$CLASSHELPER" password --list 2>&1 | 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
|
||||
check "backup list 能列出备份" "$("$CLASSHELPER" backup list 2>&1 | 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 时从 stdin 读，因此用管道喂 yes
|
||||
printf 'yes\n' | CLASSHELPER_NO_TTY=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
|
||||
@@ -0,0 +1,536 @@
|
||||
# Linux 部署与运维指南
|
||||
|
||||
本文覆盖服务端在 Linux 上的**一键安装**与日常运维（`classhelper` 命令）。
|
||||
适用：Ubuntu 20.04+ / Debian 11+ / CentOS 7+ / Rocky Linux / AlmaLinux 8+（自动识别 apt / yum / dnf）。
|
||||
|
||||
不想看长文的话，最短路径是这两条命令：
|
||||
|
||||
```bash
|
||||
sudo bash install.sh --package /path/to/classhelper-server-linux-x64-1.1.0.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`](../.github/workflows/release-linux-server.yml)
|
||||
就是干这个的（拿 ubuntu runner 跑 `pnpm dist:server:linux`，再把产物挂到对应 Release 上）：
|
||||
|
||||
1. 本地照惯例发 Windows 包的 Release（tag 形如 `v1.1.0`）；
|
||||
2. GitHub → Actions → 「发布 Linux 服务端安装包」→ Run workflow → 填 tag → 运行；
|
||||
3. 跑完 Release 里会多出 Linux 包与更新后的 `SHA256SUMS-<版本>.txt`。
|
||||
|
||||
内网离线分发也可以：在能上网的机器上 `pnpm dist:server:linux`，把 tar.gz 拷进去，
|
||||
用 `install.sh --package /path/to/xxx.tar.gz --sha256 <哈希>` 安装。
|
||||
|
||||
### 没有 Linux 机器时（交叉构建）
|
||||
|
||||
`pnpm dist:server:linux` 在非 Linux 上也**能跑**：脚本会用 npm 的 `--os=linux --cpu=x64`
|
||||
按目标平台解析可选依赖，所以 `@libsql/linux-x64-gnu` 这些"按平台分发"的包会被正确装进来。
|
||||
适合本地快速打一个包去验证安装与运维流程。已核对过的结论：
|
||||
|
||||
| 项 | 结论 |
|
||||
| --- | --- |
|
||||
| SQLite 驱动 | ✅ 包内是 `@libsql/linux-x64-gnu` + `linux-x64-musl`，**没有任何 win32 残留** |
|
||||
| 服务端本体 | ✅ Node + libsql + express + socket.io 都是纯 JS 或已就位的 Linux 原生包 |
|
||||
| 运维命令 | ✅ `status` / `doctor` / `password` / `backup` / `upgrade` / `rollback` 都不依赖平台差异 |
|
||||
| Web 端「一键切换数据库」 | ⚠ **可能失败**：这条链路要调 prisma CLI 的 schema engine，CLI 在运行期按平台扫 `@prisma/engines/schema-engine-debian-openssl-3.0.x` 这类路径，而交叉包里只有宿主平台的 `schema-engine-windows.exe` |
|
||||
|
||||
所以交叉包**能装、能跑、能验收**，只是那一个 Web 端功能存疑 —— 它会在包内写入 `.cross-built` 标记，
|
||||
`classhelper doctor` 会据此提示你（不会静默）。**正式发布一律用 GitHub Actions 那条路。**
|
||||
|
||||
```bash
|
||||
# 开发机（Windows 也可以）
|
||||
pnpm dist:server:linux
|
||||
# → release-server/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.0.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.0.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.0.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 # 改某个班的班级密码（学生端登录用）
|
||||
```
|
||||
|
||||
安全约定（照要求逐条落实）：
|
||||
|
||||
- 密码**交互输入、不回显**；不接受命令行传参，因此不会进 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`](../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` 看探针与监听地址；云服务器还要在**安全组**放行端口 |
|
||||
| 改了配置没生效 | 是否重启过（`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`（直连数据库，不需要登录） |
|
||||
| 学生端连不上 | 客户端「服务器地址」填 `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 release-server/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.0.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 登录，改一次密码再登录
|
||||
# ② 学生端客户端填 http://<IP>:4000 用班级码 G101/123456 登录，收到一条老师发的通知
|
||||
# ③ 重跑安装器（幂等性）：sudo bash /tmp/install.sh --yes --package <同一个包>
|
||||
# 期望：配置与数据保留、JWT_SECRET 不变（已登录用户不被踢下线）
|
||||
# ④ 卸载：sudo classhelper uninstall --yes
|
||||
# 期望：服务停止、单元删除、/usr/local/bin/classhelper 消失、
|
||||
# 数据与配置被搬到 /var/backups/classhelper/uninstall-*/
|
||||
# ⑤ 重启机器后服务自动起来（systemctl is-enabled classhelper）
|
||||
```
|
||||
|
||||
### 10.5 Rocky 9 的差异点
|
||||
|
||||
- 包管理器走 `dnf`，依赖包名与 apt 不同（`install.sh` 已按 `PKG` 分支处理）；
|
||||
- 默认没有 `curl` 之外的工具时会被补装，注意首次安装需要能访问 dnf 源；
|
||||
- 防火墙默认是 `firewalld`：用 `--open-firewall` 或手工
|
||||
`firewall-cmd --add-port=4000/tcp --permanent && firewall-cmd --reload`；
|
||||
- SELinux（Enforcing）：服务读写 `/opt/classhelper` 与 `/etc/classhelper` 一般不受影响，
|
||||
若日志里出现 `Permission denied` 且路径正常，先 `ausearch -m avc -ts recent` 看是不是 SELinux，
|
||||
可以用 `semanage fcontext` 加规则，或临时 `setenforce 0` 验证判断。
|
||||
|
||||
---
|
||||
|
||||
## 11. 安全清单
|
||||
|
||||
- [ ] 改掉默认管理员密码：`classhelper password admin`（**公网部署第一件事**）
|
||||
- [ ] 公网服务前面加 Nginx + HTTPS，`CORS_ORIGIN` 收敛到具体域名
|
||||
- [ ] 定期备份：`classhelper backup schedule daily`，并确认备份能恢复（`backup restore` 演练一次）
|
||||
- [ ] 配置与备份权限：`config.env` 600、`/etc/classhelper` 700、备份目录 700
|
||||
- [ ] `classhelper doctor` 无待处理项；关注"最近 7 天内有备份"
|
||||
- [ ] 审计日志（`/var/log/classhelper/audit.log`）随日志轮转保留，必要时接集中日志
|
||||
- [ ] 只在需要时使用 `--purge`；卸载默认保留数据与备份
|
||||
- [ ] 升级包一律校验 sha256（`upgrade` 内网分发时也要带 `--sha256`）
|
||||
+90
-114
@@ -4,9 +4,9 @@
|
||||
|
||||
| 形态 | 适用场景 | 产物 | 本机验证情况 |
|
||||
| --------------------- | -------------------------------------------- | -------------------------------------------------------- | -------------------------------------- |
|
||||
| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统） | `release-server/班级小助手服务端-<版本>-x64-setup.exe` | ✅ 已完整实测（静默安装/启停/卸载/UI） |
|
||||
| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统） | `releases/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 未实测 |
|
||||
| **C. Linux 原生部署** | 已有 Linux 服务器（systemd，SQLite 或 MySQL） | [`deploy/install.sh`](../deploy/install.sh) + `classhelper` 运维命令 | ⚠️ 本机无 Linux，实机验收见 [linux-deploy.md](linux-deploy.md) §10 |
|
||||
| **D. 手动部署** | 已有 Node 环境的服务器、需要自定义 | `pnpm dist:server` 的免安装目录 | ✅ 免安装目录已实测（163 项端到端） |
|
||||
|
||||
---
|
||||
@@ -22,10 +22,10 @@ pnpm dist:server -- --reuse-deps # 迭代打包：复用已安装依赖，跳
|
||||
|
||||
产物：
|
||||
|
||||
| 路径 | 说明 |
|
||||
| ----------------------------------------------------- | ----------------------------------------------- |
|
||||
| `release-server/classhelper-server/` | 免安装目录，可直接拷到任意 Windows x64 机器运行 |
|
||||
| `release-server/班级小助手服务端-1.0.0-x64-setup.exe` | 安装程序（约 34 MB，NSIS） |
|
||||
| 路径 | 说明 |
|
||||
| ----------------------------------------------------------------------- | ----------------------------------------------- |
|
||||
| `releases/server/<版本>/免安装/` | 免安装目录，可直接拷到任意 Windows x64 机器运行 |
|
||||
| `releases/server/<版本>/安装包/班级小助手服务端-<版本>-x64-setup.exe` | 安装程序（约 62 MB，NSIS） |
|
||||
|
||||
打包内容：内置 **Node 运行时**（目标机无需安装 Node.js）、后端产物、Web 管理端产物、
|
||||
生产依赖（真实目录，非软链）、迁移 SQL、`.env`（随机 JWT 密钥）、启停脚本。
|
||||
@@ -35,7 +35,7 @@ pnpm dist:server -- --reuse-deps # 迭代打包：复用已安装依赖，跳
|
||||
双击安装程序即可，**无需管理员权限**（当前用户级安装）：
|
||||
|
||||
- 安装目录：`%LOCALAPPDATA%\Programs\ClassHelperServer`
|
||||
- 静默安装：`"班级小助手服务端-1.0.0-x64-setup.exe" /S`
|
||||
- 静默安装：`"班级小助手服务端-1.1.1-x64-setup.exe" /S`
|
||||
- 开始菜单：启动服务 / 停止服务 / 重启服务 / 打开管理端 / 使用说明 / 卸载
|
||||
- 桌面：`班级小助手服务端.lnk`（打开管理端）
|
||||
- 自动加入当前用户开机自启（`HKCU\...\CurrentVersion\Run`）
|
||||
@@ -149,108 +149,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.1.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.1.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 +248,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,31 +256,19 @@ 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` |
|
||||
覆盖安装结果、服务探针、API 登录、改密（含审计与回滚）、备份、配置读写、key rotate、
|
||||
升级与回滚整条链路，末尾打印 `=== 结果：N/N 项通过 ===`。逐条清单见
|
||||
[linux-deploy.md](linux-deploy.md) 第 10 节。
|
||||
|
||||
> 注意：本机（开发环境）是 Windows 且无 Docker/WSL 发行版，因此 **3.1 的脚本没有在 Linux 实机跑过**。
|
||||
> 它复用的两套东西都已验证：Windows 免安装目录（同样的目录结构、`.env` 相对路径与
|
||||
> `AUTO_MIGRATE` 首启动行为）和 `deploy/Dockerfile` 的 runtime 阶段（同样的依赖清单与产物布局）。
|
||||
> 首次在服务器上执行后请按 3.4 的探针 + Web 登录 + `pnpm verify:e2e`（把 `VERIFY_BASE_URL` 指向服务器）确认。
|
||||
|
||||
---
|
||||
|
||||
@@ -302,7 +279,7 @@ 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 免安装目录
|
||||
pnpm dist:server -- --reuse-deps # 得到 releases/server/<版本>/免安装/ 免安装目录
|
||||
```
|
||||
|
||||
把该目录拷贝到目标机，编辑 `.env`（端口、数据库、密钥、跨域），然后：
|
||||
@@ -337,7 +314,6 @@ 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_TEACHER_PASSWORD` | `123456` | 新增/重置教师账号的默认密码（管理员录入教师用） |
|
||||
| `TERM_START_DATE` | — | 第 1 教学周的周一，用于"当前周次"与课表默认视图 |
|
||||
|
||||
+3
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "class-helper",
|
||||
"version": "1.0.0",
|
||||
"version": "1.1.1",
|
||||
"private": true,
|
||||
"description": "班级小助手 - 班级信息管理系统（Web 管理端 + 后端服务 + 桌面客户端）",
|
||||
"packageManager": "pnpm@11.8.0",
|
||||
@@ -16,6 +16,7 @@
|
||||
"build": "pnpm build:shared && pnpm --filter @classhelper/server build && pnpm --filter @classhelper/web-admin build && pnpm --filter @classhelper/desktop-client build",
|
||||
"build:desktop": "pnpm build:shared && pnpm --filter @classhelper/desktop-client build",
|
||||
"build:classisland-plugin": "node packages/classisland-plugin/scripts/build.mjs",
|
||||
"check:icons": "node scripts/check-icons.mjs",
|
||||
"typecheck": "pnpm build:shared && pnpm -r --no-bail typecheck",
|
||||
"lint": "eslint .",
|
||||
"lint:fix": "eslint . --fix",
|
||||
@@ -38,6 +39,7 @@
|
||||
"dist:win": "pnpm --filter @classhelper/desktop-client dist:win",
|
||||
"dist:dir": "pnpm --filter @classhelper/desktop-client dist:dir",
|
||||
"dist:server": "pnpm build:shared && pnpm --filter @classhelper/server build && pnpm --filter @classhelper/web-admin build && node scripts/dist-server.mjs",
|
||||
"dist:server:linux": "pnpm build:shared && pnpm --filter @classhelper/server build && pnpm --filter @classhelper/web-admin build && node scripts/dist-server.mjs --platform linux",
|
||||
"dist:classisland-plugin": "node packages/classisland-plugin/scripts/build.mjs --cipx",
|
||||
"dist:all": "pnpm dist:server && pnpm dist:win && pnpm dist:classisland-plugin"
|
||||
},
|
||||
|
||||
@@ -14,6 +14,6 @@ description: |-
|
||||
4. 可选：把班级小助手上排好的课表镜像回 ClassIsland。
|
||||
entranceAssembly: 'ClassHelper.ClassIslandPlugin.dll'
|
||||
url: https://github.com/LoveChengke/ClassHelper
|
||||
version: 1.0.0.0
|
||||
version: 1.1.1.0
|
||||
apiVersion: 2.0.0.0
|
||||
author: 班级小助手
|
||||
@@ -495,7 +495,7 @@ public sealed class BridgeService : INotifyPropertyChanged, IDisposable
|
||||
/* ---------------------------------------------------------------- 内部实现 */
|
||||
|
||||
/// <summary>插件版本（与 manifest.yml / csproj 保持一致）。</summary>
|
||||
private const string PluginVersion = "1.0.0.0";
|
||||
private const string PluginVersion = "1.1.1.0";
|
||||
|
||||
/// <summary>ClassIsland 版本读不到时不该让上报失败（开发版可能为 null）。</summary>
|
||||
private static string SafeAppVersion()
|
||||
|
||||
@@ -2,6 +2,18 @@ appId: com.classhelper.desktop
|
||||
productName: 班级小助手
|
||||
copyright: Copyright © 2026 Class Helper
|
||||
|
||||
# 语言包：Electron 发行版自带 55 个 `locales/*.pak`（实测 48.3MB 未压缩 / 约 10MB 压缩后），
|
||||
# 而本应用界面文案只有中文，其余 54 个语言包纯属白占体积（`win-unpacked` 372MB → 约 324MB）。
|
||||
# 这是 electron-builder 的官方选项：`app-builder-lib` 的 removeUnusedLanguagesIfNeeded()
|
||||
# 会对 `locales/*.pak` 做精确匹配删除，只留 `zh-CN.pak`（0.6MB）。
|
||||
#
|
||||
# 注意：**不要**为了继续压体积去删 dxcompiler/vk_swiftshader/d3dcompiler_47 这些 GPU 回退组件，
|
||||
# 或 LICENSES.chromium.html —— 前者是教室老显卡/虚拟机上的 D3D12/D3D11/Vulkan 渲染回退，
|
||||
# 后者是 Chromium 的许可证声明，合计只能再省约 12MB，风险不成比例。
|
||||
# 另外安装包有硬底：`班级小助手.exe`（就是 electron.exe）压缩后本身就有 85~90MB，别再指望压到 60MB。
|
||||
electronLanguages:
|
||||
- zh-CN
|
||||
|
||||
directories:
|
||||
output: release
|
||||
buildResources: build
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
{
|
||||
"name": "@classhelper/desktop-client",
|
||||
"version": "1.0.0",
|
||||
"version": "1.1.1",
|
||||
"private": true,
|
||||
"description": "班级小助手 EXE 客户端（Electron + Vue 3 + Element Plus + Socket.IO + IndexedDB 离线缓存）",
|
||||
"author": "Class Helper",
|
||||
"main": "dist/main/index.js",
|
||||
"scripts": {
|
||||
"dev": "node scripts/dev.mjs",
|
||||
"build": "npm run build:main && npm run build:renderer && npm run check:secrets",
|
||||
"build": "node ../../scripts/check-icons.mjs && npm run build:main && npm run build:renderer && npm run check:secrets",
|
||||
"build:main": "node scripts/build-main.mjs",
|
||||
"build:renderer": "vite build",
|
||||
"check:secrets": "node scripts/check-bundle-secrets.mjs",
|
||||
@@ -21,7 +21,6 @@
|
||||
"@classhelper/shared": "workspace:*",
|
||||
"@element-plus/icons-vue": "^2.3.2",
|
||||
"axios": "^1.20.0",
|
||||
"echarts": "^6.1.0",
|
||||
"element-plus": "^2.14.5",
|
||||
"pinia": "^4.0.3",
|
||||
"socket.io-client": "^4.8.3",
|
||||
|
||||
@@ -42,6 +42,8 @@ interface PersistedConfig {
|
||||
theme?: 'light' | 'dark';
|
||||
/** 主侧边栏是否折叠（向后兼容：旧配置没有该字段视为展开） */
|
||||
sidebarCollapsed?: boolean;
|
||||
/** 用户选择「忽略此版本」的版本号（向后兼容：旧配置没有该字段视为没忽略过任何版本） */
|
||||
ignoredUpdateVersion?: string;
|
||||
}
|
||||
|
||||
const DEFAULT_CONFIG: PersistedConfig = {
|
||||
@@ -56,6 +58,7 @@ const DEFAULT_CONFIG: PersistedConfig = {
|
||||
onboardingDone: false,
|
||||
theme: 'light',
|
||||
sidebarCollapsed: false,
|
||||
ignoredUpdateVersion: '',
|
||||
};
|
||||
|
||||
/** 主题白名单：非法值一律回落浅色 */
|
||||
@@ -179,7 +182,7 @@ function decryptToken(raw: PersistedConfig): string | null {
|
||||
}
|
||||
}
|
||||
|
||||
function readPersisted(): PersistedConfig {
|
||||
function readPersistedFromDisk(): PersistedConfig {
|
||||
try {
|
||||
const content = fs.readFileSync(configFilePath(), 'utf8');
|
||||
const parsed = JSON.parse(content) as Partial<PersistedConfig>;
|
||||
@@ -198,16 +201,125 @@ function readPersisted(): PersistedConfig {
|
||||
onboardingDone: parsed.onboardingDone === true,
|
||||
theme: normalizeTheme(parsed.theme),
|
||||
sidebarCollapsed: parsed.sidebarCollapsed === true,
|
||||
ignoredUpdateVersion:
|
||||
typeof parsed.ignoredUpdateVersion === 'string' ? parsed.ignoredUpdateVersion : '',
|
||||
};
|
||||
} catch {
|
||||
return { ...DEFAULT_CONFIG };
|
||||
}
|
||||
}
|
||||
|
||||
function writePersisted(config: PersistedConfig): void {
|
||||
const target = configFilePath();
|
||||
fs.mkdirSync(path.dirname(target), { recursive: true });
|
||||
fs.writeFileSync(target, JSON.stringify(config, null, 2), 'utf8');
|
||||
/* ------------------------------------------------------------ 内存缓存 + 异步合并写
|
||||
*
|
||||
* 为什么不能每次 saveConfig 都同步读写盘（原来的写法）：
|
||||
* 侧栏折叠（`stores/ui.ts` 的 toggleSidebar）、主题切换、通知渠道、作业看板偏好、登录/登出
|
||||
* 全都走 `saveConfig`，而它一次调用要做「readFileSync + JSON.parse + 8 个 normalize」**两遍**
|
||||
* （开头读一遍、结尾 `getConfig()` 又读一遍）+ `writeFileSync` 一遍 + DPAPI 解密一遍，
|
||||
* **全部同步跑在主进程主线程上**。主进程是 Electron 的消息泵进程，被它摁住的那一拍
|
||||
* 渲染进程也跟着掉帧 —— 用户反馈的"点汉堡展开/收回侧栏时卡一下"就是这一拍。
|
||||
*
|
||||
* 现在：配置常驻内存（连已解密的 token 一起缓存），写盘改成**异步 + 合并** ——
|
||||
* 同一拍内的多次改动只落最后一次，写入串行不会互相覆盖；退出前由 `flushConfigSync()` 兜底。
|
||||
*
|
||||
* **语义变化（有意为之）**：`saveConfig()` 返回时数据可能还没落盘（延迟 CONFIG_WRITE_DEBOUNCE_MS）。
|
||||
* 正常退出（托盘 → 退出）会走 `flushConfigSync()`，不会丢最后一次改动；只有进程被强杀
|
||||
* 才可能丢这最后 120ms 内的改动。
|
||||
*/
|
||||
|
||||
/** 写入合并窗口：拖动同类控件（滑块/连续点击）时的连续改动只落最后一次 */
|
||||
const CONFIG_WRITE_DEBOUNCE_MS = 120;
|
||||
|
||||
interface ConfigCache {
|
||||
config: PersistedConfig;
|
||||
/** 已解密的登录令牌（null = 未登录 / 解密失败）。缓存它是为了不再每次都走一遍 DPAPI */
|
||||
token: string | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 内存配置。**必须懒初始化**：`main/index.ts` 会先 `app.setPath('userData', smokeProfile)`
|
||||
* 把配置目录指到冒烟专用 profile，之后才第一次读配置；在模块顶层立即读盘会读错文件。
|
||||
*/
|
||||
let cache: ConfigCache | null = null;
|
||||
|
||||
function loadCache(): ConfigCache {
|
||||
if (cache) return cache;
|
||||
const config = readPersistedFromDisk();
|
||||
cache = { config, token: decryptToken(config) };
|
||||
return cache;
|
||||
}
|
||||
|
||||
/** 待写入的配置快照（合并窗口内只保留最后一次） */
|
||||
let pendingWrite: PersistedConfig | null = null;
|
||||
let writeTimer: ReturnType<typeof setTimeout> | null = null;
|
||||
/** 是否有一次异步写入正在进行（用它把写入串行化，避免两次写互相覆盖） */
|
||||
let writing = false;
|
||||
|
||||
/** 排一次落盘。合并窗口内的多次调用只会写最后一次；`immediate` 用于不该被延迟的场景 */
|
||||
function scheduleWrite(config: PersistedConfig, immediate = false): void {
|
||||
pendingWrite = config;
|
||||
if (immediate) {
|
||||
if (writeTimer !== null) {
|
||||
clearTimeout(writeTimer);
|
||||
writeTimer = null;
|
||||
}
|
||||
void flushConfigAsync();
|
||||
return;
|
||||
}
|
||||
// 已有待写任务（定时器在跑或正在写）：内容已经记在 pendingWrite 里，等它自己收尾即可。
|
||||
// 正在写的那次结束后会再检查一次 pendingWrite（见 flushConfigAsync 的 finally）。
|
||||
if (writeTimer !== null || writing) return;
|
||||
writeTimer = setTimeout(() => {
|
||||
writeTimer = null;
|
||||
void flushConfigAsync();
|
||||
}, CONFIG_WRITE_DEBOUNCE_MS);
|
||||
}
|
||||
|
||||
/** 异步落盘（不阻塞主进程消息泵）。失败只记日志 —— 与 readPersistedFromDisk 的容错口径一致 */
|
||||
async function flushConfigAsync(): Promise<void> {
|
||||
if (writing) return;
|
||||
const target = pendingWrite;
|
||||
if (!target) return;
|
||||
pendingWrite = null;
|
||||
writing = true;
|
||||
// 先把内容序列化下来：写入期间的后续改动由 pendingWrite 负责补一次，
|
||||
// 不会出现"这一次写的是半新半旧的对象"
|
||||
const payload = JSON.stringify(target, null, 2);
|
||||
try {
|
||||
const file = configFilePath();
|
||||
await fs.promises.mkdir(path.dirname(file), { recursive: true });
|
||||
await fs.promises.writeFile(file, payload, 'utf8');
|
||||
} catch (error) {
|
||||
logger.warn(`写入配置失败（${configFilePath()}）：${error instanceof Error ? error.message : error}`);
|
||||
} finally {
|
||||
writing = false;
|
||||
// 写入期间又有改动：再写一次（内容已被 pendingWrite 合并成最后一次）
|
||||
if (pendingWrite) void flushConfigAsync();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 退出前同步落地一次（`main/index.ts` 的 shutdownResources 调用）。
|
||||
*
|
||||
* 即使没有待写内容也把内存里的配置重写一遍：那一时刻可能正有一次异步写在进行中，
|
||||
* 它未必来得及完成；退出时多写一次的代价可以忽略。
|
||||
*/
|
||||
export function flushConfigSync(): void {
|
||||
if (writeTimer !== null) {
|
||||
clearTimeout(writeTimer);
|
||||
writeTimer = null;
|
||||
}
|
||||
const target = pendingWrite ?? cache?.config ?? null;
|
||||
if (!target) return;
|
||||
pendingWrite = null;
|
||||
try {
|
||||
const file = configFilePath();
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, JSON.stringify(target, null, 2), 'utf8');
|
||||
} catch (error) {
|
||||
logger.warn(
|
||||
`退出前写入配置失败（${configFilePath()}）：${error instanceof Error ? error.message : error}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -229,13 +341,13 @@ function normalizeServerUrl(input: string): string | null {
|
||||
}
|
||||
}
|
||||
|
||||
/** 读取配置（token 已解密），供渲染进程使用 */
|
||||
export function getConfig(): DesktopStoredConfig {
|
||||
const persisted = readPersisted();
|
||||
/** 由内存缓存组装对渲染进程暴露的配置（不再读盘、不再解密） */
|
||||
function toDesktopConfig(state: ConfigCache): DesktopStoredConfig {
|
||||
const persisted = state.config;
|
||||
return {
|
||||
serverUrl: persisted.serverUrl,
|
||||
username: persisted.username,
|
||||
token: decryptToken(persisted),
|
||||
token: state.token,
|
||||
island: normalizeIslandAppearance(persisted.island),
|
||||
homeworkBoard: normalizeHomeworkBoard(persisted.homeworkBoard),
|
||||
notificationChannel: normalizeNotificationChannel(persisted.notificationChannel),
|
||||
@@ -243,12 +355,19 @@ export function getConfig(): DesktopStoredConfig {
|
||||
onboardingDone: persisted.onboardingDone === true,
|
||||
theme: normalizeTheme(persisted.theme),
|
||||
sidebarCollapsed: persisted.sidebarCollapsed === true,
|
||||
ignoredUpdateVersion: persisted.ignoredUpdateVersion ?? '',
|
||||
};
|
||||
}
|
||||
|
||||
/** 读取配置（token 已解密），供渲染进程使用 */
|
||||
export function getConfig(): DesktopStoredConfig {
|
||||
return toDesktopConfig(loadCache());
|
||||
}
|
||||
|
||||
/** 局部更新配置：只覆盖传入的字段 */
|
||||
export function saveConfig(patch: Partial<DesktopStoredConfig>): DesktopStoredConfig {
|
||||
const persisted = readPersisted();
|
||||
const state = loadCache();
|
||||
const persisted = state.config;
|
||||
|
||||
if (typeof patch.serverUrl === 'string' && patch.serverUrl.trim()) {
|
||||
const normalized = normalizeServerUrl(patch.serverUrl);
|
||||
@@ -284,20 +403,28 @@ export function saveConfig(patch: Partial<DesktopStoredConfig>): DesktopStoredCo
|
||||
if (patch.sidebarCollapsed !== undefined) {
|
||||
persisted.sidebarCollapsed = patch.sidebarCollapsed === true;
|
||||
}
|
||||
// 空串是合法值（= 没有忽略任何版本），因此这里只判类型不判空
|
||||
if (typeof patch.ignoredUpdateVersion === 'string') {
|
||||
persisted.ignoredUpdateVersion = patch.ignoredUpdateVersion;
|
||||
}
|
||||
if (patch.token !== undefined) {
|
||||
const encrypted = encryptToken(patch.token);
|
||||
persisted.token = encrypted.token;
|
||||
persisted.tokenEncrypted = encrypted.tokenEncrypted;
|
||||
// 明文一并进缓存：既省掉一次 DPAPI 解密，也保证紧接着的 getConfig() 读到的就是刚存的令牌
|
||||
state.token = patch.token;
|
||||
}
|
||||
|
||||
writePersisted(persisted);
|
||||
return getConfig();
|
||||
scheduleWrite(persisted);
|
||||
return toDesktopConfig(state);
|
||||
}
|
||||
|
||||
/** 清空为默认配置（退出登录 / 重置） */
|
||||
/** 清空为默认配置（退出登录 / 重置）。立即落盘：它对应退出登录，不该被合并窗口延迟 */
|
||||
export function clearConfig(): DesktopStoredConfig {
|
||||
writePersisted({ ...DEFAULT_CONFIG });
|
||||
return getConfig();
|
||||
const state: ConfigCache = { config: { ...DEFAULT_CONFIG }, token: null };
|
||||
cache = state;
|
||||
scheduleWrite(state.config, true);
|
||||
return toDesktopConfig(state);
|
||||
}
|
||||
|
||||
export function getConfigPath(): string {
|
||||
|
||||
@@ -1,12 +1,13 @@
|
||||
import path from 'node:path';
|
||||
import { pathToFileURL } from 'node:url';
|
||||
import { BrowserWindow, app, shell } from 'electron';
|
||||
import { getConfig } from './config.js';
|
||||
import { flushConfigSync, getConfig } from './config.js';
|
||||
import { registerIpcHandlers } from './ipc.js';
|
||||
import { island, registerIslandIpc } from './island.js';
|
||||
import { logger } from './logger.js';
|
||||
import { runSmokeTest } from './smoke.js';
|
||||
import { createTray, destroyTray, isTrayReady } from './tray.js';
|
||||
import { scheduleStartupUpdateCheck } from './update.js';
|
||||
|
||||
// 主进程由 esbuild 打包为 CommonJS，因此这里可以直接使用 __dirname
|
||||
// （dist/main/index.js -> dist/preload/index.js 与 dist/renderer/index.html）
|
||||
@@ -163,6 +164,9 @@ if (!gotLock) {
|
||||
logger.warn(`系统托盘初始化失败（不影响主功能）：${error instanceof Error ? error.message : error}`);
|
||||
}
|
||||
|
||||
// 启动后自动查一次更新（延迟几秒，不跟首屏抢带宽）；冒烟模式下自动跳过，见 main/update.ts
|
||||
scheduleStartupUpdateCheck(() => mainWindow);
|
||||
|
||||
if (isSmokeTest) {
|
||||
try {
|
||||
await runSmokeTest(mainWindow);
|
||||
@@ -190,6 +194,11 @@ if (!gotLock) {
|
||||
*/
|
||||
function shutdownResources(): string {
|
||||
const done: string[] = [];
|
||||
// 配置是**异步合并写**的（见 main/config.ts）：退出前必须同步落地一次，
|
||||
// 否则"刚改完设置就退出"这一类操作会丢掉最后一次改动。
|
||||
// 放在最前面：后面会销毁窗口与灵动岛，先落盘不依赖任何窗口是否还在。
|
||||
flushConfigSync();
|
||||
done.push('配置已落盘');
|
||||
if (isTrayReady()) {
|
||||
destroyTray();
|
||||
done.push('托盘已销毁');
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
import { app, ipcMain, shell } from 'electron';
|
||||
import type { UpdateInfo } from '@classhelper/shared';
|
||||
import { clearConfig, getConfig, getConfigPath, saveConfig } from './config.js';
|
||||
import { checkForUpdates, ignoreUpdateVersion } from './update.js';
|
||||
import type { DesktopAppInfo, DesktopStoredConfig } from '../types/desktop.js';
|
||||
|
||||
/** IPC 通道名集中管理，preload 与主进程共用同一份字符串 */
|
||||
@@ -9,6 +11,8 @@ export const IPC_CHANNELS = {
|
||||
clearConfig: 'classhelper:config:clear',
|
||||
appInfo: 'classhelper:app:info',
|
||||
openExternal: 'classhelper:shell:open-external',
|
||||
updateCheck: 'classhelper:update:check',
|
||||
updateIgnore: 'classhelper:update:ignore',
|
||||
} as const;
|
||||
|
||||
export function registerIpcHandlers(): void {
|
||||
@@ -39,6 +43,21 @@ export function registerIpcHandlers(): void {
|
||||
await shell.openExternal(url);
|
||||
return true;
|
||||
});
|
||||
|
||||
/**
|
||||
* 检查更新（走主进程直连 GitHub，见 main/update.ts 的说明）。
|
||||
*
|
||||
* `force` 为 true 时绕过主进程缓存 —— 对应「关于」页里用户主动点的那次检查；
|
||||
* 启动自动检查一律用缓存（避免同一分钟内重复请求打满匿名限流）。
|
||||
*/
|
||||
ipcMain.handle(IPC_CHANNELS.updateCheck, (_event, force?: boolean): Promise<UpdateInfo> => {
|
||||
return checkForUpdates(force === true);
|
||||
});
|
||||
|
||||
/** 忽略某个版本的更新提示（记入 config.json，启动自动检查不再提示它） */
|
||||
ipcMain.handle(IPC_CHANNELS.updateIgnore, (_event, version: string): void => {
|
||||
if (typeof version === 'string') ignoreUpdateVersion(version);
|
||||
});
|
||||
}
|
||||
|
||||
export function getDiagnostics(): { configPath: string; config: DesktopStoredConfig } {
|
||||
|
||||
@@ -958,9 +958,9 @@ class IslandController {
|
||||
}
|
||||
|
||||
/** 当前应该把岛放在哪块屏上：跟随鼠标时用光标所在屏，否则用主屏 */
|
||||
private targetDisplay(): Electron.Display {
|
||||
private targetDisplay(cursor?: { x: number; y: number } | null): Electron.Display {
|
||||
return this.appearance.followCursorDisplay
|
||||
? screen.getDisplayNearestPoint(this.cursorOverride ?? screen.getCursorScreenPoint())
|
||||
? screen.getDisplayNearestPoint(cursor ?? this.cursorOverride ?? screen.getCursorScreenPoint())
|
||||
: screen.getPrimaryDisplay();
|
||||
}
|
||||
|
||||
@@ -970,10 +970,13 @@ class IslandController {
|
||||
* 原先锚点只在 `setAppearance()` 里算一次，于是"跟随鼠标屏幕"实际上**只在改设置的那一瞬间**
|
||||
* 生效：讲台从投影切回来之后，岛还留在原来那块屏上，直到用户再动一次外观设置。
|
||||
* 这里挂在已有的 60ms 命中轮询上（不新增定时器），并且只在目标屏幕真的变了、且窗口可见时才动窗口。
|
||||
*
|
||||
* 不需要额外监听 `screen` 的 display-* 事件：目标屏是由**当前光标位置**或主屏推出来的，
|
||||
* 插拔/切主屏之后下一轮 tick 自然会算出不同的 id，一样能触发重排。
|
||||
*/
|
||||
private syncAnchorDisplay(): void {
|
||||
private syncAnchorDisplay(cursor?: { x: number; y: number } | null): void {
|
||||
if (!this.win || this.win.isDestroyed()) return;
|
||||
const displayId = this.targetDisplay().id;
|
||||
const displayId = this.targetDisplay(cursor).id;
|
||||
if (this.anchorDisplayId === displayId) return;
|
||||
this.anchorDisplayId = displayId;
|
||||
// 换屏了：可用高度（工作区）也跟着换，列表"能放几行"要重算
|
||||
@@ -1409,11 +1412,14 @@ class IslandController {
|
||||
/**
|
||||
* 光标相对窗口左上角的本地坐标（CSS px / DIP，与渲染进程上报的岛体矩形同一坐标系）。
|
||||
* 冒烟里用 `setHitTestCursor` 注入，真实场景读系统光标。
|
||||
*
|
||||
* `cursor`：调用方在本轮 tick 里已经读过的光标位置（见 `startHitPoll`）。
|
||||
* 传进来就复用它，避免同一个 tick 里重复调 `screen.getCursorScreenPoint()`。
|
||||
*/
|
||||
private cursorLocal(): { x: number; y: number } | null {
|
||||
private cursorLocal(cursor?: { x: number; y: number } | null): { x: number; y: number } | null {
|
||||
if (!this.win || this.win.isDestroyed()) return null;
|
||||
const bounds = this.win.getBounds();
|
||||
const point = this.cursorOverride ?? screen.getCursorScreenPoint();
|
||||
const point = cursor ?? this.cursorOverride ?? screen.getCursorScreenPoint();
|
||||
return { x: point.x - bounds.x, y: point.y - bounds.y };
|
||||
}
|
||||
|
||||
@@ -1494,7 +1500,7 @@ class IslandController {
|
||||
}
|
||||
|
||||
/** 按光标位置校正命中（不依赖渲染进程是否收到 mousemove） */
|
||||
private syncHitFromCursor(): void {
|
||||
private syncHitFromCursor(cursor?: { x: number; y: number } | null): void {
|
||||
if (!this.win || this.win.isDestroyed() || !this.win.isVisible()) {
|
||||
this.setInteractive(false, '窗口不可见');
|
||||
return;
|
||||
@@ -1505,18 +1511,34 @@ class IslandController {
|
||||
this.setInteractive(false, '隐藏态');
|
||||
return;
|
||||
}
|
||||
this.setInteractive(this.isInsideHitRect(this.cursorLocal()), '光标轮询');
|
||||
this.setInteractive(this.isInsideHitRect(this.cursorLocal(cursor)), '光标轮询');
|
||||
}
|
||||
|
||||
private startHitPoll(): void {
|
||||
if (this.hitTimer) return;
|
||||
// 60ms：渲染进程的 mousemove 转发在 Windows 上并不可靠，这里是命中的**权威来源**，
|
||||
// 间隔必须足够小，否则"指针移上胶囊后立刻点击"会因窗口还没接收鼠标而点空（用户反馈过）。
|
||||
//
|
||||
// 每一跳的成本要压到最低（这个定时器从岛初始化一直跑到进程退出）：
|
||||
// 1) 光标位置**每跳只读一次**，命中判定与"跟随鼠标屏幕"共用 —— 原先 cursorLocal() 与
|
||||
// targetDisplay() 各读一次，等于每跳两次 `screen.getCursorScreenPoint()`；
|
||||
// 2) 窗口不可见时直接返回：此时命中判定与心跳检查本来就各自早退（窗口不可见 ⇒ 无命中可言），
|
||||
// 留着那两次系统调用纯属白跑。
|
||||
this.hitTimer = setInterval(() => {
|
||||
if (!this.win || this.win.isDestroyed()) return;
|
||||
const visible = this.win.isVisible();
|
||||
// 不可见、且不跟随鼠标屏幕时，连读光标都可省掉（targetDisplay 会走主屏分支）
|
||||
const cursor =
|
||||
visible || this.appearance.followCursorDisplay
|
||||
? (this.cursorOverride ?? screen.getCursorScreenPoint())
|
||||
: null;
|
||||
|
||||
// 先按目标屏幕校正窗口位置（换屏/插拔显示器），再算命中与心跳：
|
||||
// 顺序不能反，否则命中判定会用上一块屏的窗口坐标
|
||||
this.syncAnchorDisplay();
|
||||
this.syncHitFromCursor();
|
||||
this.syncAnchorDisplay(cursor);
|
||||
if (!visible) return;
|
||||
|
||||
this.syncHitFromCursor(cursor);
|
||||
this.checkRendererAlive();
|
||||
}, 60);
|
||||
// 定时器不应拖住进程退出
|
||||
@@ -1748,12 +1770,12 @@ const MIN_CARD_HEIGHT = 120;
|
||||
|
||||
|
||||
/**
|
||||
* 渲染进程心跳（渲染进程每 5s 上报一次）：超过这个时间没上报就认为它已经卡死/不响应。
|
||||
* 渲染进程心跳（渲染进程每 5s 上报一次，间隔写死在 `src/island/IslandApp.vue`）：
|
||||
* 超过这个时间没上报就认为它已经卡死/不响应。
|
||||
* 岛是"无边框透明置顶窗口"，渲染进程一旦挂掉，Windows 会把**最后一帧留在屏幕上**
|
||||
* 形成"幽灵胶囊"：窗口还在、看着正常，但怎么点都没反应（实测复现：崩掉渲染进程后
|
||||
* 点击完全不产生任何动作）。所以必须有心跳 + 重建来兜底。
|
||||
*/
|
||||
const RENDERER_ALIVE_INTERVAL_MS = 5_000;
|
||||
const RENDERER_ALIVE_TIMEOUT_MS = 20_000;
|
||||
/** 窗口重建限流：一段时间内最多重建几次，避免持续崩坏时无限重建 */
|
||||
const RECOVER_MAX_TIMES = 3;
|
||||
|
||||
@@ -15,6 +15,7 @@ import {
|
||||
ISLAND_URGENT_SIZE,
|
||||
} from './island.js';
|
||||
import { destroyTray, getTrayState, isTrayReady } from './tray.js';
|
||||
import { checkForUpdates, wasStartupCheckSkipped } from './update.js';
|
||||
|
||||
interface SmokeResult {
|
||||
name: string;
|
||||
@@ -555,11 +556,26 @@ async function diagnoseClosingFlash(label: string, withTouch: boolean): Promise<
|
||||
);
|
||||
if (buttonPoint) {
|
||||
const bounds = win.getBounds();
|
||||
island.setHitTestCursor({ x: Math.round(bounds.x + buttonPoint.x), y: Math.round(bounds.y + buttonPoint.y) });
|
||||
island.setHitTestCursor({
|
||||
x: Math.round(bounds.x + buttonPoint.x),
|
||||
y: Math.round(bounds.y + buttonPoint.y),
|
||||
});
|
||||
await sleep(160);
|
||||
win.webContents.sendInputEvent({ type: 'mouseDown', x: buttonPoint.x, y: buttonPoint.y, button: 'left', clickCount: 1 });
|
||||
win.webContents.sendInputEvent({
|
||||
type: 'mouseDown',
|
||||
x: buttonPoint.x,
|
||||
y: buttonPoint.y,
|
||||
button: 'left',
|
||||
clickCount: 1,
|
||||
});
|
||||
await sleep(40);
|
||||
win.webContents.sendInputEvent({ type: 'mouseUp', x: buttonPoint.x, y: buttonPoint.y, button: 'left', clickCount: 1 });
|
||||
win.webContents.sendInputEvent({
|
||||
type: 'mouseUp',
|
||||
x: buttonPoint.x,
|
||||
y: buttonPoint.y,
|
||||
button: 'left',
|
||||
clickCount: 1,
|
||||
});
|
||||
}
|
||||
const deadline = Date.now() + 1600;
|
||||
let index = 0;
|
||||
@@ -581,14 +597,8 @@ async function diagnoseClosingFlash(label: string, withTouch: boolean): Promise<
|
||||
const crop = image.crop({
|
||||
x: Math.max(0, Math.round((geometry.window.x - pad) * shotScale)),
|
||||
y: Math.max(0, Math.round((geometry.window.y - pad) * shotScale)),
|
||||
width: Math.min(
|
||||
image.getSize().width,
|
||||
Math.round((geometry.window.width + pad * 2) * shotScale),
|
||||
),
|
||||
height: Math.min(
|
||||
image.getSize().height,
|
||||
Math.round((geometry.window.height + pad * 2) * shotScale),
|
||||
),
|
||||
width: Math.min(image.getSize().width, Math.round((geometry.window.width + pad * 2) * shotScale)),
|
||||
height: Math.min(image.getSize().height, Math.round((geometry.window.height + pad * 2) * shotScale)),
|
||||
});
|
||||
fs.writeFileSync(path.join(dir, `${label}-${String(index).padStart(2, '0')}.png`), crop.toPNG());
|
||||
lines.push(
|
||||
@@ -2087,7 +2097,8 @@ async function runIslandChecks(
|
||||
let count = 0;
|
||||
for (let y = Math.max(0, fromY); y < Math.min(collapseShotSize.height, toY); y += 2) {
|
||||
for (let x = Math.max(0, fromX); x < Math.min(collapseShotSize.width, toX); x += 2) {
|
||||
if (x >= cardBox.x && x <= cardBox.x + cardBox.w && y >= cardBox.y && y <= cardBox.y + cardBox.h) continue;
|
||||
if (x >= cardBox.x && x <= cardBox.x + cardBox.w && y >= cardBox.y && y <= cardBox.y + cardBox.h)
|
||||
continue;
|
||||
const index = (y * collapseShotSize.width + x) * 4;
|
||||
if (index + 3 >= bitmap.length) continue;
|
||||
const b = bitmap[index];
|
||||
@@ -4349,6 +4360,46 @@ export async function runSmokeTest(win: BrowserWindow): Promise<void> {
|
||||
);
|
||||
record('关于页渲染（应用信息/诊断信息/鸣谢）', Boolean(aboutPage?.ok), String(aboutPage?.detail ?? ''));
|
||||
|
||||
// 更新检查（新功能回归）：主进程直连 GitHub 取最新 Release。
|
||||
//
|
||||
// **刻意不断言"一定有新版本"**：那会把冒烟绑死在外网可达上，而教室机器常常没有外网
|
||||
// （`ok=false` 是设计内的降级结果，不是失败）。因此两种结果都算通过，验的是：
|
||||
// 结构完整、失败时有可读原因、以及缓存真的生效。
|
||||
const updateFirst = await checkForUpdates(true);
|
||||
const isVersionLike = (value: unknown): boolean => typeof value === 'string' && /^\d/.test(value);
|
||||
const updateShapeOk =
|
||||
isVersionLike(updateFirst.currentVersion) &&
|
||||
typeof updateFirst.ok === 'boolean' &&
|
||||
typeof updateFirst.hasUpdate === 'boolean' &&
|
||||
(updateFirst.ok
|
||||
? isVersionLike(updateFirst.latestVersion) &&
|
||||
Array.isArray(updateFirst.assets) &&
|
||||
/^https:\/\//.test(updateFirst.releaseUrl) &&
|
||||
updateFirst.error === null
|
||||
: typeof updateFirst.error === 'string' && updateFirst.error.length > 0);
|
||||
record(
|
||||
'更新检查返回结构正确（无外网时降级为 ok=false 且带原因）',
|
||||
updateShapeOk,
|
||||
`ok=${updateFirst.ok} 本机=${updateFirst.currentVersion} 最新=${updateFirst.latestVersion ?? '-'} ` +
|
||||
`有新版本=${updateFirst.hasUpdate} 附件=${updateFirst.assets.length}` +
|
||||
`${updateFirst.error ? ` 原因=${updateFirst.error}` : ''}`,
|
||||
);
|
||||
|
||||
// 缓存：紧接着再查一次（不传 force）应命中缓存 —— checkedAt 不变即说明没有二次请求
|
||||
const updateSecond = await checkForUpdates();
|
||||
record(
|
||||
'更新检查结果带缓存（不重复请求 GitHub）',
|
||||
updateSecond.checkedAt === updateFirst.checkedAt,
|
||||
`两次 checkedAt 相同=${updateSecond.checkedAt === updateFirst.checkedAt}`,
|
||||
);
|
||||
|
||||
// 启动自动检查在冒烟模式下必须被跳过，否则每次验证都会产生一次真实网络请求与提示条
|
||||
record(
|
||||
'冒烟模式下跳过启动自动检查（验证不依赖外网）',
|
||||
wasStartupCheckSkipped(),
|
||||
`skipped=${wasStartupCheckSkipped()}`,
|
||||
);
|
||||
|
||||
// 未读红点必须挂在"通知"图标右上方（用户反馈：原来挂在文字后面，位置不对）
|
||||
const readBadgeGeometry = async (): Promise<{
|
||||
ok: boolean;
|
||||
|
||||
@@ -0,0 +1,215 @@
|
||||
import { app, type BrowserWindow } from 'electron';
|
||||
import {
|
||||
GITHUB_RELEASES_LATEST_API,
|
||||
GITHUB_RELEASES_PAGE,
|
||||
UPDATE_CHECK_CACHE_TTL_MS,
|
||||
UPDATE_CHECK_TIMEOUT_MS,
|
||||
UPDATE_CHECK_USER_AGENT,
|
||||
isNewerVersion,
|
||||
normalizeVersion,
|
||||
type UpdateAssetDto,
|
||||
type UpdateInfo,
|
||||
} from '@classhelper/shared';
|
||||
import { getConfig, saveConfig } from './config.js';
|
||||
import { logger } from './logger.js';
|
||||
|
||||
/**
|
||||
* 更新检查（桌面客户端）。
|
||||
*
|
||||
* **为什么在主进程做**：渲染进程通过 preload 能拿到 `getConfig()` 的明文 token（代表全班身份），
|
||||
* 它的 CSP 与导航防线是整个安全模型里最要紧的一层；让它额外去连一个外部域名、
|
||||
* 解析外部 JSON，等于把"外部数据"请进最有价值的那一侧。主进程本来就在做网络与文件，
|
||||
* 放这里也顺带复用 Node 的 fetch（无需额外依赖）。
|
||||
*
|
||||
* 与 Web 管理端的差别：Web 端受服务端 CSP 的 `connect-src` 限制，只能走 `/api/update/check` 转发；
|
||||
* 客户端没有这个限制，按用户选择**直连 GitHub**。两边归一化出的 `UpdateInfo` 结构一致。
|
||||
*/
|
||||
|
||||
/** 主进程 → 渲染进程：发现新版本（渲染进程据此弹一次性提示） */
|
||||
export const UPDATE_AVAILABLE_CHANNEL = 'classhelper:update:available';
|
||||
|
||||
/** 启动后多久自动查一次：等窗口与登录流程就绪，也不跟首屏请求抢带宽 */
|
||||
const STARTUP_DELAY_MS = 5_000;
|
||||
|
||||
interface GithubReleasePayload {
|
||||
tag_name?: unknown;
|
||||
name?: unknown;
|
||||
published_at?: unknown;
|
||||
body?: unknown;
|
||||
html_url?: unknown;
|
||||
assets?: unknown;
|
||||
}
|
||||
|
||||
let cache: { at: number; info: UpdateInfo } | null = null;
|
||||
let startupTimer: ReturnType<typeof setTimeout> | null = null;
|
||||
/** 冒烟断言用：启动自动检查是否被跳过（冒烟模式下必须是 true） */
|
||||
let startupCheckSkipped = false;
|
||||
|
||||
/** 失败的统一出口：结构完整，界面不必做 null 判断 */
|
||||
function failure(error: string): UpdateInfo {
|
||||
return {
|
||||
ok: false,
|
||||
error,
|
||||
currentVersion: app.getVersion(),
|
||||
latestVersion: null,
|
||||
hasUpdate: false,
|
||||
releaseUrl: GITHUB_RELEASES_PAGE,
|
||||
releaseName: null,
|
||||
publishedAt: null,
|
||||
notes: null,
|
||||
assets: [],
|
||||
checkedAt: new Date().toISOString(),
|
||||
};
|
||||
}
|
||||
|
||||
function toAssets(raw: unknown): UpdateAssetDto[] {
|
||||
if (!Array.isArray(raw)) return [];
|
||||
return raw
|
||||
.map((item) => item as { name?: unknown; browser_download_url?: unknown; size?: unknown })
|
||||
.filter(
|
||||
(item): item is { name: string; browser_download_url: string; size?: unknown } =>
|
||||
typeof item.name === 'string' && typeof item.browser_download_url === 'string',
|
||||
)
|
||||
.map((item) => ({
|
||||
name: item.name,
|
||||
downloadUrl: item.browser_download_url,
|
||||
size: typeof item.size === 'number' && Number.isFinite(item.size) ? item.size : 0,
|
||||
}));
|
||||
}
|
||||
|
||||
function toInfo(payload: GithubReleasePayload, currentVersion: string): UpdateInfo {
|
||||
const latestVersion = normalizeVersion(typeof payload.tag_name === 'string' ? payload.tag_name : '');
|
||||
if (!latestVersion) {
|
||||
logger.warn('更新检查：GitHub 返回的 Release 里没有可识别的 tag_name');
|
||||
return failure('GitHub 返回的版本号无法识别');
|
||||
}
|
||||
|
||||
return {
|
||||
ok: true,
|
||||
error: null,
|
||||
currentVersion,
|
||||
latestVersion,
|
||||
hasUpdate: isNewerVersion(currentVersion, latestVersion),
|
||||
releaseUrl:
|
||||
typeof payload.html_url === 'string' && payload.html_url ? payload.html_url : GITHUB_RELEASES_PAGE,
|
||||
releaseName: typeof payload.name === 'string' ? payload.name : null,
|
||||
publishedAt: typeof payload.published_at === 'string' ? payload.published_at : null,
|
||||
notes: typeof payload.body === 'string' ? payload.body : null,
|
||||
assets: toAssets(payload.assets),
|
||||
checkedAt: new Date().toISOString(),
|
||||
};
|
||||
}
|
||||
|
||||
/** 把各种失败翻译成一句用户能看懂的话（教室里最常见的就是"这台机器没有外网"） */
|
||||
function describeFailure(error: unknown): string {
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
if (error instanceof Error && error.name === 'TimeoutError') {
|
||||
return `连接 GitHub 超时（${UPDATE_CHECK_TIMEOUT_MS / 1000} 秒），本机可能没有外网`;
|
||||
}
|
||||
if (/fetch failed|ENOTFOUND|ECONNREFUSED|EAI_AGAIN|ETIMEDOUT|certificate|net::/i.test(message)) {
|
||||
return '无法连接 GitHub，本机可能没有外网';
|
||||
}
|
||||
return `检查更新失败：${message}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* 检查 GitHub 上有没有比本机新的版本（结果带缓存）。
|
||||
*
|
||||
* 缓存的意义：匿名调用 GitHub API 的限流是 60 次/小时/IP，而「关于」页的按钮可以随便点。
|
||||
* 失败结果同样进缓存 —— 否则离线时每点一次都要白等一个超时。
|
||||
*/
|
||||
export async function checkForUpdates(force = false): Promise<UpdateInfo> {
|
||||
const currentVersion = app.getVersion();
|
||||
const now = Date.now();
|
||||
if (!force && cache && now - cache.at < UPDATE_CHECK_CACHE_TTL_MS) {
|
||||
return cache.info;
|
||||
}
|
||||
|
||||
let info: UpdateInfo;
|
||||
try {
|
||||
const response = await fetch(GITHUB_RELEASES_LATEST_API, {
|
||||
headers: {
|
||||
// GitHub API 强制要求 User-Agent，不带会直接 403
|
||||
'User-Agent': UPDATE_CHECK_USER_AGENT,
|
||||
Accept: 'application/vnd.github+json',
|
||||
},
|
||||
signal: AbortSignal.timeout(UPDATE_CHECK_TIMEOUT_MS),
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
info =
|
||||
response.status === 403 || response.status === 429
|
||||
? failure('GitHub 暂时拒绝了请求（匿名查询次数过多），请过一会儿再试')
|
||||
: failure(`GitHub 返回 HTTP ${response.status}`);
|
||||
logger.warn(`更新检查失败：HTTP ${response.status}（本机版本 ${currentVersion}）`);
|
||||
} else {
|
||||
info = toInfo((await response.json()) as GithubReleasePayload, currentVersion);
|
||||
logger.info(
|
||||
`更新检查：本机 ${currentVersion} / 最新 ${info.latestVersion ?? '-'}` +
|
||||
`${info.hasUpdate ? '（有新版本）' : '（已是最新）'}`,
|
||||
);
|
||||
}
|
||||
} catch (error) {
|
||||
info = failure(describeFailure(error));
|
||||
logger.warn(`更新检查失败：${info.error}（本机版本 ${currentVersion}）`);
|
||||
}
|
||||
|
||||
cache = { at: now, info };
|
||||
return info;
|
||||
}
|
||||
|
||||
/** 「知道了 / 忽略此版本」：记到配置里，同一个版本不再重复弹提示 */
|
||||
export function ignoreUpdateVersion(version: string): void {
|
||||
const normalized = normalizeVersion(version);
|
||||
if (!normalized) return;
|
||||
saveConfig({ ignoredUpdateVersion: normalized });
|
||||
logger.info(`已忽略版本 ${normalized} 的更新提示`);
|
||||
}
|
||||
|
||||
/** 该版本是否已被用户忽略 */
|
||||
export function isUpdateIgnored(version: string): boolean {
|
||||
return normalizeVersion(getConfig().ignoredUpdateVersion) === normalizeVersion(version);
|
||||
}
|
||||
|
||||
/**
|
||||
* 启动后的自动检查：延迟 `STARTUP_DELAY_MS` 查一次，有新版本（且没被忽略）就通知渲染进程弹提示。
|
||||
*
|
||||
* **冒烟模式直接跳过**：自动化验证不该每次都发真实网络请求（既抖动又依赖外网），
|
||||
* 而且凭空多出来的提示条会撞坏既有 UI 断言。冒烟用例改为直接调 IPC 验证返回结构。
|
||||
*/
|
||||
export function scheduleStartupUpdateCheck(getWindow: () => BrowserWindow | null): void {
|
||||
if (process.env.ELECTRON_SMOKE_TEST === '1') {
|
||||
startupCheckSkipped = true;
|
||||
logger.info('更新检查：冒烟模式下跳过启动自动检查');
|
||||
return;
|
||||
}
|
||||
if (startupTimer) clearTimeout(startupTimer);
|
||||
|
||||
startupTimer = setTimeout(() => {
|
||||
startupTimer = null;
|
||||
void (async () => {
|
||||
try {
|
||||
const info = await checkForUpdates();
|
||||
if (!info.ok || !info.hasUpdate || !info.latestVersion) return;
|
||||
if (isUpdateIgnored(info.latestVersion)) {
|
||||
logger.info(`更新检查：${info.latestVersion} 已被用户忽略，本次不提示`);
|
||||
return;
|
||||
}
|
||||
const win = getWindow();
|
||||
if (!win || win.isDestroyed()) return;
|
||||
win.webContents.send(UPDATE_AVAILABLE_CHANNEL, info);
|
||||
logger.info(`更新检查：已提示新版本 ${info.latestVersion}`);
|
||||
} catch (error) {
|
||||
// 自动检查失败不该打扰用户（手动检查才需要看到原因）
|
||||
logger.warn(`启动自动检查更新失败：${error instanceof Error ? error.message : error}`);
|
||||
}
|
||||
})();
|
||||
}, STARTUP_DELAY_MS);
|
||||
// 不阻止进程退出：这个定时器只是"顺便查一下"
|
||||
startupTimer.unref?.();
|
||||
}
|
||||
|
||||
/** 冒烟断言用：启动自动检查是否被跳过（冒烟模式下应为 true —— 否则每次验证都会发真实网络请求） */
|
||||
export function wasStartupCheckSkipped(): boolean {
|
||||
return startupCheckSkipped;
|
||||
}
|
||||
@@ -1,5 +1,6 @@
|
||||
import { contextBridge, ipcRenderer } from 'electron';
|
||||
import { IPC_CHANNELS } from '../main/ipc.js';
|
||||
import { UPDATE_AVAILABLE_CHANNEL } from '../main/update.js';
|
||||
import type {
|
||||
DesktopAppInfo,
|
||||
DesktopBridge,
|
||||
@@ -7,7 +8,7 @@ import type {
|
||||
IslandClassStatePayload,
|
||||
IslandPushContext,
|
||||
} from '../types/desktop.js';
|
||||
import type { IslandNotification } from '@classhelper/shared';
|
||||
import type { IslandNotification, UpdateInfo } from '@classhelper/shared';
|
||||
|
||||
/**
|
||||
* 预加载脚本：在开启了 contextIsolation + sandbox 的前提下，
|
||||
@@ -37,6 +38,15 @@ const bridge: DesktopBridge = {
|
||||
getAppInfo: (): Promise<DesktopAppInfo> => ipcRenderer.invoke(IPC_CHANNELS.appInfo),
|
||||
openExternal: (url: string): Promise<boolean> => ipcRenderer.invoke(IPC_CHANNELS.openExternal, url),
|
||||
|
||||
/* 更新检查（主进程直连 GitHub，见 main/update.ts） */
|
||||
checkForUpdates: (force = false): Promise<UpdateInfo> =>
|
||||
ipcRenderer.invoke(IPC_CHANNELS.updateCheck, force),
|
||||
ignoreUpdateVersion: (version: string): Promise<void> =>
|
||||
ipcRenderer.invoke(IPC_CHANNELS.updateIgnore, version),
|
||||
onUpdateAvailable: (handler: (info: UpdateInfo) => void): void => {
|
||||
ipcRenderer.on(UPDATE_AVAILABLE_CHANNEL, (_event, info: UpdateInfo) => handler(info));
|
||||
},
|
||||
|
||||
islandPush: (payload: { notification: IslandNotification; context?: IslandPushContext }): void => {
|
||||
ipcRenderer.send('island:push', payload);
|
||||
},
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
<script setup lang="ts">
|
||||
import { onMounted, onUnmounted, ref } from 'vue';
|
||||
import { h, onMounted, onUnmounted, ref } from 'vue';
|
||||
import { useRouter } from 'vue-router';
|
||||
import { ElButton, ElNotification } from 'element-plus';
|
||||
import type { UpdateInfo } from '@classhelper/shared';
|
||||
import {
|
||||
startIslandBridge,
|
||||
stopIslandBridge,
|
||||
@@ -24,6 +26,52 @@ const realtime = useRealtimeStore();
|
||||
const booting = ref(true);
|
||||
const bootText = ref('正在读取本地配置...');
|
||||
|
||||
/**
|
||||
* 启动自动检查发现新版本时的提示（主进程查出后推过来，见 main/update.ts）。
|
||||
*
|
||||
* **为什么订阅放在 App.vue**：`onUpdateAvailable` 底层是 `ipcRenderer.on`，
|
||||
* 桥接层没有对应的 off —— 挂在会随"登出 → 登录"反复挂载的 ClientLayout 里，
|
||||
* 处理器会越堆越多（与灵动岛订阅同一个坑）。App.vue 整个应用生命周期只挂载一次。
|
||||
*
|
||||
* 提示是**一次性**且可永久消音：点「忽略此版本」写进 config.json，同一版本不再提示；
|
||||
* 「关于」页里仍可随时手动检查。
|
||||
*/
|
||||
function showUpdateAvailable(info: UpdateInfo): void {
|
||||
if (!info.latestVersion) return;
|
||||
ElNotification({
|
||||
title: `发现新版本 v${info.latestVersion}`,
|
||||
type: 'info',
|
||||
// 不自动消失：这是需要用户决定的事（去下载 / 忽略），滑过去就只能靠「关于」页再想起来
|
||||
duration: 0,
|
||||
message: h('div', { style: 'line-height: 1.7' }, [
|
||||
h('p', { style: 'margin: 0 0 10px' }, `当前版本 ${info.currentVersion}，可前往下载更新。`),
|
||||
h('div', { style: 'display: flex; gap: 8px' }, [
|
||||
h(
|
||||
ElButton,
|
||||
{
|
||||
size: 'small',
|
||||
type: 'primary',
|
||||
onClick: () => {
|
||||
void window.desktop?.openExternal(info.releaseUrl);
|
||||
},
|
||||
},
|
||||
() => '前往下载',
|
||||
),
|
||||
h(
|
||||
ElButton,
|
||||
{
|
||||
size: 'small',
|
||||
onClick: () => {
|
||||
void window.desktop?.ignoreUpdateVersion(info.latestVersion ?? '');
|
||||
},
|
||||
},
|
||||
() => '忽略此版本',
|
||||
),
|
||||
]),
|
||||
]),
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* 启动流程：
|
||||
* 1) 从主进程配置恢复服务器地址与登录令牌
|
||||
@@ -59,6 +107,9 @@ onMounted(async () => {
|
||||
subscribeIslandMarkRead();
|
||||
subscribeIslandMarkAllRead();
|
||||
|
||||
// 启动自动检查发现新版本时由主进程推过来（订阅只挂一次，理由见 showUpdateAvailable）
|
||||
window.desktop?.onUpdateAvailable?.(showUpdateAvailable);
|
||||
|
||||
if (auth.isAuthenticated) await router.replace('/schedule');
|
||||
else await router.replace('/login');
|
||||
|
||||
|
||||
+105
-30
@@ -103,9 +103,14 @@ const EXPECTED_MENU: Array<{ label: string; path: string }> = [
|
||||
{ label: '通用', path: '/settings/general' },
|
||||
];
|
||||
|
||||
/** 分组标题（el-sub-menu）与应包含的子项，点击分组展开后再点子项 */
|
||||
/**
|
||||
* 一级菜单项：2026-10-05 起「学习」分组已拆掉，课表/作业/通知/成绩**直接铺在侧栏一级**。
|
||||
* 下面的结构自检会确认它们真的不在任何 `el-sub-menu` 里。
|
||||
*/
|
||||
const PRIMARY_MENU_ITEMS = ['课表', '作业', '通知', '成绩'];
|
||||
|
||||
/** 分组标题（el-sub-menu）与应包含的子项，点击分组展开后再点子项。设置组自成一类，保留分组 */
|
||||
const MENU_GROUPS: Array<{ title: string; labels: string[] }> = [
|
||||
{ title: '学习', labels: ['课表', '作业', '通知', '成绩'] },
|
||||
{ title: '设置', labels: ['通用', '外观', '灵动岛', '提醒', '账号', '关于'] },
|
||||
];
|
||||
|
||||
@@ -122,16 +127,18 @@ export async function layoutNavigationSelfTest(): Promise<SmokeCheckResult> {
|
||||
// 用 startsWith 匹配就会误报"菜单项缺失"（历史失败原因）。
|
||||
const findByLabel = (selector: string, label: string): HTMLElement | undefined =>
|
||||
(Array.from(document.querySelectorAll(selector)) as HTMLElement[]).find((element) =>
|
||||
Array.from(element.querySelectorAll('span')).some(
|
||||
(span) => (span.textContent ?? '').trim() === label,
|
||||
),
|
||||
Array.from(element.querySelectorAll('span')).some((span) => (span.textContent ?? '').trim() === label),
|
||||
);
|
||||
const findMenuItem = (label: string): HTMLElement | undefined => findByLabel('.el-menu-item', label);
|
||||
const findGroupTitle = (title: string): HTMLElement | undefined =>
|
||||
findByLabel('.el-sub-menu__title', title);
|
||||
|
||||
if (!findGroupTitle('学习') || !findGroupTitle('设置')) {
|
||||
return { ok: false, detail: '侧边栏分组未渲染（当前不在主布局或未登录）' };
|
||||
if (!findGroupTitle('设置')) {
|
||||
return { ok: false, detail: '侧边栏「设置」分组未渲染（当前不在主布局或未登录）' };
|
||||
}
|
||||
const missingPrimary = PRIMARY_MENU_ITEMS.filter((label) => !findMenuItem(label));
|
||||
if (missingPrimary.length > 0) {
|
||||
return { ok: false, detail: `侧边栏缺少一级项：${missingPrimary.join('、')}` };
|
||||
}
|
||||
|
||||
const visited: string[] = [];
|
||||
@@ -150,7 +157,13 @@ export async function layoutNavigationSelfTest(): Promise<SmokeCheckResult> {
|
||||
}
|
||||
}
|
||||
|
||||
// 分组结构自检：两个分组各自应包含全部子项
|
||||
// 结构自检：
|
||||
// ① 一级项必须**真的在一级** —— 不能还挂在某个 el-sub-menu 里（用户要求把"学习"拆掉）；
|
||||
// ② 分组各自应包含全部子项
|
||||
for (const label of PRIMARY_MENU_ITEMS) {
|
||||
const element = findMenuItem(label);
|
||||
if (element?.closest('.el-sub-menu')) failures.push(`${label}(仍挂在分组里，应在一级)`);
|
||||
}
|
||||
for (const group of MENU_GROUPS) {
|
||||
for (const label of group.labels) {
|
||||
if (!findMenuItem(label)) failures.push(`${group.title}组缺少子项 ${label}`);
|
||||
@@ -874,12 +887,8 @@ export async function onboardingSelfTest(): Promise<SmokeCheckResult> {
|
||||
// 逐页「下一步」到最后一页再点「开始使用」（按钮由 data-action 标识，不依赖文案）
|
||||
const clicks: string[] = [];
|
||||
for (let attempt = 0; attempt < 12; attempt += 1) {
|
||||
const action = document.querySelector('.onboarding-welcome [data-action="finish"]')
|
||||
? 'finish'
|
||||
: 'next';
|
||||
const button = document.querySelector<HTMLElement>(
|
||||
`.onboarding-welcome [data-action="${action}"]`,
|
||||
);
|
||||
const action = document.querySelector('.onboarding-welcome [data-action="finish"]') ? 'finish' : 'next';
|
||||
const button = document.querySelector<HTMLElement>(`.onboarding-welcome [data-action="${action}"]`);
|
||||
if (!button) break;
|
||||
clicks.push(action);
|
||||
button.click();
|
||||
@@ -957,20 +966,48 @@ export async function layoutChromeSelfTest(): Promise<SmokeCheckResult> {
|
||||
const configAfterFlip = await window.desktop?.getConfig?.();
|
||||
const themePersisted = configAfterFlip?.theme === (flippedDark ? 'dark' : 'light');
|
||||
|
||||
// 2) 侧边栏：点汉堡折叠 → collapse 态 + 宽度收窄 → 配置落盘 → 再展开还原
|
||||
// 1.5) 顶栏右侧必须水平对齐（用户反馈"深色模式没对齐"，两种主题其实都偏）。
|
||||
// Element Plus 给按钮的是 `vertical-align:middle`、给下拉容器的是 `vertical-align:top`，
|
||||
// 容器不是 flex 的话两个 inline-level 子元素会各按各的规则落位，错开几像素。
|
||||
const centerYOf = (element: Element | null | undefined): number | null => {
|
||||
if (!element) return null;
|
||||
const rect = element.getBoundingClientRect();
|
||||
return rect.height > 0 ? rect.top + rect.height / 2 : null;
|
||||
};
|
||||
const themeToggleY = centerYOf(document.querySelector('[data-test="theme-toggle"]'));
|
||||
const userChipY = centerYOf(document.querySelector('.user-chip'));
|
||||
const headerCenterDelta =
|
||||
themeToggleY !== null && userChipY !== null ? Math.abs(themeToggleY - userChipY) : null;
|
||||
const headerAligned = headerCenterDelta !== null && headerCenterDelta <= 1.5;
|
||||
|
||||
// 2) 侧边栏：点汉堡折叠 → 图标导轨态 + 宽度收窄（是动画，要等它走完）→ 配置落盘 → 再展开还原
|
||||
const asideBefore = document.querySelector<HTMLElement>('.aside.ch-nav');
|
||||
const widthBefore = asideBefore?.offsetWidth ?? 0;
|
||||
// 2.0) 折叠必须是**动画**而不是瞬切（用户要求"重写菜单的动画"）。
|
||||
// 不去抓中间帧（时序敏感），直接断言侧栏上挂着 width 的过渡 —— 确定性的。
|
||||
const asideComputed = asideBefore ? getComputedStyle(asideBefore) : null;
|
||||
const asideTransitionProperty = asideComputed?.transitionProperty ?? '';
|
||||
const asideTransitionSeconds = asideComputed ? Number.parseFloat(asideComputed.transitionDuration) : 0;
|
||||
const widthAnimated =
|
||||
asideTransitionProperty.includes('width') &&
|
||||
Number.isFinite(asideTransitionSeconds) &&
|
||||
asideTransitionSeconds > 0.05;
|
||||
if (!clickToggle('[data-test="sidebar-toggle"]')) return { ok: false, detail: '汉堡按钮点击失败' };
|
||||
const collapsed = await waitUntil(() => Boolean(document.querySelector('.el-menu--collapse')), 2500);
|
||||
const collapsed = await waitUntil(() => {
|
||||
const aside = document.querySelector<HTMLElement>('.aside.ch-nav');
|
||||
return Boolean(aside?.classList.contains('is-collapsed')) && (aside?.offsetWidth ?? 999) <= 80;
|
||||
}, 4000);
|
||||
const asideAfter = document.querySelector<HTMLElement>('.aside.ch-nav');
|
||||
const widthAfter = asideAfter?.offsetWidth ?? 0;
|
||||
const configAfterCollapse = await window.desktop?.getConfig?.();
|
||||
const collapsePersisted = configAfterCollapse?.sidebarCollapsed === true;
|
||||
|
||||
// 2.1) 折叠态的两条观感硬要求（用户反馈回归）：
|
||||
// a) 菜单里不允许残留任何**可见**的文字（Element Plus 靠宽度归零隐藏，一旦被外层样式
|
||||
// 干扰就会留"半截字"）；
|
||||
// b) 折叠后的图标必须与顶部汉堡按钮在同一竖列（中心 x 相差 ≤ 2px），否则看起来"没对齐"。
|
||||
// a) 菜单里不允许残留任何**可见**的文字。折叠实现是"文字宽度被 flex 压到 0 + overflow:hidden
|
||||
// 裁掉 + opacity 归零"（`display:none` 无法过渡，用不了），所以判据是"看得见"
|
||||
// —— 有宽度且未透明 —— 而不是"根本没参与布局"；
|
||||
// b) 折叠后的图标必须与顶部汉堡按钮在同一竖列（中心 x 相差 ≤ 2px）。
|
||||
// 分组标题里还有个绝对定位的折叠箭头，它同样带 el-icon 类但已淡出，量它没有意义，排除。
|
||||
const centerXOf = (element: Element | null | undefined): number | null => {
|
||||
if (!element) return null;
|
||||
const rect = element.getBoundingClientRect();
|
||||
@@ -983,24 +1020,48 @@ export async function layoutChromeSelfTest(): Promise<SmokeCheckResult> {
|
||||
const element = node as HTMLElement;
|
||||
if (element.classList.contains('menu-icon-slot')) continue;
|
||||
const text = (element.textContent ?? '').trim();
|
||||
if (text && element.offsetParent !== null && element.getClientRects().length > 0) {
|
||||
const rect = element.getBoundingClientRect();
|
||||
// 宽高都归零但 display 不为 none 的，正是"0 宽溢出"的残影来源
|
||||
if (rect.width < 1) leftoverText.push(`0宽:${text.slice(0, 6)}`);
|
||||
else leftoverText.push(`可见:${text.slice(0, 6)}`);
|
||||
}
|
||||
if (!text || element.getClientRects().length === 0) continue;
|
||||
const rect = element.getBoundingClientRect();
|
||||
const opacity = Number(getComputedStyle(element).opacity || '1');
|
||||
if (rect.width >= 1 && opacity > 0.05) leftoverText.push(`可见:${text.slice(0, 6)}`);
|
||||
}
|
||||
const toggleCenter = centerXOf(document.querySelector('[data-test="sidebar-toggle"]'));
|
||||
const iconCenters = Array.from(
|
||||
document.querySelectorAll('.aside .el-menu--collapse .el-sub-menu__title .el-icon'),
|
||||
document.querySelectorAll(
|
||||
'.aside.is-collapsed .menu-icon-slot .el-icon, ' +
|
||||
'.aside.is-collapsed .el-sub-menu__title > .el-icon:not([class*="icon-arrow"])',
|
||||
),
|
||||
).map((node) => centerXOf(node));
|
||||
const iconDeltas = iconCenters
|
||||
.filter((value): value is number => value !== null && toggleCenter !== null)
|
||||
.map((value) => Math.abs(value - (toggleCenter as number)));
|
||||
const iconsAligned = iconDeltas.length > 0 && Math.max(...iconDeltas) <= 2;
|
||||
|
||||
// 2.2) 导轨必须"一眼看全"：先把设置组展开（11 行图标 = 最坏情况），再断言菜单区没有纵向溢出。
|
||||
// 折叠态页脚必须把**高度**也收成 0 —— 只淡出不留高度的话，那 ~70px 会把最后两个图标
|
||||
// 顶出可视区，用户就得上下滑动（反馈原话："菜单图标无法完全显示需要上下滑动"）。
|
||||
const settingsItem = Array.from(
|
||||
document.querySelectorAll<HTMLElement>('.aside .el-sub-menu .el-menu-item'),
|
||||
).find((element) =>
|
||||
Array.from(element.querySelectorAll('span')).some((span) => (span.textContent ?? '').trim() === '通用'),
|
||||
);
|
||||
const submenuOpen = (): boolean => Boolean(settingsItem && settingsItem.offsetParent !== null);
|
||||
if (!submenuOpen()) {
|
||||
// el-sub-menu__title 的点击是 **toggle**：先判"子项是否可见"再点，
|
||||
// 盲点一次会把已展开的组收起来（AGENTS §5 第 49 条）
|
||||
document.querySelector<HTMLElement>('.aside .el-sub-menu__title')?.click();
|
||||
await waitUntil(() => submenuOpen(), 2000);
|
||||
}
|
||||
const railMenu = document.querySelector<HTMLElement>('.aside .menu');
|
||||
const railOverflowPx = railMenu ? railMenu.scrollHeight - railMenu.clientHeight : Number.NaN;
|
||||
const railFits = Number.isFinite(railOverflowPx) && railOverflowPx <= 1;
|
||||
|
||||
clickToggle('[data-test="sidebar-toggle"]');
|
||||
await waitUntil(() => !document.querySelector('.el-menu--collapse'), 2500);
|
||||
// 展开同样是动画：等宽度回到 200 再继续，否则下面量页脚时侧栏还停在中间宽度
|
||||
const expandedBack = await waitUntil(() => {
|
||||
const aside = document.querySelector<HTMLElement>('.aside.ch-nav');
|
||||
return !aside?.classList.contains('is-collapsed') && (aside?.offsetWidth ?? 0) >= 190;
|
||||
}, 4000);
|
||||
|
||||
// 3) 侧栏不溢出：菜单区自己滚动（.menu 有 min-height:0 + overflow-y:auto），
|
||||
// 底部「第 N 周 / 最近同步」始终留在窗口内 —— 窗口默认高 582px，
|
||||
@@ -1018,20 +1079,27 @@ export async function layoutChromeSelfTest(): Promise<SmokeCheckResult> {
|
||||
const ok =
|
||||
flipped &&
|
||||
themePersisted &&
|
||||
headerAligned &&
|
||||
widthAnimated &&
|
||||
collapsed &&
|
||||
collapsePersisted &&
|
||||
widthAfter < widthBefore &&
|
||||
widthAfter <= 80 &&
|
||||
expandedBack &&
|
||||
leftoverText.length === 0 &&
|
||||
iconsAligned &&
|
||||
railFits &&
|
||||
footerVisible;
|
||||
return {
|
||||
ok,
|
||||
detail:
|
||||
`主题翻转=${flipped} 落盘=${themePersisted}(${configAfterFlip?.theme ?? '-'}) ` +
|
||||
`折叠=${collapsed} 宽度=${widthBefore}→${widthAfter} 落盘=${collapsePersisted} ` +
|
||||
`顶栏对齐=${headerAligned}（中线差=${headerCenterDelta === null ? '-' : headerCenterDelta.toFixed(1)}px，要求 ≤1.5px） ` +
|
||||
`宽度过渡=${widthAnimated}(${asideTransitionProperty} ${asideTransitionSeconds}s) ` +
|
||||
`折叠=${collapsed} 宽度=${widthBefore}→${widthAfter} 展开还原=${expandedBack} 落盘=${collapsePersisted} ` +
|
||||
`文字残影=${leftoverText.length === 0 ? '无' : leftoverText.join(',')} ` +
|
||||
`图标与汉堡同列=${iconsAligned}（中心差=${iconDeltas.map((d) => d.toFixed(1)).join('/') || '-'}，要求 ≤2px） ` +
|
||||
`导轨无溢出=${railFits}（溢出=${Number.isFinite(railOverflowPx) ? `${railOverflowPx}px` : '-'}） ` +
|
||||
`侧栏底部可见=${footerVisible}`,
|
||||
};
|
||||
} catch (error) {
|
||||
@@ -1063,10 +1131,17 @@ export async function aboutPageSelfTest(): Promise<SmokeCheckResult> {
|
||||
const info = await window.desktop?.getAppInfo?.();
|
||||
const hasConfigPath = Boolean(info?.configPath);
|
||||
|
||||
// 检查更新入口（新功能回归）：关于页要有这一块，且按钮可点。
|
||||
// 这里只断言"入口存在"——是否真有新版本取决于 GitHub，不该绑进冒烟（见 main/update.ts）
|
||||
const updateBlock = document.querySelector('[data-test="update-check"]');
|
||||
const updateButton = document.querySelector('[data-test="update-check-button"]');
|
||||
|
||||
await router.push('/schedule');
|
||||
return {
|
||||
ok: hasThanks && hasDiagnostics && hasConfigPath,
|
||||
detail: `鸣谢=${hasThanks} 诊断=${hasDiagnostics} configPath=${hasConfigPath ? '有' : '无'}`,
|
||||
ok: hasThanks && hasDiagnostics && hasConfigPath && Boolean(updateBlock) && Boolean(updateButton),
|
||||
detail:
|
||||
`鸣谢=${hasThanks} 诊断=${hasDiagnostics} configPath=${hasConfigPath ? '有' : '无'} ` +
|
||||
`检查更新块=${updateBlock ? '有' : '无'} 按钮=${updateButton ? '有' : '无'}`,
|
||||
};
|
||||
} catch (error) {
|
||||
return {
|
||||
|
||||
@@ -0,0 +1,193 @@
|
||||
<script setup lang="ts">
|
||||
import { computed } from 'vue';
|
||||
|
||||
/**
|
||||
* 轻量柱状图（纯 HTML/CSS，不依赖任何图表库）。
|
||||
*
|
||||
* 为什么不用 echarts：成绩页只需要「分组柱 + 数值标签 + 坐标轴」这点东西，
|
||||
* 而 `import * as echarts from 'echarts'` 会给渲染产物加 1.1MB（客户端里最大的一块），
|
||||
* 按需引入 echarts/core 也仍有约 500KB。
|
||||
*
|
||||
* 实现要点（决定了这里为什么不需要 resize 监听）：
|
||||
* - 柱高用**百分比**：`.bar-track` 是行方向 flex 里 `flex:1` 的子项，高度确定，
|
||||
* 柱子的 `height: X%` 直接按它解析；
|
||||
* - 刻度与网格线用**零高度 flex 行 + `justify-content: space-between`**：
|
||||
* 零高度元素的中心正好落在 i/(N-1) 处，与柱状区上下边界精确对齐；
|
||||
* - 纵轴刻度列与绘图区共用同一套上下留白（数值行 18px / 标签行 30px），因此永远对齐。
|
||||
*/
|
||||
interface BarItem {
|
||||
label: string;
|
||||
value: number;
|
||||
}
|
||||
|
||||
const props = withDefaults(
|
||||
defineProps<{
|
||||
/** 每根柱：分类名 + 数值（0 ~ max） */
|
||||
items: BarItem[];
|
||||
/** 柱色 */
|
||||
color?: string;
|
||||
/** 纵轴上限 */
|
||||
max?: number;
|
||||
/** 数值单位（显示在刻度与柱顶数值后面） */
|
||||
unit?: string;
|
||||
/** 图表高度（px） */
|
||||
height?: number;
|
||||
}>(),
|
||||
{ color: '#409eff', max: 100, unit: '%', height: 300 },
|
||||
);
|
||||
|
||||
/** 纵轴刻度（自上而下）：100 / 75 / 50 / 25 / 0（按 max 换算） */
|
||||
const ticks = computed(() => [1, 0.75, 0.5, 0.25, 0].map((ratio) => Math.round(props.max * ratio)));
|
||||
|
||||
function barHeight(value: number): string {
|
||||
const ratio = props.max > 0 ? value / props.max : 0;
|
||||
return `${Math.min(1, Math.max(0, ratio)) * 100}%`;
|
||||
}
|
||||
|
||||
function formatValue(value: number): string {
|
||||
return `${Number.isInteger(value) ? value : value.toFixed(1)}${props.unit}`;
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div class="bar-chart" :style="{ height: `${height}px` }">
|
||||
<div v-if="items.length === 0" class="bar-chart-empty">暂无数据</div>
|
||||
<template v-else>
|
||||
<div class="axis-y" aria-hidden="true">
|
||||
<span v-for="tick in ticks" :key="tick" class="tick">{{ tick }}{{ unit }}</span>
|
||||
</div>
|
||||
|
||||
<div class="plot">
|
||||
<div class="gridlines" aria-hidden="true">
|
||||
<span v-for="tick in ticks" :key="tick" class="gridline"></span>
|
||||
</div>
|
||||
|
||||
<div class="bars">
|
||||
<div v-for="item in items" :key="item.label" class="bar-col">
|
||||
<div class="bar-value">{{ formatValue(item.value) }}</div>
|
||||
<div class="bar-track">
|
||||
<div
|
||||
class="bar"
|
||||
:style="{ height: barHeight(item.value), background: color }"
|
||||
:title="`${item.label}：${formatValue(item.value)}`"
|
||||
></div>
|
||||
</div>
|
||||
<div class="bar-label" :title="item.label">{{ item.label }}</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<style scoped>
|
||||
.bar-chart {
|
||||
display: grid;
|
||||
grid-template-columns: 46px 1fr;
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
.bar-chart-empty {
|
||||
grid-column: 1 / -1;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
height: 100%;
|
||||
font-size: 13px;
|
||||
color: var(--ch-text-tertiary);
|
||||
}
|
||||
|
||||
/* 纵轴刻度：上下留白与 .bars 里的数值行 / 标签行一一对应 */
|
||||
.axis-y {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
justify-content: space-between;
|
||||
padding: 18px 0 30px;
|
||||
}
|
||||
|
||||
.tick {
|
||||
height: 0;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: flex-end;
|
||||
padding-right: 8px;
|
||||
font-size: 11px;
|
||||
line-height: 1;
|
||||
white-space: nowrap;
|
||||
color: var(--ch-text-tertiary);
|
||||
}
|
||||
|
||||
.plot {
|
||||
position: relative;
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.gridlines {
|
||||
position: absolute;
|
||||
inset: 18px 0 30px;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
justify-content: space-between;
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.gridline {
|
||||
height: 0;
|
||||
border-top: 1px solid var(--ch-border);
|
||||
}
|
||||
|
||||
.bars {
|
||||
display: flex;
|
||||
align-items: stretch;
|
||||
gap: 10px;
|
||||
height: 100%;
|
||||
padding: 0 6px;
|
||||
}
|
||||
|
||||
.bar-col {
|
||||
flex: 1 1 0;
|
||||
min-width: 0;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
height: 100%;
|
||||
}
|
||||
|
||||
.bar-value {
|
||||
flex: none;
|
||||
height: 18px;
|
||||
font-size: 11px;
|
||||
line-height: 1;
|
||||
text-align: center;
|
||||
white-space: nowrap;
|
||||
overflow: hidden;
|
||||
color: var(--ch-text-secondary);
|
||||
}
|
||||
|
||||
.bar-track {
|
||||
flex: 1 1 auto;
|
||||
min-height: 0;
|
||||
display: flex;
|
||||
align-items: flex-end;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
.bar {
|
||||
width: 100%;
|
||||
max-width: 46px;
|
||||
border-radius: 4px 4px 0 0;
|
||||
transition: height 0.2s ease;
|
||||
}
|
||||
|
||||
.bar-label {
|
||||
flex: none;
|
||||
height: 30px;
|
||||
padding-top: 6px;
|
||||
font-size: 11px;
|
||||
line-height: 1.3;
|
||||
text-align: center;
|
||||
white-space: nowrap;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
color: var(--ch-text-secondary);
|
||||
}
|
||||
</style>
|
||||
@@ -0,0 +1,94 @@
|
||||
import type { App } from 'vue';
|
||||
import {
|
||||
AlarmClock,
|
||||
ArrowDown,
|
||||
ArrowLeft,
|
||||
ArrowRight,
|
||||
Bell,
|
||||
Brush,
|
||||
Calendar,
|
||||
CircleCheckFilled,
|
||||
Connection,
|
||||
Expand,
|
||||
Fold,
|
||||
FullScreen,
|
||||
Guide,
|
||||
InfoFilled,
|
||||
Key,
|
||||
Link,
|
||||
Loading,
|
||||
Lock,
|
||||
MagicStick,
|
||||
Moon,
|
||||
Notebook,
|
||||
Plus,
|
||||
Pointer,
|
||||
Refresh,
|
||||
School,
|
||||
Setting,
|
||||
Sunny,
|
||||
SwitchButton,
|
||||
Tools,
|
||||
Trophy,
|
||||
UserFilled,
|
||||
Warning,
|
||||
} from '@element-plus/icons-vue';
|
||||
|
||||
/**
|
||||
* Element Plus 图标注册表（桌面客户端渲染进程）。
|
||||
*
|
||||
* **为什么不 `import * as ElementPlusIconsVue` 全量注册**：
|
||||
* 图标库有 293 个组件（实测全量打包 minified 203KB，实际用到的只有 33 个），
|
||||
* 全量注册既把死代码打进主 chunk，又要在启动时执行 293 次 `app.component()`。
|
||||
*
|
||||
* **为什么不改成模板里逐个 import**：本项目的图标是按**字符串名**引用的
|
||||
* （`ClientLayout.vue` 的菜单配置 `icon: 'Setting'`、`OnboardingWelcome.vue` 的引导步骤、
|
||||
* 按钮上的 `:icon="'FullScreen'"`、`<component :is="item.icon">`），Element Plus 会用
|
||||
* `<component :is="'Setting'">` 去解析**全局组件名**，因此图标必须以全局组件存在。
|
||||
*
|
||||
* 新增视图时若用了新图标，`scripts/check-icons.mjs` 会在构建前报错，
|
||||
* 不会静默渲染成空白。
|
||||
*/
|
||||
const APP_ICONS = {
|
||||
AlarmClock,
|
||||
ArrowDown,
|
||||
ArrowLeft,
|
||||
ArrowRight,
|
||||
Bell,
|
||||
Brush,
|
||||
Calendar,
|
||||
CircleCheckFilled,
|
||||
Connection,
|
||||
Expand,
|
||||
Fold,
|
||||
FullScreen,
|
||||
Guide,
|
||||
InfoFilled,
|
||||
Key,
|
||||
Link,
|
||||
Loading,
|
||||
Lock,
|
||||
MagicStick,
|
||||
Moon,
|
||||
Notebook,
|
||||
Plus,
|
||||
Pointer,
|
||||
Refresh,
|
||||
School,
|
||||
Setting,
|
||||
Sunny,
|
||||
SwitchButton,
|
||||
Tools,
|
||||
Trophy,
|
||||
UserFilled,
|
||||
Warning,
|
||||
} as const;
|
||||
|
||||
/** 供 `scripts/check-icons.mjs` 读取的名单（构建期静态校验用） */
|
||||
export const APP_ICON_NAMES: readonly string[] = Object.keys(APP_ICONS).sort();
|
||||
|
||||
export function registerAppIcons(app: App): void {
|
||||
for (const [name, component] of Object.entries(APP_ICONS)) {
|
||||
app.component(name, component);
|
||||
}
|
||||
}
|
||||
@@ -19,22 +19,24 @@ const notifications = useNotificationStore();
|
||||
const ui = useUiStore();
|
||||
|
||||
/**
|
||||
* 主侧边栏：ClassIsland 式「分组 + 子菜单」。
|
||||
* - 学习：课表 / 作业 / 通知 / 成绩
|
||||
* - 设置：通用 / 外观 / 灵动岛 / 提醒 / 账号 / 关于（每个子项都是独立路由 /settings/*）
|
||||
* 顶栏左侧汉堡按钮把整栏折叠成图标栏（状态持久化在主进程配置里）。
|
||||
* 主侧边栏。
|
||||
*
|
||||
* - **一级项**：课表 / 作业 / 通知 / 成绩 —— 直接铺在侧栏上，**不再套「学习」分组**。
|
||||
* 分组标题白占一行、还得多点一次展开，折叠成图标导轨时尤其明显（用户要求拆掉）。
|
||||
* - **分组**：只剩「设置」（通用 / 外观 / 灵动岛 / 提醒 / 账号 / 关于，各自是独立路由）。
|
||||
* 6 个子项平铺太长，保留分组与"默认只展开当前路由所在分组"。折叠后是图标导轨，
|
||||
* 分组子项与一级项一样以图标列出（见 styles/index.css 的折叠态规则）。
|
||||
*
|
||||
* 顶栏左侧汉堡按钮把整栏收成图标导轨（状态持久化在主进程配置里）。
|
||||
*/
|
||||
const primaryItems = [
|
||||
{ path: '/schedule', title: '课表', icon: 'Calendar' },
|
||||
{ path: '/homeworks', title: '作业', icon: 'Notebook' },
|
||||
{ path: '/notifications', title: '通知', icon: 'Bell' },
|
||||
{ path: '/grades', title: '成绩', icon: 'Trophy' },
|
||||
];
|
||||
|
||||
const menuGroups = [
|
||||
{
|
||||
title: '学习',
|
||||
icon: 'Reading',
|
||||
items: [
|
||||
{ path: '/schedule', title: '课表', icon: 'Calendar' },
|
||||
{ path: '/homeworks', title: '作业', icon: 'Notebook' },
|
||||
{ path: '/notifications', title: '通知', icon: 'Bell' },
|
||||
{ path: '/grades', title: '成绩', icon: 'Trophy' },
|
||||
],
|
||||
},
|
||||
{
|
||||
title: '设置',
|
||||
icon: 'Setting',
|
||||
@@ -60,19 +62,19 @@ const activeMenu = computed(() => route.path);
|
||||
/** 当前路由所属的分组标题（用于"只默认展开所在分组"，与 ClassIsland 一致） */
|
||||
const activeGroupTitle = computed(() => {
|
||||
const group = menuGroups.find((item) => item.items.some((entry) => route.path === entry.path));
|
||||
return group?.title ?? '学习';
|
||||
// 落在**一级项**（课表/作业/通知/成绩）上没有所属分组 —— 返回 null，别拿某个组的名字顶上去
|
||||
return group?.title ?? null;
|
||||
});
|
||||
|
||||
/**
|
||||
* 分组展开控制：默认只展开**当前路由所在的分组**。
|
||||
* 分组展开控制：默认只展开**当前路由所在的分组**（一级项不属于任何分组，此时一个都不展开）。
|
||||
*
|
||||
* 窗口默认高度与 ClassIsland 对齐（582px），两组全展开（10 个子项 + 2 个分组标题）
|
||||
* 会超出可视高度、把底部的「账号 / 关于」挤出屏幕；只展开当前组既符合 ClassIsland 的
|
||||
* 观感（它也只展开当前组），又让小窗口下的侧栏始终完整可见。
|
||||
* 用户手动展开其它分组不受限制（可多个同时展开）。
|
||||
* 窗口默认高度与 ClassIsland 对齐（582px），设置组 6 个子项展开后会超出可视高度、
|
||||
* 把底部的「账号 / 关于」挤出屏幕；只展开当前组既符合 ClassIsland 的观感（它也只展开当前组），
|
||||
* 又让小窗口下的侧栏始终完整可见。用户手动展开其它分组不受限制（可多个同时展开）。
|
||||
*/
|
||||
const menuRef = ref<MenuInstance>();
|
||||
const openedGroups = ref<string[]>([activeGroupTitle.value]);
|
||||
const openedGroups = ref<string[]>(activeGroupTitle.value ? [activeGroupTitle.value] : []);
|
||||
|
||||
watch(
|
||||
() => route.path,
|
||||
@@ -166,7 +168,11 @@ onUnmounted(() => {
|
||||
|
||||
<template>
|
||||
<el-container class="layout">
|
||||
<el-aside :width="ui.sidebarCollapsed ? '64px' : '200px'" class="aside ch-nav">
|
||||
<el-aside
|
||||
:width="ui.sidebarCollapsed ? '64px' : '200px'"
|
||||
class="aside ch-nav"
|
||||
:class="{ 'is-collapsed': ui.sidebarCollapsed }"
|
||||
>
|
||||
<div class="brand">
|
||||
<button
|
||||
type="button"
|
||||
@@ -178,22 +184,35 @@ onUnmounted(() => {
|
||||
>
|
||||
<el-icon :size="16"><Expand v-if="ui.sidebarCollapsed" /><Fold v-else /></el-icon>
|
||||
</button>
|
||||
<template v-if="!ui.sidebarCollapsed">
|
||||
<span class="brand-logo">
|
||||
<el-icon :size="16"><School /></el-icon>
|
||||
</span>
|
||||
<span class="brand-text">班级小助手</span>
|
||||
</template>
|
||||
<!-- 品牌区在折叠时**不是 v-if 删掉**，而是靠 CSS 收宽度 + 淡出：
|
||||
v-if 会在动画中途把节点直接摘掉，看上去是"啪"地一跳；收放要连续就得让它们一直在。 -->
|
||||
<span class="brand-logo">
|
||||
<el-icon :size="16"><School /></el-icon>
|
||||
</span>
|
||||
<span class="brand-text">班级小助手</span>
|
||||
</div>
|
||||
<el-menu
|
||||
ref="menuRef"
|
||||
:default-active="activeMenu"
|
||||
:default-openeds="openedGroups"
|
||||
:collapse="ui.sidebarCollapsed"
|
||||
:collapse-width="64"
|
||||
class="menu"
|
||||
@select="handleMenuSelect"
|
||||
>
|
||||
<!-- 一级项：直接铺在侧栏上（不再套「学习」分组）。
|
||||
下面 el-sub-menu 里的菜单项与本段是同一套标记（图标槽 + 未读红点 + 标题），
|
||||
改动时两处要一起改。 -->
|
||||
<el-menu-item v-for="item in primaryItems" :key="item.path" :index="item.path">
|
||||
<span class="menu-icon-slot">
|
||||
<el-icon><component :is="item.icon" /></el-icon>
|
||||
<el-badge
|
||||
v-if="showBadge(item.path)"
|
||||
:value="notifications.unreadCount"
|
||||
:max="99"
|
||||
class="menu-badge"
|
||||
/>
|
||||
</span>
|
||||
<span>{{ item.title }}</span>
|
||||
</el-menu-item>
|
||||
<el-sub-menu v-for="group in menuGroups" :key="group.title" :index="group.title">
|
||||
<template #title>
|
||||
<el-icon><component :is="group.icon" /></el-icon>
|
||||
@@ -203,13 +222,19 @@ onUnmounted(() => {
|
||||
<!-- 未读红点挂在图标右上角（之前挂在文字后面，位置不对） -->
|
||||
<span class="menu-icon-slot">
|
||||
<el-icon><component :is="item.icon" /></el-icon>
|
||||
<el-badge v-if="showBadge(item.path)" :value="notifications.unreadCount" :max="99" class="menu-badge" />
|
||||
<el-badge
|
||||
v-if="showBadge(item.path)"
|
||||
:value="notifications.unreadCount"
|
||||
:max="99"
|
||||
class="menu-badge"
|
||||
/>
|
||||
</span>
|
||||
<span>{{ item.title }}</span>
|
||||
</el-menu-item>
|
||||
</el-sub-menu>
|
||||
</el-menu>
|
||||
<div v-if="!ui.sidebarCollapsed" class="aside-footer">
|
||||
<!-- 同上：折叠时不删节点，只淡出并收掉内边距 -->
|
||||
<div class="aside-footer">
|
||||
<div class="aside-meta">第 {{ appStore.currentWeek }} 周</div>
|
||||
<div class="aside-meta">最近同步：{{ appStore.lastSyncText }}</div>
|
||||
</div>
|
||||
@@ -285,6 +310,11 @@ onUnmounted(() => {
|
||||
.aside {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
/* 展开/收回动画：宽度来自 el-aside 的内联 --el-aside-width，这里只负责过渡。
|
||||
overflow:hidden 是必需的 —— 收窄过程中文字要被栏边裁掉，不能溢出到主区域；
|
||||
菜单自己的滚动由内部的 .menu（flex:1 + min-height:0 + overflow-y:auto）负责。 */
|
||||
overflow: hidden;
|
||||
transition: width var(--nav-dur) var(--nav-ease);
|
||||
}
|
||||
|
||||
.brand {
|
||||
@@ -296,6 +326,9 @@ onUnmounted(() => {
|
||||
font-weight: 600;
|
||||
font-size: 14px;
|
||||
color: var(--ch-text);
|
||||
transition:
|
||||
padding-left var(--nav-dur) var(--nav-ease),
|
||||
gap var(--nav-dur) var(--nav-ease);
|
||||
}
|
||||
|
||||
/* 汉堡按钮：折叠/展开整个侧边栏（状态持久化） */
|
||||
@@ -318,10 +351,14 @@ onUnmounted(() => {
|
||||
background: var(--ch-hover-soft);
|
||||
}
|
||||
|
||||
/* 折叠态：侧栏只剩 64px，汉堡按钮居中 */
|
||||
.aside.ch-nav:has(.el-menu--collapse) .brand {
|
||||
justify-content: center;
|
||||
padding: 0;
|
||||
/* 折叠态：侧栏只剩 64px，汉堡按钮水平居中。
|
||||
用**位移 padding-left** 而不是 `justify-content: center` —— 后者不可过渡，会在动画中途"跳"一下。
|
||||
汉堡宽 28px，padding-left 18px ⇒ 中心 = 18 + 14 = 32px，正好是 64/2，与折叠后的图标导轨同列
|
||||
（冒烟断言中心差 ≤ 2px）。
|
||||
这里刻意用**自己的类名**（`.is-collapsed`）而不是 `:has(.el-menu--collapse)`：
|
||||
`:has()` 的失效会让 Chromium 标记整棵文档树重新计算样式。 */
|
||||
.aside.ch-nav.is-collapsed .brand {
|
||||
padding-left: 18px;
|
||||
}
|
||||
|
||||
/* Fluent 品牌标：强调色圆角方块 + 白色图标 */
|
||||
@@ -331,13 +368,56 @@ onUnmounted(() => {
|
||||
justify-content: center;
|
||||
width: 26px;
|
||||
height: 26px;
|
||||
flex: 0 0 auto;
|
||||
border-radius: 6px;
|
||||
color: #fff;
|
||||
background: linear-gradient(135deg, var(--ch-accent) 0%, #4d94d1 100%);
|
||||
overflow: hidden;
|
||||
transition:
|
||||
width var(--nav-dur) var(--nav-ease),
|
||||
opacity calc(var(--nav-dur) * 0.6) var(--nav-ease);
|
||||
}
|
||||
|
||||
/*
|
||||
* 品牌文字 / 菜单文字在折叠时**不靠 max-width 归零**（那要么写死一个魔法数字，要么
|
||||
* `none → 0` 根本不可过渡），而是：
|
||||
* - `min-width: 0` 让这个 flex 子项能被压缩（默认的 `min-width: auto` 会撑住内容宽度）；
|
||||
* - 宽度自然跟着栏宽收缩，多出来的字被 `overflow: hidden` 裁掉；
|
||||
* - 再叠一层 opacity 淡出，避免在中间帧里留下"半截字"。
|
||||
* 于是文字宽度是**跟着侧栏宽度连续变化**的，不需要给它单独设动画终点。
|
||||
*/
|
||||
.brand-text {
|
||||
min-width: 0;
|
||||
overflow: hidden;
|
||||
white-space: nowrap;
|
||||
letter-spacing: 0.2px;
|
||||
transition: opacity calc(var(--nav-dur) * 0.6) var(--nav-ease);
|
||||
}
|
||||
|
||||
/* 折叠：品牌区收成 0 宽并淡出（不是删节点，理由见模板上的注释） */
|
||||
.aside.ch-nav.is-collapsed .brand {
|
||||
gap: 0;
|
||||
}
|
||||
|
||||
/*
|
||||
* 图标导轨里**不显示滚动条**：所有图标应当一眼看全（用户要求"不要用滚轮、删掉滚动条"）。
|
||||
* 导轨之所以放得下，靠的是页脚在折叠态把高度也收成 0（见 .is-collapsed .aside-footer）——
|
||||
* 不再有那 ~70px 的留白，11 行图标（462px）在 540px 的最小窗口里也够。
|
||||
* 这里只隐藏滚动条本身，`overflow-y: auto` 保留：窗口被拉到极矮时还能滚，不至于把图标直接裁掉。
|
||||
* 展开态**不隐藏** —— 那一栏确实会超（设置组展开时约 606px > 582px），
|
||||
* 滚动条是"下面还有内容"的唯一提示，不能拿掉。
|
||||
*/
|
||||
.aside.ch-nav.is-collapsed .menu {
|
||||
scrollbar-width: none;
|
||||
}
|
||||
|
||||
.aside.ch-nav.is-collapsed .brand-logo {
|
||||
width: 0;
|
||||
opacity: 0;
|
||||
}
|
||||
|
||||
.aside.ch-nav.is-collapsed .brand-text {
|
||||
opacity: 0;
|
||||
}
|
||||
|
||||
.menu {
|
||||
@@ -393,6 +473,30 @@ onUnmounted(() => {
|
||||
.aside-footer {
|
||||
padding: 10px 16px 14px;
|
||||
border-top: 1px solid var(--ch-divider);
|
||||
overflow: hidden;
|
||||
/* max-height 是给折叠动画用的终点：`* { box-sizing: border-box }`，展开态给一个略高于
|
||||
内容（约 70px）的值，折叠时归零 —— 导轨里**一个像素都不给页脚留**。
|
||||
不这么做的话，文字淡出后仍占着 ~70px，10 个图标在 540px 的最小窗口里就放不下、被迫滚动
|
||||
（用户反馈："图标无法完全显示、需要上下滑动、滚动条碍眼"）。 */
|
||||
max-height: 96px;
|
||||
transition:
|
||||
opacity calc(var(--nav-dur) * 0.7) var(--nav-ease),
|
||||
padding var(--nav-dur) var(--nav-ease),
|
||||
max-height var(--nav-dur) var(--nav-ease),
|
||||
border-top-color var(--nav-dur) var(--nav-ease);
|
||||
}
|
||||
|
||||
/* 折叠：页脚淡出、内边距与高度一起收到 0，分隔线也透明掉。
|
||||
`min-height: 0` 是必需的：flex 子项默认 `min-height: auto`（= 内容高度），
|
||||
而 CSS 里 min-height 优先于 max-height —— 不显式归零的话 max-height:0 根本压不下去。 */
|
||||
.aside.ch-nav.is-collapsed .aside-footer {
|
||||
opacity: 0;
|
||||
padding-top: 0;
|
||||
padding-bottom: 0;
|
||||
max-height: 0;
|
||||
min-height: 0;
|
||||
border-top-color: transparent;
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.aside-meta {
|
||||
@@ -425,6 +529,17 @@ onUnmounted(() => {
|
||||
color: var(--ch-text-tertiary);
|
||||
}
|
||||
|
||||
.header-right {
|
||||
/* 必须是 flex：Element Plus 的按钮是 `vertical-align: middle`、下拉容器是 `vertical-align: top`，
|
||||
放在普通 block 容器里两个 inline-level 子元素会按各自的垂直对齐规则落位，主题切换按钮与
|
||||
用户名牌就会错开几像素（用户反馈的"深色模式没对齐"，其实两种主题下都偏，只是深色下更显眼）。
|
||||
与 Web 管理端 AdminLayout 的同名容器保持同一套写法。 */
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
flex: 0 0 auto;
|
||||
}
|
||||
|
||||
.user-chip {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
@@ -441,7 +556,7 @@ onUnmounted(() => {
|
||||
}
|
||||
|
||||
.theme-toggle {
|
||||
margin-right: 2px;
|
||||
/* 与用户名牌的间距由 .header-right 的 gap 负责，这里不再自带 margin */
|
||||
color: var(--ch-text-secondary);
|
||||
}
|
||||
|
||||
|
||||
@@ -2,29 +2,34 @@ import { createApp } from 'vue';
|
||||
import { createPinia } from 'pinia';
|
||||
import ElementPlus from 'element-plus';
|
||||
import zhCn from 'element-plus/es/locale/lang/zh-cn';
|
||||
import * as ElementPlusIconsVue from '@element-plus/icons-vue';
|
||||
import 'element-plus/dist/index.css';
|
||||
// 深色主题：html.dark 下的 --el-* 变量（品牌覆盖在 styles/index.css 的 html.dark 块）
|
||||
import 'element-plus/theme-chalk/dark/css-vars.css';
|
||||
|
||||
import App from './App.vue';
|
||||
import router from './router/index.js';
|
||||
import { registerSmokeHooks, setSmokeTeacherCredentials } from './cache/self-test.js';
|
||||
import { registerAppIcons } from './icons.js';
|
||||
import './styles/index.css';
|
||||
|
||||
const app = createApp(App);
|
||||
|
||||
for (const [name, component] of Object.entries(ElementPlusIconsVue)) {
|
||||
app.component(name, component);
|
||||
}
|
||||
// 按需注册图标（见 icons.ts：只注册用到的那些，而不是全量 293 个）
|
||||
registerAppIcons(app);
|
||||
|
||||
app.use(createPinia());
|
||||
app.use(router);
|
||||
app.use(ElementPlus, { locale: zhCn });
|
||||
|
||||
// 冒烟验证模式：把缓存自检钩子暴露给主进程调用（正常运行时不存在）。
|
||||
//
|
||||
// **动态 import 是刻意的**：`cache/self-test.ts` 有 1000 多行自检代码，
|
||||
// 静态 import 会把它打进渲染进程入口 chunk，每次启动都要解析一遍。改成动态 import 后
|
||||
// Vite/Rollup 会把它切成独立 chunk，只在冒烟模式下才加载（`verify:desktop` /
|
||||
// `verify:packaged` 的那条路径）。
|
||||
//
|
||||
// 教师凭据由 preload 从环境变量透传（**不写在代码里**：渲染产物会进 app.asar 发给学生机）。
|
||||
if (window.desktop?.smokeTest) {
|
||||
const { registerSmokeHooks, setSmokeTeacherCredentials } = await import('./cache/self-test.js');
|
||||
setSmokeTeacherCredentials({
|
||||
username: window.desktop.smokeCredentials?.username ?? '',
|
||||
password: window.desktop.smokeCredentials?.password ?? '',
|
||||
|
||||
@@ -53,6 +53,16 @@
|
||||
--ch-shadow-flyout: 0 8px 16px rgba(0, 0, 0, 0.08);
|
||||
--ch-shadow-card: 0 2px 4px rgba(0, 0, 0, 0.04);
|
||||
|
||||
/*
|
||||
* 侧栏收放动画。组件（ClientLayout 的 .aside/.brand/.brand-logo/.aside-footer）
|
||||
* 与全局的菜单导轨规则（下面的 .ch-nav.is-collapsed …）共用这一份参数，
|
||||
* 改时长/缓动只改这里，两边不会漂。
|
||||
*/
|
||||
--nav-dur: 260ms;
|
||||
--nav-ease: cubic-bezier(0.4, 0, 0.2, 1);
|
||||
/* 图标与文字的间距（折叠时收到 0） */
|
||||
--nav-gap: 8px;
|
||||
|
||||
/* 兼容旧变量名 */
|
||||
--ch-sidebar: #ffffff;
|
||||
|
||||
@@ -389,56 +399,91 @@ textarea {
|
||||
background: var(--ch-accent);
|
||||
}
|
||||
|
||||
/* 折叠态：图标居中（el-menu collapse 自带收窄，这里压掉分组缩进） */
|
||||
.ch-nav .el-menu--collapse .el-menu-item,
|
||||
.ch-nav .el-menu--collapse .el-sub-menu__title {
|
||||
margin: 2px 8px;
|
||||
padding: 0 !important;
|
||||
}
|
||||
|
||||
/*
|
||||
* 折叠态：把菜单文字**彻底不渲染**，只留图标槽。
|
||||
/* ---------------------------------------------------------------- 折叠态：图标导轨
|
||||
*
|
||||
* Element Plus 自己的隐藏方式是"把 span 的宽高压成 0 + overflow"，一旦外层样式
|
||||
* （缩进、margin、transition）稍有干扰，文字就会以 0 宽溢出的形式留在画面上 ——
|
||||
* 表现为折叠后菜单里残留"半截字"。这里直接 display:none，从根上消除残影。
|
||||
* 图标槽（.menu-icon-slot）必须保留（它同时承载未读红点）。
|
||||
* 折叠**不再用** el-menu 的 `:collapse`：那会把每个分组的子项卸载进浮层（一次结构切换），
|
||||
* 并让整条菜单重排一遍 —— 既做不出连续动画，也是"点汉堡卡一下"的渲染侧来源。
|
||||
* 现在改成纯粹的 CSS 收拢：栏宽、文字宽度、图标位置全是可过渡属性，全程没有结构变化，
|
||||
* 折叠后就是一条图标导轨（分组标题与子项都以图标列出）。
|
||||
*
|
||||
* 几何（64px 栏、菜单项左右各 8px margin）：
|
||||
* 展开 一级项 padding-left 20px、二级项 40px（Element Plus 自带）→ 图标中心 40 / 60px
|
||||
* 折叠 所有项 padding-left / padding-right 都是 12px → 图标中心 8 + 12 + 12 = 32px，
|
||||
* 正好与顶部汉堡按钮的居中位置同列（冒烟断言中心差 ≤ 2px）。
|
||||
* 图标槽（.menu-icon-slot）与分组标题里的裸图标都是 Element Plus 给的 24px 宽。
|
||||
*/
|
||||
.ch-nav .el-menu--collapse .el-menu-item > span:not(.menu-icon-slot),
|
||||
.ch-nav .el-menu--collapse .el-sub-menu__title > span:not(.menu-icon-slot) {
|
||||
display: none !important;
|
||||
|
||||
/* 图标与文字的间距改由文字的 margin-left 负责：Element Plus 给图标挂了 margin-right:5px，
|
||||
那会让图标在 24px 的槽里偏左 2.5px（折叠时肉眼可见地不居中）。 */
|
||||
.ch-nav .el-menu-item [class^='el-icon'],
|
||||
.ch-nav .el-sub-menu__title > [class^='el-icon'] {
|
||||
margin-right: 0;
|
||||
}
|
||||
|
||||
/* 折叠态：图标在 64px 栏内严格水平居中，且与顶部的汉堡按钮同一竖列（中心都在 32px） */
|
||||
.ch-nav .el-menu--collapse .el-menu-item,
|
||||
.ch-nav .el-menu--collapse .el-sub-menu__title {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
.ch-nav .el-menu-item,
|
||||
.ch-nav .el-sub-menu__title {
|
||||
transition:
|
||||
padding-left var(--nav-dur) var(--nav-ease),
|
||||
padding-right var(--nav-dur) var(--nav-ease),
|
||||
border-color var(--el-transition-duration),
|
||||
background-color var(--el-transition-duration),
|
||||
color var(--el-transition-duration);
|
||||
}
|
||||
|
||||
/*
|
||||
* 折叠态点分组图标会弹出子菜单浮层 —— 它被 teleport 到 body 下，
|
||||
* 不受 .ch-nav 作用域影响，所以这些规则写在全局；不写的话深色主题下会是浅色浮层。
|
||||
* 文字：**不给它单独设动画终点**，宽度靠 flex 被压缩 —— `min-width:0` 让这个 flex 子项
|
||||
* 能被压到 0（默认的 `min-width:auto` 会撑住内容宽度），多出来的字由 `overflow:hidden` 裁掉。
|
||||
* 于是文字宽度天然跟着栏宽连续变化，不需要写什么魔法 max-width；再叠一层 opacity 淡出，
|
||||
* 避免中间帧留下"半截字"（`display:none` 没法过渡，用不了）。
|
||||
*/
|
||||
.el-menu--popup {
|
||||
background: var(--ch-layer-solid);
|
||||
border: 1px solid var(--ch-border);
|
||||
border-radius: var(--ch-radius-card);
|
||||
box-shadow: var(--ch-shadow-flyout);
|
||||
.ch-nav .el-menu-item > span:not(.menu-icon-slot),
|
||||
.ch-nav .el-sub-menu__title > span:not(.menu-icon-slot) {
|
||||
min-width: 0;
|
||||
margin-left: var(--nav-gap);
|
||||
overflow: hidden;
|
||||
white-space: nowrap;
|
||||
transition:
|
||||
margin-left var(--nav-dur) var(--nav-ease),
|
||||
opacity calc(var(--nav-dur) * 0.6) var(--nav-ease);
|
||||
}
|
||||
|
||||
.el-menu--popup .el-menu-item {
|
||||
color: var(--ch-text);
|
||||
/* 分组标题右侧的折叠箭头：导轨里没有它的位置 */
|
||||
.ch-nav .el-sub-menu__icon-arrow {
|
||||
transition: opacity calc(var(--nav-dur) * 0.5) var(--nav-ease);
|
||||
}
|
||||
|
||||
.el-menu--popup .el-menu-item:hover {
|
||||
background: var(--ch-hover-soft);
|
||||
.ch-nav.is-collapsed .el-menu-item > span:not(.menu-icon-slot),
|
||||
.ch-nav.is-collapsed .el-sub-menu__title > span:not(.menu-icon-slot) {
|
||||
margin-left: 0;
|
||||
opacity: 0;
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.el-menu--popup .el-menu-item.is-active {
|
||||
background: var(--ch-accent-soft);
|
||||
color: var(--ch-text);
|
||||
.ch-nav.is-collapsed .el-sub-menu__icon-arrow {
|
||||
opacity: 0;
|
||||
}
|
||||
|
||||
/*
|
||||
* 折叠后的内边距。
|
||||
*
|
||||
* 这三条选择器形状都是**照抄 Element Plus 的**，不是冗余 —— 它按层级用三个不同的选择器算缩进
|
||||
* （一级项 20px、分组标题 20px、分组内子项 40px），特异度分别是 0-4-0 / 0-4-0 / 0-5-0：
|
||||
* `.el-menu--vertical:not(.el-menu--collapse):not(.el-menu--popup-container) .el-menu-item`
|
||||
* `.el-menu--vertical:not(.el-menu--collapse):not(.el-menu--popup-container) .el-sub-menu__title`
|
||||
* `.el-menu--vertical:not(.el-menu--collapse):not(.el-menu--popup-container) .el-sub-menu .el-menu-item`
|
||||
* 写成 `.ch-nav.is-collapsed .el-sub-menu__title` 这种（0-3-0）压不住任何一条 —— 实测踩过两次：
|
||||
* 第一版漏了分组标题（偏 8.0px），把「学习」拆成一级项后又漏了一级项（同样偏 8.0px）。
|
||||
* 下面两条（0-5-0 / 0-6-0）把它们全覆盖，且不用 !important。
|
||||
*/
|
||||
.ch-nav.is-collapsed .el-menu--vertical:not(.el-menu--collapse) .el-menu-item,
|
||||
.ch-nav.is-collapsed .el-menu--vertical:not(.el-menu--collapse) .el-sub-menu__title {
|
||||
padding-left: 12px;
|
||||
padding-right: 12px;
|
||||
}
|
||||
|
||||
.ch-nav.is-collapsed .el-menu--vertical:not(.el-menu--collapse) .el-sub-menu .el-menu-item {
|
||||
padding-left: 12px;
|
||||
padding-right: 12px;
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- 课表时间轴 */
|
||||
|
||||
@@ -1,6 +1,5 @@
|
||||
<script setup lang="ts">
|
||||
import { computed, onMounted, onUnmounted, ref } from 'vue';
|
||||
import * as echarts from 'echarts';
|
||||
import {
|
||||
SOCKET_EVENTS,
|
||||
averageOf,
|
||||
@@ -11,6 +10,7 @@ import {
|
||||
} from '@classhelper/shared';
|
||||
import { gradeApi } from '../api/index.js';
|
||||
import { fetchWithCache } from '../cache/index.js';
|
||||
import ScoreBarChart from '../components/ScoreBarChart.vue';
|
||||
import { useAppStore } from '../stores/app.js';
|
||||
import { useAuthStore } from '../stores/auth.js';
|
||||
import { useRealtimeStore } from '../stores/realtime.js';
|
||||
@@ -24,8 +24,6 @@ const loading = ref(false);
|
||||
const grades = ref<GradeDto[]>([]);
|
||||
const fromCache = ref(false);
|
||||
const updatedAt = ref<number | null>(null);
|
||||
const chartRef = ref<HTMLDivElement>();
|
||||
let chart: ReturnType<typeof echarts.init> | null = null;
|
||||
|
||||
const averagePercent = computed(() =>
|
||||
grades.value.length === 0
|
||||
@@ -53,6 +51,21 @@ const levelCounts = computed(() => {
|
||||
return levels;
|
||||
});
|
||||
|
||||
/**
|
||||
* 按考试聚合平均得分率（最近 8 次考试），交给 ScoreBarChart 渲染。
|
||||
* 这里原先调的是 `echarts.setOption(...)`；改用纯 CSS 柱状图是为了去掉
|
||||
* echarts（渲染产物里最大的一块，1.1MB）。聚合口径与之前完全一致。
|
||||
*/
|
||||
const examAverages = computed(() => {
|
||||
const byExam = new Map<string, number[]>();
|
||||
for (const item of grades.value) {
|
||||
const bucket = byExam.get(item.examName) ?? [];
|
||||
bucket.push(gradePercent(item.score, item.totalScore));
|
||||
byExam.set(item.examName, bucket);
|
||||
}
|
||||
return [...byExam.entries()].slice(-8).map(([label, percents]) => ({ label, value: averageOf(percents) }));
|
||||
});
|
||||
|
||||
async function loadGrades(): Promise<void> {
|
||||
loading.value = true;
|
||||
try {
|
||||
@@ -61,50 +74,11 @@ async function loadGrades(): Promise<void> {
|
||||
fromCache.value = result.fromCache;
|
||||
updatedAt.value = result.updatedAt;
|
||||
if (!result.fromCache) appStore.markSynced();
|
||||
renderChart();
|
||||
} finally {
|
||||
loading.value = false;
|
||||
}
|
||||
}
|
||||
|
||||
function renderChart(): void {
|
||||
if (!chartRef.value) return;
|
||||
chart ??= echarts.init(chartRef.value);
|
||||
|
||||
// 按考试聚合平均得分率（最近 8 次考试）
|
||||
const byExam = new Map<string, number[]>();
|
||||
for (const item of grades.value) {
|
||||
const bucket = byExam.get(item.examName) ?? [];
|
||||
bucket.push(gradePercent(item.score, item.totalScore));
|
||||
byExam.set(item.examName, bucket);
|
||||
}
|
||||
const exams = [...byExam.entries()].slice(-8);
|
||||
|
||||
chart.setOption({
|
||||
tooltip: { trigger: 'axis' },
|
||||
grid: { left: 44, right: 18, top: 30, bottom: 34 },
|
||||
xAxis: {
|
||||
type: 'category',
|
||||
data: exams.map(([name]) => name),
|
||||
axisLabel: { interval: 0, rotate: exams.length > 4 ? 20 : 0, fontSize: 11 },
|
||||
},
|
||||
yAxis: { type: 'value', max: 100, name: '得分率%' },
|
||||
series: [
|
||||
{
|
||||
type: 'bar',
|
||||
barMaxWidth: 46,
|
||||
itemStyle: { color: '#409eff', borderRadius: [4, 4, 0, 0] },
|
||||
label: { show: true, position: 'top', formatter: '{c}%', fontSize: 11 },
|
||||
data: exams.map(([, percents]) => averageOf(percents)),
|
||||
},
|
||||
],
|
||||
});
|
||||
}
|
||||
|
||||
function handleResize(): void {
|
||||
chart?.resize();
|
||||
}
|
||||
|
||||
function onGradeEvent(): void {
|
||||
void loadGrades();
|
||||
}
|
||||
@@ -115,15 +89,11 @@ function onRecovered(): void {
|
||||
|
||||
onMounted(async () => {
|
||||
await loadGrades();
|
||||
window.addEventListener('resize', handleResize);
|
||||
realtime.on(SOCKET_EVENTS.gradeUpdated, onGradeEvent);
|
||||
appStore.onServerRecovered(onRecovered);
|
||||
});
|
||||
|
||||
onUnmounted(() => {
|
||||
window.removeEventListener('resize', handleResize);
|
||||
chart?.dispose();
|
||||
chart = null;
|
||||
realtime.off(SOCKET_EVENTS.gradeUpdated, onGradeEvent);
|
||||
appStore.offServerRecovered(onRecovered);
|
||||
});
|
||||
@@ -172,7 +142,7 @@ onUnmounted(() => {
|
||||
<el-col :xs="24" :md="16">
|
||||
<el-card v-loading="loading" shadow="never">
|
||||
<template #header><span>各次考试平均得分率</span></template>
|
||||
<div ref="chartRef" class="chart"></div>
|
||||
<ScoreBarChart :items="examAverages" />
|
||||
</el-card>
|
||||
</el-col>
|
||||
</el-row>
|
||||
@@ -255,9 +225,4 @@ onUnmounted(() => {
|
||||
gap: 6px;
|
||||
margin-top: 8px;
|
||||
}
|
||||
|
||||
.chart {
|
||||
width: 100%;
|
||||
height: 300px;
|
||||
}
|
||||
</style>
|
||||
@@ -1,11 +1,13 @@
|
||||
<script setup lang="ts">
|
||||
import { onMounted, ref } from 'vue';
|
||||
import { ElMessage } from 'element-plus';
|
||||
import type { UpdateInfo } from '@classhelper/shared';
|
||||
import type { DesktopAppInfo } from '../../../types/desktop.js';
|
||||
import { useAppStore } from '../../stores/app.js';
|
||||
|
||||
/**
|
||||
* 关于（ClassIsland 同款折叠卡片式）：
|
||||
* 应用信息（版本/运行时/常用链接）→ 诊断信息（排查问题用）→ 鸣谢。
|
||||
* 应用信息（版本/运行时/常用链接/检查更新）→ 诊断信息（排查问题用）→ 鸣谢。
|
||||
* 所有外链走主进程 openExternal（只放行 http/https，见 main/ipc.ts 的白名单）。
|
||||
*/
|
||||
const appStore = useAppStore();
|
||||
@@ -14,6 +16,10 @@ const appInfo = ref<DesktopAppInfo | null>(null);
|
||||
/** 折叠面板默认展开第一项（应用信息），诊断信息默认收起 */
|
||||
const expandedNames = ref(['app']);
|
||||
|
||||
/** 检查更新：结果由主进程直连 GitHub 得到（见 main/update.ts） */
|
||||
const checking = ref(false);
|
||||
const updateInfo = ref<UpdateInfo | null>(null);
|
||||
|
||||
const PROJECT_URL = 'https://github.com/LoveChengke/ClassHelper';
|
||||
const ISSUES_URL = 'https://github.com/LoveChengke/ClassHelper/issues';
|
||||
|
||||
@@ -31,9 +37,34 @@ async function openExternal(url: string): Promise<void> {
|
||||
window.open(url, '_blank');
|
||||
}
|
||||
|
||||
/**
|
||||
* 检查更新。
|
||||
*
|
||||
* @param force true = 用户主动点击（绕过主进程缓存）；false = 进页面时带出启动自动检查的结果
|
||||
*/
|
||||
async function checkUpdate(force: boolean): Promise<void> {
|
||||
if (!window.desktop?.checkForUpdates) return;
|
||||
checking.value = true;
|
||||
try {
|
||||
updateInfo.value = await window.desktop.checkForUpdates(force);
|
||||
} finally {
|
||||
checking.value = false;
|
||||
}
|
||||
}
|
||||
|
||||
/** 忽略这个版本：写进配置，启动自动检查不再提示它 */
|
||||
async function ignoreVersion(): Promise<void> {
|
||||
const version = updateInfo.value?.latestVersion;
|
||||
if (!version) return;
|
||||
await window.desktop?.ignoreUpdateVersion(version);
|
||||
ElMessage.success(`已忽略 v${version} 的更新提示`);
|
||||
}
|
||||
|
||||
onMounted(async () => {
|
||||
if (!window.desktop) return;
|
||||
appInfo.value = await window.desktop.getAppInfo().catch(() => null);
|
||||
// 带出启动自动检查的结果（命中主进程缓存，不会再发一次请求）
|
||||
void checkUpdate(false);
|
||||
});
|
||||
</script>
|
||||
|
||||
@@ -54,9 +85,7 @@ onMounted(async () => {
|
||||
<el-icon><School /></el-icon>
|
||||
{{ collapseItems[0].title }}
|
||||
</span>
|
||||
<span class="about-extra">
|
||||
班级小助手 v{{ appInfo?.appVersion ?? '-' }}
|
||||
</span>
|
||||
<span class="about-extra">班级小助手 v{{ appInfo?.appVersion ?? '-' }}</span>
|
||||
</template>
|
||||
<div class="about-section">
|
||||
<p class="about-copy">
|
||||
@@ -77,6 +106,51 @@ onMounted(async () => {
|
||||
</el-descriptions-item>
|
||||
<el-descriptions-item label="平台">{{ appInfo?.platform ?? '-' }}</el-descriptions-item>
|
||||
</el-descriptions>
|
||||
|
||||
<!-- 检查更新：直连 GitHub 看最新的 Release 是不是比本机新 -->
|
||||
<div class="about-update" data-test="update-check">
|
||||
<div class="about-update-head">
|
||||
<span class="about-update-label">检查更新</span>
|
||||
<el-button
|
||||
size="small"
|
||||
:loading="checking"
|
||||
data-test="update-check-button"
|
||||
@click="checkUpdate(true)"
|
||||
>
|
||||
检查更新
|
||||
</el-button>
|
||||
</div>
|
||||
<div class="about-update-body">
|
||||
<template v-if="checking">正在检查…</template>
|
||||
<template v-else-if="!updateInfo">尚未检查</template>
|
||||
<template v-else-if="!updateInfo.ok">
|
||||
<!-- 教室机器没有外网是常态，这里只是"查不到"，不是错误 -->
|
||||
<span class="about-update-muted">{{ updateInfo.error ?? '暂时无法检查更新' }}</span>
|
||||
</template>
|
||||
<template v-else-if="updateInfo.hasUpdate">
|
||||
<el-tag size="small" type="success" effect="light">
|
||||
发现新版本 v{{ updateInfo.latestVersion }}
|
||||
</el-tag>
|
||||
<span class="about-update-muted">当前 v{{ updateInfo.currentVersion }}</span>
|
||||
<el-button
|
||||
link
|
||||
type="primary"
|
||||
size="small"
|
||||
data-test="update-download"
|
||||
@click="openExternal(updateInfo.releaseUrl)"
|
||||
>
|
||||
前往下载
|
||||
</el-button>
|
||||
<el-button link size="small" @click="ignoreVersion">忽略此版本</el-button>
|
||||
</template>
|
||||
<template v-else>
|
||||
<el-tag size="small" type="info" effect="plain">已是最新版本</el-tag>
|
||||
<span class="about-update-muted">
|
||||
v{{ updateInfo.currentVersion }} · {{ updateInfo.latestVersion }}
|
||||
</span>
|
||||
</template>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</el-collapse-item>
|
||||
|
||||
@@ -115,9 +189,18 @@ onMounted(async () => {
|
||||
</template>
|
||||
<div class="about-section">
|
||||
<ul class="about-thanks">
|
||||
<li><strong>ClassIsland</strong> —— 界面风格、设置页与「今天」时间轴的交互参考</li>
|
||||
<li><strong>WinIsland</strong> —— 灵动岛的窗口形态与弹簧动画参考</li>
|
||||
<li><strong>Vue / Element Plus / Prisma / Express / Socket.IO</strong> —— 本项目赖以构建的开源基石</li>
|
||||
<li>
|
||||
<strong>ClassIsland</strong>
|
||||
—— 界面风格、设置页与「今天」时间轴的交互参考
|
||||
</li>
|
||||
<li>
|
||||
<strong>WinIsland</strong>
|
||||
—— 灵动岛的窗口形态与弹簧动画参考
|
||||
</li>
|
||||
<li>
|
||||
<strong>Vue / Element Plus / Prisma / Express / Socket.IO</strong>
|
||||
—— 本项目赖以构建的开源基石
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</el-collapse-item>
|
||||
@@ -165,6 +248,42 @@ onMounted(async () => {
|
||||
margin-right: 4px;
|
||||
}
|
||||
|
||||
/* 检查更新：颜色一律走 --ch-* 变量（深色主题下不能写死浅色底/深色字） */
|
||||
.about-update {
|
||||
margin-top: 12px;
|
||||
padding: 10px 12px;
|
||||
border: 1px solid var(--ch-border);
|
||||
border-radius: var(--ch-radius-card);
|
||||
background: var(--ch-layer-alt);
|
||||
}
|
||||
|
||||
.about-update-head {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
gap: 8px;
|
||||
}
|
||||
|
||||
.about-update-label {
|
||||
font-size: 12.5px;
|
||||
font-weight: 600;
|
||||
color: var(--ch-text-secondary);
|
||||
}
|
||||
|
||||
.about-update-body {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
flex-wrap: wrap;
|
||||
gap: 8px;
|
||||
margin-top: 8px;
|
||||
font-size: 12.5px;
|
||||
color: var(--ch-text);
|
||||
}
|
||||
|
||||
.about-update-muted {
|
||||
color: var(--ch-text-tertiary);
|
||||
}
|
||||
|
||||
.about-thanks {
|
||||
margin: 0;
|
||||
padding-left: 18px;
|
||||
|
||||
+23
@@ -7,6 +7,7 @@ import type {
|
||||
IslandAppearance,
|
||||
IslandNotification,
|
||||
IslandState,
|
||||
UpdateInfo,
|
||||
} from '@classhelper/shared';
|
||||
|
||||
/** 作业页展示偏好（看板 / 列表，看板外观） */
|
||||
@@ -58,6 +59,13 @@ export interface DesktopStoredConfig {
|
||||
theme: 'light' | 'dark';
|
||||
/** 主侧边栏是否折叠成图标栏（可由顶栏汉堡按钮切换） */
|
||||
sidebarCollapsed: boolean;
|
||||
/**
|
||||
* 用户点过「忽略此版本」的版本号（空串 = 没忽略过）。
|
||||
*
|
||||
* 启动时的自动检查会跳过这个版本，避免每次开客户端都弹一次同样的提示；
|
||||
* 在「关于」页手动检查时仍会正常显示结果。
|
||||
*/
|
||||
ignoredUpdateVersion: string;
|
||||
}
|
||||
|
||||
export interface DesktopAppInfo {
|
||||
@@ -121,6 +129,21 @@ export interface DesktopBridge {
|
||||
getAppInfo(): Promise<DesktopAppInfo>;
|
||||
openExternal(url: string): Promise<boolean>;
|
||||
|
||||
/* 更新检查 */
|
||||
/**
|
||||
* 检查 GitHub 上有没有新版本（主进程直连，不经后端）。
|
||||
*
|
||||
* @param force true = 绕过主进程缓存（对应「关于」页里用户主动点的那次检查）
|
||||
*
|
||||
* 返回的 `ok:false` 是**正常结果**（教室机器没有外网 / GitHub 限流 / 超时），不是异常，
|
||||
* 界面按"暂时查不到更新"呈现即可。
|
||||
*/
|
||||
checkForUpdates(force?: boolean): Promise<UpdateInfo>;
|
||||
/** 忽略某个版本的更新提示（写入 config.json，启动自动检查不再提示它） */
|
||||
ignoreUpdateVersion(version: string): Promise<void>;
|
||||
/** 订阅"启动自动检查发现新版本"（仅新版本且未被忽略时触发一次） */
|
||||
onUpdateAvailable(handler: (info: UpdateInfo) => void): void;
|
||||
|
||||
/* 灵动岛 */
|
||||
/** 把一条通知投递到灵动岛（payload 必须是纯数据，说明见 saveConfig） */
|
||||
islandPush(payload: { notification: IslandNotification; context?: IslandPushContext }): void;
|
||||
|
||||
@@ -29,8 +29,10 @@ CORS_ORIGIN=*
|
||||
# bcrypt 加密强度
|
||||
BCRYPT_ROUNDS=10
|
||||
|
||||
# 教师新增学生账号时未指定密码所使用的初始密码
|
||||
|
||||
# 新建班级 / 新增教师未指定密码时使用的初始密码
|
||||
# （学生没有个人账号，因此没有 DEFAULT_STUDENT_PASSWORD —— 见 AGENTS.md §5 第 31 条）
|
||||
DEFAULT_CLASS_PASSWORD=123456
|
||||
DEFAULT_TEACHER_PASSWORD=123456
|
||||
# 学期配置：第 1 教学周的周一日期（YYYY-MM-DD），用于“当前周次”换算
|
||||
TERM_START_DATE=2026-02-23
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@classhelper/server",
|
||||
"version": "1.0.0",
|
||||
"version": "1.1.1",
|
||||
"private": true,
|
||||
"description": "班级小助手后端服务：REST API + Socket.IO 实时推送 + Prisma 数据访问",
|
||||
"type": "module",
|
||||
|
||||
@@ -4,7 +4,8 @@
|
||||
// 1) 本 schema 使用 sqlite provider（本地 MVP / 离线开发）。
|
||||
// 字段全部使用 String / Int / Float / Boolean / DateTime 等跨库通用类型，
|
||||
// 不使用 Prisma enum 与 @db.* 原生类型，因此可平移到 MySQL。
|
||||
// MySQL 版本见同目录 schema.mysql.prisma，切换步骤见 docs/mysql.md。
|
||||
// MySQL 复用这一份 schema（就地改写下面的 provider，见 `pnpm db:switch:mysql`），
|
||||
// 没有第二份 schema.mysql.prisma；切换步骤见 docs/mysql.md。
|
||||
// 2) 角色与优先级用 String 存储（'ADMIN' | 'TEACHER' | 'STUDENT'、
|
||||
// 'LOW' | 'NORMAL' | 'HIGH' | 'URGENT'），在 API 层用 zod 校验，
|
||||
// 这样 SQLite / MySQL 行为完全一致。
|
||||
|
||||
@@ -105,6 +105,34 @@ async function loginWithCandidates(username, passwords) {
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 反复「拉取待提醒 → 逐条确认」，直到该设备视角下没有积压。
|
||||
*
|
||||
* 为什么验证脚本要做这件事：`GET /integrations/classisland/pending` 是
|
||||
* 「本班全部未确认且未过期的提醒，按时间升序取前 20 条」。而 `verify:desktop` /
|
||||
* `verify:web` 等冒烟会**真的往演示班发通知**（AGENTS.md §5 第 38 条），
|
||||
* 那些条如果没被确认就会一直堆着 —— 攒够 20 条之后，本脚本刚发的提醒会被挤到窗口之外，
|
||||
* 表现为「待提醒里找不到刚发的那条」，与代码对不对完全无关（2026-10-05 实测踩过：
|
||||
* 库里积了 45 条历次冒烟残条，本脚本从 42/42 掉到 35/40）。
|
||||
*
|
||||
* 这里做的事情与真实插件重连后的行为完全一致（补弹积压并逐条确认），
|
||||
* 因此不会掩盖任何产品侧问题。可见范围也一致：只处理 `deviceId` 为空的班级广播
|
||||
* 与本设备自己的推送，别的设备的目标推送取不到、也确认不了。
|
||||
*/
|
||||
async function drainPending(deviceToken) {
|
||||
let total = 0;
|
||||
for (let round = 0; round < 20; round += 1) {
|
||||
const pending = await api('/integrations/classisland/pending', { deviceToken });
|
||||
const items = pending.payload?.data?.notifications ?? [];
|
||||
if (items.length === 0) break;
|
||||
for (const item of items) {
|
||||
await api('/integrations/classisland/ack', { method: 'POST', deviceToken, body: { id: item.id } });
|
||||
total += 1;
|
||||
}
|
||||
}
|
||||
return total;
|
||||
}
|
||||
|
||||
async function main() {
|
||||
console.log(`\n=== ClassIsland 联动验证（${BASE_URL}）===\n`);
|
||||
|
||||
@@ -182,7 +210,7 @@ async function main() {
|
||||
|
||||
// ---------------------------------------------------------------- 3. 上报（状态 + 课表 + 节次）
|
||||
const reportBody = {
|
||||
pluginVersion: '1.0.0.0',
|
||||
pluginVersion: '1.1.1.0',
|
||||
classIslandVersion: '2.1.0.0',
|
||||
state: {
|
||||
inClass: true,
|
||||
@@ -237,6 +265,13 @@ async function main() {
|
||||
);
|
||||
|
||||
// ---------------------------------------------------------------- 4. 下发提醒
|
||||
// 先确认掉本班的历史积压（历次冒烟留下的未确认提醒），否则 /pending 的前 20 条窗口
|
||||
// 会被它们占满，下面「插件拉取到待提醒」等用例会拿不到刚发的这条（理由见 drainPending）
|
||||
const drained = await drainPending(deviceToken);
|
||||
if (drained > 0) {
|
||||
console.log(`（已确认本班 ${drained} 条历史积压提醒，避免挤占待提醒窗口）\n`);
|
||||
}
|
||||
|
||||
const notify = await api('/integrations/classisland/notify', {
|
||||
method: 'POST',
|
||||
token: teacherToken,
|
||||
|
||||
@@ -67,6 +67,17 @@ async function main() {
|
||||
}
|
||||
console.log(` 已挂载模块：${(health.payload?.data?.modules ?? []).join(', ')}\n`);
|
||||
|
||||
// 版本号不再硬编码（见 lib/version.ts）：健康检查必须暴露一个像样的版本，
|
||||
// 更新检查要靠它判断"本机是不是旧版"；同时确认 update 模块已进注册表。
|
||||
const healthData = health.payload?.data ?? {};
|
||||
record(
|
||||
'健康检查暴露版本号与模块清单（含 update 模块）',
|
||||
typeof healthData.version === 'string' &&
|
||||
/^\d+\.\d+\.\d+/.test(healthData.version) &&
|
||||
(healthData.modules ?? []).includes('update'),
|
||||
`版本=${healthData.version} 模块数=${(healthData.modules ?? []).length}`,
|
||||
);
|
||||
|
||||
// ---------------------------------------------------------------- 1. 登录
|
||||
const teacherLogin = await api('/auth/login', {
|
||||
method: 'POST',
|
||||
@@ -2503,7 +2514,10 @@ async function main() {
|
||||
body: { classId, title: '数据库roundtrip自检2', content: '备份恢复后应消失' },
|
||||
});
|
||||
const dbRoundtripNotice2Id = dbRoundtripNotice2.payload?.data?.id;
|
||||
const dbRestore = await api(`/database/backups/${backupName}/restore`, { method: 'POST', token: adminToken });
|
||||
const dbRestore = await api(`/database/backups/${backupName}/restore`, {
|
||||
method: 'POST',
|
||||
token: adminToken,
|
||||
});
|
||||
const afterRestore = await api(`/notifications?classId=${classId}`, { token: adminToken });
|
||||
const restoreNoticeGone = !(afterRestore.payload?.data ?? []).some(
|
||||
(item) => item.id === dbRoundtripNotice2Id,
|
||||
@@ -2521,7 +2535,10 @@ async function main() {
|
||||
}
|
||||
|
||||
const dbBackupList = await api('/database/backups', { token: adminToken });
|
||||
const dbBackupDelete = await api(`/database/backups/${backupName}`, { method: 'DELETE', token: adminToken });
|
||||
const dbBackupDelete = await api(`/database/backups/${backupName}`, {
|
||||
method: 'DELETE',
|
||||
token: adminToken,
|
||||
});
|
||||
const dbBackupListAfter = await api('/database/backups', { token: adminToken });
|
||||
record(
|
||||
'备份列表与删除（创建后可见，删除后消失）',
|
||||
@@ -2612,6 +2629,42 @@ async function main() {
|
||||
} 残留班级=${leftoverClasses.map((item) => item.name).join(',') || '无'}`,
|
||||
);
|
||||
|
||||
// ---------------------------------------------------------------- 更新检查
|
||||
// 验的是"结构完整 + 权限 + 可降级"，**刻意不断言"一定有新版本"** ——
|
||||
// 那会把用例绑死在外网可达上，而学校机房/内网服务器查不到 GitHub 是常态
|
||||
// （`ok:false` 是设计内的结果，不是失败）。真实联网取值在交付前人工验一次。
|
||||
const updateAnon = await api('/update/check');
|
||||
record('更新检查未登录 401', updateAnon.status === 401, `status=${updateAnon.status}`);
|
||||
|
||||
const updateRes = await api('/update/check', { token: adminToken });
|
||||
const updateData = updateRes.payload?.data ?? {};
|
||||
const isVersionLike = (value) => typeof value === 'string' && /^\d/.test(value);
|
||||
record(
|
||||
'更新检查（管理员）：结构完整，本机版本取自 package.json',
|
||||
updateRes.status === 200 &&
|
||||
isVersionLike(updateData.currentVersion) &&
|
||||
typeof updateData.ok === 'boolean' &&
|
||||
typeof updateData.hasUpdate === 'boolean' &&
|
||||
(updateData.ok
|
||||
? isVersionLike(updateData.latestVersion) &&
|
||||
Array.isArray(updateData.assets) &&
|
||||
/^https:\/\//.test(updateData.releaseUrl ?? '') &&
|
||||
updateData.error === null
|
||||
: typeof updateData.error === 'string' && updateData.error.length > 0),
|
||||
`ok=${updateData.ok} 本机=${updateData.currentVersion} 最新=${updateData.latestVersion ?? '-'} ` +
|
||||
`有新版本=${updateData.hasUpdate} 附件=${(updateData.assets ?? []).length}` +
|
||||
`${updateData.error ? ` 原因=${updateData.error}` : ''}`,
|
||||
);
|
||||
|
||||
// force 只对管理员生效：教师带 force=1 也必须命中缓存（否则任意登录用户都能刷爆匿名限流）
|
||||
const updateTeacherForced = await api('/update/check?force=1', { token: teacherToken });
|
||||
record(
|
||||
'更新检查：教师可查（公开信息），但 force 仅管理员生效',
|
||||
updateTeacherForced.status === 200 &&
|
||||
updateTeacherForced.payload?.data?.checkedAt === updateData.checkedAt,
|
||||
`status=${updateTeacherForced.status} 命中缓存=${updateTeacherForced.payload?.data?.checkedAt === updateData.checkedAt}`,
|
||||
);
|
||||
|
||||
socket.close();
|
||||
|
||||
// ---------------------------------------------------------------- 汇总
|
||||
|
||||
@@ -6,6 +6,7 @@ import { env } from './config/env.js';
|
||||
import { pingDatabase } from './lib/db.js';
|
||||
import { sendOk } from './lib/http.js';
|
||||
import { logger } from './lib/logger.js';
|
||||
import { APP_VERSION } from './lib/version.js';
|
||||
import { mountWebAdmin, resolveWebDistDir } from './lib/web-static.js';
|
||||
import { errorHandler, notFoundHandler } from './middleware/error.js';
|
||||
import { apiRateLimiter, loginRateLimiter, requestLogger, securityHeaders } from './middleware/security.js';
|
||||
@@ -37,7 +38,8 @@ async function healthHandler(_req: Request, res: Response): Promise<void> {
|
||||
res,
|
||||
{
|
||||
status: 'ok',
|
||||
version: '1.0.0',
|
||||
// 版本号取自 package.json（见 lib/version.ts）：更新检查要拿它跟 GitHub 上的 Release 比
|
||||
version: APP_VERSION,
|
||||
env: env.nodeEnv,
|
||||
uptimeSeconds: Math.round(process.uptime()),
|
||||
database: {
|
||||
@@ -68,7 +70,7 @@ function createRootHandler(webDistDir: string | null) {
|
||||
res,
|
||||
{
|
||||
service: 'class-helper-server',
|
||||
version: '1.0.0',
|
||||
version: APP_VERSION,
|
||||
environment: env.nodeEnv,
|
||||
apiPrefix: API_PREFIX,
|
||||
socket: '/socket.io',
|
||||
@@ -115,7 +117,7 @@ function renderLandingPage(webAdminServed: boolean): string {
|
||||
<body>
|
||||
<div class="card">
|
||||
<h1>班级小助手 · 后端服务 <span class="ok">running</span></h1>
|
||||
<p class="sub">版本 1.0.0 · 运行环境 ${env.nodeEnv} · 数据库 ${env.databaseProvider}</p>
|
||||
<p class="sub">版本 ${APP_VERSION} · 运行环境 ${env.nodeEnv} · 数据库 ${env.databaseProvider}</p>
|
||||
<p class="sub">
|
||||
健康检查 <a href="${API_PREFIX}/health">${API_PREFIX}/health</a> ·
|
||||
存活 /healthz · 就绪 /readyz
|
||||
|
||||
@@ -156,7 +156,6 @@ export const env = {
|
||||
.map((item) => item.trim())
|
||||
.filter(Boolean),
|
||||
bcryptRounds: raw.BCRYPT_ROUNDS,
|
||||
/** 新增学生时未指定密码时的初始密码 */
|
||||
/** 新建班级时的默认班级密码（班级账号登录） */
|
||||
defaultClassPassword: raw.DEFAULT_CLASS_PASSWORD,
|
||||
/** 新建/重置教师账号时的初始密码 */
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { env } from '../config/env.js';
|
||||
import { logger } from './logger.js';
|
||||
|
||||
/**
|
||||
* 服务端版本号。
|
||||
*
|
||||
* 为什么不再硬编码：`app.ts` 里原本写了两个字面量 `'1.0.0'`（健康检查 + 首页），
|
||||
* 而版本号在仓库里已经有 5 份 package.json —— 更新检查要靠它判断"本机是不是旧版"，
|
||||
* 再留一份手写副本就一定会漂移。
|
||||
*
|
||||
* 取哪一份（按顺序）：
|
||||
* 1. `serverRoot/..` —— 打包形态下是运行时清单（`scripts/dist-server.mjs` 把**根**
|
||||
* package.json 的 version 写进 `staging/package.json`），也就是产物命名用的那个版本；
|
||||
* 2. `serverRoot` —— 开发形态下是 `packages/server/package.json`。
|
||||
*
|
||||
* 与 `config/env.ts` 加载 `.env` 的双候选写法同一思路：不依赖启动时的 cwd。
|
||||
*/
|
||||
function readVersion(): string {
|
||||
const candidates = [
|
||||
path.resolve(env.serverRoot, '..', 'package.json'),
|
||||
path.resolve(env.serverRoot, 'package.json'),
|
||||
];
|
||||
|
||||
for (const file of candidates) {
|
||||
try {
|
||||
const parsed = JSON.parse(fs.readFileSync(file, 'utf8')) as { version?: unknown };
|
||||
if (typeof parsed.version === 'string' && parsed.version.trim()) {
|
||||
return parsed.version.trim();
|
||||
}
|
||||
} catch {
|
||||
// 换下一个候选
|
||||
}
|
||||
}
|
||||
|
||||
logger.warn(`未能从 package.json 读到版本号（候选：${candidates.join('、')}），暂时按 0.0.0 处理`);
|
||||
return '0.0.0';
|
||||
}
|
||||
|
||||
export const APP_VERSION = readVersion();
|
||||
@@ -1,6 +1,6 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import express, { type Express, type RequestHandler } from 'express';
|
||||
import express, { type Express } from 'express';
|
||||
import { env } from '../config/env.js';
|
||||
import { logger } from './logger.js';
|
||||
|
||||
@@ -100,9 +100,3 @@ export function mountWebAdmin(app: Express): string | null {
|
||||
logger.info(`Web 管理端已挂载：${distDir}`);
|
||||
return distDir;
|
||||
}
|
||||
|
||||
/** 静态资源请求判断（用于日志降噪等场景） */
|
||||
export const staticAssetMatcher: RequestHandler = (req, _res, next) => {
|
||||
req.headers['x-classhelper-static'] = req.path.startsWith('/assets/') ? '1' : '0';
|
||||
next();
|
||||
};
|
||||
@@ -11,8 +11,13 @@ import { logger } from '../lib/logger.js';
|
||||
* - style-src 需要 'unsafe-inline'：Element Plus 运行时注入行内样式
|
||||
* - connect-src 需要放行 WebSocket（同源 ws/wss）与已配置的跨域后端
|
||||
* - 桌面客户端通过 file:// 加载页面，因此不启用 COOP/COEP，资源策略设为 cross-origin
|
||||
* - helmet 默认 CSP 自带 upgrade-insecure-requests，它会把页面**子资源**请求全部改写成
|
||||
* https —— 而安装器的默认形态是 http://IP:端口 直连（无 TLS），改写后的请求必然
|
||||
* 连接失败，表现为「管理端一片空白、标签页标题正常」（2026-10-05 实测踩到）。
|
||||
* HSTS 在明文响应里按规范本就会被浏览器忽略，但 CSP 指令没有这层豁免，
|
||||
* 所以这两者都只在 HTTPS 请求下下发（见 buildHelmet 的 httpsRequest 参数）。
|
||||
*/
|
||||
export function securityHeaders(): RequestHandler {
|
||||
function buildHelmet(httpsRequest: boolean): RequestHandler {
|
||||
const connectSrc = new Set<string>(["'self'", 'ws:', 'wss:']);
|
||||
if (Array.isArray(env.corsOrigins)) {
|
||||
for (const origin of env.corsOrigins) connectSrc.add(origin);
|
||||
@@ -32,6 +37,7 @@ export function securityHeaders(): RequestHandler {
|
||||
'base-uri': ["'self'"],
|
||||
'frame-ancestors': ["'none'"],
|
||||
'form-action': ["'self'"],
|
||||
'upgrade-insecure-requests': httpsRequest ? [] : null,
|
||||
},
|
||||
},
|
||||
crossOriginEmbedderPolicy: false,
|
||||
@@ -39,10 +45,18 @@ export function securityHeaders(): RequestHandler {
|
||||
// 允许桌面客户端等跨源场景读取静态资源与接口响应
|
||||
crossOriginResourcePolicy: { policy: 'cross-origin' },
|
||||
referrerPolicy: { policy: 'no-referrer' },
|
||||
hsts: env.isProduction ? { maxAge: 15552000, includeSubDomains: true } : false,
|
||||
hsts: httpsRequest && env.isProduction ? { maxAge: 15552000, includeSubDomains: true } : false,
|
||||
});
|
||||
}
|
||||
|
||||
export function securityHeaders(): RequestHandler {
|
||||
const secure = buildHelmet(true);
|
||||
const plain = buildHelmet(false);
|
||||
// req.secure：直连 TLS 时为 true；前面有反代时由 x-forwarded-proto 决定
|
||||
// （app.ts 里 app.set('trust proxy', env.trustProxy) 已生效）
|
||||
return (req, res, next) => (req.secure ? secure : plain)(req, res, next);
|
||||
}
|
||||
|
||||
/** 通用接口限流：防止单 IP 高频刷接口 */
|
||||
export function apiRateLimiter(): RequestHandler {
|
||||
const limiter = rateLimit({
|
||||
@@ -85,11 +99,20 @@ export function loginRateLimiter(): RequestHandler {
|
||||
});
|
||||
}
|
||||
|
||||
/** 请求耗时日志（生产 info，开发 debug） */
|
||||
/**
|
||||
* 请求耗时日志（生产 info，开发 debug）。
|
||||
*
|
||||
* 静态构建产物（`/assets/*`，带内容哈希、长缓存）**成功的请求不打点**：
|
||||
* Web 管理端首屏一次就有十几个资源请求，逐条刷 info 会把真正有用的接口日志淹掉，
|
||||
* 而且每条都要走一次 stdout 写入。失败的静态请求（404 / 500）照常记录 ——
|
||||
* 那种情况恰恰是最需要看见的（产物缺失、路径不对）。
|
||||
*/
|
||||
export function requestLogger(): RequestHandler {
|
||||
return (req, res, next) => {
|
||||
const isStaticAsset = req.path.startsWith('/assets/');
|
||||
const startedAt = process.hrtime.bigint();
|
||||
res.on('finish', () => {
|
||||
if (isStaticAsset && res.statusCode < 400) return;
|
||||
const durationMs = Number(process.hrtime.bigint() - startedAt) / 1_000_000;
|
||||
const message = `${req.method} ${req.originalUrl} ${res.statusCode} ${durationMs.toFixed(1)}ms`;
|
||||
if (res.statusCode >= 500) logger.error(message);
|
||||
|
||||
@@ -12,6 +12,7 @@ import { notificationsModule } from './notifications/notifications.module.js';
|
||||
import { schedulesModule } from './schedules/schedules.module.js';
|
||||
import { studentsModule } from './students/students.module.js';
|
||||
import { teachersModule } from './teachers/teachers.module.js';
|
||||
import { updateModule } from './update/update.module.js';
|
||||
import type { ApiModule } from './module.types.js';
|
||||
|
||||
/**
|
||||
@@ -36,4 +37,5 @@ export const apiModules: ApiModule[] = [
|
||||
teachersModule,
|
||||
dashboardModule,
|
||||
databaseModule,
|
||||
updateModule,
|
||||
].filter((module) => module.enabled !== false);
|
||||
@@ -0,0 +1,32 @@
|
||||
import { Router } from 'express';
|
||||
import { sendOk } from '../../lib/http.js';
|
||||
import { authenticate, getAuthUser } from '../../middleware/auth.js';
|
||||
import { defineModule } from '../module.types.js';
|
||||
import * as updateService from './update.service.js';
|
||||
|
||||
const router = Router();
|
||||
router.use(authenticate());
|
||||
|
||||
/**
|
||||
* GET /api/update/check?force=1 - 检查 GitHub 上有没有比本机新的版本
|
||||
*
|
||||
* 为什么 Web 管理端不直连 GitHub：浏览器的请求受服务端下发的 CSP 约束，
|
||||
* `connect-src` 只放行 `'self'` 与 WebSocket（见 `middleware/security.ts`），
|
||||
* 直连 `api.github.com` 会被浏览器拦掉。走服务端转发还顺带让所有管理员共享同一份缓存。
|
||||
*
|
||||
* 桌面客户端不受这条约束（它由主进程直连），但两边拿到的 `UpdateInfo` 结构是一致的。
|
||||
*
|
||||
* 权限：任何已登录用户都能查（信息本身来自公开仓库）。`force=1` 绕过服务端缓存，
|
||||
* 但**只有管理员生效** —— 否则任意登录用户都能靠刷这个参数把匿名限流打满。
|
||||
*/
|
||||
router.get('/check', async (req, res) => {
|
||||
const user = getAuthUser(req);
|
||||
const force = req.query.force === '1' && user.role === 'ADMIN';
|
||||
sendOk(res, await updateService.checkForUpdates({ force }), '更新检查完成');
|
||||
});
|
||||
|
||||
export const updateModule = defineModule({
|
||||
name: 'update',
|
||||
basePath: '/update',
|
||||
router,
|
||||
});
|
||||
@@ -0,0 +1,152 @@
|
||||
import {
|
||||
GITHUB_RELEASES_LATEST_API,
|
||||
GITHUB_RELEASES_PAGE,
|
||||
UPDATE_CHECK_CACHE_TTL_MS,
|
||||
UPDATE_CHECK_TIMEOUT_MS,
|
||||
UPDATE_CHECK_USER_AGENT,
|
||||
isNewerVersion,
|
||||
normalizeVersion,
|
||||
type UpdateAssetDto,
|
||||
type UpdateInfo,
|
||||
} from '@classhelper/shared';
|
||||
import { logger } from '../../lib/logger.js';
|
||||
import { APP_VERSION } from '../../lib/version.js';
|
||||
|
||||
/**
|
||||
* 更新检查：问 GitHub 上最新的 Release 是不是比本机新。
|
||||
*
|
||||
* 三个设计约束：
|
||||
* 1. **失败是常态，不是异常**：学校的服务器常常在只有内网的机房网络里，
|
||||
* 因此离线 / 限流 / 超时一律收敛成 `ok:false` + 一句人话，绝不抛给路由层（否则管理员看到的会是 500）。
|
||||
* 2. **必须带 User-Agent**：GitHub API 对没有 UA 的请求直接 403。
|
||||
* 3. **必须有缓存**：匿名调用限流是 60 次/小时/IP，而 Web 管理端每次打开弹窗都会问一次。
|
||||
*
|
||||
* 这里用 Node 内置的 `fetch`（Node 20+ / Electron 同源），不引入任何 HTTP 依赖 ——
|
||||
* 这也是本服务端**唯一**的出网请求。
|
||||
*/
|
||||
|
||||
/** GitHub Releases API 里我们真正用到的字段（其余忽略，避免把整个响应建模一遍） */
|
||||
interface GithubReleasePayload {
|
||||
tag_name?: unknown;
|
||||
name?: unknown;
|
||||
published_at?: unknown;
|
||||
body?: unknown;
|
||||
html_url?: unknown;
|
||||
assets?: unknown;
|
||||
}
|
||||
|
||||
let cache: { at: number; info: UpdateInfo } | null = null;
|
||||
|
||||
/** 失败的统一出口：结构完整，界面不必做 null 判断 */
|
||||
function failure(error: string): UpdateInfo {
|
||||
return {
|
||||
ok: false,
|
||||
error,
|
||||
currentVersion: APP_VERSION,
|
||||
latestVersion: null,
|
||||
hasUpdate: false,
|
||||
releaseUrl: GITHUB_RELEASES_PAGE,
|
||||
releaseName: null,
|
||||
publishedAt: null,
|
||||
notes: null,
|
||||
assets: [],
|
||||
checkedAt: new Date().toISOString(),
|
||||
};
|
||||
}
|
||||
|
||||
function toAssets(raw: unknown): UpdateAssetDto[] {
|
||||
if (!Array.isArray(raw)) return [];
|
||||
return raw
|
||||
.map((item) => item as { name?: unknown; browser_download_url?: unknown; size?: unknown })
|
||||
.filter(
|
||||
(item): item is { name: string; browser_download_url: string; size?: unknown } =>
|
||||
typeof item.name === 'string' && typeof item.browser_download_url === 'string',
|
||||
)
|
||||
.map((item) => ({
|
||||
name: item.name,
|
||||
downloadUrl: item.browser_download_url,
|
||||
size: typeof item.size === 'number' && Number.isFinite(item.size) ? item.size : 0,
|
||||
}));
|
||||
}
|
||||
|
||||
function toInfo(payload: GithubReleasePayload): UpdateInfo {
|
||||
const latestVersion = normalizeVersion(typeof payload.tag_name === 'string' ? payload.tag_name : '');
|
||||
// 拿不到版本号就当"查不到"，不要伪造一个 latestVersion 出来
|
||||
if (!latestVersion) {
|
||||
logger.warn('更新检查：GitHub 返回的 Release 里没有可识别的 tag_name');
|
||||
return failure('GitHub 返回的版本号无法识别');
|
||||
}
|
||||
|
||||
return {
|
||||
ok: true,
|
||||
error: null,
|
||||
currentVersion: APP_VERSION,
|
||||
latestVersion,
|
||||
hasUpdate: isNewerVersion(APP_VERSION, latestVersion),
|
||||
// 优先用 Release 自己的 html_url，拿不到才回落到列表页
|
||||
releaseUrl:
|
||||
typeof payload.html_url === 'string' && payload.html_url ? payload.html_url : GITHUB_RELEASES_PAGE,
|
||||
releaseName: typeof payload.name === 'string' ? payload.name : null,
|
||||
publishedAt: typeof payload.published_at === 'string' ? payload.published_at : null,
|
||||
notes: typeof payload.body === 'string' ? payload.body : null,
|
||||
assets: toAssets(payload.assets),
|
||||
checkedAt: new Date().toISOString(),
|
||||
};
|
||||
}
|
||||
|
||||
/** 把各种失败翻译成一句管理员能看懂的话 */
|
||||
function describeFailure(error: unknown): string {
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
if (error instanceof Error && error.name === 'TimeoutError') {
|
||||
return `连接 GitHub 超时（${UPDATE_CHECK_TIMEOUT_MS / 1000} 秒），本机可能没有外网`;
|
||||
}
|
||||
if (/fetch failed|ENOTFOUND|ECONNREFUSED|EAI_AGAIN|ETIMEDOUT|certificate/i.test(message)) {
|
||||
return '无法连接 GitHub，本机可能没有外网';
|
||||
}
|
||||
return `检查更新失败：${message}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* 检查更新（结果带缓存）。
|
||||
*
|
||||
* @param options.force 绕过缓存（由路由层限定为管理员才能生效）
|
||||
*/
|
||||
export async function checkForUpdates(options: { force?: boolean } = {}): Promise<UpdateInfo> {
|
||||
const now = Date.now();
|
||||
if (!options.force && cache && now - cache.at < UPDATE_CHECK_CACHE_TTL_MS) {
|
||||
return cache.info;
|
||||
}
|
||||
|
||||
let info: UpdateInfo;
|
||||
try {
|
||||
const response = await fetch(GITHUB_RELEASES_LATEST_API, {
|
||||
headers: {
|
||||
'User-Agent': UPDATE_CHECK_USER_AGENT,
|
||||
Accept: 'application/vnd.github+json',
|
||||
},
|
||||
signal: AbortSignal.timeout(UPDATE_CHECK_TIMEOUT_MS),
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
// 403 / 429 基本都是匿名限流（60 次/小时/IP）—— 给出可操作的提示而不是原始状态码
|
||||
info =
|
||||
response.status === 403 || response.status === 429
|
||||
? failure('GitHub 暂时拒绝了请求（匿名查询次数过多），请过一会儿再试')
|
||||
: failure(`GitHub 返回 HTTP ${response.status}`);
|
||||
logger.warn(`更新检查失败：HTTP ${response.status}（本机版本 ${APP_VERSION}）`);
|
||||
} else {
|
||||
info = toInfo((await response.json()) as GithubReleasePayload);
|
||||
logger.info(
|
||||
`更新检查：本机 ${APP_VERSION} / 最新 ${info.latestVersion ?? '-'}` +
|
||||
`${info.hasUpdate ? '（有新版本）' : '（已是最新）'}`,
|
||||
);
|
||||
}
|
||||
} catch (error) {
|
||||
info = failure(describeFailure(error));
|
||||
logger.warn(`更新检查失败：${info.error}（本机版本 ${APP_VERSION}）`);
|
||||
}
|
||||
|
||||
// 失败结果**也缓存**：否则机房断网时，管理员每点一次按钮都要白等一个超时。
|
||||
cache = { at: now, info };
|
||||
return info;
|
||||
}
|
||||
@@ -3,7 +3,11 @@
|
||||
"compilerOptions": {
|
||||
"rootDir": "src",
|
||||
"outDir": "dist",
|
||||
"noEmit": false
|
||||
"noEmit": false,
|
||||
"removeComments": true,
|
||||
"declaration": false,
|
||||
"declarationMap": false,
|
||||
"sourceMap": false
|
||||
},
|
||||
"include": ["src/**/*.ts", "src/**/*.d.ts"]
|
||||
}
|
||||
@@ -1,9 +1,26 @@
|
||||
{
|
||||
"extends": "./tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"target": "ES2023",
|
||||
"lib": ["ES2023"],
|
||||
"module": "NodeNext",
|
||||
"moduleResolution": "NodeNext",
|
||||
"types": ["node"],
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"forceConsistentCasingInFileNames": true,
|
||||
"skipLibCheck": true,
|
||||
"resolveJsonModule": true,
|
||||
"isolatedModules": true,
|
||||
"verbatimModuleSyntax": true,
|
||||
"allowImportingTsExtensions": true,
|
||||
"rewriteRelativeImportExtensions": true,
|
||||
"noEmit": false,
|
||||
"outDir": "dist",
|
||||
"rootDir": "src"
|
||||
"rootDir": "src",
|
||||
"removeComments": true,
|
||||
"declaration": false,
|
||||
"declarationMap": false,
|
||||
"sourceMap": false
|
||||
},
|
||||
"include": ["src/generated/**/*.ts"]
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@classhelper/shared",
|
||||
"version": "1.0.0",
|
||||
"version": "1.1.1",
|
||||
"private": true,
|
||||
"description": "班级小助手 - 三端共享的类型、常量与工具函数",
|
||||
"type": "module",
|
||||
|
||||
@@ -27,6 +27,8 @@ export const API_PATHS = {
|
||||
integrations: '/integrations',
|
||||
/** 数据库管理（仅管理员）：状态/备份/导入导出/一键切换 */
|
||||
database: '/database',
|
||||
/** 更新检查：Web 端经服务端转发查 GitHub 上的最新 Release（浏览器受 CSP 限制不能直连） */
|
||||
update: '/update',
|
||||
dashboard: '/dashboard/summary',
|
||||
} as const;
|
||||
|
||||
@@ -496,3 +498,29 @@ export const MAX_PAGE_SIZE = 200;
|
||||
|
||||
/** 教师与管理员角色集合，便于 RBAC 判断 */
|
||||
export const STAFF_ROLES: readonly UserRole[] = ['ADMIN', 'TEACHER'];
|
||||
|
||||
/* ------------------------------------------------------------------ 更新检查 */
|
||||
|
||||
/**
|
||||
* 更新来源：本项目用 **GitHub Releases** 分发交付物（服务端 / 客户端安装包、便携版、插件 .cipx），
|
||||
* 因此"有没有新版本"就是问 GitHub 上最新的那个 Release。
|
||||
*
|
||||
* 仓库是**公开**的，匿名调用即可（不需要 token）；但匿名限流是 60 次/小时/IP，
|
||||
* 所以服务端与客户端都把结果缓存 `UPDATE_CHECK_CACHE_TTL_MS`，不要每次开页面都打一次。
|
||||
*/
|
||||
export const GITHUB_REPO = { owner: 'LoveChengke', repo: 'ClassHelper' } as const;
|
||||
|
||||
/** 最新 Release 的 API 地址（GitHub 保证它不含草稿与预发布版） */
|
||||
export const GITHUB_RELEASES_LATEST_API = `https://api.github.com/repos/${GITHUB_REPO.owner}/${GITHUB_REPO.repo}/releases/latest`;
|
||||
|
||||
/** 给人看的 Release 列表页（「前往下载」按钮打开它） */
|
||||
export const GITHUB_RELEASES_PAGE = `https://github.com/${GITHUB_REPO.owner}/${GITHUB_REPO.repo}/releases`;
|
||||
|
||||
/** GitHub API 强制要求 User-Agent，不带会直接 403 */
|
||||
export const UPDATE_CHECK_USER_AGENT = 'ClassHelper-UpdateCheck';
|
||||
|
||||
/** 检查结果缓存时长（30 分钟）：既避开匿名限流，也不至于让用户等太久才知道有新版本 */
|
||||
export const UPDATE_CHECK_CACHE_TTL_MS = 30 * 60 * 1000;
|
||||
|
||||
/** 单次检查的超时：教室机 / 机房的网络常常很慢，但也不能把界面卡住 */
|
||||
export const UPDATE_CHECK_TIMEOUT_MS = 8_000;
|
||||
@@ -41,7 +41,7 @@ export function canAssignTeachers(role: UserRole): boolean {
|
||||
return role === 'ADMIN';
|
||||
}
|
||||
|
||||
/** 学生名单（增删学生、重置密码、导入名单）：仅管理员 */
|
||||
/** 学生名单（增删学生、导入名单）：仅管理员（学生没有账号，因此没有"重置密码"这一步） */
|
||||
export function canManageRoster(role: UserRole): boolean {
|
||||
return role === 'ADMIN';
|
||||
}
|
||||
@@ -92,7 +92,7 @@ export const PERMISSION_MATRIX: readonly {
|
||||
}[] = [
|
||||
{ action: '班级创建 / 修改 / 删除', admin: true, head: false, subject: false },
|
||||
{ action: '分配班主任与科任老师', admin: true, head: false, subject: false },
|
||||
{ action: '学生名单管理（增删 / 重置密码 / 导入）', admin: true, head: false, subject: false },
|
||||
{ action: '学生名单管理（增删 / 导入）', admin: true, head: false, subject: false },
|
||||
{ action: '教师录入（新建 / 导入名单 / 重置密码）', admin: true, head: false, subject: false },
|
||||
{ action: '课表管理（增删改 / 时间配置导入）', admin: true, head: true, subject: false },
|
||||
{ action: '布置作业', admin: true, head: true, subject: true },
|
||||
|
||||
@@ -1098,3 +1098,41 @@ export interface DatabaseSwitchStepDto {
|
||||
status: 'running' | 'done' | 'error';
|
||||
detail?: string;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ 更新检查 */
|
||||
|
||||
/** Release 里的一个附件（安装包 / 便携版 / 插件包） */
|
||||
export interface UpdateAssetDto {
|
||||
name: string;
|
||||
downloadUrl: string;
|
||||
size: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 更新检查结果（服务端 `GET /api/update/check` 与桌面客户端 IPC 共用同一结构）。
|
||||
*
|
||||
* 两点约定：
|
||||
* 1. **`ok:false` 是正常结果，不是异常** —— 服务器没有外网、GitHub 限流、请求超时都会走到这里，
|
||||
* 调用方按"暂时查不到"呈现即可（与 ClassIsland 推送失败只记日志是同一种处理思路）。
|
||||
* 2. **`currentVersion` 由调用方各自提供**：服务端比的是服务端版本、客户端比的是客户端版本。
|
||||
* 两边安装版本可能不同（例如教室机没跟着升级），所以不能由一端替另一端判断。
|
||||
*/
|
||||
export interface UpdateInfo {
|
||||
ok: boolean;
|
||||
/** 失败原因（给人看的一句话）；ok=true 时为 null */
|
||||
error: string | null;
|
||||
/** 本机版本 */
|
||||
currentVersion: string;
|
||||
/** GitHub 上最新 Release 的版本号；ok=false 时为 null */
|
||||
latestVersion: string | null;
|
||||
hasUpdate: boolean;
|
||||
/** 给人看的 Release 页面地址（「前往下载」用） */
|
||||
releaseUrl: string;
|
||||
/** Release 标题 */
|
||||
releaseName: string | null;
|
||||
publishedAt: string | null;
|
||||
/** Release 说明（Markdown 原文，由界面自行截断展示） */
|
||||
notes: string | null;
|
||||
assets: UpdateAssetDto[];
|
||||
checkedAt: string;
|
||||
}
|
||||
@@ -28,9 +28,7 @@ export function isDayKey(value: string): boolean {
|
||||
if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
|
||||
const [year, month, day] = value.split('-').map(Number);
|
||||
const date = new Date(year, month - 1, day);
|
||||
return (
|
||||
date.getFullYear() === year && date.getMonth() === month - 1 && date.getDate() === day
|
||||
);
|
||||
return date.getFullYear() === year && date.getMonth() === month - 1 && date.getDate() === day;
|
||||
}
|
||||
|
||||
/** 在 YYYY-MM-DD 上加减天数（用于日期选择器的区间与"昨天/明天"） */
|
||||
@@ -357,3 +355,65 @@ export function minutesUntil(time: string, now: Date = new Date()): number {
|
||||
if (target < 0) return 0;
|
||||
return target - (now.getHours() * 60 + now.getMinutes());
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ 版本比较（更新检查） */
|
||||
|
||||
/**
|
||||
* 版本号归一化：去掉首尾空白与前导的 `v` / `V`。
|
||||
*
|
||||
* 之所以需要：GitHub 的 tag 是 `v1.0.0`，而 package.json / `app.getVersion()` 给的是 `1.0.0`，
|
||||
* 两边不归一化就没法比。三端共用这一个实现，避免"客户端说有新版、服务端说没有"。
|
||||
*/
|
||||
export function normalizeVersion(value: string | null | undefined): string {
|
||||
return (value ?? '').trim().replace(/^[vV]/, '');
|
||||
}
|
||||
|
||||
/**
|
||||
* 比较两个版本号：`a` 比 `b` 新返回正数，旧返回负数，相同返回 0。
|
||||
*
|
||||
* 规则：
|
||||
* 1. 按 `.` 分段比数字（每段只取开头的连续数字，因此 `1.0.0-fix` 的第三段仍是 `0`）；
|
||||
* 2. 数字全部相同、只有后缀不同时，**带后缀的一方视为更新**。
|
||||
*
|
||||
* 第 2 条是为 `v0.1.0-fix` 这种"同一个版本号的修复发布"定的：按标准 semver，
|
||||
* `0.1.0-fix` 是 `0.1.0` 的**预发布**（应当更旧），但本项目是拿它当"修完再补发一版"用的，
|
||||
* 照 semver 判会让那条修复版永远提示不出来。另外 `/releases/latest` 本身会跳过预发布，
|
||||
* 所以不用担心把 `-beta` 当成正式版。
|
||||
*/
|
||||
export function compareVersions(a: string | null | undefined, b: string | null | undefined): number {
|
||||
const left = normalizeVersion(a);
|
||||
const right = normalizeVersion(b);
|
||||
if (left === right) return 0;
|
||||
|
||||
const parse = (value: string): { numbers: number[]; suffix: string } => {
|
||||
const [core = '', ...rest] = value.split('-');
|
||||
const numbers = core.split('.').map((part) => {
|
||||
const matched = /^\d+/.exec(part.trim());
|
||||
return matched ? Number(matched[0]) : 0;
|
||||
});
|
||||
return { numbers, suffix: rest.join('-') };
|
||||
};
|
||||
|
||||
const l = parse(left);
|
||||
const r = parse(right);
|
||||
const length = Math.max(l.numbers.length, r.numbers.length);
|
||||
for (let index = 0; index < length; index += 1) {
|
||||
const diff = (l.numbers[index] ?? 0) - (r.numbers[index] ?? 0);
|
||||
if (diff !== 0) return diff > 0 ? 1 : -1;
|
||||
}
|
||||
|
||||
if (l.suffix === r.suffix) return 0;
|
||||
// 数字相同时：裸版本更旧（1.0.0 < 1.0.0-fix），两个都有后缀才按字典序
|
||||
if (!l.suffix) return -1;
|
||||
if (!r.suffix) return 1;
|
||||
return l.suffix.localeCompare(r.suffix);
|
||||
}
|
||||
|
||||
/** `latest` 是否比 `current` 新（更新检查的判定入口；latest 为空一律视为"没有新版"） */
|
||||
export function isNewerVersion(
|
||||
current: string | null | undefined,
|
||||
latest: string | null | undefined,
|
||||
): boolean {
|
||||
if (!normalizeVersion(latest)) return false;
|
||||
return compareVersions(latest, current) > 0;
|
||||
}
|
||||
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "@classhelper/web-admin",
|
||||
"version": "1.0.0",
|
||||
"version": "1.1.1",
|
||||
"private": true,
|
||||
"description": "班级小助手 Web 管理端（Vue 3 + Vite + Element Plus）",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"dev": "vite",
|
||||
"build": "vue-tsc --noEmit -p tsconfig.json && vite build",
|
||||
"build": "node ../../scripts/check-icons.mjs && vue-tsc --noEmit -p tsconfig.json && vite build",
|
||||
"build:only": "vite build",
|
||||
"preview": "vite preview",
|
||||
"typecheck": "vue-tsc --noEmit -p tsconfig.json"
|
||||
@@ -15,7 +15,6 @@
|
||||
"@classhelper/shared": "workspace:*",
|
||||
"@element-plus/icons-vue": "^2.3.2",
|
||||
"axios": "^1.20.0",
|
||||
"echarts": "^6.1.0",
|
||||
"element-plus": "^2.14.5",
|
||||
"pinia": "^4.0.3",
|
||||
"socket.io-client": "^4.8.3",
|
||||
|
||||
@@ -42,6 +42,7 @@ import {
|
||||
type TimeLayoutParsePreview,
|
||||
type UpdateClassAccountRequest,
|
||||
type UpdateClassRequest,
|
||||
type UpdateInfo,
|
||||
type UpdateIntegrationDeviceRequest,
|
||||
type UserDto,
|
||||
} from '@classhelper/shared';
|
||||
@@ -126,12 +127,8 @@ export const homeworkApi = {
|
||||
date?: string;
|
||||
}): Promise<HomeworkDto[]> => api.get(API_PATHS.homeworks, params),
|
||||
/** 哪些天有作业（日期选择器高亮） */
|
||||
days: (params: {
|
||||
classId?: string;
|
||||
from?: string;
|
||||
to?: string;
|
||||
days?: number;
|
||||
}): Promise<HomeworkDaysDto> => api.get(`${API_PATHS.homeworks}/days`, params),
|
||||
days: (params: { classId?: string; from?: string; to?: string; days?: number }): Promise<HomeworkDaysDto> =>
|
||||
api.get(`${API_PATHS.homeworks}/days`, params),
|
||||
detail: (id: string): Promise<HomeworkDto> => api.get(`${API_PATHS.homeworks}/${id}`),
|
||||
create: (payload: CreateHomeworkRequest): Promise<HomeworkDto> => api.post(API_PATHS.homeworks, payload),
|
||||
update: (id: string, payload: Partial<CreateHomeworkRequest>): Promise<HomeworkDto> =>
|
||||
@@ -344,8 +341,10 @@ export const integrationApi = {
|
||||
*/
|
||||
export const databaseApi = {
|
||||
status: (): Promise<DatabaseStatusDto> => api.get(`${API_PATHS.database}/status`),
|
||||
testConnection: (payload: { provider: 'sqlite' | 'mysql'; url: string }): Promise<DatabaseConnectionTestDto> =>
|
||||
api.post(`${API_PATHS.database}/test-connection`, payload),
|
||||
testConnection: (payload: {
|
||||
provider: 'sqlite' | 'mysql';
|
||||
url: string;
|
||||
}): Promise<DatabaseConnectionTestDto> => api.post(`${API_PATHS.database}/test-connection`, payload),
|
||||
listBackups: (): Promise<DatabaseBackupMetaDto[]> => api.get(`${API_PATHS.database}/backups`),
|
||||
createBackup: (): Promise<DatabaseBackupMetaDto> => api.post(`${API_PATHS.database}/backups`, {}),
|
||||
restoreBackup: (name: string): Promise<{ counts: Record<string, number> }> =>
|
||||
@@ -366,3 +365,18 @@ export const databaseApi = {
|
||||
getSwitchJob: (jobId: string): Promise<DatabaseSwitchJobDto | null> =>
|
||||
api.get(`${API_PATHS.database}/switch/jobs/${encodeURIComponent(jobId)}`),
|
||||
};
|
||||
|
||||
/**
|
||||
* 更新检查：问服务端 GitHub 上有没有比本机新的版本。
|
||||
*
|
||||
* **Web 端不直连 GitHub** —— 服务端下发的 CSP `connect-src` 只放行 `'self'` 与 WebSocket
|
||||
* （见 `middleware/security.ts`），浏览器直连 `api.github.com` 会被拦掉；
|
||||
* 走服务端转发还顺带让所有管理员共享同一份缓存（匿名限流 60 次/小时/IP）。
|
||||
*
|
||||
* `ok:false` 是正常结果（机房没外网 / GitHub 限流），不是异常。
|
||||
*/
|
||||
export const updateApi = {
|
||||
/** @param force 绕过服务端缓存；仅管理员生效 */
|
||||
check: (force = false): Promise<UpdateInfo> =>
|
||||
api.get(`${API_PATHS.update}/check${force ? '?force=1' : ''}`),
|
||||
};
|
||||
@@ -0,0 +1,213 @@
|
||||
<script setup lang="ts">
|
||||
import { computed } from 'vue';
|
||||
|
||||
/**
|
||||
* 轻量柱状图（纯 HTML/CSS，不依赖任何图表库）。
|
||||
*
|
||||
* 为什么不用 echarts：成绩页只需要「分组柱 + 数值标签 + 坐标轴」这点东西，
|
||||
* 而 `import * as echarts from 'echarts'` 会给构建产物加 1.1MB。
|
||||
*
|
||||
* 实现要点（决定了这里为什么不需要 resize 监听）：
|
||||
* - 柱高用**百分比**：`.bar-track` 是行方向 flex 里 `flex:1` 的子项，高度确定，
|
||||
* 柱子的 `height: X%` 直接按它解析；
|
||||
* - 刻度与网格线用**零高度 flex 行 + `justify-content: space-between`**：
|
||||
* 零高度元素的中心正好落在 i/(N-1) 处，与柱状区上下边界精确对齐；
|
||||
* - 纵轴刻度列与绘图区共用同一套上下留白（数值行 18px / 标签行 28px），因此永远对齐。
|
||||
*
|
||||
* 与桌面客户端那份（`packages/desktop-client/src/renderer/components/ScoreBarChart.vue`）
|
||||
* 是刻意分开的两份：两端的设计令牌体系不同（`--ch-*` 浅/深色 vs `--el-*`），
|
||||
* 合用一个组件反而要塞一堆条件样式。
|
||||
*/
|
||||
interface BarItem {
|
||||
label: string;
|
||||
value: number;
|
||||
}
|
||||
|
||||
const props = withDefaults(
|
||||
defineProps<{
|
||||
/** 每根柱：分类名 + 数值 */
|
||||
items: BarItem[];
|
||||
/** 柱色 */
|
||||
color?: string;
|
||||
/** 纵轴上限；不传时按数据最大值向上取整到「好看」的刻度 */
|
||||
max?: number;
|
||||
/** 数值单位（显示在刻度与柱顶数值后面） */
|
||||
unit?: string;
|
||||
/** 图表高度（px） */
|
||||
height?: number;
|
||||
}>(),
|
||||
{ color: '#409eff', max: undefined, unit: '', height: 220 },
|
||||
);
|
||||
|
||||
/** 把数值向上取整到 1/2/5 × 10^n，让刻度落在整数上 */
|
||||
function niceCeil(value: number): number {
|
||||
if (value <= 0) return 1;
|
||||
const base = 10 ** Math.floor(Math.log10(value));
|
||||
const normalized = value / base;
|
||||
const step = normalized <= 1 ? 1 : normalized <= 2 ? 2 : normalized <= 5 ? 5 : 10;
|
||||
return step * base;
|
||||
}
|
||||
|
||||
const axisMax = computed(() => {
|
||||
if (props.max !== undefined) return props.max;
|
||||
const dataMax = props.items.reduce((max, item) => Math.max(max, item.value), 0);
|
||||
return niceCeil(dataMax);
|
||||
});
|
||||
|
||||
/** 纵轴刻度（自上而下）：100% / 75% / 50% / 25% / 0%，去重后最多 5 条 */
|
||||
const ticks = computed(() => {
|
||||
const values = [1, 0.75, 0.5, 0.25, 0].map((ratio) => Math.round(axisMax.value * ratio));
|
||||
return [...new Set(values)];
|
||||
});
|
||||
|
||||
function barHeight(value: number): string {
|
||||
const ratio = axisMax.value > 0 ? value / axisMax.value : 0;
|
||||
return `${Math.min(1, Math.max(0, ratio)) * 100}%`;
|
||||
}
|
||||
|
||||
function formatValue(value: number): string {
|
||||
return `${Number.isInteger(value) ? value : value.toFixed(1)}${props.unit}`;
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div class="bar-chart" :style="{ height: `${height}px` }">
|
||||
<div v-if="items.length === 0" class="bar-chart-empty">暂无数据</div>
|
||||
<template v-else>
|
||||
<div class="axis-y" aria-hidden="true">
|
||||
<span v-for="tick in ticks" :key="tick" class="tick">{{ tick }}{{ unit }}</span>
|
||||
</div>
|
||||
|
||||
<div class="plot">
|
||||
<div class="gridlines" aria-hidden="true">
|
||||
<span v-for="tick in ticks" :key="tick" class="gridline"></span>
|
||||
</div>
|
||||
|
||||
<div class="bars">
|
||||
<div v-for="item in items" :key="item.label" class="bar-col">
|
||||
<div class="bar-value">{{ formatValue(item.value) }}</div>
|
||||
<div class="bar-track">
|
||||
<div
|
||||
class="bar"
|
||||
:style="{ height: barHeight(item.value), background: color }"
|
||||
:title="`${item.label}：${formatValue(item.value)}`"
|
||||
></div>
|
||||
</div>
|
||||
<div class="bar-label" :title="item.label">{{ item.label }}</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<style scoped>
|
||||
.bar-chart {
|
||||
display: grid;
|
||||
grid-template-columns: 40px 1fr;
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
.bar-chart-empty {
|
||||
grid-column: 1 / -1;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
height: 100%;
|
||||
font-size: 13px;
|
||||
color: var(--el-text-color-placeholder);
|
||||
}
|
||||
|
||||
.axis-y {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
justify-content: space-between;
|
||||
padding: 18px 0 28px;
|
||||
}
|
||||
|
||||
.tick {
|
||||
height: 0;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: flex-end;
|
||||
padding-right: 8px;
|
||||
font-size: 11px;
|
||||
line-height: 1;
|
||||
white-space: nowrap;
|
||||
color: var(--el-text-color-secondary);
|
||||
}
|
||||
|
||||
.plot {
|
||||
position: relative;
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.gridlines {
|
||||
position: absolute;
|
||||
inset: 18px 0 28px;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
justify-content: space-between;
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.gridline {
|
||||
height: 0;
|
||||
border-top: 1px solid var(--el-border-color-lighter);
|
||||
}
|
||||
|
||||
.bars {
|
||||
display: flex;
|
||||
align-items: stretch;
|
||||
gap: 8px;
|
||||
height: 100%;
|
||||
padding: 0 6px;
|
||||
}
|
||||
|
||||
.bar-col {
|
||||
flex: 1 1 0;
|
||||
min-width: 0;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
height: 100%;
|
||||
}
|
||||
|
||||
.bar-value {
|
||||
flex: none;
|
||||
height: 18px;
|
||||
font-size: 11px;
|
||||
line-height: 1;
|
||||
text-align: center;
|
||||
white-space: nowrap;
|
||||
overflow: hidden;
|
||||
color: var(--el-text-color-secondary);
|
||||
}
|
||||
|
||||
.bar-track {
|
||||
flex: 1 1 auto;
|
||||
min-height: 0;
|
||||
display: flex;
|
||||
align-items: flex-end;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
.bar {
|
||||
width: 46%;
|
||||
max-width: 46px;
|
||||
border-radius: 4px 4px 0 0;
|
||||
transition: height 0.2s ease;
|
||||
}
|
||||
|
||||
.bar-label {
|
||||
flex: none;
|
||||
height: 28px;
|
||||
padding-top: 6px;
|
||||
font-size: 11px;
|
||||
line-height: 1.3;
|
||||
text-align: center;
|
||||
white-space: nowrap;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
color: var(--el-text-color-secondary);
|
||||
}
|
||||
</style>
|
||||
@@ -0,0 +1,268 @@
|
||||
<script setup lang="ts">
|
||||
import { computed } from 'vue';
|
||||
|
||||
/**
|
||||
* 轻量折线图（内联 SVG + HTML 数据点，不依赖任何图表库）。
|
||||
*
|
||||
* 为什么不用 echarts：成绩页只需要一条「各科平均得分率」折线，
|
||||
* 而 `import * as echarts from 'echarts'` 会给构建产物加 1.1MB。
|
||||
*
|
||||
* 实现要点：
|
||||
* - 线画在 `viewBox="0 0 100 100"` + `preserveAspectRatio="none"` 的 SVG 里，
|
||||
* 于是 viewBox 坐标 (x, y) 精确对应绘图区的 (x%, y%)；`vector-effect="non-scaling-stroke"`
|
||||
* 保证非等比拉伸时线宽仍是 2px；
|
||||
* - 数据点用**绝对定位的 HTML 圆点**（而不是 SVG `<circle>`），这样非等比拉伸下仍是正圆；
|
||||
* 点位与线的坐标共用同一套百分比，天然对齐；
|
||||
* - 横轴分类点落在**每个分组的中心**（`(i + 0.5) / n`），与 echarts 的 category 轴一致；
|
||||
* - 全程零 resize 监听。
|
||||
*/
|
||||
interface LineItem {
|
||||
label: string;
|
||||
value: number;
|
||||
}
|
||||
|
||||
const props = withDefaults(
|
||||
defineProps<{
|
||||
items: LineItem[];
|
||||
color?: string;
|
||||
/** 纵轴上限；不传时按数据最大值向上取整 */
|
||||
max?: number;
|
||||
unit?: string;
|
||||
height?: number;
|
||||
}>(),
|
||||
{ color: '#67c23a', max: undefined, unit: '%', height: 220 },
|
||||
);
|
||||
|
||||
function niceCeil(value: number): number {
|
||||
if (value <= 0) return 1;
|
||||
const base = 10 ** Math.floor(Math.log10(value));
|
||||
const normalized = value / base;
|
||||
const step = normalized <= 1 ? 1 : normalized <= 2 ? 2 : normalized <= 5 ? 5 : 10;
|
||||
return step * base;
|
||||
}
|
||||
|
||||
const axisMax = computed(() => {
|
||||
if (props.max !== undefined) return props.max;
|
||||
const dataMax = props.items.reduce((max, item) => Math.max(max, item.value), 0);
|
||||
return niceCeil(dataMax);
|
||||
});
|
||||
|
||||
const ticks = computed(() => {
|
||||
const values = [1, 0.75, 0.5, 0.25, 0].map((ratio) => Math.round(axisMax.value * ratio));
|
||||
return [...new Set(values)];
|
||||
});
|
||||
|
||||
/** 数据点：x / y 都是绘图区的百分比坐标（0~100） */
|
||||
const points = computed(() => {
|
||||
const count = props.items.length;
|
||||
const max = axisMax.value;
|
||||
return props.items.map((item, index) => {
|
||||
const ratio = max > 0 ? item.value / max : 0;
|
||||
return {
|
||||
label: item.label,
|
||||
value: item.value,
|
||||
x: ((index + 0.5) / count) * 100,
|
||||
y: (1 - Math.min(1, Math.max(0, ratio))) * 100,
|
||||
};
|
||||
});
|
||||
});
|
||||
|
||||
/**
|
||||
* Catmull-Rom 转三次贝塞尔，复刻 echarts `smooth: true` 的观感。
|
||||
* tension 0.2 与 echarts 的默认平滑强度接近。
|
||||
*/
|
||||
const linePath = computed(() => {
|
||||
const list = points.value;
|
||||
if (list.length < 2) return '';
|
||||
const tension = 0.2;
|
||||
const round = (value: number) => Number(value.toFixed(2));
|
||||
|
||||
let path = `M ${round(list[0]!.x)} ${round(list[0]!.y)}`;
|
||||
for (let index = 0; index < list.length - 1; index += 1) {
|
||||
const previous = list[index - 1] ?? list[index]!;
|
||||
const current = list[index]!;
|
||||
const next = list[index + 1]!;
|
||||
const afterNext = list[index + 2] ?? next;
|
||||
|
||||
const control1x = current.x + (next.x - previous.x) * tension;
|
||||
const control1y = current.y + (next.y - previous.y) * tension;
|
||||
const control2x = next.x - (afterNext.x - current.x) * tension;
|
||||
const control2y = next.y - (afterNext.y - current.y) * tension;
|
||||
|
||||
path += ` C ${round(control1x)} ${round(control1y)}, ${round(control2x)} ${round(control2y)}, ${round(
|
||||
next.x,
|
||||
)} ${round(next.y)}`;
|
||||
}
|
||||
return path;
|
||||
});
|
||||
|
||||
/** 折线下方的面积：从终点垂到基线，再沿基线回到起点 */
|
||||
const areaPath = computed(() => {
|
||||
const list = points.value;
|
||||
if (list.length < 2) return '';
|
||||
const first = list[0]!;
|
||||
const last = list[list.length - 1]!;
|
||||
return `${linePath.value} L ${Number(last.x.toFixed(2))} 100 L ${Number(first.x.toFixed(2))} 100 Z`;
|
||||
});
|
||||
|
||||
function formatValue(value: number): string {
|
||||
return `${Number.isInteger(value) ? value : value.toFixed(1)}${props.unit}`;
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div class="line-chart" :style="{ height: `${height}px` }">
|
||||
<div v-if="items.length === 0" class="line-chart-empty">暂无数据</div>
|
||||
<template v-else>
|
||||
<div class="axis-y" aria-hidden="true">
|
||||
<span v-for="tick in ticks" :key="tick" class="tick">{{ tick }}{{ unit }}</span>
|
||||
</div>
|
||||
|
||||
<div class="plot">
|
||||
<div class="gridlines" aria-hidden="true">
|
||||
<span v-for="tick in ticks" :key="tick" class="gridline"></span>
|
||||
</div>
|
||||
|
||||
<svg class="lines" viewBox="0 0 100 100" preserveAspectRatio="none" aria-hidden="true">
|
||||
<path v-if="areaPath" :d="areaPath" :fill="color" fill-opacity="0.12" />
|
||||
<path
|
||||
v-if="linePath"
|
||||
:d="linePath"
|
||||
fill="none"
|
||||
:stroke="color"
|
||||
stroke-width="2"
|
||||
stroke-linejoin="round"
|
||||
stroke-linecap="round"
|
||||
vector-effect="non-scaling-stroke"
|
||||
/>
|
||||
</svg>
|
||||
|
||||
<div class="points">
|
||||
<div v-for="point in points" :key="point.label" class="point-col">
|
||||
<span
|
||||
class="point"
|
||||
:style="{ top: `${point.y}%`, background: color }"
|
||||
:title="`${point.label}：${formatValue(point.value)}`"
|
||||
></span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="x-labels" aria-hidden="true">
|
||||
<span v-for="point in points" :key="point.label" class="x-label" :title="point.label">
|
||||
{{ point.label }}
|
||||
</span>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<style scoped>
|
||||
.line-chart {
|
||||
display: grid;
|
||||
grid-template-columns: 40px 1fr;
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
.line-chart-empty {
|
||||
grid-column: 1 / -1;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
height: 100%;
|
||||
font-size: 13px;
|
||||
color: var(--el-text-color-placeholder);
|
||||
}
|
||||
|
||||
/* 上下留白与绘图区（.gridlines / .lines / .points 的 inset）严格一致 */
|
||||
.axis-y {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
justify-content: space-between;
|
||||
padding: 18px 0 28px;
|
||||
}
|
||||
|
||||
.tick {
|
||||
height: 0;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: flex-end;
|
||||
padding-right: 8px;
|
||||
font-size: 11px;
|
||||
line-height: 1;
|
||||
white-space: nowrap;
|
||||
color: var(--el-text-color-secondary);
|
||||
}
|
||||
|
||||
.plot {
|
||||
position: relative;
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.gridlines,
|
||||
.lines,
|
||||
.points {
|
||||
position: absolute;
|
||||
inset: 18px 0 28px;
|
||||
}
|
||||
|
||||
.gridlines {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
justify-content: space-between;
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.gridline {
|
||||
height: 0;
|
||||
border-top: 1px solid var(--el-border-color-lighter);
|
||||
}
|
||||
|
||||
.lines {
|
||||
/* 尺寸完全由上面的 inset 决定（left/right/top/bottom 都给了），不要再写 width/height，
|
||||
否则会和 inset 打架 */
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.points {
|
||||
display: flex;
|
||||
}
|
||||
|
||||
.point-col {
|
||||
flex: 1 1 0;
|
||||
min-width: 0;
|
||||
position: relative;
|
||||
}
|
||||
|
||||
.point {
|
||||
position: absolute;
|
||||
left: 50%;
|
||||
width: 8px;
|
||||
height: 8px;
|
||||
border-radius: 50%;
|
||||
transform: translate(-50%, -50%);
|
||||
}
|
||||
|
||||
.x-labels {
|
||||
position: absolute;
|
||||
left: 0;
|
||||
right: 0;
|
||||
bottom: 0;
|
||||
height: 28px;
|
||||
display: flex;
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.x-label {
|
||||
flex: 1 1 0;
|
||||
min-width: 0;
|
||||
padding-top: 6px;
|
||||
font-size: 11px;
|
||||
line-height: 1.3;
|
||||
text-align: center;
|
||||
white-space: nowrap;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
color: var(--el-text-color-secondary);
|
||||
}
|
||||
</style>
|
||||
@@ -0,0 +1,179 @@
|
||||
<script setup lang="ts">
|
||||
import { computed, ref, watch } from 'vue';
|
||||
import { formatDate, type UpdateInfo } from '@classhelper/shared';
|
||||
import { updateApi } from '@/api';
|
||||
|
||||
/**
|
||||
* 「检查更新」弹窗（Web 管理端顶栏用户菜单）。
|
||||
*
|
||||
* 数据来自**服务端**的 `GET /api/update/check` —— 浏览器受服务端下发的 CSP `connect-src`
|
||||
* 限制，不能直连 `api.github.com`；走服务端转发还顺带让所有管理员共享同一份缓存
|
||||
* （GitHub 匿名限流 60 次/小时/IP）。
|
||||
*
|
||||
* `ok:false` 是**正常结果**（机房没有外网 / GitHub 限流 / 超时），不是错误 ——
|
||||
* 界面按"暂时查不到"呈现，并给出重试入口，而不是弹一句红字报错。
|
||||
*/
|
||||
const props = defineProps<{ modelValue: boolean }>();
|
||||
const emit = defineEmits<{ (event: 'update:modelValue', value: boolean): void }>();
|
||||
|
||||
const visible = computed({
|
||||
get: () => props.modelValue,
|
||||
set: (value: boolean) => emit('update:modelValue', value),
|
||||
});
|
||||
|
||||
const loading = ref(false);
|
||||
const info = ref<UpdateInfo | null>(null);
|
||||
|
||||
/** 发布时间（本地格式），拿不到就不显示 */
|
||||
const publishedText = computed(() => {
|
||||
const at = info.value?.publishedAt;
|
||||
return at ? formatDate(at, true) : '';
|
||||
});
|
||||
|
||||
/**
|
||||
* 用户点菜单里的「检查更新」是一次明确的手动检查，因此**绕过服务端缓存**（force=1，仅管理员生效）；
|
||||
* 打开弹窗时才查，而不是进页面就查 —— 没点菜单就不该产生任何外部请求。
|
||||
*/
|
||||
async function check(): Promise<void> {
|
||||
loading.value = true;
|
||||
try {
|
||||
info.value = await updateApi.check(true);
|
||||
} catch {
|
||||
// 请求本身失败（如火并发的接口限流）：http.ts 已经弹过提示，这里只保证弹窗里不留空白
|
||||
info.value = null;
|
||||
} finally {
|
||||
loading.value = false;
|
||||
}
|
||||
}
|
||||
|
||||
function openRelease(): void {
|
||||
const url = info.value?.releaseUrl;
|
||||
if (!url) return;
|
||||
window.open(url, '_blank', 'noopener');
|
||||
}
|
||||
|
||||
function formatBytes(size: number): string {
|
||||
if (!Number.isFinite(size) || size <= 0) return '';
|
||||
const mb = size / 1024 / 1024;
|
||||
return mb >= 1 ? `${mb.toFixed(1)} MB` : `${Math.round(size / 1024)} KB`;
|
||||
}
|
||||
|
||||
// 打开时才查：关闭后清空结果，下次打开重新查一遍（避免显示上一次的陈旧结论）
|
||||
watch(
|
||||
() => props.modelValue,
|
||||
(opened) => {
|
||||
if (opened) void check();
|
||||
else info.value = null;
|
||||
},
|
||||
);
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<el-dialog v-model="visible" title="检查更新" width="520px" data-test="update-dialog">
|
||||
<div v-loading="loading" class="update-body">
|
||||
<template v-if="info && info.ok">
|
||||
<el-alert
|
||||
v-if="info.hasUpdate"
|
||||
type="success"
|
||||
:closable="false"
|
||||
show-icon
|
||||
data-test="update-found"
|
||||
:title="`发现新版本 v${info.latestVersion}`"
|
||||
:description="`当前版本 v${info.currentVersion}${publishedText ? ` · 发布于 ${publishedText}` : ''}`"
|
||||
/>
|
||||
<el-alert
|
||||
v-else
|
||||
type="info"
|
||||
:closable="false"
|
||||
show-icon
|
||||
data-test="update-latest"
|
||||
title="已是最新版本"
|
||||
:description="`当前版本 v${info.currentVersion}（GitHub 最新为 v${info.latestVersion}）`"
|
||||
/>
|
||||
|
||||
<template v-if="info.hasUpdate">
|
||||
<div v-if="info.releaseName" class="update-name">{{ info.releaseName }}</div>
|
||||
|
||||
<div v-if="info.notes" class="update-notes-label">更新说明</div>
|
||||
<pre v-if="info.notes" class="update-notes">{{ info.notes }}</pre>
|
||||
|
||||
<template v-if="info.assets.length > 0">
|
||||
<div class="update-notes-label">可下载文件</div>
|
||||
<ul class="update-assets">
|
||||
<li v-for="asset in info.assets" :key="asset.name">
|
||||
<span class="update-asset-name">{{ asset.name }}</span>
|
||||
<span v-if="formatBytes(asset.size)" class="update-asset-size">
|
||||
{{ formatBytes(asset.size) }}
|
||||
</span>
|
||||
</li>
|
||||
</ul>
|
||||
</template>
|
||||
</template>
|
||||
</template>
|
||||
|
||||
<!-- 查不到不是错误：机房没有外网、GitHub 限流都会走到这里 -->
|
||||
<el-alert
|
||||
v-else-if="!loading"
|
||||
type="warning"
|
||||
:closable="false"
|
||||
show-icon
|
||||
data-test="update-unavailable"
|
||||
title="暂时无法检查更新"
|
||||
:description="info?.error ?? '请稍后重试；若服务器没有外网，可手动打开项目 Release 页面查看'"
|
||||
/>
|
||||
</div>
|
||||
|
||||
<template #footer>
|
||||
<el-button @click="visible = false">关闭</el-button>
|
||||
<el-button :loading="loading" @click="check()">重新检查</el-button>
|
||||
<el-button v-if="info?.ok && info.hasUpdate" type="primary" @click="openRelease">前往下载</el-button>
|
||||
</template>
|
||||
</el-dialog>
|
||||
</template>
|
||||
|
||||
<style scoped>
|
||||
.update-body {
|
||||
min-height: 72px;
|
||||
}
|
||||
|
||||
.update-name {
|
||||
margin-top: 12px;
|
||||
font-size: 13px;
|
||||
font-weight: 600;
|
||||
color: var(--el-text-color-primary);
|
||||
}
|
||||
|
||||
.update-notes-label {
|
||||
margin: 12px 0 6px;
|
||||
font-size: 12px;
|
||||
color: var(--el-text-color-secondary);
|
||||
}
|
||||
|
||||
.update-notes {
|
||||
margin: 0;
|
||||
padding: 10px 12px;
|
||||
max-height: 200px;
|
||||
overflow: auto;
|
||||
background: var(--el-fill-color-light);
|
||||
border-radius: var(--ch-radius-sm);
|
||||
font-size: 12px;
|
||||
line-height: 1.7;
|
||||
white-space: pre-wrap;
|
||||
word-break: break-word;
|
||||
font-family: inherit;
|
||||
color: var(--el-text-color-regular);
|
||||
}
|
||||
|
||||
.update-assets {
|
||||
margin: 0;
|
||||
padding-left: 18px;
|
||||
font-size: 12px;
|
||||
line-height: 1.9;
|
||||
color: var(--el-text-color-regular);
|
||||
}
|
||||
|
||||
.update-asset-size {
|
||||
margin-left: 6px;
|
||||
color: var(--el-text-color-secondary);
|
||||
}
|
||||
</style>
|
||||
@@ -0,0 +1,74 @@
|
||||
import type { App } from 'vue';
|
||||
import {
|
||||
ArrowDown,
|
||||
Bell,
|
||||
Calendar,
|
||||
Coin,
|
||||
Connection,
|
||||
CopyDocument,
|
||||
Document,
|
||||
Guide,
|
||||
Lock,
|
||||
Menu,
|
||||
Notebook,
|
||||
Odometer,
|
||||
Plus,
|
||||
Refresh,
|
||||
School,
|
||||
Search,
|
||||
SwitchButton,
|
||||
Trophy,
|
||||
Upload,
|
||||
User,
|
||||
UserFilled,
|
||||
WarningFilled,
|
||||
} from '@element-plus/icons-vue';
|
||||
|
||||
/**
|
||||
* Element Plus 图标注册表（Web 管理端）。
|
||||
*
|
||||
* **为什么不 `import * as ElementPlusIconsVue` 全量注册**：
|
||||
* 图标库有 293 个组件（实测全量打包 minified 203KB，实际用到的只有 22 个 / 59KB），
|
||||
* 全量注册既把 144KB 死代码打进主 chunk，又要在启动时执行 293 次 `app.component()`。
|
||||
*
|
||||
* **为什么不改成模板里逐个 import**：本项目的图标是按**字符串名**引用的
|
||||
* （菜单/路由配置里的 `icon: 'Odometer'`、按钮上的 `:icon="'Search'"`、
|
||||
* `<component :is="item.icon">`），Element Plus 的 `el-button` / `el-menu-item`
|
||||
* 会用 `<component :is="'Odometer'">` 去解析**全局组件名**，因此图标必须以全局组件存在。
|
||||
*
|
||||
* 新增视图时若用了新图标，`scripts/check-icons.mjs` 会在构建前报错（见 package.json 的 build 脚本），
|
||||
* 不会静默渲染成空白。
|
||||
*/
|
||||
const APP_ICONS = {
|
||||
ArrowDown,
|
||||
Bell,
|
||||
Calendar,
|
||||
Coin,
|
||||
Connection,
|
||||
CopyDocument,
|
||||
Document,
|
||||
Guide,
|
||||
Lock,
|
||||
Menu,
|
||||
Notebook,
|
||||
Odometer,
|
||||
Plus,
|
||||
Refresh,
|
||||
School,
|
||||
Search,
|
||||
SwitchButton,
|
||||
Trophy,
|
||||
Upload,
|
||||
User,
|
||||
UserFilled,
|
||||
WarningFilled,
|
||||
} as const;
|
||||
|
||||
/** 供 `scripts/check-icons.mjs` 读取的名单（构建期静态校验用） */
|
||||
export const APP_ICON_NAMES: readonly string[] = Object.keys(APP_ICONS).sort();
|
||||
|
||||
export function registerAppIcons(app: App): void {
|
||||
for (const [name, component] of Object.entries(APP_ICONS)) {
|
||||
app.component(name, component);
|
||||
}
|
||||
}
|
||||
@@ -4,6 +4,7 @@ import { useRoute, useRouter } from 'vue-router';
|
||||
import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus';
|
||||
import { STORAGE_KEYS } from '@classhelper/shared';
|
||||
import { authApi } from '@/api';
|
||||
import UpdateCheckDialog from '@/components/UpdateCheckDialog.vue';
|
||||
import { useAuthStore } from '@/stores/auth';
|
||||
import { useRealtimeStore } from '@/stores/realtime';
|
||||
import { useResponsive } from '@/composables/useResponsive';
|
||||
@@ -107,6 +108,10 @@ async function handleLogout(): Promise<void> {
|
||||
void router.push({ name: 'login' });
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ 检查更新 */
|
||||
/** 顶栏用户菜单「检查更新」弹窗 */
|
||||
const updateVisible = ref(false);
|
||||
|
||||
/* ------------------------------------------------------------ 修改密码 */
|
||||
const passwordVisible = ref(false);
|
||||
const passwordFormRef = ref<FormInstance>();
|
||||
@@ -295,6 +300,10 @@ const tourSteps = computed(() => [
|
||||
<el-icon><Guide /></el-icon>
|
||||
使用引导
|
||||
</el-dropdown-item>
|
||||
<el-dropdown-item divided data-test="update-check-entry" @click="updateVisible = true">
|
||||
<el-icon><Refresh /></el-icon>
|
||||
检查更新
|
||||
</el-dropdown-item>
|
||||
<el-dropdown-item divided @click="handleLogout">
|
||||
<el-icon><SwitchButton /></el-icon>
|
||||
退出登录
|
||||
@@ -352,6 +361,9 @@ const tourSteps = computed(() => [
|
||||
</template>
|
||||
</el-dialog>
|
||||
|
||||
<!-- 检查更新：问服务端最新 Release（浏览器受 CSP 限制不能直连 GitHub），见组件内说明 -->
|
||||
<UpdateCheckDialog v-model="updateVisible" />
|
||||
|
||||
<!--
|
||||
新手引导：首次登录自动弹出（见 script 的 onMounted），头像菜单「使用引导」可重看。
|
||||
target 为 null 的步骤（首尾两步）由 el-tour 放到屏幕居中；其余步骤锚定真实 UI。
|
||||
|
||||
@@ -2,19 +2,17 @@ import { createApp } from 'vue';
|
||||
import { createPinia } from 'pinia';
|
||||
import ElementPlus from 'element-plus';
|
||||
import zhCn from 'element-plus/es/locale/lang/zh-cn';
|
||||
import * as ElementPlusIconsVue from '@element-plus/icons-vue';
|
||||
import 'element-plus/dist/index.css';
|
||||
|
||||
import App from './App.vue';
|
||||
import router from './router';
|
||||
import { registerAppIcons } from './icons';
|
||||
import '@/styles/index.css';
|
||||
|
||||
const app = createApp(App);
|
||||
|
||||
// 全量注册 Element Plus 图标，模板里可直接 <el-icon><Bell /></el-icon>
|
||||
for (const [name, component] of Object.entries(ElementPlusIconsVue)) {
|
||||
app.component(name, component);
|
||||
}
|
||||
// 按需注册图标（见 icons.ts：只注册用到的那些，而不是全量 293 个）
|
||||
registerAppIcons(app);
|
||||
|
||||
app.use(createPinia());
|
||||
app.use(router);
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
<script setup lang="ts">
|
||||
import { computed, onMounted, onUnmounted, reactive, ref, watch } from 'vue';
|
||||
import { ElMessage, ElMessageBox } from 'element-plus';
|
||||
import * as echarts from 'echarts';
|
||||
import {
|
||||
SOCKET_EVENTS,
|
||||
SUBJECT_CATALOG,
|
||||
@@ -15,6 +14,8 @@ import {
|
||||
type StudentDto,
|
||||
} from '@classhelper/shared';
|
||||
import { classApi, courseApi, gradeApi } from '@/api';
|
||||
import ScoreBarChart from '@/components/ScoreBarChart.vue';
|
||||
import ScoreLineChart from '@/components/ScoreLineChart.vue';
|
||||
import TableImportDialog from '@/components/TableImportDialog.vue';
|
||||
import { useAuthStore } from '@/stores/auth';
|
||||
import { useRealtimeStore } from '@/stores/realtime';
|
||||
@@ -41,10 +42,15 @@ const students = ref<StudentDto[]>([]);
|
||||
const stats = ref<GradeStats | null>(null);
|
||||
const filter = reactive({ classId: '', courseId: '', examName: '' });
|
||||
|
||||
const levelChartRef = ref<HTMLDivElement>();
|
||||
const courseChartRef = ref<HTMLDivElement>();
|
||||
const levelChart = ref<ReturnType<typeof echarts.init> | null>(null);
|
||||
const courseChart = ref<ReturnType<typeof echarts.init> | null>(null);
|
||||
/** 等级分布柱状图的数据（count 是整数，纵轴上限交给组件按数据自动取整） */
|
||||
const levelItems = computed(() =>
|
||||
(stats.value?.distribution ?? []).map((item) => ({ label: `${item.level} 等`, value: item.count })),
|
||||
);
|
||||
|
||||
/** 各课程平均得分率折线图的数据 */
|
||||
const courseItems = computed(() =>
|
||||
(stats.value?.byCourse ?? []).map((item) => ({ label: item.courseName, value: item.averagePercent })),
|
||||
);
|
||||
|
||||
const averagePercent = computed(() => {
|
||||
if (grades.value.length === 0) return 0;
|
||||
@@ -79,7 +85,6 @@ async function loadGrades(): Promise<void> {
|
||||
if (requestId !== gradesRequestId) return;
|
||||
grades.value = list;
|
||||
stats.value = statistic;
|
||||
renderCharts();
|
||||
} finally {
|
||||
if (requestId === gradesRequestId) loading.value = false;
|
||||
}
|
||||
@@ -94,55 +99,15 @@ async function onClassChange(): Promise<void> {
|
||||
await loadTeacherSuggestions();
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ 图表 */
|
||||
|
||||
function renderCharts(): void {
|
||||
const statistic = stats.value;
|
||||
if (!statistic) return;
|
||||
|
||||
if (levelChartRef.value) {
|
||||
levelChart.value ??= echarts.init(levelChartRef.value);
|
||||
levelChart.value.setOption({
|
||||
tooltip: { trigger: 'axis' },
|
||||
grid: { left: 40, right: 16, top: 30, bottom: 28 },
|
||||
xAxis: { type: 'category', data: statistic.distribution.map((item) => `${item.level} 等`) },
|
||||
yAxis: { type: 'value', minInterval: 1 },
|
||||
series: [
|
||||
{
|
||||
type: 'bar',
|
||||
barWidth: '46%',
|
||||
itemStyle: { color: '#409eff', borderRadius: [4, 4, 0, 0] },
|
||||
data: statistic.distribution.map((item) => item.count),
|
||||
},
|
||||
],
|
||||
});
|
||||
}
|
||||
|
||||
if (courseChartRef.value) {
|
||||
courseChart.value ??= echarts.init(courseChartRef.value);
|
||||
courseChart.value.setOption({
|
||||
tooltip: { trigger: 'axis' },
|
||||
grid: { left: 40, right: 16, top: 30, bottom: 28 },
|
||||
xAxis: { type: 'category', data: statistic.byCourse.map((item) => item.courseName) },
|
||||
yAxis: { type: 'value', max: 100, name: '得分率%' },
|
||||
series: [
|
||||
{
|
||||
type: 'line',
|
||||
smooth: true,
|
||||
symbolSize: 8,
|
||||
areaStyle: { opacity: 0.12 },
|
||||
itemStyle: { color: '#67c23a' },
|
||||
data: statistic.byCourse.map((item) => item.averagePercent),
|
||||
},
|
||||
],
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
function handleResize(): void {
|
||||
levelChart.value?.resize();
|
||||
courseChart.value?.resize();
|
||||
}
|
||||
/* ------------------------------------------------------------ 图表
|
||||
*
|
||||
* 等级分布与各课程得分率原先用 echarts 渲染（`import * as echarts from 'echarts'`
|
||||
* 会给构建产物加 1.1MB）。现在换成两个自包含的轻量组件：
|
||||
* - ScoreBarChart：纯 HTML/CSS 柱状图
|
||||
* - ScoreLineChart：内联 SVG 折线 + HTML 数据点
|
||||
* 两者都是响应式的（百分比布局），因此不再需要 resize 监听，
|
||||
* 数据也直接从上面两个 computed 流过去，不需要手写 setOption。
|
||||
*/
|
||||
|
||||
/* ------------------------------------------------------------ 统一科目
|
||||
*
|
||||
@@ -299,14 +264,10 @@ watch(
|
||||
onMounted(async () => {
|
||||
await loadClasses();
|
||||
await loadGrades();
|
||||
window.addEventListener('resize', handleResize);
|
||||
realtime.on(SOCKET_EVENTS.gradeUpdated, onGradeEvent);
|
||||
});
|
||||
|
||||
onUnmounted(() => {
|
||||
window.removeEventListener('resize', handleResize);
|
||||
levelChart.value?.dispose();
|
||||
courseChart.value?.dispose();
|
||||
realtime.off(SOCKET_EVENTS.gradeUpdated, onGradeEvent);
|
||||
});
|
||||
</script>
|
||||
@@ -361,13 +322,13 @@ onUnmounted(() => {
|
||||
<el-col :xs="24" :md="9">
|
||||
<el-card shadow="never">
|
||||
<template #header><span>等级分布</span></template>
|
||||
<div ref="levelChartRef" class="chart"></div>
|
||||
<ScoreBarChart :items="levelItems" />
|
||||
</el-card>
|
||||
</el-col>
|
||||
<el-col :xs="24" :md="9">
|
||||
<el-card shadow="never">
|
||||
<template #header><span>各课程平均得分率</span></template>
|
||||
<div ref="courseChartRef" class="chart"></div>
|
||||
<ScoreLineChart :items="courseItems" :max="100" />
|
||||
</el-card>
|
||||
</el-col>
|
||||
</el-row>
|
||||
@@ -503,10 +464,3 @@ onUnmounted(() => {
|
||||
/>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<style scoped>
|
||||
.chart {
|
||||
height: 220px;
|
||||
width: 100%;
|
||||
}
|
||||
</style>
|
||||
Generated
-26
@@ -41,9 +41,6 @@ importers:
|
||||
axios:
|
||||
specifier: ^1.20.0
|
||||
version: 1.20.0
|
||||
echarts:
|
||||
specifier: ^6.1.0
|
||||
version: 6.1.0
|
||||
element-plus:
|
||||
specifier: ^2.14.5
|
||||
version: 2.14.5(vue@3.5.42(typescript@5.9.3))
|
||||
@@ -181,9 +178,6 @@ importers:
|
||||
axios:
|
||||
specifier: ^1.20.0
|
||||
version: 1.20.0
|
||||
echarts:
|
||||
specifier: ^6.1.0
|
||||
version: 6.1.0
|
||||
element-plus:
|
||||
specifier: ^2.14.5
|
||||
version: 2.14.5(vue@3.5.42(typescript@5.9.3))
|
||||
@@ -1711,9 +1705,6 @@ packages:
|
||||
ecdsa-sig-formatter@1.0.11:
|
||||
resolution: {integrity: sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==}
|
||||
|
||||
echarts@6.1.0:
|
||||
resolution: {integrity: sha512-q0yaFPggC9FUdsWH4blavRWFmxdrIodbkoKNAjJudAI6CA9gNPxHtV2RcZNEepZVlk4yvBYkOkbk6HIVpIyHZA==}
|
||||
|
||||
ee-first@1.1.1:
|
||||
resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
|
||||
|
||||
@@ -3118,9 +3109,6 @@ packages:
|
||||
peerDependencies:
|
||||
typescript: '>=4.8.4'
|
||||
|
||||
tslib@2.3.0:
|
||||
resolution: {integrity: sha512-N82ooyxVNm6h1riLCoyS9e3fuJ3AMG2zIZs2Gd1ATcSFjSA23Q0fzjjZeh0jbJvWVDZ0cJT8yaNNaaXHzueNjg==}
|
||||
|
||||
tslib@2.8.1:
|
||||
resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
|
||||
|
||||
@@ -3440,9 +3428,6 @@ packages:
|
||||
zod@4.6.2:
|
||||
resolution: {integrity: sha512-lh5RCAGFa1Cm2hjtNwLQhSs/AsqdWnTQaBER9fEwN/88pSh7KOtJavtBx/0VlkN/uFd61SwYmljLMDAsHlvzBQ==}
|
||||
|
||||
zrender@6.1.0:
|
||||
resolution: {integrity: sha512-oEGMDB6pOP2S6OwRR4PdVv610zrjnA3Bh+JnSG12fYJlBKjtNAoEb5fSUoCOOINlH96I2fU38/A2UpRKs67xYQ==}
|
||||
|
||||
snapshots:
|
||||
|
||||
'@babel/helper-string-parser@7.29.7': {}
|
||||
@@ -5044,11 +5029,6 @@ snapshots:
|
||||
dependencies:
|
||||
safe-buffer: 5.2.1
|
||||
|
||||
echarts@6.1.0:
|
||||
dependencies:
|
||||
tslib: 2.3.0
|
||||
zrender: 6.1.0
|
||||
|
||||
ee-first@1.1.1: {}
|
||||
|
||||
effect@3.20.0:
|
||||
@@ -6599,8 +6579,6 @@ snapshots:
|
||||
dependencies:
|
||||
typescript: 5.9.3
|
||||
|
||||
tslib@2.3.0: {}
|
||||
|
||||
tslib@2.8.1: {}
|
||||
|
||||
tsx@4.23.13:
|
||||
@@ -6865,7 +6843,3 @@ snapshots:
|
||||
graphmatch: 1.1.1
|
||||
|
||||
zod@4.6.2: {}
|
||||
|
||||
zrender@6.1.0:
|
||||
dependencies:
|
||||
tslib: 2.3.0
|
||||
@@ -0,0 +1,143 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* 图标注册表静态校验（构建前门禁）。
|
||||
*
|
||||
* 为什么需要：
|
||||
* 本项目的 Element Plus 图标是按**字符串名**全局引用的 —— 菜单/路由配置里的 `icon: 'Odometer'`、
|
||||
* 按钮上的 `:icon="'Search'"`、`<component :is="item.icon">`，以及模板里的 `<el-icon><School /></el-icon>`。
|
||||
* 为了让主 chunk 不为 293 个图标里的 250 个死代码买单，两端改成**按需注册**
|
||||
* （`packages/web-admin/src/icons.ts`、`packages/desktop-client/src/renderer/icons.ts`）。
|
||||
*
|
||||
* 代价是：新增视图时用了一个没注册的图标，Vue 只会打一条 warning、界面上**静默渲染成空白** ——
|
||||
* 这类问题在 verify:web / verify:desktop 里都不容易暴露。因此在这里做一次静态校验，
|
||||
* 有遗漏就 exit 1，把失败挪到构建阶段。
|
||||
*
|
||||
* 用法：node scripts/check-icons.mjs （已挂进两端 package.json 的 build 脚本）
|
||||
*/
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath, pathToFileURL } from 'node:url';
|
||||
|
||||
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
||||
|
||||
const TARGETS = [
|
||||
{
|
||||
name: 'web-admin',
|
||||
registry: path.join(root, 'packages/web-admin/src/icons.ts'),
|
||||
sources: [path.join(root, 'packages/web-admin/src')],
|
||||
},
|
||||
{
|
||||
name: 'desktop-client',
|
||||
registry: path.join(root, 'packages/desktop-client/src/renderer/icons.ts'),
|
||||
sources: [
|
||||
path.join(root, 'packages/desktop-client/src/renderer'),
|
||||
path.join(root, 'packages/desktop-client/src/island'),
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
/** 递归收集 .vue / .ts 源文件 */
|
||||
function collectFiles(dirs) {
|
||||
const found = [];
|
||||
const walk = (dir) => {
|
||||
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) walk(full);
|
||||
else if (/\.(vue|ts)$/.test(entry.name)) found.push(full);
|
||||
}
|
||||
};
|
||||
for (const dir of dirs) {
|
||||
if (fs.existsSync(dir)) walk(dir);
|
||||
}
|
||||
return found;
|
||||
}
|
||||
|
||||
/**
|
||||
* 从注册表文件里取出 `const APP_ICONS = { ... } as const;` 的键名。
|
||||
* 这里刻意做文本解析而不是 import：注册表是 .ts，构建期没有可用的 TS 运行时。
|
||||
* 对象字面量用的是简写属性（`{ Odometer, Bell }`），所以键名就是标识符本身。
|
||||
*/
|
||||
function readRegistry(file) {
|
||||
const source = fs.readFileSync(file, 'utf8');
|
||||
const match = source.match(/const APP_ICONS = \{([\s\S]*?)\} as const;/);
|
||||
if (!match) {
|
||||
throw new Error(`${path.relative(root, file)} 里找不到 \`const APP_ICONS = { ... } as const;\` 块`);
|
||||
}
|
||||
return new Set(match[1].match(/[A-Za-z][A-Za-z0-9]*/g) ?? []);
|
||||
}
|
||||
|
||||
/**
|
||||
* Element Plus 图标库的真实导出名（293 个）。
|
||||
* 用运行时 import 取，而不是从 `dist/types/components/*.vue.d.ts` 猜文件名转 PascalCase ——
|
||||
* 后者的来回转换（如 `circle-check-filled`）并不可靠。
|
||||
*/
|
||||
async function loadKnownIconNames() {
|
||||
const candidates = [
|
||||
path.join(root, 'packages/web-admin/node_modules/@element-plus/icons-vue'),
|
||||
path.join(root, 'packages/desktop-client/node_modules/@element-plus/icons-vue'),
|
||||
];
|
||||
for (const base of candidates) {
|
||||
const manifest = path.join(base, 'package.json');
|
||||
if (!fs.existsSync(manifest)) continue;
|
||||
const pkg = JSON.parse(fs.readFileSync(manifest, 'utf8'));
|
||||
const entry = path.resolve(base, pkg.module ?? pkg.main);
|
||||
const module = await import(pathToFileURL(entry).href);
|
||||
return new Set(Object.keys(module).filter((key) => key !== 'default' && /^[A-Z][A-Za-z0-9]*$/.test(key)));
|
||||
}
|
||||
throw new Error('找不到 @element-plus/icons-vue，请先执行 pnpm install');
|
||||
}
|
||||
|
||||
/** 扫描一个包，返回「用到的图标名 -> 首次出现位置」 */
|
||||
function collectUsages(files, known) {
|
||||
const usages = new Map();
|
||||
const record = (name, file, index) => {
|
||||
if (!known.has(name) || usages.has(name)) return;
|
||||
const line = fs.readFileSync(file, 'utf8').slice(0, index).split('\n').length;
|
||||
usages.set(name, `${path.relative(root, file)}:${line}`);
|
||||
};
|
||||
|
||||
for (const file of files) {
|
||||
const source = fs.readFileSync(file, 'utf8');
|
||||
// 字符串形式：icon: 'Odometer' / :icon="'Search'" / :prefix-icon="'Lock'" / 菜单配置数组
|
||||
for (const match of source.matchAll(/['"]([A-Z][A-Za-z0-9]*)['"]/g)) {
|
||||
record(match[1], file, match.index ?? 0);
|
||||
}
|
||||
// 标签形式：<el-icon><School /></el-icon> / <Loading />
|
||||
for (const match of source.matchAll(/<([A-Z][A-Za-z0-9]*)[\s/>]/g)) {
|
||||
record(match[1], file, match.index ?? 0);
|
||||
}
|
||||
}
|
||||
return usages;
|
||||
}
|
||||
|
||||
const known = await loadKnownIconNames();
|
||||
let failed = false;
|
||||
|
||||
for (const target of TARGETS) {
|
||||
const registered = readRegistry(target.registry);
|
||||
// 扫描时排除注册表自身：否则报出的「首次出现位置」会是注册表那一行，指不到真正的使用点
|
||||
const files = collectFiles(target.sources).filter((file) => file !== target.registry);
|
||||
const usages = collectUsages(files, known);
|
||||
|
||||
const missing = [...usages.keys()].filter((name) => !registered.has(name)).sort();
|
||||
const unused = [...registered].filter((name) => !usages.has(name)).sort();
|
||||
|
||||
if (missing.length > 0) {
|
||||
failed = true;
|
||||
console.error(`\n[check-icons] ✗ ${target.name}：以下图标被使用但未注册（界面会渲染成空白）`);
|
||||
for (const name of missing) {
|
||||
console.error(` - ${name} （${usages.get(name)}）`);
|
||||
}
|
||||
console.error(` 请把它们加进 ${path.relative(root, target.registry)} 的 APP_ICONS 对象与 import 列表。`);
|
||||
} else {
|
||||
console.log(`[check-icons] ✓ ${target.name}：用到 ${usages.size} 个图标，全部已注册`);
|
||||
}
|
||||
|
||||
if (unused.length > 0) {
|
||||
// 不是错误：多注册一个只多 1KB 左右。列出来是为了让名单别无限膨胀。
|
||||
console.log(`[check-icons] 提示：注册了但当前未使用的图标 —— ${unused.join('、')}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (failed) process.exit(1);
|
||||
console.log('[check-icons] 图标注册表校验通过');
|
||||
+383
-26
@@ -1,16 +1,25 @@
|
||||
/**
|
||||
* 服务端 + Web 管理端 生产打包脚本：pnpm dist:server
|
||||
*
|
||||
* 产出：
|
||||
* 产出（Windows）：
|
||||
* release-server/classhelper-server/ 可直接运行的免安装目录
|
||||
* release-server/班级小助手服务端-<版本>-x64-setup.exe Windows 安装程序（NSIS）
|
||||
*
|
||||
* 打包策略（面向"双击即可用、目标机无需安装 Node"）：
|
||||
* 1. 内置 Node 运行时（复制本机 node.exe）—— 目标机无需安装 Node.js
|
||||
* 产出（Linux，加 --platform linux，即 pnpm dist:server:linux）：
|
||||
* release-server/classhelper-server-linux-x64-<版本>.tar.gz Linux 一键安装器的输入
|
||||
* release-server/classhelper-server-linux-x64-<版本>.tar.gz.sha256
|
||||
*
|
||||
* 为什么 Linux 包要在 Linux 上构建：`@libsql/linux-x64-gnu`、`@prisma/adapter-libsql` 都是
|
||||
* 平台相关依赖，在 Windows 上 npm install 出来的 node_modules 装到 Linux 跑不起来。
|
||||
* 仓库里的 .github/workflows/release-linux-server.yml 用 ubuntu runner 出这个包。
|
||||
*
|
||||
* 打包策略（面向"双击即可用、目标机无需安装 Node"，Linux 侧同理）：
|
||||
* 1. 内置 Node 运行时（Windows 复制本机 node.exe；Linux 由安装器下载官方/glibc-217 版 Node）
|
||||
* 2. 依赖用 npm 安装为真实目录（非 pnpm 软链），保证可整体拷贝到别的机器
|
||||
* 3. 后端使用 tsc 构建产物（ESM），Web 管理端使用 Vite 构建产物
|
||||
* 4. 首次启动自动执行迁移（AUTO_MIGRATE=true）+ 自动生成 JWT 密钥 + PID 文件
|
||||
* 5. 用 electron-builder 自带的 NSIS（makensis）生成安装程序
|
||||
* 5. Windows 用 electron-builder 自带的 NSIS（makensis）生成安装程序；
|
||||
* Linux 打 tar.gz，交给 deploy/install.sh 安装
|
||||
*/
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import crypto from 'node:crypto';
|
||||
@@ -22,12 +31,25 @@ import { resolveNodeRuntime } from './lib/node-runtime.mjs';
|
||||
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
||||
const serverDir = path.join(root, 'packages', 'server');
|
||||
const webDir = path.join(root, 'packages', 'web-admin');
|
||||
const deployDir = path.join(root, 'deploy');
|
||||
const outRoot = path.join(root, 'release-server');
|
||||
const staging = path.join(outRoot, 'classhelper-server');
|
||||
|
||||
/** win = 免安装目录 + NSIS 安装程序；linux = 带运维工具的 tar.gz（给 deploy/install.sh 用） */
|
||||
const PLATFORM = (() => {
|
||||
const index = process.argv.indexOf('--platform');
|
||||
const value = index >= 0 ? process.argv[index + 1] : process.platform === 'win32' ? 'win' : 'linux';
|
||||
if (!['win', 'linux'].includes(value)) throw new Error(`--platform 只支持 win / linux（收到 ${value}）`);
|
||||
return value;
|
||||
})();
|
||||
const isLinux = PLATFORM === 'linux';
|
||||
|
||||
const staging = path.join(outRoot, isLinux ? 'classhelper-server-linux-x64' : 'classhelper-server');
|
||||
|
||||
const VERSION = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version;
|
||||
const PRODUCT = '班级小助手服务端';
|
||||
const PORT = '4000';
|
||||
const LINUX_ARCH = 'x64';
|
||||
const LINUX_TARBALL = path.join(outRoot, `classhelper-server-linux-${LINUX_ARCH}-${VERSION}.tar.gz`);
|
||||
|
||||
const log = (message) => console.log(`[dist:server] ${message}`);
|
||||
|
||||
@@ -43,6 +65,20 @@ const run = (command, args, options = {}) => {
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* 交叉构建：在非 Linux 机器上出 Linux 包。
|
||||
*
|
||||
* npm ≥9.6 支持 `--os` / `--cpu`，会按**目标平台**解析可选依赖，因此
|
||||
* `@libsql/linux-x64-gnu` 这类"按平台分发"的包能装进来（默认只会装宿主平台的 win32-x64-msvc）。
|
||||
*
|
||||
* 什么时候能用：本地想快速打一个包出来测安装/运维流程时。
|
||||
* **正式发布仍应在 Linux 上构建**（CI 的 workflow 就是干这个的）：交叉构建时
|
||||
* prisma CLI 的原生引擎（`db push` / `generate` 用，即 Web 端「数据库一键切换」那条链路）
|
||||
* 是宿主平台下载的，Linux 上不一定能跑；`dist:server:linux` 在非 Linux 上会明确告警。
|
||||
*/
|
||||
const CROSS_BUILD = isLinux && process.platform !== 'linux';
|
||||
const CROSS_TARGET = { os: 'linux', cpu: 'x64' };
|
||||
|
||||
/* ------------------------------------------------------------ 1. 前置构建 */
|
||||
|
||||
function ensureBuilds() {
|
||||
@@ -130,8 +166,13 @@ function installDependencies() {
|
||||
writeRuntimeManifest();
|
||||
|
||||
const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
|
||||
const args = ['install', '--omit=dev', '--no-audit', '--no-fund', '--loglevel=error'];
|
||||
if (CROSS_BUILD) {
|
||||
args.push(`--os=${CROSS_TARGET.os}`, `--cpu=${CROSS_TARGET.cpu}`);
|
||||
log(`交叉构建：按目标平台 ${CROSS_TARGET.os}-${CROSS_TARGET.cpu} 解析依赖（正式发布请在 Linux 上构建）`);
|
||||
}
|
||||
log('安装生产依赖（npm install --omit=dev，真实目录，便于整体拷贝）...');
|
||||
run(npmCmd, ['install', '--omit=dev', '--no-audit', '--no-fund', '--loglevel=error'], {
|
||||
run(npmCmd, args, {
|
||||
cwd: staging,
|
||||
env: {
|
||||
...process.env,
|
||||
@@ -150,6 +191,8 @@ function copyRecursive(from, to) {
|
||||
|
||||
function buildRuntime() {
|
||||
// 后端代码：保留 dist 层级，保证代码里 serverRoot 的计算（../..）与开发环境一致
|
||||
// 注：dist 里没有 .d.ts / *.map —— packages/server/tsconfig.build.json 显式关掉了它们
|
||||
//（那三样占了原 dist 的 82%，运行时一个都用不到，见 AGENTS.md §5 第 54 条）。
|
||||
copyRecursive(path.join(serverDir, 'dist'), path.join(staging, 'server', 'dist'));
|
||||
// 迁移文件（首次启动 AUTO_MIGRATE 使用）
|
||||
copyRecursive(
|
||||
@@ -160,6 +203,9 @@ function buildRuntime() {
|
||||
// schema.prisma —— 切换时改写 provider 后供 prisma generate / db push 使用
|
||||
// prisma.config.ts —— Prisma 7 的 CLI 配置（连接串来自子进程环境变量）
|
||||
// tsconfig.generate.json —— generate 产出的是 .ts，切换后用它编译进 dist/generated
|
||||
// 注意：tsconfig.generate.json **故意是自包含的**（不 extends tsconfig.json/tsconfig.base.json），
|
||||
// 因为安装目录里只有 server/ 一层，那两级基配置不在包里 —— 一旦 extends 就会在打包形态下
|
||||
// 报 TS5083「Cannot read file .../server/tsconfig.json」，数据库「一键切换」直接走不到底。
|
||||
for (const file of ['schema.prisma']) {
|
||||
fs.copyFileSync(path.join(serverDir, 'prisma', file), path.join(staging, 'server', 'prisma', file));
|
||||
}
|
||||
@@ -191,10 +237,17 @@ function buildRuntime() {
|
||||
// Web 管理端
|
||||
copyRecursive(path.join(webDir, 'dist'), path.join(staging, 'web'));
|
||||
|
||||
// Node 运行时（必须是真正的 node.exe，不能用宿主 Electron 可执行文件）
|
||||
const nodeRuntime = resolveNodeRuntime();
|
||||
copyRecursive(nodeRuntime.path, path.join(staging, 'node.exe'));
|
||||
log(`内置 Node 运行时：${nodeRuntime.path}（${nodeRuntime.version}）`);
|
||||
if (isLinux) {
|
||||
// Linux 包不带 Node 二进制：官方 linux-x64 构建绑 glibc 版本（老系统要 glibc-217 变体），
|
||||
// 由 deploy/install.sh 在目标机上按 glibc 自动挑一个下载。这里只留占位目录。
|
||||
fs.mkdirSync(path.join(staging, 'runtime'), { recursive: true });
|
||||
fs.writeFileSync(path.join(staging, 'VERSION'), `${VERSION}\n`, 'utf8');
|
||||
} else {
|
||||
// Node 运行时（必须是真正的 node.exe，不能用宿主 Electron 可执行文件）
|
||||
const nodeRuntime = resolveNodeRuntime();
|
||||
copyRecursive(nodeRuntime.path, path.join(staging, 'node.exe'));
|
||||
log(`内置 Node 运行时：${nodeRuntime.path}（${nodeRuntime.version}）`);
|
||||
}
|
||||
|
||||
// 数据目录：强制清空，避免把打包机上测试用的数据库带进安装包
|
||||
fs.rmSync(path.join(staging, 'data'), { recursive: true, force: true });
|
||||
@@ -202,6 +255,176 @@ function buildRuntime() {
|
||||
fs.mkdirSync(path.join(staging, 'logs'), { recursive: true });
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ 3.5 运行时裁剪 */
|
||||
|
||||
/** 递归统计文件大小（字节）；目标既可以是目录也可以是单个文件 */
|
||||
function dirSize(target) {
|
||||
if (!fs.existsSync(target)) return 0;
|
||||
const stat = fs.statSync(target);
|
||||
if (stat.isFile()) return stat.size;
|
||||
let total = 0;
|
||||
const walk = (dir) => {
|
||||
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) walk(full);
|
||||
else total += fs.statSync(full).size;
|
||||
}
|
||||
};
|
||||
walk(target);
|
||||
return total;
|
||||
}
|
||||
|
||||
const sizeMb = (target) => Math.round(dirSize(target) / 1024 / 1024);
|
||||
|
||||
/**
|
||||
* 运行时裁剪：删掉**运行时永远加载不到**的静态载荷。
|
||||
*
|
||||
* 为什么值得单独立一步：安装包的 node_modules 实测 380MB，而其中绝大部分是
|
||||
* Prisma 为「它支持的所有数据库方言」准备的查询编译器副本 —— 本项目的 schema
|
||||
* 只在 sqlite / mysql 之间切换（见 docs/mysql.md、`lib/db.ts` 的 DatabaseProvider），
|
||||
* 其余方言（postgresql / cockroachdb / sqlserver）的 wasm 一个字节都用不上。
|
||||
*
|
||||
* 原则：只删数据文件与文档，**不碰任何会被 require 的入口**；每一条都写明依据。
|
||||
* 改这里之前先看「为什么安全」，改完务必按 AGENTS.md §8 的清单复验一次
|
||||
* （尤其是数据库管理模块的「生成客户端 / 一键切换」—— 它是唯一会调用 Prisma CLI 的地方）。
|
||||
*/
|
||||
function pruneRuntime() {
|
||||
const nodeModules = path.join(staging, 'node_modules');
|
||||
if (!fs.existsSync(nodeModules)) return;
|
||||
|
||||
const before = sizeMb(staging);
|
||||
const removed = [];
|
||||
const drop = (target, note) => {
|
||||
if (!fs.existsSync(target)) return;
|
||||
const size = dirSize(target);
|
||||
fs.rmSync(target, { recursive: true, force: true });
|
||||
removed.push({ path: path.relative(staging, target), size, note });
|
||||
};
|
||||
|
||||
/* (a) @prisma/client/runtime —— 只留 sqlite / mysql 的 ESM 方言包
|
||||
*
|
||||
* 依据：`src/generated/prisma/internal/class.ts` 里的 queryCompiler 是**生成期按
|
||||
* provider 写死**的动态 import（当前是 `query_compiler_fast_bg.sqlite.mjs` +
|
||||
* `query_compiler_fast_bg.sqlite.wasm-base64.mjs`）；切到 MySQL 时重新 generate 只会
|
||||
* 指向 `*.mysql.*`。而：
|
||||
* - postgresql / cockroachdb / sqlserver 与全部 `_small_bg` 变体：本产品不支持，永不加载；
|
||||
* - `.wasm-base64.js`（CJS 版）：服务端是 ESM（`type: module`），只走 `.mjs`；
|
||||
* - `.map`：Node 没开 `--enable-source-maps`，不会读。
|
||||
* 实测这一步省下约 60MB。 */
|
||||
const clientRuntime = path.join(nodeModules, '@prisma', 'client', 'runtime');
|
||||
if (fs.existsSync(clientRuntime)) {
|
||||
const keep = new Set([
|
||||
'client.js',
|
||||
'client.mjs',
|
||||
'client.d.ts',
|
||||
'client.d.mts',
|
||||
'wasm-compiler-edge.js',
|
||||
'wasm-compiler-edge.mjs',
|
||||
'wasm-compiler-edge.d.ts',
|
||||
'wasm-compiler-edge.d.mts',
|
||||
'query_compiler_fast_bg.sqlite.js',
|
||||
'query_compiler_fast_bg.sqlite.mjs',
|
||||
'query_compiler_fast_bg.mysql.js',
|
||||
'query_compiler_fast_bg.mysql.mjs',
|
||||
'query_compiler_fast_bg.sqlite.wasm-base64.mjs',
|
||||
'query_compiler_fast_bg.mysql.wasm-base64.mjs',
|
||||
]);
|
||||
for (const entry of fs.readdirSync(clientRuntime)) {
|
||||
if (keep.has(entry)) continue;
|
||||
drop(path.join(clientRuntime, entry), '@prisma/client/runtime：只保留 sqlite/mysql 的 ESM 方言包');
|
||||
}
|
||||
}
|
||||
|
||||
/* (b) prisma CLI 的 build/ —— 同样只留 sqlite / mysql
|
||||
*
|
||||
* 依据：部署形态里 Prisma CLI 只被数据库管理模块用于 `generate` 与 `db push`，
|
||||
* 两者都按当前 provider 选用对应的查询编译器 wasm。 */
|
||||
const prismaBuild = path.join(nodeModules, 'prisma', 'build');
|
||||
if (fs.existsSync(prismaBuild)) {
|
||||
const unusedDialect =
|
||||
/^query_compiler_(?:fast|small)_bg\.(?:postgresql|cockroachdb|sqlserver)\.(?:js|mjs|wasm)$/;
|
||||
for (const entry of fs.readdirSync(prismaBuild)) {
|
||||
if (!unusedDialect.test(entry)) continue;
|
||||
drop(path.join(prismaBuild, entry), 'Prisma CLI：只保留 sqlite/mysql 的查询编译器');
|
||||
}
|
||||
}
|
||||
|
||||
/* (c) 通用静态载荷：sourcemap / 文档 / 测试与示例目录
|
||||
*
|
||||
* 依据：Node 不读 sourcemap；文档与测试夹具不会被 require。
|
||||
* **不要**顺手删 `*.d.ts`：数据库「一键切换」要跑
|
||||
* `tsc -p tsconfig.generate.json` 编译重新生成的 Prisma 客户端，
|
||||
* 那一步需要 `@prisma/client` 与 `@types/*` 的类型声明。
|
||||
*
|
||||
* 两条硬护栏（都踩过）：
|
||||
* 1) **整棵 `@types/**` 不参与裁剪** —— 类型包里的 `test/`、`docs/` 是真实的声明文件
|
||||
* （如 `@types/node/test/reporters.d.ts` 被 `test.d.ts` 引用），按"测试目录"删掉会让
|
||||
* tsc 报 TS6053；
|
||||
* 2) 名字命中 DROP_DIRS 的目录，只要里面含 `*.d.ts` 就整个跳过 —— 同名目录在不同包里
|
||||
* 含义完全不同，不能只看名字。 */
|
||||
const DROP_DIRS = new Set([
|
||||
'test',
|
||||
'tests',
|
||||
'__tests__',
|
||||
'__mocks__',
|
||||
'example',
|
||||
'examples',
|
||||
'docs',
|
||||
'benchmark',
|
||||
]);
|
||||
const isDroppableDoc = (name) =>
|
||||
/\.(?:md|markdown)$/i.test(name) && !/^(?:license|licence|notice|copying|third[-_]?party)/i.test(name);
|
||||
/** 目录下（递归）是否存在类型声明文件 */
|
||||
const containsDts = (dir) => {
|
||||
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
if (entry.isDirectory()) {
|
||||
if (containsDts(path.join(dir, entry.name))) return true;
|
||||
} else if (entry.name.endsWith('.d.ts')) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
return false;
|
||||
};
|
||||
// 工作区内部包（@classhelper/shared）是手工放的；@types 整棵保留（理由见上）
|
||||
const protectedRoots = new Set([path.join(nodeModules, '@classhelper'), path.join(nodeModules, '@types')]);
|
||||
const walkPrune = (dir) => {
|
||||
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (protectedRoots.has(full)) continue;
|
||||
if (entry.isDirectory()) {
|
||||
if (DROP_DIRS.has(entry.name) && !containsDts(full)) {
|
||||
drop(full, 'node_modules 里的测试/示例/文档目录');
|
||||
continue;
|
||||
}
|
||||
walkPrune(full);
|
||||
continue;
|
||||
}
|
||||
if (/\.map$/i.test(entry.name)) {
|
||||
drop(full, 'node_modules 里的 sourcemap');
|
||||
} else if (isDroppableDoc(entry.name)) {
|
||||
drop(full, 'node_modules 里的说明文档');
|
||||
}
|
||||
}
|
||||
};
|
||||
walkPrune(nodeModules);
|
||||
|
||||
const after = sizeMb(staging);
|
||||
const saved = before - after;
|
||||
if (removed.length === 0) {
|
||||
log('运行时裁剪：没有可裁剪的内容（跳过）');
|
||||
return;
|
||||
}
|
||||
// 逐类汇总，便于回归时对照有没有误删
|
||||
const byNote = new Map();
|
||||
for (const item of removed) {
|
||||
byNote.set(item.note, (byNote.get(item.note) ?? 0) + item.size);
|
||||
}
|
||||
log(`运行时裁剪：删除 ${removed.length} 项，节省约 ${Math.round(saved)} MB（${before}MB -> ${after}MB）`);
|
||||
for (const [note, bytes] of [...byNote.entries()].sort((a, b) => b[1] - a[1])) {
|
||||
log(` · ${(bytes / 1024 / 1024).toFixed(1)}MB ${note}`);
|
||||
}
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ 4. 配置与脚本 */
|
||||
|
||||
function writeEnvironmentFile() {
|
||||
@@ -236,7 +459,8 @@ LOG_LEVEL=info
|
||||
|
||||
# 可选项
|
||||
BCRYPT_ROUNDS=10
|
||||
DEFAULT_STUDENT_PASSWORD=123456
|
||||
# 新建班级的初始密码（学生端用「班级码 + 班级密码」登录，没有个人学生账号）
|
||||
DEFAULT_CLASS_PASSWORD=123456
|
||||
TERM_START_DATE=
|
||||
`;
|
||||
fs.writeFileSync(path.join(staging, '.env'), content, 'utf8');
|
||||
@@ -386,7 +610,8 @@ function writeReadme() {
|
||||
管理员 admin / admin123
|
||||
教师 teacher1 / teacher123、teacher2 / teacher123
|
||||
班级 班级码 G101/G102/G203 + 班级密码 123456（学生端桌面客户端使用）
|
||||
个人 student01 ~ student15 / student123（个人学生账号，接口向后兼容）
|
||||
说明 学生没有个人账号：学生只是名单记录（成绩/未交/叫人/已读都按名单走），
|
||||
学生端统一用「班级码 + 班级密码」登录。
|
||||
|
||||
三、目录说明
|
||||
server\\ 后端程序（server\\dist\\index.js 为入口）
|
||||
@@ -443,6 +668,117 @@ function writeReadme() {
|
||||
|
||||
/* ------------------------------------------------------------ 5. NSIS 安装程序 */
|
||||
|
||||
/* ------------------------------------------------------------ 5. Linux 专属内容 */
|
||||
|
||||
/**
|
||||
* Linux 包额外要带的东西：运维命令本体、安装器模板、systemd / logrotate / profile.d、
|
||||
* Docker 形态的 Dockerfile、Nginx 样例。
|
||||
*
|
||||
* 布局（deploy/install.sh 依赖它，改动要同步改那里）：
|
||||
* bin/classhelper 运维命令（安装到 /usr/local/bin 的软链指向它）
|
||||
* tools/admin-cli.mjs 离线改密 / 备份快照工具
|
||||
* classhelper.service.template systemd 单元模板（__NODE__/__DIR__/… 占位符）
|
||||
* systemd/classhelper-backup.* classhelper backup schedule 用的定时器
|
||||
* logrotate.d/、profile.d/ 安装时拷到 /etc 下
|
||||
* Dockerfile --mode docker 时用它构建镜像
|
||||
* nginx.conf 反代样例（--with-nginx）
|
||||
*/
|
||||
function copyLinuxExtras() {
|
||||
const copyFile = (from, to, mode) => {
|
||||
fs.mkdirSync(path.dirname(to), { recursive: true });
|
||||
fs.copyFileSync(from, to);
|
||||
if (mode) fs.chmodSync(to, mode);
|
||||
};
|
||||
const copyDir = (from, to) => copyRecursive(from, to);
|
||||
|
||||
// 目标路径就是安装目录里的相对路径 —— install.sh 的 place_program_files 按这几个名字铺开，
|
||||
// 名字对不上就会在安装时才暴露（而且症状是"命令找不到"，不是构建报错）。
|
||||
const required = [
|
||||
['bin/classhelper', path.join(deployDir, 'classhelper'), 0o755],
|
||||
['tools/admin-cli.mjs', path.join(deployDir, 'tools', 'admin-cli.mjs')],
|
||||
['classhelper.service.template', path.join(deployDir, 'classhelper.service')],
|
||||
['Dockerfile', path.join(deployDir, 'Dockerfile.linux-package')],
|
||||
['nginx.conf', path.join(deployDir, 'nginx.conf')],
|
||||
];
|
||||
for (const [target, source, mode] of required) {
|
||||
if (!fs.existsSync(source)) throw new Error(`缺少打包所需文件：${path.relative(root, source)}`);
|
||||
copyFile(source, path.join(staging, target), mode);
|
||||
}
|
||||
// Windows 上 chmod 只影响只读位，打出来的 tar 里/bin/classhelper 的可执行位靠 install.sh 兜底
|
||||
// （place_program_files 里有 chmod +x），这里只是让在 Linux 上构建时也带上正确的权限位。
|
||||
if (process.platform !== 'win32') fs.chmodSync(path.join(staging, 'bin', 'classhelper'), 0o755);
|
||||
|
||||
for (const [target, source] of [
|
||||
['systemd', path.join(deployDir, 'systemd')],
|
||||
['logrotate.d', path.join(deployDir, 'logrotate.d')],
|
||||
['profile.d', path.join(deployDir, 'profile.d')],
|
||||
]) {
|
||||
if (fs.existsSync(source)) copyDir(source, path.join(staging, target));
|
||||
}
|
||||
log('已注入运维工具与模板（bin/classhelper、tools/、systemd/、Dockerfile 等）');
|
||||
}
|
||||
|
||||
function writeLinuxReadme() {
|
||||
const content = `${PRODUCT} v${VERSION}（Linux ${LINUX_ARCH}）
|
||||
|
||||
一、这是什么
|
||||
这是给 deploy/install.sh 用的安装包，不能直接双击运行。安装方式：
|
||||
|
||||
curl -fsSL -O https://github.com/.../classhelper-server-linux-${LINUX_ARCH}-${VERSION}.tar.gz
|
||||
sudo bash install.sh --package ./classhelper-server-linux-${LINUX_ARCH}-${VERSION}.tar.gz
|
||||
|
||||
或者在有本安装包的机器上：
|
||||
sudo bash install.sh --package /path/to/classhelper-server-linux-${LINUX_ARCH}-${VERSION}.tar.gz
|
||||
|
||||
二、包内目录
|
||||
server/ 后端程序（server/dist/index.js 为入口）
|
||||
server/prisma/ 迁移 SQL（首启动 AUTO_MIGRATE=true 时自动执行）
|
||||
web/ Web 管理端（由后端直接托管）
|
||||
node_modules/ 生产依赖（linux 真实目录，可直接整体拷贝）
|
||||
tools/ 运维工具（admin-cli.mjs：离线改密、数据库一致性快照）
|
||||
bin/classhelper 运维命令（installation 时会软链到 /usr/local/bin/classhelper）
|
||||
systemd/ classhelper-backup.{service,timer}（定时备份用）
|
||||
logrotate.d/ profile.d/ 安装时拷到 /etc 下
|
||||
Dockerfile --mode docker 时用它构建镜像
|
||||
VERSION 版本号
|
||||
|
||||
三、安装后的默认账号（首次启动自动创建）
|
||||
管理员 admin / admin123（安装器里设置初始密码则用它）
|
||||
学生端 班级码 + 班级密码（学生没有个人账号）
|
||||
|
||||
四、常用运维命令（安装后）
|
||||
classhelper status / doctor / password admin / backup / upgrade / rollback / logs -f
|
||||
|
||||
五、默认路径
|
||||
安装目录 /opt/classhelper（安装时可改）
|
||||
配置 /etc/classhelper/config.env（权限 600；安装目录里的 .env 是它的软链）
|
||||
数据 <安装目录>/data
|
||||
日志 /var/log/classhelper/（安装日志 + 审计日志）
|
||||
备份 /var/backups/classhelper/
|
||||
|
||||
六、安全建议
|
||||
- 立刻修改默认密码：classhelper password admin
|
||||
- 公网访问请在前面加 Nginx/Caddy 并启用 HTTPS，并把配置里的 CORS_ORIGIN 收敛到你的域名
|
||||
- 定期备份：classhelper backup schedule daily
|
||||
- 更换 JWT_SECRET 会让所有用户重新登录（classhelper key rotate）
|
||||
`;
|
||||
fs.writeFileSync(path.join(staging, 'README.txt'), content, 'utf8');
|
||||
}
|
||||
|
||||
/** 打 tar.gz 并输出 sha256（classhelper upgrade 会校验这个哈希） */
|
||||
function packLinuxTarball() {
|
||||
fs.rmSync(LINUX_TARBALL, { force: true });
|
||||
const topDir = path.basename(staging); // tar 里套一层目录，安装器用 --strip-components=1 展开
|
||||
log(`打包 ${path.relative(root, LINUX_TARBALL)} ...`);
|
||||
run('tar', ['-czf', LINUX_TARBALL, '-C', path.dirname(staging), topDir]);
|
||||
|
||||
const digest = crypto.createHash('sha256').update(fs.readFileSync(LINUX_TARBALL)).digest('hex');
|
||||
const shaFile = `${LINUX_TARBALL}.sha256`;
|
||||
fs.writeFileSync(shaFile, `${digest} ${path.basename(LINUX_TARBALL)}\n`, 'utf8');
|
||||
log(`sha256：${digest}`);
|
||||
return { file: LINUX_TARBALL, shaFile, digest };
|
||||
}
|
||||
|
||||
function findMakensis() {
|
||||
const cacheRoot = path.join(root, '.cache', 'electron-builder');
|
||||
const candidates = [];
|
||||
@@ -500,7 +836,7 @@ function buildInstaller() {
|
||||
/* ------------------------------------------------------------ 主流程 */
|
||||
|
||||
function main() {
|
||||
log(`版本 ${VERSION}`);
|
||||
log(`版本 ${VERSION}｜平台 ${PLATFORM}`);
|
||||
ensureBuilds();
|
||||
|
||||
// 迭代打包时可加 --reuse-deps 复用已安装的 node_modules，跳过 2 分钟的 npm install
|
||||
@@ -526,25 +862,46 @@ function main() {
|
||||
installDependencies();
|
||||
}
|
||||
buildRuntime();
|
||||
pruneRuntime();
|
||||
|
||||
if (isLinux) {
|
||||
copyLinuxExtras();
|
||||
writeLinuxReadme();
|
||||
// 交叉构建的包留个标记：`classhelper doctor` 会据此提醒"这个包不是在 Linux 上打的"。
|
||||
// 不静默 —— 这个包能装能跑，但 Web 端「数据库一键切换」依赖 prisma CLI 的**原生 schema engine**，
|
||||
// 而 npm 的 postinstall 只下宿主平台那一个（交叉包里就是 schema-engine-windows.exe）。
|
||||
if (CROSS_BUILD) {
|
||||
fs.writeFileSync(
|
||||
path.join(staging, '.cross-built'),
|
||||
`cross-built on ${process.platform}-${process.arch} at ${new Date().toISOString()}\n`,
|
||||
'utf8',
|
||||
);
|
||||
}
|
||||
const { file, shaFile } = packLinuxTarball();
|
||||
if (CROSS_BUILD) {
|
||||
log('');
|
||||
log('⚠ 这是**交叉构建**出来的包（在非 Linux 机器上打的），没有在 Linux 上实机验证过：');
|
||||
log(' · 已确认没问题：@libsql/linux-x64-gnu 与 linux-x64-musl 都在包内、没有任何 win32 依赖，');
|
||||
log(' 服务端本体（Node + libsql + express + socket.io）在 Linux 上可正常跑；');
|
||||
log(' · 存疑的一处：Web 端「数据库管理 → 一键切换数据库」会调 prisma CLI 的 schema engine，');
|
||||
log(' CLI 在运行期按平台扫 @prisma/engines/schema-engine-debian-openssl-3.0.x 这类路径，');
|
||||
log(' 而交叉包里只有宿主平台的 schema-engine-windows.exe → 这一步可能失败（其余功能不受影响）。');
|
||||
log(' · 包内已写入 .cross-built 标记，classhelper doctor 会提示这一点。');
|
||||
log(' 正式发布请用 .github/workflows/release-linux-server.yml（ubuntu runner）出包。');
|
||||
log('');
|
||||
}
|
||||
log(`Linux 安装包：${path.relative(root, file)}（${sizeMb(LINUX_TARBALL)} MB）`);
|
||||
log(`校验文件：${path.relative(root, shaFile)}`);
|
||||
log('完成。部署方式：sudo bash deploy/install.sh --package <上面的 tar.gz>');
|
||||
return;
|
||||
}
|
||||
|
||||
writeEnvironmentFile();
|
||||
writeRuntimeScripts();
|
||||
writeReadme();
|
||||
|
||||
const installer = buildInstaller();
|
||||
|
||||
const sizeMb = (target) => {
|
||||
let total = 0;
|
||||
const walk = (dir) => {
|
||||
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) walk(full);
|
||||
else total += fs.statSync(full).size;
|
||||
}
|
||||
};
|
||||
walk(target);
|
||||
return Math.round(total / 1024 / 1024);
|
||||
};
|
||||
|
||||
log(`免安装目录：${path.relative(root, staging)}（${sizeMb(staging)} MB）`);
|
||||
if (installer)
|
||||
log(
|
||||
|
||||
@@ -265,6 +265,72 @@ async function runAdminTeacherChecks(win) {
|
||||
Boolean(removed?.ok),
|
||||
`${removed?.ok ? `已删除 ${username}` : `原因=${removed?.reason ?? '-'}`}`,
|
||||
);
|
||||
|
||||
// 4) 更新检查：顶栏用户菜单 →「检查更新」→ 弹窗渲染出结果
|
||||
//
|
||||
// 只断言"入口可用 + 弹窗给出了结论"，**刻意不断言一定有新版本** ——
|
||||
// 那会把用例绑死在外网可达上（机房服务器查不到 GitHub 是常态，"暂时无法检查更新"是设计内的结果）。
|
||||
// 判据用弹窗内的文案（与本脚本其余用例一致）：data-test 打在 el-dialog / el-alert 上，
|
||||
// 是否透传到根元素取决于组件实现，不如文案直接。
|
||||
const updateCheck = await win.webContents.executeJavaScript(`(async () => {
|
||||
const chip = document.querySelector('[data-tour="user-chip"]');
|
||||
if (!chip) return { ok: false, reason: '顶栏找不到用户菜单' };
|
||||
chip.click();
|
||||
|
||||
const menuDeadline = Date.now() + 5000;
|
||||
let entry = null;
|
||||
while (Date.now() < menuDeadline && !entry) {
|
||||
entry = Array.from(document.querySelectorAll('.el-dropdown-menu__item')).find((node) =>
|
||||
(node.textContent ?? '').includes('检查更新'),
|
||||
);
|
||||
if (!entry) await new Promise((resolve) => setTimeout(resolve, 80));
|
||||
}
|
||||
if (!entry) return { ok: false, reason: '用户下拉菜单里没有「检查更新」' };
|
||||
entry.click();
|
||||
|
||||
const findDialog = () =>
|
||||
Array.from(document.querySelectorAll('.el-dialog')).find((node) =>
|
||||
(node.querySelector('.el-dialog__title')?.textContent ?? '').includes('检查更新'),
|
||||
);
|
||||
|
||||
const deadline = Date.now() + 25000;
|
||||
let state = '';
|
||||
while (Date.now() < deadline && !state) {
|
||||
const dialog = findDialog();
|
||||
const text = (dialog?.innerText ?? '').replace(/\\s+/g, ' ');
|
||||
if (text.includes('发现新版本')) state = '发现新版本';
|
||||
else if (text.includes('已是最新版本')) state = '已是最新版本';
|
||||
else if (text.includes('暂时无法检查更新')) state = '暂时无法检查更新';
|
||||
if (!state) await new Promise((resolve) => setTimeout(resolve, 150));
|
||||
}
|
||||
|
||||
// 收尾关闭，避免影响后续用例。Element Plus 关闭后 DOM 仍在（只把 .el-overlay 置成 display:none），
|
||||
// 而且淡出有过渡 —— 所以要轮询等遮罩真的隐藏，不能点完 sleep 一下就看（会误报"没关上"）。
|
||||
const dialog = findDialog();
|
||||
const closeButton = Array.from(dialog?.querySelectorAll('.el-dialog__footer button') ?? []).find(
|
||||
(node) => (node.textContent ?? '').trim() === '关闭',
|
||||
);
|
||||
closeButton?.click();
|
||||
|
||||
const closeDeadline = Date.now() + 5000;
|
||||
let closed = false;
|
||||
while (Date.now() < closeDeadline && !closed) {
|
||||
const overlay = findDialog()?.closest('.el-overlay');
|
||||
closed = !overlay || getComputedStyle(overlay).display === 'none';
|
||||
if (!closed) await new Promise((resolve) => setTimeout(resolve, 100));
|
||||
}
|
||||
|
||||
return state
|
||||
? { ok: true, state, closed }
|
||||
: { ok: false, reason: '弹窗 25 秒内没有渲染出结论' };
|
||||
})()`);
|
||||
record(
|
||||
'更新检查（管理员入口）：顶栏菜单 → 弹窗给出结论并可关闭',
|
||||
Boolean(updateCheck?.ok) && updateCheck?.closed !== false,
|
||||
`结论=${updateCheck?.state ?? '-'} 已关闭=${updateCheck?.closed ?? '-'}${
|
||||
updateCheck?.reason ? ` 原因=${updateCheck.reason}` : ''
|
||||
}`,
|
||||
);
|
||||
}
|
||||
|
||||
async function main() {
|
||||
@@ -743,6 +809,53 @@ async function main() {
|
||||
})()`);
|
||||
await sleep(300);
|
||||
|
||||
// 7.66 成绩图表：内置 SVG/CSS 图表（替换 echarts 后的回归）
|
||||
// echarts 全量引入曾让 GradesView 分块有 1.1MB；换成两个自包含组件后
|
||||
// 分块降到十几 KB。这里断言的是"真的画出来了"：柱子有实际高度、
|
||||
// 折线有路径、数据点落在不同的纵坐标上（否则说明比例换算写错了）。
|
||||
const gradeCharts = await win.webContents.executeJavaScript(`(() => {
|
||||
const bar = document.querySelector('.bar-chart');
|
||||
const line = document.querySelector('.line-chart');
|
||||
if (!bar || !line) return { ok: false, reason: '成绩页没有渲染图表容器' };
|
||||
const empty = Boolean(bar.querySelector('.bar-chart-empty'));
|
||||
const heights = Array.from(bar.querySelectorAll('.bar')).map(
|
||||
(node) => node.getBoundingClientRect().height,
|
||||
);
|
||||
const points = Array.from(line.querySelectorAll('.point'));
|
||||
const tops = new Set(points.map((node) => Math.round(node.getBoundingClientRect().top)));
|
||||
// 柱高比例要跟数据对上：最高的柱应接近绘图区高度，而不是全都贴地或全都顶格
|
||||
const track = bar.querySelector('.bar-track')?.getBoundingClientRect().height ?? 0;
|
||||
return {
|
||||
ok: true,
|
||||
empty,
|
||||
barCount: heights.length,
|
||||
drawnBars: heights.filter((h) => h > 0).length,
|
||||
distinctHeights: new Set(heights.map((h) => Math.round(h))).size,
|
||||
tallestRatio: track > 0 ? Number((Math.max(0, ...heights) / track).toFixed(2)) : 0,
|
||||
linePaths: line.querySelectorAll('svg path').length,
|
||||
pointCount: points.length,
|
||||
distinctTops: tops.size,
|
||||
};
|
||||
})()`);
|
||||
// 注意：某个等级人数为 0 时它的柱高本来就是 0（echarts 也一样），
|
||||
// 所以判据是「至少画出一根、且柱高有区分度」，不是「每根都有高度」。
|
||||
record(
|
||||
'成绩图表为内置 SVG/CSS（柱子按数据出高度、折线有路径与数据点）',
|
||||
Boolean(gradeCharts?.ok) &&
|
||||
gradeCharts?.empty === false &&
|
||||
gradeCharts?.barCount > 0 &&
|
||||
gradeCharts?.drawnBars >= 1 &&
|
||||
gradeCharts?.distinctHeights > 1 &&
|
||||
gradeCharts?.tallestRatio > 0.3 &&
|
||||
gradeCharts?.tallestRatio <= 1.01 &&
|
||||
gradeCharts?.linePaths >= 1 &&
|
||||
gradeCharts?.pointCount > 0 &&
|
||||
gradeCharts?.distinctTops > 1,
|
||||
`柱=${gradeCharts?.drawnBars}/${gradeCharts?.barCount}（高度种类=${gradeCharts?.distinctHeights} 最高占绘图区=${gradeCharts?.tallestRatio}）` +
|
||||
` 折线路径=${gradeCharts?.linePaths} 数据点=${gradeCharts?.pointCount} 纵坐标种类=${gradeCharts?.distinctTops}` +
|
||||
`${gradeCharts?.reason ? ` 原因=${gradeCharts.reason}` : ''}`,
|
||||
);
|
||||
|
||||
// 7.7 ClassIsland 时间配置导入弹窗（班主任可见：粘贴 JSON → 解析预览 → 确认导入）
|
||||
// 7.7 ClassIsland 课程表导入弹窗（班主任可见：粘贴 JSON → 解析预览 → 单双周识别）
|
||||
// 注：需求调整后课表页只保留「导入 ClassIsland 课程表」入口（"导入时间配置"按钮已下线，
|
||||
|
||||
Reference in new issue
Block a user