Add MatrixStorage docs

54895y · 54895y · commit 133c49557f90 · 2026-04-03T11:00:18.000+08:00
diff --git a/docs/matrixstorage/_category_.json b/docs/matrixstorage/_category_.json
@@ -0,0 +1,9 @@
+{
+  "label": "MatrixStorage",
+  "position": 5,
+  "link": {
+    "type": "generated-index",
+    "description": "MatrixStorage 的安装、命令、后端、邮箱、仓库与外部方块接入说明。"
+  }
+}
+
diff --git a/docs/matrixstorage/block-warehouses.mdx b/docs/matrixstorage/block-warehouses.mdx
@@ -0,0 +1,50 @@
+---
+title: 实体仓库
+description: 原版、自定义方块与家具仓库的当前实现边界。
+---
+
+# 实体仓库
+
+## 支持模式
+
+- `terminal`
+- `location`
+
+`terminal` 仅作为个人仓库/邮箱入口。  
+`location` 为真正的坐标仓库记录。
+
+## 原版方块
+
+当前原版方块仓库会优先复用方块自身原生库存。
+
+这意味着：
+
+- 原版容器会保留原生打开方式
+- 漏斗搬运可通过事件开关进行限制
+- 挖掉后内容会像原版容器一样掉落
+
+## 自定义方块与家具
+
+当前已接入：
+
+- `CraftEngine`
+- `ItemsAdder`
+- `Nexo`
+
+三类来源都支持：
+
+- 放置识别
+- 交互打开
+- 破坏时移除仓库记录
+- 虚拟库存掉落
+
+## 设置项
+
+当前设置页可修改：
+
+- 显示名称
+- 信任列表
+- 漏斗插入开关
+- 漏斗抽取开关
+- 比较器输出开关
+
diff --git a/docs/matrixstorage/commands-and-permissions.mdx b/docs/matrixstorage/commands-and-permissions.mdx
@@ -0,0 +1,40 @@
+---
+title: 命令与权限
+description: MatrixStorage 的玩家命令、管理员命令与权限节点。
+---
+
+# 命令与权限
+
+## 玩家命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `/matrixstorage` | 打开仓库总览中心。 |
+| `/mailbox` | 打开邮箱。 |
+| `/mailbox send <player> <message>` | 发送普通邮件。 |
+| `/mailbox senditem <player> [message]` | 将主手物品作为附件发出。 |
+| `/mailbox sendmoney <player> <amount> [message]` | 发送金额附件邮件。 |
+| `/warehouse` | 打开仓库总览中心。 |
+| `/warehouse personal` | 打开个人仓库。 |
+| `/warehouse pending` | 打开待收区。 |
+| `/warehouse open <block-id>` | 打开指定实体仓库。 |
+| `/warehouse settings <block-id>` | 打开指定实体仓库设置。 |
+| `/warehouse trust <block-id> <player>` | 添加信任玩家。 |
+| `/warehouse untrust <block-id> <player>` | 移除信任玩家。 |
+
+## 管理员命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `/matrixstorage reload` | 重载配置与后端。 |
+| `/matrixstorageadmin status` | 查看当前状态。 |
+| `/matrixstorageadmin warehouse open <player>` | 查看目标玩家个人仓库。 |
+| `/matrixstorageadmin mailbox open <player>` | 查看目标玩家邮箱。 |
+| `/matrixstorageadmin block inspect <world> <x> <y> <z>` | 查看目标坐标仓库记录。 |
+
+## 权限节点
+
+- `matrixstorage.admin`
+
+当前实现以 `matrixstorage.admin` 作为管理员总权限。普通玩家入口暂时默认不做细分拆分。
+
diff --git a/docs/matrixstorage/database-and-storage.mdx b/docs/matrixstorage/database-and-storage.mdx
@@ -0,0 +1,37 @@
+---
+title: 数据库与存储
+description: MatrixStorage 的四后端与状态持久化方式。
+---
+
+# 数据库与存储
+
+## 支持后端
+
+`database.yml` 当前支持：
+
+- `sqlite`
+- `mysql`
+- `redis`
+- `yaml`
+
+默认值：
+
+```yml
+type: sqlite
+```
+
+## 当前实现方式
+
+当前版本采用统一快照持久化：
+
+- 邮件记录
+- 玩家个人仓库
+- 待收区
+- 实体仓库设置与库存快照
+
+其中原版容器型实体仓库会优先使用方块自身的原生库存；快照层同时保留一份仓库内容备份，避免世界保存异常时完全丢失状态。
+
+## 不自动回退
+
+如果目标后端初始化失败，插件不会自动切到其他后端，以避免数据分裂。
+
diff --git a/docs/matrixstorage/faq.mdx b/docs/matrixstorage/faq.mdx
@@ -0,0 +1,19 @@
+---
+title: FAQ
+description: MatrixStorage 当前常见问题。
+---
+
+# FAQ
+
+## 为什么金额邮件无法领取？
+
+当前金额附件依赖 Vault 经济接口。没有安装 Vault 或没有可用经济实现时，金额无法发放。
+
+## 为什么实体仓库没有出现在总览里？
+
+只有 `location` 模式的仓库会进入玩家总览列表。`terminal` 只是入口方块，不生成独立仓库记录。
+
+## 为什么某些自定义家具不能走原版漏斗逻辑？
+
+当前版本已经接入 `CraftEngine / ItemsAdder / Nexo` 的方块与家具识别，但是否具备完全等同原版容器的红石/漏斗行为，仍取决于对应来源在世界中的实际承载方式。
+
diff --git a/docs/matrixstorage/index.mdx b/docs/matrixstorage/index.mdx
@@ -0,0 +1,38 @@
+---
+title: MatrixStorage
+description: Matrix 系列统一仓储插件总览。
+slug: /matrixstorage
+---
+
+# MatrixStorage
+
+`MatrixStorage` 是 Matrix 系列里的统一仓储插件，当前实现围绕四条主线工作：
+
+- 玩家邮箱
+- 个人仓库与待收区
+- 位置型实体仓库
+- `MatrixShop` 外部仓库 SPI 对接
+
+同时已经接入：
+
+- 原版方块仓库
+- `CraftEngine` 自定义方块与家具仓库
+- `ItemsAdder` 自定义方块与家具仓库
+- `Nexo` 自定义方块与家具仓库
+
+当前代码基线：
+
+- TabooLib 6
+- Kotlin
+- `MatrixLib` 作为硬前置插件
+- `sqlite / mysql / redis / yaml` 四后端
+
+建议阅读顺序：
+
+1. [安装与依赖](/docs/matrixstorage/installation)
+2. [命令与权限](/docs/matrixstorage/commands-and-permissions)
+3. [数据库与存储](/docs/matrixstorage/database-and-storage)
+4. [邮箱](/docs/matrixstorage/mailbox)
+5. [仓库总览](/docs/matrixstorage/warehouse-overview)
+6. [实体仓库](/docs/matrixstorage/block-warehouses)
+7. [外部接入](/docs/matrixstorage/integrations)
diff --git a/docs/matrixstorage/installation.mdx b/docs/matrixstorage/installation.mdx
@@ -0,0 +1,45 @@
+---
+title: 安装与依赖
+description: MatrixStorage 的安装步骤、前置和可选依赖。
+---
+
+# 安装与依赖
+
+## 必需前置
+
+| 插件 | 说明 |
+| --- | --- |
+| `MatrixLib` | Matrix 系列统一前置，必须先加载。 |
+
+## 可选依赖
+
+| 插件 | 作用 |
+| --- | --- |
+| `Vault` | 玩家邮件金额附件领取。 |
+| `MatrixShop` | 作为外部仓库提供者，接收 `CommerceWarehouseProvider` 调用。 |
+| `CraftEngine` | 自定义方块/家具仓库放置与交互。 |
+| `ItemsAdder` | 自定义方块/家具仓库放置与交互。 |
+| `Nexo` | 自定义方块/家具仓库放置与交互。 |
+
+## 默认配置文件
+
+```text
+plugins/MatrixStorage/
+├─ config.yml
+├─ database.yml
+├─ module.yml
+├─ messages.yml
+├─ Mailbox/settings.yml
+├─ Warehouse/settings.yml
+└─ BlockWarehouse/settings.yml
+```
+
+## 启动确认
+
+启动成功后，控制台会显示：
+
+- 当前后端描述
+- 邮件数量
+- 实体仓库数量
+- `MatrixShop` 桥接状态
+
diff --git a/docs/matrixstorage/integrations.mdx b/docs/matrixstorage/integrations.mdx
@@ -0,0 +1,26 @@
+---
+title: 外部接入
+description: MatrixStorage 与 MatrixShop、CraftEngine、ItemsAdder、Nexo 的对接说明。
+---
+
+# 外部接入
+
+## MatrixShop
+
+当前 `MatrixStorage` 会在运行时检测 `MatrixShop`，并通过 Bukkit `ServicesManager` 注册 `CommerceWarehouseProvider` 兼容代理。
+
+当前桥接行为：
+
+- `store()`：把物品写入待收区，把金额写成系统邮件。
+- `openWarehouse()`：直接打开目标玩家个人仓库。
+- `pendingCount()`：统计待收区非空槽位数量。
+
+## CraftEngine / ItemsAdder / Nexo
+
+三者当前都采用运行时反射注册事件监听，而不是编译期硬依赖。
+
+这样做的结果是：
+
+- 没安装对应插件时，`MatrixStorage` 仍可正常启动。
+- 安装后会自动接管对应事件。
+
diff --git a/docs/matrixstorage/mailbox.mdx b/docs/matrixstorage/mailbox.mdx
@@ -0,0 +1,31 @@
+---
+title: 邮箱
+description: MatrixStorage 邮箱模块的入口与行为。
+---
+
+# 邮箱
+
+当前邮箱同时承担两种业务：
+
+- 玩家互寄
+- 系统金额投递通知
+
+## 当前附件能力
+
+- 文本内容
+- 主手物品附件
+- Vault 金额附件
+
+## 领取规则
+
+- 金额附件：领取时尝试通过 Vault 发放。
+- 物品附件：领取时进入玩家待收区。
+- 邮件可在 UI 中归档。
+
+## UI 规则
+
+邮箱页默认按时间倒序展示：
+
+- 左键领取
+- 右键归档
+
diff --git a/docs/matrixstorage/warehouse-overview.mdx b/docs/matrixstorage/warehouse-overview.mdx
@@ -0,0 +1,30 @@
+---
+title: 仓库总览
+description: 玩家个人仓库、待收区与实体仓库总览中心。
+---
+
+# 仓库总览
+
+`/warehouse` 与 `/matrixstorage` 默认都会进入总览中心。
+
+总览页当前聚合：
+
+- 个人仓库
+- 待收区
+- 邮箱入口
+- 玩家拥有的全部实体仓库列表
+
+## 实体仓库列表
+
+列表项当前展示：
+
+- 显示名
+- 仓库 ID
+- 世界坐标
+- 来源类型
+
+点击行为：
+
+- 左键打开仓库
+- 右键打开设置
+
diff --git a/docs/plugins.mdx b/docs/plugins.mdx
@@ -65,3 +65,16 @@ MatrixShop 是模块化交易插件。当前代码已经实现以下模块，并
 - Record
 
 [进入 MatrixShop 文档](/docs/matrixshop)
