61 lines
5.3 KiB
Markdown
61 lines
5.3 KiB
Markdown
# 本地构建控制台设计
|
||
|
||
## 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.
|