Refresh MatrixShop goods repository documentation

Author: 54895y

docs/matrixshop/configuration-structure.mdx

@@ -171,6 +171,10 @@ playerpoints:
 - `shops/*.yml`
 - `ui/*.yml`
 
+`SystemShop` 还额外包含：
+
+- `goods/*.yml`
+
 个别模块还带有额外文件：
 
 - `ChestShop/signs.yml`
@@ -203,6 +207,7 @@ playerpoints:
 - 静态按钮
 - 动态槽位
 - 商品模板
+- 对 `SystemShop/goods/*.yml` 的商品引用
 
 同时，**当前实现里 `shopId` 以文件名为准**。
 

docs/matrixshop/economy-examples.mdx

@@ -104,20 +104,29 @@ Currency:
   Key: vault
 
 goods:
-  iron_sword:
-    material: 'IRON_SWORD'
-    amount: 1
-    price: 120
-    buy-max: 16
-    name: '&f铁剑'
-
-  diamond_sword:
-    material: 'DIAMOND_SWORD'
-    amount: 1
-    price: 420
-    currency: playerpoints
-    buy-max: 8
-    name: '&b钻石剑'
+  - iron_sword
+  - diamond_sword
+```
+
+```yml
+# SystemShop/goods/iron_sword.yml
+id: iron_sword
+material: 'IRON_SWORD'
+amount: 1
+price: 120
+buy-max: 16
+name: '&f铁剑'
+```
+
+```yml
+# SystemShop/goods/diamond_sword.yml
+id: diamond_sword
+material: 'DIAMOND_SWORD'
+amount: 1
+price: 420
+currency: playerpoints
+buy-max: 8
+name: '&b钻石剑'
 ```
 
 最终效果：

docs/matrixshop/economy.mdx

@@ -117,11 +117,17 @@ vault
 当前主要体现在 `SystemShop`：
 
 ```yml
+# SystemShop/shops/weapon.yml
 goods:
