|
|
@@ -0,0 +1,249 @@
|
|
|
+# 全国校区地图 · 设计文档
|
|
|
+
|
|
|
+- 日期：2026-10-20
|
|
|
+- 分支：`dev`
|
|
|
+- 状态：待评审（本阶段只出设计，不写实现）
|
|
|
+
|
|
|
+## 1. 背景与目标
|
|
|
+
|
|
|
+已有「店铺运营」按学校分组看数据，但缺少一个**全国视角**：哪些学校在用、分布在哪、开了几家。
|
|
|
+
|
|
|
+新增一级菜单 **校区地图**：
|
|
|
+
|
|
|
+- 中国地图上展示所有学校；**启用的学校点亮**（涟漪 + 名称），停用的显示为灰点
|
|
|
+- 可在界面上**创建学校**：填名称、在地图上点出位置、启用
|
|
|
+- 点击点位或列表项可查看/编辑/停用/删除
|
|
|
+
|
|
|
+## 2. 已定的关键决策
|
|
|
+
|
|
|
+| 决策 | 结论 | 原因 |
|
|
|
+|---|---|---|
|
|
|
+| 位置来源 | **必须在地图上主动点选**，不提供经纬度输入框 | 一个城市有多所高校，城市中心会重叠且偏差大；手填经纬度对使用者不友好 |
|
|
|
+| 默认位置 | **没有默认位置**，未落点不允许保存 | 避免"看起来创建成功、点却落在市中心" |
|
|
|
+| 城市字段 | 只作为**地图跳转的辅助**（选城市 → 地图飞过去 → 再点精确位置），不决定落点 | 兼顾"快速定位到城市"和"精确到校区" |
|
|
|
+| 省份 | 落点后**自动识别**（点在哪个省），也可手动改 | 避免坐标与省份对不上 |
|
|
|
+| 坐标系 | 统一存 **GCJ-02**（底图坐标系） | 点选天然得到 GCJ-02；混用 WGS84 会有几百米偏差（见 §4.3） |
|
|
|
+
|
|
|
+## 3. 交互设计
|
|
|
+
|
|
|
+### 3.1 创建学校（主流程）
|
|
|
+
|
|
|
+```
|
|
|
+[新建学校] → 弹窗：学校名称
|
|
|
+ 可选：省份 → 城市（仅用于把地图飞过去）
|
|
|
+ [取消] [在地图上选择位置]
|
|
|
+ ↓
|
|
|
+ 弹窗收起，地图进入「定位模式」：
|
|
|
+ 顶部提示条：请在地图上点击学校所在位置 · Esc 取消
|
|
|
+ 鼠标变十字；可选省份时先飞到该省/市（zoom 6~9）
|
|
|
+ ↓
|
|
|
+ 点击地图 → 落一个临时标记（脉冲动画）
|
|
|
+ 提示条变成：已选位置（自动识别的省份） [重选] [确认创建]
|
|
|
+ ↓
|
|
|
+ 确认 → 保存并默认「启用」→ 点位变橙色涟漪，列表新增一条
|
|
|
+```
|
|
|
+
|
|
|
+要点：
|
|
|
+
|
|
|
+- **没点位置时"确认创建"不可用**，从流程上杜绝城市中心兜底
|
|
|
+- 落点后自动识别省份；识别不出（点在海上/境外）时提示"该位置不在中国境内，请重新选择"
|
|
|
+- 同城多校因为各自精确点选，天然分散，不会叠在一起
|
|
|
+
|
|
|
+### 3.2 编辑与重新定位
|
|
|
+
|
|
|
+列表项或点位 → 右侧详情卡：
|
|
|
+
|
|
|
+```
|
|
|
+┌ 中国计量大学 ────────────────┐
|
|
|
+│ 浙江省 · 杭州市 │
|
|
|
+│ 坐标 120.3626, 30.3187 │ ← 只读展示，不可编辑输入框
|
|
|
+│ [重新定位] [停用] [删除] │
|
|
|
+└──────────────────────────────┘
|
|
|
+```
|
|
|
+
|
|
|
+- **重新定位**：再次进入定位模式，地图飞到该点（zoom 9），点击新位置后确认覆盖
|
|
|
+- 名称可改（点详情卡标题进入编辑）
|
|
|
+- 删除需二次确认
|
|
|
+
|
|
|
+### 3.3 启用 / 停用
|
|
|
+
|
|
|
+- 列表每项一个开关；打开 = 点亮，关闭 = 灰点
|
|
|
+- 开关即时生效，不需要保存按钮
|
|
|
+- 停用只影响地图展示，不删除学校、不影响「店铺运营」数据
|
|
|
+
|
|
|
+### 3.4 地图交互
|
|
|
+
|
|
|
+| 操作 | 行为 |
|
|
|
+|---|---|
|
|
|
+| 滚轮 / 双指 | 缩放（zoom 3 ~ 12） |
|
|
|
+| 拖拽 | 平移 |
|
|
|
+| 双击省份 | 放大到该省 |
|
|
|
+| 悬停点位 | tooltip：学校名 · 省/市 · 状态 |
|
|
|
+| 点击点位 | 选中并高亮，右侧滚动到对应卡片 |
|
|
|
+| 搜索框 | 按名称过滤列表；点结果 → 地图飞到该点（zoom 9） |
|
|
|
+| [回到全国] | 恢复默认视野（center 104, 35 / zoom 1.2） |
|
|
|
+
|
|
|
+### 3.5 空态与异常
|
|
|
+
|
|
|
+| 场景 | 展示 |
|
|
|
+|---|---|
|
|
|
+| 一所学校都没有 | 地图灰显 + 中央「新建第一所学校」按钮 + 一行说明 |
|
|
|
+| 存储不可用 | 地图正常显示，顶部提示「学校数据暂不可用」+ 重试，创建按钮禁用 |
|
|
|
+| 底图加载失败 | 提示「地图数据加载失败，请刷新」，不渲染空白画布 |
|
|
|
+| 名称重复 | 保存时提示「已存在同名学校」，不创建 |
|
|
|
+| 点位在境外 | 拒绝保存并提示重新选择 |
|
|
|
+
|
|
|
+## 4. 地图技术方案
|
|
|
+
|
|
|
+### 4.1 技术选型
|
|
|
+
|
|
|
+- **ECharts 5.6.0**（仓库已内置 `public/vendor/echarts.min.js`），`geo` 组件 + `effectScatter` 系列
|
|
|
+- **底图**：中国省级 GeoJSON，本地内置 `public/vendor/china-map.json`（569KB，35 个省级面，含南海诸岛）
|
|
|
+- **城市定位库**：`public/vendor/cn-cities.json`（19KB，35 省 / 477 个城市区县的中心坐标，只用于"飞到城市"）
|
|
|
+- 全部离线，不依赖任何地图服务或 Key
|
|
|
+
|
|
|
+### 4.2 点亮实现
|
|
|
+
|
|
|
+```
|
|
|
+geo（底图，roam 可缩放平移）
|
|
|
+├── effectScatter series「已启用」
|
|
|
+│ symbolSize 10~14，颜色 #ff6b35
|
|
|
+│ rippleEffect { brushType: 'stroke', scale: 3.2, period: 3.5 }
|
|
|
+│ label { show: true, formatter: 学校名, position: right }
|
|
|
+│
|
|
|
+└── scatter series「未启用」
|
|
|
+ symbolSize 6，颜色 #b8b2ad，无涟漪、无标签
|
|
|
+```
|
|
|
+
|
|
|
+- 点击：`chart.on('click', params => selectSchool(params.data.id))`
|
|
|
+- 悬停：tooltip formatter 输出三行（名称 / 省市 / 状态）
|
|
|
+- 选中：被选中的点 symbolSize +4、边框加亮，右侧卡片同步高亮
|
|
|
+- 同城多点重叠：先按经纬度绘制；若两点**屏幕像素距离 < 14px**，对后者做 ≤8px 的确定性偏移（按 id 哈希），保证都看得见
|
|
|
+
|
|
|
+### 4.3 坐标系（重要）
|
|
|
+
|
|
|
+中国互联网地图（阿里 DataV、高德）用的是 **GCJ-02**，而 GPS / OpenStreetMap 是 **WGS84**，两者在国内相差 300~600 米。
|
|
|
+
|
|
|
+| 例子 | WGS84 | GCJ-02 | 偏差 |
|
|
|
+|---|---|---|---|
|
|
|
+| 中国计量大学 | 120.3580, 30.3210 | **120.3626, 30.3187** | 约 440m / 254m |
|
|
|
+| 杭州市中心 | 120.1536, 30.2875 | 120.1583, 30.2851 | 约 452m / 257m |
|
|
|
+| 天安门 | 116.3910, 39.9070 | 116.3972, 39.9084 | 约 533m / 155m |
|
|
|
+
|
|
|
+结论：
|
|
|
+
|
|
|
+- **用户在底图上点选的坐标天然是 GCJ-02**，直接存，所见即所得
|
|
|
+- 外部来源（GPS、OSM、别人给的经纬度）是 WGS84，入库前要转换；提供 `wgs84ToGcj02()` 工具函数与一条 `scripts/` 小工具供批量导入
|
|
|
+- 只读展示坐标时标注「GCJ-02」，避免误用
|
|
|
+
|
|
|
+## 5. 数据模型
|
|
|
+
|
|
|
+复用现有 ops 存储（默认 SQLite，可切 PG），新增一张表：
|
|
|
+
|
|
|
+```sql
|
|
|
+CREATE TABLE IF NOT EXISTS ops_school (
|
|
|
+ id text PRIMARY KEY, -- 服务端生成，如 sch_20261020_a1b2c3
|
|
|
+ name text NOT NULL,
|
|
|
+ province text NOT NULL DEFAULT '',
|
|
|
+ city text NOT NULL DEFAULT '',
|
|
|
+ lng real NOT NULL, -- GCJ-02
|
|
|
+ lat real NOT NULL,
|
|
|
+ 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);
|
|
|
+```
|
|
|
+
|
|
|
+设计说明：
|
|
|
+
|
|
|
+- `name` 唯一，防止重复创建同一所学校
|
|
|
+- `province` / `city` 为展示与分组用；`province` 由落点自动识别，`city` 取用户在下拉里选的值（允许为空）
|
|
|
+- 与「店铺运营」的关联：`ops_shop.school` 是字符串，按 **名称相等** 关联；创建时会提示「与 N 个运营数据中的学校匹配」，对不上也允许创建（先画图、后补数据）
|
|
|
+- `enabled` 用 0/1，SQLite 与 PG 都兼容
|
|
|
+
|
|
|
+## 6. 接口
|
|
|
+
|
|
|
+| 方法 | 路径 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| GET | `/api/schools` | 列表（含 enabled、坐标、省市） |
|
|
|
+| POST | `/api/schools` | 创建；`{ name, province, city, lng, lat, enabled? }` |
|
|
|
+| POST | `/api/schools/:id` | 更新（改名、重新定位） |
|
|
|
+| POST | `/api/schools/:id/toggle` | 启用/停用 `{ enabled }` |
|
|
|
+| DELETE | `/api/schools/:id` | 删除 |
|
|
|
+
|
|
|
+校验：
|
|
|
+
|
|
|
+- `name`：去空白、1~60 字符、唯一
|
|
|
+- `lng` / `lat`：必填；中国范围（lng 73~136、lat 3~54）之外拒绝
|
|
|
+- `province` / `city`：可选，≤40 字符
|
|
|
+- 存储不可用：`GET` 返回 200 + `{ enabled:false, reason }`，写操作 503（与 ops 现有一致）
|
|
|
+
|
|
|
+## 7. 界面布局
|
|
|
+
|
|
|
+```
|
|
|
+┌──────────────────────────────────────────────────────────────┐
|
|
|
+│ 校区地图 + 新建学校 │
|
|
|
+│ 已启用 3 / 共 5 │
|
|
|
+├───────────────────────────────────┬──────────────────────────┤
|
|
|
+│ │ 🔍 搜索学校 │
|
|
|
+│ 中国地图（可缩放平移） │ ┌──────────────────────┐ │
|
|
|
+│ │ │● 中国计量大学 [开] │ │
|
|
|
+│ ● 中国计量大学 │ │ 浙江 · 杭州 │ │
|
|
|
+│ ● 浙江工商大学桐庐校区 │ ├──────────────────────┤ │
|
|
|
+│ ○ 浙江科技学院（未启用） │ │○ 浙江科技学院 [关] │ │
|
|
|
+│ │ │ 浙江 · 杭州 │ │
|
|
|
+│ [回到全国] │ └──────────────────────┘ │
|
|
|
+└───────────────────────────────────┴──────────────────────────┘
|
|
|
+```
|
|
|
+
|
|
|
+- 左侧地图占 2/3 以上，右侧列表 320px
|
|
|
+- 列表按省份分组，组头显示该省启用数（如「浙江省 2/3」）
|
|
|
+- 窄屏（<1100px）时列表折叠到地图下方
|
|
|
+
|
|
|
+## 8. 与现有功能的关系
|
|
|
+
|
|
|
+- **独立菜单**，不改「店铺运营」的现有行为
|
|
|
+- 数据上通过 `ops_shop.school` 名称关联，为下一步「点击地图上的学校 → 打开店铺运营并筛选该学校」留好接口（本期不做跳转）
|
|
|
+- 不参与采集、不参与钉钉推送、不影响任何现有接口
|
|
|
+
|
|
|
+## 9. 测试
|
|
|
+
|
|
|
+### 9.1 单元
|
|
|
+
|
|
|
+- 坐标范围校验（境内/境外）
|
|
|
+- 名称去重与去空白
|
|
|
+- 省份自动识别（点在浙江/北京/境外三种情况）
|
|
|
+- WGS84 → GCJ-02 转换（用 §4.3 三组已知值做断言，误差 < 1e-4）
|
|
|
+
|
|
|
+### 9.2 接口（临时 SQLite）
|
|
|
+
|
|
|
+- 创建 → 列表可见；重复名称 400
|
|
|
+- 切换启用状态；删除后列表消失
|
|
|
+- 坐标缺省 / 越界 → 400
|
|
|
+- 存储不可用 → GET 200 + `enabled:false`，POST 503
|
|
|
+
|
|
|
+### 9.3 冒烟
|
|
|
+
|
|
|
+`GET /api/schools` 200（只读，不新增写操作）
|
|
|
+
|
|
|
+### 9.4 手工验收
|
|
|
+
|
|
|
+新建「中国计量大学」→ 选浙江省 → 地图飞到浙江 → 点下沙位置 → 保存 → 点位点亮并显示名称 → 刷新页面仍在 → 停用变灰 → 重新启用再点亮 → 删除后消失。
|
|
|
+
|
|
|
+## 10. 待办清单（通过评审后拆实施计划）
|
|
|
+
|
|
|
+- [ ] `public/vendor/china-map.json`、`cn-cities.json`（已就绪，需登记到静态白名单）
|
|
|
+- [ ] `ops_school` 表与存储方法（SQLite + PG 两驱动）
|
|
|
+- [ ] `/api/schools` 五个端点 + 校验 + 存储降级
|
|
|
+- [ ] `public/schools.js`：地图渲染、点亮、定位模式、列表联动、创建/编辑弹窗
|
|
|
+- [ ] `index.html` 菜单与页面骨架、`app.js` 视图注册、`style.css`
|
|
|
+- [ ] 坐标工具：`wgs84ToGcj02()` + 省份识别（点在多边形内）
|
|
|
+- [ ] 测试脚本扩展（单元 + 接口）与 smoke 只读断言
|
|
|
+- [ ] README 增补「校区地图」章节与坐标系说明
|
|
|
+
|
|
|
+## 11. 开放问题（实施前需确认）
|
|
|
+
|
|
|
+1. 学校列表是否要显示「该学校在店铺运营里有几家店 / 最近有数据的日期」？（需要与 ops 数据联查，工作量 +0.5 天）
|
|
|
+2. 删除学校时，如果「店铺运营」里已有同名学校的数据，是否需要二次确认并提示影响？
|
|
|
+3. 是否需要「批量导入学校」（给一份 Excel/CSV，含名称+坐标）？本期默认不做。
|
liangzhao