参与指南

从克隆到第一个改动合入，路径不长，但门禁不少——每条门禁背后都站着一个真实事故。照着这一页走，一个下午能把第一轮改动收干净。环境搭建和启动见从零开始；写代码本身的规矩（分层、状态、注释）见开发规范，这里只讲流程。

工作流：一个改动从发起到合入

这个仓库的惯例是单 main 分支 + 轮次制：不走长期特性分支，一个改动单元是"一轮"——扫描、实施、门禁、治理同步、提交五步走完才合入。CI 在 PR 和 push main 时跑同一套门禁，所以合入前本地过一遍等价检查，基本不会在 CI 上翻车。

五步里最容易被新人省掉的是扫描和治理同步。扫描决定了你知不知道自己碰的东西被谁依赖（这个仓库 7 万多行，凭感觉改必翻车）；治理同步决定了下一个人能不能从台账里找到你做过什么。

环境与前置

环境搭建完整版见从零开始，最少清单：

bash

cd editor
npm install --legacy-peer-deps   # peer 冲突是备案的已知项，别用 --force
npm run dev                      # :4230

跑 e2e 需要 cd tools && npx playwright install chromium；跑生产形态需要 Rust 工具链（rust-version 1.85+）。姊妹仓（GISSDK、ng-mfe）只有做微前端联调才需要，缺失时相关检查自动跳过。

新功能往哪落

先按问题域定位，再走对应接线：

样式语义（paint/layout/表达式）：StyleStore 的 mutator 里改，配 spec 元数据检查——spec-coverage 门禁会强制中文词表和面板补齐。
界面意图（显示名、分组、底图这类）：ms-config 文档加字段，四点联动：config.model 类型 → codec 与 Schema 同步 → store setter → buildConfigDocument 供料。详见配置参考。
纯 UI（开合、弹层、局部状态）：组件本地 signal；跨组件触发动作走 UiService 计数通道。

两个高频陷阱提前说：

属性编辑类改动禁止手写 ['interpolate',['linear'],['zoom'],10,v,20,v] 这类字面量，一律走 AST 工厂和 compileExpression（prop-upgrade.ts 是样板）。手写字面量绕过了词表，JSON 面板和持久化会立刻对不上。
新弹窗走 ui.modal 联合类型 + app.component 模板分支 + imports 三点；轻弹层用 host 绑定惯用法（document:click + Escape + stopPropagation）。不要自己新起一套弹窗 DOM。

新增地图能力（调 MapLibre native API）另有三问门禁：先在 core/map/map-capabilities.ts 的能力矩阵登记，再写对账测试——因为编辑器和 GISSDK 内核是两个 maplibre 版本，API 面可能不一致。

提交信息怎么写

中文长信息，按轮次聚合，门禁结果写数字不写"通过"：

text

R-62 台账落账：需求行 R-62＋任务行 T-282…T-287（6 项用户反馈批次）＋用例文档随动
门禁：tsc 0 错 + vitest 223 文件 4610 例 + build 通过 + e2e 17 套 PASS + 基线 0.000%
治理同步：CHANGELOG 章节、roadmap 条目、铁律 §9 基线 4523→4610

格式不神秘：第一行一句话结论，然后变更分项（需求/现状/实现/验证），然后门禁数字，然后治理同步了哪里。翻 git log 看几条就有感觉了。

评审清单

提交前自查，也用来评审别人的改动：

[ ] 依赖方向正确：shared 零上行依赖、core 不 import features、无环（architecture 测试会拦，先自查省一轮）。
[ ] 订阅纪律：异步流走 RxJS 管道；手写 .subscribe( 同行配 takeUntilDestroyed。
[ ] 写通道唯一：样式经 StyleStore.update，config 经 ConfigStore 命名方法，没有绕过。
[ ] 组件无请求、无业务状态字段；模板无 map/filter/join、无多语句 click。
[ ] 新共享物已配单测并在 DEVELOPMENT-GUIDE 复用登记节登记。
[ ] 事件监听、定时器、Observer 都可解绑。
[ ] 注释符合契约：写"为什么"，没有需求编号和变更史。
[ ] 违反铁律处有据可查：标注 RK-xx 或备案说明，例外清单（铁律 §7）只引用不扩大。
[ ] 改了权威文档就更新文档地图登记，不在第二处复制同一份事实。

治理文档去哪写

变更类型	登记处
轮次明细（架构/功能/UI）	`editor/docs/refactor/REFACTOR-CHANGELOG.md` 对应轮次章节
轮次索引与门禁终态	`docs/notes/roadmap.md` 文末索引节
新增权威文档	文档地图登记表
新风险	DEVELOPMENT-GUIDE 风险台账（RK-xx，给等级/触发条件/责任域）

禁止事项

这些是红线，评审必拦：

绕过 store 直改样式对象；在组件里 fetch / subscribe；向样式文档写 mapstudio:* 约定键（界面意图进 ms-config）。
删除代码、配置、测试前不列清单确认；删 CSS 前 src 和 tools 双域 grep 复核零引用。
在 README 或注释里复制权威文档的大段内容——只留指针。
ng-content 条件包含；程序化装载不布防 autosave（suppressNextSave()）。
为"可从样式反推"省略配置授权字段：配置文档是完整授权面，不是缓存的派生物。

想了解这个仓库为什么用轮次制而不是大重写，以及当前正在推进的简化重构，接着读演进指南。

参与指南 ​

工作流：一个改动从发起到合入 ​

环境与前置 ​

新功能往哪落 ​

提交信息怎么写 ​

评审清单 ​

治理文档去哪写 ​

禁止事项 ​