# 商城 GUI

工具栏“工具 → 商城编辑器”优先打开当前归档的 `etc/cerashop.etc`，仅当该文件不存在时回退到 `etc/(r)cerashop.etc`，并切换 GUI 模式；两者都不存在时提示错误。也可手动打开商城文件后切换 GUI 模式。

## 浏览与编辑

- 一级页签遵循 `[shop button list and sequence]` 的顺序，“退出”作为关闭按钮；遗漏的非空商品类型补在后面，保证商品可以访问。
- 二级分类对应商品区段。卡片展示物品图标、名称、商品编号、物品编号、点券／金币价格、购买数量和非空日期参数。
- 工具栏“商品名／物品名”切换作用于所有商城页签，并在本次应用会话中保持。未配置商品名的时装优先回退到物品名，找不到名称时显示编号。
- 按住 Cmd／Ctrl 点击卡片上的物品编号，可在当前窗格打开对应的物品文件。
- 搜索匹配商品名、物品名和两种编号。物品名称分批加载；图标只查询当前页，卡片每页 60 件。
- 热卖与新品按 `[hotnew sell ipg]` 聚合；积分页按 `[specific product mileage]` 聚合，并非新增一种积分购买规则。商品售价和原有积分参数分开处理。
- 新增、编辑、删除在弹窗中进行。新增默认取现有商品最大编号加一，跳过已知历史引用占用的编号；可手动指定唯一的正整数编号。
- 普通道具提供数量、名称、金币、点券和日期参数；时装和礼包分别使用独立布局。其他参数保持原值，可展开编辑。
- 修改先进入编辑器草稿。“保存商城”写入工作区；保存 PVF 才会写入归档文件。

## 格式与保护

当前 110US 样本中普通道具、不可交易时装均为 14 字段，礼包为 13 字段。另通过同归档 `(f)cerashop.etc` 核对了可交易时装的 13 字段布局；不将其当作普通道具的数量和名称布局。

90CN 普通版 `etc/cerashop.etc` 按内容识别为旧版布局：时装 6 字段、道具 9 字段、礼包 11 字段、名称装饰 8 字段，角色服务礼包等采用独立字段映射。复活币、材料、恢复道具、魔王之契约、社区等分类一并展示，新增／编辑使用当前文件实际布局；旧版限购和按钮控制中的商品引用按原位置同步。

周边商品是外部链接记录，按只读卡片展示原始名称和价格参数，不套用点券单位。6 字段时装表尚未确认价格列，显示“未配置价格”，其类型及期限参数保留在其他参数中。`-1` 占位编号不作为重复商品编号，也不会在删除占位记录时移除其他引用。

TW 商城按内容识别为独立布局：道具 10 字段、礼包 10 字段，可交易／不可交易时装分别为 7／8 字段。保留配置中的独立“宠物”页签。`etc/cerashop.etc` 的真实样本有 133 件商品，`etc/cerashop_first.etc` 有 54,476 条记录；两个文件都可通过文件 GUI 打开，工具栏仍按普通版优先的既定规则选择文件。尚未确认的时装价格参数不作为售价展示。

首次打开优先选择配置顺序中有商品的页签，避免 TW 默认进入没有推荐配置的空“热卖与新品”页；手动选择的页签仍保留。

90CN 样本中商城导航的结束标签实际写作 `[/shop button and sequence]`，解析时将其匹配到 `[shop button list and sequence]`；编辑不会重写这一历史拼写。其他不匹配的标签仍会报错。

商品改号／删除同步以下已知商品编号引用：限购、购物车限制、赠送限制、仅赠送、不可叠加购买、立即生效商品、热卖、新品、默认推广页、指定商品积分、已购限购隐藏列表，以及 `storage`／`visible storage` 的仓库映射。不会改写物品编号或任意未知区段。

仅替换变化的 token，保留未知参数、未改动的区段、字符串类型标记及原始换行。重复编号、残缺记录、重复商品区段或类型不匹配均提示错误。无法识别的分类锁定编辑；存在未识别商品时，禁止新增、改号及删除，防止遗漏编号冲突或引用。

日期参数尚未确认代表过期时间，因此界面不将它标为“过期”或自动下架。价格列按此次样本分析映射，未确认的其他字段不赋予业务含义。

## 验证

```sh
cd frontend
npm test -- --run tests/cera-shop.test.ts tests/gui-launcher.test.ts
npm run build
```

真实样本回归通过 `PVF_CERA_TEXT` 指向从归档只读提取的目标脚本文本，避免将个人数据放进测试夹具：

```sh
PVF_CERA_TEXT=/path/to/cerashop.txt npm test -- --run tests/cera-shop.test.ts
```

普通版真实样本回归使用 `PVF_CERA90_LEGACY_TEXT`；90CN `(r)` 版使用 `PVF_CERA90_TEXT`，均指向只读导出的脚本文本。

TW 普通版和 first 版真实样本回归分别使用 `PVF_CERA_TW_TEXT`、`PVF_CERA_TW_FIRST_TEXT`，指向从归档只读导出的脚本文本。