HalfCart：基于LBS的1\.5km本地拼单系统全栈实践与踩坑复盘

HalfCart基于LBS的1.5km本地拼单系统全栈实践与踩坑复盘项目背景与定位本地即时拼单的需求一直存在但多数拼单场景要么依附于社群信息过载、履约无保障要么局限于大型电商平台履约周期长、无法覆盖即时性需求。HalfCart 瞄准的是 1.5km 半径内的邻里 / 商圈轻量拼单场景用户通过自然语言快速发布拼单平台基于地理位置做半径筛选与就近排序支持从发单、参团、支付到核销的完整闭环主打低门槛、快履约、强本地属性。本文从技术选型、核心链路实现、踩坑复盘三个维度完整复盘这个项目从 0 到 1 的落地过程。技术选型与整体架构项目处于 MVP 验证阶段选型核心原则是业务交付优先合理控制架构复杂度核心能力依赖成熟第三方服务不重复造轮子。整体采用前后端分离的轻量架构无复杂的分布式组件。后端技术栈Web 框架FastAPIPython。选择核心原因有三点一是 Python 生态对接第三方服务LLM、地图、支付的 SDK 最完善开发效率高二是原生支持异步、类型提示与自动 OpenAPI 文档接口联调成本极低三是 MVP 阶段 QPS 压力小性能完全满足需求。数据层MySQL 8.0 作为主存储承载用户、订单、支付、地址等核心业务数据Redis 用于接口限流、地理编码结果缓存与热点数据缓存降低第三方接口调用频次。消息队列RabbitMQ 承载异步通知、状态变更回调等非核心链路避免同步阻塞主业务流程。核心第三方能力Dify负责自然语言结构化解析实现 “说一句话就能发单”高德地图 LBS提供地理编码、步行距离计算、定位反欺诈能力微信公众号 OAuth实现微信生态内一键登录支付宝沙箱支付链路闭环验证。前端技术栈前端没有采用主流的 Vite Vue SPA 工程化方案而是主动选择了独立 HTML 多页面架构 CDN 引入 Vue3 Vant4。决策依据MVP 阶段页面数量有限19 个业务页面多页面架构改造成本低、迭代快修改即生效无需构建流程H5 场景下多页面首屏性能优于单页应用无打包体积问题弱网环境加载体验更好部署简单纯静态资源可直接托管无需前端构建流水线降低运维成本。公共逻辑请求封装、跳转工具、Token 管理统一抽离到common.js所有页面统一引入兼顾复用性与灵活性。核心技术实现1. 基于 LLM 的自然语言发单链路这是项目最核心的差异化能力用户无需逐个填写表单只需输入一段自然语言如 “今晚 8 点山姆拼瑞士卷差 3 人小区北门取人均 35”系统自动解析为标准化的拼单字段。链路设计原则解耦提取与校验Dify 工作流只负责一件事实体提取与结构化输出。通过优化后的提示词强制大模型输出固定 8 字段的 JSON 结构包含商品名称、拼单人数、人均价格、取货时间、取货地址、备注等同时输出置信度评分。后端负责所有规则校验人数下限校验、价格合法性校验、时间过期校验、地址二次标准化。业务规则不依赖大模型的概率性输出保证逻辑确定性。关键设计置信度分级置信度≥0.6 时自动填充表单低于阈值时仅做参考由用户手动确认降级兜底Dify 服务不可用时自动降级为纯手动表单发单不阻塞主流程字段强校验后端对返回的 JSON 做严格 Schema 校验字段缺失、类型错误时直接走降级逻辑避免脏数据入库。2. LBS 地理围栏与距离排序1.5km 半径筛选是产品的核心边界整套地理能力基于高德 Web 服务 API 实现。核心流程地理编码用户输入的文字地址转换为 GCJ-02 坐标系经纬度同时返回标准化地址解决用户输入地址模糊、不规范的问题批量距离计算拼单列表查询时基于用户当前坐标批量计算所有有效拼单的步行距离而非直线距离避免 “直线很近、实际隔河 / 隔高速” 的体验问题半径筛选与排序过滤步行距离≤1500 米的拼单按距离由近到远排序返回前端展示具体距离数值。稳定性设计Mock 模式本地开发默认开启 Mock无需真实 Key 即可联调业务逻辑避免调试消耗免费配额熔断机制连续调用失败达到阈值后触发熔断冷却期内自动走本地估算降级防止第三方服务故障拖垮主业务反欺诈校验基于定位速度、定位精度做基础反作弊拦截模拟定位、虚拟定位的异常请求。3. 多模式统一鉴权体系支持三种登录方式后端统一基于 JWT 鉴权前端无感知微信 OAuth 登录微信生态内主登录入口授权后自动创建 / 匹配账号登录即注册手机号验证码登录通用兜底登录方式首次登录自动静默注册生成默认昵称与账户用户无感知账号密码登录补充登录方式满足偏好密码登录的用户。配套机制前端统一请求拦截器自动注入 Bearer Token401 状态自动清空本地凭证并跳转登录页同时携带当前页面路径作为回跳参数页面级登录拦截除首页、详情页等游客可浏览的页面外其余页面初始化时强制校验 Token无权限自动跳转登录接口粒度权限控制团长专属操作核销、结束拼单在后端做身份校验前端仅做视图控制避免前端越权。踩坑复盘与解决方案落地过程中踩了不少意料之外的坑多数问题不在核心业务逻辑而在第三方对接与架构细节上。坑 1Dify 输出格式不稳定与变量映射错误问题初期试图把业务校验逻辑全部写入 Dify 提示词导致输出格式波动大字段时有时无工作流中代码节点与 LLM 节点的输出变量绑定错误频繁出现入参为空的情况排查成本极高。解决方案职责拆分Dify 只做结构化提取所有业务规则校验全部后置到后端用确定性代码替代大模型的概率性判断输出强约束提示词中强制指定 JSON Schema配合系统级输出格式约束大幅降低字段缺失、格式错误的概率后端二次校验对返回结果做全量 Schema 校验异常直接走降级不把不确定性传递给业务层。坑 2高德地图前后端密钥混用问题初期混淆了高德两类 Key 的用途将前端 JS API 的 Key 填入后端服务导致地理编码接口持续报权限错误排查了近两个小时才定位根因。解决方案双密钥隔离后端 Web 服务 Key 仅部署在服务端配置 IP 白名单前端 JS Key 仅用于页面地图渲染配置域名白名单二者物理隔离从架构上避免混用配置分层所有密钥统一通过环境变量管理代码中无硬编码前后端配置文件完全分离增加 Mock 层本地开发默认走 Mock 模式无需真实 Key 即可跑通全流程上线前再切换正式密钥。坑 3多页面架构下的跳转与状态治理缺失问题原型阶段为了快速出页面所有跨页跳转全部用console.log占位最终统计有 42 处占位逻辑导致核心流程完全无法推进同时各页面独立管理 Token登录状态不同步回跳逻辑混乱。解决方案公共层收敛封装全局goPage跳转工具与getQueryParam参数读取工具统一替换所有占位代码统一管理路径拼接与参数传递状态统一Token、用户信息统一存储在 localStorage公共 JS 统一初始化所有页面共享同一份状态回跳标准化跳转登录页时自动携带当前页面路径作为redirect参数登录成功后自动回跳无需每个页面单独处理。坑 4前后端字段对齐成本高问题后端字段以下划线命名goods_name前端初期按驼峰取值goodsName加上字段名拼写错误导致联调时大量接口 “通了但拿不到值”低级错误占比很高。解决方案约定命名规范前后端统一采用下划线命名从根源消除命名转换问题静态对齐审计联调前用脚本全量扫描前后端字段输出对齐清单提前发现拼写、类型不匹配问题统一请求封装前端 request 层统一做错误提示字段缺失时输出明确日志降低排障成本。一点架构思考做这个项目最大的感受是技术选型没有优劣只有是否匹配阶段。MVP 阶段最珍贵的是迭代速度而不是架构的 “优雅性”。多页面架构不如 SPA “标准”但它让前端开发效率提升了一倍用第三方服务做核心能力不如自研 “可控”但它让一个人就能在三周内跑通完整闭环。很多人做项目容易陷入架构焦虑总觉得不上微服务、不上工程化就是 “不专业”但对创业项目、个人项目而言能快速验证业务、跑通闭环才是第一优先级。当然这种轻量架构也有明确的边界如果后续用户量上涨、页面数量翻倍依然会向工程化 SPA、服务化拆分演进。但那是业务验证成功之后的事而不是现在。后续规划目前核心交易链路已全部跑通接下来的重点是三个方向一是完善拼单内聊天、履约通知等体验功能二是强化反作弊与风控能力治理虚假拼单与恶意定位三是优化前端交互细节提升移动端体验。等正式在小区落地跑一段时间再补一篇线上真实运行数据的复盘。部分图片演示