CYBERSWAT / 开发部自由练习 · v0.4.1

把单元跑起来：从自己的代码到完整作品

这份操作手册与每节的“动手路线”配套。所有命令都在你复制出的 my-bootcamp 根目录运行；只有明确写了 --prefix 的命令进入相应子项目。不要在源码里到处创建第二套 api/web/desktop 文件夹。提供的接线代码属于教材样例，阅读、修改它与完成规则函数都是练习的一部分。

Windows 第一次上手：先确认位置，再运行

以下是 PowerShell 路线，Windows 设备是否实际通过要另行记录；先按手册01从官方来源选择符合架构的 VS Code 和 Node 24.x。不要为了排错修改系统策略或 PATH。运行 node --version 和 npm.cmd --version，找不到命令就重开终端并求助，暂时停在这里。

  1. 从课程下载页取得完整 ZIP；打开公开清单，找到 bootcamp-starter-v0.4.zip 对应的 SHA-256。下面假设浏览器保存到了“下载”目录；若不在此处，用文件实际位置替换路径：
Get-FileHash -LiteralPath (Join-Path $env:USERPROFILE 'Downloads\bootcamp-starter-v0.4.zip') -Algorithm SHA256

将输出 Hash 与清单中该文件的值逐字符比较（大小写不影响）；不同、清单打不开或没有该项时停止，不解压也不继续。哈希用于核对下载是否与清单一致，不证明下载来源可信。

  1. 在文件管理器里新建尚不存在的个人目录，例如“文档”下 CyberSWAT 学习；用右键解压完整 ZIP 到其中。保留原 ZIP；不要覆盖旧练习。进入解压出的 bootcamp 文件夹，确认有 package.json、u03 和 tools；在此文件夹打开 PowerShell。也可按手册02检查，Get-Location 应指向该 bootcamp 根目录，中文或空格路径切换时用英文引号，例如 Set-Location "路径按自己的实际位置填写"，不要原样运行示意路径。

  2. 在该目录执行 npm.cmd ci，完成后执行 npm.cmd run check。package-lock.json 记录具体依赖，npm ci 根据它重建 node_modules；仅类型检查通过不代表 TODO 完成。安装需要网络，失败时保留错误并停下；无权限时联系设备支持者，不绕过策略。依赖与命令区别见手册11。

  3. 先观察参考核心：node tools/try.mjs u03 --reference、node tools/check.mjs u03 --reference。参考通过不代表自己已完成；先做自己的 u03/starter/model.ts，初始 TODO 失败正常。之后按 U03 的有效 JSON → 错误 { → 有效 false 顺序检查：原文保留、旧输出清空、恢复后旧错误消失。参考核心测试不代替实际页面检查。

卡住时记录系统和架构、node --version、当前目录、正在运行的命令、预期、实际错误及已经尝试的步骤；求助前遮去姓名、私有路径、凭据和真实数据。有关文件与终端的解释见手册01。

第一次进入

零基础先做 E01 和各单元标注的手册先修。先修按“能完成什么”判断：U01 前能定义函数、读数组和对象、识别异常；页面前能解释输入→事件→状态→显示；数据库前能解释请求、表、唯一约束及一次查询。跳过这些直接复制命令，不能记作学会。

  1. 下载本页的完整练习包，解压后将 bootcamp 文件夹命名为 my-bootcamp，用编辑器打开整个文件夹。复制时可以不带 node_modules、work、data、dist、.env，这些由自己生成。不要只复制某一个 model.ts。
  2. 打开编辑器终端，运行 node --version，本版技术验证用 Node 24.11.1；执行 npm --version 确认包管理器可用。安装方法见 手册01，先在这个步骤解决“找不到命令”。
  3. 运行 npm ci，再运行 npm run check。后者必须以退出码 0 结束；它只检查类型，TODO 尚未完成时依然可能通过。
  4. 运行 node tools/try.mjs u03。初次的 TODO: convertInput 是预期的待完成提示，不是安装失败。打开 u03/starter/model.ts 能找到同名函数。

只有做 U01 的命令行阶段时，到这里就够了。U02–U12 的页面或服务阶段再继续以下准备；依赖安装只需首次或锁文件改变后执行。

npm ci --prefix runtime --ignore-scripts
node tools/lab.mjs init
npm run db:generate --prefix runtime

init 建立 runtime/.env；重复执行保留已有配置。db:generate 按课程锁定的 Prisma 6.19.3 生成客户端，本版本不要跟着最新版文档替换为其他大版本的 API。若下载失败，检查错误中具体域名，通过官方或学校可用渠道处理；不靠删代码/跳过检查伪装成功。依赖版本只是这次验证基线。

每节循环：写一段，验一段

  1. 在 uNN/starter/model.ts 实现本节第一项规则，保留类型和导出名称。reference 是参考答案，不是填写位置。
  2. 运行 node tools/try.mjs uNN，比较该节固定样例；再运行 node tools/check.mjs uNN，根据测试名称找到尚未完成的行为。返回失败时先看实际值和预期值，不要改断言来“通过”。
  3. 完成本节全部规则后运行 npm run check。两项都过再接作品。
  4. 运行 node tools/build-app.mjs uNN。这个命令复制你的规则到构建区、做严格类型检查并生成浏览器能执行的 JavaScript，不改你的 starter 文件。
  5. 运行 node tools/lab.mjs start uNN，保持这个终端打开；在自己电脑的浏览器访问它输出的本机地址。另开一个终端做验收。若在远程主机学习，浏览器需访问学校提供的合规开发预览；127.0.0.1 指运行程序的那台机器，本教程不包含绕过网络管理的方法。
  6. 修改 model 或服务 TS 后，用 Ctrl+C 停止、重新 build、重新 start。当前样例没有热更新；忘记重新构建会看到旧代码。只改 web 下的 JS/HTML 后刷新页面即可。

服务绑定本机，默认应用端口 3400。启动遇到 EADDRINUSE，关闭自己先前的练习进程，或修改 runtime/.env 中 PORT 后重新启动；不关闭不认识的服务。如果改变了应用端口，验收时设置 LAB_URL，或直接在 tools/probe.mjs 末尾的默认本机地址改成自己的端口。

哪些单元需要数据库

单元 本地依赖 成品所在位置
U01 Node u01/cli.mjs；数据在 u01/data/
U02、U03、U07 浏览器与本地应用服务 runtime/web/uNN.js；U02 数据在该浏览器的本地存储
U04、U05、U06、U09、U10、U12 PostgreSQL + 本地应用服务 runtime/src/uNN.ts 与 runtime/prisma/schema.prisma
U08、U10 额外开一个本地模拟目标 tools/target.mjs，端口 3401
U11 本地应用服务及文件目录 runtime/data/file-notes/，更新备份在其 backups 中
U13 Electron 与桌面会话 desktop/，单独走下文

数据库单元在首次运行前执行：

node tools/lab.mjs db up

需要本机已安装 Docker Engine 或 Docker Desktop，且 docker compose version 可用。命令启动本副本专用的 PostgreSQL 17 容器和数据卷，等待数据库健康，再应用仓库中的迁移。它不会连接组织业务库。首次拉取镜像需要网络；失败时保留报错，先完成核心规则阶段，数据库阶段仍记未完成。

runtime/.env 中 DB_PORT 与 DATABASE_URL 的端口必须相同，默认 55439。端口冲突时一起修改，再重试。配置仅放个人副本，不提交 .env。源码中的 runtime/compose.yaml 与迁移是需要提交的。

完成本节首次验收后，Ctrl+C 停止 API，再执行：

node tools/lab.mjs db restart
node tools/lab.mjs start uNN

在第二终端执行 node tools/probe.mjs uNN --resume。预期列出“重启后数据仍在”。该命令读自己上次验收生成的 work/uNN-probe.json，因此必须先运行过不带 --resume 的验收。不删除数据卷来求干净。暂停学习时 Ctrl+C 停 API，执行 node tools/lab.mjs db stop；下次 db up 会复用原数据。源码、配置、数据库数据卷是三个不同位置，复制源码不等于备份数据库。

两个实验身份怎样使用

U05/U09/U12 的页面有 Alice、Bob 两个虚构教学账号。点击“登录实验账号”后，本地服务验证固定实验密码并发临时令牌；服务从令牌取得身份，忽略正文中的 owner/actor。刷新或重启后重新登录。它只为观察资源所有权提供夹具，不是注册/密码管理作品；正式认证仍按手册21另做。

验收脚本会自动登录两个账号、发送并发或越权请求，并增加带随机前缀的合成数据。它不清空已有作品数据。通过后打印本次具体检查；失败时输出路径、预期状态与实际响应，先检查服务单元、数据库、令牌和规则函数四处。

U08/U10：不要寻找一个外站来“试一下”

先开第二终端运行 node tools/lab.mjs target，再启动本节服务。模拟目标只绑定本机端口 3401，并能返回成功、失败、超时；验收脚本会切换这些状态。若端口改变，同步修改 runtime/.env 的 TARGET_PORT 和 tools/probe.mjs 中目标默认端口，或为验收进程设置同名环境变量。目标程序没有业务数据，Ctrl+C 即可停止。

U13：从桌面开发启动到本机教学包

先完成 U03 和 U13 规则。仍在练习根目录依次运行：

npm ci --prefix desktop
npm run install:binary --prefix desktop
node tools/build-desktop.mjs
npm start --prefix desktop

应出现本地 JSON 窗口。需要图形桌面会话，纯远程终端不会凭空出现窗口。install:binary 明确下载 Electron 对应平台的二进制文件（45.0.0 的 npm 包不自动完成这一步）；缺失时应解决安装问题，不通过关闭安全隔离来强行启动。

尝试合法 JSON→格式化预览→另存为→先取消，再另存为到自己的学习目录。检查中文、缩进、结尾换行；页面仍保留输入。再试非法 JSON 和非法建议文件名，必须显示错误。

开发版通过后关闭窗口，运行 npm run package --prefix desktop。产物在 desktop/out/，按自己的操作系统打开对应目录内的 BootcampJSON 可执行程序/应用包，再做一遍保存与取消。打包脚本只制作当前系统和架构的未签名教学包，不是安装器，也不代表跨平台发行验证。更改规则后重新编译和打包。

卡住时从哪个位置恢复

现象 先检查 继续方式
TODO / HTTP 501 对应 starter 中的函数 完成规则，再类型检查、构建、启动
网页无响应 启动终端是否还开着、端口是否一致 先确认日志输出本机地址
改了代码没变化 是否仍运行旧 dist 停止→build→start→刷新
数据库启动失败/P1001 Docker 是否运行、端口、.env、容器健康 修复后 db up，不删数据卷
HTTP 401/403/409 未登录、别人资源、资源冲突 根据本节约定分别处理，不全部当服务器坏了
类型通过但页面报 TODO 类型与行为是两项检查 先让核心测试全部过
API 500 服务终端日志、DB 是否可用 不返回假成功；恢复依赖后重新请求
参考实现通过、自己不通过 页面模式标记、starter 差异 逐个函数比较；不能拿参考结果填写自己的完成记录

一次独立验证应留下什么

每节建立自己的 LEARNING.md，按 工作台记录模板 保存：命令与工作目录、核心测试输出、页面实际操作、失败与恢复、自己的变式。每次先写预测再运行，解释为什么得到这个结果。教材参考、自动实测和学员真正掌握是三种事实；不需要等待教师放行，但不能把前两者当作第三者。