集市茶铺

---
name: market-stall
description: 为独立品牌做一家能真正操作的小网店，成品是一个可离线打开的 HTML 文件，用井号路由：首页、可筛选的商品页、商品详情、会改变价格的选项、售罄选项、购物篮抽屉、优惠码、常见问题、专门设计的 404，以及不收款的演示结账。外观是手绘集市摊位，商品插图由代码按数据画出，不需要照片。当有人要做小店演示、店铺原型或小品牌网店，或点名要这个风格时使用。不能用来收真实款项。
version: 1.0.0
---

# 集市茶铺

外观和功能都在模板里。你要做的只是写一段 JSON，小店卖什么、说什么全部来自它。其余的由 `scripts/check.mjs` 把关。

具体的颜色、字体和每个插图参数，见 `references/style.md`。

## 需要问清楚的信息

需求里没有的，一次问完，放在同一条消息里。

必须有：
1. 店名，卖什么。
2. 商品：名称、一句话介绍、价格，以及规格或颜色等选项，每个选项加多少钱。
3. 哪些选项或商品已售完。
4. 这家店是真实的还是虚构的。

可以有：
5. 优惠码及其内容。
6. 配送方式和价格。
7. 常见问题的答案。
8. 配色季节：春、夏、秋、冬（`spring`、`summer`、`autumn`、`winter`）。默认用小店所在地当前的季节。
9. 语言：英文或中文。一个文件只用一种语言。

## 信息不够时

- **需求很单薄：** 用小店的口吻复述用户给的事实。绝不编造顾客、评价、评分、销量、奖项、产地或资质。把你推断出来的每一句话列给用户。
- **必填项没给（价格、商品名）：** 不要悄悄编。用明显标记的占位内容，比如商品名写“香型一（待定）”，价格用 10.00 这样的整数，并在回复里列在“待替换的占位内容”下。不要用 `[[...]]`，检查脚本会拒绝它。
- **信息卡内容少：** `facts` 可以只有一条，也可以为空，为空时信息卡不显示。用户没给的燃烧时长、重量、材料都不要写。`story` 一句话也行，120 字是上限，不是目标。
- **没人能回答：** 继续做，在 `notice`、`footer` 和一条常见问题回答里写明是虚构小店，并在回复里列出你的假设。
- **“三种香型、两个规格”：** 这是每种香型一款商品，共三款，每款带一个规格选项。有自己的名字和插图的，算单独商品；买家只是在同一样东西的不同版本里挑的，算选项。
- **篇幅不同：** 商品多少都行。首页那一排和首屏都按实际数量排版，一款、两款、三款都不会留空位。示例是 8 款。常见问题可以随意增减。`notes` 固定 3 条。
- **不知道所在地，选不了季节：** 用用户所在地当前的季节。这也不知道时，选商品所属的季节，在回复里说明，然后继续。
- **没有真实链接或收款方式：** 不需要链接，结账始终是演示。如果对方需要真实收款，直说这个模板做不到，把小店当作设计稿交给他们继续开发。

## 步骤

1. 写 `shop.json`。从 `assets/template.zh.html`（英文版用 `assets/template.html`）的 `shop-data` 段开始，每个占位符都写明了字数上限。金额一律用分：`1450` 就是 14.50。如果包里有 `example/shop.zh.json`，可以参考。
2. 按 `references/style.md` 选每款商品的 `draw` 参数。`kind` 要选真实的物件：蜡烛用 `candle`，不要用 `jar`。没有对应类型的商品一律用 `parcel`，并在交付说明里讲明，不要用相近的图充数，比如拿碗画烛台。给每个规格设 `draw.scale`（小 0.85，中 1，大 1.12），让插图随选项变化。
3. 生成：`node scripts/fill.mjs shop.json output.html --zh`，英文版去掉 `--zh`。不要手改 HTML。中文版每次改文字后都要重新运行，因为它只嵌入这些文字用到的招牌字体片段。
4. 检查：`node scripts/check.mjs output.html`，虚构小店加 `--fictional`。按报告修改，直到通过。
5. 实测：`node scripts/drive.mjs output.html --shots shots/`。它在真实浏览器里按遍每个控件，分别在动效开启、动效减弱和手机尺寸下运行，还会试长店名，以及只有一款、两款、三款商品的小店，大约需要一分半钟。有失败就修。
6. 亲眼看：用看图工具打开 `shots/` 里的截图，再自己打开每个商品页。每一页都要在电脑和手机尺寸下看过。看店名和商品名的断行，看价签有没有挡住标签。读着别扭就改文字或插图参数，不要动 CSS。

