diff --git a/AGENTS.md b/AGENTS.md index 6b4f3a0..2e3d429 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -432,7 +432,9 @@ pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版 git add -A && git commit -m "chore(release): <版本>" && git push origin master # ⑦ 开 Release(gh release create 会创建并推送 tag,从而触发 Linux 包的 CI;见下) -gh release create v<版本> --title "v<版本>" --generate-notes +# 正文用手写的更新日志,别只留 --generate-notes 的自动列表(见「每次发版必须一起交付的四样东西」) +gh release create v<版本> --title "ClassHelper v<版本>(<一句话定位>)" \ + --notes-file releases/ReleaseNotes-<版本>.md gh release upload v<版本> \ releases/client/<版本>/安装包/*.exe \ releases/classisland-plugin/<版本>/安装包/*.cipx \ @@ -478,6 +480,36 @@ gh workflow run release-linux-server.yml -f tag=v<版本> -f attach=true **已发布的版本号不要复用**:客户端把它记进「忽略此版本」,两端各有 30 分钟缓存 —— 同号换内容会让「检查更新」永久失灵。要修就 `pnpm version:bump patch` 发新号。 +#### 每次发版必须一起交付的四样东西 + +`pnpm dist:all` 只产出安装包。**每次版本迭代都要把这四样一起做掉**,少一样都算「发到一半」: + +| # | 交付物 | 落在哪 | 怎么做 | +| -- | ------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | +| ① | **更新日志** | GitHub Release 的正文 | 手写,草稿放 `releases/ReleaseNotes-<版本>.md`(与它描述的产物同一层),用 `gh release create/edit --notes-file` 发布。**不要**只挂 `--generate-notes` 的自动列表 | +| ② | **Linux 服务端包** | Release 上的 `classhelper-server-linux-x64-<版本>.tar.gz` | tag 推上去由 `release-linux-server.yml` 构建;**推完必须去 Actions 确认没红** | +| ③ | **文档** | `docs/reference.md`(功能说明 + 验收对照表)与相关章节 | 新增功能补对应小节;改交付形态一并改 §2 / §7 与 `docs/dev/*` | +| ④ | **官网与 README** | `website/index.html`(功能块)、`website/download.html`(兜底版本号)、`README.md`(功能清单) | 新功能补进功能块 / 清单;页面里的版本号由 `pnpm version:bump` 覆盖,不用手写 | + +更新日志的骨架照 1.2.0 / 1.3.0 那两份:**一句话定位 → 分节讲功能 → ⚠️ 升级须知(含自动应用的迁移)→ +验收表 → 产物表**。验收表里**只写真跑过的数字**,没跑就直说没跑,别照抄上一版的。 + +**② 有个很容易漏的坑:CI 是按 tag 的 ref 检出源码的**(`actions/checkout` 的 +`ref: ${{ steps.ref.outputs.tag }}`)。所以发完版又发现构建脚本(或任何影响出包的代码)要修时, +**光推 master 不够** —— CI 仍会拿旧 tag 的源码跑,必须把 tag 挪到修复后的提交: + +```bash +git tag -f v<版本> <修复后的提交> && git push --force origin v<版本> +``` + +tag 一变会自动重跑。v1.3.0 实测踩过:tag 指的那个提交里 `dist-server.mjs` 有个 bug +(见 §5 第 59 条 ④),CI 红了、Release 上少一个 Linux 包,而本地完全看不出来 —— +Windows 侧走的是另一条分支,`pnpm dist:server` 一直绿。 + +**推完 tag 去 `gh run list --limit 5` 看一眼。** `发布官网与文档站`(master 推送触发)与 +`发布 Linux 服务端安装包`(tag 推送触发)是两条独立流水线,**前者绿不代表后者出来了**; +失败用 `gh run view ` 定位到具体是哪一步。 + #### 官网与文档站怎么发布 **不用做任何事。** 推 master 时只要 `website/**`、`docs/**`、`scripts/build-pages.mjs` 或 diff --git a/README.md b/README.md index 9083959..1430eed 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,12 @@ ClassHelper是给中小学班级用的一套信息管理系统。
- [x] 成绩录入:单条 / 批量 / 表格导入,带等级分布与得分率统计 - [x] ClassIsland 联动:签发设备令牌、下发提醒、把课表镜像回教室大屏 - [x] 数据库管理:连接体检、备份与恢复、SQLite ⇄ MySQL 一键切换 +- [x] 权限组:39 个权限键,建组分配账号 —— 没分组的按角色默认生效,分组后只按组的并集算 +- [x] 客户端设备:每台教室机器的版本、在线状态与最后心跳;一键推送更新,可下发关机 / 重启 / 注销 / 锁屏 +- [x] 大模型助手:一句话解析成待确认的作业 / 通知 / 叫人,点确认才落库 +- [x] 通知与作业批量发布:勾多个班一次发完,个别班失败不影响其余班级 +- [x] 系统设置:开发者模式、运行诊断、开机自启开关(仅安装形态) +- [x] 关怀模式:字号与控件整体放大 - [x] 手机小屏适配,可「添加到主屏幕」当应用用 ### 教室里的桌面客户端 @@ -63,6 +69,7 @@ ClassHelper是给中小学班级用的一套信息管理系统。
- [x] 成绩总览:全班成绩表格 + 柱状图 + 等级分布 - [x] 教室机器可直接录入作业、勾选未交名单 - [x] 离线优先:断网回退 IndexedDB 缓存,恢复连接后自动同步 +- [x] 断网期间错过的通知,重新上线时补弹一次;渲染进程崩了会安静地自己重建窗口 - [x] 浅色 / 深色主题,跟随系统 ### 灵动岛(桌面通知浮窗) @@ -87,6 +94,7 @@ ClassHelper是给中小学班级用的一套信息管理系统。
- [x] Linux 一键安装 + `classhelper` 运维命令(systemd 托管,升级 / 回滚 / 备份) - [x] Docker Compose(MySQL 版与 SQLite 版各一份) - [x] SQLite 与 MySQL 一键切换,备份与跨库迁移共用同一份 JSON 快照 +- [x] 客户端批量更新不依赖外网:安装包由服务端下载缓存,教室机从服务端取,校验 sha256 后空闲时自动装 ## 软件截图 diff --git a/docs/dev/release.md b/docs/dev/release.md index fdb9355..7ad99c3 100644 --- a/docs/dev/release.md +++ b/docs/dev/release.md @@ -19,6 +19,21 @@ description: 改版本号、跑验收、打安装包、发 GitHub Release、发 | 要给别人一份新安装包 | 只在自己机器上跑 | | 插件单独发补丁(只动插件第 4 段版本号) | — | +## 每次发版必须一起交付的四样东西 + +打安装包只是其中一件。**少一样都算「发到一半」**: + +| # | 交付物 | 落在哪 | 怎么做 | +| -- | ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------------ | +| ① | **更新日志** | GitHub Release 的正文 | 手写,草稿放 `releases/ReleaseNotes-<版本>.md`,用 `--notes-file` 发布。别只挂自动生成的列表 | +| ② | **Linux 服务端包** | Release 上的 `classhelper-server-linux-x64-<版本>.tar.gz` | tag 推上去由 CI 构建;**推完去 Actions 确认没红**(见第 7 步) | +| ③ | **文档** | `docs/reference.md`(功能说明 + 验收对照表)与相关章节 | 新增功能补对应小节;改交付形态一并改第 2 章 / 第 7 章 | +| ④ | **官网与 README** | `website/index.html`、`website/download.html`、`README.md` | 新功能补进官网功能块与 README 功能清单;版本号由脚本覆盖 | + +更新日志的骨架(照 1.2.0 / 1.3.0 那两份写): +**一句话定位 → 分节讲功能 → ⚠️ 升级须知(含会自动应用的迁移)→ 验收表 → 产物表**。 +验收表里**只写真跑过的数字**,没跑就直说没跑,不要照抄上一版的。 + ## 版本号写在哪(14 处 / 12 个文件) 同一个版本号分散在 14 个落点上,**手工改必然漏一处**,而漏掉的那处不会报错: @@ -143,7 +158,7 @@ cp "releases/client/$V/安装包/"*-x64-portable.exe ".cache/release-staging/Cla cp "releases/server/$V/安装包/"*-x64-setup.exe ".cache/release-staging/ClassHelper-$V-x64-server-setup.exe" cp "releases/classisland-plugin/$V/安装包/ClassHelper.ClassIslandPlugin.cipx" .cache/release-staging/ -gh release create v$V --title "v$V" --generate-notes +gh release create v$V --title "ClassHelper v$V(<一句话定位>)" --notes-file "releases/ReleaseNotes-$V.md" gh release upload v$V .cache/release-staging/* "releases/SHA256SUMS-$V.txt" --clobber ``` @@ -173,6 +188,15 @@ gh release upload v$V .cache/release-staging/* "releases/SHA256SUMS-$V.txt" --cl gh workflow run release-linux-server.yml -f tag=v1.1.3 -f attach=true ``` +> **CI 是按 tag 的 ref 检出源码的。** 发完版又发现构建脚本(或任何影响出包的代码)要修时, +> **光推 master 不够** —— CI 仍会拿旧 tag 的源码跑,得把 tag 挪到修复后的提交: +> `git tag -f v<版本> <提交> && git push --force origin v<版本>`,tag 一变会自动重跑。 +> 1.3.0 实测踩过:tag 指的那个提交里打包脚本有个 bug,CI 红了、Release 上少一个 Linux 包, +> 而本地 `pnpm dist:server` 一直是绿的(Windows 侧走另一条分支)。 +> +> 另外,本页第 8 步的「官网与文档站」是**另一条**流水线(master 推送触发)—— +> 它绿不代表 Linux 包出来了,推完 tag 要去 `gh run list --limit 5` 看一眼。 + ### 8. 官网与文档站 **不用做任何事。** 推送 master 时只要 `website/**`、`docs/**`、`scripts/build-pages.mjs` 或 diff --git a/website/index.html b/website/index.html index f659181..67ff457 100644 --- a/website/index.html +++ b/website/index.html @@ -476,6 +476,34 @@ SQLite 与 MySQL 互相搬数据,中途失败会自动回滚 —— 现有的库不会被动到。

+
+

#权限

+

谁能做什么,点着勾

+

+ 建权限组、把账号分进去。没分组的按角色默认生效,分组之后只按组的并集算 —— 既能放权,也能收权。 +

+
+
+

#教室机器

+

每台机器一个身份

+

+ 版本、在线状态、最后心跳一眼看完;可以一键推送更新,也能下发关机、重启、注销、锁屏。 +

+
+
+

#大模型助手

+

说一句话就发出去

+

+ 它只把话解析成待确认的卡片,你点了才落库 —— 权限、上课时段、ClassIsland 推送还是原来那套。 +

+
+
+

#批量发布

+

勾几个班,一次发完

+

+ 通知与作业都能批量。个别班失败不影响其余班级,哪个班为什么没发出去会逐班写清楚。 +

+
@@ -515,6 +543,13 @@ 高度、宽度、圆角、字号、停靠位置、视觉风格都能调;越界的值在主进程统一夹紧。

+
+

#自愈

+

崩了会自己回来

+

+ 渲染进程挂了先安静地重建窗口;断网期间错过的通知,重新上线时补弹一次。 +

+