智能快寄柜-03-+首页任务工单 模块分析

一、公共支撑基础模块（全局依赖，所有业务模块共用）

1.1 接口鉴权与限流子模块

1. 统一接口身份校验，拦截非法请求
2. 接口调用频次控制，防刷、防恶意调用
3. 异常请求拦截日志输出
4. 对应工单验收标准：安全 - 接口鉴权与频控生效

1.2 多级缓存子模块

1. 用户定位结果缓存，切换城市主动刷新
2. 全量城市列表全局缓存，提升检索速度
3. 寄存点热点区域数据缓存，降低 DB 压力
4. 寄存指南静态内容缓存
5. 缓存失效、更新策略统一封装

1.3 全链路日志 & 用户行为埋点子模块

1. 接口请求 / 响应日志记录（耗时、入参、出参、异常）
2. 用户操作埋点：定位、切换城市、搜索寄存点、查看指南
3. 日志持久化，用于业务数据分析、迭代优化
4. 工单要求：全链路记录埋点日志

1.4 数据存储与索引子模块

1. 数据表设计：城市信息表、寄存点表、寄存指南内容表
2. 索引设计：城市名称 / 拼音索引、寄存点地理位置空间索引、分页索引
3. 提供建表、索引初始化脚本
4. 数据 CRUD 通用封装工具

1.5 监控告警子模块

1. 接口性能指标采集：响应耗时、并发量、错误率
2. 性能阈值告警：定位接口 > 200ms、寄存点查询 P95>300ms 触发告警
3. 千级并发降级监控、异常大盘输出
4. 输出文档：监控指标与日志规范文档

1.6 通用工具能力子模块

1. 地理计算工具：两点直线距离计算
2. 分页统一封装工具
3. 多语言内容解析工具
4. 运营灰度下发工具（分批开放城市）
5. 接口版本兼容处理工具
6. 统一空状态、异常信息返回封装

二、模块 1：用户定位功能模块（首页基础前置模块）

2.1 定位获取子功能模块

1. 多渠道定位优先级控制：GPS 经纬度定位 > IP 定位
2. 定位解析：经纬度 / IP 转换为省份、城市名称、城市编码
3. 前端触发入口：首页「我的附近」自动定位、手动刷新定位按钮
4. 对外接口：获取当前城市定位接口

2.2 定位缓存管理子功能模块

1. 缓存存储本次定位城市信息，减少重复调用第三方定位服务
2. 缓存刷新触发规则：手动切换城市、手动点击重新定位
3. 标准化输出城市结构体（城市名、城市 code、省份）

2.3 定位异常降级子功能模块

1. 捕获异常场景：定位权限关闭、GPS 超时、IP 服务调用失败、网络异常
2. 降级兜底策略：返回系统默认城市
3. 异常日志埋点，记录失败原因用于优化

模块依赖：仅依赖公共支撑模块；输出数据供给城市选择、寄存点搜索模块

三、模块 2：城市选择管理功能模块

3.1 全量服务城市列表子功能模块

1. 查询系统所有已开通寄存柜服务的城市
2. 城市分组展示、运营灰度下发（分批次上线新城市，用户可见不同城市池）
3. 前端承载页面：独立选择城市弹窗 / 城市选择页
4. 接口：全量城市列表查询接口

3.2 城市检索子功能模块

1. 检索支持：中文模糊检索、拼音首字母检索
2. 检索结果过滤，仅展示当前用户灰度范围内城市
3. 接口：城市模糊搜索接口

3.3 用户城市切换子功能模块

1. 用户选中城市后，存储用户选择记录
2. 返回目标城市 ID、城市基础元信息给前端
3. 切换成功后自动联动触发寄存点重新查询
4. 行为埋点：记录用户切换城市操作

3.4 城市页面文案配置子功能模块

1. 未开通服务城市兜底提示文案
2. 年度城市拓展预告文案（2025 年内覆盖百城）
3. 文案后台可配置，实时生效无需发版

模块依赖：公共支撑模块 + 用户定位模块；输出城市 ID 给寄存点搜索模块

四、模块 3：寄存点地图搜索功能模块（核心业务模块）

4.1 寄存点条件检索子功能模块

1. 双维度查询条件：
   1. 维度 1：用户当前定位坐标（附近查询）
   2. 维度 2：用户输入关键词（车站 / 景点 / 商圈搜索）
2. 基于城市 ID 过滤，仅查询当前选中城市寄存点
3. 基于空间索引快速匹配点位
4. 接口：寄存点综合搜索接口

4.2 距离排序 & 分页子功能模块

1. 计算用户坐标与寄存点坐标距离
2. 检索结果按距离由近到远排序
3. 分页封装，批量返回寄存点基础信息：名称、地址、距离、空闲柜数量
4. 高并发性能优化，保障 P95 响应≤300ms

4.3 地图点位渲染子功能模块

1. 批量输出当前城市所有寄存点地图坐标标记
2. 地图选中寄存点，返回该点位完整详情卡片
3. 前端承载页面：首页查询寄存点跳转地图页面

4.4 空状态兜底子功能模块

1. 5km 范围内无寄存点时，返回空页面提示文案
2. 埋点记录无寄存点场景，支撑业务拓展分析

模块依赖：公共支撑模块 + 用户定位模块 + 城市选择模块

五、模块 4：寄存指南内容功能模块（运营内容模块）

5.1 指南内容查询子功能模块

1. 统一接口返回全套指引内容：寄存规则、操作流程、注意事项、常见问题
2. 前端承载：首页寄存指南入口、长图文详情页
3. 接口：寄存指南内容获取接口

5.2 后台动态配置子功能模块

1. 运营后台可视化编辑图文内容
2. 内容修改实时生效，无需服务端发版
3. 内容分层存储：步骤图、文字说明、提示文案分离配置

5.3 多语言 & 版本兼容子功能模块

1. 多套语言内容存储，根据用户区域自动匹配对应语言
2. 接口携带版本号，兼容新旧前端页面，平滑迭代不兼容问题