Skip to content

Commit 7e1a1a0

Browse files
author
54895y
committed
docs: expand MatrixShop module configuration guides
1 parent 76e705f commit 7e1a1a0

15 files changed

Lines changed: 1970 additions & 94 deletions

‎docs/matrixshop/configuration-structure.mdx‎

Lines changed: 134 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,114 @@
11
---
22
title: 配置结构
3-
description: MatrixShop 当前版本的目录布局与文件职责。
3+
description: MatrixShop 顶层配置、模块目录和入口文件的详细结构说明。
44
---
55

66
# 配置结构
77

8-
当前 MatrixShop 不是“一个总配置 + 一堆平铺子目录”的结构，而是三层配置：
8+
当前 MatrixShop 的配置不是“一个总配置文件解决所有问题”，而是三层：
99

10-
- 顶层全局文件
11-
- 模块目录
12-
- 模块内的 `settings.yml`、`shops/*.yml`、`ui/*.yml`
10+
1. 顶层全局文件
11+
2. 模块目录
12+
3. 模块内部的 `settings.yml`、`shops/*.yml`、`ui/*.yml`
1313

1414
## 顶层文件
1515

16-
| 文件 | 作用 |
16+
### `config.yml`
17+
18+
```yaml
19+
debug: false
20+
21+
system-shop:
22+
default-category: weapon
23+
24+
messages:
25+
no-permission: '&c你没有权限执行这个操作。'
26+
player-only: '&c该命令只能由玩家执行。'
27+
```
28+
29+
字段解释：
30+
31+
| 字段 | 说明 |
32+
| --- | --- |
33+
| `debug` | 是否输出调试信息。生产服通常保持 `false`。 |
34+
| `system-shop.default-category` | 系统商店直接打开时默认进入的分类。这里的值要和 `SystemShop/shops/<file-name>.yml` 对应。 |
35+
| `messages.no-permission` | 无权限时的提示。 |
36+
| `messages.player-only` | 非玩家执行命令时的提示。 |
37+
38+
### `module.yml`
39+
40+
```yaml
41+
modules:
42+
menu: true
43+
system-shop: true
44+
player-shop: true
45+
global-market: true
46+
auction: true
47+
chestshop: true
48+
transaction: true
49+
cart: true
50+
record: true
51+
```
52+
53+
字段解释：
54+
55+
| 字段 | 说明 |
1756
| --- | --- |
18-
| `config.yml` | 调试、默认系统商店分类、基础消息 |
19-
| `module.yml` | 九个模块的启用状态 |
20-
| `database.yml` | SQLite / MySQL 数据层配置 |
57+
| `modules.menu` | 是否启用导航菜单模块。 |
58+
| `modules.system-shop` | 是否启用系统商店。 |
59+
| `modules.player-shop` | 是否启用玩家商店。 |
60+
| `modules.global-market` | 是否启用全球市场。 |
61+
| `modules.auction` | 是否启用拍卖行。 |
62+
| `modules.chestshop` | 是否启用箱子商店。 |
63+
| `modules.transaction` | 是否启用面对面交易。 |
64+
| `modules.cart` | 是否启用购物车。 |
65+
| `modules.record` | 是否启用账本记录。 |
66+
67+
最实用的理解方式是：这里控制的是“模块总开关”。如果你把某个模块关掉，即使该模块目录里的配置还在，入口也不会正常工作。
68+
69+
### `database.yml`
70+
71+
```yaml
72+
Database:
73+
Type: SQLITE
74+
75+
SQLite:
76+
File: 'Data/data.db'
77+
78+
MySQL:
79+
Host: '127.0.0.1'
80+
Port: 3306
81+
Database: 'matrixshop'
82+
Username: 'root'
83+
Password: 'password'
84+
Maximum-Pool-Size: 10
85+
86+
Redis:
87+
Enabled: false
88+
Host: '127.0.0.1'
89+
Port: 6379
90+
Password: ''
91+
Channels:
92+
Invalidate: 'matrixshop:invalidate'
93+
Sync: 'matrixshop:sync'
94+
```
95+
96+
字段解释：
97+
98+
| 字段 | 说明 |
99+
| --- | --- |
100+
| `Database.Type` | 当前想使用的后端类型。默认是 `SQLITE`。 |
101+
| `SQLite.File` | SQLite 数据文件路径。 |
102+
| `MySQL.*` | MySQL 连接参数。 |
103+
| `Maximum-Pool-Size` | 连接池大小。 |
104+
| `Redis.Enabled` | 当前配置层可见，但实际实现里更偏预留字段。 |
105+
| `Redis.Channels.*` | Redis 频道名称，仍建议视为预留配置。 |
106+
107+
> 当前文档仍建议把 `SQLITE` 和 `MYSQL` 作为主要选项来理解，Redis 不要当作稳定主存储来写运营说明。
21108

