全国校区地图 · 设计文档（v2：自动定位版）

日期：2026-10-20
分支：dev
状态：待评审（本阶段只出设计，不写实现）
变更：取消「选省/市 + 地图点选」流程，改为输入学校名自动定位
v3 变更：学校数据改为 JSON 静态存储（种子文件 + 运行时文件），不再用数据库；内置「浙江工商桐庐校区」

1. 背景与目标

已有「店铺运营」按学校分组看数据，但缺少全国视角。

新增一级菜单 校区地图：

中国地图上展示所有学校；启用的学校点亮（涟漪 + 名称），停用的显示为灰点
界面上创建学校：只填名称，系统自动定位并点亮
列表与「店铺运营」数据关联，显示该学校的门店数与最近数据日期
删除有运营数据的学校时二次确认

2. 关键决策

决策	结论
位置来源	本地高校坐标库自动匹配（2820 所），不选省市、不点地图、不填经纬度
未收录的学校	① 在线地理编码兜底（Photon）→ ② 仍失败则创建为「未定位」，不点亮，列表可点「重新定位」重试
坐标系	统一 GCJ-02（底图坐标系）；数据源是 BD-09 需转换，在线兜底是 WGS84 需转换
省份	由坐标预先算好（点落省份多边形），不需要用户选
存储	JSON 文件（种子 + 运行时），不依赖数据库；Node 18 也可用
内置学校	预置「浙江工商大学桐庐校区」（别名：浙江工商桐庐校区等）
批量导入	不做
删除保护	有同名运营数据时二次确认

3. 交互设计

3.1 创建学校

[新建学校] → 弹窗：输入「学校名称」（即时联想）
                 ┌──────────────────────────────┐
                 │ 中国计量大学     浙江省        │ ← 本地库命中
                 │ 中国计量大学现代科技学院  浙江省 │
                 └──────────────────────────────┘
        ↓ 选中
   地图自动飞到该点（zoom 8）→ 落标记（脉冲）→ 底部确认卡：
        ┌──────────────────────────────────────┐
        │ 中国计量大学 · 浙江省                  │
        │ 坐标 120.3626, 30.3210（GCJ-02）      │
        │              [取消]  [创建并点亮]      │
        └──────────────────────────────────────┘
        ↓
   创建成功 → 点位橙色涟漪 + 学校名，列表新增一条

规则：

精确且唯一命中（如「中国计量大学」）：直接显示确认卡，一次点击完成
多条命中（如「中国计量大学」与「中国计量大学现代科技学院」）：候选列表选择，带省份区分
无命中：显示「未收录该学校」+ [尝试在线定位]；在线也失败时提供 [先创建（未定位）]
创建默认启用（点亮），可立即关闭

3.2 编辑

点列表项 → 右侧详情卡：

┌ 中国计量大学 ──────────────────┐
│ 浙江省 · 120.3626, 30.3210      │
│ 运营数据：9 家门店 · 最近 10-07  │
│ [重新匹配]  [停用]  [删除]       │
└────────────────────────────────┘

重新匹配：回到搜索框，输入新名称重新定位（覆盖坐标）
改名：详情卡标题可编辑
不提供拖动或点选微调（遵循"不点地图"的要求）

3.3 删除保护

若「店铺运营」中存在同名学校：

确定删除「中国计量大学」？
店铺运营中有 9 家门店使用了该名称，最近数据日期 2026-10-07。
删除学校不会删除运营数据。
[取消] [仍然删除]

3.4 地图交互

操作	行为
滚轮 / 双指	缩放（zoom 3~12）
拖拽	平移
悬停点位	tooltip：学校名 · 省份 · 门店数
点击点位	选中并高亮，右侧滚动到对应卡片
搜索框（列表上方）	过滤列表；点结果地图飞过去
[回到全国]	恢复默认视野

3.5 空态与异常

场景	展示
没有学校	地图灰显 + 中央「创建第一所学校」
存储不可用	地图正常渲染 + 顶部提示「学校数据暂不可用」+ 重试
底图加载失败	提示刷新，不渲染空画布
名称重复	保存时提示「已存在同名学校」
未定位学校	列表中灰色标签「未定位」，可重新定位

4. 定位数据与算法

4.1 本地高校库

public/vendor/cn-universities.json（238KB，2820 所）：

{
  "中国计量大学": { "lng": 120.362644, "lat": 30.321047, "province": "浙江省" },
  "浙江科技学院": { "lng": 120.025229, "lat": 30.220034, "province": "浙江省" }
}

生成方式（构建期一次性；数据已生成，生成脚本在实施阶段一并提供）：

取开源数据集 flwfdd/china-university-location（2820 所，百度坐标）
BD-09 → GCJ-02 转换
用省级 GeoJSON 做点在多边形内判断，写入 province
输出精简 JSON（不含冗余字段）

