Add MatrixShop 1.4.0 discount docs

Author: 54895y

docs/matrixshop/configuration/bstats-and-telemetry.mdx

@@ -76,7 +76,7 @@ enabled: false
 源码构建后，MatrixShop 当前会输出带重定位 bStats 的运行产物：
 
 ```text
-build/libs/MatrixShop-1.3.0-all.jar
+build/libs/MatrixShop-1.4.0-all.jar
 ```
 
 `org.bstats` 已被重定位到插件私有包名下，避免和其他同样使用 bStats 的插件产生类冲突。

docs/matrixshop/configuration/system-shop.mdx

@@ -77,6 +77,77 @@ name: '&f铁剑'
 - `lore`
 - `currency`
 
+`price` 当前支持两种写法：
+
+```yaml
+price: 120
+```
+
+```yaml
+price:
+  base: 120
+  discounts:
+    - id: vip
+      percent: 10
+      condition:
+        - "perm 'group.vip'"
+    - id: event
+      amount-off: 5
+    - id: night-surge
+      surcharge: 8
+```
+
+折扣规则说明：
+
+- `percent`
+  - 百分比折扣，多个命中规则按百分比相加
+- `amount-off`
+  - 固定减免
+- `surcharge`
+  - 固定加价
+- `condition`
+  - Kether 条件列表，不写则视为始终命中
+- `whitelist`
+  - 指定当前规则只允许与哪些折扣 id 叠加
+- `blacklist`
+  - 指定当前规则不能与哪些折扣 id 叠加
+
+当前行为：
+
+- 百分比折扣总和上限为 `100`
+- 最终成交价不会低于一个最小正价
+- 商品页、确认页和实际扣费都使用折后最终价
+
+叠加控制示例：
+
+```yaml
+price:
+  base: 420
+  discounts:
+    - id: vip
+      percent: 10
+      condition:
+        - "perm 'group.vip'"
+    - id: svip
+      percent: 15
+      blacklist:
+        - vip
+      condition:
+        - "perm 'group.svip'"
+    - id: mvp
+      percent: 20
+      blacklist:
+        - svip
+      condition:
+        - "perm 'group.mvp'"
+```
+
+按上面这个例子：
+
+- `SVIP` 命中时不会再叠加 `VIP`
+- `MVP` 命中时不会再叠加 `SVIP`
+- 如果你希望某条规则只允许和特定折扣共存，可以改用 `whitelist`
+
 `goods` 目录当前还支持两种可复用资源：
 
 - 商品组
@@ -171,6 +242,8 @@ icons:
 - `groups.<id>.goods`
   - 非随机模式下直接引用静态商品或商品组
 
+刷新池条目的 `price` 同样支持对象结构，并会与商品本体中的 `discounts` 合并结算。
+
 默认资源里已经带了一个关闭状态的注释示例：
 
 - `SystemShop/shops/weapon.yml`

docs/matrixshop/getting-started/quick-start.mdx

@@ -21,6 +21,7 @@ sidebar_position: 1
 
 如果你正在从 `1.0.0` 升级，请先阅读：
 
+- [1.4.0 发布说明](./release-notes-1-4-0)
 - [1.3.0 发布说明](./release-notes-1-3-0)
 - [1.2.0 发布说明](./release-notes-1-2-0)
 - [1.1.1 发布说明](./release-notes-1-1-1)

docs/matrixshop/index.mdx

@@ -10,7 +10,7 @@ MatrixShop 是面向生存、经济和市场场景的模块化交易插件。当
 
 当前最新版本入口：
 
-- [1.3.0 发布说明](./release-notes-1-3-0)
+- [1.4.0 发布说明](./release-notes-1-4-0)
 - [更新日志总览](./release-notes)
 
 ## 当前版本状态
@@ -69,7 +69,7 @@ MatrixShop 是面向生存、经济和市场场景的模块化交易插件。当
 如果你第一次接触 MatrixShop，推荐顺序是：
 
 1. [快速开始](./quick-start)
-2. [1.3.0 发布说明](./release-notes-1-3-0)
+2. [1.4.0 发布说明](./release-notes-1-4-0)
 3. [配置结构](./configuration-structure)
 4. [经济模块](./economy)
 5. [命令与权限](./commands-and-permissions)
