chore(task): archive 09-17-local-build-console

This commit is contained in:
que01 committed 2026-09-22 14:16:31 +08:00
1 parent 3760650c70
commit 5125e097af
6 files changed
+155

No files matched your search

@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,60 @@
# 本地构建控制台设计
## Architecture
新增 `npm run console` 启动的本机控制服务。服务只绑定 `127.0.0.1`,启动后打开默认浏览器;它以 Node 内置 `http` 提供 JSON API、Server-Sent Events(SSE)和无构建的静态 HTML/CSS/JS。首版不引入 React、Vite、Electron 或数据库。
```text
browser UI
│ HTTP / SSE, localhost only
▼
scripts/build-console.js
├─ configs + diagnostics + stage manifests → area/history cards
├─ import OSM/ZIP → inputs/console/<config-key>/ + ownership record
├─ spawn node scripts/build-area.js → streamed build log/job state
├─ serve outputs/<area-dir>/ as read-only preview assets
└─ validated cleanup target → macOS Trash
```
`build-area.js` continues to own all pipeline stages. The console does not import it in-process or duplicate its business logic; it starts it as a child process with `--config` and optional `--stages`, collecting stdout/stderr for the UI.
## Data and ownership
At startup the service enumerates `config/areas/*.json`, calls the existing `readAreaConfig()` / diagnostics APIs, and reads stage manifests. Those files are the history source of truth.
The import form copies selected OSM and ZIP files into `inputs/console/<config-key>/`. A local ignored ownership record under `.build-console/areas/<config-key>.json` records the configuration filename, managed input paths, ZIP hash, and output directory. It exists only to prove which files the console may clean; ordinary historical configs with external paths remain usable but do not grant deletion authority over those sources.
The ZIP `areaId` is immutable and becomes configuration `id`. Because an explicit Save As must not collide with its source config or generated output, the user-facing configuration key is a separate filesystem-safe slug; a saved copy gets a distinct config filename and explicit `outputs.areaDir` / `fileStem` derived from that key. The package contract keeps the original ZIP `areaId`.
## User flow
1. **Welcome / readiness**: display a short three-step guide and checks for Node, Blender, writable managed input directory, and existing areas. Explain that OSM supplies buildings/landscape while ZIP supplies authoritative roads.
2. **History**: show every `config/areas/*.json` as a card with input locations, tree style, output health, last successful stage and links to preview/package when present.
3. **Import / Save As**: choose OSM and ZIP, inspect ZIP contract and locked `areaId`, choose tree style, select a config key, then copy inputs and atomically write a new config. Existing config edits default to Save As; overwrite requires a typed/explicit confirmation.
4. **Build**: choose standard full build or individual existing stages. At most one build job may run; SSE reports stdout/stderr, named stage progression, completion marker and a concise actionable error summary.
5. **Preview**: link to a read-only `/artifacts/<config-key>/...` route that serves the generated preview HTML and its package-relative assets. Vehicle selection stays in the existing preview runtime, rather than changing build artifacts.
6. **Cleanup**: cards and multi-select provide (a) Clear build outputs and (b) Remove area. A confirmation screen lists regions, file counts and byte totals. Targets must be canonically located under allowed project roots. macOS Finder moves them to Trash; it never calls recursive shell deletion.
## API boundary
- `GET /api/health`, `/api/areas`, `/api/options`: readiness, history cards and supported tree styles.
- `POST /api/import/inspect`: multipart/selected file validation without promoting files; verifies ZIP root/contract/areaId via the shared native package validator.
- `POST /api/areas`: copy managed inputs, write ownership record and new config atomically.
- `POST /api/areas/:key/build`: create one build job; `GET /api/jobs/:id/events` streams SSE logs and terminal state.
- `POST /api/cleanup/preview` and `/api/cleanup/confirm`: separate target computation from confirmation, avoiding a stale/hidden destructive scope.
- `GET /artifacts/:key/*`: safely serve only the selected area output root; reject traversal and arbitrary filesystem paths.
Requests are same-origin, localhost-only and JSON validated. File names are normalized to generated safe names; filesystem writes use staging plus rename. Cleanup uses `realpath` containment checks immediately before moving targets to Trash.
## Compatibility and rollout
- Existing commands and hand-authored configurations remain unchanged.
- Existing configs are visible even when their input paths are external; they are never copied or marked owned until a user explicitly imports/saves a console-managed version.
- The console's new local state and managed imports are gitignored. Normal area config files remain reviewable JSON.
- Rollback is deleting the new console-specific files and npm script; it never changes pipeline output contracts.
## Validation strategy
- Unit tests for config/history discovery, ZIP inspection, ownership classification, safe path rejection, Save As collision handling, cleanup plan creation and destructive-target containment.
- HTTP tests for localhost binding, API validation, SSE job lifecycle and artifact traversal rejection.
- Manual smoke test: import OSM+ZIP, save, full build, preview, clear outputs, rebuild, remove area, restore from Trash if needed.
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,22 @@
# 本地构建控制台实施计划
1. Create a dependency-free console server and static UI shell; add `npm run console`, localhost-only binding, automatic browser launch and environment/readiness endpoint.
2. Extract/reuse small pipeline-facing helpers for area discovery, diagnostics summary, native ZIP inspection and supported tree-style options. Do not import `build-area.js` as a module.
3. Implement history cards and onboarding: config scanning, manifest/status summary, input descriptions, package/preview links and model option selection.
4. Implement safe import and Save As: upload/copy OSM+ZIP into ignored managed storage, inspect ZIP contract/areaId, atomically write a config with collision-safe output overrides, and record ownership.
5. Implement serialized build jobs with child-process log capture, SSE progress, completion/failure states, and links to the existing generated preview.
6. Implement cleanup planning and confirmation. Validate canonical paths, move only allowed targets to macOS Trash, and cover single/batch clear-output versus remove-area paths.
7. Add focused Node HTTP/unit tests, update README with launch/use/troubleshooting guidance, then manually run the actual imported-area build and preview flow.
## Validation commands
- `node --check` for each new Node entry/helper.
- focused console test command added to `package.json`.
- existing `npm run test:native-road-package`, `npm run test:build-stages`, `npm run test:preview-assets`, and `npm run test:package-contract`.
- `npm run console`, import a valid OSM/ZIP fixture, run a full build, open preview, and exercise both cleanup scopes.
## Risk controls and rollback
- Never bind beyond loopback; do not serve arbitrary paths or allow parallel builds.
- Validate cleanup targets after confirmation and immediately before Trash movement; no `rm -rf` implementation.
- If the UI path fails, existing CLI remains the supported fallback. Removing console files/script rolls back the feature without changing existing area data or output contracts.
@@ -0,0 +1,45 @@
# 本地构建控制台
## Goal
提供一个在本机 localhost 运行的图形控制台,使用户无需记忆命令行即可选择或导入道路构建输入、执行现有构建管线、查看进度并打开 Cesium 预览。
## Confirmed facts
- 当前唯一的交互入口是 `scripts/interactive-build.js`:它枚举 `config/areas/*.json`、选择阶段后调用 `scripts/build-area.js`。
- `build-area.js` 是构建、Blender/Cesium 子进程、package 发布和 preview 写入的唯一所有者;控制台必须调用它,不能复制阶段实现。
- native 区域配置通过 `nativeRoadPackage` 引用 `native-road-package/v1.1` ZIP;导入器会验证 ZIP 契约和 `areaId`,并将其安全解压到私有 pipeline cache。
- Blender 与本地文件系统不能由纯静态浏览器页面直接访问,因此入口必须由本机服务配合浏览器 UI 组成。
- 现有配置及其 `outputs/<area>/_pipeline/stages/*.manifest.json` 是历史输入和构建历史的可读取事实源,不能另建会漂移的重复数据库。
## Requirements
- R1: 以 localhost 页面作为首版交付方式;命令行入口继续可用。
- R2: 首页自动枚举并导入 `config/areas/*.json`,以区域卡片呈现可复用配置、输入摘要、最近构建状态、预览与发布包入口。
- R3: 用户可从界面选择 OSM 与 native-road ZIP,读取 ZIP 的 `areaId` 和契约信息,并在构建前给出 OSM/ZIP/区域 ID 的明确校验反馈。
- R3.1: 成功导入的 OSM 与道路 ZIP 复制到项目托管输入目录;新配置引用托管副本,保证可复现且不依赖 `/tmp` 或用户外部路径。
- R4: 保持首版简单:构建前仅可选择项目已有的植被/树木风格;Cesium 预览中可选择车辆模型。两者分别影响静态场景与演示运行时。
- R5: 用户可选构建阶段并启动现有 build-area 管线,看到实时阶段状态、日志、产物链接与可行动的失败说明。
- R6: 对历史配置的修改默认另存为新配置;覆盖已有配置必须是显式确认操作。
- R6.1: 控制台提供单项清理与批量清理,仅处理它创建的托管输入和本项目生成的区域输出;绝不删除用户在项目外选择的原始文件。首版清理统一移入系统废纸篓,保留恢复机会。
- R6.2: 清理范围分为两级,且单项、批量均适用:`清理构建产物` 仅移除区域输出并保留配置和托管输入;`移除区域` 将区域配置、控制台托管输入和区域输出一并移入废纸篓。批量操作必须先展示受影响区域和文件数,再允许确认。
- R7: 产品内置首次使用引导:说明 OSM、道路 ZIP、模型选项、构建阶段、预览入口和 Blender/Node 环境检查,不以外部 README 代替。
## Out of scope
- 改写道路编译器、ZIP 契约、Blender 几何或 Cesium 预览运行时。
- 远程部署、多用户协作、云端构建或将本机文件上传到第三方服务。
- 第一阶段打包为 macOS `.app`;待 localhost 工作流验证后再评估。
## Acceptance criteria
- [ ] 用户可在浏览器中启动、选择历史区域并重新执行一次已有构建,无需手写 CLI 参数。
- [ ] 用户可导入 OSM 与有效道路 ZIP,且在启动 Blender 前看到 ZIP contract / areaId / 文件缺失的校验结果。
- [ ] 用户可保存为新的区域配置而不改变原配置;显式覆盖有确认保护。
- [ ] 页面可展示构建阶段、实时日志、成功后的 preview URL 与 `package/manifest.json`。
- [ ] 首次使用者可仅依照页面引导完成一次输入、构建和预览,并理解失败时下一步怎么做。
## Technical notes
- native-road ZIP 的 `areaId` 与区域配置 `id` 必须相等;控制台应从 ZIP 读取并锁定该 ID,避免提供必然失败的可编辑字段。
- 控制台管理的输入需要有可判定 ownership 的目录/记录,才能安全实施区域级清理;历史配置引用的外部路径始终视为只读、非托管输入。
@@ -0,0 +1,26 @@
{
"id": "local-build-console",
"name": "local-build-console",
"title": "本地构建控制台",
"description": "",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-09-17",
"completedAt": "2026-09-22",
"branch": null,
"base_branch": "experiment/road-compiler-rethink",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": null,
"relatedFiles": [],
"notes": "",
"meta": {}
}