-  diamond_sword:
-    material: 'DIAMOND_SWORD'
-    price: 420
-    currency: playerpoints
+  - diamond_sword
+```
+
+```yml
+# SystemShop/goods/diamond_sword.yml
+id: diamond_sword
+material: 'DIAMOND_SWORD'
+price: 420
+currency: playerpoints
 ```
 
 ### 商店级
@@ -171,7 +177,7 @@ Currency:
 
 - `SystemShop` 默认使用金币
 - `Auction/default.yml` 使用点券
-- `SystemShop/shops/weapon.yml` 下某把武器单独使用点券
+- `SystemShop/goods/diamond_sword.yml` 单独使用点券
 
 可以这样写：
 
@@ -187,10 +193,15 @@ Currency:
   Key: vault
 
 goods:
-  diamond_sword:
-    material: 'DIAMOND_SWORD'
-    price: 420
-    currency: playerpoints
+  - diamond_sword
+```
+
+```yml
+# SystemShop/goods/diamond_sword.yml
+id: diamond_sword
+material: 'DIAMOND_SWORD'
+price: 420
+currency: playerpoints
 ```
 
 ```yml

docs/matrixshop/modules-overview.mdx

@@ -13,7 +13,7 @@ description: MatrixShop 各模块职责、默认文件和详细文档入口。
 | --- | --- | --- | --- |
 | `economy` | 统一货币定义与结算入口 | `Economy/currency.yml` | [经济模块](./economy) |
 | `menu` | 总入口导航菜单 | `Menu/settings.yml`、`Menu/shops/main.yml` | [Menu](./shop-types/menu) |
-| `system-shop` | 静态系统商店 | `SystemShop/settings.yml`、`SystemShop/shops/*.yml` | [SystemShop](./shop-types/system-shop) |
+| `system-shop` | 静态系统商店 | `SystemShop/settings.yml`、`SystemShop/goods/*.yml`、`SystemShop/shops/*.yml` | [SystemShop](./shop-types/system-shop) |
 | `player-shop` | 玩家个人商店 | `PlayerShop/settings.yml`、`PlayerShop/shops/default.yml` | [PlayerShop](./shop-types/player-shop) |
 | `global-market` | 全服共享市场 | `GlobalMarket/settings.yml`、`GlobalMarket/shops/default.yml` | [GlobalMarket](./shop-types/global-market) |
 | `auction` | 拍卖行 | `Auction/settings.yml`、`Auction/shops/default.yml` | [Auction](./shop-types/auction) |
@@ -54,7 +54,7 @@ description: MatrixShop 各模块职责、默认文件和详细文档入口。
 为了避免把 MatrixShop 理解成“所有模块都完全一样”，这里再强调一次：
 
 - `Economy` 负责统一货币定义，不建议在业务模块里重复实现结算逻辑。
-- `SystemShop` 主要是静态 YAML 商品。
+- `SystemShop` 主要是静态 YAML 商品，推荐用 `goods/*.yml` + `shops/*.yml` 引用。
 - `PlayerShop`、`GlobalMarket`、`Auction` 主要是运行时上架数据。
 - `ChestShop` 有箱子、库存、告示牌这套线下交互。
 - `Transaction` 不是商品市场，而是面对面交换。

docs/matrixshop/quick-start.mdx

@@ -31,6 +31,9 @@ plugins/MatrixShop/
 ├─ Economy/
 ├─ Menu/
 ├─ SystemShop/
+│  ├─ goods/
+│  ├─ shops/
+│  └─ ui/
 ├─ PlayerShop/
 ├─ GlobalMarket/
 ├─ Auction/
@@ -46,6 +49,10 @@ plugins/MatrixShop/
 - `shops/*.yml`
 - `ui/*.yml`
 
+`SystemShop` 还会额外包含：
+
+- `goods/*.yml`
+
 但有三个例外：
 
 - `ChestShop/`：不再使用 `shops/*.yml`，只保留 `settings.yml`、`signs.yml` 和 `ui/*.yml`

docs/matrixshop/release-notes-1-2-0.mdx

@@ -13,6 +13,8 @@ description: MatrixShop 1.2.0 的新增功能、管理员商品维护流程和
 
 这一版的重点不是调整玩家侧业务链，而是补齐管理员对 `SystemShop` 商品的快速维护能力。
 
+> 后续主线版本已经把管理员商品流拆成 `goods save` 与 `goods add` 两步，并把商品定义优先存放到 `SystemShop/goods/*.yml`。本页保留的是 `1.2.0` 发布当时的原始流程说明。
+
 ## 本版本重点
 
 ### 管理员快速上架

docs/matrixshop/shop-types/system-shop.mdx

@@ -1,6 +1,6 @@
 ---
 title: SystemShop
-description: SystemShop 的默认配置、分类文件和商品字段解释。
+description: SystemShop 的默认配置、goods 目录、分类引用和管理员维护方式。
 ---
 
 # SystemShop
@@ -10,6 +10,7 @@ description: SystemShop 的默认配置、分类文件和商品字段解释。
 ## 默认文件
 
 - `SystemShop/settings.yml`
+- `SystemShop/goods/*.yml`
 - `SystemShop/shops/weapon.yml`
 - `SystemShop/shops/food.yml`
 - `SystemShop/shops/material.yml`
@@ -121,7 +122,7 @@ icons:
 
 ## `SystemShop/shops/weapon.yml`
 
-这是最关键的商品分类配置文件。`food.yml` 和 `material.yml` 的结构与它一致。
+分类文件负责页面布局、模板和商品引用。推荐写法如下：
 
 ```yaml
 id: weapon
@@ -165,47 +166,15 @@ template:
     - ''
     - '&e左键进入购买确认'
 
+Currency:
+  Key: vault
+
 goods:
-  wooden_sword:
-    material: 'WOOD_SWORD'
-    amount: 1
-    price: 25
-    buy-max: 16
-    name: '&f木剑'
-    lore:
-      - '&7入门级近战武器'
-  iron_sword:
-    material: 'IRON_SWORD'
-    amount: 1
-    price: 120
-    buy-max: 16
-    name: '&f铁剑'
-    lore:
-      - '&7稳定的主力武器'
-  diamond_sword:
-    material: 'DIAMOND_SWORD'
-    amount: 1
-    price: 420
-    buy-max: 8
-    name: '&b钻石剑'
-    lore:
-      - '&7高品质近战武器'
-  bow:
-    material: 'BOW'
-    amount: 1
-    price: 180
-    buy-max: 8
-    name: '&6弓'
-    lore:
-      - '&7远程作战基础装备'
-  arrow_bundle:
-    material: 'ARROW'
-    amount: 16
-    price: 32
-    buy-max: 64
-    name: '&f箭矢 x16'
-    lore:
-      - '&7远程消耗品补给'
+  - wooden_sword
+  - iron_sword
+  - diamond_sword
+  - bow
+  - arrow_bundle
 ```
 
 ### 顶层字段解释
@@ -217,20 +186,40 @@ goods:
 | `layout` | `g` 是动态商品槽位，`I` 是说明，`R` 是返回。 |
 | `icons` | 静态图标定义。 |
 | `template` | 所有动态商品统一使用的名称和 Lore 模板。 |
-| `goods` | 静态商品列表。 |
+| `Currency.Key` | 当前分类的默认货币 key。 |
+| `goods` | 当前分类引用的商品 id 列表。 |
+
+## `SystemShop/goods/diamond_sword.yml`
+
+商品文件负责真正的商品定义：
 
-### `goods.*` 字段解释
+```yaml
+id: diamond_sword
+material: 'DIAMOND_SWORD'
+amount: 1
+price: 420
+buy-max: 8
+name: '&b钻石剑'
+lore:
+  - '&7高品质近战武器'
+```
+
+### 商品字段解释
 
 | 字段 | 说明 |
 | --- | --- |
+| `id` | 商品 id，通常与文件名一致。 |
 | `material` | 商品材质。 |
+| `item` | 更高保真的物品定义，可覆盖基础材质展示。 |
 | `amount` | 每次购买给多少个。 |
 | `price` | 单次交易价格。 |
 | `buy-max` | 单次购买的最大数量或上限展示值。 |
 | `name` | 商品显示名。 |
 | `lore` | 商品说明。 |
 | `currency` | 商品级货币 key。可选；只有你想覆盖默认货币时才需要写。 |
 
+> 兼容说明：旧版 `SystemShop/shops/*.yml` 中直接内联 `goods.<id>` 的写法仍然可读取，但新配置应优先拆到 `SystemShop/goods/*.yml`。
+
 ## 当前货币优先级
 
 `SystemShop` 当前采用：
@@ -240,10 +229,31 @@ goods:
 3. `SystemShop/settings.yml` 里的 `Currency.Key`
 4. 默认回退 `vault`
 
+## 管理员商品维护
+
+当前后台命令流已经拆成两步：
+
+1. 保存商品定义到 `goods` 仓库
+2. 把已保存商品挂到某个系统商店分类
+
+命令如下：
+
+- `/matrixshopadmin goods ui [page]`
+- `/matrixshopadmin goods save <price> [buy-max] [product-id]`
+- `/matrixshopadmin goods add <category> <product-id>`
+- `/matrixshopadmin goods select <category> <product-id>`
+- `/matrixshopadmin goods edit <price|buy-max|currency|name|item|remove> ...`
+
+其中：
+
+- `goods save` 只写 `SystemShop/goods/*.yml`
+- `goods add` 只负责把商品 id 引用进分类文件的 `goods:`
+- `goods edit remove` 只会把商品从当前分类下架，不会删除 `goods` 仓库里的文件
+
 ## 你应该怎么改
 
 - 想新增一个分类：复制一份 `shops/weapon.yml`，改文件名，再把 `ui/shop.yml` 的按钮指过去。
-- 想新增一个商品：直接在 `goods:` 下加一项。
+- 想新增一个商品：新建 `SystemShop/goods/<product-id>.yml`，然后把 id 加到对应分类的 `goods:` 列表里。
 - 想改默认打开的分类：改顶层 `config.yml` 的 `system-shop.default-category`。
 
 ## 相关文件
@@ -252,4 +262,4 @@ goods:
 - `SystemShop/shops/material.yml`
 - `SystemShop/ui/confirm.yml`
 
-通常先改 `shops/*.yml`，只有在你想重做分类入口和确认流程时，才需要再动 `ui/*.yml`。
+通常先改 `goods/*.yml` 和 `shops/*.yml`，只有在你想重做分类入口和确认流程时，才需要再动 `ui/*.yml`。