chore(task): archive 09-17-local-build-console
This commit is contained in:
1 parent
3760650c70
commit
5125e097af
6 files changed
+155
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user