Author SHA1 Message Date
que01 0f1850f740 fix: align separators at complex crosswalks 2026-09-29 10:23:13 +08:00
que01 c03a90709e fix: align complex junction separator cutoffs 2026-09-29 09:59:06 +08:00
que01 1842eb7d8c fix: clip complex junction lane separators 2026-09-29 09:23:26 +08:00
que01 05614d1a69 feat: refine complex junction geometry and workbench 2026-09-23 17:55:55 +08:00
que01 7c04d086db chore: record journal 2026-09-17 11:16:02 +08:00
que01 512333375e chore(task): archive 09-17-junction-exclusion-routing 2026-09-17 11:15:23 +08:00
que01 818d91d8b5 fix: preserve exclusions in complex junction pavement 2026-09-17 11:14:43 +08:00
que01 e8ecfecbf4 chore: record journal 2026-09-17 10:10:43 +08:00
que01 c4c25dea80 chore(task): archive 09-17-junction-layer-seams 2026-09-17 10:09:37 +08:00
que01 b9c38b0b7b docs: scope junction exclusion routing follow-up 2026-09-17 10:07:40 +08:00
que01 cfb3593a0b fix: verify and align complex junction layer seams 2026-09-17 10:07:26 +08:00
que01 79590d3d0f chore(task): archive 09-08-junction-reference-fidelity 2026-09-17 09:14:38 +08:00
que01 55888e8d91 refactor: split complex junction stages 2026-09-16 17:45:57 +08:00
que01 1679d1bfc1 fix: preserve corridor markings between complex junctions 2026-09-16 16:21:40 +08:00
que01 e0eaa1c950 fix: fill pavement gaps when junction islands move outward 2026-09-16 15:35:33 +08:00
que01 0c42eb46cd fix complex junction island geometry 2026-09-16 13:24:34 +08:00
que01 c3579074fd fix: keep complex islands beyond outer lane edge 2026-09-15 13:53:31 +08:00
que01 3ed503a986 fix: keep island contact polygon inside boundary 2026-09-15 13:24:16 +08:00
que01 95b8f068aa fix: curve complex island away from junction core 2026-09-15 11:06:30 +08:00
que01 f122e8236a fix: close divided two-node T junction pavement 2026-09-15 09:54:46 +08:00
que01 fda733ce72 fix: fill internal complex junction pavement holes 2026-09-14 18:12:18 +08:00
que01 a2bce9f465 fix: render only unified junction pavement 2026-09-14 17:47:50 +08:00
que01 7ca57a68e6 fix: limit junction pavement to arm crossings 2026-09-14 16:52:21 +08:00
que01 8882754b23 fix: publish unified complex junction pavement 2026-09-14 16:43:45 +08:00
que01 787faa7604 Revert "fix: pave complex junction crossings"
This reverts commit 914adcc4e6.
2026-09-14 16:02:16 +08:00
que01 914adcc4e6 fix: pave complex junction crossings 2026-09-14 15:54:39 +08:00
que01 062f20f34c fix: preserve approach lane separators near junction controls 2026-09-14 15:24:50 +08:00
que01 ad0f55e79d docs: record preliminary junction visual acceptance 2026-09-14 14:33:35 +08:00
que01 92c5977dd6 docs: add junction visual acceptance checklist 2026-09-14 14:22:38 +08:00
que01 6b11c640e1 docs: align facility validation with crossing provenance 2026-09-14 14:18:34 +08:00
que01 edadf98df1 test: verify published layers stay on pavement 2026-09-14 14:13:02 +08:00
que01 0f9dcace3d docs: clarify automatic region solving scope 2026-09-14 14:06:46 +08:00
que01 36c5d5c4c8 test: cover multiple automatic exclusion holes 2026-09-14 14:00:52 +08:00
que01 3d5cc2de6b docs: record preview computation contracts 2026-09-14 13:52:42 +08:00
que01 82846cdebc perf: cache bundled turn lane manifest 2026-09-14 13:48:27 +08:00
que01 78c357e445 docs: close existing facility linkage acceptance 2026-09-14 13:39:24 +08:00
que01 aeccae1187 docs: record junction editor browser verification 2026-09-14 13:28:50 +08:00
que01 d0a4cfa7ff perf: reduce junction preview handle and collision work 2026-09-14 12:14:59 +08:00
que01 6a8f026d12 fix: fill junction core and connect cluster lane trajectories 2026-09-14 10:47:25 +08:00
que01 695bf21a84 fix: coordinate crosswalk landings across all four islands 2026-09-14 09:43:12 +08:00
que01 1b91e280bc feat: solve complete junction island contacts 2026-09-14 08:59:32 +08:00
que01 7a7912f302 fix: align junction crossings and round pedestrian islands 2026-09-11 17:35:32 +08:00
que01 76f81d024a feat: establish junction region geometry baseline 2026-09-11 15:27:53 +08:00
que01 de97600fe8 feat: restore inferred corner islands 2026-09-11 13:27:17 +08:00
que01 f356e8e99c fix: render complex core above corner fills 2026-09-11 13:20:19 +08:00
que01 df39237829 fix: keep corner crosswalks within wedges 2026-09-11 13:16:36 +08:00
que01 14930c5dd6 fix: resolve multi-carriageway complex cores 2026-09-11 13:11:08 +08:00
que01 eaafcd85da feat: close four-arm divided junction cores 2026-09-11 13:03:09 +08:00
que01 6cfcd5d4b2 feat: restore complex corner crossings 2026-09-11 12:49:22 +08:00
que01 376427d270 fix: default complex junction crosswalks 2026-09-11 12:40:46 +08:00
que01 3575e372bd docs: record junction fidelity validation 2026-09-11 12:31:13 +08:00
que01 ff11dc2654 test: validate three-arm junction editing workflow 2026-09-11 12:10:53 +08:00
que01 f40caaa264 fix: hide handles for unavailable junction structures 2026-09-11 11:37:58 +08:00
que01 2b79085042 feat: publish junction region connectivity metrics 2026-09-11 11:31:21 +08:00
que01 3a8af43140 fix: require source evidence for complex crosswalks 2026-09-11 11:24:19 +08:00
que01 858db529ae test: verify complex entry edits in workbench 2026-09-11 09:56:47 +08:00
que01 067c0e370d feat: complete carriageway direction interaction 2026-09-11 09:51:02 +08:00
que01 a5089220b5 fix: align carriageway edge handles with entry geometry 2026-09-11 09:36:31 +08:00
que01 44fa82299b fix: 保存车行道左右边界编辑状态 2026-09-10 15:33:52 +08:00
que01 f1a5b284a7 test: include carriageway edit handles in api scope 2026-09-10 14:06:56 +08:00
que01 f722cadf25 feat: publish independent carriageway edge handles 2026-09-10 13:56:12 +08:00
que01 c77308c170 feat: publish complex carriageway position handles 2026-09-10 13:46:05 +08:00
que01 53b63ae333 test: expose complex carriageway edit handles 2026-09-10 13:27:07 +08:00
que01 e2ec728af3 fix: keep comparison baseline stable without junction quality 2026-09-10 12:21:47 +08:00
que01 7e4d77afbe fix: complete complex carriageway edit data flow 2026-09-10 12:18:52 +08:00
que01 655e7efaef fix: preserve complex edge edit values 2026-09-10 11:38:47 +08:00
que01 936354fec8 fix: apply complex carriageway edge offsets 2026-09-10 11:17:15 +08:00
que01 38dc9d6f52 feat: support complex carriageway edge offsets 2026-09-10 11:01:11 +08:00
que01 3e74732190 feat: support complex carriageway direction edits 2026-09-10 10:44:43 +08:00
que01 88b7e17f4d feat: support complex carriageway position edits 2026-09-10 10:37:46 +08:00
que01 92894c7e4f feat: report complex junction layer coverage 2026-09-10 10:22:06 +08:00
que01 5ec46c3b3e feat: include junction quality in compile reports 2026-09-10 10:14:27 +08:00
que01 3cf6bebb10 feat: diagnose junction seam tolerance violations 2026-09-10 10:08:21 +08:00
que01 efb7de6a83 feat: expose junction region quality metrics 2026-09-10 10:05:06 +08:00
que01 bde28c8743 test: cover safe junction exclusion holes 2026-09-10 10:00:38 +08:00
que01 609935d209 feat: preserve safe junction exclusion holes 2026-09-10 09:56:21 +08:00
que01 c003edaf51 fix: respect finite extents in junction region overlap 2026-09-10 09:47:07 +08:00
que01 101bcb3792 fix: constrain complex junction corner and crossing publication 2026-09-09 17:53:32 +08:00
que01 79f2ee5d4e fix: suppress orphaned complex junction attachments 2026-09-09 17:44:00 +08:00
que01 cd65dbe879 fix: share complex junction entry sections across layers 2026-09-09 17:23:17 +08:00
que01 49212b3f34 feat: measure junction shared seam errors 2026-09-09 17:09:41 +08:00
que01 79f83412e6 feat: complete complex junction transition editing 2026-09-09 16:57:47 +08:00
que01 801d8be980 feat(junction): expose transition length handle 2026-09-09 15:40:41 +08:00
que01 21c05800c0 docs(trellis): record junction task phase closure 2026-09-09 15:32:32 +08:00
que01 413b3d9b89 feat(junction): validate transition length constraints 2026-09-09 15:23:03 +08:00
que01 95c49722d4 test(junction): bound transition length by source availability 2026-09-09 14:54:06 +08:00
que01 433499bbcb feat(junction): centralize transition length derivation 2026-09-09 14:49:54 +08:00
que01 fe6a160741 docs(trellis): define transition edit contract milestone 2026-09-09 14:45:28 +08:00
que01 febaeb4092 docs(trellis): record seam tolerance measurement 2026-09-09 14:30:40 +08:00
que01 a4b1ad8510 feat(junction): report shared seam tolerance 2026-09-09 14:29:12 +08:00
que01 134e0752ed docs(trellis): record boundary invariant evidence 2026-09-09 14:25:35 +08:00
que01 011874dd33 feat(junction): publish entry ring status 2026-09-09 14:17:44 +08:00
que01 a37c707188 feat(junction): validate entry ring geometry 2026-09-09 14:09:44 +08:00
que01 a90826efed test(junction): reject zero-area approach surfaces 2026-09-09 14:04:17 +08:00
que01 b3a2d5fcd5 test(junction): validate compiled approach rings 2026-09-09 13:58:10 +08:00
que01 2f627df232 refactor(junction): share canonical entry rings 2026-09-09 13:55:52 +08:00
que01 f4cf42f1c6 test(junction): protect touching exclusion boundaries 2026-09-09 13:50:54 +08:00
que01 d35b704e5e docs(trellis): record irregular arm matrix coverage 2026-09-09 13:48:30 +08:00
que01 ff7f011826 test(junction): cover irregular six-arm closure 2026-09-09 13:46:47 +08:00
que01 1de7bc2bd0 test(junction): cover irregular five-arm closure 2026-09-09 13:41:30 +08:00
que01 173296e348 test(junction): cover skew four-arm closure 2026-09-09 13:38:32 +08:00
que01 9df315ec16 test(junction): cover skew three-arm closure 2026-09-09 13:32:08 +08:00
que01 103004b30a test(junction): enforce deterministic boundary planning 2026-09-09 13:28:40 +08:00
que01 a090cb1e58 test(junction): isolate foreign junction plans 2026-09-09 13:26:16 +08:00
que01 9af3afcbbd docs(trellis): record junction matrix milestone 2026-09-09 12:32:17 +08:00
que01 57530016f7 feat(junction): publish transition status in manifest 2026-09-09 12:23:56 +08:00
que01 a6121aecfe test(junction): cover short transition rejection 2026-09-09 12:19:45 +08:00
que01 a476faf171 test(junction): preserve topology under translation 2026-09-09 12:17:03 +08:00
que01 af286c6149 test(junction): cover heading wrap stability 2026-09-09 12:15:07 +08:00
que01 88fcee94a0 test(junction): validate offset unequal core closure 2026-09-09 12:08:00 +08:00
que01 a22319a149 fix(junction): protect entry surfaces from exclusion regions 2026-09-09 12:01:16 +08:00
que01 9b6b5b5791 test(junction): keep facilities aligned with width edits 2026-09-09 11:58:53 +08:00
que01 6c7d81df35 fix(junction): diagnose unsupported entry transitions 2026-09-09 11:53:53 +08:00
que01 b1fd54f0f8 feat(junction): expose entry transition feasibility 2026-09-09 11:47:05 +08:00
que01 e5d805a369 fix(junction): reject collapsed core boundary edges 2026-09-09 11:44:51 +08:00
que01 c4902cd4c8 test(junction): preserve identity across input reorder 2026-09-09 11:40:17 +08:00
que01 9ec99ed03e test(junction): enforce core boundary invariants 2026-09-09 11:39:03 +08:00
que01 234dd46f59 test(junction): cover six-arm rotation stability 2026-09-09 11:34:56 +08:00
que01 f18dd0c0eb feat(junction): list sourced islands 2026-09-09 11:14:28 +08:00
que01 db904d3194 chore(junction): type facility provenance 2026-09-09 11:08:16 +08:00
que01 8929edcee4 feat(junction): show facility evidence 2026-09-09 10:58:17 +08:00
que01 0e162d1f43 feat(junction): project sourced islands 2026-09-09 10:54:45 +08:00
que01 cd3a9c9613 fix(junction): trim complex preview lanes 2026-09-09 10:33:24 +08:00
que01 4e7274ec61 fix(junction): bound complex cutback transitions 2026-09-09 10:28:55 +08:00
que01 280b726c6f feat(junction): taper complex carriageway edits 2026-09-09 10:24:57 +08:00
que01 d353b48a0b fix(junction): anchor controls to sourced crossings 2026-09-09 10:21:26 +08:00
que01 a98d170757 fix(junction): align complex crossing handles 2026-09-09 10:20:01 +08:00
que01 48fd432266 feat(junction): place sourced complex crossings 2026-09-09 10:15:33 +08:00
que01 d49cdab40a feat(junction): mark complex crossing evidence 2026-09-09 10:13:25 +08:00
que01 c14b8b09f2 feat(junction): publish sourced traffic islands 2026-09-09 10:05:43 +08:00
que01 3bf2edaf99 fix(junction): reject overlapping exclusion cores 2026-09-09 10:00:32 +08:00
que01 75bdfbe607 test(junction): cover known island exclusions 2026-09-09 09:57:14 +08:00
que01 4b8f37a219 feat(junction): preserve known traffic island regions 2026-09-09 09:43:55 +08:00
que01 b6f4dfeb0c fix(junction): omit unsupported corner facilities 2026-09-09 09:23:58 +08:00
que01 f56c0978b0 refactor(junction): keep edit metrics pure 2026-09-09 09:17:52 +08:00
que01 88d8b841e5 feat(junction): close verified complex cores 2026-09-09 09:15:58 +08:00
que01 b4abfdb870 feat(junction): derive complex approach boundary sections 2026-09-08 18:02:24 +08:00
que01 4de971ce68 fix(junction): align complex boundary trims 2026-09-08 17:57:03 +08:00
que01 a12e2ac823 feat(junction): share complex topology build plan 2026-09-08 17:47:35 +08:00
que01 855400fba2 fix(junction): keep complex carriageways connected 2026-09-08 17:16:51 +08:00
que01 53a2cb3450 fix(junction): make complex corner radius responsive 2026-09-08 17:06:05 +08:00
que01 36a8291c05 fix(junction): resolve complex handle preview roads 2026-09-08 16:16:59 +08:00
que01 bf26a74a33 chore(task): archive 09-08-complex-junction-editing 2026-09-08 15:57:33 +08:00
que01 f515a1e934 docs(task): record complex junction delivery 2026-09-08 15:57:33 +08:00
que01 880ca8da91 chore(task): archive complex junction acceptance stage 2026-09-08 15:55:56 +08:00
que01 6896f8a554 chore(task): archive complex junction lifecycle stage 2026-09-08 15:42:10 +08:00
que01 a5f64a2349 fix(junction): isolate lifecycle previews and drafts 2026-09-08 15:28:06 +08:00
que01 89f4ce79b0 chore(task): archive complex junction facilities stage 2026-09-08 15:08:45 +08:00
que01 49a44fdf73 feat(junction): edit complex crossing facilities 2026-09-08 15:05:00 +08:00
que01 bb5dc01c07 chore(task): archive complex junction geometry stage 2026-09-08 14:31:21 +08:00
que01 80f122be46 feat(junction): edit complex cutbacks and corners 2026-09-08 14:30:43 +08:00
que01 d0e1f62f2b chore: record journal 2026-09-08 12:11:57 +08:00
que01 971be2314c chore(task): archive complex junction width stage 2026-09-08 12:10:35 +08:00
que01 c4bcbe8ff9 feat(junction): enable complex carriageway width editing 2026-09-08 12:09:44 +08:00
que01 56647fcdaa chore: record journal 2026-09-08 11:31:59 +08:00
que01 3a151e97c3 chore(task): archive complex junction identity stage 2026-09-08 11:27:39 +08:00
que01 0a5a229ce3 feat(junction): establish stable complex junction structure 2026-09-08 11:25:57 +08:00
que01 bd8b55e58b docs(task): record complex junction editing roadmap 2026-09-08 11:25:05 +08:00
que01 bba3ebe4b0 chore: ignore test result artifacts 2026-09-08 09:02:17 +08:00
que01 2b49a78b99 style(junction): fold facilities and clarify diagnostics 2026-09-07 18:02:34 +08:00
que01 a0bdd25c9d chore: record journal 2026-09-07 17:39:10 +08:00
que01 3ba7e6f1e8 chore(task): archive JunctionTools Stage 5 2026-09-07 17:14:37 +08:00
que01 0065c3eaec feat(junction): project advanced facilities and associations 2026-09-07 17:12:29 +08:00
que01 61ae90352a chore: record journal 2026-09-07 16:47:22 +08:00
que01 fc962ce402 chore(task): archive JunctionTools Stage 4 2026-09-07 16:45:59 +08:00
que01 92ab2edd96 feat(junction): add reference geometry comparison layer 2026-09-07 16:45:37 +08:00
que01 4519cad562 chore: record journal 2026-09-07 15:50:49 +08:00
que01 73ce56c290 chore(task): archive JunctionTools Stage 3 2026-09-07 15:48:24 +08:00
que01 63c6cefce7 feat(junction): enforce stage3 geometry validation on save 2026-09-07 15:47:34 +08:00
que01 cb55b3ad68 chore: record journal 2026-09-07 15:24:47 +08:00
que01 06a58c9dbf chore(task): archive JunctionTools Stage 2 2026-09-07 15:23:46 +08:00
que01 de6ef8e64b feat(junction): add stage2 object selection scope controls 2026-09-07 15:23:03 +08:00
que01 b89c5fd174 chore: record journal 2026-09-07 14:56:16 +08:00
que01 977858b283 chore(task): archive JunctionTools Stage 1 2026-09-07 14:52:33 +08:00
que01 fc7fe81eff feat(junction): expose stage1 structure and standards panel 2026-09-07 14:52:06 +08:00
que01 0f804b71d1 chore: record journal 2026-09-07 14:23:11 +08:00
que01 d61c86ed2c chore(task): archive completed road editor workflows 2026-09-07 14:21:57 +08:00
que01 39e338668b chore: record journal 2026-09-07 14:14:47 +08:00
que01 91e088b25a chore(task): archive 09-07-junctiontools-standards 2026-09-07 14:12:24 +08:00
que01 61cf276745 feat(junction): add structure and standards contract 2026-09-07 14:11:44 +08:00
que01 8d6f531377 chore: record journal 2026-09-07 10:58:40 +08:00
que01 cdcc606391 chore(task): archive 09-04-complex-junction-shapes 2026-09-07 10:52:57 +08:00
que01 a359f88edc feat(junction): classify complex junction shapes 2026-09-07 10:52:12 +08:00
que01 38ea779d9b feat: add complex junction selection markers 2026-09-04 17:09:32 +08:00
que01 57248f1aa4 chore(task): archive direct edit junction tools 2026-09-04 14:52:20 +08:00
que01 1f439d98de fix(workbench): show junction traffic signals 2026-09-04 14:23:27 +08:00
que01 f10a5da325 feat(workbench): stabilize junction tools workspace 2026-09-04 09:46:19 +08:00
que01 e6b822416d fix(workbench): keep map visible in junction tools 2026-09-03 14:04:13 +08:00
que01 c9d9e45f48 fix(workbench): clarify junction browse mode 2026-09-03 13:54:26 +08:00
que01 39d7453ebc chore(tasks): archive completed edit workflows 2026-09-03 13:34:25 +08:00
que01 a78f5257fc test(junction): verify preview and compile parity 2026-09-03 13:32:37 +08:00
que01 3811790dc8 fix(workbench): persist junction workspace edits 2026-09-03 12:39:01 +08:00
que01 b7d9a1973e test(workbench): cover junction workspace deep links 2026-09-03 12:35:45 +08:00
que01 8c99bb7340 docs(tasks): plan junction tools delivery 2026-09-03 12:28:47 +08:00
que01 6a0736517f chore(task): record junction facilities progress 2026-09-03 12:13:01 +08:00
que01 ecfa391eea feat(workbench): summarize junction facilities and diagnostics 2026-09-03 12:07:50 +08:00
que01 1bd1fd712f chore(task): record junction geometry progress 2026-09-03 12:02:48 +08:00
que01 60e28f6b7a feat(workbench): expose junction geometry parameters 2026-09-03 12:02:16 +08:00
que01 f6f51fe90b feat(compile): expose effective junction plans 2026-09-03 11:44:26 +08:00
que01 4b38ce3c31 fix(workbench): require explicit junction draft exit 2026-09-03 11:28:49 +08:00
que01 c59fb704ef chore(task): archive 09-02-junction-tools-workspace 2026-09-03 11:24:23 +08:00
que01 2504e8342f feat(workbench): add junction tools workspace shell 2026-09-03 11:20:37 +08:00
que01 96833d3a63 chore(task): archive 09-02-junction-detection-hotspot 2026-09-03 11:13:45 +08:00
que01 7d9b0f46d4 feat(workbench): add junction hotspot entry points 2026-09-03 11:12:22 +08:00
que01 bd7b049930 chore(task): archive 09-02-junction-requirements-research 2026-09-03 11:05:03 +08:00
que01 6b75d273e7 chore(task): archive 09-01-lane-maneuver-position-drag 2026-09-03 09:51:14 +08:00
que01 15be3480ed chore(task): archive workbench-component-boundaries 2026-09-03 09:50:01 +08:00
que01 58f59c8a45 test(workbench): verify exported package contract 2026-09-02 17:52:54 +08:00
que01 fcb07b8396 test(workbench): add browser regression coverage 2026-09-02 17:39:25 +08:00
que01 2fb9db65e5 test(workbench): lock cross-domain edit history 2026-09-02 16:57:36 +08:00
que01 bb6c51c489 fix(workbench): preserve cross-domain undo order 2026-09-02 16:41:12 +08:00
que01 31552a5b6f feat(workbench): drag control markings as elements 2026-09-02 16:04:38 +08:00
que01 834470cfa1 refactor(workbench): split editor state and components 2026-09-02 15:04:58 +08:00
que01 caa3cb843f feat(workbench): add traffic signal rotation handle 2026-09-02 11:38:30 +08:00
que01 9b7c3d59bd feat(workbench): stage traffic signal edits 2026-09-02 09:30:03 +08:00
que01 9c83392b97 feat(workbench): drag traffic signal assemblies 2026-09-02 09:05:56 +08:00
que01 cf5bc0602b feat(workbench): improve traffic signal editing 2026-09-02 09:04:56 +08:00
que01 00d5f7650f refactor(workbench): use persistent mode switch 2026-09-01 17:20:16 +08:00
que01 c804a373ca feat(workbench): unify lane maneuver edits in v2 2026-09-01 16:46:22 +08:00
que01 118dc8e9aa fix(workbench): preview lane arrow drag 2026-09-01 15:04:11 +08:00
que01 fe73d993a9 fix(workbench): preview staged lane arrow overrides 2026-09-01 14:46:22 +08:00
que01 0318876e6a fix(compile): validate direct edit constraint ranges 2026-09-01 14:28:24 +08:00
que01 bb108267e3 feat(workbench): organize map editing panels 2026-09-01 13:47:30 +08:00
que01 6d80597642 feat(workbench): preview and drag lane turn arrows 2026-09-01 11:47:35 +08:00
que01 9cb715a592 feat: drag lane turn arrows along their lanes 2026-09-01 10:24:59 +08:00
que01 5457f960ff chore: record lane maneuver workbench session 2026-09-01 09:21:58 +08:00
que01 3d135761e7 fix: outline selected turn arrows 2026-09-01 09:21:24 +08:00
que01 2415733597 chore(task): archive lane maneuver override 2026-09-01 09:17:57 +08:00
que01 e48eb15827 feat: edit lane turn arrows in workbench 2026-09-01 09:17:24 +08:00
que01andClaude Opus 5 8b84166e6f chore(task): record lane-maneuver delivery and the UI prerequisite
All seven criteria pass against a live area. Notes what a UI would need first:
turn arrows group by lane plus maneuver, a two-field key, where crosswalks and
stop lines group by a single property — so the element registry's groupProperty
has to become composable before arrows can join it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 18:02:27 +08:00
que01andClaude Opus 5 335c8ea68a feat: override which turn arrow a lane shows
The arrow on a lane came from the OSM turn:lanes tag with no way to change it,
and a lane the tag skipped got no arrow at all. lane-maneuver is a v1 override
that sets it.

v1 rather than a v2 constraint, because "which arrow" is a discrete attribute of
a lane with no station to anchor to, while every v2 anchor is positional. The
existing road override already covers OSM-derived values this way — laneCount,
width, sidewalks — and this is the same kind of thing. Arrow *placement* is the
positional half and stays out; it also still has an open question about whether
a group is a lane or a single arrow.

Three behaviours, each measured against compiled output: an override replaces
the tag's maneuver, it adds arrows to a lane the tag never marked, and '' removes
one the tag asked for. The empty string is therefore distinguished from "no
override" rather than falling through to the tag. An empty override set leaves
the arrows byte-identical and the fixtures untouched.

Validation lists the accepted maneuvers and rejects anything else, including
correctly-spelled components in the wrong order. It cannot be left to
normalizeManeuver(), which returns unrecognised input unchanged — a typo would
otherwise reach the template lookup and silently produce no arrow.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 18:00:53 +08:00
que01andClaude Opus 5 15d41be444 chore(task): record progress and the blocker on corner grips
Steps 1, 2 and 4 are done and step 3 is parked with a reason: the client never
reads affects and no highlighting exists, so fixing it alone changes nothing a
user can see. It belongs with the highlight, as one piece of work.

Step 5 has a design question that should be settled before code. The size value
is a pair while the drag path is scalar end to end, so a corner grip moving one
component has to preserve the other or every drag resets the half it did not
touch. Three options noted, with the reason the tempting one — letting element
controls build their own value — is the wrong shape.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 17:12:57 +08:00
que01andClaude Opus 5 f3924caa5c feat: make crosswalk size a constraint the geometry stage reads
Every zebra was six stripes at 3m by 0.45m on a 0.9m pitch, all literals. Depth
and stripe count are now a constraint, junction-crosswalk-size, and the loop
reads them.

The span across the road stays derived rather than stored: it is count times
pitch, and pitch is fixed because stripe and gap widths are standardised while
the road they cross is not. Widening a crossing means adding stripes, which is
what a real one does, and it is why the span quantises in 0.9m steps.

That also fixes a span pinned at 4.95m regardless of the street. Measured, every
crossing sat on a 6.50m carriageway and covered under four fifths of it. The
default now follows the segment width — both directions, since a crossing spans
the carriageway — giving eight stripes and 6.74m, reaching the kerb rather than
stopping short. Fixture baselines move for exactly two entries on the one area
with crossings; the area without them is untouched.

No handle is published yet. design.md requires proving compileGeometry() consumes
a parameter before any grip is drawn — the rule left over from profile.interval
shipping a handle that did nothing — so the grips come next, on a value already
known to work.