坐标系验证（以 Photon 返回的 WGS84 → GCJ-02 为参照）：

学校	数据集原始(BD-09)	转换后 GCJ-02	与参照偏差
清华大学	116.33337, 40.00964	116.32677, 40.00391	45m
北京大学	116.31683, 39.99888	116.31031, 39.99288	33m
武汉大学	114.37292, 30.54380	114.36651, 30.53748	274m
中国计量大学	120.36904, 30.32740	120.36264, 30.32105	284m
复旦大学	121.51077, 31.30187	121.50419, 31.29623	392m

不转换直接用会是 850~1200m 的系统性偏移，所以转换是必须的。残差在校区尺度内（校区本身就有几百米跨度），可接受。

4.2 名称匹配

按顺序尝试，命中即止：

精确匹配（去首尾空格）
归一化匹配：去掉括号内容、空格、全半角差异（中国计量大学(下沙校区) → 中国计量大学）
前缀/包含匹配（计量大学 → 中国计量大学）

候选排序：精确 > 归一化 > 包含；同分时名称短的优先。最多返回 8 条，带省份用于区分。

4.3 未收录兜底

在线地理编码（服务端发起，避免浏览器跨域）：

请求 https://photon.komoot.io/api/?q=<名称>&limit=5
只接受 countrycode=CN 且 name 与输入相似度足够高的结果
返回 WGS84 → WGS84→GCJ-02 转换后使用
超时 8s；失败则创建为「未定位」

设计上把「在线兜底」做成可选动作（用户点按钮触发），不做成创建时自动请求——避免无网络环境下创建流程卡住。

4.4 点亮

geo（省级底图，roam）
├── effectScatter「已启用」：橙色 #ff6b35，rippleEffect，右侧名称标签
└── scatter「未启用 / 未定位」：灰色 #b8b2ad，无标签

点击、悬停、选中联动；同屏像素距离 <14px 的两点做 ≤8px 确定性偏移。

5. 数据模型（JSON 静态存储）

5.1 两类文件

文件	是否提交到仓库	作用
`server/schools.seed.json`	提交	内置学校（随版本发布）；初始只有浙江工商桐庐校区
`data/schools.json`	不提交（`data/` 已 gitignore）	运行时新增/修改的学校，以及对内置项的覆盖

读取时合并两者，对外的列表就是合并结果；写入只动 data/schools.json。

5.2 条目结构

{
  "id": "sch_tonglu_001",
  "name": "浙江工商大学桐庐校区",
  "aliases": ["浙江工商桐庐校区", "浙江工商大学杭州商学院", "杭州商学院桐庐校区"],
  "province": "浙江省",
  "city": "杭州市",
  "county": "桐庐县",
  "lng": 119.744166,
  "lat": 29.830417,
  "source": "seed",
  "seed": true,
  "enabled": true,
  "created_at": "2026-10-20T00:00:00.000Z",
  "updated_at": "2026-10-20T00:00:00.000Z"
}

字段说明：

name 为唯一键；aliases 只用于搜索联想，不参与唯一性
lng/lat（GCJ-02）为 null 表示「未定位」（灰点、不点亮）
seed: true 表示内置项
内置项坐标：浙江工商大学杭州商学院桐庐校区（桐庐县），[119.744166, 29.830417]

5.3 合并与写回规则

操作	行为
读取	种子 + 运行时；同名（`name`）时运行时字段覆盖种子
新建	只写 `data/schools.json`；若与种子/运行时同名 → 400
修改（改名/重新定位/启停）	写 `data/schools.json` 的同名记录（对种子项即"覆盖层"）
删除	运行时项：从文件移除；种子项：拒绝删除，提示「内置学校只能停用」
文件缺失/损坏	用种子继续工作，日志 warning，不崩溃
写入	临时文件 + rename 原子替换；单进程串行

5.4 与运营数据的关联

学校存 JSON，运营数据在 ops 库（SQLite/PG），关联在读取时做：

按 ops_school_name（即学校名及别名）去 ops_shop.school 精确匹配
聚合出「门店数」与「最近数据日期」
ops 库不可用时：地图与学校管理照常，关联字段显示「未关联运营数据」

5.5 内置学校

字段	值
名称	浙江工商大学桐庐校区
别名	浙江工商桐庐校区 / 浙江工商大学杭州商学院 / 杭州商学院桐庐校区
省/市/县	浙江省 / 杭州市 / 桐庐县
坐标（GCJ-02）	119.744166, 29.830417
默认状态	启用（点亮）

名称采用「浙江工商大学桐庐校区」是为了和上传表里的 学校名称 对得上（人工统计表用的就是全称），别名保证用户输入简称也能搜到。

6. 接口