@@ -105,6 +105,7 @@ MatrixShop 是面向生存、经济和市场场景的模块化交易插件。当
 
 ### 更新日志
 
+- [1.4.0 发布说明](./release-notes-1-4-0)
 - [1.3.0 发布说明](./release-notes-1-3-0)
 - [1.2.0 发布说明](./release-notes-1-2-0)
 - [1.1.1 发布说明](./release-notes-1-1-1)
@@ -120,6 +121,7 @@ MatrixShop 是面向生存、经济和市场场景的模块化交易插件。当
 
 如果你是从 `1.0.0` 升级，请先看：
 
+- [1.4.0 发布说明](./release-notes-1-4-0)
 - [1.3.0 发布说明](./release-notes-1-3-0)
 - [1.2.0 发布说明](./release-notes-1-2-0)
 - [1.1.1 发布说明](./release-notes-1-1-1)

docs/matrixshop/release-notes/index.mdx

@@ -11,13 +11,14 @@ sidebar_position: 0
 
 如果你准备升级，建议按从新到旧的顺序阅读：
 
-1. [1.3.0 发布说明](./release-notes-1-3-0)
-2. [1.2.0 发布说明](./release-notes-1-2-0)
-3. [1.1.1 发布说明](./release-notes-1-1-1)
-4. [1.1.0 发布说明](./release-notes-1-1-0)
+1. [1.4.0 发布说明](./release-notes-1-4-0)
+2. [1.3.0 发布说明](./release-notes-1-3-0)
+3. [1.2.0 发布说明](./release-notes-1-2-0)
+4. [1.1.1 发布说明](./release-notes-1-1-1)
+5. [1.1.0 发布说明](./release-notes-1-1-0)
 
 ## 阅读建议
 
-- 想看当前最新功能和验证结果：先看 [1.3.0 发布说明](./release-notes-1-3-0)
-- 想看管理员商品维护流历史变化：继续看 [1.2.0 发布说明](./release-notes-1-2-0)
+- 想看当前最新功能和验证结果：先看 [1.4.0 发布说明](./release-notes-1-4-0)
+- 想看 `SystemShop` 折扣系统、价格对象和购物车锁价行为：看 [1.4.0 发布说明](./release-notes-1-4-0)
 - 想回看 `1.1.x` 的收口和修复：看 [1.1.1](./release-notes-1-1-1) 与 [1.1.0](./release-notes-1-1-0)

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

