Files

5.3 KiB
Raw Permalink Blame History

本地构建控制台设计

Architecture

新增 npm run console 启动的本机控制服务。服务只绑定 127.0.0.1,启动后打开默认浏览器;它以 Node 内置 http 提供 JSON API、Server-Sent Events(SSE)和无构建的静态 HTML/CSS/JS。首版不引入 React、Vite、Electron 或数据库。

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.