Adding the kind made the client's exhaustive scalar switch fail to compile, which
is the check working: size is a pair and has no dragged-scalar form, so that case
now says so and throws rather than writing half a value.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 17:10:45 +08:00
que01andClaude Opus 5 84c82f3f09 feat: select and drag stop lines the same way as crosswalks
Element identity moves behind a provenance-keyed registry, and stop lines join
as its second entry. Selection, the dashed box and the drag all work unchanged —
the registry supplies the group key, the layer the members live in, and the
constraint that moves them.

Stop lines are the useful second case rather than an easy one. They are a group
of one where a crosswalk is six, so adding them proves the grouping does not
quietly depend on there being parts; and they share crossing_node_id with the
zebra they protect on all eight measured groups, so provenance has to pick the
type before the key is ever read. A test holds both.

The registry promises only what the measurements support: provenance picks the
type, then a key picks the group. Arrows are deliberately absent — their group
keys are two-field and derived, group sizes run to 230, and neither has a
constraint kind the geometry stage reads.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 15:36:33 +08:00
que01andClaude Opus 5 323ff9279f docs: map which markings the element model reaches
Measured the grouping of every marking layer. Stop lines are nearly free — same
feature builder, same key shape, an existing constraint kind, and a sweep shows
the offset tracks one-to-one across its whole range with no dead zone. Arrows
are not: neither kind exists and neither is read by the geometry stage.

The trap is that crosswalks and stop lines share crossing_node_id on all eight
groups, so grouping has to branch on provenance before touching the key or the
two merge into one element. That is already how element.ts works and a test
holds it.

What the data earns is a provenance-keyed registry and nothing more: group keys
are single-field, two-field and derived; group sizes run 1 to 230; two element
types have no constraint at all. A universal element protocol would be inventing
past the evidence, which the PRD rules out.

Also records delivery state — steps 1 and 2 done, 3 through 5 not started — so
the task is not mistaken for complete.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 15:21:01 +08:00
que01andClaude Opus 5 5c89d92041 docs: record the two-road ambiguity and the range contract
The directional-road trap cost two rounds in one session — once on the client,
once in the solver — and both times produced a plausible number attached to the
wrong object, which nothing but a segment with two of the thing will catch.

Also tabulates what measuring three handle ranges turned up: one rejects past a
third of its declared span, one goes silently inert over most of it, and one
would happily place a stop line 126m from the junction it protects. Each was
derived independently, and each was wrong in its own direction.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 15:17:01 +08:00
que01andClaude Opus 5 59e3dc2320 chore(task): narrow range validation to the kinds still affected
The silently-inert case is fixed for crosswalk inset, so this task is down to
the edge-offset case and the missing server-side check. Records the reusable
shape — ceilings derived from geometry rather than declared as constants — and
the trap that cost a round: two directional roads of one segment can meet at a
junction serving different objects, so taking the first match publishes one
road's bound on the other's handle.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 15:04:23 +08:00
que01andClaude Opus 5 479ffd00ed fix: publish the crosswalk inset ceiling that actually moves the zebra
Every junction-crosswalk-inset handle advertised max 8. Sweeping the real
response across eight groups, the ceiling ran 1.0 to 4.5 and varied per
approach, so 44-88% of the declared range moved nothing and returned no
diagnostic. Two approaches had a ceiling at or below the 1.5 default, meaning
dragging outward there did nothing at all — which is what made direct editing
look broken rather than limited.

crossingJunctionInset() stops responding once the inset reaches the cutback, and
sooner still when the crossing sits beyond the 4m cap, giving
cutback - max(0, junctionDistance - 4). Predicted ceilings matched all eight
measurements within the 0.5m sweep step, and the published max now matches them
8/8 where it used to be a flat 8.

The distance needs to know which crossing an approach serves, which lived only
inside compileControlMarkings(). crossing-approach.js now holds that rule at road
level, which is model-only and so usable from the solver. Behaviour is
unchanged: every lane of a road shares its junction distance, so the compiler's
(road, lane) ordering already grouped by road — fixtures confirm the geometry is
byte-identical.

Both directional roads of a segment can meet at one junction serving different
crossings; taking the first match published one road's ceiling on the other's
handle. The road that ends at this node wins, which is the same rule the client
uses to find the handle and the same one crossingJunctionInset() applies.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 15:00:08 +08:00
que01andClaude Opus 5 8a039f47ab fix: keep the selection box on the crosswalk it is drawn around
The box measured state.layers, which is the last compiled output and does not
change while editing. The zebra is drawn from the preview, so it slid out from
under its own box on every drag and only caught up after a recompile.

Reading the preview when one exists puts them back on the same geometry. A null
preview layer already means "back to baseline", which is what the fallback says.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 14:22:28 +08:00
que01andClaude Opus 5 4b70b0221d docs: record the crosswalk inset dead zone
Sweeping the declared [0, 8] range and measuring where the group actually lands:
0 to 3.2 tracks one-to-one, and 3.2 to 8 does not move at all. No diagnostic, no
feedback — roughly 60% of the advertised range is inert.

crossingJunctionInset() drives it. targetDistance bottoms out once inset reaches
the approach's cutback, and a 4m cap sits above that, so the real ceiling varies
per approach while the manifest publishes a flat 8 for all of them.

This is worse than the edge-offset case already on file. That one refuses and
says so; this one silently does nothing, which is indistinguishable from a broken
control — the exact failure the interval flag exists to prevent, occurring in the
upper half of a range rather than across a whole handle. A user whose first drag
lands in the dead zone concludes direct editing does not work.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 14:11:57 +08:00
que01andClaude Opus 5 7b5bb753a7 feat: drag the crosswalk itself, not a dot beside it
A dashed box now hugs the selected group and is the thing you grab. It is
oriented along the crossing rather than along latitude and longitude: measured
groups run at azimuths from 14 to 105 degrees, so an axis-aligned box would sit
visibly askew and read as a bug. Extents come out at 3.00m by 4.94m on every
group, matching the compiler's literals.

The box carries the handleId of the control that moves it rather than an id of
its own, so grabbing it runs the existing value gesture — no second drag branch,
no second constraint, and the dot still works where the two overlap.

Resolving that control needs more than the segment: 15 of 23 segments carry two
crosswalk-inset handles, one per junction, and one segment carries two groups.
The junction is the road's last source node, which is the rule
crossingJunctionInset() already applies rather than a guess, and it resolves 8/8
groups uniquely — the two-group segment included, told apart by direction.

Also stops a gesture that never moved from becoming an edit. handleUpEvent
always reports a final value, so a tap committed a constraint equal to the one
already there. The box is a large target, which turns that from a curiosity into
something a user would hit routinely.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 14:06:51 +08:00
que01andClaude Opus 5 2694cad619 feat: select a crosswalk group by clicking any of its stripes
A crosswalk renders as six stripe features but is edited as one thing. Clicking
one now resolves the whole group, and clicking anything else drops the selection
so a box cannot outlive what it was drawn around.

The group id needed no compiler change: crosswalk:node/<crossingId> is already
stable, because compileControlMarkings() emits exactly one group per crossing
from a single candidate road. Verified against real output — 48 stripes, 8
groups of 6, nothing ungrouped, and none of the 8 stop lines mistaken for one,
since both share controlFeature() and are told apart by provenance. Grouping
therefore reads a published identifier rather than clustering on proximity,
which prd.md forbids.

Two supporting fixes in MapCanvas: the select callbacks join the existing
callback ref, and an empty click now reports background instead of returning
early. The listener is registered once, so it had been holding the first
render's closures — harmless while they only called stable setters, and not
survivable now that one of them reads current layers.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 13:35:59 +08:00
que01andClaude Opus 5 623481fd2c chore(task): correct the elementId premise and split the first gate
Measured rather than assumed: grouping the 48 stripes by crossing_node_id yields
exactly 8 groups of 6, and no crossing maps to more than one road. The uniqueness
is structural — compileControlMarkings() iterates model.crossings and each pass
emits one group from one candidate — so crosswalk:node/<crossingId> is already a
stable group id and needs no compiler change.

The earlier claim that no group id existed conflated the crossing node
(node/-26452, the pedestrian crossing) with the junction node (node/1140799725).
Different ids. Grouping client-side therefore reads a published identifier rather
than clustering by proximity, which is what the PRD forbids.

The missing affects entries are real and unchanged, but they only degrade
drag highlighting; they do not block selection. The two are now separate steps,
and selection moves first because it costs nothing on the server.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 13:13:09 +08:00
que01andClaude Opus 5 086939be93 chore(task): re-plan the crosswalk experiment around one root cause
Three symptoms turned out to be one hole. junctionAffects() builds
junctionSurface + roadAffects + connectors and never adds crosswalks, so on an
area with 48 of them the crosswalk-inset handle reports 59 affected features and
zero crosswalks. The cause is that stripe ids key off the crossing node while the
solver has no approach-to-group mapping — which is also why there is no stable
elementId and why clicking a stripe cannot select the group. Publishing that
mapping resolves all three, so it is now the first gate rather than three
separate steps.

Corner resize moves into the first phase by decision; rotation is deferred, since
it needs a new constraint kind and the compiler has to consume it before any grip
may be drawn.

Sizing semantics are settled: stripe depth is a stored number, but span is
count x pitch, so the corner drag varies the count at a fixed 0.9m pitch and
therefore quantises. That is honest rather than janky and the UI has to read as
deliberate snapping. It also fixes span being pinned at 5.4m regardless of road
width, which will move fixture baselines.

Records the data prerequisite: crossing nodes are required, and the current
import had none, which is what made the handle look broken.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 13:02:46 +08:00
que01andClaude Opus 5 2ef24539f9 docs: record the two-channel input rules
Four things the parameter panel settled that the next input channel should not
have to rediscover: where the channels meet, why a drag clamps while a field
refuses, why a focused field owns its own text, and why reset disables rather
than deletes.

The clamp/refuse split is the one most likely to be reported as an
inconsistency. It is one invariant with two honest expressions — a pointer
cannot state an intent it never reached, so it stops; typed text is an intent,
so rewriting it hides a typo behind a plausible number.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 12:51:24 +08:00
que01andClaude Opus 5 6663c289e7 chore(task): bound the crosswalk experiment to position editing
A four-arm junction already carries 20 handles across 4 segments, and the main
map shows only the selected segment's — so seeing one junction whole takes four
selections. That is why element-level selection is a prerequisite for complex
junction work rather than a refinement of it.

The experiment stays crosswalk-only by decision, to keep the risk small. What
that costs is now written down: a crosswalk moves but does not reshape the
junction, so passing this proves the select-and-position path and nothing about
approach width, cutback or corner radius, which change the junction polygon
itself and have to be validated separately.

Also records that the parameter form half already exists, so the element
controls join the existing exits instead of growing a second preview or undo
path.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 12:04:09 +08:00
que01andClaude Opus 5 1c27501534 feat: edit road parameters by number as well as by drag
The map had one input device. A drag projects a pointer onto the manifest's
axis; there was no way to state a value, read one, or withdraw one.

Both channels now meet at the same three exits in App.tsx — draftValue()
previews, settleValue() commits one undoable command, abandonGesture() puts the
settled state back — so nothing about the constraint, the debounce or the
previewSeq arbitration is implemented twice. EditSession is untouched: focus and
blur land on the gesture boundary that pointerdown and pointerup already used,
which is why typing 1.53 is one undo step rather than four.

Three rules the two devices do not share:

- Live drag values bypass React and write the input's value directly, per
  direct-edit-client.md §7. A layout effect re-applies them after a mid-drag
  preview replaces the manifest, and drops the override once the manifest
  reports the value the drag asked for.
- Typed values out of range are refused, not clamped. A pointer cannot state an
  intent it never reached, so a drag clamps; typed text is an intent, and a
  clamped typo reads as a plausible value that can go unnoticed. The offered
  extremes round inward — a real max of 2.925 renders as 2.93 under
  nearest-rounding, which the range it came from would then reject.
- Reset disables the constraint rather than deleting it: validateEditDocument()
  rejects an operation naming a constraint that is not in the document. This is
  the one edit a drag cannot express, since a drag can set a value but never
  withdraw one.

Interval editing stays behind intervalEditingSupported, which is still false —
compileGeometry() does not read profile.interval, and a control that changes
nothing is worse than no control. The conversions are implemented and tested so
the row appears when the flag flips.

Probing a live manifest turned up a defect that is not from this change and is
not fixed here: an edge offset advertises ±2.925 while the solver rejects past
about ±1. Evidence is in the task's research/, and the requirement moved to
08-31-constraint-range-validation.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 11:58:00 +08:00
372 changed files with 26673 additions and 2093 deletions

No files matched your search