方法	路径	说明
GET	`/api/schools`	列表，含 enabled、坐标、门店数、最近数据日期
GET	`/api/schools/search?q=`	本地高校库联想（也可前端直接加载 JSON 搜索，二选一）
POST	`/api/schools`	创建：`{ name, lng?, lat?, province?, source? }`；缺坐标时按名称自动匹配
POST	`/api/schools/:id`	更新（改名 / 重新匹配 / 坐标）
POST	`/api/schools/:id/toggle`	启用/停用
POST	`/api/schools/locate`	在线兜底：`{ name }` → `{ lng, lat, province, source }`
DELETE	`/api/schools/:id`	删除

校验：名称 1~60 且唯一；坐标若提供必须在 GCJ-02 中国范围（lng 73~136，lat 3~54）。

存储相关：写操作失败（磁盘只读等）返回 500 并保持文件原样；GET /api/schools 始终可用（JSON 不依赖数据库）。测试通过环境变量 SCHOOLS_FILE 指定临时文件，避免污染本机 data/schools.json。

7. 界面

┌──────────────────────────────────────────────────────────────┐
│ 校区地图                          + 新建学校                 │
│ 已启用 3 / 共 5                                              │
├───────────────────────────────────┬──────────────────────────┤
│                                   │ 🔍 搜索                   │
│        中国地图（可缩放）           │ 浙江省 2/3               │
│                                   │ ┌──────────────────────┐ │
│      ● 中国计量大学                │ │● 中国计量大学 [开]    │ │
│      ● 浙江工商大学桐庐校区         │ │  9 店 · 最近 10-07    │ │
│      ○ 浙江科技学院（未启用）       │ ├──────────────────────┤ │
│                                   │ │○ 浙江科技学院 [关]    │ │
│                  [回到全国]        │ │  未关联运营数据        │ │
│                                   │ └──────────────────────┘ │
└───────────────────────────────────┴──────────────────────────┘

列表按省份分组，组头显示启用数
每项显示「N 店 · 最近日期」；无关联数据显示「未关联运营数据」
点击列表项 → 地图飞过去并选中
详情卡提供「查看运营数据」→ 跳转「店铺运营」并预选该校（按名称匹配）
宽度 <1100px 时列表移到地图下方

8. 与现有功能的关系

独立菜单，不改动店铺运营现有行为
通过 ops_shop.school 名称关联，仅做只读展示（门店数、最近日期）
不参与采集、不参与钉钉推送

9. 测试

9.1 单元

BD-09 → GCJ-02 转换（用 §4.1 五组值断言，误差 < 200m）
名称匹配：精确 / 带括号 / 简称 / 无命中
坐标范围校验（境内 / 境外）
省份识别（中国计量大学 → 浙江省；境外点 → 空）

9.2 接口（临时 SQLite）

创建（带坐标 / 仅名称自动匹配）→ 列表可见
重名 400；停用/启用；删除
未定位学校（lng/lat 为空）不报错，enabled=1 也不点亮
关联字段：造 2 条 ops_shop 同名数据 → 返回门店数 2 与最近日期
内置项不可删除（400），可停用；运行时项可删除
种子 + 运行时合并：同名时运行时覆盖
文件损坏：仍能返回种子数据，不 500
ops 库不可用：GET /api/schools 仍 200，关联字段为空

9.3 冒烟

GET /api/schools 200（只读）

9.4 手工验收

输入「中国计量大学」→ 联想出现 → 选中 → 地图飞到杭州下沙 → 创建 → 点位点亮 → 刷新仍在 → 列表显示关联门店数与最近日期 → 停用变灰 → 删除时若有运营数据出现二次确认。

10. 待办清单（评审通过后拆计划）

scripts/build-university-data.js（数据生成脚本，含 BD-09 转换与省份归属；数据文件已就绪）
public/vendor/cn-universities.json（已生成，待登记静态白名单）
server/schools.seed.json（内置浙江工商桐庐校区）
schools-store.js：种子 + 运行时文件合并、原子写、损坏兜底
/api/schools 端点（含 search / locate / 关联查询 / 删除保护）
public/schools.js：地图、联想、创建、编辑、启停、删除确认、列表联动
index.html 菜单与页面、app.js 注册、style.css
测试脚本扩展 + smoke 只读断言
README 增补「校区地图」与坐标系说明

11. 已确认事项

未收录学校：在线地理编码兜底 → 失败允许创建为「未定位」（灰点、不点亮），列表内可重试定位
关联跳转：详情卡提供「查看运营数据」，跳转「店铺运营」并预选该学校
不做批量导入；创建后默认启用
学校数据用 JSON（种子 + 运行时），不进数据库；内置项只能停用不能删除

2026-10-20-campus-map-design.md 15 KB Lịch sử Raw