# 🤝 CGo OpenMap 社区贡献与城市主理人指南

感谢你对 **CGo OpenMap** 城市轨道交通线路图开放平台的关注与支持！

无论你是为自己所在的城市绘制一份全新的地铁线路图，还是修正现有城市的站点坐标、线路走向或时刻表，我们都极其欢迎你的参与。

---

## 🌟 “城市主理人”计划 (City Maintainer Initiative)

为了致敬每一位在数字世界中编织城市轨道交通脉络的贡献者，本项目设立**官方城市主理人机制**：

1. **尊享专属署名权**：
   - 当你的城市数据合入官方主仓库后，你的名字与 GitHub 个人主页将永久展示在：
     - 地图界面核心的 **「关于与帮助」弹窗**（随城市动态联动高亮当前主理人）；
     - 项目官方 `README.md` 的 **致谢与主理人名录**；
     - 城市元数据中心（`city/data.js`）的官方数据记录。
2. **主理人治理权**：
   - 作为该城市的官方主理人，未来若有其他贡献者向该城市提交站点勘误或线路调整 PR，官方团队将优先抄送并尊重主理人的审核与合注意见。

---

## 🛡️ 官方版本兼容性承诺（合入主库 vs 独立分支）

CGo OpenMap 核心引擎正在飞速演进（包括未来规划的换乘寻路引擎、时刻表联动、实际走向模式联动、3D 视图等重大升级）。

| 对比维度 | ✅ 合入官方主仓库（提 PR） | ❌ 私下保留独立分支（不提 PR） |
| :--- | :--- | :--- |
| **底层引擎持续升级** | **无缝平滑升级**，始终享受最新功能与性能优化 | 随着底层引擎迭代，私有分支迅速失配破损 |
| **数据迁移与自动化维护** | 官方核心团队负责向后兼容、自动化格式迁移与测试 | 需自行逐行排查并修改数据格式，维护成本极高 |
| **Bug 修复与生态支持** | 享受官方社区全球开发者的联合纠错与协同支持 | 单打独斗，需自行修复浏览器兼容性与渲染问题 |
| **开源法律合规** | 100% 符合 GNU AGPLv3 与 ODbL 双轨开源规范 | 若在线公开部署但不开源数据，存在侵权违规风险 |

> 💡 **核心原则**：将城市数据合并回官方主库，是让你的心血长期存续、持续获得最先进引擎驱动的最佳选择！

---

## 🚀 极简 3 步贡献流程

### 第一步：Fork 并准备数据
1. Fork 本仓库至你的 GitHub 账号，并克隆到本地；
2. 仔细阅读 **[城市移植手册 (PORTING.md)](./PORTING.md)**，并参考现有的北京（`city/beijing/`）与沈阳（`city/shenyang/`）数据实现；
3. **准备数据（两种方式任选）**：
   - **智能提取（推荐）**：启动静态服务访问 `http://localhost:8080/drunk/`，使用 **Drunk 转换工作台** 上传底图/PDF/AI 自动提取全网站点与走向并导出标准代码。  
     *(⚠️ 注：Drunk 系统目前处于早期开发验证阶段，仅供测试使用，数据需人工复核。极其欢迎开发者共同参与 Drunk 转换系统的算法与交互开发！)*
   - **纯手工配置**：在 `city/` 目录下新建城市文件夹（如 `city/guangzhou/`），手工丈量配置车站与线路数据。

### 第二步：登记城市元数据与署名
在 `city/data.js` 的 `CITY_REGISTRY` 中注册你的城市，并在 `maintainers` 中留下你的署名：

```javascript
"guangzhou": {
    id: "guangzhou",
    name: "广州",
    folder: "./city/guangzhou",
    mainLogic: "./city/guangzhou/guangzhou.js",
    center: { x: 900, y: 650 },
    defaultScale: 1.0,
    mapSize: { width: 2000, height: 1600 },
    searchCity: "广州",
    title: "CGo OpenMap - 广州轨道交通线路图",
    // 填写主理人信息（将自动在 UI 与文档中动态展示）
    maintainers: [
        { name: "你的昵称或GitHub用户名", role: "城市主理人", github: "https://github.com/yourname" }
    ]
}
```

