Files
ClassHelper/prompts/full-repo-audit-optimize-release.prompt.md
T

150 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ClassHelper 全仓审计、优化与本地交付
> 先读根 AGENTS.md,再完成本文件与[审计清单](full-repo-audit-checklist.md)。
> 以现场源码和本次命令为证据;保留已有工作;每阶段汇报结果。历史报告只作线索。
## 0. 工作顺序
1. 确认 cwd、分支、HEAD 和未提交文件;读取 AGENTS.md 及适用的子目录规则。
2. 读 docs/dev/architecture.md、testing.md、release.md、permissions.md,再用 docs/reference.md 定位实现。
3. 完成 Phase 0,建立问题账本,再按域修复。自动执行模式逐阶段继续;用户要求先确认计划时先交基线、账本和计划。
4. 每项按“复现/测量 → 最小修复 → 定向验证 → 按主题提交”闭环。
先用 rg 定位再分段读取。日志保存 .cache/audit/<本次运行>/,对话报告实际摘要。
首次生成唯一 runId,并在账本记录 cwd、HEAD、工具版本、命令和进程标识;中断后沿用原目录,追加日志而不覆盖失败证据。
只读可并行;同一文件单一写者,shared/schema/根配置串行处理,同时只运行一个大构建。
每阶段建议 1–2 小时时间盒;到时报告卡点及下一步,不静默延长。
## 1. 工程边界
完整契约在 AGENTS.md,修改对应模块前核对:
- 验收使用临时 SQLite、独立账号与文件目录;真实库不 seed/reset,不改真实班级密码,不发测试消息。
- 权限同时检查能力、该键范围和业务关系;CLASS_DEVICE 的既有本班能力保留;课表维护范围不能自授任课关系。
- 单一 Prisma schema,SQLite/MySQL 通用;模型变动新增迁移并同步快照及旧库兼容,保留历史迁移。
- 批量写入和整库恢复保留事务边界;事件在提交后发;日期/周次使用共享及服务端唯一入口。
- Electron 保留桥接白名单、CSP、同源导航、缓存隔离、设备归属、去重和 SHA256 门禁。冒烟使用假系统执行器。
- 岛的透明、几何、投影、触摸、崩溃限流和两种模式规则保持原约束;视觉与联网验收按 testing.md 的授权边界执行。
- 保留运行数据、依赖缓存、dist、凭据及其他版本交付物;递归文件操作前验证绝对目标路径。
- 中文文案、文档、注释与 Conventional Commits;LF,只格式化本次改动。
- 版本只走 scripts/version.mjs;用户已给版本策略时沿用,否则打包前确认级别,建议 patch。
- 未明确授权不 push、不建 tag/Release、不上传或替换远端资产;本地站点构建不等于发布。
## 2. 现场证据与账本
账本位于 .cache/audit/<本次运行>/ledger.md:
| ID | 域/检查项 | 文件:行号 | 复现命令与现象 | 级别 | 方案 | 验证日志 | 状态 |
| ---- | --------- | --------- | -------------- | ---- | -------- | -------- | ---------------- |
| 示例 | A3 | 具体源码 | 实际结果 | P0 | 单一主题 | 本次证据 | 修复/无问题/后续 |
清单 A–I 每项必须有结论;“无问题”要证据,“后续”要原因、影响和具体下一步。
P0:越权、数据丢失/错乱、生产中断、迁移损坏;P1:已测量性能缺陷或错误行为;P2/P3:维护与文案。
先复现 P0,再修 P1;候选不是结论,不为凑数改代码。
至少三项性能改进使用相同输入及工具链记录前后值和复现命令。
指标可为查询/模型操作数、载荷、原始/gzip 体积、启动中位数或内存;模型操作数不能冒充底层 SQL 条数。
保留 HTTP、事件和离线格式;必要的安全收紧明确说明触发条件,同步调用方、文档和断言。
单文件超过 40% 或跨多个文件的大重构先报告方案、收益和回滚路径;不做无度量重写、全仓格式化、无关改名。
新运行时依赖须说明现有依赖无法满足的原因、体积和回滚方式。
## 3. Phase 0:基线
依次记录命令、退出码、耗时和关键输出:
```text
git status --short --branch
git log --oneline -5
node -v
Get-Command pnpm
pnpm --version
pnpm version:check
pnpm check:icons
pnpm lint
pnpm typecheck
pnpm docs:check
pnpm build
```
实际 pnpm 须匹配根 packageManager;DSH 配置见 AGENTS.md。需要前置时按 install → db:generate → 独立库 db:deploy → build:shared。
基线构建不要求迁移业务库。确需准备独立夹具时,先显式设置本次审计目录内的绝对 SQLite `DATABASE_URL`,再执行 `pnpm --filter @classhelper/server db:deploy`,完成后恢复原环境变量;不能沿用 Prisma 从业务 `.env` 读取的地址。专项优先使用会自建临时库的 verify 包装器。
大构建保存进程标识并轮询,不重复启动。出口:每条命令有本次结果;账本覆盖 A–I;P0 明确;汇报一次。
## 4. Phase 1–4:修复与优化
| 阶段 | 工作 | 出口 |
| ---------------- | -------------------------------------------------------------- | ------------------------------------------------------ |
| 1 服务端/数据 | 清单 A–C;先鉴权、事务、竞态和错误码,再重复查询、序列化、索引 | 类型检查与相关隔离专项通过,快照/迁移完整,性能有测量 |
| 2 Web | 清单 D;先构建量体积,再优化加载、守卫、请求、PWA、生命周期 | 构建与隐藏 UI 通过;样式、交互、组件注册不回归 |
| 3 桌面 | 清单 E;检查真实启动、桥接、缓存、设备、传输、更新及资源调用链 | 桌面构建和默认 quick 冒烟通过;未改岛不额外占用桌面 |
| 4 shared/脚本/CI | 清单 F–G;三端契约、退出码、临时资源、跨平台 | 静态与专项通过;Linux 交付改动有 bash 和 Linux/CI 证据 |
先保留失败信号再改实现;断言更新须对应明确行为修正,不删断言、不跳过、不放宽鉴权。
缓存初始化或请求内重复计算时,权限变更仍实时生效,快照恢复/换库后初始化状态可重置。
## 5. Phase 5–6:文档和提示词
按源码同步 README、AGENTS、受影响帮助/开发文档、索引与官网;新增页登记 toc。
核对改动页面全部链接和图片目标,docfx 严格构建不能代替普通链接检查。
展示图保留 docs/images,回归留档 docs/screenshots;自动生成的新截图须人工核验后才交付。
保持官网根站与 /docs/ 布局、脚本版本落点;下载页核对在线元数据及离线兜底路径。
提示词保留目标、边界、现场入口、清单、出口、验证和失败处理,移除重复规则与固定模块/表/测试总数。
用零上下文代理自检 Phase 0 可执行性;修正缺口,不重复昂贵或有副作用的验收。
出口:格式、链接、docs:check、pages:build 通过;有提示词优化前后差异和自检结论。
## 6. 验证矩阵
以当前 package.json 为准;新改动只重跑受影响检查,最终汇总本批证据。
| 范围 | 检查 |
| ------------- | --------------------------------------------------------------------- |
| 静态 | lint、typecheck、check:icons、version:check |
| 服务端 | verify:e2e、verify:v14;权限加 verify:authz |
| 审计/事务/PWA | verify:audit;本次问题补夹具及指标 |
| 生命周期/迁移 | verify:lifecycle、verify:client-migrations、临时旧库升级 |
| 课件/设备 | verify:courseware、verify:clients-api |
| 更新 | verify:update-download、verify:update-installer、verify:client-agent |
| Web | Web 包 build、verify:web:isolated |
| 桌面 | build:desktop、verify:desktop、相关逻辑专项 |
| 打包 | verify:packaged --exe <portable 路径> --offline;服务端副本初始化复验 |
| 文档/官网 | 本次文件格式和链接、docs:check、pages:build、关键输出页检查 |
默认不执行真实系统指令、安装器、桌面视觉或外网;需要时在已有授权内处理。
记录真实通过/失败/阻塞,不引用历史数量。
## 7. Phase 7:版本与本地包
1. 沿用已确认版本策略;未指定时此时确认,建议 patch。确认后通过 version 脚本修改并 version:check。
2. 检查磁盘和 releases 当前目录,保留其他版本及同号可恢复副本。
3. 后台执行 dist:all,核对实际产物并完成打包冒烟,不只看退出码。
4. 写 ReleaseNotes-<版本>.md,说明变化、兼容注意、实际验证和文件清单。
5. 计算 SHA256SUMS-<版本>.txt,使用 release.md 的上传名,附本地名映射、大小、摘要。
6. Linux 正式包由 Linux runner 构建;无远端授权时明确待 CI,不用 Windows 交叉包冒充。
7. releases 无 win-unpacked、staging 或解包副本;只清理本次生成且已确认的临时对象。
出口:Windows 包齐全、哈希可复算、packaged=true 离线两次启动通过,说明与包一致。
远端另按 release.md 在明确授权后执行,并等待 CI。
## 8. Phase 8:提交与交付
逐主题审阅 diff,排除凭据、业务数据、临时库、缓存和包;按中文 Conventional Commits 分组提交。
保留任务输入外的原有未提交工作,不把历史 result 改写为当前事实。
最终交付:A–I 账本及级别汇总;三项以上性能前后表和命令;验证矩阵及重试原因;
本地包路径/大小/SHA256、ReleaseNotes/清单;文档与提示词差异、自检;提交列表、未覆盖范围和后续。
完成判据:P0 有修复回归,P1 修复或有量化延期理由;各项无“待看”;源码、版本、文档和包一致;
受影响门禁通过或准确说明阻塞;有可审阅提交,没有把未执行检查写成通过。
## 9. 失败处理
| 情况 | 操作 |
| --------------------- | ----------------------------------------------------------------- |
| 工具版本不对 | 按 AGENTS 修正 DSH 路径并核验,不为转发壳修改依赖 |
| Node 原生内存错误 | 留日志、限制并发或用满足 engines 的已安装 Node LTS 复验,记录版本 |
| docfx 缺失/警告 | 按 build.mjs 提示处理、补 toc;装不上记阻塞,不关严格模式 |
| electron-builder 受限 | 核对进程访问限制,用已授权环境;不据此重装依赖 |
| 失败/超时 | 查本次日志及进程,只清理本次资源;先复现,不放宽断言 |
| 写入受限 | 尝试授权范围内最小操作,拒绝时完成可行的只读工作并解释 |
| 外网/CI 未授权 | 完成本地交付,远端步骤记后续 |
| 中断恢复 | 先核对 git、日志、任务标识及进程,避免重复构建和覆盖结果 |