主题
演进指南
这个仓库从原型长到 7 万多行，从没停下来做过"大重写"，代码却始终没有烂掉。靠的是一套轮次机制：把大改动切成可验证的小步，每步有机器门禁兜底，不做的决定也记录在案。这一页讲机制怎么运转、历史怎么查、以及下一步往哪走——想知道"代码为什么长这样"和"现在该认领什么"，从这里进。
治理轮机制
一轮治理的标准闭环长这样：
三个设计点值得点破。审计先行：先摸清全部现状再动手，重复面要区分"逐字重复"（可以直接合并）和"语义相同"（要备案是否收编）。等价证据：重构不动行为的承诺不靠自觉，靠 DOM 字节级比对、求值对账、像素基线这类机器证据。备案文化：被否决的方案也记录在案并说明理由，半年后有人再提同样的想法，翻备案就知道为什么当时不做——省掉一轮重复论证。
编号线：四条轮次线索
| 编号线 | 内容 | 记账处 |
|---|---|---|
| M 轮（M0–M6） | 功能里程碑：基线搭建、像素校准、GISSDK 集成、动态交互、双文档架构 | docs/notes/roadmap.md（编年体历史 + 文末索引节） |
| E 轮（E1–E6） | 表达式内核 AST 化：注册表、typecheck、会话、构建器 UI | roadmap + design/ |
| R 轮（R1–R7+） | 架构治理轮：分层归位、门禁补强、响应式迁移、减法 | editor/docs/refactor/REFACTOR-CHANGELOG.md |
| 接力轮 | 像素复刻接力 + UI 修复批（已收口，历史在 git） | roadmap 索引 |
分工原则：roadmap 只做索引，轮次明细由 CHANGELOG 承载，避免一份台账两处维护。
REFACTOR-CHANGELOG 怎么读
editor/docs/refactor/REFACTOR-CHANGELOG.md 是重构明细的唯一出处，按时间正序排列——想看最新进展直接翻到文末，每一轮一个章节，标题带日期和轮号（如"压缩收口轮（2026-10-11）"）。读的时候抓三样东西：
- 门禁终态数字：每轮收口都记录测试数、覆盖率、e2e 结论，这是下一轮的基线。
- 事故与教训：不少章节记着"e2e 门禁拦截的重构回归"，这些是门禁体系为什么长成这样的原因。
- 销账记录：风险台账（DEVELOPMENT-GUIDE §5 的 RK-xx）和迁移台账的条目在哪里轮次解决，明细都指回这里。
注意这份文档是给"延续性维护"看的内部台账，行文保留了工作记录的味道；人类读者以本站为入口，需要细节时再跳过去查。
门禁矩阵是安全网
持续重构敢做，前提是红线全部机器化，人来评审的只剩取舍。当前的安全网：
tests/architecture.test.ts：依赖方向、订阅纪律、import 图无环；tests/app/spec-coverage.test.ts：以 style-spec 包为真源逐项对账；map-capabilities对账、模板 imports 守卫、ng-content 条件包含断言；- e2e fixture 冻结装载、中文视觉基线、生产冒烟。
一条红线一旦写成测试，就不再依赖评审记忆。门禁清单与阈值的权威在测试策略。
当前进行时：简化重构
editor/docs/refactor/SIMPLIFICATION-PLAN.md（2026-10-16 全量读码体检）是现役的简化重构评估。它的判断是：架构骨架健康（四层分层、Signals store、单一数据源都执行到位），问题是"长胖了没瘦身"——集中在几个巨型文件、shared 层角色混杂、复制粘贴的守卫代码。
本轮已落地（低风险移动 + 单源化）
- StyleDiff 类型与 diff 纯函数移到
core/map/style-diff.ts，斩断了唯一的 core 级模块环（style-store ↔ map 子树互相依赖）。 - style-store 尾部约 700 行底图交付纯函数移到
core/config/basemap-delivery.ts，style-store 从 2851 行瘦到约 2100 行。 - SpecService 的静态表（属性表、分组表约 400 行）外移
core/spec-tables.ts，SpecService 只剩查询逻辑。 - 「样式已受保护」拦截提示单源化：UiService 新增
notifyStyleLocked()，替换了散在 11 个文件里的 17 处逐字复制的 toast。 - 注释全仓"去 AI 化"：清掉 350+ 处需求编号和变更史叙事，基准见开发规范的注释一节。
下一步（按计划排序，需配套测试）
| # | 动作 | 说明 |
|---|---|---|
| N1 | 拆 stops-editor（现 4300+ 行） | 曲线图拆 stops-chart、停靠弹层拆 stop-popover；纯函数层已就绪 |
| N2 | 拆 layer-list（现 3700+ 行） | 底图段、附属虚拟行、工具条分拆；layer-list-fns 已备好 |
| N3 | config-codec 按管线拆三 | codec / validate / migrate 三段物理边界现成 |
| N4 | ConfigStore 暂存泛型化 + ownConfig 收口 | 一个 Stash 实现替三份手写；17 处手调 ownConfig 收进写方法 |
| N5 | map.service 拆两个子系统 | 选择数据临时渲染与符号尺寸预览外移为协作单元 |
| N6 | prop-editor 与 global-prop-editor 提公共骨架 | "双胞胎"组件各削 300–500 行 |
| N7 | spec-doc 迁出 core 并数据化 | 千行中文文档常量去 features/help |
| N8 | app.component 模板拆弹窗 | 1704 行组合根拆到约 1000 |
配套还要补守卫：core 不得 import shared 的 UI 组件与有状态服务；shared 进一步分成纯函数（shared-core）与组件（shared-ui）两区，用测试锁住方向。计划还留了一条提醒：巨型组件拆分动静大，单独立项做，不要和别的清理混在一个 diff 里。
spec 升级方法学
升级 @maplibre/maplibre-gl-style-spec 不是改个版本号：先做全量 schema diff 清单，然后按 spec-coverage 对账补齐中文词表（shared/spec-zh/）与面板覆盖，最后 node tools/verify-spec26.mjs 做运行时冒烟。24.10 → 26.4.4 走过完整一轮，任何一环缺失，spec-coverage 门禁会直接红给你看。
翻案与例外
被否决的备案默认不可翻案，要翻需用户裁决，在 ADR 和原备案处销账。先例是 ADR-15：2026-09-30 用户一次裁决推翻了 RxJS、Tailwind、CDK 三项旧禁令，旧 ADR 标注"已被推翻"而不是删掉。评审接受的例外（铁律 §7）按"勿扩大"管理：可以引用，不许效仿，例外清单本身也是每轮审计的核对对象。
从哪认领工作
当前待办集中在三处：roadmap 文末索引（长期项）、docs/analysis/SUMMARY.md §7（未决产品裁决）、铁律 §8（遗留裁决项与行为缺陷）。加上 SIMPLIFICATION-PLAN 的 N1–N8。认领后按"只读审计 → 任务书 → 实施 + 等价证据 → 门禁 → 备案"的节奏推进，提交前过参与指南的清单。