+1
View File
@@ -14,3 +14,4 @@ workbench-data/
# Claude 本机私有设置,不进入版本控制
.claude/settings.local.json
test-results/
+370 -1
View File
@@ -10,7 +10,7 @@ It is required because the feature crosses compiler, storage, and HTTP layers.
```js
resolveDirectEditConstraints(model, editDocument, context)
// -> { roadProfiles, junctionPlans, constraintStates, handles, diagnostics }
// -> { roadProfiles, junctionPlans, clusterPlans, constraintStates, handles, diagnostics }
GET /api/edit-state
POST /api/edit-preview
@@ -40,6 +40,10 @@ POST /api/revisions/:id/rebase
- `POST /api/revisions/:id/rebase` is read-only and returns status counts plus
per-constraint details. `pending`, `conflicted`, and `stale` constraints do
not enter geometry solving.
- A resolved constraint whose saved numeric value no longer fits the current
geometry range is returned as `stale` with reason `range-out-of-bounds`.
A missing replay anchor uses reason `anchor-missing`; callers must not infer
the stale cause from the status alone.
## 4. Validation & Error Matrix
@@ -53,6 +57,7 @@ POST /api/revisions/:id/rebase
| Solver replay anchor cannot resolve | Mark `stale` or `conflicted` with diagnostic; never silently apply |
| Compiler geometry version differs | Mark all replayable constraints `recheck` without changing values |
| Invariant violation (lane width, crossing boundaries, self-intersection, connector bounds) | Return a blocking diagnostic; do not clamp or silently repair |
| Constraint value outside the current handle range | Return a blocking diagnostic; do not clamp or silently repair |
## 5. Good / Base / Bad Cases
@@ -108,6 +113,21 @@ the pure resolver remains reusable by preview and formal compilation.
The handle manifest reports `axisAzimuth = tangent + 90` for both sides, which is
therefore *right*. Handle placement must offset the left handle by `tangent - 90`.
Complex carriageway edge handles use the same convention, but their position is
the effective inner entry section rather than the legacy cutback point:
```text
innerStation = outerStation - transitionLength + positionOffset
edgeDistance = effectiveWidth / 2 + sideEdgeOffset
```
Compute the tangent at `innerStation`, then apply `directionOffsetDegrees` before
placing the left and right handles. This keeps the manifest aligned with
`JunctionBoundaryGraph` after transition, position, direction, width, or edge
edits. Tests must measure that the two handles are geographically opposite and
their separation equals `effectiveWidth + leftOffset + rightOffset` within the
geometry tolerance; checking only stored scalar values does not prove placement.
**Regression**: `makeRoadHandles()` once placed the left handle at `tangent + 90`,
drawing it over the right kerb, so dragging the visually-left handle moved the
right edge. Assert sides by geography (a north-heading road's left handle is west
@@ -147,3 +167,352 @@ empty one produce identical output. Assert that a **non-empty** document changes
the compiled output. Wiring gaps between two handlers need an HTTP-level test, and
a regression test is only trustworthy once you have watched it fail without the
fix.
---
## 11. One segment, two directional roads, two junctions
A segment's forward and backward roads can both reach the same junction while
serving different objects. Anything that resolves "the thing at this approach" by
taking the first match will therefore publish one road's answer on the other's
handle.
Measured: 15 of 23 segments carried two `junction-crosswalk-inset` handles, and
one segment carried two crosswalk groups.
The discriminator is the road whose **last source node** is this junction —
`road.sourceNodeIds.at(-1)` — which is the rule `crossingJunctionInset()` already
applies to find its junction plan:
```js
// WRONG — whichever direction comes first in `items` wins
const crossing = approach.items.map((i) => crossingByRoadId.get(i.road.id)).find(Boolean);
// RIGHT — the road that actually ends here
const crossing = approach.items
.filter((i) => String(i.road.sourceNodeIds?.at(-1)) === String(nodeId))
.map((i) => crossingByRoadId.get(i.road.id))
.find(Boolean);
```
**Mistake made, twice in one session**: once on the client picking a handle for a
selected element, once in the solver computing that handle's bound. Both produced
plausible values on the wrong object, which no type check and no smoke test
catches — only asserting against a segment that genuinely has two.
---
## 12. A handle's range is part of its contract
`value.min` / `value.max` say "drag here and something happens". Each kind
currently derives them independently, and every one measured was wrong in a
different direction:
| kind | declared | measured | failure |
| --- | --- | --- | --- |
| `road-edge-offset` | ±2.925 | rejected past ~±1 | blocking diagnostic mid-drag |
| `junction-crosswalk-inset` | 0–8 | inert past 1.0–4.5 | **silent**, 44–88% dead |
| `junction-stop-line-offset` | 0.5–126.28 | fully linear | no meaningful ceiling at all |
The silent case is the worst: a drag that does nothing is indistinguishable from
a broken control, and it is what `flag.ts` blocks whole features for.
Rules:
- Derive the ceiling from the geometry that consumes the value, not from a
constant. `effectiveCrosswalkInsetMax()` is the worked example: read where the
consuming function saturates and solve for it.
- Never publish a `max` below the current value — a manifest that contradicts
itself. Equal is fine and honest: it says there is no headroom.
- A range wide enough to produce nonsense (a stop line 126m from its junction) is
as much a defect as one that is dead.
## 13. Complex junction shape summary
### 1. Scope / Trigger
Complex-junction compilation publishes a structural classification which the
JunctionTools page displays. This crosses the compiler, the persisted GeoJSON
layer, `/api/state`, and the typed browser state.
### 2. Signatures
```js
GET /api/state?debug=1
// debug.junctionShapes?: Array<{
// clusterId: string, kind: string, label: string,
// armCount: number, throughPairCount: number
// }>
```
### 3. Contracts
- `complex-core` is published in `layers/road_surface.geojson`, not
`intersection_surface.geojson`.
- Its `shape_kind`, `shape_label`, `arm_count`, and `through_pair_count`
properties are the compiler authority. The service must project them without
reclassifying from node count.
- `debug.junctionShapes` is present only for debug state. An absent matching
entry means the client shows its ordinary cluster context, not an invented
shape.
### 4. Validation & Error Matrix
| Condition | Required behavior |
| --- | --- |
| No complex core for a configured cluster | Omit its summary; do not emit a false shape |
| Shape is unsupported | Compiler emits a normal-junction fallback diagnostic and no `complex-core` |
| GeoJSON properties are missing | Use `unsupported` and the readable fallback label only while projecting an existing core |
### 5. Good / Base / Bad Cases
- Good: a five-node cluster with five external arms returns `5 臂非规则路口`.
- Base: debug is off, so no shape summaries are returned.
- Bad: reading `intersection_surface.geojson` returns no complex cores and makes
the UI falsely appear to lack classification.
### 6. Tests Required
- Compiler: assert `complex-core` has the expected shape kind and arm count for
a real OSM cluster.
- Service/UI: assert debug state reads the road-surface core and the workspace
renders the received label without node-count inference.
### 7. Wrong vs Correct
```js
// Wrong: complex cores are not stored in this layer.
readLayer('layers/intersection_surface.geojson')
// Correct: project compiler-owned properties from their published layer.
readLayer('layers/road_surface.geojson')
```
## 14. Junction structure and standards profile
Stage-0 JunctionTools structure is compiler-owned and versioned independently
of the direct-edit document. `buildJunctionStructure(input)` must return
`junction-structure/v1` with unique stable object keys, readable labels, and
explicit arm/corner/facility references; it must reject duplicate keys,
unknown references, and an effective arm count that differs from the supplied
arms. It must not infer missing arms from an internal `2x1`/`2x2` layout.
`CN_URBAN_DEFAULT_PROFILE` is the immutable `cn-urban-default` profile. Use
`cloneProfile()` before applying project-specific changes and
`validateStandardsProfile()` at the boundary. Rules distinguish recommended,
warning, and blocking/invariant fields; a profile is metadata and rule
configuration, not a client-side save decision. Keep the compiler as the sole
producer of structure and diagnostics so the client cannot reclassify a
junction from node counts.
## 15. Save-time geometry validation
`saveEdits()` must run the same `resolveDirectEditConstraints()` used by
`editPreview()` after validating the candidate document and before writing it.
Any diagnostic with `severity: 'error'` returns HTTP 400 and leaves the active
document byte-identical; warnings remain saveable. This prevents a client from
skipping preview and persisting a width, corner radius, crossing offset, or
stop-line value that the compiler rejects. Version conflicts are checked first
and continue to return HTTP 409 without invoking geometry validation writes.
## 16. Scoped complex junction identity
### Scope and signatures
Stage 1 establishes the read model consumed by later cluster editing. Use
`resolveComplexJunctionTopology(model, cluster, helpers)` in complex geometry,
then `structureFromTopology(topology, shape, center, features)`. Projection is
`projectJunctionStructure({ model, layers, trafficSignals, junctionRef })`.
### Contracts
- `junctionRef` is `{ type: 'node' | 'cluster', id }`. Explicit `null` means no
junction projection; unknown references return `null`, never the first core.
- `GET /api/state` returns `junctionStructures`, keyed by `node:<id>` and
`cluster:<id>`. The legacy singular field is null at this unscoped entry point.
- `GET /api/edit-state?junction=<node>` preserves the node selection contract;
`?cluster=<id>` selects a cluster. Preview uses the equivalent `selection`
object. A selected editable cluster publishes its external carriageway,
corner, and stop-line handles. It publishes `cluster-crossing-inset` only for
an arm with a matching OSM crossing node.
- A selected cluster that cannot project an authoritative `junctionStructure`
returns an empty scoped handle list from both edit state and preview. The API
must not advertise controls for an object the workbench cannot identify or
render as an editable structure.
- A cluster carriageway anchor contains `clusterId`, stable
`carriagewayKey`, `sourceNodeIds`, and `sourceRoadIds`. Replay matches all
source identity; a missing or changed source is stale with `anchor-missing`.
The solver stores width and cutback values separately, and `compileGeometry()`
applies them only to the matching complex-junction approach before geometry is
generated.
- A cluster corner anchor contains its stable adjacent-arm `cornerKey` and the
two representative carriageway keys. It is replayed against the same
source-sorted arm grouping used by `resolveComplexJunctionTopology()`. The
complex generator reads a local radius by that `cornerKey`; no other corner is
rewritten.
- A cluster crossing anchor contains `clusterId`, stable
`crossingKey` (`crossing:<armKey>`), and its source-backed carriageway keys.
Crosswalk inset is in `0..8` m; stop-line offset is in `0.5..12` m. Replay
resolves the same arm grouping and marks a missing arm `stale/anchor-missing`.
Generated crosswalk stripes and stop lines publish that `crossing_key`; the
generator applies the inset once per stripe group and positions each incoming
stop line relative to its matching crossing. Never identify these facilities
by `crossing_node_id`, because complex members can share a node.
- A road envelope or inferred stop line is not crossing evidence. Without a
matching source crossing node, compilation emits no complex crosswalk,
publishes no crossing-inset handle, records facility evidence as
`unknown-no-crossing-source`, and emits
`complex-junction-crossing-source-missing`. A stop line may remain as an
independent inferred facility; its position must not consume a nonexistent
crossing inset.
- Source matching uses the same inferred arm radius in handle publication and
constraint solving. A published handle must remain applicable at every
advertised value, including `value.max`.
- Preview and save both evaluate the same candidate through the resolver and
`compileGeometry()`. Save rejects every `severity: error` diagnostic before
writing the edit document.
- Complex road-surface features carry `junction_key`, `object_key` and relevant
`arm_key`, `carriageway_key`, `corner_key`. Core (or the first remaining
approach when the core fails) carries `junction_structure` for persisted reads.
- A supported complex core publishes measurable region evidence:
`connected_entry_count`, `required_pavement_connected`, `core_ring_area`,
`core_ring_self_intersects`, and the existing shared-seam metrics. A contained
exclusion hole is valid only when it preserves every required entry seam.
- Stable keys derive from cluster and sorted source node/segment/road IDs, with
corner keys derived from adjacent arms. Display indices and headings are not
object identities. `topologyFingerprint` detects source topology changes.
- Root provenance lists member nodes and external road/segment IDs. Arms point
to carriageways, corners to arms, facilities to feature IDs; normalizers must
preserve these fields and readonly capabilities across JSON round trips.
- Signal projection joins exact member `node_id` / `control_id`, retaining the
existing `signal_uid` as `geometryRef` and `provenance.featureIds`. It does not
rewrite the separately persisted signal document or guess from UID substrings.
### Validation matrix
| Input | Result |
| --- | --- |
| Multiple selection keys or repeated query keys | 400, no implicit priority |
| Empty/object-valued ID | 400 |
| Unknown node/cluster or missing compiled complex structure | null structure, empty diagnostics |
| Missing/ambiguous object source | readonly capability with reason |
| Explicit cluster selection | empty handles; never all-area or member-node handles |
### Cases and tests
Good: reorder member/road arrays and retain semantic IDs; delete a source and
change its identity/fingerprint. Base: legacy node editing still works. Bad:
opening cluster B while rendering cluster A's first core. Test the 3/4/offset/5+
arm matrix, two-cluster isolation, internal-link exclusion, grouped crossings,
scoped signals, JSON round trips, and persisted/preview projection equality.
```js
// Wrong: chooses an arbitrary junction and loses the selected scope.
projectJunctionStructure({ model, layers });
// Correct for a scoped editor:
projectJunctionStructure({ model, layers, trafficSignals,
junctionRef: { type: 'cluster', id: selectedClusterId } });
```
## Complex carriageway transition length
`cluster-carriageway-transition-length` uses the source-checked
`cluster-carriageway` anchor and `value.transitionLengthMeters`. Replay verifies
source road/node membership before solving. The resolved `clusterTransitions`
map is separate from `clusterCutbacks`: the outer source seam is fixed, and the
inner station is `outerStation - transitionLengthMeters` along the source
polyline. Radial distance differences are not lengths on curved approaches.
The maximum is the available outer station; the minimum is the smaller of the
configured minimum and the existing source-derived transition (short existing
approaches remain representable). Impossible surface geometry still requires
compiler validation. A saved transition is never silently clamped.
Regression evidence: solver rejects out-of-range/source-mismatched values;
API preview measures the requested length and preserves the outer seam;
save/read/replay reproduces preview geometry; browser input sends the new kind.
## Complex carriageway direction and edge bounds
`cluster-carriageway-direction` remains persisted as
`value.offsetDegrees`, including for numeric input and existing documents. Its
manifest handle declares `interaction.kind = rotation`, an EPSG:4326 `center`
at the effective inner entry section, and `radiusMeters`. Pointer projection is
the signed shortest azimuth change around that center; pointer metres must never
be interpreted as degrees. The direction ghost follows the declared circle and
uses degree units.
Position and width handles use the same effective inner entry section as the
BoundaryGraph. Direction edits rotate the width axis and both edge handles at
that section.
The manifest and solver share the carriageway edge range. For one side, with
effective width `W`, opposite offset `O`, and minimum lane total `M`, the range
is `max(-W/2, M-W-O)..W/2`. Both endpoints are accepted; a value outside the
range is rejected with a blocking geometry diagnostic. Independent side
constraints and legacy constraints containing both offsets must be evaluated
with both effective offsets present.
Boundary closure reports `sharedSeamErrors` per carriageway and
`maxSharedSeamErrorMeters` against the authoritative BoundaryGraph inner
section. For a simple closure the section is an exact ring edge. For overlapping
multi-carriageway entries, the center is the union of center-to-entry cells;
a complete inner seam may then lie inside that union. Such a seam is accepted
only after splitting it at every polygon boundary intersection and checking
all resulting intervals (0.1 mm numerical boundary tolerance), then measuring
its endpoint mismatch against its authoritative graph edge. Missing or
uncovered seams remain `Infinity`; valid overlap must not discard carriageways
or falsify the connected-entry count. Explicit transition stations are clamped to the source polyline
range for legacy/direct compiler inputs and marked
`insufficient-source-length` when the requested length cannot fit. The solver
rejects such values before they can be saved.
## Shared complex approach consumers
`compileGeometry()` builds each complex approach BoundaryGraph once. External
road surfaces, edges, sidewalks, center markings and published lane centerlines
read its source-polyline `outer.stationMeters`; do not independently reconstruct
`outerRadius - cutback` in a consumer. The complex surface generator receives the
same graph instance. Transition lane endpoints interpolate the respective outer
and inner section edges, preserving the fixed source width when the inner width
changes. Unsupported, invalid or excluded transitions do not publish preview
lanes or their derived markings. This contract does not yet replace the separate
corner sidewalk overrun geometry or validate all short-road suppression paths.
## Complex cluster vehicle paths
Cluster connectors trace enabled lane movements through internal roads to
external lane ports. Use breadth-first traversal per incoming lane; avoid
cycling through internal lanes. Preserve source movement IDs and existing lane
restrictions. A published whole-cluster path references visible approach lanes
and their travel-oriented endpoints (outbound preview polylines are stored in
reverse travel order). Do not retain per-node connector fragments as if they
were whole-cluster trajectories.
Curves preserve endpoint tangents and use adaptive sampling (2 cm chord error,
2 m maximum segment length, 1 degree tangent/chord error). These are geometric
sampling tolerances, not proof of curvature continuity or vehicle turning
radius. Published cluster paths must be non-self-intersecting, fully inside the
published pavement region and avoid island edges/interiors. Failed candidate
paths remain diagnostic/deferred movements, never fake safe curves. Current
implementation explores a bounded set of cubic control lengths; it is not a
complete motion planner and does not prove vehicle swept-envelope clearance.
## Preview computation and bundled assets
When `resolveDirectEditConstraints()` receives `selection.type === 'cluster'`,
it may omit road, node-junction, and lane-maneuver handles that the selector
would discard. It must still solve the complete document before filtering the
manifest: saved constraints outside the selected handle family can affect the
compiled geometry. The scoped result must equal the unscoped resolution with
only the published handle array filtered.
The bundled `assets/lane-icons/manifest.json` may be cached in-process using its
file modification time and size as the invalidation key. Custom manifest paths
remain uncached because they are valid live test/config inputs. Caching must not
change compiled features or manifest validation errors.
Regression requirements: compare scoped and unscoped resolution plus compiled
layers for an empty document and a document containing mixed constraint kinds;
load the bundled manifest twice and verify the cached result; run the existing
preview/API and geometry suites after changes.
+3
View File
@@ -4,3 +4,6 @@
- [Road Revision Storage](./road-revision-storage.md) -- immutable workbench revision layout, validation, and recovery contract.
- [Direct Edit Solver And API](./direct-edit-api.md) -- pure constraint solving, preview/save endpoints, version protection, and rebase behavior.
- [Junction Island Contact](./junction-island-contact.md) -- confirmed target contract for full crossing-edge contact, dynamic island legs and the six-point green region (implementation pending).
- [Junction Layer Seams](./junction-layer-seams.md) -- metric seam audit, source identity mapping, and both-end corridor trims.
@@ -0,0 +1,78 @@
# Junction island contact
## Status and scope
Confirmed user requirement, 2026-09-11; implementation pending. Applies to the
complex-junction composition with two adjacent arm crossings and one crossing
beside the inward-curved hypotenuse. This is not a universal traffic-island
definition. Simple junction behavior is unchanged.
## Geometry contract
- A contact is the complete short edge of a crossing rectangle, not an arbitrary
white stripe, a point, or only the portion that happens to intersect the island.
- Each of the three crossings contributes one contact segment and two endpoints.
All three complete segments must be shared with the island outer boundary.
- Contact positions are geometry-dependent. The two perpendicular leg lengths
are solved from the contacts and available space; twice crossing depth is not
a hard constraint.
- Preserve six distinct contact endpoints in boundary order. Connecting them
forms the green hexagon on the island. Its three contact edges coincide with
the crossing contacts; its other three edges connect adjacent contacts.
The green region and rounded island outer boundary are distinct geometries.
- Rounded corners and inward curves occupy non-contact boundary portions.
A straight contact edge must remain straight over its full length, including
the hypotenuse-side landing. Rounding must not trim away contact endpoints.
- Solve in local metric coordinates and reuse coordinates across consumers.
Preserve consistent stripe dimensions and spacing, avoid positive-area
crossing/island intersection, and maintain stop-line separation.
- If the available space cannot satisfy the composition, report the object and
failed constraint. Do not shorten a crossing, detach it, or report the partial
composition as valid.
## Required validation
For each complete contact segment S and published island boundary B, measure
the length of S covered by B, not polygon intersection area alone. Require
uncovered length and endpoint-to-boundary distance <= 0.01 m; this tolerance
is numerical, not a design gap. Also check interior samples to catch an arc
touching only at the endpoints.
The six green vertices must equal the six contact endpoints within metric
tolerance, with each used once; the ring must be simple, have positive area,
lie inside the outer island, and retain all three full contact edges. An
independently fitted polygon or a hull dropping vertices fails this contract.
Required cases: orthogonal base case; unequal contact offsets and crossing
depths; translated/rotated equivalents; changed available space; roundovers
that would cut into contacts; and an infeasible composition. On the current
real OSM, verify all contacts and all six vertices for every published island,
not just feature counts or a hand-picked corner. Retain image evidence showing
the outer boundary, green hexagon, complete crossing rectangles and stop lines.
Wrong: move a stripe until it touches an arc at one point and declare success
because overlap area is zero. Correct: share the complete crossing short-edge
segment with the island boundary, then derive the green polygon from those
same endpoints and verify non-contact curves separately.
## Generator stage ordering
`src/compile/complex-junction.js` keeps `buildComplexJunctionGeometry` as the
orchestrator. Its private stages own approach selection/stop lines, arm crossing
layout, corner composition, crossing displacement, pavement assembly and
publication. Keep the existing local solvers in their geometry modules.
- `buildArmCrossings` writes the arm's `crosswalkFrame`, `crosswalkRadius` and
evidence before `buildCornerCompositions` consumes them.
- Corner contact solutions collect both endpoint offsets for each shared arm.
Call `applyCrossingDisplacements` once after all corners, before pavement
assembly. It updates stripes, stop lines and the full swept crossing regions;
moving only the visible stripes leaves pavement gaps.
- Preserve the current failure dependency during structural refactors: a failed
corner contact solve also skips that corner's sidewalk. Changing this is a
behavior change requiring a dedicated regression, not a helper extraction.
- Core `approach_headings` uses `arm.representative.heading`, not `arm.heading`:
the representative heading and grouped arm heading can differ.
- Validate refactors against complete generator results, including feature
order, metadata and diagnostics. Run `test/junction-island-offset.js` explicitly
alongside `npm test`; it covers the shared-endpoint displacement path.
@@ -0,0 +1,88 @@
# Junction layer seams
## Scope and source contracts
Complex-junction seams use a **0.01 m** numerical tolerance in local metric
coordinates. This is internal stitching precision, not OSM survey accuracy.
`test/helpers/junction-seams.js` audits published features against source
identities in `junction_structure`; it does not call the geometry builders to
manufacture expected geometry.
- Exterior surfaces match the complete `directional_road_ids` set of a
carriageway. Core and pavement match `cluster_id`; approaches match
`carriageway_key`.
- Native lanes use `road_id` and travel-direction `lane_index`. Preview lanes
use a combined cross-section index running from `outer.right` to `outer.left`.
Map outgoing lanes in reverse order, followed by incoming lanes in forward
order. Do not equate these two index spaces or choose a nearest lane globally.
- Edge lines match the source road and `side`. Separators match the lane pair;
the boundary between opposite directions belongs to the road centre marking.
Centre markings match the complete `directional_road_ids` set and a primary
`road_id` belonging to that set; a partial source match is not sufficient.
- Sidewalk corners match `corner_key` and strips from their two source arms.
Absence is acceptable only for disabled source sidewalks or an explicit
rejection identifying that exact corner. A cluster-wide fallback diagnostic
must not excuse a missing corner elsewhere.
## Both ends of a corridor
`trimRoadAtComplexClusters(road, junctionPlans, clusters, boundaries)` in
`native-road.js` calculates **both** endpoint cutbacks from the original source
polyline and each cluster's `outer.stationMeters`, then calls `trimLineRange`
once. Road surfaces, sidewalks, edges, centre lines and native lanes share it.
Wrong: select `startCluster || endCluster` as the only trim owner, or trim
sequentially using the second station on the shortened line. Correct: resolve
each endpoint independently and preserve intermediate source bends.
The first bug leaves the far approach covered by exterior pavement and its
edge/lane endpoints tens of metres past the seam. Vertex-to-boundary checks can
miss it because the long side edges still touch both seam endpoints.
## Measurements and failures
`auditJunctionSeams(model, geometry, structures)` returns each layer's `checked`,
`failed`, `notApplicable` and identity-bearing `records`.
| Interface | Required measurement |
| --- | --- |
| Exterior surface / approach | Endpoint error and complete boundary segment coverage |
| Approach / core and published pavement | Complete segment containment, respecting holes |
| Native / preview lanes and solid edges | Corresponding endpoint or paint-cap midpoint |
| Dashed edges, centre lines, separators | Support alignment and bounded terminal gap |
| Corner / sidewalk strip | Both full end edges, with source-arm matching |
Missing expected objects fail; never iterate only detected objects and report an
empty set as success. Segment coverage partitions at all boundary crossings, so
interior notches cannot hide between fixed probes. Polygon holes remain holes.
The canonical complex-pavement region fills construction pockets before it
subtracts explicit `model.exclusionRegions`. A core hole alone is not proof of
the published pavement contract: crossing and corner inputs can otherwise fill
it again. After subtraction, an empty or disconnected result, or any missing
complete approach seam, rejects canonical pavement publication and carries the
cluster plus exclusion identities in its diagnostic.
Dashes do not need white paint across every seam. An outward road starts its
dash sequence at the seam, so its first cap must coincide; the other end can
leave a residual dash cycle. Current edge/separator cycles are 2 m paint + 2 m
gap. Centre markings publish `dash_length_m` and `dash_gap_m`. Report these gaps
separately from the 1 cm transverse alignment tolerance. The audit does not
certify every individual dash, every double-line component, or interior paint
continuity through a complex core where centre markings are not published.
## Required regression
Run `node test/junction-layer-seams.js` (also in `npm test`). To inspect every
identity and measurement, run:
```sh
node test/junction-layer-seams.js --report /private/tmp/junction-layer-seams.json
```
Keep nonempty per-layer counts for straight/curved, one-way/two-way, local width
and island edits, two-ended corridors, reordered input, current real OSM and
explicitly sidewalk-enabled real OSM. Required negative controls: exactly 2 cm
displacement, missing single/whole counterparts, wrong source identities,
swapped lane indices, absent first anchored dash, a 2 cm interior notch and a
hole. Do not loosen the tolerance or refresh unrelated fixture snapshots.
@@ -2,4 +2,8 @@
Use typed React function components. `App.tsx` owns session/editor composition, while reusable map and UI concerns live in named components. Prefer the shared `ui/button.tsx` primitive for commands. Do not create business UI with `querySelector` or `innerHTML`.
Forms use controlled inputs and submit handlers. Keep map canvas DOM owned by OpenLayers and surrounding controls owned by React.
Components expose explicit props for values and callbacks. A form component may own presentation-local state such as a select value, but it must not import `api`, mutate `WorkbenchState` directly, or implement save/preview/undo behavior. The composition root passes commands such as `stage`, `updateSignal`, or `onAccept`.
The inspector is composed from independent sections. Section components must preserve existing write semantics: ordinary v1 forms stage overrides, `lane-maneuver` uses the v2 session, and signal forms update the signal draft command. Do not make a generic form abstraction that hides these boundaries.
Forms use controlled inputs and submit handlers. Keep map canvas DOM owned by OpenLayers and surrounding controls owned by React. Extracting a component must preserve labels, default values, event ordering, and the current accordion behavior unless a separate product task approves a change.
+187 -1
View File
@@ -125,6 +125,13 @@ a swapped object would leave the requester arbitrating for a session nobody read
request layer only sends and cancels. The discard rule is worth unit-testing and
must not depend on network timing.
Selection changes are a second freshness boundary. `PreviewRequester.invalidate()`
must cancel the active request and advance its generation; `dispatch()` checks
that captured generation before giving a response to `EditSession`. Abort alone
is insufficient because a transport may resolve after receiving its abort signal.
When changing junction/segment scope, clear scoped preview geometry before the
new manifest arrives, so an A-scope result cannot render while B is selected.
Undo of a **saved** gesture appends an inverse operation; persisted history is
never rewritten. Undo of an unsaved one just moves the cursor.
@@ -140,6 +147,23 @@ match `main` exactly. Guard once at construction, not per call site.
while `compileGeometry()` ignores `profile.interval`. A control whose drag changes
nothing is worse than no control.
### Lane maneuver is v2 direct edit only
`lane-maneuver` is a spatial direct-edit constraint. Its selector and draggable
outline are available only in edit mode and must be routed through `EditSession` and
the preview endpoint. It must never be added to the ordinary v1 staged override
array, which is reserved for road, connector, and marking style overrides.
With edit mode off, selecting a turn-arrow part may still show read-only element
information, but it must not create a manifest request, ghost, preview, handle, or
staged lane-maneuver override.
Crosswalk inset and stop-line offset follow the same element ownership rule. New
manifests use a `junction-crossing` anchor containing `crossingId` plus its road
context; legacy `junction-approach` anchors remain readable for document replay.
The crossing values must be kept separate from junction approach width/cutback
plans so editing one crossing cannot move the road geometry or another crossing.
---
## 10. Saving is not the same as applying
@@ -152,6 +176,84 @@ say so.
---
## 11. Two input channels, three shared exits
A value can come from a drag or from a number field. They differ only in how the
scalar is produced and when the gesture closes; everything downstream is shared:
| Exit | Meaning |
| --- | --- |
| `draftValue(handle, value)` | preview, do not commit |
| `settleValue(handle, value)` | one undoable command, or abandon if it drafts nothing |
| `abandonGesture()` | release the id, clear live overrides, re-preview the settled state |
`EditSession` needs no change to accept a second channel: `gestureIdentity()` is
minted lazily by the first draft and released by `commitGesture()`, so `focus` /
`blur` land on the same boundary `pointerdown` / `pointerup` already used. That is
what makes typing `1.53` one undo step instead of four.
**Forbidden**: a second preview path, debounce, or undo stack per input device.
---
## 12. Continuous input clamps; discrete input refuses
The invariant is shared — a constraint value never leaves `[min, max]` — but the
two devices express it differently.
- A drag **clamps**. A pointer cannot state an intent it never reached, and the
handle has to stay on a road shape that can exist (§3). The clamp is visible in
the moment: the handle stops while the cursor keeps going.
- A number field **refuses**: mark it invalid, send no preview, add no undo step,
keep the last valid preview. Typed text *is* an intent, so rewriting it is a
retroactive edit — and the failure modes are asymmetric. A clamped typo (24
becoming 5.4) reads as a plausible value and can go unnoticed; a refusal cannot.
Offer the extremes as one click, but round them **inward**: a real max of `2.925`
renders as `2.93` under nearest-rounding, which the range it came from rejects.
`formatBoundInward()` exists for this.
**Mistake made**: the first draft of the panel displayed and filled
`formatParameterValue(min)`, which produced a value its own range check refused.
---
## 13. A field being typed in owns its own text
Every settled preview replaces the manifest, so a controlled input bound to
`handle.value.current` is rewritten mid-keystroke: typing `1.` fires a preview for
`1`, and the response resets the field to `1`, dropping the decimal point.
The field therefore holds local text while focused and follows the manifest only
when it is not:
```ts
value={text ?? formatParameterValue(handle.value.current)}
```
There is no second number to reconcile: `numericValue()` in the solver reads the
constraint back out, so `value.current` is the request echoed, never a solved
substitute. Seed the local text from what is on screen at focus, not from the
manifest — after a drag the row can legitimately be ahead of the last settled
preview.
---
## 14. Reset disables the constraint; it does not delete it
`validateEditDocument()` rejects an operation whose `constraintIds` name a
constraint that is not in the document, so removing one would mean recording an
operation about nothing. Setting `enabled: false` is what design.md already
sanctions for undoing saved work, and `constraintFor()` skips disabled
constraints, so the handle comes back without a `constraintId` and the row reports
itself unmodified again.
This is the one edit a drag cannot express: a drag can set a value, never withdraw
one. `handle.constraintId` — present only when a constraint exists — is also how
"untouched" is told apart from "explicitly set to the baseline number".
---
## Checklist before committing edit-client changes
- [ ] No baseline source is written
@@ -161,4 +263,88 @@ say so.
- [ ] Constraints sent with their operations
- [ ] No geometry or OL reads inside a `setState` updater
- [ ] No per-`pointermove` React state updates
- [ ] Flag off ⇒ no sources, no layers, no interactions, no requests
- [ ] Flag off ⇒ no sources, layers, or interactions. A selected complex
JunctionTools workspace may request its scoped manifest solely to discover
server-published edit capability before the edit switch is enabled.
- [ ] Every input channel meets at the shared exits, not a parallel path
- [ ] Displayed bounds round inward, so an offered extreme is accepted
- [ ] A focused field is not rewritten by an arriving preview
## 15. Complex shape display is server-owned
`WorkbenchState.debug.junctionShapes` is a debug-only read model keyed by
`clusterId`. JunctionTools may display `label` and `armCount` for the currently
opened cluster, but it must not derive T/十字/偏置 shapes from `nodeIds.length`.
The same internal node layout can resolve to different external-arm topology.
If no summary exists, omit the shape row and retain normal cluster context; do
not show an inferred fallback. The compiler's safe fallback has no complex core
and therefore no summary.
## 16. Scoped structure and semantic map selection
Use `structureForJunction(state, ref)` to read `state.junctionStructures`; do not
reuse the unscoped singular structure when its ref differs. A missing structure
stays unavailable. Use `junctionEditSelection(ref)` for edit-state and preview
requests so a cluster never falls back to the last selected road or node.
## 17. Complex geometry editing
Complex JunctionTools consumes the same v2 `EditSession`, `PreviewRequester`,
`ParameterPanel`, and map handle callbacks as ordinary junctions. Editable
handles include `cluster-carriageway-width`, `cluster-carriageway-cutback`,
`cluster-corner-radius`, `cluster-crossing-inset`, and
`cluster-stop-line-offset`. The first two use a `cluster-carriageway` anchor; a
corner anchor is resolved to its representative carriageway only to create the
snapshot; crossing controls use `cluster-crossing` and its stable
`crossingKey`. Before edit mode, a selected cluster loads its scoped manifest so
`canEditJunction()` can use an editable server handle as the capability signal.
Do not add a cluster-local draft, preview, undo, or save flow.
Compiler structure provenance supplies cluster hotspots and external road IDs.
`localJunctionState` and `localJunctionPreview` recognize explicit `junction_key`
(and legacy `cluster_id`) before testing node/road references. This keeps core
and corner features that do not carry member node IDs and excludes neighboring
clusters even if a connecting road is shared.
Map/list selection goes through `junctionObjectKeyForFeature` and
`junctionObjectFeatures`: compiler keys identify arms/corners/crossing groups;
signal UIDs resolve through scoped facility provenance. Display labels and row
indices are never parsed into IDs. Highlighting is a read-only overlay, allocated
when selecting an object; it must not mutate baseline features or rebuild the
map. On scope changes clear object selection and ignore obsolete manifest loads.
Map capability reason codes into user-facing Chinese descriptions.
Required checks: opposite node/cluster scopes with equal raw IDs, unknown scope,
list-to-feature grouping and feature-to-list identity, foreign-cluster exclusion,
raw signal UID selection, map identity preservation, and reload stability.
### Junction workspace save and grouped ranges
Workspace actions must include `EditSession.dirty`, `canUndo`, and `canRedo`;
`JunctionSession.dirty` alone misses settled grouped edits. Reuse the global
commands and expose save status in the junction route, where the main header is
hidden. The edit render revision is not a persisted document version: a save
changes it, so comparing a captured render revision after saving can crash React.
The API owns version conflict checks.
Cluster browse mode may prefetch its scoped manifest before an `EditSession`
exists. Record a document key as loaded only after the session has actually
loaded its constraints, operations, and `documentVersion`. When the cached key
matches but the session version does not, reload the authoritative document;
otherwise the first save can incorrectly send version 0 after a topology update.
A grouped scalar is available only if the individual ranges intersect. Otherwise
show why a common value is unavailable and expand individual controls; never
render a minimum larger than the maximum. Transition length uses the same input,
preview, history, and persistence path as other geometry parameters.
### Rotational direction handles
`cluster-carriageway-direction` keeps `value.current` and persisted
`offsetDegrees` in degrees. Its manifest declares
`interaction: { kind: 'rotation', center, radiusMeters }`. Project pointer input
as the shortest signed azimuth change around `center`, clamp it to the manifest
range, and place the ghost on the declared circle. Never convert linear pointer
metres directly into degrees. The ghost label uses `°`; numeric input continues
through the shared scalar edit session and save path.
+10 -2
View File
@@ -1,5 +1,13 @@
# Directory Structure
The Vite workbench lives in `workbench/client/`. Application code is under `src/`: `components/` for UI, `map/` for OpenLayers adapters, `lib/` for API clients, `types/` for API contracts, and `ui/` for shared primitives. The Node HTTP server remains `workbench/server.js`.
The Vite workbench lives in `workbench/client/`. Application code is under `src/`:
Keep OpenLayers construction and source mutation outside page components; `src/components/MapCanvas.tsx` owns lifecycle and `src/map/layers.ts` owns the layer registry.
- `components/` contains typed React view components and form sections. Components receive domain data and commands through props; they do not own cross-page persistence.
- `hooks/` contains one stateful editing domain per hook (`useOverrideDraft`, `useDirectEditSession`, or `useTrafficSignalDraft`). Hooks may call the API boundary through injected commands, but must not share mutable module state.
- `edit/` contains pure direct-edit models, projections, sessions, preview arbitration and geometry-unit helpers.
- `map/` contains OpenLayers adapters. `MapCanvas.tsx` owns map lifecycle and `map/layers.ts` owns the layer registry and source updates.
- `lib/` is the browser HTTP boundary; `types/` owns API and workbench contracts; `ui/` contains shared primitives.
`App.tsx` is the composition root: it loads server state, owns selection and page-level commands, and connects editing domains to the map and inspector. It must not contain substantial form implementations or a second copy of an editing protocol.
Keep OpenLayers construction and source mutation outside page components. The map is constructed once per mounted canvas; React re-renders and inspector extraction must not rebuild it or reset its view.
@@ -1,3 +1,9 @@
# Hook Guidelines
Use effects for imperative OpenLayers lifecycle only. `MapCanvas.tsx` constructs one map on mount, updates sources when server state changes, and updates visibility separately. Store callback-sensitive values such as selected road and scene mode in refs so stable OpenLayers style callbacks see current values.
Each custom hook owns one domain and exposes a typed command surface. The three existing edit domains are distinct: ordinary v1 staged overrides, v2 direct-edit session/preview, and traffic-signal drafts. A hook must not create a second undo stack or preview path for another domain.
Keep `EditSession`, `PreviewRequester`, signal history, and gesture refs stable across renders. Effects may synchronize external state, but a hook must not recreate a session or requester from ordinary state changes. Callback dependencies that are consumed by a stable OpenLayers listener belong in refs.
Hooks should return data and callbacks; they should not render JSX. API errors are converted to the existing status/reporting command at the composition boundary unless the hook owns a self-contained async view.
+6 -6
View File
@@ -15,12 +15,12 @@ This directory contains guidelines for frontend development. Fill in each file w
| Guide | Description | Status |
|-------|-------------|--------|
| [Direct Edit Client](./direct-edit-client.md) | Handle/ghost/preview layer ownership, drag projection, session and save contracts | Filled |
| [Directory Structure](./directory-structure.md) | Module organization and file layout | To fill |
| [Component Guidelines](./component-guidelines.md) | Component patterns, props, composition | To fill |
| [Hook Guidelines](./hook-guidelines.md) | Custom hooks, data fetching patterns | To fill |
| [State Management](./state-management.md) | Local state, global state, server state | To fill |
| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | To fill |
| [Type Safety](./type-safety.md) | Type patterns, validation | To fill |
| [Directory Structure](./directory-structure.md) | Module organization and file layout | Filled |
| [Component Guidelines](./component-guidelines.md) | Component patterns, props, composition | Filled |
| [Hook Guidelines](./hook-guidelines.md) | Custom hooks, data fetching patterns | Filled |
| [State Management](./state-management.md) | Local state, global state, server state | Filled |
| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | Filled |
| [Type Safety](./type-safety.md) | Type patterns, validation | Filled |
---
@@ -14,6 +14,8 @@ The workbench frontend uses Prettier as the source formatting authority. Code is
- Do not commit dense, manually minified, or single-line JSX/TypeScript.
- Do not hand-format around Prettier output.
- Do not leave a page component responsible for unrelated form implementations, API calls, and multiple edit histories after a named component or hook boundary exists.
- Do not duplicate an edit protocol while extracting it. Move ownership and update call sites in one change so there is only one active path.
---
@@ -22,6 +24,8 @@ The workbench frontend uses Prettier as the source formatting authority. Code is
- Run `npm run format` after editing frontend files.
- Run `npm run format:check` in the validation gate.
- Keep React components, hooks, types, and API clients in separately formatted modules once a component becomes non-trivial.
- Keep `App.tsx` as a composition root. New domain behavior belongs in a hook or named component with typed props.
- Refactors must preserve API call order, DOM-visible labels/defaults, and OpenLayers map identity unless the task explicitly changes them.
---
@@ -35,3 +39,4 @@ The workbench frontend uses Prettier as the source formatting authority. Code is
- Formatting check passes.
- UI behavior changes do not rebuild the OpenLayers map unless the map lifecycle explicitly requires it.
- Verify ordinary v1 staged, v2 direct-edit, and traffic-signal draft flows independently; passing one flow does not prove the others survived extraction.
+10 -1
View File
@@ -1,3 +1,12 @@
# State Management
Use component `useState` for server state, selection, staged overrides, layer visibility and UI filters. `src/lib/api.ts` is the sole browser HTTP boundary. Keep staged overrides separate from persisted `WorkbenchState.overrides`; save them before compile.
Use component `useState` for server state, selection, layer visibility and UI filters. Domain hooks own their draft state: ordinary v1 staged overrides remain separate from persisted `WorkbenchState.overrides`; v2 constraints remain inside `EditSession`; signal drafts remain separate until the signal save step.
`src/lib/api.ts` is the sole browser HTTP boundary. Presentational components never call it directly. `App` coordinates the fixed save order: ordinary v1 overrides, v2 document, signal draft, then compile and replace server state.
Whenever App accepts a fresh server `WorkbenchState` (initial load, import, compile,
signal generation, or an accepted junction candidate), it must also refresh the
signal draft's saved baseline. Otherwise discard can restore an older signal geometry
after a later rotation or move.
Do not duplicate the whole `WorkbenchState` in multiple hooks. Hooks may use `setState` to update their owned slice and refs for non-serializable history, but there must be one current server state and one owner for each undo/redo stack. `lane-maneuver` belongs exclusively to v2 direct edit; it must not re-enter the v1 staged array.
+2
View File
@@ -1,3 +1,5 @@
# Type Safety
Define browser contracts in `src/types/state.ts` from actual workbench API payloads. Use `unknown` for extensible GeoJSON properties and comparison payloads, then narrow locally. Run `npm run test:client` after TypeScript changes; avoid `any` and broad assertions.
Component and hook boundaries must define named prop/return types for commands and domain data. Do not pass an untyped bag of callbacks or expose mutable refs as public props. Keep API payload narrowing in `lib/` or the owning domain adapter, not in each presentational component.
@@ -1,21 +0,0 @@
# 设计
技术合约不在本文重复定义。权威定义见父任务 `.trellis/tasks/08-26-direct-manipulation-road-editor/design.md` 的以下小节:
- 「约束模型」— `junction-approach-width`、`junction-cutback`、`junction-corner-radius` 三个 kind 与其锚点。
- 「编辑所有权」— junction reserve 独占、`junction-approach-width` 优先于道路 profile、单 `JunctionRef` 会话。
- 「Handle manifest」— 手柄字段与 `reserves`。
- 「预览时序与延迟预算」— 防抖、`previewSeq` 仲裁、`degraded`。
- 「上线与回滚形态」— `directEdit` 开关。
会话状态、四态语义与所有权边界的完整推导见父任务 `research/junction-tools.md`。
## 本子任务的局部决定
- 工作区是独立路由,不是主地图上的浮层面板:路口编辑是高密度局部操作,叠在主地图上会与道路手柄争夺命中区。
- 复用 `direct-edit-map-editor` 的 `EditSession`、ghost/preview source 与命令栈,不新建第二套编辑基础设施。差异只在加载的上下文范围与可用 kind。
- 草稿属于活动工作副本的 session,不是独立导出文件。因此「取消」只需丢弃 session,不涉及文件回滚。
- 「应用到工作区」不写盘:合并后的约束是活动副本的未保存状态,交给主地图的普通 undo/redo 管理。这样保存路径只有一条。
- 会话互斥用显式守卫实现:存在未处理草稿时切换 `JunctionRef` 直接拒绝并提示,不做自动应用或自动丢弃——两者都会让用户丢失意图。
- 本期只实现 `JunctionRef.type === 'node'`。`cluster` 分支保留类型但入口置灰,避免把 cluster 降级成多个互相冲突的普通路口编辑。
- 单个角部圆角:本期只允许编辑一个 corner,多角部批量编辑属后续任务。
@@ -1,41 +0,0 @@
# 实施计划
对应父任务 `implement.md` 的第 7 步。每步一个提交,门禁不过就停。
前置:`direct-edit-solver-api`(junction 三个 kind 的求解与预览端点)与 `direct-edit-map-editor`(`EditSession`、ghost/preview source、命令栈)均已交付。
## 1. 工作区路由与上下文加载
- 目标:能进能回,且不丢全局方位。
- 范围:单 `JunctionRef` 路由(本期只走 `node`,`cluster` 入口置灰);从路口面或诊断进入;加载该路口的编辑上下文(路口面、进口、相邻道路短上下文、车道/connector、步行带、停止线、斑马线、诊断、当前约束);返回主地图并恢复位置。
- 验证:`npm run test:client`、`npm run build`;手测——从路口面进入、从诊断进入、返回后主地图位置与选中态保持。
- 门禁:`cluster` 入口置灰且有原因提示,不落到 node 分支。
- 回滚点:纯新增路由,`directEdit` 开关关闭即隐藏入口。
## 2. 会话状态机与互斥守卫
- 目标:四态语义先于几何落地,避免后续用几何调试状态。
- 范围:`draft` / `applied` / `saved` / `cancelled` 的纯逻辑;未处理草稿时切换 `JunctionRef` 的拒绝守卫;取消复原。复用 `EditSession`,不新建第二套命令栈。
- 验证:`npm run test:client:unit` —— draft → 应用后成为主工作区未保存约束;取消后活动副本无残留;存在未处理草稿时切换被拒绝且草稿不丢;应用后的编辑可被主地图 undo/redo 撤销。
- 门禁:切换拒绝路径有测试;不存在自动应用或自动丢弃草稿的分支。
- 回滚点:纯逻辑模块,revert 后回到第 1 步的只读工作区。
## 3. 三项可拖能力与完整预览
- 目标:进口宽度、cutback、单角部圆角真正可编辑,预览覆盖全部受影响对象。
- 范围:三类手柄的渲染与拖拽;首次拖拽即 ghost;防抖后服务端局部权威预览;预览覆盖道路面、路口面、步行带、车道中心线、connector/movement、停止线、斑马线、标线;拟合失败返回最后有效几何加结构化诊断。
- 验证:`npm run test:client:unit`(手柄事件到三个 kind 的约束值投影)、`npm run test`(局部求解与全量编译对同一约束集结果一致)、`npm run test:client`、`npm run build`;手测——三项各自可拖;预览包含上述全部对象;制造拟合失败时不把非法图形显示成已应用。
- 门禁:预览对象清单逐项核对通过;失败态显示最后有效几何而非空白或非法图形。
- 回滚点:按 kind 分批提交,可单独回退某一类手柄。
## 4. 闭环验证
- 目标:与主工作区和持久化链路接通。
- 范围:应用回主地图、保存、重新编译的完整往返;`expectedDocumentVersion` 复用主地图已实现的冲突处理。
- 验证:`npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build`;手测——应用后返回主地图显示同一几何;保存后重新编译几何不变且约束状态 `exact`。
- 门禁:`prd.md` 全部验收标准勾选。
- 回滚点:revert 后回到第 3 步的预览-only 状态。
## 步骤依赖
1 → 2 → 3 → 4 硬顺序。第 2 步先于第 3 步是刻意的:会话四态若在几何可拖之后才做,取消与互斥的缺陷会被误当成求解问题。
@@ -1,41 +0,0 @@
# 最小 JunctionTools
父任务:`.trellis/tasks/08-26-direct-manipulation-road-editor`。需求来源与权威合约在父任务的 `prd.md` / `design.md`。
## 目标
用专用工作区承载路口编辑,验证单一普通路口的进口宽度、cutback 与单个角部圆角,闭合"预览 → 应用到工作区 → 保存 → 取消"四态。这是路口能力的最小可信切片,不是完整路口编辑器。
## 顺序依赖
前置:`direct-edit-solver-api`(junction 相关的三个 kind 求解与预览端点)与 `direct-edit-map-editor`(`EditSession`、ghost/preview 图层、命令栈)。
后继:无。cluster 高级编辑、多路口联动为独立后续任务。
## 范围
- 单 `JunctionRef`(`{type:'node'|'cluster', id}`,本期只走 `node`)的工作区路由与返回主地图的上下文保持。
- 加载该路口的编辑上下文:路口面、进口、相邻道路短上下文、车道/connector、步行带、停止线、斑马线、诊断与当前约束。
- 三项可拖能力:进口宽度、cutback、单个角部圆角。
- session draft:首次拖拽即 ghost,防抖后服务端权威局部预览。
- 「应用到工作区」合并有效草稿为活动副本的未保存约束;「保存」持久化;「取消」丢弃草稿并复原。
- 会话边界:切换相邻路口前必须应用或取消。
## 不做
- cluster 的高级编辑与复合路口模板编排。
- 多个路口的联合会话或联动编辑。
- 控制设施的逐个手工布置。
- 主地图道路区间的编辑(属 `direct-edit-map-editor`)。
- OSM 图拓扑的修改。
## 验收标准
- [ ] 从路口面或诊断可进入工作区,并能带位置返回主地图。
- [ ] 三项能力各自可拖,首次拖拽即有 ghost,防抖后显示服务端权威几何。
- [ ] 预览包含全部受影响派生对象:道路面、路口面、步行带、车道中心线、connector/movement、停止线、斑马线、标线。
- [ ] 拟合失败时返回最后有效几何加结构化诊断,不把非法图形显示成已应用。
- [ ] 「应用到工作区」后返回主地图仍显示同一几何,且该编辑处于未保存状态、可被主地图 undo/redo 管理。
- [ ] 「取消」后回到进入工作区前的状态,活动副本无残留。
- [ ] 未处理草稿时切换相邻路口被拒绝,并提示先应用或取消。
- [ ] 「保存」后重新编译几何不变,约束状态 `exact`。
- [ ] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build` 全绿。
@@ -1,59 +0,0 @@
# 斑马线元素级编辑器设计
## 架构边界
本实验扩展现有直接编辑链路,而非建立画布对象存储:
```text
crosswalk feature 点击
-> elementId
-> element manifest (anchor + parameters + legal controls)
-> native-road-edits/v2 constraint
-> resolveDirectEditConstraints
-> compileControlMarkings
-> preview / save / recompile
```
`elementId` 是选择和分组标识;持久化仍使用稳定语义 anchor 上的 constraint。它不能是 GeoJSON 数组下标、屏幕坐标或临时 UUID。
## 选择合同
斑马线的每一条 stripe feature 必须包含 `native_id`、`element_id` 与可回链的 crossing / approach 身份。选择适配层只读取 `element_id`,再向服务器取得选中元素的权威 manifest。客户端不会据条带数量、空间距离或渲染顺序自行聚类。
元素 manifest 至少包含:
```ts
interface EditableElement {
elementId: string
kind: 'crosswalk'
anchor: { type: 'junction-approach'; nodeId: string; segmentId: string }
featureIds: string[]
controls: Array<{
kind: 'position' | 'length' | 'width'
value: { current: number; min: number; max: number; unit: 'meter' }
axisAzimuth?: number
}>
fields: Array<{ key: string; value: number; min: number; max: number; unit: 'meter' | 'count' }>
}
```
第一阶段只发布 `position` 及其现有 `junction-crosswalk-inset` 回写规则。第二阶段再加入尺寸和条带参数,避免在实验开始前规定尚未验证的通用元素协议。
## 编辑与预览
- 选择由 `MapCanvas` 的 feature 事件产生,但选择状态由 App/编辑会话持有,不能写入 baseline source。
- 元素控件写入的是 manifest 指定的 constraint kind/value;表单复用同一写入器。
- 选中框和控件只是 `editHandles` / `editGhost` 层的临时 UI;权威预览仍由服务端返回,baseline source 不被客户端改写。
- 空白点击会清除元素选择;道路选择可继续决定道路级 handle manifest。斑马线元素选中与道路选择可并存,但两组控件不得重叠或竞争同一 pointer 手势。
## 数据演进
第一阶段不新增 persisted schema:位置继续使用已有 `junction-crosswalk-inset`。第二阶段如果确实需要尺寸参数,新增一个专属 kind 或扩展同一 kind 的严格 schema 校验;具体选择以第一阶段运行结果为准,不预先固化。
缺省参数必须字节级保持现有斑马线输出。参数越界、条带间互相重叠或越过可用进口范围均返回 blocking diagnostic,不在客户端静默钳制真实约束。
## 兼容与回滚
- 无新 constraint 时,编译输出与当前版本一致。
- `directEdit` 关闭时不请求 element manifest、不安装元素选择交互、不产生额外图层。
- 第一阶段每个步骤独立提交;回滚元素 UI 或 manifest 不影响既有道路级控制。
@@ -1,49 +0,0 @@
# 实施计划
## 0. 建立事实与测试夹具
- 追踪 `compileControlMarkings()` 的每条 stripe 属性、`native_id` 构成和从地图点击到 `onFeature` 的路径。
- 添加失败优先的测试:同组 stripe 需要稳定共享 `elementId`,不同 crossing 不得共享;空编辑输出与基线一致。
- 门禁:能证明一个具体 feature 无歧义回链到一个 junction approach 和 crossing。
## 1. 第一阶段:元素 manifest 与选择
- 在编译器为 crosswalk stripe 写稳定的元素标识和回链属性。
- 在 direct-edit 服务响应中增量发布按 selection/element 获取的元素 manifest,不扩大现有道路 handle 的职责。
- 客户端建立 `ElementSelection` 纯状态与 feature 点击适配;点击 stripe 选择整组、空白清除。
- 验证:编译器单元测试、API 测试、客户端 selection 单元测试。
## 2. 第一阶段:位置编辑闭环
- 用 element manifest 的 position control 渲染元素级控件和选中外框;安装时不得影响道路 handle hit-test。
- 从位置手势和表单走同一个 draft builder,写入 `junction-crosswalk-inset`。
- 验证:拖拽与表单值生成同形约束;预览/保存/重载一致;`exact` 状态和撤销/重做覆盖。
- 门禁:一次非空编辑可在正式重编译结果中观察到斑马线位置变化。失败即停止,不能只交付 UI。
## 3. 复盘门禁
- 手测选中、取消、道路级手柄共存、拖拽钳位、表单验证、保存重载。
- 只有在第一阶段验收全部通过后,才能为尺寸/外观参数做持久化 schema 决策。
## 4. 第二阶段:尺寸与外观
- 依据第一阶段证据设计并验证长度、宽度、条带数、间距的约束 schema。
- 编译器读取参数、返回 blocking diagnostics;元素 manifest 表达对应控件/字段。
- 实现与表单字段完全一致的尺寸控件,补齐组合参数、持久化和 rebase 测试。
## 验证命令
```sh
npm run format:check
npm run test
npm run test:client
npm run test:client:unit
npm run build
```
## 风险文件
- `src/compile/native-road.js`:斑马线生成与默认输出兼容性。
- `src/compile/direct-edit-solver.js` / `native-road-edits.js`:约束求解、schema 和 manifest 必须同步。
- `workbench/server.js`:element manifest 查询与 preview 不得写入磁盘。
- `workbench/client/src/components/MapCanvas.tsx`、`App.tsx`、`edit/`:选择、临时控件和表单不得污染 baseline layer。
@@ -0,0 +1,2 @@
{"file":".trellis/tasks/09-23-complex-junction-interior-line/prd.md","reason":"Acceptance criteria cover the white-line screenshot regression and ordinary-marking compatibility."}
{"file":".trellis/tasks/09-23-complex-junction-interior-line/design.md","reason":"Provides the data-flow and compatibility checks for review."}
@@ -0,0 +1,41 @@
# Design
## Boundary
The compiler must publish complex-junction white road markings only on the
approach side of the first generated crosswalk or stop line. The central
junction pavement and zebra crossing remain free of those markings.
## Data Flow
1. Complex junction templates produce approach lane preview lines and control
polygons (`crosswalks` and `stopLines`).
2. `compileComplexLaneSeparators` derives white lane-separator geometry from
preview lanes. This is the layer shown by the screenshot.
3. `compileCenterLines` derives center-line marking geometry from the trimmed
bidirectional approach line.
4. Both paths use `trimLineBeforeFirstControl`; complex lines must first be
oriented from the exterior toward the cluster center, then restored to their
published direction.
## Implementation Shape
Reuse the existing center-aware `trimLaneOutsideControls` behavior (or extract
its orientation step into a small shared helper) for complex preview and center
lines. For complex lane separators, also trim against the stable published
approach/core boundary so a control polygon that ends short of the core cannot
leave an interior tail. Ordinary roads keep the existing behavior. All cutoffs
remain driven by published geometry, with no cluster-specific coordinates.
## Compatibility
- Preserve feature identities, styles, source road IDs, and signal layers.
- Do not change connector or lane-solving coordinates; only published marking
geometry is clipped.
- Ordinary-junction trimming remains unchanged.
## Risks
If the first control polygon is malformed or absent, the existing full-line
fallback remains in place. Tests must cover both line orientations so a future
OSM way direction cannot reintroduce the bug.
@@ -0,0 +1,2 @@
{"file":".trellis/tasks/09-23-complex-junction-interior-line/design.md","reason":"Defines the center-aware clipping contract for complex white markings."}
{"file":".trellis/tasks/09-23-complex-junction-interior-line/implement.md","reason":"Lists the ordered implementation and validation work."}
@@ -0,0 +1,27 @@
# Implementation Plan
1. Add a focused geometry regression for the `8005332807` complex cluster that
identifies white marking features and asserts their published geometry does
not overlap generated crosswalk/stop-line controls or the interior side of
the approach boundary.
2. Update complex center-line and preview lane-separator trimming to orient by
cluster center before applying the first-control cutoff.
3. Add an opposite-direction synthetic/control assertion proving ordinary
junction markings retain their current behavior.
4. Run focused junction marking tests, then the full test suite and diff checks.
## Validation
- `node test/junction-corridor-markings.js`
- `node test/junction-marking-containment.js`
- `node test/junction-layer-seams.js`
- `npm test`
- `git diff --check`
## Risky Files
- `src/compile/native-road.js`
- `test/junction-corridor-markings.js` or the closest existing geometry test
Do not update fixture baselines unless the final behavior change is reviewed
and explicitly intended.
@@ -0,0 +1,64 @@
# Fix Complex Junction Interior Line for cluster-8005332807
## Goal
Prevent a white lane marking from crossing the zebra crossing and extending into
the interior of a complex junction. The visible result must match the user's
screenshot for `cluster-8005332807` and must not regress ordinary-junction
markings.
## Confirmed Facts
- The reported line is white in the workbench screenshot, so it is a road
marking layer rather than the dark/magenta signal or connector overlays.
- The affected geometry is in the complex-junction cluster containing node
`8005332807`; the screenshot shows the marking continuing inward past a
zebra crossing toward the central pavement region.
- Complex lane separators are generated separately from ordinary road
separators in `src/compile/native-road.js` and are expected to stop at
complex-junction controls and boundaries.
- `trimLineBeforeFirstControl` assumes its input starts at the exterior and
proceeds toward the junction. Complex preview/center lines can be supplied
in the opposite direction, so the current code can preserve the interior
segment instead of the approach segment.
- The screenshot's white line is specifically published as
`native-road-complex-lane-separator/v1` by `compileComplexLaneSeparators`,
not as a signal or center-line overlay. That path clips against controls but
does not independently enforce the complex core boundary.
- Existing worktree changes are unrelated user work and must be preserved.
## Requirements
- R1. In a complex-junction view, the affected white lane marking must stop
before it crosses the zebra crossing or enters the configured junction
interior region.
- R2. The fix must be derived from the actual complex-junction geometry,
crossing controls, or their stable published boundary, not from a
cluster-specific coordinate or screenshot-only special case.
- R3. Lane markings outside the affected complex-junction segment, including
ordinary-junction markings, must remain unchanged.
- R4. Add a regression covering `cluster-8005332807` and a control case proving
ordinary-junction marking generation remains unchanged.
## Technical Decision
Orient complex marking lines by distance from the cluster center before
applying the existing first-control trim, then enforce the published complex
approach/core boundary before restoring their original direction. This keeps
the fix geometry-driven and leaves ordinary road trimming untouched.
## Acceptance Criteria
- [ ] The reported white marking no longer crosses the zebra crossing or
enters the complex-junction interior in the workbench image.
- [ ] No affected white marking segment published for the complex cluster lies
inside its configured crossing/interior boundary; geometry remains finite
and stable.
- [ ] Existing signal, marking, and complex-junction behavior remains intact,
including the affected real OSM fixture.
## Scope Boundary
- In scope: complex-junction white lane-marking geometry and its regression.
- Out of scope: traffic-signal phase logic, OSM source editing, free signal
creation/deletion, vehicle simulation, and unrelated road or island geometry.
@@ -0,0 +1,26 @@
{
"id": "complex-junction-interior-line",
"name": "complex-junction-interior-line",
"title": "Fix complex junction interior line for cluster-8005332807",
"description": "",
"status": "in_progress",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-09-23",
"completedAt": null,
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": null,
"relatedFiles": [],
"notes": "",
"meta": {}
}
@@ -0,0 +1,34 @@
# 总体设计
## 边界
`JunctionTools` 是主地图之外的局部编辑器。主地图只负责显示派生热区和进入入口;编辑器负责一个 `JunctionRef` 的上下文、草稿、预览、应用、保存和取消。
## 数据流
`compiled model/junctionPlans` → `junction descriptors` → `hotspot layer` → `JunctionRef` → `junction session` → `semantic constraints` → `/api/edit-preview` → affected layers → apply/save → active document/revision。
热区是派生显示对象,不新增持久化 schema。node 使用 node id,cluster 使用 cluster id 加 arm/corner 锚点。所有长度使用米,位置锚定 station 或 OSM node。
## 编辑器分层
- `junction-detection`:纯逻辑识别 descriptor、状态和热区几何。
- `junction-workspace`:路由、上下文加载、session 四态和主地图返回。
- `junction-solver`:把 node/cluster 约束归一为 effective plan,供普通与复杂几何共同消费。
- `junction-facilities`:设施联动、诊断汇总和发布前检查。
- OpenLayers 仅作为显示/输入 adapter,不能直接写正式编译 source。
## 首期决策约束
- `JunctionRef` 首期只允许 `type: 'node'` 进入可编辑 session;`cluster` 和 `candidate` descriptor 可展示但不可写入。
- 工作区与主地图共享 undo/redo 栈;一次“应用到工作区”是一个历史边界,拖拽过程只产生 draft/preview。
- 工作区离开由显式守卫控制:有未处理草稿时必须应用、放弃或取消离开;不得静默处理草稿。
- 保存请求必须携带打开时的文档/编译版本。版本不一致返回冲突,保留本地草稿,不做强制覆盖或隐式 rebase。
- 阶段 B 的求解写入仅覆盖三种既有 junction constraint;车道、connector 和设施在此阶段只作为派生上下文与诊断输入。
- 设施编辑只允许修改已有设施的语义 override,不新增或删除设施身份。
- 诊断接口必须提供稳定 `code` 和 `severity`,几何非法为 `blocking`,非致命设施问题可为 `warning`。
- JunctionTools 通过独立路由承载 `JunctionRef`,路由变化不得重建 `MapCanvas`,返回时恢复主地图视角和选择快照。
## 兼容与回滚
阶段 A/B 可挂在现有编辑开关下;未进入 JunctionTools 时主地图行为不变。cluster 几何统一前不得开放 cluster 写入。任何阶段失败都可回退到只读热区或现有普通路口编辑,不影响 v1 overrides、v2 文档和导出包。
@@ -0,0 +1,10 @@
# 执行计划
1. 完成 RoadRunner 对标和本项目需求基线,冻结术语、范围、验收。
2. 实现纯逻辑 junction descriptor 与热区显示;普通 node 可进入,candidate/cluster 状态明确。
3. 建立独立 JunctionTools 路由与上下文快照,闭合 draft/apply/save/cancel 和返回主地图。
4. 统一 node/cluster 的 effective junction plan,让宽度、cutback、圆角真正驱动同一套几何预览。
5. 接入车道、connector、斑马线、停止线、信号灯的联动诊断和发布校验。
6. 运行全量服务端、客户端、E2E、导出契约测试,完成用户复核后再提交。
每一步先写纯逻辑测试,再接 UI;不使用绝对像素作为核心契约,不自动提交。
@@ -0,0 +1,110 @@
# JunctionTools 路口编辑工作区
父任务:`.trellis/tasks/08-26-direct-manipulation-road-editor`。需求来源与权威合约在父任务的 `prd.md` / `design.md`。
## 目标
用地图上的可识别路口区域作为入口,进入一个独立的 JunctionTools 路口编辑页面。页面专注展示单个路口及其完整局部上下文,在同一可视化画布和同一编辑会话中同时承载路口几何、已有设施、参数双向联动、预览和诊断。主地图只负责发现、导航和返回,不承载完整路口编辑体验。
## 当前产品设想
- 主地图识别普通路口和已配置的复杂路口 cluster,并以可点击热区表达,而不是依赖点击某一条道路或控制柄。
- 点击热区后进入独立 JunctionTools 编辑器,聚焦路口局部上下文;返回主地图时保留原地图视角、选中对象和未保存编辑。
- 编辑器首版即作为一体化路口工作区:进口宽度、cutback、角部圆角、路口面、车道/connector、斑马线、停止线、信号灯和诊断在同一 session 中协调;内部可以分区,但用户不需要跨页面切换。
- 所有编辑复用现有 direct-edit 文档、preview、revision、undo/redo 和导出契约,不建立第二套持久化几何。
## RoadRunner 对标拆解
RoadRunner 的路口能力不能简化成几个拖拽手柄。对本项目有价值的能力可拆成四层:
1. 路口识别与入口:从相交道路形成可识别的 junction 对象,并在场景中提供明确的选择目标。
2. 局部工作区:聚焦一个路口,显示进口、边界、车道、连接关系、标线和诊断,编辑完成后回到整体场景。
3. 几何与拓扑编辑:调整进口宽度、路口边界、转角圆角、车道连接和车道数,并让派生几何保持连续、合法。
4. 设施与验证:在路口上下文中布置或调整停止线、斑马线、信号灯等设施,并对冲突、自交、车道宽度和连接状态给出反馈。
本项目的映射不是复制 RoadRunner 内部实现:OSM 中心线和拓扑是只读输入,GeoJSON 是派生输出;可持久化的对象必须是 node/cluster 锚定的语义约束。当前代码已经具备 cluster candidate 检测、complex-junction 几何生成、三类 junction 约束和 preview/save/revision 基础,但缺少“热区 → JunctionTools 工作区”的产品层闭环。
## 分阶段方向
- 阶段 A:派生路口热区和识别状态(普通 node、已确认 cluster、候选 cluster),点击后进入/返回工作区。
- 阶段 B:独立单路口页面、局部上下文和现有三项几何参数编辑闭环。
- 阶段 C:在同一页面接入车道/connector、斑马线、停止线、信号灯的联动编辑和冲突诊断;这是实现顺序,不是拆开的产品功能。
- 阶段 D:cluster 多节点、多进口、多角部及更接近 RoadRunner 的拓扑创作能力。
阶段 A 不应把热区写成新的几何事实;它应由编译模型和 junction plan 派生,避免出现 UI 有路口而编译器不认的第二套数据。
## 本轮已决边界
- 首期只有普通 `node` 可编辑;已确认 `cluster` 只读,`candidate cluster` 只展示识别结果与诊断。
- 阶段 B 只开放进口宽度、cutback、单角部圆角;车道/connector 先展示并诊断,不开放拓扑写入。
- 设施首期允许移动或修改已有斑马线、停止线、信号灯,但不允许创建或删除设施。
- “应用到工作区”形成一个 undo 步骤,并进入主地图共用历史栈;连续拖拽不逐帧进入 undo。
- 离开工作区前必须选择应用并返回、放弃并返回或留在工作区,不自动应用或自动放弃。
- 保存时若编译模型或文档版本变化,拒绝保存并保留草稿,要求重新加载后处理,不自动覆盖或自动 rebase。
- candidate 不得在本轮被确认或转化为持久化 cluster。
- 自交、越界、最小车道宽度等几何非法诊断为 `blocking`;可修复的设施缺失或间距问题可为 `warning`。
- JunctionTools 使用独立 URL 路由,例如 `/junction/:type/:id`,支持刷新、浏览器返回和深链接。
## 总体约束
- OSM 节点、道路中心线和基础拓扑只读;编辑保存语义约束,不保存派生 GeoJSON。
- 普通 node 与复杂 cluster 使用不同的 `JunctionRef` 锚点,不把 cluster 降级成多个普通 node。
- 热区、路口边界和可编辑对象必须来自同一份编译状态;候选识别不能静默改变几何。
- 路口编辑必须复用现有 preview、active document、revision、版本冲突保护和 undo/redo。
- 无效几何不得替换最后有效预览;必须返回结构化诊断。
- 路口 session 与主地图 session 互斥,切换对象前必须应用或取消草稿。
- 导出包契约保持 `native-road-package/v1.1` 不变。
## 子任务地图
1. `09-02-junction-requirements-research`:RoadRunner 能力、用户流程、术语和需求验收基线。
2. `09-02-junction-detection-hotspot`:node/cluster/candidate 识别、热区派生模型和点击入口。
3. `09-02-junction-tools-workspace`:独立工作区路由、上下文加载、返回和 session 状态机。
4. `09-02-junction-geometry-editor`:进口宽度、cutback、圆角、车道/connector 的统一求解与预览。
5. `09-02-junction-facilities-validation`:斑马线、停止线、信号灯联动、诊断和最终发布验证。
依赖顺序为 1 → 2 → 3 → 4 → 5;每个子任务独立验收,父任务负责跨任务契约和最终集成。
## 顺序依赖
前置:`direct-edit-solver-api`(junction 相关的三个 kind 求解与预览端点)与 `direct-edit-map-editor`(`EditSession`、ghost/preview 图层、命令栈)。
后继:无。cluster 高级编辑、多路口联动为独立后续任务。
## 范围
- 路口识别结果和热区入口的最小交互。
- 单 `JunctionRef`(`{type:'node'|'cluster', id}`)的工作区路由与返回主地图的上下文保持;首期只有 `node` 进入可编辑 session,`cluster` 与 candidate 只读。
- 加载该路口的编辑上下文:路口面、进口、相邻道路短上下文、车道/connector、步行带、停止线、斑马线、诊断与当前约束。
- 三项可拖能力:进口宽度、cutback、单个角部圆角。
- session draft:首次拖拽即 ghost,防抖后服务端权威局部预览。
- 「应用到工作区」合并有效草稿为活动副本的未保存约束;「保存」持久化;「取消」丢弃草稿并复原。
- 会话边界:切换相邻路口前必须应用或取消。
## 不做
- cluster 的高级编辑与复合路口模板编排。
- 多个路口的联合会话或联动编辑。
- 控制设施的新建、删除和身份创建;首期只允许修改已有设施的语义参数。
- 主地图道路区间的编辑(属 `direct-edit-map-editor`)。
- OSM 图拓扑的修改。
- 一次性实现 RoadRunner 级别的完整路口建模、任意拓扑创作或多路口联合编辑。
## 验收标准
### 独立一体化页面方向(2026-09-03)
- [ ] `/junction/:type/:id` 是独立路口编辑页面,进入后自动聚焦单个路口;主地图只作为入口和返回目标。
- [ ] 页面画布持续展示路口几何与已有斑马线、停止线、信号灯,参数面板不得遮挡主要路口视图。
- [ ] 几何参数和已有设施调整在同一页面、同一 draft/preview/undo/apply/save/cancel 链路中完成。
- [ ] 表单与地图操作双向同步:表单修改反映到画布,地图拖拽回写参数;失败预览保留最后有效几何并显示诊断。
- [ ] 首版支持已有设施的移动或已有字段修改,不创建、删除或跨路口迁移设施;cluster 与 candidate 继续只读。
- [ ] 从路口面或诊断可进入工作区,并能带位置返回主地图。
- [ ] 三项能力各自可拖,首次拖拽即有 ghost,防抖后显示服务端权威几何。
- [ ] 预览包含全部受影响派生对象:道路面、路口面、步行带、车道中心线、connector/movement、停止线、斑马线、标线。
- [ ] 拟合失败时返回最后有效几何加结构化诊断,不把非法图形显示成已应用。
- [ ] 「应用到工作区」后返回主地图仍显示同一几何,且该编辑处于未保存状态、可被主地图 undo/redo 管理。
- [ ] 「取消」后回到进入工作区前的状态,活动副本无残留。
- [ ] 未处理草稿时切换相邻路口被拒绝,并提示先应用或取消。
- [ ] 「保存」后重新编译几何不变,约束状态 `exact`。
- [ ] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build` 全绿。
@@ -3,7 +3,7 @@
"name": "direct-edit-junction-tools",
"title": "最小 JunctionTools",
"description": "单一普通路口的进口宽度、cutback、单角部圆角与预览/应用/取消",
"status": "planning",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
@@ -11,14 +11,20 @@
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-08-26",
"completedAt": null,
"completedAt": "2026-09-04",
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"children": [
"09-02-junction-requirements-research",
"09-02-junction-detection-hotspot",
"09-02-junction-tools-workspace",
"09-02-junction-geometry-editor",
"09-02-junction-facilities-validation"
],
"parent": "08-26-direct-manipulation-road-editor",
"relatedFiles": [],
"notes": "",
@@ -0,0 +1,154 @@
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>JunctionTools UI Prototype</title>
<style>
:root {
color: #dfe9e5;
background: #101a18;
font-family: Inter, ui-sans-serif, system-ui, -apple-system, sans-serif;
}
* { box-sizing: border-box; }
body { margin: 0; min-width: 1080px; }
button, input { font: inherit; }
button { cursor: pointer; }
.app { min-height: 100vh; display: grid; grid-template-rows: 64px 1fr 38px; }
.topbar { display: flex; align-items: center; gap: 22px; padding: 0 22px; background: #173b32; border-bottom: 1px solid #2d594d; }
.brand { letter-spacing: .14em; font-size: 12px; color: #95b5aa; text-transform: uppercase; }
.title { font-size: 18px; font-weight: 700; color: #f5fbf8; }
.crumb { color: #9eb9ae; font-size: 13px; }
.topbar-spacer { flex: 1; }
.top-action { border: 1px solid #6d988a; color: #e9f4ef; background: transparent; padding: 8px 12px; border-radius: 4px; }
.top-action.primary { background: #d3e9df; border-color: #d3e9df; color: #183a31; font-weight: 700; }
.workspace { min-height: 0; display: grid; grid-template-columns: minmax(0, 1fr) 360px; }
.canvas { position: relative; overflow: hidden; background: #d9dfda; }
.canvas-head { position: absolute; z-index: 2; left: 20px; top: 18px; display: flex; gap: 8px; }
.chip { border: 1px solid #b3c0ba; background: #eff4f0e8; color: #29483e; border-radius: 4px; padding: 7px 10px; font-size: 12px; box-shadow: 0 2px 8px #263b3222; }
.chip.active { border-color: #2f755d; background: #e0f1e8; color: #205a45; }
.map-svg { position: absolute; inset: 0; width: 100%; height: 100%; }
.map-label { font-size: 13px; fill: #345448; font-weight: 700; }
.map-note { position: absolute; left: 20px; bottom: 18px; padding: 9px 12px; color: #3c574d; background: #eef3efdf; border: 1px solid #b8c7bf; border-radius: 4px; font-size: 12px; }
.inspector { overflow: auto; padding: 20px 18px; background: #f7faf8; color: #20352d; border-left: 1px solid #cad9d1; }
.section { padding-bottom: 18px; margin-bottom: 18px; border-bottom: 1px solid #dbe6e0; }
.section:last-child { border-bottom: 0; }
.section-title { margin: 0 0 12px; font-size: 14px; color: #173b32; }
.section-subtitle { margin: -5px 0 12px; color: #71847b; font-size: 12px; }
.field { display: grid; grid-template-columns: 1fr 104px; gap: 10px; align-items: center; margin: 11px 0; }
.field label { font-size: 13px; }
.field small { display: block; color: #82938b; font-size: 11px; margin-top: 3px; }
.field input { width: 100%; border: 1px solid #aabdb3; border-radius: 3px; padding: 7px 8px; color: #173b32; background: white; text-align: right; }
.unit { position: relative; }
.unit span { position: absolute; right: 8px; top: 8px; color: #7c9187; font-size: 12px; pointer-events: none; }
.unit input { padding-right: 28px; }
.range { height: 4px; margin: 6px 0 0; border-radius: 10px; background: #c9d9d1; }
.range i { display: block; width: 57%; height: 100%; background: #3d8b6c; border-radius: 10px; }
.facility { display: flex; justify-content: space-between; align-items: center; padding: 9px 0; border-top: 1px solid #e5ede8; font-size: 13px; }
.facility:first-of-type { border-top: 0; }
.facility strong { color: #245b47; }
.status { display: flex; align-items: center; gap: 8px; color: #2e7558; font-size: 12px; }
.dot { width: 8px; height: 8px; border-radius: 50%; background: #3d9a6c; }
.diagnostic { padding: 9px 10px; background: #edf5f0; border-left: 3px solid #3d8b6c; color: #45665a; font-size: 12px; line-height: 1.5; }
.actions { display: flex; gap: 8px; }
.action { flex: 1; padding: 9px 8px; border: 1px solid #9bb2a7; border-radius: 3px; background: white; color: #245241; }
.action.main { background: #286b52; color: white; border-color: #286b52; }
.footer { display: flex; align-items: center; gap: 18px; padding: 0 20px; background: #18322b; color: #b7cdc3; font-size: 12px; }
.footer strong { color: #e1f1ea; }
.legend { margin-left: auto; display: flex; gap: 14px; }
.legend span::before { content: ''; display: inline-block; width: 9px; height: 9px; margin-right: 5px; border-radius: 50%; background: currentColor; }
.legend .geometry { color: #2f7e61; }
.legend .facility-dot { color: #b1783c; }
</style>
</head>
<body>
<div class="app">
<header class="topbar">
<span class="brand">JunctionTools</span>
<span class="title">路口节点 1140799919</span>
<span class="crumb">独立编辑页面 / 普通路口</span>
<span class="topbar-spacer"></span>
<button class="top-action">撤销</button>
<button class="top-action">重做</button>
<button class="top-action">返回主地图</button>
<button class="top-action primary">保存并重新生成</button>
</header>
<main class="workspace">
<section class="canvas" aria-label="路口可视化画布">
<div class="canvas-head">
<span class="chip active">路口几何</span>
<span class="chip">斑马线</span>
<span class="chip">停止线</span>
<span class="chip">信号灯</span>
</div>
<svg class="map-svg" viewBox="0 0 900 700" role="img" aria-label="单个路口及其设施预览">
<rect width="900" height="700" fill="#d9dfda" />
<path d="M0 285 H900 V415 H0 Z" fill="#7e8987" />
<path d="M385 0 H515 V700 H385 Z" fill="#7e8987" />
<path d="M0 280 H900 M0 420 H900 M380 0 V700 M520 0 V700" stroke="#d5dcda" stroke-width="3" />
<path d="M0 350 H900 M450 0 V700" stroke="#f4f5ed" stroke-width="2" stroke-dasharray="14 13" opacity=".7" />
<path d="M320 285 H580 V415 H320 Z" fill="#697673" stroke="#286b52" stroke-width="4" stroke-dasharray="9 7" />
<g fill="#f5f8ef">
<path d="M346 265 h75 v12 h-75z M346 423 h75 v12 h-75z" />
<path d="M479 265 h75 v12 h-75z M479 423 h75 v12 h-75z" />
<path d="M305 305 h12 v90 h-12z M573 305 h12 v90 h-12z" />
</g>
<g stroke="#e8eee9" stroke-width="9" opacity=".95">
<path d="M347 286 V330 M365 286 V330 M383 286 V330 M401 286 V330" />
<path d="M499 370 V414 M517 370 V414 M535 370 V414 M553 370 V414" />
</g>
<g fill="none" stroke="#b1783c" stroke-width="6"><path d="M330 275 H430" /><path d="M470 425 H570" /></g>
<g fill="#d4934b" stroke="#704c2b" stroke-width="2"><circle cx="300" cy="270" r="9" /><circle cx="600" cy="430" r="9" /><circle cx="565" cy="270" r="9" /></g>
<g fill="#2f7e61" stroke="#f2fff8" stroke-width="3"><circle cx="450" cy="285" r="11" /><circle cx="385" cy="350" r="11" /><circle cx="515" cy="350" r="11" /><circle cx="450" cy="415" r="11" /></g>
<g stroke="#2f7e61" stroke-width="2" fill="none"><path d="M450 285 L450 210" /><path d="M385 350 L300 350" /><path d="M515 350 L600 350" /><path d="M450 415 L450 490" /></g>
<g class="map-label"><text x="30" y="80">北进口</text><text x="680" y="80">东进口</text><text x="30" y="635">南进口</text><text x="680" y="635">西进口</text></g>
<g fill="#173b32"><text x="655" y="520" class="map-label">预览中 · 路口边界</text></g>
</svg>
<div class="map-note">拖动绿色控制点调整几何;橙色设施可单独移动或编辑</div>
</section>
<aside class="inspector" aria-label="路口配置与诊断">
<section class="section">
<h2 class="section-title">路口几何</h2>
<p class="section-subtitle">修改后立即在画布显示服务端预览</p>
<div class="field"><label>北进口宽度<small>合法范围 3.6–12.0 m</small></label><div class="unit"><input value="7.20" /><span>m</span></div></div>
<div class="range"><i></i></div>
<div class="field"><label>东进口收口距离<small>合法范围 1.0–18.0 m</small></label><div class="unit"><input value="5.40" /><span>m</span></div></div>
<div class="range"><i style="width: 32%"></i></div>
<div class="field"><label>北→东角部圆角<small>合法范围 1.0–12.0 m</small></label><div class="unit"><input value="4.00" /><span>m</span></div></div>
<div class="range"><i style="width: 40%"></i></div>
</section>
<section class="section">
<h2 class="section-title">已有设施</h2>
<p class="section-subtitle">选择画布中的设施可编辑其语义参数</p>
<div class="facility"><span>斑马线 · 北侧</span><strong>6 条带 · 退让 1.5 m</strong></div>
<div class="facility"><span>停止线 · 北侧</span><strong>偏移 2.7 m</strong></div>
<div class="facility"><span>信号灯组 · 3 组</span><strong>可移动 / 可旋转</strong></div>
</section>
<section class="section">
<h2 class="section-title">验证诊断</h2>
<div class="diagnostic">当前几何合法,进口截面连续,路口面无自交。所有预览对象均落在所属道路范围内。</div>
</section>
<section class="section">
<div class="status"><span class="dot"></span><strong>预览已同步</strong><span>preview #18 · 142 ms</span></div>
</section>
<div class="actions">
<button class="action">放弃草稿</button>
<button class="action main">应用到工作区</button>
</div>
</aside>
</main>
<footer class="footer">
<strong>草稿 · 3 项未应用</strong>
<span>路口面、斑马线、停止线将随本次预览同步更新</span>
<div class="legend"><span class="geometry">几何控制</span><span class="facility-dot">设施控制</span></div>
</footer>
</div>
</body>
</html>
@@ -38,6 +38,7 @@ type RoadConstraintKind =
| 'junction-cutback'
| 'junction-corner-radius'
| 'junction-crosswalk-inset'
| 'junction-crosswalk-size'
| 'junction-stop-line-offset'
```
@@ -50,14 +51,21 @@ type RoadConstraintKind =
| `junction-cutback` | `junction-approach` | `{ cutbackMeters }` | 米 | JunctionTools |
| `junction-corner-radius` | `junction-corner` | `{ radiusMeters }` | 米 | JunctionTools |
| `junction-crosswalk-inset` | `junction-approach` | `{ insetMeters }` | 米,斑马线距路口边界的退让 | 主地图 / JunctionTools |
| `junction-crosswalk-size` | `junction-approach` | `{ depthMeters, stripeCount }` | 米 + 整数条带数 | 主地图 |
| `junction-stop-line-offset` | `junction-approach` | `{ offsetMeters }` | 米,停止线沿进口后退的距离 | 主地图 / JunctionTools |
前 6 个 kind 对应 PRD 首期范围(外缘、步行带、车道分隔 + 进口、cutback、角部)。
后 2 个于 2026-08-28 追加,是「更多元素可直接操纵」方向的第一类扩展:控制标线的**位置**
`junction-crosswalk-inset` 与 `junction-stop-line-offset` 于 2026-08-28 追加,是「更多元素可直接操纵」方向的第一类扩展:控制标线的**位置**
成为可编辑参数。它们不改变路口形状,只移动标线,因此不触发路口边界重算。
放置是否成立的判据(`STOP_LINE_MAX_APPROACH_DISTANCE_METERS` 等)不在此范围内。
`junction-crosswalk-size` 于 2026-08-31 追加,是第一个改变标线**自身尺寸**而非位置的 kind。
横跨道路的跨度不是存储值,而是 `stripeCount × pitch` 派生;pitch 固定 0.9m 不可编辑,
因为条带宽与间隙在现实中是标准化的,而它横跨的道路不是。加宽靠增加条带数,
所以跨度是**量化**的。同批修掉了「跨度恒为 4.95m,与路宽无关」的缺陷:
无约束时条带数由整段车行道宽度推导。
新增 kind 的前提:**几何阶段必须已经消费它**。本项目曾为 `profile.interval` 交付过
一个拖动无效果的手柄(见 `08-26-direct-edit-map-editor/research/interval-not-applied.md`),
所以扩展 kind 时先证明 `compileGeometry()` 读取该参数,再画任何手柄。
@@ -213,7 +221,7 @@ workbench-data/import-<id>/
主地图 Road editor 只编辑两个 junction reserve 之间的道路内部 interval。reserve 内的 approach width、transition、cutback 和 corner 由 `JunctionTools` 独占。同一进口上 `junction-approach-width` 显式约束优先于道路 profile,求解器负责边界连续。
`JunctionTools` 是单 `JunctionRef` session(`{type:'node'|'cluster', id}`):拖拽立即 ghost,服务端返回完整局部派生图层;"应用到工作区"把有效草稿合并为活动副本的未保存约束,"保存"才持久化,"取消"回到进入前状态。切换相邻路口前必须应用或取消。首个交付仅支持普通 node junction 的进口宽度、cutback 与一个角部圆角。
`JunctionTools` 是独立的单 `JunctionRef` 页面(`{type:'node'|'cluster', id}`):主地图只负责发现和导航,页面自身负责路口自动居中、完整可视化画布、几何与已有设施编辑。页面不得被参数面板遮挡;路口面、进口、车道/connector、斑马线、停止线和信号灯都必须保持可见,编辑控件覆盖在同一画布上。拖拽立即 ghost,服务端返回完整局部派生图层;"应用到工作区"把有效草稿合并为活动副本的未保存约束,"保存"才持久化,"取消"回到进入前状态。切换相邻路口前必须应用或取消。
## 不变量
@@ -262,4 +270,3 @@ workbench-data/import-<id>/
@@ -91,6 +91,17 @@
## 验收标准(交付阶段)
### 独立 JunctionTools 页面(重新确认,2026-09-03)
JunctionTools 必须是一个独立的路口编辑页面,而不是覆盖在主地图上的参数弹层。主地图只负责发现路口、显示入口和返回导航;进入 `/junction/:type/:id` 后,页面主要视觉对象是当前单个路口,不能被编辑面板遮挡。
- [ ] 页面自动聚焦并适配当前路口,持续显示路口面、进口道路、圆角、cutback、斑马线、停止线和信号灯。
- [ ] 几何编辑与已有设施编辑在同一页面完成,使用同一份 draft、preview、undo/redo、apply、save、cancel 状态。
- [ ] 参数输入和地图拖拽是同一参数的两个输入通道:任一通道变化都会在路口画布上显示权威预览,另一通道同步当前值。
- [ ] 预览失败时保留最后一个有效几何并显示结构化诊断;非法值不得显示成已应用几何。
- [ ] 首版支持已有斑马线、停止线、信号灯的可视化调整和已有字段编辑;设施创建、删除和跨路口迁移不在首版范围。
- [ ] 主地图的道路级编辑能力不因进入独立页面而消失;离开页面前必须明确应用、保存、放弃或继续停留。
每条都必须可执行验证,不接受"看起来对了"。
- [ ] 拖动道路外缘 → 保存 → 重新编译,道路面、步行带、车道线、标线与 connector 一致更新,约束状态为 `exact`。
@@ -3,7 +3,7 @@
"name": "direct-manipulation-road-editor",
"title": "直接操纵道路编辑工作台",
"description": "探索类似 Drawtonomy 的直接操纵道路编辑,保持结构化 overrides、可审计性和可重编译性",
"status": "planning",
"status": "completed",
"dev_type": "feature",
"scope": "road-editor",
"package": null,
@@ -11,7 +11,7 @@
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-08-26",
"completedAt": null,
"completedAt": "2026-09-07",
"branch": null,
"base_branch": "main",
"worktree_path": null,
@@ -26,7 +26,11 @@
"08-27-junction-dominated-roads",
"08-28-edit-interaction-polish",
"08-28-junction-control-offsets",
"08-28-crosswalk-element-editor"
"08-28-crosswalk-element-editor",
"08-31-parameter-panel-binding",
"08-31-constraint-range-validation",
"08-31-lane-maneuver-override",
"09-02-workbench-component-boundaries"
],
"parent": null,
"relatedFiles": [
@@ -0,0 +1,148 @@
# 斑马线元素级编辑器设计
## 架构边界
本实验扩展现有直接编辑链路,而非建立画布对象存储:
```text
crosswalk feature 点击
-> elementId
-> element manifest (anchor + parameters + legal controls)
-> native-road-edits/v2 constraint
-> resolveDirectEditConstraints
-> compileControlMarkings
-> preview / save / recompile
```
`elementId` 是选择和分组标识;持久化仍使用稳定语义 anchor 上的 constraint。它不能是 GeoJSON 数组下标、屏幕坐标或临时 UUID。
## 选择合同
斑马线的每一条 stripe feature 必须包含 `native_id`、`element_id` 与可回链的 crossing / approach 身份。选择适配层只读取 `element_id`,再向服务器取得选中元素的权威 manifest。客户端不会据条带数量、空间距离或渲染顺序自行聚类。
元素 manifest 至少包含:
```ts
interface EditableElement {
elementId: string
kind: 'crosswalk'
anchor: { type: 'junction-approach'; nodeId: string; segmentId: string }
featureIds: string[]
controls: Array<{
kind: 'position' | 'length' | 'width'
value: { current: number; min: number; max: number; unit: 'meter' }
axisAzimuth?: number
}>
fields: Array<{ key: string; value: number; min: number; max: number; unit: 'meter' | 'count' }>
}
```
第一阶段发布 `position` 与 `length` / `width`:位置沿用现有 `junction-crosswalk-inset`,尺寸需要新的回写规则(见「尺寸的语义」)。`rotation` **不在本任务范围**,理由见文末。
## `elementId` 已经存在
实测:48 条条带按 `crossing_node_id` 分组恰好得到 8 组、每组 6 条,且没有任何
crossing 对应多条道路。唯一性是结构性的——`compileControlMarkings()` 的循环是
`for (const crossing of model.crossings)`,每次迭代由单个 `crosswalkCandidate`
产出一组。
因此 **`crosswalk:node/<crossingId>` 就是稳定的组标识**,无需新增编译器字段。
条带 `native_id` 形如 `crosswalk:node/-26452:1`,组前缀直接可用;
`crossing_node_id` 也已在 feature 属性里。
客户端据此分组**不构成** PRD 禁止的「按经纬度近似聚类」——它读的是已发布的稳定
标识,不是空间猜测。
> 早期分析曾断言组标识缺失,理由是「同一节点的多个进口共用它」。那是把
> **crossing 节点**(`node/-26452`,人行横道)与 **junction 节点**
> (`node/1140799725`,路口)混为一谈了。两者不是同一个 id。
## `affects` 缺失仍是真问题
上一节不影响这一节。`junctionAffects()`(`direct-edit-solver.js:628`)构造的是
`junctionSurfaceId + roadAffects + connectors`,**从不加入 crosswalk 或 stop-line**。
实测在有 48 条斑马线的区域,`junction-crosswalk-inset` 手柄的 `affects` 共 59 项,
crosswalk 为 **0**。
成因是求解器手上没有「进口 → crossing」的映射:该关系在编译器的
`compileControlMarkings()` 内部由 `arrivalEndpointIds` 与距离阈值算出,从未对外发布。
后果限于**拖拽高亮会亮错一片**(PRD 第 2 条要求高亮受影响对象)。
它**不阻塞选中**,因为选中走的是上一节的组标识。两者是独立的两步。
## 编辑与预览
- 选择由 `MapCanvas` 的 feature 事件产生,但选择状态由 App/编辑会话持有,不能写入 baseline source。
- 元素控件写入的是 manifest 指定的 constraint kind/value;表单复用同一写入器。
- 选中框和控件只是 `editHandles` / `editGhost` 层的临时 UI;权威预览仍由服务端返回,baseline source 不被客户端改写。
- 空白点击会清除元素选择;道路选择可继续决定道路级 handle manifest。斑马线元素选中与道路选择可并存,但两组控件不得重叠或竞争同一 pointer 手势。
## 尺寸的语义
斑马线的几何目前**全是字面量**(`native-road.js:1264`):
```js
rectangleAt(controlCenter, axis, across, 3, 0.45, -2.25 + index * 0.9)
// ↑长 ↑宽 ↑偏移,共 6 条
```
`rectangleAt(center, axis, across, length, width, offset)` 中 `length` 沿 `axis`
(行车方向),`width` 沿 `across`(横跨道路)。所以:
| 用户看到的 | 实际是什么 | 存储形态 |
| --- | --- | --- |
| 进深(沿行车方向) | 每条条带的 `length`,6 条共用 | 一个数,可直接参数化 |
| 跨度(横跨道路) | **条带数 × 间距**,非存储值 | 派生量 |
跨度是派生量,所以拖四角改跨度必须决定改哪个因子。**已定:固定间距、改条带数。**
- 条带宽 0.45m 与间隙 0.45m(间距 0.9m)在现实中是标准化的,改间距会让宽路上的
斑马线拉得很稀,不符合任何规范。
- 代价是跨度手柄按 0.9m **量化跳动**,不是连续的。这是语义诚实的结果,
不是手感缺陷;UI 上必须让它看起来是有意吸附的。
同时修掉一个既有缺陷:**跨度恒为 5.4m,与路宽无关**。20m 宽的路上斑马线也只有
5.4m,横不过去。参数化后默认跨度应由路宽推导,而不是写死 6 条。
## 选中框与抓手
视觉采用常规 transform gizmo:矩形虚线选框 + 四角空心方块。
一条硬规矩:**画几个抓手,就得有几个是活的。** 画了拖不动的四角、或转了没反应的
旋转柄,正是 `flag.ts` 为 `profile.interval` 立下的反面教材——
「一个拖了没效果的控件比没有控件更糟」。长得像 Figma 但只有一半能用,
比朴素的圆点更糟,用户会当成 bug 报。
所以抓手随能力分批出现,而不是先画全再逐个点亮:
| 抓手 | 语义 | 何时出现 |
| --- | --- | --- |
| 虚线选框 | 纯反馈,无语义 | 第一阶段 |
| 移动 | `junction-crosswalk-inset` | 第一阶段(语义现成) |
| 四角方块 | 进深 / 跨度 | 第一阶段(需编译器参数化) |
| 旋转柄 | 相对进口轴的偏转角 | **不做** |
## 旋转为何押后
`axis` 派生自 `crosswalkCandidate.placement.axis`,即进口方向。要能旋转,
需要新增一个「相对进口轴的偏转角」constraint kind。而 `design.md` 的规矩是
**新增 kind 的前提是几何阶段必须已经消费它**——先证明 `compileGeometry()` 读取
该参数,再画任何手柄。
偏转角本身是合理的(现实中斑马线确实会相对进口斜置),且用「相对派生轴的角度」
表达是语义化的,不违反「不持久化 transform 矩阵」。但它是独立的一轮
编译器 + kind + 客户端工作,已明确押后。
## 数据演进
位置继续使用已有 `junction-crosswalk-inset`。尺寸需要新的持久化形态,本阶段一并落地:进深与条带数各是一个参数,跨度由 `条带数 × 间距` 派生,间距本阶段不可编辑。具体是新增专属 kind 还是扩展同一 kind 的严格 schema,在第一个门禁(进口↔组映射)通过后定,不预先固化。
新增任何 kind 前必须先证明 `compileGeometry()` 读它——本项目已经为 `profile.interval` 交付过一个拖了无效果的手柄。
缺省参数必须字节级保持现有斑马线输出。参数越界、条带间互相重叠或越过可用进口范围均返回 blocking diagnostic,不在客户端静默钳制真实约束。
## 兼容与回滚
- 无新 constraint 时,编译输出与当前版本一致。
- `directEdit` 关闭时不请求 element manifest、不安装元素选择交互、不产生额外图层。
- 第一阶段每个步骤独立提交;回滚元素 UI 或 manifest 不影响既有道路级控制。
@@ -1,4 +1,6 @@
{"file":".trellis/spec/backend/direct-edit-api.md","reason":"元素 manifest、preview 和持久化必须继续满足直接编辑的服务端合同。"}
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"元素选择、临时控件与表单必须保持 handle/ghost/preview 图层所有权。"}
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"元素选择、临时控件与表单必须保持 handle/ghost/preview 图层所有权;§11-14 定义了输入通道汇合点、夹值/拒绝分工与聚焦期文本所有权。"}
{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"feature 属性、element manifest、constraint schema 与客户端选择状态跨越编译器、API 和 UI。"}
{"file":".trellis/tasks/08-26-direct-manipulation-road-editor/design.md","reason":"继承 v2 语义约束、坐标分层、预览和 revision 的权威合同。"}
{"file":".trellis/spec/guides/code-reuse-thinking-guide.md","reason":"元素控件必须接既有 draftValue/settleValue/abandonGesture,禁止新建第二条预览或 undo 链路。"}
{"file":".trellis/tasks/08-26-direct-manipulation-road-editor/design.md","reason":"继承 v2 语义约束、坐标分层、预览和 revision 的权威合同,以及新增 kind 前必须先证明几何阶段消费它的规矩。"}
{"file":".trellis/tasks/08-31-parameter-panel-binding/design.md","reason":"参数表单那一半的既有实现与三个通道无关出口的契约。"}
@@ -0,0 +1,134 @@
# 实施计划
顺序按**风险递减**排列:每一步都有可独立验证的门禁,失败即停,不进入下一步。
数据前提:`nantaizihu-9PTsZg`(由桌面 `南台子湖创新谷OSM.osm` 导入)含 10 个
`highway=crossing` 节点、8 组 zebra,编译出 48 条斑马线与 8 条停止线。
不带 crossing 的 OSM 无法验证本任务任何一步。
## 0. 建立事实与测试夹具
- 追踪 `compileControlMarkings()` 的每条 stripe 属性、`native_id` 构成,以及从地图点击到 `onFeature` 的路径。
- 添加失败优先的测试:同组 stripe 需要稳定共享 `elementId`,不同 crossing 不得共享;空编辑输出与基线字节一致。
- 门禁:能证明一个具体 feature 无歧义回链到一个 junction approach 和 crossing。
## 1. 元素选择(纯客户端)
`design.md` 已实测确认 `crosswalk:node/<crossingId>` 就是稳定组标识,
条带属性里已有 `crossing_node_id`。**本步不需要改编译器。**
- 客户端建立 `ElementSelection` 纯状态:从 feature 属性推出组标识,不做空间聚类。
- 点击任一条带选中整组、点空白清除;选择状态由 App / 编辑会话持有,不写 baseline source。
- 元素选中与道路选择可并存,但两组控件不得竞争同一 pointer 手势。
- 验证:客户端 selection 单元测试(同组共享、跨组不共享、重编译后稳定)。
- **门禁**:一个具体 feature 无歧义回链到一个组,且组内条带数与编译输出一致。
## 2. 选中框与移动
- 渲染矩形虚线选框(框住整组 6 条)+ 移动抓手,接已有 `junction-crosswalk-inset`。
- 控件走 `App.tsx` 既有的三个出口 `draftValue()` / `settleValue()` / `abandonGesture()`,**不新建第二条预览或 undo 链路**(见 `.trellis/spec/frontend/direct-edit-client.md` §11)。
- 安装时不得影响道路 handle 的 hit-test。
- **门禁**:一次非空元素编辑可在正式重编译结果中观察到斑马线位置变化。只交付 UI 不算通过。
## 3. 修正 `affects`(服务端)
独立于第 1 步——选中不依赖它,但拖拽高亮依赖。
- 求解器建立并消费「进口 → crossing」映射,使 `junctionAffects()` 不再遗漏 crosswalk。
该关系目前只存在于 `compileControlMarkings()` 内部(`arrivalEndpointIds` + 距离阈值)。
- 验证:API 测试。
- **门禁**:`junction-crosswalk-inset` 手柄的 `affects` 必须包含它实际移动的那 6 条 crosswalk feature。当前实测为 0。
## 4. 编译器尺寸参数化
斑马线几何目前全是字面量(`native-road.js:1264`:长 3m、宽 0.45m、间距 0.9m、6 条)。
- 进深与条带数成为参数;间距本阶段固定 0.9m 不可编辑;跨度 = 条带数 × 间距,派生。
- 默认跨度由路宽推导,修掉「跨度恒为 5.4m 与路宽无关」的既有缺陷。
- 无约束时输出与当前版本**字节级一致**(除上述默认跨度修正外,该修正需单独记录并更新基线)。
- 越界、条带重叠、超出可用进口范围返回 blocking diagnostic。
- **门禁**:先证明 `compileGeometry()` 读取新参数,再画任何抓手。这条规矩来自
`profile.interval` 那次教训——求解器写了、几何阶段没读、交付了一个拖动无效果的手柄。
## 5. 四角尺寸抓手
- 四角空心方块:一轴改进深(连续),一轴改跨度(按 0.9m 量化吸附)。
- 量化必须看起来是有意吸附,不能像卡顿。
- 表单与抓手写同一组元素参数,值、单位、范围、诊断一致。
- **门禁**:画出来的每个抓手都必须是活的。宁可少画,不可画死的
(`direct-edit-client.md` 的 `intervalEditingSupported` 先例)。
## 6. 复盘
- 手测:选中、取消、道路级手柄共存、移动钳位、尺寸吸附、表单校验、保存重载、撤销/重做。
- 记录哪些结论可推广到停止线/箭头,哪些**不可**——斑马线只改位置与自身尺寸,
不改路口形状;`approach-width` / `cutback` / `corner-radius` 是另一个几何类别,
本实验不为它们背书(见 `prd.md` 的「试验对象的覆盖边界」)。
## 明确不做
- 旋转。需要新增「相对进口轴偏转角」constraint kind 且编译器先消费它,已决定押后。
- 条带间距编辑。
- 推广到停止线、箭头、信号灯。
## 验证命令
```sh
npm run format:check
npm run test
npm run test:client
npm run test:client:unit
npm run build
```
## 风险文件
- `src/compile/native-road.js`:斑马线生成与默认输出兼容性;尺寸参数化会动到基线快照。
- `src/compile/direct-edit-solver.js`:`junctionAffects()` 是第 1 步的核心;element manifest 与 handle manifest 不得互相污染。
- `src/compile/native-road-edits.js`:新增 kind 或扩展 schema 时校验必须同步。
- `workbench/server.js`:element manifest 查询与 preview 不得写入磁盘。
- `workbench/client/src/App.tsx`、`edit/`、`components/`:元素控件必须接既有三出口;选中框是临时 UI,不得写 baseline layer。
- `test/fixtures.js`:默认跨度改由路宽推导会改动 fixture 基线,需显式更新而非静默接受。
---
## 交付进度(2026-08-31)
| 步骤 | 状态 |
| --- | --- |
| 0 建立事实与测试夹具 | ✅ |
| 1 元素选择 | ✅ `edit/element.ts`,浏览器已确认;已推广到停止线 |
| 2 选中框与移动 | ✅ 虚线框可直接拖拽 |
| 3 修正 `affects` | ⏸ 暂缓——客户端从不读 `affects`,高亮未实现,单独修不可见。应与高亮作为一件事做 |
| 4 编译器尺寸参数化 | ✅ `junction-crosswalk-size`,门禁已过,基线已更新 |
| 5 四角尺寸抓手 | ⬜ 未开始,见下方设计难点 |
| 6 复盘 | 部分:推广分析见 `research/generalising-to-other-markings.md` |
第 1–2 步之外另修了两处既有缺陷:`MapCanvas` 的陈旧闭包与空白点击不上报,
以及 `junction-crosswalk-inset` 的上界(44%~88% 死区,见
`08-31-parameter-panel-binding/research/manifest-range-vs-solver.md`)。
手测确认:选中、虚线框、拖拽均可用。**尚未手测**:框跟随修复后的表现、
上界修复后的拖拽手感——两者都需重启工作台进程才能生效。
## 第 5 步的设计难点(未解决)
`junction-crosswalk-size` 的值是**一对数** `{ depthMeters, stripeCount }`,
而拖拽链路是标量的:`projectHandleValue` 产出一个数,`constraintValueFor`
把它包成一个 value。四角抓手需要两个自由度:
- 一轴改进深(连续,米)
- 一轴改跨度(量化,写回 `stripeCount`)
拖其中一个必须**保留另一个的当前值**,否则每次拖拽都会把未触碰的那半重置为默认。
可行方向(未定):
1. 发两个标量手柄,`draftFor` 在构造 value 时与已有约束合并
2. 扩展 `EditHandle` 表达多分量,改动面更大
3. 元素控件不走 `draftFor`,自己构造 value——**违反「两条通道汇合于同一出口」**,不推荐
方向 1 最小,但需要 `draftFor` 能读到该约束的当前值;目前它只从 handle 拿标量。
动手前应先定这个,否则会长出第二条 draft 路径。
另:`junction-crosswalk-size` 已加入 `JUNCTION_KINDS` 但**不在** `CONTROL_KINDS`,
所以参数面板不渲染它——它的值是一对数,而面板渲染标量。接入抓手时一并处理。
@@ -12,6 +12,7 @@
- `compileControlMarkings()` 为一组斑马线生成多条 `crosswalk` GeoJSON feature;每条 feature 的属性目前不足以作为稳定的组级编辑目标。
- 浏览器已有 `EditSession`、服务端权威 preview、保存、重编译与撤销链路。编辑数据必须保持语义约束,不得保存派生 GeoJSON 或屏幕坐标。
- 当前普通道路级手柄仍服务于横断面参数,不应与元素级选择共用或互相覆盖。
- `08-31-parameter-panel-binding` 已交付参数表单那一半:`ParameterPanel` 组件、`edit/parameter.ts` 的文本↔数值/范围判定/单位换算,以及 `App.tsx` 中通道无关的三个出口 `draftValue()`(预览)、`settleValue()`(提交一步 undo)、`abandonGesture()`(放弃)。元素级控件应接入同一组出口,**不要新建第二条预览或 undo 链路**。
## 范围
@@ -52,6 +53,25 @@
- 选中框是交互反馈,不能成为第二个几何模型;所有位置、范围和尺寸的权威值由后端 element manifest 给出。
- 当前地图 feature 的属性可能缺少足以识别 crossing 的稳定字段。需要先通过编译器补充,不可在客户端按经纬度近似聚类。
### 试验对象的覆盖边界(2026-08-31 决定)
本任务的上游动机是**为复杂路口做前置**:普通四岔口已有 20 个手柄分属 4 条 segment,
主地图一次只显示当前选中 segment 的手柄,要看全一个路口需依次选中 4 条道路。
每参数一个圆点的模型撑不到复杂路口,元素级选中是必需品而非优化。
已明确决定:**第一次试验只做斑马线,不并入形状类元素**,以控制风险。
代价必须记录在案——斑马线是**位置类**元素,`design.md` 明确「不改变路口形状,
只移动标线,因此不触发路口边界重算」。而复杂路口真正难的是
`junction-approach-width` / `junction-cutback` / `junction-corner-radius`:
它们改变路口多边形本身,涉及边界连续、面自交、cutback 处截面衔接。
因此:
- 本试验通过 **只证明**「选中 + 位置编辑」这条链路可行。
- 它 **不证明** 形状类元素的元素级编辑可行,那是另一个几何类别。
- 推广到形状类元素前必须单独验证,不得以本试验的结论替代。
## Acceptance Criteria
- [ ] TBD
@@ -0,0 +1,84 @@
# 元素模型能推广到哪些标线
日期:2026-08-31
来源:`08-28-crosswalk-element-editor` 第 1–2 步交付后,对 `nantaizihu-9PTsZg` 的实测。
## 各元素的分组结构(实测)
| 图层 | provenance | 分组键 | feature | 组数 | 每组大小 |
| --- | --- | --- | --- | --- | --- |
| `crosswalks` | `native-road-crosswalk/v1` | `crossing_node_id` | 48 | 8 | 恒 6 |
| `vehicleStopLines` | `native-road-stop-line/v1` | `crossing_node_id` | 8 | 8 | 恒 1 |
| `turnArrows` | `native-road-turn-arrow/v1` | `lane_id` + `maneuver` | 108 | 28 | 3 或 5 |
| `directionArrows` | `native-road-direction-arrow/v1` | `lane_id` | 324 | 50 | 2~28 |
| `laneSeparators` | `native-road-lane-separator/v1` | `road_id` + 车道对 | 731 | 9 | 26~230 |
## 关键陷阱:斑马线与停止线共用 `crossing_node_id`
交集 **8/8**——两者由同一个 `controlFeature()` 构造,`crossing_node_id` 完全重合。
只按该字段分组会把一组斑马线和它的停止线并成一个"元素"。
**必须先按 `provenance` 判类型,再取分组键。** `element.ts` 已如此实现并有测试守着
(`rejects a stop line, which shares the same feature builder`)。任何推广都不能绕过这一步。
## 可编辑性就绪度
| 元素 | 约束 kind | 编译器是否消费 | 实测响应 | 成本 |
| --- | --- | --- | --- | --- |
| 斑马线 | `junction-crosswalk-inset` | ✅ | 已修正上界,全程有效 | **已完成** |
| 停止线 | `junction-stop-line-offset` | ✅ | **全程线性,零死区** | **几乎免费** |
| 转向箭头 | ❌ 无 | ❌ | — | 新 kind + 编译器 |
| 方向箭头 | ❌ 无 | ❌ | — | 新 kind + 编译器 |
| 车道分隔线 | v1 overrides,仅样式 | 仅样式 | 位置不可编辑 | 另一类问题 |
停止线实测:offset `0.5 → 126` 位移 `0 → 125.36m`,增量始终 1:1。
**没有斑马线那种死区**,可以直接接入。
但它有反向的毛病:声明范围 `[0.5, 126.28]`(`approach.length * 0.45`),
允许把停止线推到离路口 126 米——而 `native-road.js` 有
`STOP_LINE_MAX_APPROACH_DISTANCE_METERS = 25`。范围过宽同样是缺陷,
见 `.trellis/spec/backend/direct-edit-api.md` §12。
## 值得建立的抽象(仅此而已)
一个按 provenance 索引的小注册表:
```ts
interface ElementSpec {
provenance: string;
kind: ElementKind;
groupKey(properties: Record<string, unknown>): string | null;
constraintKind: ConstraintKind;
}
```
`element.ts` 现有的 `crosswalkElementIdOf` / `groupMembers` / `elementSelectionFor`
改为查表即可,选中、选框、拖拽三条链路无需改动。
**不要**据此建立"所有元素"的通用协议——PRD 明确禁止
(「不提前建立『所有元素』的大而全抽象」)。理由在上表里:
分组键的形态各不相同(单字段 / 双字段 / 派生),
每组大小从 1 到 230,箭头类连约束 kind 都还不存在。
现在能证明的只有「provenance + 分组键 → 组」这一条,注册表恰好只承诺这一条。
## 推荐顺序
1. **停止线**——注册表 + 一条 spec 条目。约束现成、编译器已消费、响应已验证。
同时暴露注册表是否够用:它的每组只有 1 个 feature,而斑马线是 6 个,
能验证分组逻辑不依赖"多 part"这个偶然属性。
2. **修 `affects`**(原第 3 步)——目前 `junctionAffects()` 不含任何标线,
拖拽高亮会亮错一片。停止线接入后这个问题会更明显。
3. **转向箭头**——需要新 constraint kind,且必须先证明 `compileGeometry()` 读它。
分组键 `lane_id + maneuver` 已验证(28 组,每组 3 或 5 个 part)。
4. **方向箭头**——最贵。分组语义本身待定:按 `lane_id` 是 50 组(编辑间距/整体偏移),
按 `lane_id + sequence` 是 324 组(逐个箭头独立摆放)。
这是产品决策,不是实现细节,需先定。
5. **车道分隔线**——不同类问题。已有 v1 样式 override,缺的是位置,
而位置由 `road-lane-divider` 约束管,属道路横断面而非元素级。
## 与复杂路口的关系
停止线和转向箭头都是**位置类**元素,与斑马线同属一个几何类别:
移动它们不改变路口多边形。所以第 1、3 步不会为形状类元素
(`approach-width` / `cutback` / `corner-radius`)提供任何背书——
那仍是独立的、未验证的一类,见 `prd.md`「试验对象的覆盖边界」。
@@ -3,7 +3,7 @@
"name": "crosswalk-element-editor",
"title": "斑马线元素级编辑器实验",
"description": "",
"status": "planning",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
@@ -11,7 +11,7 @@
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-08-28",
"completedAt": null,
"completedAt": "2026-09-07",
"branch": null,
"base_branch": "main",
"worktree_path": null,
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,57 @@
# 设计:约束范围校验与重放失效
## 问题边界
`road-edge-offset` 的 manifest 以 `makeRoadHandles()` 中一个 segment 的双向总宽计算 `±width * 0.45`,而 `applyRoadConstraint()` 针对锚点指向的单条 direction road 执行最小车道宽与外缘边界判定。二者不共享数据和公式,导致已发布的拖拽终点能被求解器拒绝。
范围是锚点在**当前模型和当前已应用截面状态**下的可行域;它不是客户端提示。直接 API、正式编译重放和 manifest 必须对同一个值作同一判断。
## 单一范围所有者
在 `src/compile/direct-edit-solver.js` 增加内部 range resolver。它接收当前 model、constraint/handle anchor,以及已经应用的 road profile 或 junction plan,返回值字段的 `{ min, max }`;无法解析的锚点由现有锚点状态流程处理,而不是伪造范围。
每个已发布 kind 均通过该 resolver 取范围:
- `road-edge-offset`:以锚点所指单条 road 的宽度、车道数及另一侧当前 offset 推导。下限确保总宽不低于 `laneCount * MIN_LANE_WIDTH_METERS`;两侧上限受单侧半宽不变量约束。不能再以 segment 总宽发布范围。
- `road-lane-divider`:按锚点 road 的单车道宽和最小车道宽推导对称范围。
- `road-sidewalk-width`、corner radius、crosswalk size:将现有有限常量移进 resolver。
- approach width、cutback、crosswalk inset、stop-line offset:由对应 approach 与当前 plan 推导;crosswalk inset 延用 `effectiveCrosswalkInsetMax()`,不再让 manifest / apply 分别持有上界。
Resolver 的上界不得低于已保存的 current 值:历史值会先在重放预检中判 stale,只有尚未失效的值才可发布给客户端。这避免“当前值超过 manifest max”的自相矛盾状态。
## 求解与重放
`solveConstraints()` 每次应用 constraint 前,将其与当前 profile/plan 交给 range resolver:
- 预览、保存后重新编译、直接调用 resolver:越界产生阻塞诊断,constraint state 为未应用 `invalid`;不夹值也不写回 document。
- `reconcileConstraints()`:对 `exact` / `recheck` 的已解析锚点,在不改值的前提下按当前几何计算其范围。值越界时将 document 内存副本状态置为 `stale`,并携带不可变的 replay reason `range-out-of-bounds`;该约束随后不会进入 solver。
- 锚点不存在仍是 `stale`,reason 为 `anchor-missing`。候选可重定位时仍沿用 `pending` / `conflicted`。
范围校验的阻塞诊断与重放 stale 是两条刻意不同的路径:前者说明本次草稿违法,后者说明曾经合法的历史编辑不再适合新的几何。
## API 契约
`constraintStates` 在原有 `status` / `applied` / `reason` 外,将 reason 标准化为可供 rebase 消费的枚举值:
- `range-out-of-bounds`
- `anchor-missing`
- 保留已有 `disabled`、`status-*`、`invalid`。
`POST /api/revisions/:id/rebase` 继续返回 status counts 和 constraints 明细;调用方通过每个 stale constraint 的 `reason` 区分范围失效和锚点失效。无 schema 版本变更,旧客户端可忽略新增/更精确的 reason。
## 数据流
```
current model + applied profile/plan
-> constraint range resolver
-> manifest value.min/max
-> preview/formal solver blocking validation
-> reconciliation stale check during replay
-> rebase constraintStates.reason
```
## 兼容性与风险
- 不修改 persisted v2 schema,也不自动夹值、重写 value 或近似映射锚点。
- 新 range 可能使旧文档中先前允许但几何上不可行的值显示为 stale;这是目标行为。上线前在真实 import 目录做 rebase 审计。
- 多条相互影响的 road constraints 仍按文档顺序求解。范围 helper 使用当前已应用 profile,确保 manifest 和本次 solver 的单值判断一致;组合造成的后续不变量失败仍由现有事务式 solver 拒绝,不能把其他约束偷偷改掉。
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,29 @@
# 实施计划:约束范围校验与重放失效
## 实施顺序
1. 在 `direct-edit-solver.js` 搜索所有 manifest 与 apply 分支中的范围常量,建立 anchor/context-aware range resolver,并为 road/junction kind 迁移已有边界。
2. 让 `makeRoadHandles()` / `makeJunctionHandles()` 从该 resolver 填充 `value.min` / `value.max`;road edge 使用单向 road 和该 side 的 profile,移除 segment 总宽 `0.45` 公式。
3. 在 `applyRoadConstraint()`、`applyJunctionConstraint()` 写入前调用相同 resolver,越界使用 kind 明确的 blocking diagnostic,保留现有 rollback snapshot 行为。
4. 扩展 `reconcileConstraints()`:已解析、可重放的值若落在新几何范围外则变为 `stale`,并发出 `range-out-of-bounds`;锚点缺失变为 `anchor-missing`,不破坏 pending/conflicted 逻辑。
5. 确认 `rebaseEdits()` 的现有 constraint 明细透传 reason;必要时为 response contract 补稳定字段和测试。
6. 追加 unit tests:外缘 extrema、直接越界诊断、manifest/solver 同源、几何缩窄后的 stale、不参与求解、anchor stale reason、既有 exact 回归。
7. 追加 API integration tests:`editPreview()` 越界诊断与 `rebaseEdits()` reason/counts。
8. 按项目质量门槛运行 format、unit/integration/client/build;对真实 import 做只读 rebase 审计并记录受影响约束数。
## 验证命令
```sh
npm run format:check
npm run test
npm run test:client
npm run build
```
测试重点不只比较 manifest 数字,还要把 manifest 的每个端点实际提交给 resolver,确认没有 blocking diagnostic。重放测试必须断言 stale constraint 未出现在 road profile / junction plan。
## 风险点与回退
- 风险文件:`src/compile/direct-edit-solver.js`。范围 helper 若错误共享 segment 与 direction 宽度,会再次出现 handle / solver 不一致;新增 fixture-style unit case 固化双向道路场景。
- 兼容性:保留 v2 文档、constraint kind、status 集合与 API 主字段。reason 仅增加细分值。
- 回退:本改动不迁移或覆写存储。若真实目录审计发现意外大量 stale,回退代码即可恢复旧行为,原始 edit documents 不受影响。
@@ -0,0 +1,70 @@
# 约束值范围的服务端校验与重放失效
## 目标
让 manifest 声明的取值范围与求解器实际接受的可行域一致,并让保存后因几何变化而越界的约束按既有 status 机制转 `stale`,而不是静默产出畸形几何。
缺口有**三种表现**,均已实测确认(证据见 `08-31-parameter-panel-binding/research/manifest-range-vs-solver.md`):
1. **过松且会被拒**——manifest 宣告的范围比求解器接受的宽。某 6.5m 道路的外缘偏移手柄声明 `±2.925`,超过约 `±1` 即返回 `direct-edit-outer-edges-cross`。宣告范围约为可行域的 3 倍。
2. **过松且静默无效**——比上一种更糟,因为没有任何反馈。`junction-crosswalk-inset` 声明 `[0, 8]`,实测 `0 → 3.2` 线性响应,`3.2 → 8` **位移增量全为 0**。成因是 `crossingJunctionInset()` 中 `targetDistance = max(0, cutbackMeters - inset)` 在 inset 达到 `cutbackMeters` 后触底,外加 `CROSSWALK_MAX_JUNCTION_INSET_METERS = 4` 的封顶。声明范围里约 60% 是死区。
3. **无校验**——求解器不检查 manifest 的 `min`/`max`,范围目前仅由客户端夹值实际约束。
> **第 2 种已于 2026-08-31 在 `08-28-crosswalk-element-editor` 中修复。**
> `src/compile/crossing-approach.js` 的 `effectiveCrosswalkInsetMax()` 按
> `cutback - max(0, junctionDistance - 4)` 发布真实上界,8 组实测全部吻合,
> 且 fixture 证明几何字节不变。
>
> 本任务因此**只需覆盖其余 kind**——尤其是第 1 种(外缘偏移)。
> 那次修复也给出了可复用的形态:**上界由几何推导,不是常量**;
> 以及一个易犯的坑:一条 segment 的两条方向道路可能在同一路口服务不同对象,
> 取第一个匹配会把 A 的上界发到 B 的手柄上。
第 1 种仍待处理:手柄在死区里拖动毫无反应或直接报错,与「控件坏了」难以区分,
正是 `flag.ts` 为 `profile.interval` 立下的那条规矩要避免的情形
(「一个拖了没效果的控件比没有控件更糟」),只是它发生在量程的一段而非整个控件。
## 已确认的事实
- `direct-edit-solver.js` 的 `applyConstraint` 分支(302、312、322 行附近)只校验 `Number.isFinite` 与非负,**未校验 manifest 声明的 `min` / `max`**。
- 范围目前是纯客户端概念:manifest 下发它,`projection.ts:60` 的 `projectHandleValue` 夹它,仅此而已。今天没出事,只因拖拽是唯一写入通道且它必夹。
- 部分范围是**动态的**:外缘偏移为 `±Math.max(0.1, width * 0.45)`,随道路宽度浮动;步行带固定 `0..8`;角部圆角固定 `0.5..30`。
- 因此保存时合法的值,可能在道路几何变化后越界——重导入改变车道数、其它约束改变断面宽度均可触发。该类越界发生在保存之后的求解期,**客户端结构上无法拦截**。
- 父 `design.md` 已为同类情形定义规则:"`boundaryIndex` ⋯ 重放时若车道数变化导致越界,该约束转 `stale`,不做近似映射。"数值范围越界属于同一类,只是未被写下。
- `08-31-parameter-panel-binding` 引入第二条写入通道(数值输入)。该任务在客户端拦截越界输入,但那只覆盖输入当下,不覆盖本任务的场景。
## 范围
1. manifest 发布的 `min`/`max` 必须落在求解器实际接受的可行域内——宣告一个必被拒绝的极值等于骗用户。
2. 求解器在应用约束时校验其值落在该 kind / 该锚点当前的合法范围内。
3. 越界值产生**阻塞性诊断**,不静默夹值、不静默丢弃。
4. 范围的计算与 manifest 中 `value.min` / `value.max` 的生成**共用同一处逻辑**,不得出现两份定义。
5. 重放(重导入、几何版本变更)时,因范围变化而越界的约束转 `stale`,与 `boundaryIndex` 越界同等处理。
6. rebase 响应的 status 计数与明细覆盖这一新的 `stale` 来源。
## 明确不做
- 不改变客户端拖拽的夹值行为(`projectHandleValue` 是渲染正确性的一部分)。
- 不为越界约束做近似映射或自动修正——与父 `design.md` 的"不自动改值"一致。
- 不新增约束 kind,不改动几何生成。
## 验收标准
- [ ] 复现 research 记录的场景:某 6.5m 道路的外缘偏移手柄,其发布的 `max` 不再是一个提交即被 `direct-edit-outer-edges-cross` 拒绝的值。
- [ ] 对任一手柄,提交恰好等于 manifest `min` 或 `max` 的值不产生阻塞诊断(宣告即可用)。
- [ ] 绕过客户端直接 POST 一个越界约束到 `/api/edit-preview`,返回阻塞性诊断而非畸形几何。
- [ ] manifest 的 `min`/`max` 与求解器校验用的范围来自同一处代码,可由测试证明二者一致。
- [ ] 构造一个"保存时合法、几何变化后越界"的场景(如缩窄道路使可行域下降),重放后该约束报 `stale`,且不参与求解。
- [ ] `stale` 的原因在 rebase 响应中可区分于锚点丢失导致的 `stale`。
- [ ] 既有的 `exact` 约束不因本改动被误判失效——回归现有 revision 编译结果不变。
- [ ] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run build` 全绿。
## 风险与门槛
- 范围收紧可能让**既有已保存约束**突然变 `stale`。上线前必须在真实 import 目录上跑一遍,确认影响面,并确保旧 revision 仍可打开并复现原结果(父 `design.md` 的可复现性要求)。
- 范围的两份定义(manifest 生成处与校验处)若各写各的,会产生"手柄允许但求解器拒绝"的死区。第 3 条是硬要求。
## 关联
- 缺口由 `08-31-parameter-panel-binding` 的设计过程发现,详见该任务 `design.md` 的「已知缺口」。
- 本任务不阻塞面板任务:面板的客户端校验独立成立。
@@ -0,0 +1,26 @@
{
"id": "constraint-range-validation",
"name": "constraint-range-validation",
"title": "约束值范围的服务端校验与重放失效",
"description": "服务端补 manifest min/max 校验;保存后因几何变化导致的数值越界转 stale",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P3",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-08-31",
"completedAt": "2026-09-03",
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": "08-26-direct-manipulation-road-editor",
"relatedFiles": [],
"notes": "",
"meta": {}
}
@@ -0,0 +1,2 @@
{"file": ".trellis/spec/frontend/direct-edit-client.md", "reason": "Verify that new lane selection does not write baseline layers or join the drag-handle path."}
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Verify the staged override remains a compiler-valid lane-maneuver payload."}
@@ -0,0 +1,48 @@
# Lane Maneuver UI Design
## Boundary
This increment exposes the existing v1 `lane-maneuver` override in the workbench.
It changes neither compiler validation nor the placement algorithms. In particular,
`native-road-direction-arrow/v1` remains display-only because it represents repeated
straight-ahead markings controlled by a separate interval policy.
## Selection Model
`edit/element.ts` remains the sole conversion point from clicked GeoJSON properties
to a logical element. Its registry gains a turn-arrow entry whose group key is the
ordered tuple `[lane_id, maneuver]`; the key is serialized with a dedicated, stable
separator rather than inferred from `native_id`. This groups the 3/5 polygon parts
of one visual arrow without merging arrows from different maneuvers on the same lane.
The current crosswalk/stop-line `ElementSelection` is junction-control-specific.
Turn arrows instead produce a lane selection carrying `laneId`, `maneuver`, and the
group feature ids. They deliberately do not call `handleForElement` or create an
outline/drag target: changing a maneuver is a v1 discrete override rather than a
v2 spatial constraint.
Lane centerlines already publish `native_id` equal to the compiler lane id. The
click handler recognizes that id and creates the same lane selection, with the
current maneuver resolved from the stored/staged override first, then from the
clicked turn arrow if present, otherwise empty. That makes an unmarked lane editable.
## Inspector And Save Flow
The inspector owns the discrete selector. It receives the selected lane and the
effective override list, offers the compiler's six exact canonical values plus
empty-string removal, and stages one deterministic id per lane. The existing
`stage` function replaces entries with equal ids, so a lane has exactly one pending
override and save/recompile continues through the established API path.
This is intentionally not a direct-edit (`EditSession`) operation: no preview
endpoint consumes lane-maneuver and a client-side visual preview would disagree with
the authoritative compiler output. The existing save-then-recompile copy remains
the user-visible boundary.
## Tests
Pure tests cover tuple grouping, part selection, lane-centerline selection and
non-selection of direction arrows. A component-level test is unnecessary for the
existing app test style; the inspector's emitted object is kept simple enough to
exercise by extracting a pure override builder if needed. Typecheck and build cover
the wiring.
@@ -0,0 +1,2 @@
{"file": ".trellis/spec/frontend/direct-edit-client.md", "reason": "Preserve direct-edit layer and handle ownership while adding a separate v1 discrete selection path."}
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Keep the UI's staged override shape aligned with the compiler and API contract."}
@@ -0,0 +1,16 @@
# Implementation Plan
1. Generalize the element registry's group-key reader and add a lane-maneuver
selection type for turn arrows and lane centerlines.
2. Wire map clicks to preserve the existing control-element path while selecting
lane arrows or centerlines through the new path.
3. Add an inspector selector that stages a lane-maneuver override with canonical
values and an explicit removal value.
4. Add focused element tests for multi-property grouping and unmarked-lane entry.
5. Run formatting, server tests, client type/unit tests, and production build.
## Rollback
The UI is isolated to `workbench/client/src/edit/element.ts`, `App.tsx`, and its
unit tests. Reverting those files restores the previous display-only arrow behavior;
the compiler's already-shipped v1 override contract remains untouched.
@@ -0,0 +1,125 @@
# 车道转向箭头覆盖
## 目标
让用户能决定某条车道画什么导向箭头,而不必回去改 OSM。走 **v1 override**,
新增 `lane-maneuver` kind。
## 为什么是 v1 而不是 v2
这一点决定了整个设计,先说清楚。
导向箭头的**内容**(左转/直行/右转)来自 OSM 标签
`turn:lanes:<direction>`,是车道的一个**离散属性**;而 v2 直接编辑的锚点是
`{roadId, station}` 这类**位置上的约束**。「这条车道显示什么箭头」没有位置,
硬塞进 v2 会让锚点模型失去意义。
v1 override 里已有覆盖 OSM 派生值的先例:`road` kind 覆盖 `laneCount`、
`widthMeters`、`sidewalkLeft/Right`。转向属于同一类。
**箭头的位置参数(间距、距路口距离)是另一回事**,属于 v2,且还有未定的
分组决策,不在本任务内。
## 已确认的事实
- `turn:lanes:<direction>` 或 `turn:lanes` 以 `|` 分隔,每段对应一条车道;
`compileLaneMarkings()`(`native-road.js:1520`)读它,`maneuvers[index]` 取到本车道那段。
- 当前 `if (!explicitManeuver) continue`——OSM 没标的车道**不画箭头**,
所以覆盖必须能给"本来没有"的车道加上箭头,不只是改已有的。
- `normalizeManeuver()`(`turn-lane-arrows.js:114`)已导出,支持恰好 6 种取值:
`through` / `left` / `right` / `through;left` / `through;right` / `through;left;right`。
它对输入排序后查表,所以 `left;through` 与 `through;left` 等价。
- `validateOverrides()` 已构造 `laneIds` 集合(`native-road.js:295`),
形如 `lane:<roadId>:<index>`,`lane-connection` 是使用它的现成先例。
- 实测当前区域有 28 条 `turn:lanes:*` 标签,编译出 108 个导向箭头,
`maneuver` 取值 4 种、`placement_distance_meters` 恒为 6。
## 范围
1. 新增 v1 override kind `lane-maneuver`,字段 `{ laneId, maneuver }`。
2. `maneuver` 取 6 种受支持值之一;**空字符串表示不画箭头**,用于移除 OSM 标了但不想要的箭头。
3. 校验 `laneId` 属于已知车道;未知目标按既有 stale 机制处理,不新造一套。
4. 覆盖优先于 OSM 标签;能给 OSM 未标注的车道**新增**箭头。
5. 无覆盖时输出与当前版本**字节级一致**。
## 明确不做
- 箭头的位置参数(间距 32m、距路口 6m)——属 v2,且分组语义未定。
- 直行箭头(`directionArrows`)——那是沿车道重复摆放的另一套逻辑。
- 客户端 UI。本任务只做编译器与 override 合同;先证明覆盖生效,再谈怎么点选。
- 不改 OSM 源文件,不改车道数或拓扑。
## 验收标准
- [x] 对一条 OSM 已标 `turn:lanes` 的车道施加覆盖,编译输出的 `maneuver` 变为覆盖值。
- [x] 对一条 OSM **未标**的车道施加覆盖,输出**新增**该车道的箭头。
- [x] `maneuver: ''` 使该车道不再输出箭头。
- [x] 非法 `maneuver`(如 `'u-turn'`)被拒绝并报错,不静默降级。
- [x] 未知 `laneId` 按既有 stale 机制处理,与 `lane-connection` 行为一致。
- [x] 空覆盖集的编译输出与改动前字节一致(fixture 不变)。
- [x] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build` 通过。
## 风险与门槛
- **门禁**:先证明覆盖真的改变正式编译输出,再谈 UI。本项目已有
`profile.interval` 的教训——参数写了、几何阶段没读、交付了一个无效控件。
- `laneId` 的稳定性与 `lane-connection` 同级:车道数变化会使高索引车道失效,
由既有 stale 机制兜底,本任务不新增重定位逻辑。
- `normalizeManeuver` 对未知取值会原样返回拼接串(`supported.get(...) || parts.join(';')`),
所以校验必须在 override 层做,不能指望它兜底。
## 交付状态(2026-08-31)
编译器与 override 合同**已完成**,7 条验收标准全部通过,实测于
`nantaizihu-9PTsZg`(108 个导向箭头 / 28 条车道有箭头)。
| 场景 | 结果 |
| --- | --- |
| 覆盖已标注车道 | `through;left;right` → `left` |
| 给未标注车道新增 | 新增 3 个 part |
| `maneuver: ''` 移除 | 0 个 |
| 空覆盖集 | 与基线字节一致,fixture 未变 |
**客户端 UI 按 PRD 明确不做。** 现在只能通过 override 文件或 API 施加。
接 UI 时需要的前置:导向箭头的分组键是 `lane_id + maneuver`(实测 108 个 → 28 组,
每组 3 或 5 个 part),与斑马线的 `crossing_node_id` 不同形态,
`element.ts` 的注册表需要扩展 `groupProperty` 为可组合的形式。
## UI 增量(规划中,2026-09-01)
### 已确认事实
- 工作台点击事件会传递所有命中的 feature,但只有开启 `?directEdit=1` 时才会请求
`element.ts` 判断是否为可编辑元素;该注册表目前仅登记斑马线和停止线,故转向箭头
会清空元素选择。
- 路口转向箭头的 provenance 是 `native-road-turn-arrow/v1`,一个逻辑箭头由
`lane_id + maneuver` 共同标识,并绘制为 3 或 5 个 part。
- `lane-maneuver` 是 v1 离散 override,不是 v2 位置约束;它不能接入现有
`ElementSelection -> handleForElement -> 拖拽手柄` 路径。
- 沿车道重复的道路方向箭头 provenance 是 `native-road-direction-arrow/v1`,固定为
`through`,由 32m 间距规则生成,当前没有对应的 override 合同。
- 仅允许点击已生成的转向箭头无法满足“给 OSM 未标注车道新增箭头”:该车道没有 feature
可点,故 UI 还必须允许从车道中心线或道路检查器选择目标车道。
### 拟议范围
1. 点击任一转向箭头 part 时,选中其完整 `lane_id + maneuver` 组,并在检查器展示
六种合法转向及“无箭头”。
2. 从车道中心线进入同一编辑器,使没有现存转向箭头的车道也能新增箭头。
3. 选择值以单一、按 `laneId` upsert 的 `lane-maneuver` override 暂存;保存并重新生成后
更新正式几何。空字符串仍表示移除。
4. 扩展 element 注册表的分组键表达能力,但不把 v1 override 伪装成 v2 拖拽约束。
### 验收标准(UI)
- [x] 点击任一 `native-road-turn-arrow/v1` part 会选中同一
`lane_id + maneuver` 的所有 part,且不会并入同车道的其他 maneuver。
- [x] 点击车道中心线能选中该车道并展示相同的转向编辑器;即使该车道当前没有转向箭头,
用户仍能选择一种转向并暂存。
- [x] 转向编辑器只提供编译器接受的六种规范值和“无箭头”;选择会按 laneId upsert
一个 `lane-maneuver` override,空字符串表示移除。
- [x] “保存修改”后 override 被服务端接受;“保存并重新生成”后,编译结果反映所选
maneuver 或移除,并可重新选择新的箭头。
- [x] `native-road-direction-arrow/v1` 不显示转向编辑器,32m 间距及其生成数量不变。
- [x] 既有斑马线、停止线选择及直接编辑手柄不回归;`npm run format:check`、
`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build` 通过。
@@ -0,0 +1,26 @@
{
"id": "lane-maneuver-override",
"name": "lane-maneuver-override",
"title": "车道转向箭头覆盖",
"description": "v1 override 新增 lane-maneuver:覆盖 OSM turn:lanes,决定某条车道画什么导向箭头",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-08-31",
"completedAt": "2026-09-01",
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": "08-26-direct-manipulation-road-editor",
"relatedFiles": [],
"notes": "",
"meta": {}
}
@@ -0,0 +1,4 @@
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"检查面板未写入 baseline source、控件值全部由 manifest 驱动、previewSeq 仲裁未被绕开。"}
{"file":".trellis/spec/frontend/state-management.md","reason":"检查聚焦/失焦的值所有权切换无第二真相来源,且中间态不被预览响应改写。"}
{"file":".trellis/spec/frontend/quality-guidelines.md","reason":"检查新增纯逻辑的单测覆盖与客户端质量门槛。"}
{"file":".trellis/spec/guides/code-reuse-thinking-guide.md","reason":"核对拖拽与输入两条通道汇合于同一个 draftFor,未出现并行实现。"}
@@ -0,0 +1,138 @@
# 参数面板与数值双向绑定 · 设计
> 父任务 `08-26-direct-manipulation-road-editor/design.md` 仍是约束模型、求解边界与 API 合约的权威定义。本文只补充**第二条输入通道**引入的规则,不改变其中任何一条。
## 架构定位
本任务不触碰服务端。约束模型、求解器、handle manifest、revision 全部原样保留。改动完全落在客户端输入层:
```text
┌─ 拖拽(连续)──→ projectHandleValue() ─┐
选中道路 → manifest ─┤ ├→ draftFor(handle, value)
└─ 输入框(离散)→ 解析 + 范围校验 ──────┘ ↓
PreviewRequester
(80ms 防抖 + previewSeq 仲裁)
↓
EditSession.commit()
```
`draftFor(handle, value)`(`App.tsx:206`)本就是纯函数 `(手柄, 数字) → 草稿`。两条通道的唯一区别是**如何产生那个数字**以及**何时闭合 gesture**,汇合点之后完全一致。
## 不变量:取值范围
> **约束值永不超出 manifest 声明的 `[min, max]`。**
>
> - **连续输入**(拖拽、滑杆)在极限处**停止移动**。ghost 与手柄按夹后的值绘制,绝不跟随越界的光标。
> - **离散输入**(数值框)**拒绝接受**越界值:标记非法、不发预览、不进 undo 栈、保留最后一个有效预览。范围提示可一键填入极值。
这是**一条规则的两种设备表达**,不是两套策略。
连续设备没有表达"拒绝"的手段——停止移动就是它的拒绝,而且是当场可见的:手柄停住、光标继续走。用户不会形成"我设成了 -24.1"这个信念。夹值理由见 `projection.ts:75` 的注释(ol-ext 探针把手柄拖到 -24.1m 而约束夹在 -5.4m,手柄指向一个不可能存在的路形)。
离散设备则相反:数字已经键入、Tab 已经按下,此时夹值是**事后篡改**。且失败模式不对称——
| 用户意图 | 夹值 | 拒绝 |
| --- | --- | --- |
| 打错(想输 2.4,输成 24) | 变成 5.4,看起来合理,可能永不被发现 | 立即可见 |
| 想拉满 | 如愿 | 多一步(或点范围提示一键填入) |
拒绝错了只损失一次击键;夹值错了会把一个**看起来正常的错误值**送进下游编译与仿真。故取拒绝。
## 值的所有权
任一时刻,一个参数的显示值来源是**唯一**且由聚焦状态决定的:
| 状态 | 显示值 | 理由 |
| --- | --- | --- |
| 未聚焦 | `handle.value.current` | 服务端权威回显 |
| 聚焦中 | 本地文本 draft | 保留 `1.`、`-`、空串等中间态 |
必须如此的原因:`App.tsx:197` 在每次预览结算时 `setManifest(response.handles)` 整体替换 manifest。受控输入若直接绑定 `value.current`,键入 `1.` 触发的防抖预览返回后会把输入框冲成 `1`,小数点消失。
失焦即清 draft。此时 `value.current` 必然等于刚提交的值——因为 `direct-edit-solver.js:136` 的 `numericValue()` 直接回显约束里的数字,服务端不改写。**故不存在"请求值 vs 求解值"的双显示需求。**
> 该结论依赖 solver 当前行为。若日后改为回写求解结果,本节规则失效,需同步重审。
## gesture 边界
`gestureIdentity()` 是懒创建的 operationId 单例,`commitGesture()` 释放它。它抽象的是"一段有始有终的操作",与指针无绑定关系,因此可原样承载键盘输入:
| 阶段 | 拖拽 | 输入框 | 动作 |
| --- | --- | --- | --- |
| 开始 | `pointerdown` | `focus` | 铸 operationId |
| 进行 | `pointermove` | `onChange` | `requester.schedule()`,**不 commit** |
| 结束 | `pointerup` | `blur` / `Enter` | `requester.flush()` + `commitGesture()` |
| 放弃 | — | `Escape` | 回滚显示值 + `requester.cancel()` |
`EditSession` 与 `gestureIdentity()` 无需改动。输入 `1.53` 产生一步 undo,而非四步。
滑杆(若实现)的 pointerdown/up 天然落在此表内,不引入新分支。
**保存路径**:`saveDirectEdits()` 必须在入口强制结算未闭合的 gesture。DOM 中 blur 先于 click 触发,直接点"保存"能赶上,但该顺序过于脆弱,不作为正确性依赖。
## 区间的单位分层
父 `design.md` 的坐标分层表规定持久化层只有米与归一化 station。显示层不受该表约束。
| 层 | 单位 |
| --- | --- |
| 持久化 / 传输 | `station` (0..1) |
| 面板显示与输入 | 米(`station × roadLengthMeters`) |
**只在用户实际编辑时换算**,不在每次渲染时做 米→station→米 的往返,否则四舍五入会让数字自行漂移。`roadLengthMeters` 取自 `IntervalRangeHandle`,与 range 手柄同源。
区间由整条道路共享(`rangeDraftFor` 重锚该路全部约束),故在面板中**每条路一行**,不随手柄重复。
## 面板可表达而拖拽不能表达的操作
`value.current` 在无约束时回落基线(外缘偏移基线为 0),因此"未修改"与"显式设为 0"数值完全相同。`handle.constraintId` 仅在约束存在时出现,客户端据此区分。
由此得到一个拖拽结构上无法提供的能力:**删除约束**。拖拽只能设值,不能移除。面板每行提供"重置",删除该约束并使该行回到未修改态。
这是参数面板的实质增量,而非拖拽的镜像显示。
## 渲染性能
`handleDragEvent` 每次 mousemove 触发,而 `App.tsx` 是单个 974 行组件。拖拽值回流面板必须经 rAF 节流,不得直接 `setState`。
节流有效性需在扩大面板规模前验证——手柄当前仅 5~6 个,问题不会自行显现。
## 边界
- 面板不得成为第二套几何算法或第二个值的真相来源。范围、位置、`affects`、可编辑性一律只来自服务端 manifest。
- 面板只呈现主地图拥有的 kind。路口 shape 三 kind 仍属 `JunctionTools`;保留区内手柄呈禁用态并显示 `disabledReason`。
- 不新增约束 kind,不改动求解器。
## 已知缺口
服务端 `applyConstraint` 只校验 `Number.isFinite` 与非负,**不校验 manifest 的 `min`/`max`**。今日范围仅由客户端 `projectHandleValue` 的夹值实际约束。
外缘偏移的范围随道路宽度浮动(`±Math.max(0.1, width * 0.45)`),因此保存时合法的值可能在后续几何变化后越界。此类越界发生在保存之后的求解期,**客户端结构上无法拦截**。
父 `design.md` 已为 `boundaryIndex` 定义同类规则——"重放时若车道数变化导致越界,该约束转 `stale`,不做近似映射"——数值范围越界应同等处理。
属重放正确性,不属本任务;独立成任务。本任务的客户端校验不因该缺口存在而降级:范围在哪定义就在哪拦,并避免一次注定被拒的求解。
## 右侧工作台信息架构(2026-09-01)
右栏是操作面板而非信息流。顶部固定呈现当前选择对象、其道路方向和修改状态;下方
采用单主展开区的手风琴,避免所有表单在初始状态占满地图旁的空间。
| 分段 | 内容 | 展开规则 | 写入语义 |
| --- | --- | --- | --- |
| 道路 | 基础道路覆盖、直接编辑参数 | 选中道路时默认展开 | override 暂存;直接编辑 preview/session |
| 元素 | 车道箭头、标线、信号灯 | 选择相应地图元素时自动展开 | 箭头/标线暂存;信号灯即时 API |
| 连接 | 路口连接、行驶动作、手工候选 | 默认收起 | override 暂存 |
| 高级 | 复杂路口候选、技术 JSON | 始终默认收起 | 候选沿用现有调用 |
每个分段使用受控 React 状态,而非依赖原生 `<details>` 的不可观察状态;这让地图选中
事件可以可靠地展开相应段,且移动端与桌面端保持同一状态模型。分段标题显示摘要
(如参数修改数、所选第几车道、连接数量),但不复制任何几何或约束值。
车道箭头在元素段显示 maneuver 选择、距路口端的米数读数和有限数值输入。数值输入与
拖曳都写同一 `lane-maneuver.placementDistanceMeters`;客户端只限制为有限非负值,控制
设施与端点安全位置仍由正式编译的 `nearestSafeTurnArrowPlacement()` 权威裁决。
为避免继续膨胀 `App.tsx`,右栏容器、对象摘要、手风琴、道路/连接/元素分段应迁入
`workbench/client/src/components/`。现有 `ParameterPanel` 保持其 manifest 值所有权和
DOM 直写性能策略,只作为“道路”分段的内容,不被重写为另一条输入链路。
@@ -0,0 +1,6 @@
{"file":".trellis/spec/frontend/direct-edit-client.md","reason":"面板是第二条输入通道,必须继续遵守 manifest 驱动、baseline 不被写入、预览时序与图层所有权。"}
{"file":".trellis/spec/frontend/state-management.md","reason":"聚焦期本地 draft 与服务端 value.current 的所有权切换是本任务的核心状态规则,不得产生第二个值的真相来源。"}
{"file":".trellis/spec/frontend/component-guidelines.md","reason":"新增参数面板组件需符合既有组件结构与职责边界。"}
{"file":".trellis/spec/frontend/hook-guidelines.md","reason":"拖拽回流的 rAF 节流以 hook 承载,需符合既有 hook 约定。"}
{"file":".trellis/spec/guides/code-reuse-thinking-guide.md","reason":"输入通道必须复用 draftFor / PreviewRequester / EditSession,禁止复制出第二套预览与 undo 链路。"}
{"file":".trellis/tasks/08-26-direct-manipulation-road-editor/design.md","reason":"继承 v2 约束模型、坐标分层、预览时序与 handle manifest 的权威合同。"}
@@ -0,0 +1,97 @@
# 实施计划
顺序按**风险递减**排列:每一步都有可独立验证的门禁,失败即停,不进入下一步。
## 0. 纯逻辑与测试夹具
- 在 `workbench/client/src/edit/` 新增参数值的纯逻辑:数值格式化/解析(保留 `1.`、`-`、空串中间态)、范围校验、`station ↔ 米` 换算。
- 与现有 `meters.ts` / `projection.ts` / `selection.ts` 同侧,**不得 import OpenLayers**。
- 失败优先的 vitest:越界判定的边界值、中间态解析不丢字符、米↔station 往返不漂移。
- 门禁:新增模块的单测在 node 下跑通,且 `grep -r "from 'ol" ` 对新文件无命中。
## 1. 面板只读渲染
- 新增面板组件,遍历 `editHandles` 渲染:中文名、`value.current`、单位、`[min, max]`。**此步不可编辑。**
- 多个 `road-lane-divider` 按 `boundaryIndex` 分行;不可编辑手柄呈禁用态并显示 `disabledReason`。
- 依 `handle.constraintId` 是否存在标记"已修改"。
- 区间每条路一行,以米显示。
- 验证:选中不同道路、选中含保留区的道路、选中多车道道路,面板结构正确。
- 门禁:`directEdit` 开关关闭时面板不渲染、不请求 manifest,网络轨迹与 main 一致。
## 2. 拖拽 → 面板回流
- 拖拽值**直接写 DOM 节点**(ref + `textContent` / `value`),不经 React 渲染。
`direct-edit-client.md` §7:rAF 合并是**最低要求**,"写到源头"才是生产规则;ghost 直接写 OL source,面板的等价物是直接写 DOM。
- **禁止**在 `handleDragEvent` 中 `setState`;gesture 结束时才做一次 state 对账。
- 禁止在 `setState` updater 内计算或读 OL 状态(§6)。
- 验证:拖拽过程中面板数值实时跟随;用 render 计数确认**面板未新增任何渲染**。
注意门禁不是"拖拽期间渲染 0 次"——`onSettled` 的 `setManifest` 本就会在拖拽中随防抖预览触发渲染,那是服务端权威预览的固有代价,改动前就存在。要证明的是 `pointermove` 自身不再产生渲染。
- 拖拽中落地的预览会把 manifest 换成滞后一个防抖周期的值,需保证数字不在两者间闪烁。
- 门禁:节流有效性必须在此步证明。手柄当前仅 5~6 个,问题不会自行显现;跳过则后续无从归因。
## 3. 输入通道:预览、gesture 边界、commit
- 输入框接入 `draftFor` → `PreviewRequester.schedule()`,复用 80ms 防抖与 `previewSeq` 仲裁。
- gesture 边界按 `design.md` 表实现:`focus` 铸 operationId,`onChange` 只预览,`blur` / `Enter` 走 `flush()` + `commitGesture()`,`Escape` 回滚 + `cancel()`。
- 聚焦期间显示本地文本 draft,失焦后跟随 `value.current`。
- **`EditSession` 与 `gestureIdentity()` 不得修改**;若发现需要改,说明边界映射错了,退回重审。
- 验证:输入框改值与拖到同一数值产出同形约束;输入 `1.53` 后一次 Ctrl+Z 回到修改前;键入 `1.` 期间到达的预览响应不改写输入框。
- 门禁:一次非空表单编辑可在正式重编译结果中观察到几何变化。只交付 UI 不算通过。
## 4. 范围拒绝与极值填入
- 越界输入:标红、**不发预览请求**、不进 undo 栈、保留最后一个有效预览。
- 拖拽与滑杆的夹值行为保持不变(`projectHandleValue` 不改)。
- 范围提示中的极值可点击填入。
- 验证:越界时网络面板无新请求;blur 后无新 undo 步骤;点击极值可正常提交;拖拽越界时手柄仍停在极限。
- 门禁:夹值与拒绝的差异必须体现为 `design.md` 中的同一条不变量,不得实现成两条并列策略。
## 5. 重置与区间换算
- 每行"重置"删除该约束,使该行回到未修改态(`constraintId` 消失、值回落基线)。
- 区间的米↔station 换算实现并单测;**区间行受 `intervalEditingSupported` 门控,当前为 `false` 故不渲染**。
理由与 range 手柄一致(`flag.ts:46`):`compileGeometry()` 不读 `profile.interval`,一个改了没效果的输入框比没有更糟。
换算只在用户实际编辑时进行,渲染路径不做米→station→米 往返。
- 验证:重置后保存重编译,该参数回到基线;换算函数往返无累积漂移;开关为 `false` 时面板不出现区间行。
## 6. 加固与手测
- `saveDirectEdits()` 入口强制结算未闭合 gesture,不依赖 blur/click 顺序。
- 手测清单:
- 输入未失焦直接点"保存",修改被正确持久化。
- 拖拽与输入交替操作,undo/redo 序列正确。
- 快速连续输入,乱序预览响应不覆盖较新结果。
- 切换选中道路时未闭合的输入被正确结算或放弃。
- OpenLayers `Map` 未被重建,仅受影响 source 被替换。
- 门禁:交付前 `directEdit` 开关行为与改动前一致。
## 验证命令
```sh
npm run format:check
npm run test
npm run test:client
npm run test:client:unit
npm run build
```
## 风险文件
- `workbench/client/src/App.tsx`:974 行单组件。面板 state 与拖拽回流都落在此处,是重渲染风险的集中点;必要时先抽出编辑状态再加面板。
- `workbench/client/src/edit/session.ts`:**不应修改**。若实现中需要改动,说明 gesture 边界映射有误。
- `workbench/client/src/edit/projection.ts`:`projectHandleValue` 的夹值是拖拽正确性的一部分(见其 75 行注释),不得为"统一行为"而移除。
- `workbench/client/src/edit/preview-request.ts`:防抖与 `previewSeq` 仲裁由两条通道共用,任何改动同时影响拖拽。
- `src/compile/direct-edit-solver.js`:**本任务不改**。若发现必须改,先确认不是把服务端校验缺口混进了本任务范围。
## 右侧工作台扩展(2026-09-01)
1. 抽出受控手风琴和选择对象摘要组件,建立“道路 / 元素 / 连接 / 高级”四段及其
自动展开规则;先用静态现有内容验证不改变写入行为。
2. 将现有 `Inspector` 的道路覆盖、连接、候选和技术详情迁入对应分段;将标线、箭头、
信号迁入元素分段。保留 `ParameterPanel` 的 API 和直接编辑数据流。
3. 补充箭头位置的米数读数和精确输入,与拖曳使用同一 staged override;输入非法值不暂存。
4. 用组件/纯逻辑单测覆盖自动展开、分段摘要、箭头位置写入和不同写入语义;手测桌面及
窄屏的空间、焦点和滚动。
5. 执行 `npm run format:check`、`npm run test`、`npm run test:client`、
`npm run test:client:unit`、`npm run build`,并验证选箭头、标线、信号、道路与连接的
现有保存流程未回归。
@@ -0,0 +1,118 @@
# 参数面板与数值双向绑定
## 目标
给直接编辑加一个参数面板:选中道路后,每个可编辑参数以数值形式呈现,既能读到地图拖拽的实时结果,也能直接输入数值驱动几何。两条输入通道写同一份结构化约束,共用同一条预览、保存、撤销链路。
地图直接操纵**保留**,不被替换。面板是第二个平等的输入通道,不是拖拽的只读显示器。
## 已确认的事实
以下均为读代码核实,不是推断:
- `App.tsx:206` 的 `draftFor(handle, value)` 已经是纯函数 `(手柄, 数字) → 草稿`。拖拽只是产生这个数字的一种方式;输入框可以复用同一个入口。
- `EditHandle.value` 是 `{ current, min, max, unit: 'meter' }`——**取值范围服务端早已下发**,客户端不需要新增来源。
- `direct-edit-solver.js:136` 的 `numericValue(constraint, key, fallback)` 直接从约束读值,无约束时回落基线。**服务端从不改写用户输入的数字**;值非法时发阻塞诊断(`direct-edit-invalid-value`)拒绝,不做静默替换。因此不存在"请求值 vs 求解值"两个数字。
- `App.tsx:197` 每次预览结算都 `setManifest(response.handles)` 整体替换 manifest,`value.current` 随之刷新。受控输入若直接绑定它,输入中间态(`1.`、`-`、空串)会被冲掉。
- `projection.ts:60` 的 `projectHandleValue` 把拖拽值夹到 `[min, max]`,`ghost.show()` 与 `handlePositionFor()` 都按夹后的值绘制。拖拽越界时手柄停在极限、光标继续移动。
- 服务端 `applyConstraint`(`direct-edit-solver.js:302/312/322` 附近)只校验 `Number.isFinite` 与非负,**未校验 manifest 的 `min`/`max`**。范围目前是纯客户端概念。
- 外缘偏移的范围随道路宽度浮动(`±Math.max(0.1, width * 0.45)`);步行带固定 `0..8`;角部圆角固定 `0.5..30`。
- `gestureIdentity()` 懒创建 operationId,`commitGesture()` 释放它。一次 gesture = `EditSession.commit()` 一次 = 一步 undo。该机制与指针无绑定关系。
- `handle.constraintId` 仅在约束存在时出现,因此客户端能区分"未修改(基线回落)"与"显式设为该值"。
- 区间由整条道路共享:`rangeDraftFor` 会把该路上所有约束一起重锚。`IntervalRangeHandle` 同时携带 `station` 与 `roadLengthMeters`。
- 同一条路可有多个 `road-lane-divider` 手柄,靠 `boundaryIndex` 区分。
- `direct-edit-solver.js` 写 `profile.interval`(290、472 行),但 `compileGeometry()` 不读它——`native-road.js` 中 `interval` 的唯一命中是方向箭头间距,与此无关。**每次直接编辑实际作用于整条道路。** 因此 `flag.ts:46` 的 `intervalEditingSupported` 为 `false`,range 手柄被隐藏。
- 当前**没有任何参数面板**。与手柄相关的 UI 仅 `App.tsx:404` 状态栏一句 `手柄 ${n} 个`。
- `handleDragEvent` 每次 mousemove 触发;`App.tsx` 是单个 974 行组件。
## 范围
### 1. 面板与读取
1. 选中道路后,面板按手柄列出可编辑参数:中文名、当前值、单位、合法范围。
2. 多个 `road-lane-divider` 分别成行,用 `boundaryIndex` 标识,不按 kind 去重。
3. 影响区间**每条路一行**(不是每个手柄一行),以米显示,`station` 仍是唯一存储真相。
**受 `intervalEditingSupported` 门控**:该开关当前为 `false`,故本任务不渲染区间行。
换算与显示逻辑仍按第 5 节实现并单测,随开关翻转一并生效。
4. 每行标记该参数是否已被显式修改(依据 `handle.constraintId` 是否存在)。
5. 不可编辑手柄(落在路口保留区)在面板中呈禁用态并显示 `disabledReason`。
### 2. 拖拽 → 数字
6. 拖拽过程中面板数值实时跟随,与地图 ghost 同步。
7. 高频更新经 rAF 节流,不得每次 mousemove 触发整个 App 重渲染。
### 3. 数字 → 图形
8. 输入框修改值时走与拖拽相同的 `draftFor` → `PreviewRequester` 链路,含 80ms 防抖与 `previewSeq` 仲裁。
9. gesture 边界:`focus` 对应 `pointerdown`(铸 operationId),`blur` / `Enter` 对应 `pointerup`(`commitGesture`)。输入 `1.53` 只产生**一步** undo。
10. `Escape` 回滚到上一个有效值并 `cancel()` 在途请求。
11. 聚焦期间输入框显示本地文本,失焦后跟随 `value.current`。中间态不被预览响应冲掉。
12. `saveDirectEdits()` 入口先强制结算未闭合的 gesture,不依赖 blur 与 click 的触发顺序。
### 4. 范围处理
13. 拖拽与滑杆维持夹值(`projectHandleValue` 不变)。
14. 数值输入**不夹值**:越界时标记非法、不发预览、不进 undo 栈,保留最后一个有效预览。
15. 范围提示中的极值可一键填入。
### 5. 重置
16. 每行提供"重置",删除该约束回到基线。这是拖拽无法表达的操作——拖拽只能设值,不能移除约束。
## 明确不做
- 不移除、不削弱地图上的拖拽手柄。
- 不新增约束 kind,不改动求解器几何逻辑。
- 不补服务端 `min`/`max` 校验(见「已知缺口」,另立任务)。
- 不做参数的批量编辑、复制粘贴、跨道路应用。
- 不动 `JunctionTools` 的所有权边界;面板只呈现主地图拥有的 kind。
- 不同步遗留 `workbench/client/app.js`。
## 验收标准
- [ ] 选中道路后面板列出全部可编辑参数;多条车道分隔各自成行且可独立修改。
- [ ] 拖拽手柄时面板数值实时跟随;拖拽期间 React 重渲染次数经 rAF 收敛(非每 mousemove 一次)。
- [ ] 输入框改值后地图预览更新,与拖到同一数值的结果一致。
- [ ] 输入 `1.53` 后按 Ctrl+Z **一次**即回到修改前状态。
- [ ] 输入过程中(如已键入 `1.`)到达的预览响应不会改写输入框内容。
- [ ] 输入越界值:字段标红、不发预览请求(可由网络面板证明)、保留上一个有效预览、blur 后不产生 undo 步骤。
- [ ] 点击范围提示中的极值可一键填入并正常提交。
- [ ] 拖拽越界时手柄停在极限位置,行为与改动前一致。
- [ ] 未修改参数与显式设为基线值的参数在面板上可区分;"重置"能删除约束并使该行回到未修改态。
- [ ] 影响区间的米↔station 换算函数经单测覆盖,往返无累积漂移。(区间行本身受 `intervalEditingSupported` 门控,当前不渲染。)
- [ ] 输入未失焦时直接点"保存",该次修改被正确持久化。
- [ ] 路口保留区内的手柄在面板中禁用并显示原因。
- [ ] `npm run format:check`、`npm run test`、`npm run test:client`、`npm run test:client:unit`、`npm run build` 全绿。
## 风险与门槛
- 面板不得成为第二套几何或第二个值的真相来源。所有范围、位置、影响对象仍只来自服务端 manifest。
- `value.current` 是**请求值的回显**而非求解值。若后续 solver 改成回写求解结果,第 11 条的显示规则失效,必须同步重审。
- 外缘偏移的 `min`/`max` 随道路宽度浮动,因此"当前合法"不等于"永远合法"。客户端校验只能覆盖输入当下。
- 拖拽回流若实现为直接 `setState`,会逐帧重渲染 974 行的 `App`。必须先确认节流有效再扩大面板规模。
## 已知缺口(不在本任务内)
服务端只校验 finite/非负,不校验 manifest 的 `min`/`max`;而外缘偏移范围随道路宽度浮动,意味着保存时合法的值可能在几何变化后越界。这类越界**客户端结构上无法拦截**——它发生在保存之后的求解期。
`design.md` 已为 `boundaryIndex` 定义了同类规则("重放时若车道数变化导致越界,该约束转 `stale`"),数值范围越界应当同等处理。属重放正确性,独立成任务。
## 右侧工作台扩展(2026-09-01)
当前右侧栏将道路基础覆盖、直接编辑参数、路口连接、车道转向箭头、标线样式、
原生信号灯、复杂路口候选和技术 JSON 直接按顺序堆叠,缺少所选对象摘要、明确的
编辑上下文和一致的表单层级。用户确认本轮应覆盖全部既有编辑器,而非只处理道路
参数或车道箭头。
拟纳入范围:
- 统一右侧栏的对象摘要、未保存/即时保存状态和表单布局。
- 重新组织道路、元素、连接、调试/技术详情中的全部既有表单与信息展示。
- 为车道转向箭头补足距路口位置的可读数与精确输入,继续复用
`placementDistanceMeters` 覆盖和既有拖曳行为。
- 保持各写入语义:普通 override 继续暂存并经保存/重新生成生效;信号灯继续走
现有即时 API;直接编辑继续走 manifest/preview/session 链路。
已决 UX:右栏使用手风琴式可折叠分段,以控制地图工作台中的垂直空间占用。
所选地图元素的关联编辑段自动展开;调试与技术详情默认收起。
@@ -0,0 +1,108 @@
# manifest 范围与求解器可行域不一致
日期:2026-08-31
来源:`08-31-parameter-panel-binding` 实施期间对运行中工作台(`osm-KZZP9U`)的实测。
## 现象
手柄 `handle:road-edge-offset:segment:way/-3246/0:left`,manifest 声明
`value.min = -2.925`、`value.max = 2.925`(即 `±width * 0.45`,道路宽 6.5m)。
逐值探测 `POST /api/edit-preview`:
| offsetMeters | 阻塞诊断 |
| --- | --- |
| -2.90 | `direct-edit-outer-edges-cross` |
| -2.00 | `direct-edit-outer-edges-cross` |
| -1.00 | `direct-edit-outer-edges-cross` |
| **-0.50** | **(无)** |
| **0.00** | **(无)** |
| **0.50** | **(无)** |
| **1.00** | **(无)** |
| 2.00 | `direct-edit-outer-edges-cross` |
| 2.90 | `direct-edit-outer-edges-cross` |
| 500 | `direct-edit-outer-edges-cross` |
探针构造已排除误报:小幅值干净,说明请求本身合法。
## 结论
**manifest 宣告的范围比求解器实际接受的可行域宽约 3 倍,且双向都是。**
真实边界落在 `(-1.0, -0.5]` 与 `[1.0, 2.0)` 之间,未进一步二分。
失败原因未查明。`direct-edit-outer-edges-cross` 对应 design.md 的
「同一站点左右外缘不得交叉」不变量,但仅移动**单侧**外缘 1m
(6.5m 宽的路)为何会触发交叉,需要读 `compileGeometry()` 才能确定——
可能经由车道最小宽度 2.4m 派生,也可能诊断名不完全对应其实际判据。
## 与既有行为的关系
这不是本任务引入的。拖拽一直夹到 `±2.925`,所以用户一直能拖进被拒区间——
拖过约 1m 后几何冻结、诊断出现,而手柄继续走到 2.925。
按 design.md「无效草稿不替换最后一个有效预览」,这是既定行为。
参数面板没有改变它,但**把它变可见了**:范围以文字打印,且极值可一键填入。
点击极值会得到一个必被服务端拒绝的值。
## 处理
未在本任务修改。理由:
- 客户端范围校验必须用 manifest 的 `min`/`max`,用别的就是发明第二个真相来源
(`direct-edit-client.md` §2)。
- 收窄范围需要求解器解析地算出外缘交叉的可行区间,属求解器工作,
本任务明确排除。
- 点击极值的结果是一个诚实的服务端拒绝:诊断可见、最后一个有效预览保留、可撤销。
不是静默破坏。
已并入 `08-31-constraint-range-validation` 的需求。
---
# 追加:`junction-crosswalk-inset` 的静默死区
日期:2026-08-31,区域 `nantaizihu-9PTsZg`。
手柄 `handle:junction-crosswalk-inset:node/1140799725:segment:way/-3246/0`
声明 `value.min = 0`、`value.max = 8`。逐值提交预览并测量该组 6 条斑马线的中心位移:
| inset | 相对 inset=0 的位移 | 增量 |
| --- | --- | --- |
| 0 | 0.00 | — |
| 0.5 | 0.50 | +0.50 |
| 1.0 | 1.00 | +0.50 |
| 2.0 | 2.00 | +0.50 |
| 3.0 | 3.00 | +0.50 |
| 4.0 | 3.20 | +0.20 |
| 5.0 | 3.20 | **+0.00** |
| 6.0 | 3.20 | **+0.00** |
| 8.0 | 3.20 | **+0.00** |
`0 → 3.2` 是干净的 1:1 线性响应;`3.2 → 8` **完全无响应,且无任何诊断**。
## 成因
`crossingJunctionInset()`(`native-road.js:1325`):
```js
const targetDistance = Math.max(0, plan.cutbackMeters - inset);
return Math.min(CROSSWALK_MAX_JUNCTION_INSET_METERS,
Math.max(0, candidate.junctionDistanceMeters - targetDistance));
```
inset 增至 `plan.cutbackMeters` 后 `targetDistance` 触底为 0,再增无效;
外层 `CROSSWALK_MAX_JUNCTION_INSET_METERS = 4` 另有封顶。
因此有效上界是 `min(cutbackMeters, …)` 的某个函数,**逐进口不同**,
而 manifest 对所有进口一律发布固定的 `max: 8`。
## 为何比外缘偏移那例更严重
外缘偏移越界会返回阻塞诊断——用户看得到"不行"。
本例越界**什么都不发生**:拖动手柄,几何纹丝不动,没有诊断、没有提示。
与「控件坏了」无法区分。
这正是 `flag.ts` 为 `profile.interval` 立下的规矩所要避免的
(「一个拖了没效果的控件比没有控件更糟」),区别只在于它发生在量程的上半段,
而不是整个控件。
若用户在已处于死区的进口上首次尝试拖拽,得到的印象就是"直接编辑不工作"。
@@ -0,0 +1,26 @@
{
"id": "parameter-panel-binding",
"name": "parameter-panel-binding",
"title": "参数面板与数值双向绑定",
"description": "为直接编辑加参数面板:数值输入与地图拖拽双向绑定,共用同一条约束/预览/undo 链路",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-08-31",
"completedAt": "2026-09-03",
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": "08-26-direct-manipulation-road-editor",
"relatedFiles": [],
"notes": "",
"meta": {}
}
@@ -0,0 +1,2 @@
{"file": ".trellis/spec/frontend/direct-edit-client.md", "reason": "Check no baseline writes, per-pointermove React churn, or accidental rotation path."}
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Check position serialization, validation, and recompile behavior across layers."}
@@ -0,0 +1,28 @@
# Design: Lane Maneuver Position Drag
## Selection And Gesture
The selected arrow group remains one logical target: `lane_id + maneuver`. A new
display-only selection layer will become the drag hit target, while its members are
never moved independently. Pointer coordinates are projected onto the lane centerline
and converted to a distance from the lane's junction end, matching the compiler's
`placement_distance_meters` convention.
## Contract
The existing `lane-maneuver` override gains optional finite, non-negative
`placementDistanceMeters`, measured from the lane's junction end. The compiler uses
it when present, otherwise keeps its current candidate-placement algorithm
byte-for-byte. Maneuver and position are updated together by lane id so an old
maneuver override cannot shadow a newer position entry.
## Validation And Preview
The server remains authoritative for collision checks and final geometry. The client
may project and clamp the ghost for responsive feedback, but it must submit the
position through the existing save/recompile boundary and never mutate baseline
GeoJSON. The candidate position must clear control features and leave the compiler's
endpoint safety buffer.
Rotation is intentionally absent from the contract; adding it later must not require
reinterpretation of the position field.
@@ -0,0 +1,2 @@
{"file": ".trellis/spec/frontend/direct-edit-client.md", "reason": "Reuse the existing projection, ghost, baseline ownership, and save-boundary rules for a new lane-arrow gesture."}
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "Trace the new position field from UI through override validation and compiler placement."}
@@ -0,0 +1,14 @@
# Implementation Plan
1. Resolve invalid-position behavior and freeze the wire field name/units in the PRD.
2. Add compiler validation and placement override handling with empty-override parity tests.
3. Add a lane-arrow drag interaction that projects along the lane and moves the complete part group.
4. Add authoritative save/recompile wiring and focused client/server regression tests.
5. Run format, server tests, client type/unit tests, and production build; manually verify
an existing and a newly-added arrow in the workbench.
## Explicit Non-Goals
- Arrow rotation or arbitrary lateral movement.
- Position editing for `native-road-direction-arrow/v1`.
- Per-part dragging or a second undo/preview protocol.
@@ -0,0 +1,59 @@
# 车道转向箭头位置拖曳
## Goal
TBD.
## Requirements
- TBD
## Acceptance Criteria
- [ ] TBD
## 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`.
# 车道转向箭头位置拖曳
## 目标
让用户可以把一个完整的路口转向箭头沿所属车道拖到新的位置。箭头的 polygon
part 必须整体平移,内部形状、part 顺序和 `maneuver` 不变;旋转和箭头内容修改
不属于本任务。
## 已确认事实
- 一个视觉箭头由同一 `lane_id + maneuver` 下的 3 或 5 个 polygon part 组成,点击
任一 part 已能选中整组。
- 编译器目前以 `placement_distance_meters` 记录箭头距路口端的距离,并在 6/10/14/18/22m
候选位置中避开斑马线和停止线。该字段目前是输出值,还没有 override 合同。
- 车道中心线已作为无箭头车道的选择入口;位置拖曳必须同时适用于已有箭头和刚新增的箭头。
- 现有 v2 拖曳链路按车道轴投影、以服务端预览为准;箭头位置属于新的离散/连续混合
override,不能伪装成道路宽度或路口偏移 constraint。
## 范围
1. 拖曳完整 `lane_id + maneuver` 箭头组,保持 part 相对几何不变。
2. 将拖曳位置保存为 `lane-maneuver.placementDistanceMeters`(从车道驶入路口端量起的米数),
并在保存/重新生成后由编译器读取。
3. 位置必须沿车道中心线投影,不能改变横向位置;不能越过车道有效端点或与斑马线、停止线重叠。
4. 已有的 maneuver 下拉框继续有效;旋转手柄、角度字段和沿路 `directionArrows` 不在范围内。
## 验收标准
- [ ] 拖曳任一箭头 part 会整体移动同组所有 part,不拆散、不改变形状和旋转。
- [ ] 拖曳释放时位置按车道轴投影并受有效范围约束;服务端正式编译输出的
`placement_distance_meters` 反映新位置。
- [ ] 新增箭头后也能拖曳其位置;刷新或重新编译不会回到旧位置。
- [ ] 箭头不能落在斑马线/停止线范围内,也不能超出车道安全端点。
- [ ] 未设置位置覆盖时,输出与现有编译结果字节一致。
- [ ] 旋转、沿路重复方向箭头和既有 v2 控件行为不回归。
## 关键决策
当用户把箭头拖向无效区域(控制设施或安全端点)时,连续夹紧到最近合法位置,
并在拖动过程中让完整箭头组停在该位置。这个行为与现有 v2 数值拖曳一致。
@@ -0,0 +1,26 @@
{
"id": "lane-maneuver-position-drag",
"name": "lane-maneuver-position-drag",
"title": "车道转向箭头位置拖曳",
"description": "",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-09-01",
"completedAt": "2026-09-03",
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": null,
"relatedFiles": [],
"notes": "",
"meta": {}
}
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,3 @@
# Design
新增纯逻辑 descriptor/状态模型和独立热点图层 adapter;输入只读编译状态,输出 `JunctionRef`,不写 active document。
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,21 @@
# Implementation
先为 node/cluster/candidate 派生逻辑加单测,再接 MapCanvas 热区渲染和点击路由;验证与现有道路/设施命中隔离。
# Implementation
1. Add a pure descriptor model deriving editable node, readonly configured cluster,
and candidate cluster hotspots from the compiled state.
2. Add a dedicated OpenLayers hotspot layer with visibility control and isolated
click handling that returns a stable `JunctionRef`.
3. Add unit coverage for descriptor stability and node/cluster/candidate status.
## Progress
- [x] Pure descriptor model and stable `JunctionRef`
- [x] Dedicated hotspot layer and map click adapter
- [x] Client type-check, unit tests, format check, and production build
## Deferred
- Independent JunctionTools route and session lifecycle belong to the workspace
child task and are intentionally not implemented here.
@@ -0,0 +1,20 @@
# 路口识别与热区模型
## Goal
从编译模型派生普通 node、已确认 cluster 和 candidate cluster 的路口描述与可点击热区。
## Requirements
- 热区不新增持久化几何事实;来源必须是 junction plan、cluster 配置和诊断。
- 普通 node 可进入编辑;已确认 cluster 显示 cluster 级热区;candidate 明确显示待确认状态。
- 热区点击必须返回稳定 `JunctionRef` 和地图位置,不与道路/设施选择竞争。
- 热区范围覆盖路口核心及必要的进口上下文,并可解释其来源。
- 普通 node 热区可进入编辑;已确认 cluster 热区只读;candidate cluster 热区只展示状态、组成道路和诊断。
- 本任务不得提供 candidate 确认或 cluster 持久化创建动作。
## Acceptance Criteria
- [ ] 同一编译状态下热区与 junction descriptor 一致且稳定。
- [ ] node、cluster、candidate 的状态和点击行为有纯逻辑测试。
- [ ] 热区图层开关、选中态和空白点击行为不破坏现有地图。
@@ -0,0 +1,26 @@
{
"id": "junction-detection-hotspot",
"name": "junction-detection-hotspot",
"title": "路口识别与热区模型",
"description": "",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-09-02",
"completedAt": "2026-09-03",
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": "08-26-direct-edit-junction-tools",
"relatedFiles": [],
"notes": "",
"meta": {}
}
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,3 @@
# Design
设施层只保存现有语义文档;JunctionTools 汇总设施约束、受影响图层和阻塞诊断,发布前复用导出契约校验。
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,14 @@
# Implementation
接入斑马线/停止线/信号灯联动与诊断,再补保存、取消、撤销/重做、导出回归;所有产品改动等待用户复核后提交。
## Progress
- [x] 工作区展示已有斑马线、停止线、信号灯数量
- [x] 汇总路口关联诊断并区分阻塞/提示
- [x] 客户端类型检查、单元测试、格式检查和生产构建
- [x] 全量服务端与工作台集成测试
## Deferred
- 设施的创建、删除和独立位置编辑仍按已决边界留给后续任务;本阶段只做已有设施的上下文展示与验证摘要。
@@ -0,0 +1,20 @@
# 路口设施与验证闭环
## Goal
在 JunctionTools 中协调斑马线、停止线、信号灯及发布前诊断,形成可复核的路口交付闭环。
## Requirements
- 设施编辑复用现有元素语义和交通信号文档,不复制 GeoJSON。
- 设施必须受所属进口/路口几何约束,越界时给出结构化诊断。
- 发布前展示受影响对象、阻塞问题、文档版本和导出契约状态。
- 保存、取消、撤销/重做和导出行为与主地图保持一致。
- 首期只允许修改已有斑马线、停止线和信号灯的语义位置或参数,不允许创建或删除设施。
- 自交、越界和几何不可解为 `blocking`;设施缺失或间距不足等非致命问题可为 `warning`,UI 依赖稳定诊断 code/severity。
## Acceptance Criteria
- [ ] 设施联动 preview 包含斑马线、停止线和信号灯派生对象。
- [ ] 非法设施位置不会替换最后有效预览。
- [ ] 保存后导出包契约不变,完整回归测试通过。
@@ -0,0 +1,26 @@
{
"id": "junction-facilities-validation",
"name": "junction-facilities-validation",
"title": "路口设施与验证闭环",
"description": "",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-09-02",
"completedAt": "2026-09-03",
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": "08-26-direct-edit-junction-tools",
"relatedFiles": [],
"notes": "",
"meta": {}
}
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,3 @@
# Design
建立 node/cluster 共用的 effective junction plan;solver 是唯一语义来源,`complex-junction.js` 只消费求解结果并生成派生图层。
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,13 @@
# Implementation
先统一锚点和计划,再逐项接宽度、cutback、圆角,最后验证完整 preview、失败保留和正式编译一致性。
## Progress
- [x] 统一输出 `effectiveJunctionPlans`
- [x] 普通 node 输出可写计划,cluster 输出聚合只读计划
- [x] 编译入口透传 junction template,上层 solver 单测覆盖
- [x] 工作区三项几何控件接入 ParameterPanel,共享 preview/apply/save 回调(普通 node)
- [x] 失败拟合、乱序预览和正式编译一致性 E2E
预览请求层已有失败保留、乱序丢弃的单元回归;本轮补充服务端工作流回归,验证真实路口进口宽度从预览到保存再到正式编译发布的几何一致性。
@@ -0,0 +1,20 @@
# 路口几何与拓扑编辑
## Goal
让 node/cluster 的路口编辑约束由同一套 effective plan 驱动,避免参数和复杂路口几何脱节。
## Requirements
- 统一进口宽度、cutback、角部圆角的 node/cluster 锚点和求解输入。
- 预览覆盖道路面、路口面、步行带、车道中心线、connector/movement 和控制设施。
- 最小车道宽度、边界连续、自交和 connector 越界必须阻塞并保留最后有效预览。
- cluster 不得被静默拆成多个 node 编辑。
- 阶段 B 仅允许普通 node 写入三项既有约束;cluster 仅验证只读 effective plan,不开放写入。
- 车道和 connector 在本阶段作为预览、诊断和影响对象展示,不提供拓扑创建、删除或重连。
## Acceptance Criteria
- [ ] 三类约束在 node 和已确认 cluster 上均有可验证的 effective plan。
- [ ] 乱序 preview、失败拟合和保存重编译有测试。
- [ ] 同一约束集的 preview 与正式编译结果一致。
@@ -0,0 +1,26 @@
{
"id": "junction-geometry-editor",
"name": "junction-geometry-editor",
"title": "路口几何与拓扑编辑",
"description": "",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-09-02",
"completedAt": "2026-09-03",
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": "08-26-direct-edit-junction-tools",
"relatedFiles": [],
"notes": "",
"meta": {}
}
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,3 @@
# Design
以现有编译模型、RoadRunner 可观察工作流和父任务约束为证据源,产出术语表、能力矩阵、阶段边界和验收映射;不引入代码依赖。
@@ -0,0 +1 @@
{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,3 @@
# Implementation
整理官方/公开资料与仓库证据,记录事实、推断和未知;评审通过后再冻结父任务 PRD,不启动产品代码。
@@ -0,0 +1,23 @@
# 路口需求与RoadRunner能力调研
## Goal
建立 RoadRunner Junction 对标与本项目需求基线,明确用户流程、术语、约束和阶段边界。
## Requirements
- 区分 RoadRunner 可观察能力、不可验证的内部实现和本项目必须自研的部分。
- 定义 node、cluster、candidate、hotspot、JunctionRef、session 的统一术语。
- 输出阶段 A-D 的范围、风险和验收标准。
## Acceptance Criteria
- [ ] 需求文档包含用户流程、约束、不做项和可观察验收。
- [ ] 所有 RoadRunner 对标结论标注证据或推断来源。
- [ ] 父任务和后续子任务可直接引用该基线。
## 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`.
@@ -0,0 +1,26 @@
{
"id": "junction-requirements-research",
"name": "junction-requirements-research",
"title": "路口需求与RoadRunner能力调研",
"description": "",
"status": "completed",
"dev_type": null,
"scope": null,
"package": null,
"priority": "P2",
"creator": "dingkang",
"assignee": "dingkang",
"createdAt": "2026-09-02",
"completedAt": "2026-09-03",
"branch": null,
"base_branch": "main",
"worktree_path": null,
"commit": null,
"pr_url": null,
"subtasks": [],
"children": [],
"parent": "08-26-direct-edit-junction-tools",
"relatedFiles": [],
"notes": "",
"meta": {}
}
Loaded 100 of 372 files, more files were not shown because too many files have changed in this diff. Show more