22109
## 模块目录
23110

24-
当前默认资源目录如下：
111+
默认资源目录如下：
25112

26113
- `Menu/`
27114
- `SystemShop/`
@@ -33,67 +120,56 @@ description: MatrixShop 当前版本的目录布局与文件职责。
33120
- `Cart/`
34121
- `Record/`
35122

36-
## `settings.yml`
123+
每个模块目录通常包含：
37124

38-
每个模块的 `settings.yml` 主要负责两类内容：
125+
- `settings.yml`
126+
- `shops/*.yml`
127+
- `ui/*.yml`
39128

40-
1. 模块是否启用后的运行选项
41-
2. 命令绑定声明
129+
个别模块还带有额外文件：
42130

43-
命令绑定的通用结构是：
44-
45-
```yaml
46-
Bindings:
47-
Commands:
48-
Bindings:
49-
- 'auction'
50-
- 'ah'
51-
Register: true
52-
Show-In-Help: true
53-
Priority: 20
54-
Condition: 'perm matrixshop.auction.use'
55-
```
131+
- `ChestShop/signs.yml`
132+
- `Record/retention.yml`
56133

57-
其中：
134+
## `settings.yml` 和 `shops/*.yml` 的分工
58135

59-
- `Bindings`：候选命令关键字
60-
- `Register`：是否注册为独立命令
61-
- `Show-In-Help`：是否出现在 `/ms help`
62-
- `Priority`：多个命令别名冲突时的优先级
136+
### `settings.yml`
63137

64-
## `shops/*.yml`
138+
负责模块级控制，例如：
65139

66-
`shops/*.yml` 是当前版本最重要的入口配置。它承担两个职责：
140+
- 命令候选关键字
141+
- 模块开关
142+
- 权限条件
143+
- 运行参数
67144

68-
1. 定义一个菜单视图
69-
2. 定义一个 `shopId`
145+
### `shops/*.yml`
70146

71-
规则很简单：
147+
负责入口页或主视图，例如：
72148

73-
- 文件名就是 `shopId`
74-
- 里面可以再次声明 `Bindings.Commands`
75-
- 里面的 `layout`、`icons`、`template` 决定这个入口怎么显示
149+
- 标题
150+
- 菜单布局
151+
- 静态按钮
152+
- 动态槽位
153+
- 商品模板
76154

77-
当前示例里，以下模块都依赖 `shops/*.yml`：
155+
同时，**当前实现里 `shopId` 以文件名为准**。
78156

79-
- `Menu`
80-
- `SystemShop`
81-
- `PlayerShop`
82-
- `GlobalMarket`
83-
- `Auction`
84-
- `ChestShop`
85-
- `Transaction`
86-
- `Cart`
87-
- `Record`
157+
例如：
88158

89-
## `ui/*.yml`
159+
- `PlayerShop/shops/default.yml` -> `default`
160+
- `Cart/shops/cart.yml` -> `cart`
161+
- `Record/shops/record.yml` -> `record`
90162

