← 返回全部工具

智能餐卡平台

堂食餐补余额消费系统：顾客选店或扫商家收款码，输入金额与支付密码直接扣款；充值仅走微信；亲属账户可关联共用余额。无外卖、不选菜。

端 技术 说明
用户端 UniApp Vue3 H5 + 微信小程序
后端 FastAPI + SQLAlchemy + Alembic MySQL，JWT 鉴权
平台管理端 Vue3 + Element Plus + Vite 运营、财务、配置
商家后台 Vue3 + Element Plus + Vite 入驻、订单、提现

目录结构

├── backend/          # FastAPI 接口与静态资源
│   ├── app/
│   │   ├── api/      # user / admin / merchant / pay
│   │   ├── core/     # 配置、安全
│   │   ├── db/       # 会话、迁移入口
│   │   ├── models/   # 数据模型
│   │   └── services/ # 钱包、堂食支付、微信、短信、财务等
│   ├── migrations/   # Alembic 迁移
│   ├── static/       # 上传与静态文件
│   ├── .env          # 本地环境变量（勿提交密钥）
│   ├── run.py        # 启动入口（默认 8000）
│   └── seed.py       # 可选演示数据
├── uniapp/           # 用户端（HBuilderX 或 npm）
├── admin/            # 平台管理后台（默认 5173）
├── merchant/         # 商家独立后台（默认 5174）
└── docs/             # 需求/说明文档

本地端口

服务 地址
后端 API http://127.0.0.1:8000
健康检查 http://127.0.0.1:8000/api/health
平台管理端 http://127.0.0.1:5173
商家后台 http://127.0.0.1:5174
用户端 H5 http://127.0.0.1:8080

admin / merchant 开发服务器已将 /api、/static 代理到后端。

本地运行

前置

  • Python 3.10+（建议）
  • Node.js 18+
  • MySQL 8（或兼容版本）
  • 用户端可选：HBuilderX、微信开发者工具

1. 后端

cd backend
# 复制并编辑 .env（至少配置 DATABASE_URL、SECRET_KEY）
pip install -r requirements.txt
python run.py

首次启动会自动执行数据库迁移，并按 ADMIN_BOOTSTRAP_USER / ADMIN_BOOTSTRAP_PASSWORD 创建平台管理员（默认 admin / admin123）。

可选写入演示门店等数据：

cd backend
python seed.py

2. 平台管理端

cd admin
npm i
npm run dev

浏览器打开 http://127.0.0.1:5173 ，使用 bootstrap 管理员账号登录。

3. 商家后台

cd merchant
npm i
npm run dev

浏览器打开 http://127.0.0.1:5174 。新商家可在「入驻申请」提交，平台审核通过后登录经营。

4. 用户端 H5 / 微信小程序

接口基址见 uniapp/src/utils/config.js（默认 http://127.0.0.1:8000）。

方式 A — npm（H5）

cd uniapp
npm i
npm run dev:h5

方式 B — HBuilderX

用 HBuilderX 打开 uniapp/ 目录：

  • H5：运行到浏览器
  • 微信小程序：运行到微信开发者工具（需配置小程序 AppID）

构建 H5 预览示例：

cd uniapp
npm run build:h5
npm run preview:h5

环境变量（backend/.env）

变量 说明
DATABASE_URL MySQL 连接串，如 mysql+pymysql://user:pass@host:3306/db?charset=utf8mb4
SECRET_KEY JWT 等签名密钥，生产环境务必更换
ACCESS_TOKEN_EXPIRE_MINUTES JWT 登录有效分钟数，默认 10080（7 天）
USER_H5_BASE_URL 用户端 H5 根地址（商家收款码跳转；也可在平台「基础信息」配置）
ADMIN_BOOTSTRAP_USER / ADMIN_BOOTSTRAP_PASSWORD 首次启动创建的平台管理员
WX_OA_APPID / WX_OA_SECRET 微信公众号（H5 网页授权）
WX_OA_GH_ID / WX_OA_NAME 公众号原始 ID / 名称（展示用）
WX_MP_APPID / WX_MP_SECRET 微信小程序
WX_MCH_ID / WX_MCH_KEY 微信支付商户号与 API 密钥（v2）
WX_NOTIFY_URL 微信支付回调，如 http://host:8000/api/pay/wechat/notify
TENCENT_SMS_* 腾讯云短信（也可在平台后台填写，后台优先）

说明：

  • H5 不在微信内打开时，充值会提示到微信中操作。
  • 短信、微信相关配置多数可在平台管理端「平台配置」中维护；后台已填则优先于 .env。

功能概览

用户端

  • 注册 / 密码登录 / 短信登录、找回密码、换绑手机
  • 微信授权登录（H5 公众号 / 小程序）
  • 首页门店、入口图标、公告；门店列表与详情
  • 堂食付款：选店或扫码 → 金额 + 支付密码 → 扣餐补余额
  • 微信充值、账单、订单、卡券兑换
  • 账户关联（主账户添加亲属手机号，共用余额）
  • 支付密码设置、客服入口

平台管理端

  • 总览、平台配置（基础信息 / 短信 / 微信模板等）
  • 首页幻灯片、入口图标
  • 商户管理（入驻审核、状态、佣金、商家账号）
  • 用户余额（调账、批量调账）、账户关联查看
  • 堂食订单、批量充值（含 Excel）
  • 卡券营销、提现审核、财务报表、操作日志

商家后台

  • 入驻申请 → 待审 → 审核通过后经营
  • 经营概览、门店订单（可导出）
  • 提现申请、财务对账
  • 门店资料、下载收款码（二维码指向用户端付款页）

核心业务流程

堂食付款

  1. 选店：用户打开门店「堂食」→ 输入金额 + 支付密码 → 确认支付。
  2. 扫码：商家在「门店资料」下载收款码 → 顾客扫码进入该店付款页 → 输入金额 + 支付密码。
  3. 扣的是本人钱包；若该手机号已被主账户关联，则扣主账户余额。

首次支付前需在「我的 → 支付密码」设置 6 位数字支付密码。

充值

仅支持微信支付。回调地址为 WX_NOTIFY_URL（/api/pay/wechat/notify）。平台亦可批量充值 / Excel 导入。

账户关联

  • 账户关联：主账户添加亲属手机号。
  • 关联列表：查看已关联号码，主账户可解除。
  • 被关联用户消费时扣主账户余额。

商家入驻与提现

  1. 商家在商家后台提交入驻申请。
  2. 平台在「商户管理」审核通过并配置商家登录信息（如需要）。
  3. 堂食订单产生可结算金额后，商家发起提现，平台在「提现审核」处理。

技术说明

  • 启动时 Alembic 迁移自动执行（见 run.py lifespan）。
  • API 统一风格大致为 { code, message, data }；健康检查：GET /api/health。
  • 上传文件挂载在 /static。
  • 用户端默认定位参考坐标见 uniapp/src/utils/config.js（可按实际城市修改）。

生产注意

生产环境部署（Linux + Nginx + systemd）见 docs/部署文档.md。

  • 更换 SECRET_KEY、管理员初始密码；勿将真实 .env 提交仓库。
  • 配置公网 HTTPS 域名：USER_H5_BASE_URL、WX_NOTIFY_URL、微信授权回调域名与 JS 安全域名。
  • 微信支付、短信需在对应控制台完成商户与模板配置后再联调。
  • 前端生产构建：admin / merchant 使用 npm run build；用户端 H5 使用 npm run build:h5（或 HBuilderX 发行）。