@@ -0,0 +1,112 @@
+---
+title: 1.4.0 发布说明
+description: MatrixShop 1.4.0 的 SystemShop 折扣系统、价格对象、测试结果与升级说明。
+slug: /matrixshop/release-notes-1-4-0
+sidebar_position: 1
+---
+
+# MatrixShop 1.4.0 发布说明
+
+发布时间：`2026-04-03`
+
+## 版本定位
+
+`1.4.0` 是围绕 `SystemShop` 价格模型的一次功能版本更新。
+
+这一版的重点不是继续扩模块，而是把系统商店的价格从“固定数值”扩展成“可按玩家条件结算的价格对象”。
+
+## 本版本重点
+
+### `price` 键支持对象结构
+
+`SystemShop` 商品和刷新池条目现在都支持：
+
+```yaml
+price:
+  base: 420
+  discounts:
+    - id: vip
+      percent: 10
+      condition:
+        - "perm 'group.vip'"
+    - id: holiday
+      amount-off: 20
+    - id: night-surge
+      surcharge: 8
+```
+
+同时保持旧写法兼容：
+
+```yaml
+price: 420
+```
+
+### 支持折扣重叠与 Kether 条件
+
+当前折扣规则支持：
+
+- `percent`
+- `amount-off`
+- `surcharge`
+- `condition`
+- `whitelist`
+- `blacklist`
+
+行为规则：
+
+- 多条命中的百分比折扣按相加计算
+- 折扣率总和上限为 `100`
+- 最终成交价不会低于最小正价
+- Kether 条件失败时只跳过对应规则，不影响插件启动
+
+### 刷新池价格对象会合并商品本体折扣
+
+刷新池条目中的 `price` 如果写成对象结构：
+
+- `base` 会覆盖商品本体基础价
+- `discounts` 会与商品本体规则合并
+
+这意味着同一个 goods 可以保留通用折扣规则，而刷新池只额外附加某一批次的活动规则。
+
+### 购物车现在锁定系统商店折后价
+
+系统商店商品加入购物车时：
+
+- `snapshotPrice` 记录的是入车时折后价
+- 后续折扣规则变化不会改写该条目的成交价
+
+这使购物车行为和系统商店确认页展示保持一致。
+
+## 升级说明
+
+如果你不需要折扣系统，可以完全不改现有配置。
+
+当前兼容策略：
+
+- `price: 420` 继续可用
+- 旧 inline `goods.<id>` 结构继续可读
+- 新写法只是在 `price` 键下新增对象结构
+
+## 验证
+
+本版本发布前已完成：
+
+- `./gradlew build`
+- docs site `npm run build`
+- `paper-1.21.8` smoke boot
+- `paper-1.21.11` smoke boot
+- 在 `paper-1.21.11` 测试服中，将 inline `SystemShop` 商品的 `price` 改成对象结构，并同时使用：
+  - `percent`
+  - `amount-off`
+  - `surcharge`
+  - Kether `condition`
+  - `blacklist`
+
+该配置已验证可正常启动，未出现新的 `price-config-invalid` 或 `discount-condition-failed` 启动告警。
+
+## 相关链接
+
+- [GitHub Releases](https://github.com/54895y/MatrixShop/releases)
+- [1.4.0 GitHub Release](https://github.com/54895y/MatrixShop/releases/tag/v1.4.0)
+- [CHANGELOG](https://github.com/54895y/MatrixShop/blob/main/CHANGELOG.md)
+- [1.3.0 发布说明](./release-notes-1-3-0)

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

@@ -221,6 +221,61 @@ lore:
 | `lore` | 商品说明。 |
 | `currency` | 商品级货币 key。可选；只有你想覆盖默认货币时才需要写。 |
 
+`price` 也可以写成对象：
+
+```yaml
+price:
+  base: 420
+  discounts:
+    - id: vip
+      percent: 10
+      condition:
+        - "perm 'group.vip'"
+    - id: weekend
+      amount-off: 20
+    - id: night-surge
+      surcharge: 8
+```
+
+当前折扣规则：
+
+- 支持 `percent`、`amount-off`、`surcharge`
+- `condition` 使用 Kether 条件判断
+- 支持 `whitelist`、`blacklist` 控制折扣叠加
+- 多条命中的 `percent` 会相加
+- 最终成交价不会低于最小正价
+- `{price}` 显示最终价；`{base-price}`、`{discount-count}`、`{discount-summary}` 可用于自定义 UI
+
+黑名单示例：
+
+```yaml
+price:
+  base: 420
+  discounts:
+    - id: vip
+      percent: 10
+      condition:
+        - "perm 'group.vip'"
+    - id: svip
+      percent: 15
+      blacklist:
+        - vip
+      condition:
+        - "perm 'group.svip'"
+    - id: mvp
+      percent: 20
+      blacklist:
+        - svip
+      condition:
+        - "perm 'group.mvp'"
+```
+
+这个例子里：
+
+- `SVIP` 命中后会排斥 `VIP`
+- `MVP` 命中后会排斥 `SVIP`
+- `whitelist` 则用于反向定义“只允许与哪些折扣叠加”
+
 > 兼容说明：旧版 `SystemShop/shops/*.yml` 中直接内联 `goods.<id>` 的写法仍然可读取，但新配置应优先拆到 `SystemShop/goods/*.yml`。
 
 ## `SystemShop/goods/starter_weapons.yml`
@@ -259,6 +314,8 @@ entries:
     buy-max: 3
 ```
 
+刷新池条目的 `price` 同样支持对象结构，并会与商品本体的折扣规则合并。
+
 ## 刷新区域
 
 当前已经有 SystemShop 刷新基础能力，配置位置在 `icons.<char>.refresh`。

sidebars.ts

@@ -110,6 +110,7 @@ const sidebars: SidebarsConfig = {
             id: 'matrixshop/release-notes/index',
           },
           items: [
+            'matrixshop/release-notes/release-notes-1-4-0',
             'matrixshop/release-notes/release-notes-1-3-0',
             'matrixshop/release-notes/release-notes-1-2-0',
             'matrixshop/release-notes/release-notes-1-1-1',