## 数据如何起作用

路由都写在地址的 `#` 之后：`#/` 首页，`#/shop` 商品页（筛选条件保留在这里，如 `#/shop?kind=green&stock=1&sort=low`），`#/p/商品id` 商品详情，`#/faq`，`#/checkout`，`#/order/单号` 演示单。其他地址一律显示专门设计的 404。

- **`featured: true`：** 前三款挂在首屏，前四款排在首页那一排。标记不足四款时，其余商品按摊位顺序补上。
- **`filters`：** 你写在 JSON 里的筛选，可以没有。同一组内多选会放宽结果，不同组之间会收窄结果。“是否有货”下的“只看有货”会自动加上，不要自己再写一个。只要某款商品还有一个版本能买，它就算有货。
- **售完：** 选项上的 `soldOut: true` 只挡这个选项。写在商品上，或者一组选项全部售完，就挡住整款商品。
- **`delivery`：** 一种或多种都行。`cost` 以分为单位，显示在说明之前，所以说明里不要重复这个金额（`check.mjs` 会查）。`freeOver` 表示购物篮达到这么多分后免费。`needsAddress: true` 表示选这一项时要填地址。
- **`promos`：** `kind` 可以是 `percent`（`value` 为 1 到 100）、`amount`（`value` 以分为单位）或 `freedelivery`（没有 `value`）。`min` 是可选的最低金额，以分为单位；不够时优惠码被拒绝，之后金额掉下来则优惠暂停。优惠码不分大小写，会忽略空格，一次只能用一个。

## 安装 Playwright

`check.mjs` 和 `fill.mjs` 只需要 Node 18 或更高版本。`drive.mjs` 需要 Playwright：运行 `npm install playwright` 和 `npx playwright install chromium`，然后在该文件夹下运行。如果装在别处，设置 `PLAYWRIGHT_FROM=/包含/node_modules/的路径`。同一时间只开一个浏览器。

## 交付内容

- `output.html`：整家店就是这一个文件，双击即可离线打开。英文版约 300 KB；中文版因招牌字体约 2 MB。
- `shop.json`：数据源，方便以后修改。
- 回复里写明：推断的内容、假设、可以试用的优惠码、测试了什么。

## 交付前检查

- [ ] `check.mjs` 通过。
- [ ] `drive.mjs` 通过，动效开启和减弱都测过。
- [ ] 每一页都看过电脑和手机尺寸的真实截图。
- [ ] 应该改变插图的规格或选项确实改变了插图。
- [ ] 没有用户未提供的说法：没有评价、没有销量、没有资质。
- [ ] 虚构小店在横幅、页脚和常见问题里都写明了。
- [ ] 文件里只有一种语言。
- [ ] 用户能找到优惠码，通过 `promoHint` 或常见问题。
- [ ] 回复里列出了推断的内容和假设。

## 什么时候不要用

- 小店要收真实款项或接真实订单。这里什么都不会发送出去，库存就是 JSON 里写的。
- 商品必须用照片展示，比如服装上身效果或艺术品。
- 商品超过约 60 款，或库存每小时都在变。
- 必须用品牌自己的视觉。这个包的外观是固定的，这正是它的设计。

## 运行要求

脚本需要 Node 18 或更高版本，`drive.mjs` 还需要 Playwright，查看成品用任意较新的浏览器。成品不发出任何外部请求。字体均为开放授权，列在 `assets/fonts-license.txt` 里，请把授权文件和包放在一起。