feat(M03-C): 完成地图选店与距离排序

2026-06-18 15:15:39 +08:00
parent 9417064e61
commit df373faa82
24 changed files with 614 additions and 132 deletions
@@ -0,0 +1,20 @@
+# M03-C 地图选店与距离 API
+
+## `GET /app-api/stores`
+
+请求头：
+
+- `x-wechat-appid`
+- 多租户 AppID 时提供 `tenant-id`
+
+筛选参数：
+
+- `city`
+- `businessStatus`
+- `openNow=true|false`
+- `latitude` + `longitude`
+- `maxDistanceMeters`
+
+经纬度必须成对提供。距离由后端使用 Haversine 公式计算并排序，客户端不能提交或覆盖距离值。未授权定位时可仅传城市进行手工选店。
+
+营业中状态按门店时区、业务状态和每周营业时间计算，支持跨午夜营业时间。
@@ -0,0 +1,8 @@
+# M03-C 门店发现数据库变更
+
+- 迁移版本：`2026061809`
+- `qipai_stores` 新增 `city`、`district`
+- 新增租户/城市/营业状态索引
+- 新增租户/经纬度索引
+
+城市字段用于拒绝定位后的手工选店；经纬度仅作为后端距离计算输入，不接受客户端提供的伪造距离。
@@ -0,0 +1,29 @@
+# M03-C 地图选店与距离
+
+- 日期：2026-06-18
+- 起始 commit：`9417064`
+- 工程 commit：本阶段工程提交
+- ENGINEERING_DELTA=YES
+- 子阶段状态：待 push 与远端校验
+
+## 工程增量
+
+- 公开门店发现 API，按 AppID/tenant 绑定解析租户。
+- 后端 Haversine 距离计算、最近门店排序和最大距离筛选。
+- 城市、营业状态和实时营业中筛选。
+- 按门店时区和每周营业时间计算营业状态，支持跨午夜。
+- 小程序首页接入定位附近门店和手工城市查询；拒绝定位不会阻断选店。
+
+## 验证
+
+- Windows 全量 `npm test` 通过。
+- 小程序 JSON 解析和 JavaScript 静态语法检查通过。
+- WSL MySQL 8.4.9 `up → verify → down → up → verify` 通过。
+- 迁移语句：up 46、verify 29、down 43。
+- 实测同城筛选、距离排序、无匹配城市空结果。
+
+## 影响
+
+- 数据库迁移：`2026061809_m03c_store_discovery`。
+- 小程序新增固定域名门店查询封装。
+- 无新增环境变量和秘密。