2026-10-20-campus-map-design.md 12 KB
全国校区地图 · 设计文档（v2：自动定位版）
- 日期：2026-10-20
- 分支：
dev - 状态：待评审（本阶段只出设计，不写实现）
- 变更：取消「选省/市 + 地图点选」流程，改为输入学校名自动定位
1. 背景与目标
已有「店铺运营」按学校分组看数据，但缺少全国视角。
新增一级菜单 校区地图：
- 中国地图上展示所有学校；启用的学校点亮（涟漪 + 名称），停用的显示为灰点
- 界面上创建学校：只填名称，系统自动定位并点亮
- 列表与「店铺运营」数据关联，显示该学校的门店数与最近数据日期
- 删除有运营数据的学校时二次确认
2. 关键决策
| 决策 | 结论 |
|---|---|
| 位置来源 | 本地高校坐标库自动匹配（2820 所），不选省市、不点地图、不填经纬度 |
| 未收录的学校 | ① 在线地理编码兜底（Photon）→ ② 仍失败则创建为「未定位」，不点亮，列表可点「重新定位」重试 |
| 坐标系 | 统一 GCJ-02（底图坐标系）；数据源是 BD-09 需转换，在线兜底是 WGS84 需转换 |
| 省份 | 由坐标预先算好（点落省份多边形），不需要用户选 |
| 批量导入 | 不做 |
| 删除保护 | 有同名运营数据时二次确认 |
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. 数据模型
沿用 ops 存储（SQLite 默认 / PG 可切）：
CREATE TABLE IF NOT EXISTS ops_school (
id text PRIMARY KEY, -- sch_20261020_a1b2c3
name text NOT NULL,
province text NOT NULL DEFAULT '',
lng real, -- GCJ-02；未定位时为 NULL
lat real,
source text NOT NULL DEFAULT 'local', -- local | geocode | none
enabled integer NOT NULL DEFAULT 1,
created_at text NOT NULL,
updated_at text NOT NULL
);
CREATE UNIQUE INDEX IF NOT EXISTS ops_school_name_idx ON ops_school (name);
lng/lat允许 NULL = 未定位（不点亮）source记录定位来源，便于排查- 与运营数据的关联：按
ops_shop.school = ops_school.name精确匹配，查询时聚合门店数与MAX(date)
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）。
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 与最近日期 - 存储不可用 → GET 200 +
enabled:false，写操作 503
9.3 冒烟
GET /api/schools 200（只读）
9.4 手工验收
输入「中国计量大学」→ 联想出现 → 选中 → 地图飞到杭州下沙 → 创建 → 点位点亮 → 刷新仍在 → 列表显示关联门店数与最近日期 → 停用变灰 → 删除时若有运营数据出现二次确认。
10. 待办清单（评审通过后拆计划）
-
scripts/build-university-data.js（数据生成脚本，含 BD-09 转换与省份归属；数据文件已就绪） -
public/vendor/cn-universities.json（已生成，待登记静态白名单） -
ops_school表 + 存储方法（SQLite / PG） -
/api/schools端点（含 search / locate / 关联查询 / 删除保护所需计数） -
public/schools.js：地图、联想、创建、编辑、启停、删除确认、列表联动 -
index.html菜单与页面、app.js注册、style.css - 测试脚本扩展 + smoke 只读断言
- README 增补「校区地图」与坐标系说明
11. 待确认
- 「未收录学校」走在线兜底失败后，是否允许创建为「未定位」（灰点、不点亮）？还是直接拒绝创建？
- 列表点击是否要顺带跳转到「店铺运营并筛选该学校」？（关联体验更完整，约 +0.5 天）