### 第三步：更新 Service Worker、本地验证并提交 Pull Request
1. **更新离线缓存**：打开 `sw.js`，递增 `CACHE_NAME` 版本号，并将新城市资源文件路径加入 `ASSETS_TO_CACHE` 清单中。
   > ⚠️ **关键警示**：**一定要更新 Service Worker，否则更改可能不会生效！** 如果在本地调试时遇到了**“怎么修改代码都不起作用、刷新毫无变化”**的情况，请务必首先思考是否是 Service Worker 强缓存导致（可在浏览器 DevTools 中勾选 Disable cache 或执行硬刷新）。
2. 启动本地静态服务（如 `npx serve .` 或 Python 简易服务器），确保：
   - [ ] 线路与车站完整渲染，无控制台报错；
   - [ ] 站名文本无遮挡重叠，深色与浅色模式显示正常；
   - [ ] 搜索框可正常检索新城市车站；
   - [ ] Service Worker 缓存已更新且能正常离线运行。

确认无误后，向官方仓库的 `main` 分支发起 **Pull Request**！

---

## 📋 PR 提交自查清单 (Checklist)

提交 PR 时，请在描述中确认以下内容（直接复制）：

```markdown
### 提交内容自查
- [ ] 已在 `city/{city_id}/` 下完整添加城市数据文件
- [ ] 已在 `city/data.js` 中注册城市并填写 `maintainers` 主理人信息
- [ ] 已在 `assets/svg/` 准备或复用该城市的线路徽标
- [ ] 已在 `sw.js` 中递增 `CACHE_NAME` 版本号并登记新文件（务必更新，否则更改无法生效）
- [ ] 已在本地测试，深色/浅色模式均无显示缺陷，控制台无报错
- [ ] 承诺本数据由本人依据官方公开运营数据整理，同意在 ODbL 1.0 / CC BY-SA 4.0 协议下向社区共享
```

---

## 🍺 协同开发 Drunk 智能转换系统

> **开发阶段说明**：**Drunk 线路图智能转换系统当前处于早期开发验证阶段，仅供测试与实验使用。热烈欢迎广大开发者共同参与开发！**

为了让全球的轨道交通爱好者与开发者更轻松地数字化城市线网，我们正在持续推进 Drunk 系统的演进。极其欢迎对以下方向感兴趣的开发者共同贡献：
- **PDF & 矢量工程解析**（`drunk/js/pdf_vector_extractor.js`）：进一步增强对各类复杂版本 PDF 与 Adobe Illustrator (`.ai`) 专色色板、图层元数据与文字曲线的解析精度；
- **视觉大模型提示词与拓扑解算**（`drunk/js/deepseek_vision.js`）：优化多模态模型对密集交叉线网、环线与平行共线站点的空间关系识别率；
- **智能排版避让与几何算法**（`drunk/js/ocr_align_solver.js` / `drunk_pipeline.js`）：改进 8 方向自动排版算法、文字碰撞检测与 45°/90° 正交网格智能吸附；
- **UI/UX 交互体验**（`drunk/index.html` / `drunk/css/drunk.css`）：持续打磨全深色工作台的流畅交互（如快捷键支持、历史撤销重做、多选批量移动等）。

欢迎随时向官方主仓库提交 Pull Request 或 Issue 进行探讨！

---

## 📄 协议与授权声明

根据本项目的双轨开源体系：
- 提交的代码与引擎相关优化受 **GNU AGPLv3** 约束；
- 提交的城市地理、车站与线路数据受 **ODbL 1.0 / CC BY-SA 4.0** 约束。

提交 PR 即代表你同意授权 CGo OpenMap 官方仓库在上述开源协议下分发、维护并持续演进你所提交的内容。