91-
`ui/*.yml` 用于承载模块的具体界面模板，例如：
163+
## 从哪里继续读
92164

93-
- 系统商店确认页
94-
- 拍卖详情页
95-
- 玩家商店编辑页
96-
- 购物车结算页
97-
- 交易确认页
165+
如果你要改具体模块，请直接进入新的详细页：
98166

99-
模块代码会按自己的流程打开这些 UI 文件，因此 `ui/*.yml` 更偏向“内部页面”，而 `shops/*.yml` 更偏向“入口页面”。
167+
- [Menu](./shop-types/menu)
168+
- [SystemShop](./shop-types/system-shop)
169+
- [PlayerShop](./shop-types/player-shop)
170+
- [GlobalMarket](./shop-types/global-market)
171+
- [Auction](./shop-types/auction)
172+
- [ChestShop](./shop-types/chest-shop)
173+
- [Transaction](./shop-types/transaction)
174+
- [Cart](./shop-types/cart)
175+
- [Record](./shop-types/record)

‎docs/matrixshop/index.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ MatrixShop 是一个模块化交易插件。当前代码已经围绕统一命令
3535
- 命令绑定、独立命令与 `shopId` 解析规则
3636
- SQLite / MySQL / 文件回退行为
3737
- 各交易模块的当前能力边界
38+
- 每个模块默认配置的完整示例与字段解读
3839
- UI 配置和动作语法
3940

4041
## 开始阅读
@@ -46,3 +47,4 @@ MatrixShop 是一个模块化交易插件。当前代码已经围绕统一命令
4647
3. [命令与权限](./commands-and-permissions)
4748
4. [数据库与存储](./database-and-storage)
4849
5. [模块总览](./modules-overview)
50+
6. [商店与模块详解](./shop-types)

‎docs/matrixshop/modules-overview.mdx‎

Lines changed: 41 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,60 @@
11
---
22
title: 模块总览
3-
description: MatrixShop 九个模块的职责与当前边界。
3+
description: MatrixShop 各模块职责、默认文件和详细文档入口。
44
---
55

66
# 模块总览
77

8-
## 模块列表
8+
当前 MatrixShop 默认启用了九个模块。为了让文档更容易查找，本站现在把每个模块都拆成了单独页面。
99

10-
| 模块 ID | 作用 | 关键文件 |
11-
| --- | --- | --- |
12-
| `menu` | 总入口菜单 | `Menu/settings.yml`、`Menu/shops/*.yml` |
13-
| `system-shop` | 服务器预设商店 | `SystemShop/settings.yml`、`SystemShop/shops/*.yml` |
14-
| `player-shop` | 玩家个人商店 | `PlayerShop/settings.yml`、`PlayerShop/shops/*.yml` |
15-
| `global-market` | 全服上架市场 | `GlobalMarket/settings.yml`、`GlobalMarket/shops/*.yml` |
16-
| `auction` | 拍卖行 | `Auction/settings.yml`、`Auction/shops/*.yml` |
17-
| `chestshop` | 箱子商店 | `ChestShop/settings.yml`、`ChestShop/shops/*.yml` |
18-
| `transaction` | 面对面交易 | `Transaction/settings.yml`、`Transaction/shops/*.yml` |
19-
| `cart` | 购物车 | `Cart/settings.yml`、`Cart/shops/*.yml` |
20-
| `record` | 交易记录 | `Record/settings.yml`、`Record/shops/*.yml` |
10+
## 模块清单
2111