+
+## MatrixStorage
+
+MatrixStorage 是 Matrix 系列的统一仓储插件，围绕邮箱、个人仓库、位置型实体仓库与外部仓库投递工作，当前代码已经提供：
+
+- 玩家互寄邮箱
+- 系统投递与待收区
+- 个人仓库与总览中心
+- 原版方块、CraftEngine、ItemsAdder、Nexo 的方块/家具仓库接入
+- MatrixShop 外部仓库提供者桥接
+- SQLite / MySQL / Redis / YAML 四后端
+
+[进入 MatrixStorage 文档](/docs/matrixstorage)
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
@@ -106,6 +106,7 @@ const config: Config = {
         {to: '/docs/matrixauth/overview', label: 'MatrixAuth', position: 'left'},
         {to: '/docs/matrixcook/overview', label: 'MatrixCook', position: 'left'},
         {to: '/docs/matrixshop', label: 'MatrixShop', position: 'left'},
+        {to: '/docs/matrixstorage', label: 'MatrixStorage', position: 'left'},
         {type: 'search', position: 'right'},
         {to: '/ai-search', label: 'AI 搜索', position: 'right'},
         {
@@ -150,6 +151,10 @@ const config: Config = {
               label: 'MatrixShop',
               to: '/docs/matrixshop',
             },
+            {
+              label: 'MatrixStorage',
+              to: '/docs/matrixstorage',
+            },
           ],
         },
         {
diff --git a/sidebars.ts b/sidebars.ts
@@ -139,6 +139,24 @@ const sidebars: SidebarsConfig = {
         },
       ],
     },
+    {
+      type: 'category',
+      label: 'MatrixStorage',
+      link: {
+        type: 'doc',
+        id: 'matrixstorage/index',
+      },
+      items: [
+        'matrixstorage/installation',
+        'matrixstorage/commands-and-permissions',
+        'matrixstorage/database-and-storage',
+        'matrixstorage/mailbox',
+        'matrixstorage/warehouse-overview',
+        'matrixstorage/block-warehouses',
+        'matrixstorage/integrations',
+        'matrixstorage/faq',
+      ],
+    },
   ],
 };
 
