feat: export portable native road packages

bin/road-compiler.js

@@ -4,13 +4,17 @@
 const fs = require("fs");
 const path = require("path");
 const { compiler } = require("../src");
+const { exportNativeRoadPackage } = require("../src/export/native-road-package");
 
 const args = process.argv.slice(2);
 const index = args.indexOf("--input");
-if (index < 0 || !args[index + 1] || index + 2 !== args.length) {
-  throw new Error("Usage: road-compiler --input <RoadCompilerInput.json>");
+const exportIndex = args.indexOf("--export-zip");
+const expectedLength = exportIndex >= 0 ? 4 : 2;
+if (index < 0 || !args[index + 1] || (exportIndex >= 0 && !args[exportIndex + 1]) || args.length !== expectedLength) {
+  throw new Error("Usage: road-compiler --input <RoadCompilerInput.json> [--export-zip <output.zip>]");
 }
 const inputFile = path.resolve(args[index + 1]);
 const input = JSON.parse(fs.readFileSync(inputFile, "utf8"));
 const { result, comparison } = compiler.compileInput(input);
+if (exportIndex >= 0) exportNativeRoadPackage(input.outDir, path.resolve(args[exportIndex + 1]));
 console.log(`NATIVE_ROAD_COMPILE_DONE ${JSON.stringify({ areaId: input.areaId, roads: result.model.roads.length, endpoints: result.model.endpoints.length, diagnostics: result.diagnostics.length, output: input.outDir, comparison })}`);

docs/native-road-package-v1.md

@@ -73,6 +73,20 @@ shape and owns all path derivation.
 The editable signal source at `trafficSignalsFile` is a sibling of `outDir`.
 It is included in the parity baseline because regeneration must be stable.
 
+## ZIP Export
+
+The Web workbench's **导出道路包** action and the CLI's optional
+`--export-zip <output.zip>` emit the portable package form. The ZIP root is
+flat: it contains the six JSON documents above and `layers/*.geojson`, without
+an enclosing area directory. It contains no OSM input, overrides, or compiler
+workspace paths. `compiled.json` retains only model and movement data needed by
+the downstream preview; its internal `source` paths are removed.
+
+The ZIP manifest adds informational `generator: { name, version }`. Consumers
+must select compatibility only from `contract`, `areaId`, and declared files.
+Entry order and timestamp are fixed, so unchanged compiled output exports to
+the same ZIP hash.
+
 Successful CLI execution prints exactly one completion marker:
 
 ```text

package-lock.json

@@ -1,13 +1,14 @@
 {
   "name": "@osm-asset/road-compiler",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@osm-asset/road-compiler",
-      "version": "0.1.0",
+      "version": "0.2.2",
       "dependencies": {
+        "fflate": "0.8.3",
         "ol": "10.10.0"
       },
       "bin": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osm-asset/road-compiler",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "private": false,
   "type": "commonjs",
   "main": "src/index.js",
@@ -9,9 +9,11 @@
   },
   "scripts": {
     "test": "node test/index.js && node test/fixtures.js",
-    "road:workbench": "node bin/road-workbench.js"
+    "road:workbench": "node bin/road-workbench.js",
+    "road:export": "node bin/road-compiler.js"
   },
   "dependencies": {
+    "fflate": "0.8.3",
     "ol": "10.10.0"
   }
 }

src/compile/layer-manifest.js

@@ -10,10 +10,10 @@ const LAYER_REGISTRY = Object.freeze([
   { key: "sidewalkSurface", source: "sidewalk_surface", role: "surface", materialLayer: "sidewalks" },
   { key: "laneSeparators", source: "lane_separators", role: "marking", materialLayer: "lane_separators", splitBy: { prop: "color", cases: [{ match: "yellow", material: "native_lane_separator_yellow" }, { default: true, material: "lane_separators" }] } },
   { key: "centerLines", source: "center_lines", role: "marking", materialLayer: "center_lines", splitBy: { prop: "color", cases: [{ match: "white", material: "native_center_line_white" }, { default: true, material: "center_lines" }] } },
-  { key: "crosswalks", source: "crosswalks", role: "marking", materialLayer: "crosswalks" },
-  { key: "vehicleStopLines", source: "vehicle_stop_lines", role: "marking", materialLayer: "vehicle_stop_lines" },
   { key: "directionArrows", source: "direction_arrows", role: "marking", materialLayer: "lane_arrows_webscale" },
   { key: "turnArrows", source: "turn_arrows", role: "marking", materialLayer: "lane_arrows_webscale" },
+  { key: "crosswalks", source: "crosswalks", role: "marking", materialLayer: "crosswalks" },
+  { key: "vehicleStopLines", source: "vehicle_stop_lines", role: "marking", materialLayer: "vehicle_stop_lines" },
   { key: "laneCenterlines", source: "lane_centerlines", role: "semantic" },
   { key: "connectors", source: "connectors", role: "semantic" },
 ]);

src/export/native-road-package.js

@@ -0,0 +1,56 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { zipSync } = require("fflate");
+const { LAYER_REGISTRY, validatePublishedLayers } = require("../compile/layer-manifest");
+
+const ROOT_FILES = [
+  "manifest.json",
+  "compiled.json",
+  "diagnostics.json",
+  "comparison.json",
+  "traffic-signal-assemblies.json",
+  "traffic-signals.json",
+];
+
+const GENERATOR = Object.freeze({ name: "road-compiler", version: "0.3.0" });
+
+function packageEntries(directory) {
+  const manifestPath = path.join(directory, "manifest.json");
+  if (!fs.existsSync(manifestPath)) throw new Error(`Native road package manifest is missing: ${manifestPath}`);
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  if (manifest.contract !== "native-road-package/v1.1") throw new Error("Native road package requires native-road-package/v1.1.");
+  if (!manifest.areaId || typeof manifest.areaId !== "string") throw new Error("Native road package manifest areaId is required.");
+  validatePublishedLayers(directory, manifest);
+  const files = [];
+  for (const relative of ROOT_FILES) files.push(relative);
+  for (const layer of LAYER_REGISTRY) files.push(`layers/${layer.source}.geojson`);
+  for (const relative of files) {
+    const file = path.join(directory, relative);
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`Native road package file is missing: ${relative}`);
+  }
+  return { manifest, files: [...new Set(files)].sort() };
+}
+
+function exportNativeRoadPackage(directory, destination = null) {
+  const { manifest, files } = packageEntries(directory);
+  const entries = Object.fromEntries(files.map((relative) => [relative, fs.readFileSync(path.join(directory, relative))]));
+  // The model/movements remain needed by host preview generation, but absolute
+  // compiler-workspace paths are not part of the exported package contract.
+  const compiled = JSON.parse(entries["compiled.json"].toString("utf8"));
+  delete compiled.source;
+  entries["compiled.json"] = Buffer.from(`${JSON.stringify(compiled, null, 2)}\n`);
+  entries["manifest.json"] = Buffer.from(`${JSON.stringify({ ...manifest, generator: GENERATOR }, null, 2)}\n`);
+  // ZIP timestamps start at 1980; a fixed value keeps repeated exports byte-stable.
+  const bytes = zipSync(entries, { level: 6, mtime: new Date("1980-01-01T00:00:00Z") });
+  if (destination) {
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    const temporary = `${destination}.tmp-${process.pid}`;
+    fs.writeFileSync(temporary, bytes);
+    fs.renameSync(temporary, destination);
+  }
+  return { bytes, manifest, files };
+}
+
+module.exports = { ROOT_FILES, GENERATOR, packageEntries, exportNativeRoadPackage };

src/index.js

@@ -10,6 +10,7 @@ module.exports = {
   nativeTrafficSignals: require("./native-traffic-signals"),
   nativeRoad: require("./compile/native-road"),
   layerManifest: require("./compile/layer-manifest"),
+  nativeRoadPackage: require("./export/native-road-package"),
   compiler: require("./compile/compiler"),
   check: require("./check"),
 };

test/fixtures.js

@@ -1,9 +1,13 @@
 "use strict";
 
 const assert = require("assert/strict");
+const crypto = require("crypto");
+const { execFileSync } = require("child_process");
 const fs = require("fs");
 const path = require("path");
+const { unzipSync, strFromU8 } = require("fflate");
 const { compiler } = require("../src");
+const { exportNativeRoadPackage } = require("../src/export/native-road-package");
 
 const root = path.resolve(__dirname, "..");
 for (const areaId of ["fengshu-er-road", "nantaizi-lake-innovation-valley"]) {
@@ -23,5 +27,23 @@ for (const areaId of ["fengshu-er-road", "nantaizi-lake-innovation-valley"]) {
   const { result } = compiler.compileInput(input);
   assert.equal(result.areaId, areaId);
   assert.ok(fs.existsSync(path.join(input.outDir, "compiled.json")));
+  const first = exportNativeRoadPackage(input.outDir);
+  const second = exportNativeRoadPackage(input.outDir);
+  assert.equal(crypto.createHash("sha256").update(first.bytes).digest("hex"), crypto.createHash("sha256").update(second.bytes).digest("hex"));
+  const entries = unzipSync(first.bytes);
+  const manifest = JSON.parse(strFromU8(entries["manifest.json"]));
+  assert.equal(manifest.areaId, areaId);
+  assert.equal(manifest.contract, "native-road-package/v1.1");
+  assert.deepEqual(manifest.generator, { name: "road-compiler", version: "0.3.0" });
+  assert.equal("source" in JSON.parse(strFromU8(entries["compiled.json"])), false);
+  assert.equal(Object.keys(entries).some((entry) => entry.includes("override") || entry.endsWith(".osm")), false);
+  assert.equal(Object.keys(entries).length, 18);
+  if (isFengshu) {
+    const inputFile = path.join(outputRoot, "road-compiler-input.json");
+    const archive = path.join(outputRoot, "export.zip");
+    fs.writeFileSync(inputFile, `${JSON.stringify(input)}\n`);
+    execFileSync(process.execPath, [path.join(root, "bin", "road-compiler.js"), "--input", inputFile, "--export-zip", archive]);
+    assert.ok(fs.existsSync(archive));
+  }
 }
 console.log("road compiler fixture tests passed");

workbench/client/index.html

@@ -1,4 +1,4 @@
 <!doctype html>
 <html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>道路编译工作台</title><link rel="stylesheet" href="/vendor/ol/ol.css"><link rel="stylesheet" href="/app.css"></head>
-<body><header><strong>道路编译工作台</strong><span id="area"></span><span id="status"></span><span id="dirty-state" aria-live="polite"></span><label style="display:inline;margin:0 0 0 auto;white-space:nowrap"><input id="scene-preview" type="checkbox"> 场景效果</label><button id="save">保存修改</button><button id="compile">保存并重新生成</button></header>
+<body><header><strong>道路编译工作台</strong><span id="area"></span><span id="status"></span><span id="dirty-state" aria-live="polite"></span><label style="display:inline;margin:0 0 0 auto;white-space:nowrap"><input id="scene-preview" type="checkbox"> 场景效果</label><a id="export-package" href="/api/export.zip" download>导出道路包</a><button id="save">保存修改</button><button id="compile">保存并重新生成</button></header>
 <main><aside class="issues"><h1>图层</h1><label><input data-layer="osm" type="checkbox" checked> OSM 道路中心线</label><label><input data-layer="native" type="checkbox" checked> 自研道路与路口面</label><label><input data-layer="sidewalks" type="checkbox" checked> 路缘与步行带</label><label><input data-layer="lanes" type="checkbox" checked> 车道与转向路径</label><label><input data-layer="gaodeReference" type="checkbox" checked> 高德规整路口参考</label><label><input data-layer="reference" type="checkbox"> osm2streets 参考面</label><hr><h1>当前编译概览</h1><dl id="summary"></dl><hr><h1>待检查问题</h1><div id="diagnostic-filters" class="segmented"><button data-diagnostic-filter="all" type="button">全部</button><button data-diagnostic-filter="candidates" type="button">可连接</button><button data-diagnostic-filter="other" type="button">其他</button></div><ul id="diagnostics"></ul></aside><section id="map" class="map"></section><aside class="inspector"><h1>当前道路设置</h1><p id="hint">点击道路、车道、转向路径或路口面以查看详情。</p><section id="selected-junction" hidden><h2>当前路口</h2><output id="junction-detail"></output></section><form id="road-form" hidden><label>道路</label><output id="road-name"></output><output id="movement-summary"></output><output id="lane-convention"></output><section id="selected-movement" hidden><h2>当前行驶动作</h2><output id="movement-detail"></output></section><div id="direction-switch"></div><label>本方向道路宽度（米）<input id="width" type="number" min="1" step="0.01"></label><label>本方向车道数<input id="lanes" type="number" min="1" step="1"></label><label><input id="left" type="checkbox"> 左侧有路缘与步行带</label><label><input id="right" type="checkbox"> 右侧有路缘与步行带</label><button type="submit">暂存本道路修改</button></form><form id="center-line-form" hidden><h2 id="marking-style-heading">道路中心线样式</h2><output id="center-line-segment"></output><label>样式<select id="center-line-style"><option value="yellow-dashed">黄色虚线（默认）</option><option value="white-dashed">白色虚线</option><option value="yellow-solid">黄色实线</option><option value="white-solid">白色实线</option></select></label><button type="submit">暂存标线样式</button></form><hr><h2>路口连接</h2><div id="connections">请选择一条道路。</div><button id="add-connection" type="button" hidden>手工新增驶出连接</button><details><summary>技术详情与来源</summary><pre id="evidence">无</pre></details></aside></main><script type="importmap">{"imports":{"rbush":"/vendor/rbush/index.js","quickselect":"/vendor/quickselect/index.js"}}</script><script type="module" src="/app.js"></script></body></html>

workbench/server.js

@@ -7,6 +7,7 @@ const path = require("path");
 const { loadOverrides, validateOverrides, writeJsonAtomic } = require("../src/compile/native-road");
 const { generate, validateDocument, runtime } = require("../src/native-traffic-signals");
 const { convertGeoJson } = require("../src/reference/gaode");
+const { exportNativeRoadPackage } = require("../src/export/native-road-package");
 
 function startWorkbench({ area, configPath, repoRoot, compileFresh, readAreaConfig, junctionReference = null, debug = false, port = 8787 }) {
   if (typeof junctionReference === "string") junctionReference = readJunctionReference(junctionReference);
@@ -31,6 +32,16 @@ function handle(request, response, area, context, junctionReference, debug = fal
   if (request.method === "GET" && url.pathname === "/app.css") return sendFile(response, path.join(__dirname, "client", "app.css"), "text/css; charset=utf-8");
   if (request.method === "GET" && url.pathname.startsWith("/vendor/")) return sendVendorFile(response, url.pathname, context.repoRoot);
   if (request.method === "GET" && url.pathname === "/api/state") return sendJson(response, 200, state(area, junctionReference, debug));
+  if (request.method === "GET" && url.pathname === "/api/export.zip") return Promise.resolve().then(() => {
+    const exported = exportNativeRoadPackage(area.outputs.nativeRoadDir);
+    response.writeHead(200, {
+      "Content-Type": "application/zip",
+      "Content-Disposition": `attachment; filename="${area.id}.native-road.zip"`,
+      "Content-Length": exported.bytes.length,
+      "Cache-Control": "no-store",
+    });
+    response.end(Buffer.from(exported.bytes));
+  }).catch((error) => sendJson(response, 400, { ok: false, error: error.message }));
   if (request.method === "POST" && url.pathname === "/api/traffic-signals") return readBody(request).then((body) => {
     const document = validateDocument(body, fs.readFileSync(area.input, "utf8"));
     writeJsonAtomic(area.outputs.nativeTrafficSignals, document);