【标签】社会服务
【标题】【社会服务】邻里鲜生 - 社区团购四端一体电商平台 Demo
- Demo 简介
1.1 是什么
邻里鲜生是一个面向社区团购场景的四端一体移动端 Web 应用，采用浏览器直接访问的方式，无需下载安装 App。系统包含：
用户端：面向社区居民的购物消费端
团长端：面向社区自提点负责人的管理端
骑手端：面向配送人员的配送端
运营后台：面向平台管理者的全局管理端
技术架构上采用 Docker 单容器部署，首次启动时自动初始化数据库并填充演示数据，开箱即用。
1.2 面向谁
用户角色 核心需求 解决的痛点
社区居民 家门口的便捷购物，邻里互助 传统社区团购依赖微信群接龙，信息混乱；老人不会用 App、不敢绑卡；子女想远程照顾父母却力不从心
团长 高效管理社区订单和佣金 手工记账易出错、漏结；拼团状态靠脑子记；退款纠纷难处理
骑手 快速接单和配送，位置实时更新 配送路线不清晰；位置更新不及时导致用户反复询问
运营人员 全局掌控社区业务数据 社区数据分散、缺乏可视化看板；团长绩效难评估
1.3 项目规模
数据库：31 张表，覆盖用户、商品、订单、库存、佣金、拼团、骑手、优惠券、积分、退款等全链路数据模型
API 接口：76+ 个接口，RESTful 风格设计，JWT 无状态认证
代码量：约 9,500 行 JavaScript（后端 17 个路由文件 + 前端四端 23 个页面组件）
前端技术：原生 JavaScript 实现，零框架依赖，CSS 变量主题系统
1.4 核心功能
① 完整电商闭环 + 订单状态机
订单状态机严格遵循以下流转规则：
Plain Text
1
2
待付款(10) → 待配送(20) → 配送中(30) → 已送达(40) → 已完成(50)
→ 售后退款(60) / 已取消(99)
每个状态变更都写入 order_status_log 表，全链路可追溯
库存防超卖采用数据库事务 + 行级原子扣减，高并发下安全可靠
支持超时自动取消、自动确认收货等自动化流程
② 子女代付（银发关怀场景）
专门针对银发群体设计的代付功能，完整链路：
老人在用户端下单，选择"找人代付"
系统生成 Base64 编码的代付 token，生成分享链接
老人通过微信分享链接给子女
子女无需登录，直接打开链接查看订单详情
子女确认代付，事务内完成：订单状态更新 → 支付流水写入 → 库存扣减 → 销量更新 → 积分发放 → 会员等级升级 → 消息通知
演示模式下自动触发配送流程
核心价值：老人全程无需绑定银行卡，解决了银发群体线上购物的支付难题。
③ 实时地图追踪
基于 Leaflet + 高德地图瓦片实现三层地图能力：
地图能力 实现方式 说明
社区定位 浏览器 Geolocation API + Haversine 距离公式 根据用户位置匹配最近的社区自提点
地址选点 地图点击 + 反向地理编码 用户可在地图上直接选点，系统自动转换为地址文本
骑手追踪 3 秒轮询 + 标记移动动画 订单配送中实时显示骑手位置，地图上标记平滑移动
定位降级方案：浏览器定位失败 → 默认坐标匹配最近社区 → Mock 社区数据，确保用户不会卡在定位步骤。
④ 团长工作台
团长端提供完整的运营能力：
订单管理：派单、送达确认、订单状态追踪
佣金结算：支持并发安全（事务 + 唯一约束防重复结算），自动计算佣金
售后审批：同意退款自动回补库存 + 退还优惠券 + 扣减积分
拼团管理：查看拼团状态、到期自动退款
提现申请：申请提现、查看提现记录
⑤ 定时任务调度器
scheduler.js 实现 5 个核心定时任务，每分钟扫描执行：
任务 触发条件 执行动作
订单超时自动取消 15 分钟未支付 状态改为 99，释放锁定库存
配送超时自动确认 24 小时未确认收货 自动完成订单
佣金自动结算 订单完成后 结算团长佣金
拼团到期自动退款 拼团到期未成团 全额退款给参与者
优惠券过期失效 到达有效期结束时间 自动标记为已过期
⑥ 演示模式自动配送
delivery-simulator.js 在演示模式下，支付成功后自动走完配送全流程：
支付成功 → 3 秒后进入待配送状态
自动分配骑手 → 进入配送中状态
骑手位置每秒更新，模拟真实配送轨迹
到达目的地 → 自动送达 → 自动确认完成
用户可在订单详情页地图上看到骑手实时移动效果。
- Demo 创作思路
2.1 灵感来源
社区团购是高频刚需场景，但中小团长普遍缺乏数字化工具支撑。很多团长依赖微信群接单 + 手工记账，效率低下且容易出错。尤其是报名帖中描述的"老人下单、子女代付"场景深深触动了我——远在他乡的儿女通过一个链接就能照顾父母的餐桌，这是一个充满温情的社会服务场景。
2.2 想解决的问题
深入调研社区团购场景后，发现以下核心痛点——这些痛点区别于普通电商，是社区团购特有的邻里服务难题：
邻里信息孤岛：传统社区团购依赖微信群接龙，商品信息分散在不同群聊，居民要加多个群才能看全商品；团长在多个群回复消息，忙得不可开交
团长能力瓶颈：大多数团长是家庭主妇或退休老人，不会用复杂的管理软件，只能靠本子记账、计算器算佣金，经常漏算、错算
银发数字鸿沟：社区里大量老人想买东西，但不会下载 App、不敢绑定银行卡，子女又不在身边，只能眼睁睁看着别人方便购物
拼团信任危机：拼团到期后团长口头通知退款，经常拖延或忘记，引发邻里矛盾；团员不知道拼团进度，心里没底
自提体验差：到货后团长在群里发消息通知取货，老人错过消息就白跑一趟；不清楚商品是否到货、谁帮自己代买了东西
邻里互助无渠道：邻居之间想帮忙代买、代付，但没有安全的线上渠道，只能私下转账，缺乏信任感
2.3 为什么做这个方向
选择社区团购作为 Demo 方向，基于以下考量——这是一个充满社会温度的社区服务场景：
邻里属性强：社区团购不是冷冰冰的电商交易，而是建立在邻里信任基础上的互助行为，团长就是邻居，骑手可能也是小区住户，这种人情味是普通电商没有的
社会价值突出：解决银发群体的数字鸿沟问题，让老人也能享受线上购物的便利；通过子女代付功能，让远在他乡的儿女能照顾父母的餐桌，体现"千里之外的关爱"
业务链路完整：从商品浏览到售后退款，覆盖完整的电商闭环，能充分展示产品价值和技术能力
技术难点集中：包含状态机、并发库存、定时任务、地图集成、支付幂等、佣金结算、代付链路等典型后端技术难点
演示性强：流程清晰、反馈明确，评审能快速体验核心功能，感受社区服务的温暖
2.4 技术选型考量
技术 选型理由
better-sqlite3 嵌入式数据库，无需额外服务，Docker 单容器即可跑起，适合 Demo 快速部署
原生 JS 前端 零构建步骤，JS 文件直接引入即用，降低部署门槛，便于快速迭代
Leaflet + 高德瓦片 免费开源，国内访问稳定，避免 Google Maps 的访问限制
JWT 认证 无状态，适合四端共用一套 API，简化认证逻辑
Docker 单容器部署，环境一致性好，一键启动
3. Demo 体验地址
3.1 体验链接
反向代理域名，浏览器直接访问。Docker 单容器部署在香港服务器上，7x24 小时可用。
3.2 登录方式
方式 说明
体验模式 点击"
体验模式（免登录）“一键进入首页，自动使用演示用户
账号登录 手机号：13800138000，密码：123456
3.3 推荐体验路径
体验路径一：子女代付（核心亮点）
步骤 操作 预期效果
1 点击"体验模式"进入首页 看到商品列表、Banner 轮播、分类导航
2 浏览商品，选择商品加入购物车 购物车数量增加
3 点击底部"购物车"图标，进入购物车 看到已选商品列表
4 点击"去结算”，进入确认订单页面 看到地址、优惠券、配送费、实付金额
5 点击"找人代付"按钮 生成代付链接，弹窗显示链接并支持一键复制
6 复制链接，在新浏览器窗口打开 打开代付页面，显示下单人信息、商品明细、代付金额
7 点击"确认代付"按钮 代付成功，页面跳转成功提示
8 返回原窗口，进入订单列表 看到该订单状态变为"配送中"
9 点击订单进入订单详情 看到骑手实时位置地图，标记在移动
10 等待几秒后 订单自动送达，可确认收货
体验路径二：完整购物流程
步骤 操作 预期效果
1 浏览首页，点击商品进入详情 看到商品规格、价格、评价、详情图
2 选择规格，点击"加入购物车" 购物车数量增加
3 进入购物车，点击"去结算" 确认订单信息
4 选择优惠券，点击"提交订单" 订单创建成功
5 点击"立即支付" 支付成功，进入配送流程
6 订单详情页查看骑手位置 实时地图追踪
7 确认收货 订单完成，积分到账
3.4 其他端体验
端 地址 账号信息
团长端 邻里鲜生 · 团长工作台 手机号：13800138001，密码：123456
骑手端 邻里鲜生 · 骑手端 点击"体验登录"
运营后台 邻里鲜生 · 运营后台 用户名：admin，密码：admin123
4. TRAE 实践过程
4.1 整体开发流程
整个项目从需求评审到 Docker 部署，全程在 TRAE 中完成。TRAE 不是单纯的代码生成器，而是一个能理解项目全貌、持续迭代的 AI 工程伙伴。
4.2 关键开发阶段
第一阶段：全项目代码审查 —— 从文档到代码的一致性验证
目标：验证现有代码与 PRD、技术规格说明书的一致性
过程：
使用 TRAE 的 SearchCodebase 语义搜索能力，快速定位关键功能的实现位置
逐模块比对功能是否与技术文档一致实现
重点审查：订单状态机、库存扣减逻辑、售后退款流程、支付链路
发现的问题（共 17 个致命问题）：
订单状态机断裂（支付后卡在待配送，无自动流转）
下单-支付假闭环（未调用支付接口却显示成功）
售后退款完全未实现
库存超卖（无事务、无行级锁）
拼团订单无库存管控
定时任务全缺（订单超时、佣金结算、拼团退款等）
佣金结算并发冲突
骑手模块缺失
消息通知缺失
代付功能后端有接口但前端无入口
地图功能未实现
定位功能未实现
多个页面缺返回按钮（操作不闭环）
头像 URL 乱码显示
叶子节点页面无导航
个人信息无法编辑
数据源混乱（部分页面用 mock 而非 API）
第二阶段：逐项修复 —— 从断裂到闭环
目标：修复所有致命问题，构建完整的业务闭环
新增核心文件：
scheduler.js：5 个定时任务调度器，每分钟扫描执行
delivery-simulator.js：演示模式自动配送 + 骑手轨迹模拟
messages.js：消息通知模块，支持站内消息推送
rider.js：骑手模块，包含位置更新、配送分配逻辑
proxy.js：子女代付完整链路，支持代付链接生成和支付
关键修复：
支付接口改为调用后端 POST /orders/:no/pay，真正写入支付流水
库存扣减改为事务内 WHERE available_stock >= ? 原子操作，防止超卖
售后退款补全：申请 → 审批 → 退款 + 库存回补 + 优惠券退还 + 积分扣减
订单状态机补全：支付后自动进入待配送 → 模拟配送进入配送中 → 送达 → 自动确认完成
第三阶段：运行时错误排查 —— 从崩溃到稳定
目标：解决部署到服务器后的运行时问题
遇到的问题及解决方案：
问题 原因 解决方案
better-sqlite3 版本不匹配 Node 20 与编译版本不兼容 在 Docker 容器内重新编译 better-sqlite3
order_item 列名错配 sku_name vs name 统一列名为 sku_name
佣金结算并发唯一约束冲突 同一订单多次结算 事务内使用 INSERT OR IGNORE
warehouse_coverage 列缺失 建表语句不完整 补全建表语句
community_sku 表无数据 seed 脚本未初始化 补充 seed 数据
第四阶段：地图集成 —— 从零到三层地图能力
目标：实现社区定位、地址选点、骑手追踪三大地图能力
实现过程：
集成 Leaflet 1.9.4 地图库
使用高德地图瓦片源（webrd0{s}.is.autonavi.com），解决 OSM 瓦片国内访问慢的问题
实现 Haversine 距离公式进行社区匹配
实现骑手位置 3 秒轮询机制
踩坑记录：
OSM 瓦片国内访问慢 → 切换高德瓦片源
Leaflet SRI hash 校验失败 → 移除 integrity 属性
浏览器 geolocation 要求 HTTPS → 实现三级降级方案
第五阶段：用户体验闭环 —— 从功能可用到体验完整
目标：修复体验断点，完善操作闭环
修复内容：
补全订单详情、拼团列表、拼团详情 3 个页面的返回按钮
修复"我的"页面头像 URL 乱码（placehold.co 国内无法访问 → 改用 emoji 默认头像 + onerror 降级）
新增个人信息编辑功能（16 个预设 emoji 头像 + 昵称修改 + API 持久化）
完善代付功能入口（确认订单页"找人代付"按钮 + 订单详情页代付按钮 + 代付链接复制弹窗）
新增代付页面（无需登录即可访问，展示订单详情 + 一键代付 + 成功页）
底部 4 个 Tab 固定布局验证（CSS flex column + flex-shrink:0）
第六阶段：Docker 部署 —— 从本地到线上
目标：实现一键部署，确保环境一致性
部署配置：
Dockerfile：Node 20 Alpine 基础镜像 + better-sqlite3 编译 + 项目代码复制
docker-compose.yml：单服务 + 端口映射 + 数据卷持久化
docker-entrypoint.sh：启动时自动检查数据库，首次运行执行 seed.js 初始化
部署步骤：
通过 SSH 免密 scp 上传代码到服务器
执行 docker-compose up -d --build 重建容器
配置 Nginx 反向代理域名 linli.kozow.com
验证健康检查接口 /health 返回正常
4.3 关键任务对话 Session ID
以下 Session ID 可用于验证作品确实由 TRAE 开发完成：
Session ID 任务描述
6a475acca08e35d10a0b44f8 功能一致性排查与 17 项致命问题修复
3024088579987392:8e4c05d08ae9cb3cc8865d98d0d53f2c 地图集成与定位降级方案实现
3024088579987392:73cfb3ac32783619fbe70bcf5b8fbca2 子女代付功能开发与 Docker 部署
3024088579987392:3bc08a461e16d8a946abcc5ac4dfabab 用户体验闭环修复与功能完善
4.4 TRAE 使用心得
在整个开发过程中，TRAE 展现了以下核心价值：
代码理解能力：能够通读全项目代码，理解业务逻辑和技术架构
问题定位能力：通过语义搜索快速定位问题代码，提高排查效率
代码生成能力：根据需求生成高质量的代码，减少重复劳动
调试支持：协助排查运行时错误，提供解决方案
部署支持：编写 Docker 配置文件，实现一键部署
5. 技术架构
5.1 架构图
Plain Text
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
┌─────────────────────────────────────────────────────────┐
│ 浏览器端 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 用户端 │ │ 团长端 │ │ 骑手端 │ │ 运营后台 │ │
│ │ 原生 JS │ │ 原生 JS │ │ 原生 JS │ │ 原生 JS │ │
│ │ 响应式布局│ │ 响应式布局│ │ 响应式布局│ │ 管理后台 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │
│ └─────────────┴─────────────┴─────────────┘ │
│ │ Fetch + JWT │
└────────────────────────┼─────────────────────────────────┘
│
┌────────────────────────┼─────────────────────────────────┐
│ Docker 容器 (Node.js 20) │
│ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Express API (76+ 路由) │ │
│ │ │ │
│ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐│ │
│ │ │ 订单 │ │ 商品 │ │ 团长 │ │ 代付 │ │ 骑手 ││ │
│ │ │ 状态机│ │ 库存 │ │ 佣金 │ │ 链路 │ │ 配送 ││ │
│ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘│ │
│ │ │ │
│ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐│ │
│ │ │ 定时 │ │ 配送 │ │ 消息 │ │ 地图 │ │ 优惠 ││ │
│ │ │ 调度 │ │ 模拟 │ │ 通知 │ │ 服务 │ │ 券 ││ │
│ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘│ │
│ └───────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ better-sqlite3 (31 张表) │ │
│ │ 用户/商品/订单/库存/佣金/拼团/骑手/ │ │
│ │ 优惠券/积分/退款/消息/购物车/社区/地址… │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
5.2 技术栈
层次 技术 版本
后端框架 Express 4.18.2
数据库 better-sqlite3 11.3.0
认证 jsonwebtoken 9.0.2
密码加密 bcryptjs 2.4.3
地图 Leaflet 1.9.4
地图瓦片 高德地图 -
部署 Docker + docker-compose -
反向代理 Nginx -
5.3 数据库设计（31 张表）
模块 表名 说明
用户 user, user_address, user_message 用户信息、收货地址、站内消息
社区 city, community, warehouse, warehouse_coverage 城市、社区、前置仓、覆盖范围
商品 category, sku, sku_spec, community_sku 分类、商品、规格、社区商品
库存 inventory 仓库级库存（可用 + 锁定）
订单 order, order_item, order_status_log 订单、明细、状态流转日志
支付 payment_transaction 支付流水（支持幂等）
佣金 commission_settlement, leader_withdraw 佣金结算、提现记录
营销 coupon, user_coupon, point_transaction 优惠券、用户券、积分流水
拼团 group_buy, group_buy_participant 拼团活动、参与记录
配送 rider, rider_delivery, rider_warehouse 骑手、配送分配、骑手站点关联
售后 refund 退款记录
团长 leader, user_community 团长信息、用户社区关联
后台 admin_user, admin_role, admin_log 管理员、角色、操作日志
购物车 cart_items 购物车
报名帖链接
