osmWorkflow/.trellis/tasks/archive/2026-08/08-11-interactive-area-cli/prd.md

Interactive area build CLI

Goal

提供一个交互式区域构建入口，减少手写 npm run build:area -- --config ... --stages ... 的频率；用户可选择区域和一个或多个构建阶段，CLI 按既有阶段约束执行。

Confirmed Facts

• 当前 scripts/build-area.js 支持 intermediates、reimport、blender、cesium、 preview 与 compress 六个阶段，并接受逗号分隔的 --stages。
• intermediates 与 reimport 互斥：前者会从 OSM 重建 GeoPackage，后者回导 QGIS 编辑。
• 执行顺序固定为 intermediates/reimport -> blender -> cesium -> preview -> compress； cesium 当前会自动写入 preview 产物。
• 项目没有终端交互依赖；现有命令行调用必须继续可用于脚本和自动化。

Requirements

• R1：提供交互式入口，列出可用区域配置并允许用户选择目标区域。
• R2：交互式入口允许一次选择多个阶段，并清晰展示阶段名称与用途。
• R3：选择互斥阶段时必须阻止执行并解释原因；不得静默选择其中之一。
• R4：执行多个阶段时必须使用既有依赖顺序，而非用户勾选顺序。
• R5：保留 npm run build:area -- --config ... --stages ... 的现有非交互行为与语义。
• R6：无 TTY、取消输入或无效输入时必须安全退出，不启动任何构建。
• R7：TTY 交互使用方向键移动、空格多选、回车确认；菜单应显示当前选择状态。
• R8：npm run build 启动交互式入口；npm run build:area 继续保留为非交互入口。

Acceptance Criteria

• 用户可从终端选择区域和多项阶段，无需手写配置路径或逗号分隔阶段名。
• 选择 intermediates 与 reimport 时，CLI 明确报互斥错误且不运行构建。
• 选择乱序的多个阶段时，实际执行顺序仍遵循既有管线顺序。
• 既有非交互 build:area 调用保持兼容。
• 取消或在非交互环境调用不会触发构建。
• 用户可用方向键、空格和回车完成区域及阶段选择。
• npm run build 启动交互菜单，npm run build:area 的现有调用保持不变。

Key Decisions

• 采用终端原生多选菜单，而非输入逗号分隔编号；避免引入运行时依赖。
• npm run build 作为日常交互入口；npm run build:area 继续服务自动化和精确调用。

Out Of Scope

• 修改各 stage 的构建业务逻辑、依赖关系或产物格式。
• 将巡航路线、QGIS 图层编辑或区域配置编辑纳入本次交互流程。
• GUI 或浏览器界面的构建控制台。

Notes

• Keep prd.md focused on requirements, constraints, and acceptance criteria.
• Lightweight tasks can remain PRD-only.
• For complex tasks, add design.md for technical design and implement.md for execution planning before task.py start.