22-
## 当前范围说明
12+
| 模块 | 作用 | 关键文件 | 详细页 |
13+
| --- | --- | --- | --- |
14+
| `menu` | 总入口导航菜单 | `Menu/settings.yml`、`Menu/shops/main.yml` | [Menu](./shop-types/menu) |
15+
| `system-shop` | 静态系统商店 | `SystemShop/settings.yml`、`SystemShop/shops/*.yml` | [SystemShop](./shop-types/system-shop) |
16+
| `player-shop` | 玩家个人商店 | `PlayerShop/settings.yml`、`PlayerShop/shops/default.yml` | [PlayerShop](./shop-types/player-shop) |
17+
| `global-market` | 全服共享市场 | `GlobalMarket/settings.yml`、`GlobalMarket/shops/default.yml` | [GlobalMarket](./shop-types/global-market) |
18+
| `auction` | 拍卖行 | `Auction/settings.yml`、`Auction/shops/default.yml` | [Auction](./shop-types/auction) |
19+
| `chestshop` | 箱子商店 | `ChestShop/settings.yml`、`ChestShop/shops/default.yml` | [ChestShop](./shop-types/chest-shop) |
20+
| `transaction` | 面对面交易 | `Transaction/settings.yml`、`Transaction/shops/default.yml` | [Transaction](./shop-types/transaction) |
21+
| `cart` | 购物车 | `Cart/settings.yml`、`Cart/shops/cart.yml` | [Cart](./shop-types/cart) |
22+
| `record` | 账本记录 | `Record/settings.yml`、`Record/shops/record.yml` | [Record](./shop-types/record) |
2323

24-
### 真正按 `shopId` 分开的模块
24+
## 应该先读哪些页
2525

26-
这些模块的命令、入口菜单和数据库记录都已经按 `shops/<file-name>.yml` 的文件名做作用域：
26+
### 如果你在做新服部署
2727

28-
- `player-shop`
29-
- `global-market`
30-
- `auction`
31-
- `transaction`
28+
建议顺序：
3229

33-
### 入口是分开的，但运行态仍是共享的模块
30+
1. [配置结构](./configuration-structure)
31+
2. [商店与模块详解](./shop-types)
32+
3. 你实际会用到的模块页
3433

35-
这些模块支持多个 `shops/*.yml` 入口，但内部数据不是完全按 `shopId` 物理拆分：
34+
### 如果你在排查某个商店为什么打不开
3635

37-
- `cart`
38-
- `record`
39-
- `chestshop`
36+
先看：
4037

41-
其中：
38+
1. 对应模块的 `settings.yml` 是否启用、是否有权限条件。
39+
2. 对应 `shops/*.yml` 的文件名是否和你打开的 `shopId` 一致。
40+
3. 模块页里记录的默认命令别名和 UI 文件是否匹配。
4241

43-
- `cart` 主要是按入口过滤可结算来源
44-
- `record` 主要是按入口过滤模块视图
45-
- `chestshop` 的 `shops/*.yml` 更像不同入口视图，而不是多套独立箱店池
42+
### 如果你在做中文化或重做界面
4643

47-
### 配置驱动、不走数据库运行表的模块
44+
先看：
4845

49-
- `menu`
50-
- `system-shop`
46+
1. [绑定与 UI](./bindings-and-ui)
47+
2. 对应模块页中的 `shops/*.yml`
48+
3. 对应模块的 `ui/*.yml`
5149

52-
其中 `system-shop` 主要依赖 YAML 配置和 Vault 经济，不需要 JDBC 运行表。
50+
## 当前模块边界
51+
52+
为了避免把 MatrixShop 理解成“所有模块都完全一样”，这里再强调一次：
53+
54+
- `SystemShop` 主要是静态 YAML 商品。
55+
- `PlayerShop`、`GlobalMarket`、`Auction` 主要是运行时上架数据。
56+
- `ChestShop` 有箱子、库存、告示牌这套线下交互。
57+
- `Transaction` 不是商品市场，而是面对面交换。
58+
- `Cart` 和 `Record` 是辅助模块，不是独立销售市场。
59+
60+
如果你准备直接改字段，请进入 [商店与模块详解](./shop-types) 下的具体模块页。

‎docs/matrixshop/shop-types/_category_.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "商店与模块详解",
3+
"position": 6,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "按模块查看 MatrixShop 默认配置、入口文件和逐项字段说明。"
7+
}
8+
}

0 commit comments

Comments
 (0)