点餐小程序一键生成
给一个餐饮商家，产出一套能直接跑、能直接上线的微信点餐小程序：顾客扫码点单，商家在同一个
小程序里接单、改菜单、看经营数据。不需要从零写代码 —— 复制模板工程 + 按客户信息替换 + 建库即可。
产出
| 端 | 内容 |
|---|---|
| 顾客端 | 首页（轮播 + 推荐 + 门店）／点单（分类 + 菜品）／菜品详情（规格 + 辣度）／购物车（堂食·外带）／订单记录／订单详情／门店选择 |
| 商家端 | 概览（今日 KPI + 待办）／订单（接单·出餐·完成·取消）／菜单（菜品·分类·广告图增删改排序换图）／数据（今日·近 7 天·近 30 天·自定义）／我的（员工与手机号、外带取餐时间点） |
| 后端 | 7 张表 + RLS + 18 个 SECURITY DEFINER 函数，手机号 OTP 登录 + 绑定码认领 |
| 工程 | 微信原生小程序，WorkBuddy 云服务（数据库 / 存储 / 登录），含测试与版式复现脚本 |
模板来自一个已上线运营的麻辣香锅品牌，页面结构、交互细节、统计口径都经过真机验证。
什么时候用
- 用户要给自己的餐厅 / 咖啡馆 / 奶茶店做点单小程序
- 用户要一个「像某某点餐」的小程序，或要二维码点餐、自取预约
- 用户已有小程序，要换品牌、换菜单、加门店
- 用户问「点餐小程序怎么做」「帮我搭个点单系统」
不适合：纯外卖平台对接（美团/饿了么）、需要在线支付的场景（本模板支付接口留空，走「到店支付 / 餐后结账」）。
工作流
Step 0 · 先问清三件事
缺了就问，别猜：
- 品牌名（招牌上那几个字）+ 主营品类（如「麻辣香锅」「粤式点心」）
- 门店：几家、店名、地址、营业时间、电话、大致经纬度
- 菜单：几个分类、每类有哪些菜、价格、哪些是招牌
如果这三项一时拿不全，先用内置示例跑通全链路（3 家门店 / 4 分类 / 10 道菜），
再让用户对着真实小程序提「把 A 改成 B」，比等着收集齐更快。
Step 1 · 准备 spec（可选）
不传 --spec 就用 assets/seed/demo-menu.json。要换真实内容时，复制它改这几段：
{
"brand": "京慧源", "cuisine": "麻辣香锅", "phone": "010-65058812", "packFee": 2,
"stores": [{ "id": "store_guomao", "name": "…", "address": "…", "latitude": 39.9,
"longitude": 116.4, "business_hours": "10:00-22:00",
"tags": ["…"], "notice": "…", "sort": 1, "takeaway_slots": ["11:30"] }],
"categories": [{ "id": "cat_signature", "name": "招牌香锅", "description": "…", "sort": 1 }],
"dishes": [{ "id": "dish_001", "category_id": "cat_signature", "name": "…", "price": 78,
"image": "/assets/dishes/d01.jpg", "spicy": 3, "is_recommend": true,
"spec_label": "份量", "specs": { "size": [], "spicy": ["微辣","中辣"] },
"sort": 1, "monthly_sales": 0 }],
"merchants": [{ "phone": "13800138000", "name": "店主", "role": "owner",
"store_id": "", "claim_code": "888888" }]
}
脚本会自动校验：菜品 category_id 必须存在于分类里、价格必须是数字、id 不能重复。
Step 2 · 生成工程
python <skill>/scripts/init_project.py \
--target /abs/path/<project> \
--brand "蜀香居" --cuisine "川菜" --phone "021-88886666" \
--project shuxiangju-miniprogram \
--spec /abs/path/menu.json \
--application-id wbapp_xxx --publishable-key wbpk_xxx
| 参数 | 说明 |
|---|---|
--target |
生成到哪（必填，非空加 --force） |
--spec |
菜单 JSON，默认 assets/seed/demo-menu.json |
--brand / --cuisine / --phone |
覆盖 spec 里的品牌信息，同时改门店名与广告文案 |
--project |
工程名，写进 package.json / project.config.json |
--application-id |
云服务应用 ID，用于重命名隐私声明文件 .<id>.privacy.json |
--publishable-key |
云服务 publishableKey，写进 miniprogram/utils/public-config.js |
--wechat-appid |
微信小程序 AppID，默认 touristappid（游客模式，发布前要换） |
--dry-run |
只打印计划不落盘 |
生成物：完整工程 + db/00_setup_all.sql（建库）+ db/02_seed.sql（种子）+ README.md。
先 --dry-run 看一遍，确认门店数、菜品数、目标路径都对再真跑。
Step 3 · 建库（两条 SQL，顺序不能反）
在云服务应用下依次执行，都是单条语句，整份丢进去即可，不要逐句拆：
| 顺序 | 文件 | 模式 | 作用 |
|---|---|---|---|
| 1 | db/00_setup_all.sql |
migrate |
7 表 + 索引 + RLS + 18 个函数 + 授权 |
| 2 | db/02_seed.sql |
write |
门店 / 分类 / 菜品 / 广告图 / 商家账号 |
两条都幂等，可反复执行。注意第 2 条会把库里同名 id 的内容覆盖成 spec 里的值 ——
商家已经在后台改过菜单后，不要重复跑种子，改内容走商家后台。
exec_sql 一次只接受一条语句，本文件的 DO $$ … $$ 外层就是为此设计的，保持整份。
Step 4 · 配云 + 自检
miniprogram/utils/public-config.js填publishableKey（endpoint是平台固定网关，不要改）- 自检（不需要真机、不联云，用
wx桩拦请求）：
cd <project> && npm install
node scripts/test-order.js # 18 项：下单 / 计价 / 状态流转
node scripts/test-merchant.js # 115 项：商家数据层 + 统计聚合
node scripts/test-img.js # 29 项：图片三态解析
三个都必须 0 FAIL。改过 utils/ 下任何文件后重跑一遍，比开模拟器快得多。
Step 5 · 交付与上线
用微信开发者工具导入工程目录（miniprogramRoot 已配好，miniprogram_npm/ 随工程提供）。
发布走应用面板，不要引导用户去开发者工具上传或公众平台提审 —— 详见 references/publish.md。
三条硬约束
改这套代码时，下面三条一旦违反，小程序不会报错但会「静默坏掉」：
dishes.category_id必须指向存在的分类。 点单页是「遍历分类 → 过滤菜品」，
分类被删或 id 写错，那些菜直接不显示，不报错、控制台干净，极难排查。- 图片地址绝不要把签名 URL 回写数据库。 WorkBuddy 云存储不提供公开 URL，只有 1–3600 秒
签名链接；库里只存shared/<uid>/…原始路径，渲染前由utils/img.js换签名地址。 - 金额与数字字段不要写成字符串。
config.js的PACK_FEE要参与金额运算，
写成'2'会在+时变成字符串拼接，算出"2108"这种金额。
内容改动导航
上线后绝大多数需求不用改代码、不用发版：
| 想改什么 | 去哪 |
|---|---|
| 菜名 / 价格 / 图片 / 上下架 / 排序 | 商家后台 →「菜单」→ 菜品 |
| 增删分类 | 商家后台 →「菜单」→ 分类 |
| 首页轮播图与文案 | 商家后台 →「菜单」→ 广告图 |
| 外带可选的取餐时间点 | 商家后台 →「我的」→ 门店取餐时间 |
| 单笔外带订单的取餐时间 | 商家后台 → 订单卡片 |
| 员工与绑定码 | 商家后台 →「我的」→ 员工 |
| 页面结构、配色、交互、支付 | 改代码 + 发版 |
参考文档
| 文件 | 什么时候读 |
|---|---|
references/architecture.md |
要改代码、加页面、理解数据流时 |
references/data-model.md |
要改表结构、加字段、调统计口径时 |
references/pitfalls.md |
改任何东西之前都要扫一眼，全是踩过的坑 |
references/publish.md |
建库、开通云服务、发布上线时 |
references/schema.md |
建库 SQL 在哪、为什么是一整条 DO 块、怎么改表结构 |
模板资产
| 路径 | 说明 |
|---|---|
assets/template/ |
模板工程密封件。index.json 是清单，part-001.json … part-009.json 是分片，密封了 138 个文件（8 个页面、商家后台、云 SDK、图片、sql/ 下全部 DDL）。文本文件按原文存，48 张图片走 base64 |
assets/seed/demo-menu.json |
示例菜单（3 门店 / 4 分类 / 10 道菜） |
assets/README.template.md |
生成工程时写入的 README 模板 |
scripts/pack_template.py |
分片的解封 / 回封 / 校验工具 |
为什么模板不是 zip、不是散目录：技能市场的服务端白名单只收文本文件。
.wxss / .wxml / .sql 这类小程序专有后缀会被拒（不允许的文件类型），
zip 和图片这类二进制也会被拒（禁止上传二进制文件）。所以整份工程只能密封进 .json 分片，
init_project.py 读的是分片，不是 zip —— 别去 assets/ 里找 template.zip，它已经不存在了。
要改模板内容，走「解包 → 改 → 回封」：
python scripts/pack_template.py --unpack /tmp/tpl # 解到临时目录
# ... 在 /tmp/tpl 里改，建议先用 init_project.py 生成一份跑通再搬回来
python scripts/pack_template.py --pack /tmp/tpl # 回封成 part-*.json
python scripts/pack_template.py --verify # 校验文件数 / 总字节 / 每片 sha256
技能目录下只保留 .md / .py / .json 三种扩展名 —— 上传到技能市场前，
确认 find . -type f ! -name '*.md' ! -name '*.py' ! -name '*.json' 没有输出。
