From 9507a7f0b12b0824381835014442c9afa493edba Mon Sep 17 00:00:00 2001 From: cc_cece Date: Thu, 13 Aug 2026 01:07:13 +0800 Subject: [PATCH] docs: correct audited content and claims --- blog/2026-04-28-welcome.mdx | 2 +- blog/authors.yml | 2 +- .../webshopx-payments/commands-permissions.md | 2 +- docs/webshopx-payments/faq.md | 4 +- docs/webshopx-payments/hook-channels.md | 4 +- docs/webshopx-payments/install-deploy.md | 4 +- docs/webshopx-payments/official-channels.md | 2 +- docs/webshopx-payments/overview.md | 10 +- docs/webshopx/player/algorithm.md | 116 ++++++++++-------- docs/webshopx/player/auctions.md | 4 +- docs/webshopx/player/dynamic-pricing.md | 2 +- docs/webshopx/player/shop-and-orders.md | 22 ++-- docusaurus.config.ts | 2 +- .../webshopx-payments/commands-permissions.md | 2 +- .../current/webshopx-payments/faq.md | 4 +- .../webshopx-payments/hook-channels.md | 2 +- .../webshopx-payments/install-deploy.md | 6 +- .../webshopx-payments/official-channels.md | 2 +- .../current/webshopx-payments/overview.md | 12 +- .../webshopx-payments/payment-solution.md | 8 +- .../current/webshopx/player/algorithm.md | 38 +++--- .../webshopx/player/shop-and-orders.md | 12 +- 22 files changed, 144 insertions(+), 118 deletions(-) diff --git a/blog/2026-04-28-welcome.mdx b/blog/2026-04-28-welcome.mdx index 69df442..cc0b7d3 100644 --- a/blog/2026-04-28-welcome.mdx +++ b/blog/2026-04-28-welcome.mdx @@ -1,4 +1,4 @@ ---- +--- slug: welcome title: 欢迎来到我的文档站 authors: [Prism-Committee] diff --git a/blog/authors.yml b/blog/authors.yml index ffea70f..bb869b4 100644 --- a/blog/authors.yml +++ b/blog/authors.yml @@ -1,4 +1,4 @@ -Prism-Committee: +Prism-Committee: name: Prism-Committee title: Developer url: https://github.com/Prism-Committee diff --git a/docs/webshopx-payments/commands-permissions.md b/docs/webshopx-payments/commands-permissions.md index a03529e..d37b414 100644 --- a/docs/webshopx-payments/commands-permissions.md +++ b/docs/webshopx-payments/commands-permissions.md @@ -7,7 +7,7 @@ sidebar_position: 7 # 命令与权限体系 -`WebShopX-Payments` 提供了极其简洁的游戏内指令与权限节点，主要用于管理员进行配置热重载与运行时状态排障。 +`WebShopX-Payments` 提供游戏内指令与权限节点，主要用于配置热重载与运行时状态排障。 v3 的渠道配置也可以由 WebShopX 后台通过 Provider 能力展示，但这不会改变 `/wsxpay` 的权限节点，也不代表 WebShopX 会替第三方插件完成重载。 diff --git a/docs/webshopx-payments/faq.md b/docs/webshopx-payments/faq.md index f3a3012..74b4f82 100644 --- a/docs/webshopx-payments/faq.md +++ b/docs/webshopx-payments/faq.md @@ -74,10 +74,10 @@ v3 排障应先执行 `/wsxpay status`，再区分“Provider 未注册”“内 ### Q：使用 Gradle 构建打包时出现 Java Class Version 错误？ :::note[编译环境推荐] -`WebShopX-Payments` 源码包含较新的 Java 特性，**推荐且必须使用 JDK 25** 进行编译。 +项目 CI 当前使用 JDK 25 构建，建议本地构建也使用 JDK 25，以减少与官方构建环境的差异。插件产物以 Java 8 字节码为目标；这不表示 Minecraft 服务端运行时必须使用 Java 25。 在 Windows PowerShell 终端中，您可以通过以下命令临时指定 JDK 路径进行编译： ```powershell -$env:JAVA_HOME='C:\Program Files\Java\jdk-25.0.3' +$env:JAVA_HOME='C:\Program Files\Java\jdk-25' $env:JAVA_TOOL_OPTIONS='-Duser.country=US' .\gradlew.bat :plugin:bukkit:with-backend:build ``` diff --git a/docs/webshopx-payments/hook-channels.md b/docs/webshopx-payments/hook-channels.md index ebb2719..2d3c7b7 100644 --- a/docs/webshopx-payments/hook-channels.md +++ b/docs/webshopx-payments/hook-channels.md @@ -119,8 +119,8 @@ Hook 能否使用取决于操作系统、微信/支付宝客户端版本、账 ### (3) 因数据库写入延迟调大超时 :::warning[关键配置微调] -由于微信本地数据库持久化机制的原因，当您手机收到付款时，电脑端微信需要**大约 10 秒甚至更久**才会将消息真正写入到本地数据库文件中。 -因此，使用 Hook v4 通道时，必须在插件端的 `config.yml` 中将超时时间调大（推荐 200 秒以上），否则玩家极易在等待解密时被判定超时： +由于微信本地数据库持久化机制的原因，手机收到付款后，电脑端微信写入本地数据库可能存在延迟。 +因此，使用 Hook v4 通道时，应根据实测延迟适当调大插件端 `config.yml` 的超时时间；可先以 200 秒作为排障起点，再根据日志和业务要求调整： ```yaml # config.yml payment: diff --git a/docs/webshopx-payments/install-deploy.md b/docs/webshopx-payments/install-deploy.md index 45cca0b..b7ee8ea 100644 --- a/docs/webshopx-payments/install-deploy.md +++ b/docs/webshopx-payments/install-deploy.md @@ -7,7 +7,7 @@ sidebar_position: 2 # 安装与部署 -本节指导您如何在 Minecraft 服务器中安装 `WebShopX-Payments` 插件，启动内嵌支付服务，并实现与主商城插件 `WebShopX` 的无缝联动。 +本节说明如何在 Minecraft 服务器中安装 `WebShopX-Payments`、启动内嵌支付服务，并与 `WebShopX` 连接。 ## 1. 环境要求 @@ -86,5 +86,5 @@ sequenceDiagram ``` :::note[事务失败容灾] -如果在上述第 **14** 步回调发货时，`WebShopX` 的入账监听器因为临时数据库挂起等原因执行失败，该笔已成功付款的交易会在 `wsxpay-orders.yml` 中保留为待确认状态，并在稍后不断发起重试，直到发货逻辑完全成功为止，从而确保不会漏单。 +如果支付状态通知未被业务监听器确认，记录会在 `wsxpay-orders.yml` 中保持未通知状态；插件运行期间会定时重试。该机制用于降低临时故障造成的漏通知风险，但运维人员仍应监控失败日志并核对支付平台账单与 WebShopX 账单。 ::: diff --git a/docs/webshopx-payments/official-channels.md b/docs/webshopx-payments/official-channels.md index 216f581..934383c 100644 --- a/docs/webshopx-payments/official-channels.md +++ b/docs/webshopx-payments/official-channels.md @@ -7,7 +7,7 @@ sidebar_position: 5 # 官方支付通道配置 -官方支付通道通过接入各支付平台的官方商户接口，直接完成订单的预创建、扫码以及状态同步。由于是官方直连通道，具备**并发高**、**状态响应即时**、**无需任何 Hook 软件常驻**等绝对优势，是生产环境的推荐选择。 +官方支付通道通过各平台的商户接口完成订单预创建、扫码与状态同步。相比按金额匹配的 Hook 方案，它能按平台订单号区分并发订单，也不需要 Hook 软件常驻；生产使用前仍应完成沙盒或小额实测、回调验证和账单对账。 v3.1.1 支持从 WebShopX 的 Provider 设置页维护插件公开的渠道字段，但密钥仍由 WebShopX-Payments 校验和保存。页面未展示的高级字段继续编辑当前版本生成的 `backend/config.json`。 diff --git a/docs/webshopx-payments/overview.md b/docs/webshopx-payments/overview.md index 683cc60..81476c6 100644 --- a/docs/webshopx-payments/overview.md +++ b/docs/webshopx-payments/overview.md @@ -47,7 +47,7 @@ This plugin is based on [SweetCheckout](https://github.com/MrXiaoM/SweetCheckout :::warning[高危配置与防坑提醒] 1. **不要暴露内嵌后端端口**：默认的 `62233` 端口仅用于 Bukkit 插件与后端之间的 WebSocket/HTTP 通信。Hook 终结点路径（`/api/hook/receive`）并无安全校验，**请勿将后端端口直接暴露到公网**！ -2. **Hook 模式的金额竞争冲突**：所有 Hook 模式（支付宝/微信 Hook）均依赖 **“付款金额”** 进行订单匹配。**同一时间段内，不能有两名玩家同时创建相同金额的 Hook 订单**（例如不能同时创建两个 1.00 元的微信扫码订单）。后面发起的玩家必须等待前面的订单支付完成或超时取消。官方接口（WeChat Native、Alipay 订单码等）则完全无此限制。 +2. **Hook 模式的金额竞争冲突**：所有 Hook 模式（支付宝/微信 Hook）均依赖 **“付款金额”** 进行订单匹配。**同一时间段内，不能有两名玩家同时创建相同金额的 Hook 订单**（例如不能同时创建两个 1.00 元的微信扫码订单）。后面发起的玩家必须等待前面的订单支付完成或超时取消。官方商户接口使用平台订单号匹配，不受这项同金额限制。 3. **私钥凭证安全**：请勿将包含生产密钥、商户私钥、Client Secret 的配置文件或 `secrets` 密钥文件夹上传至公开代码库。 ::: @@ -55,7 +55,7 @@ This plugin is based on [SweetCheckout](https://github.com/MrXiaoM/SweetCheckout 1. 先确保 `WebShopX` 本身部署就绪，能够正常访问管理后台。 2. 安装 `WebShopX-Payments` 并选择合适的支付通道（先建议配置 PayPal 沙盒或微信/支付宝经营收款码进行小额测试）。 -3. 玩家进行测试支付，并在扫码支付后游戏内能够瞬时收到 WebShopX 的入账与发货命令通知。 +3. 玩家进行测试支付，确认支付状态、WebShopX 入账和发货结果均正确；Hook 与异步回调渠道可能存在处理延迟。 4. 在生产环境正式上线。 --- @@ -75,8 +75,6 @@ This plugin is based on [SweetCheckout](https://github.com/MrXiaoM/SweetCheckout 3. **接受条款** 使用或保留本项目的任何部分（包括源码或编译文件），即视为您已阅读并完全同意本声明的所有条款。**如有异议，请立即停止使用并彻底删除所有相关文件。** -:::info[💡 关于“无费率”的补充说明] -项目简介中所提及的“无费率”，是指**本项目绝不额外收取任何中间手续费或平台抽成**。 - -* **示例**：如您使用支付宝官方的“当面付/订单码支付”接口，支付宝官方会正常收取 0.6% 的商户手续费（最终费率即为 0.6%），本项目作为开源工具，中间不会产生任何额外的二次抽成或隐形费用。 +:::info[💡 关于“无额外平台抽成”的说明] +项目所称“无额外平台抽成”，仅表示 WebShopX-Payments 本身不在交易中收取佣金。支付机构、收单机构、换汇或网络服务仍可能按商户协议收费，具体费率以对应平台和商户合同为准。 ::: diff --git a/docs/webshopx/player/algorithm.md b/docs/webshopx/player/algorithm.md index 35848ca..daf3357 100644 --- a/docs/webshopx/player/algorithm.md +++ b/docs/webshopx/player/algorithm.md @@ -1,11 +1,11 @@ ---- +--- id: algorithm title: 算法 sidebar_label: 算法 sidebar_position: 8 --- -# WebShopX 算法 详细手册 +# WebShopX 算法详解 > **文档性质**：深度手册 @@ -13,14 +13,15 @@ sidebar_position: 8 ## 🏗️ 第一章：核心架构 -动态价格算法、拍卖机制算法让 WebShopX 从传统的“静态商店”转向一个基于 **热度反馈机制（Demand-Driven Feedback）** 驱动的自适应经济引擎。系统的核心目标是通过算法自动调节物价，利用数学模型对冲服务器的通货膨胀。 +动态价格与拍卖算法让 WebShopX 在固定价格之外提供基于市场压力的定价和多种竞价机制。管理员应结合服务器经济数据配置价格边界，并先在少量商品上验证效果。 ### 1.1 核心防护机制 -* **🛡️ 钳制函数 (Clamping)**：所有动态价格在经过复杂公式计算后，最终都会被收敛在服主设定的绝对安全区间内： + +- **🛡️ 边界钳制 (Clamping)**：配置最低价或最高价后，动态价格会被限制在相应区间内： $$P_{\text{final}} = \max(P_{\min}, \min(P_{\text{calc}}, P_{\max}))$$ - 这意味着无论算法如何暴走，物价永远不会击穿 $P_{\max}$（最高限价）和 $P_{\min}$（底价）。 -* **📜 事务溯源**：底层的 `MarketService` 与持久化层深度绑定，每一笔订单、每一次价格演变均有详细日志记录，支持发生挤兑时的经济复盘。 -* **🔒 乐观锁并发**：采用基于 `version` 字段的数据库乐观锁控制，在高频交易（如全服抢购）场景下，严格防止“超卖”和“读写竞争”产生的经济漏洞。 + 同时配置 $P_{\max}$（最高限价）和 $P_{\min}$（最低价）时，最终价格不会超出这两个边界。 +- **📜 持久化记录**：订单、成交和价格历史写入数据库，可用于运营排查与经济复盘。 +- **🔒 事务并发控制**：市场成交会在数据库事务中锁定并重新读取相关记录，以降低并发交易造成的库存和余额竞争风险。 --- @@ -31,93 +32,113 @@ sidebar_position: 8 系统通过监测**需求热度 ($D_t$)**，利用以下数学模型实时计算成交价。每一种算法都对应着不同的经济调节目的。 ### 📈 1. 线性需求 (LINEAR_DEMAND_V1) + 最经典、最直观的供需模型。买得越多，涨得越稳。 -* **数学公式**：$P_t = P_0 + k \cdot D_t$ -* **参数解析**：$k$ 为价格斜率。若 $k=0.5$，每增加 1 点热度，价格上涨 0.5。 -* **经济学应用**：适用于**基础矿物（铁锭、煤炭）**等产出稳定、消耗极大的硬通货。能有效设定服务器的基础物价基准。 + +- **数学公式**：$P_t = P_0 + k \cdot D_t$ +- **参数解析**：$k$ 为价格斜率。若 $k=0.5$，每增加 1 点热度，价格上涨 0.5。 +- **经济学应用**：适用于**基础矿物（铁锭、煤炭）**等产出稳定、消耗极大的硬通货。能有效设定服务器的基础物价基准。 ### 📉 2. 边际递减 (DIMINISHING_RETURN_V1) + 初期涨价明显，但随着热度不断攀升，涨价幅度会遭到强力压制，最终无限趋近于一个上限。 -* **数学公式**：$P_t = P_0 + a \cdot \frac{D_t}{1 + bD_t}$ -* **参数解析**：极限溢价为 $a/b$。若 $a=10, b=0.1$，则无论买多少，最高只会比原价贵 100。 -* **经济学应用**：适用于**大宗建筑方块（泥土、石砖、混凝土）**。保护建筑党玩家，防止他们因为购买几千个方块而破产。 + +- **数学公式**：$P_t = P_0 + a \cdot \frac{D_t}{1 + bD_t}$ +- **参数解析**：极限溢价为 $a/b$。若 $a=10, b=0.1$，则无论买多少，最高只会比原价贵 100。 +- **经济学应用**：适用于**大宗建筑方块（泥土、石砖、混凝土）**。保护建筑党玩家，防止他们因为购买几千个方块而破产。 ### 🌊 3. 对数平滑 (LOG_SMOOTH_V1) + 对数字变化极度脱敏的模型，曲线非常圆润。 -* **数学公式**：$P_t = P_0 \cdot (1 + \alpha \ln(1 + D_t))$ -* **参数解析**：$\alpha$ 控制平滑度。在热度从 100 涨到 1000 的过程中，价格可能只上涨了不到一倍。 -* **经济学应用**：适用于**日常高频消耗品（火把、面包、箭矢）**。玩家零碎购买时，体感上几乎察觉不到涨价，体验极佳。 + +- **数学公式**：$P_t = P_0 \cdot (1 + \alpha \ln(1 + D_t))$ +- **参数解析**：$\alpha$ 控制平滑度。在热度从 100 涨到 1000 的过程中，价格可能只上涨了不到一倍。 +- **经济学应用**：适用于**日常高频消耗品（火把、面包、箭矢）**。玩家零碎购买时，体感上几乎察觉不到涨价，体验极佳。 ### 🚀 4. 指数防护 (EXPONENTIAL_DEFENSE_V1) -极其暴力的反垄断防御塔。热度微小的提升会导致价格呈几何倍数核爆级上涨。 -* **数学公式**：$P_t = P_0 \cdot e^{\beta D_t}$ -* **参数解析**：$\beta$ 为指数倍率。通常设置在 0.01 到 0.05 之间。 -* **经济学应用**：适用于**战略级物资（下界合金锭、信标、极品附魔书）**。允许普通玩家买一两个，但若土豪企图一次性买 50 个清空库存，天文数字的价格会瞬间抽干他的钱包。**强烈建议严格配置 $P_{\max}$。** + +需求压力上升时，价格会按指数曲线增长，适合需要抑制集中购买的稀缺商品。 + +- **数学公式**：$P_t = P_0 \cdot e^{\beta D_t}$ +- **参数解析**：$\beta$ 为指数倍率。通常设置在 0.01 到 0.05 之间。 +- **应用建议**：可用于**战略级物资（下界合金锭、信标、高级附魔书）**。指数增长较快，建议配置合理的 $P_{\max}$ 并先做小范围测试。 ### 🚧 5. 阈值分段 (THRESHOLD_STEP_V1) + 不触碰红线就相安无事，一旦越界重拳出击。 -* **数学公式**： - * 当 $D_t \le T$ 时：$P_t = P_0 + k_1 D_t$ - * 当 $D_t > T$ 时：$P_t = P_0 + k_1 T + k_2(D_t - T)$ （其中 $k_2 \gg k_1$） -* **参数解析**：$T$ 为安全阈值。 -* **经济学应用**：适用于**功能性道具（潜影壳、经验瓶、刷怪蛋）**。精准区分“正常玩家买来用”和“工作室大规模囤货倒卖”。 + +- **数学公式**： + - 当 $D_t \le T$ 时：$P_t = P_0 + k_1 D_t$ + - 当 $D_t > T$ 时：$P_t = P_0 + k_1 T + k_2(D_t - T)$ （其中 $k_2 \gg k_1$） +- **参数解析**：$T$ 为安全阈值。 +- **经济学应用**：适用于**功能性道具（潜影壳、经验瓶、刷怪蛋）**。精准区分“正常玩家买来用”和“工作室大规模囤货倒卖”。 ### ⚖️ 6. 弹性模型 (ELASTICITY_V1) + 引入经济学中的“价格弹性”概念。 -* **数学公式**：$P_t = P_0 \cdot (\frac{D_t + \varepsilon}{D_0 + \varepsilon})^{\eta}$ -* **参数解析**：$\eta$（Eta）为弹性指数。$\eta < 1$ 市场表现迟钝（抗跌抗涨），$\eta > 1$ 市场极度敏感（暴涨暴跌）。 -* **经济学应用**：适用于**特殊代币、绿宝石**。服主可以通过调整 $\eta$ 直接操控市场的神经敏感度。 + +- **数学公式**：$P_t = P_0 \cdot (\frac{D_t + \varepsilon}{D_0 + \varepsilon})^{\eta}$ +- **参数解析**：$\eta$（Eta）为弹性指数。$\eta < 1$ 市场表现迟钝（抗跌抗涨），$\eta > 1$ 市场极度敏感（暴涨暴跌）。 +- **应用建议**：可用于**特殊代币、绿宝石**。管理员可通过调整 $\eta$ 控制价格对市场压力的敏感程度。 ### 🔥 7. 恐慌抢购 (PANIC_BUYING_V1) + 模拟真实世界中的“羊群效应”与挤兑危机。 -* **数学公式**：$P_t = P_0 + kD_t + \gamma \cdot \max(0, D_t - T)^2$ -* **参数解析**：引入了二次项 $\gamma$。突破阈值 $T$ 后，价格进入抛物线加速上涨轨道。 -* **经济学应用**：适用于**绝版头颅、活动限量盲盒**。用极端的涨幅引爆玩家的抢购心理。 + +- **数学公式**：$P_t = P_0 + kD_t + \gamma \cdot \max(0, D_t - T)^2$ +- **参数解析**：引入了二次项 $\gamma$。突破阈值 $T$ 后，价格进入抛物线加速上涨轨道。 +- **应用建议**：可用于**绝版头颅、活动限量物品**。阈值后的涨幅较快，应配合价格上限和运营监控。 --- -## 🔨 第三章：拍卖机制算法全解析 (4大模式) +## 🔨 第三章：拍卖机制算法解析（4 种模式） ### 📢 1. 英式公开拍卖 (English Auction) -* **机制运行**：经典的“价高者得”。每一次有效出价都会成为新的**基准价**。 -* **反制狙击 (Anti-Snipe)**：系统内置软性延时机制。如果在结束前最后 $N$ 秒内有人出价，倒计时会自动延长 $M$ 秒，彻底消灭“在最后一秒卡点出价”的玩法。 -* **资产冻结**：玩家出价瞬间，对应钱包资金即被**强锁**；一旦被后来者超越，`AsyncRefundTask` 会在毫秒级内将资金解冻退回。 + +- **机制运行**：经典的“价高者得”。每一次有效出价都会成为新的**基准价**。 +- **反狙击 (Anti-Snipe)**：如果在结束前最后 $N$ 秒内有人有效出价，结束时间会延长 $M$ 秒，降低最后一刻出价的优势。 +- **资金冻结**：有效出价会冻结相应钱包资金；被超越或拍卖结算后，系统会在事务中处理解冻和退款记录。 ### 📉 2. 荷兰减价拍卖 (Dutch Auction) -* **机制运行**：从一个不可理喻的天价起步，价格随时间流逝呈阶梯式下跌（例如每小时降价 5%）。 -* **心理博弈**：全服玩家同时盯着一个物品，先点击“买断”的人瞬间成交。等得越久越便宜，但也越容易被截胡。 -* **应用场景**：服务器官方清仓大甩卖、高价值地皮起拍。 + +- **机制运行**：价格从起拍价开始，在配置的持续时间内线性下降至底价。 +- **心理博弈**：全服玩家同时盯着一个物品，先点击“买断”的人瞬间成交。等得越久越便宜，但也越容易被截胡。 +- **应用场景**：服务器官方清仓大甩卖、高价值地皮起拍。 ### 📦 3. 密封第二价格拍卖 (Vickrey Auction) -* **机制运行**：暗拍模式。在开标前，所有人的出价都被加密隐藏。截止后，**出价最高的人获胜，但他只需要支付“第二高的出价金额”**。 -* **经济学原理**：诺贝尔经济学奖级的设计。这在博弈论中消除了“赢家诅咒”，在数学上证明了**“玩家报出自己内心真实的最高底线”是唯一的绝对优势策略（Dominant Strategy）**。无需互相揣测，回归物品真实价值。 + +- **机制运行**：暗拍模式。在开标前，所有人的出价都被加密隐藏。截止后，**出价最高的人获胜，但他只需要支付“第二高的出价金额”**。 +- **机制说明**：在标准独立私人价值模型等假设下，第二价格拍卖会鼓励参与者按自身估值出价；实际结果仍取决于参与者、保留价和服务器配置。 ### 🕯️ 4. 蜡烛随机拍卖 (Candle Auction) -* **机制运行**：流程类似英式拍卖，**但真实的流拍结束点是一个隐藏的随机数**。 -* **应用特色**：表面倒计时是晚上 8:00 结束，但系统可能在 7:55 到 8:00 之间的任意一毫秒悄悄落锤判定。玩家被迫尽早给出有竞争力的价格，而不是苟到最后。 + +- **机制运行**：流程类似英式拍卖，但实际结束时间会在公开结束时间之后的随机扩展窗口内确定。 +- **应用特色**：参与者无法准确预知扩展窗口内的最终结束时刻，因此更适合提前给出有效出价。 --- ## 🔧 第四章：服主深度调参实战指南 ### 4.1 价格热度的双轨驱动 + 动态价格的引擎不仅受买入影响，还受时间影响： + 1. **正向反馈（买入/事件驱动）**：玩家每次下单，系统根据购买数量向该商品池注入热度（Demand）。 -2. **负向反馈（时间驱动/衰减）**：系统内部运行着一个 Cron 任务，以固定周期（如每 6 小时）执行衰减衰减：$D_{\text{new}} = D_{\text{old}} \cdot (1 - \text{DecayRate})$。 +2. **回归反馈（时间驱动/衰减）**：周期任务按配置步长让市场压力向 0 回归：正值减小、负值增大，且不会越过 0。 ### 4.2 调参安全红线 (Safety Protocols) -* **灰度测试**：不要一上来就把全服硬通货改成动态价格。先用“腐肉”、“骨头”这种边缘物品开辟一个试验田，观察玩家行为和曲线 3-5 天后再全面推广。 + +- **灰度测试**：不要一上来就把全服硬通货改成动态价格。先用“腐肉”、“骨头”这种边缘物品开辟一个试验田，观察玩家行为和曲线 3-5 天后再全面推广。 --- ## 🐛 第五章：技术故障排查与工单支持 **Q1: 为什么网页端看到的价格，点购买时提示价格已变化？** -A: 这是正常的。在高频动态市场中，你浏览页面和发起请求之间存在时间差。如果有别人抢先买了一份，热度更新会导致最新价格高于你看到的缓存价。这也是 `version` 乐观锁在起保护作用。 +A: 页面展示与提交交易之间可能发生其他成交，市场压力和报价因此变化。刷新页面并按最新报价重新确认即可。 **Q2: 玩家反馈拍卖流拍后，钱卡在冻结状态没有退回？** -A: 大概率是服务器遭遇了瞬时的 TPS 骤降或内存溢出（OOM），导致异步退款任务（`AsyncRefundTask`）被挂起。 -**解决方案**：请服主在后台查看日志定位报错，然后可手动调用管理员指令或重启插件同步状态。 +A: 先检查拍卖是否已到实际结束时间（蜡烛拍卖可能包含随机扩展窗口），再查看市场记录、钱包账单和服务端日志。若状态长时间未推进，请保留上架 ID、时间和相关日志后提交 Issue；不要直接修改数据库。 --- @@ -127,4 +148,3 @@ WebShopX 正在逐步完善中。如果您在部署过程中遇到任何 Bug， 👉 **请至 GitHub 官方仓库提交 Issue：** [WebShopX-Issues (点击进入反馈中心)](https://github.com/Prism-Committee/WebShopX-Issues) - diff --git a/docs/webshopx/player/auctions.md b/docs/webshopx/player/auctions.md index 12b2f65..d7192e3 100644 --- a/docs/webshopx/player/auctions.md +++ b/docs/webshopx/player/auctions.md @@ -17,7 +17,7 @@ WebShopX 拍卖包含多种竞价模式，并涉及出价、资金冻结、退 ## 2. 拍卖模式速览 -> 主条目：[拍卖算法](algorithm#-第三章拍卖机制算法全解析-4大模式) +> 主条目：[拍卖算法](algorithm#-第三章拍卖机制算法解析4-种模式) | 模式 | 交互方式 | 价格机制 | 适用场景 | | --- | --- | --- | --- | @@ -51,7 +51,7 @@ WebShopX 拍卖包含多种竞价模式，并涉及出价、资金冻结、退 ## 3. 各模式关键参数 -> v3 前端已经加入相关提示。另可参考 [拍卖算法](algorithm#-第三章拍卖机制算法全解析-4大模式)。 +> v3 前端已经加入相关提示。另可参考 [拍卖算法](algorithm#-第三章拍卖机制算法解析4-种模式)。 ## 4. 出价与资金冻结 diff --git a/docs/webshopx/player/dynamic-pricing.md b/docs/webshopx/player/dynamic-pricing.md index 1512dc8..3e8f3a1 100644 --- a/docs/webshopx/player/dynamic-pricing.md +++ b/docs/webshopx/player/dynamic-pricing.md @@ -60,7 +60,7 @@ sidebar_position: 6 ## 4 页面展示算法解读 -> 主条目：[动态价格算法](algorithm#-第二章动态价格算法全解析-7大基石模型) +> 主条目：[动态价格算法](algorithm#-第二章动态价格算法解析) 购买时页面上会显示具体算法名。理解它们，有助于你更好判断买入节奏和商机： diff --git a/docs/webshopx/player/shop-and-orders.md b/docs/webshopx/player/shop-and-orders.md index b99bd75..d3abc60 100644 --- a/docs/webshopx/player/shop-and-orders.md +++ b/docs/webshopx/player/shop-and-orders.md @@ -17,15 +17,19 @@ sidebar_position: 4 | ----------------------- | --------------- | ------------------------------------------ | | **`COMMAND`** | **指令执行** | 购买后由控制台或以玩家身份执行预设指令。 | | **`GIVE_ITEM`** | **物品发放** | 系统直接生成物理道具并放入玩家背包。 | -| **`POTION_EFFECT`** | **药水效果** | 购买后为玩家施加特定的 药水效果。 | +| **`GIVE_CUSTOM_ITEM`** | **自定义物品** | 购买后按配置执行自定义物品发放逻辑。 | +| **`POTION_EFFECT`** | **药水效果** | 购买后为玩家施加特定的药水效果。 | +| **`SNAPSHOT_ITEM`** | **快照物品** | 按已保存的物品快照发放物品。 | | **`RECYCLE_ITEM`** | **回收/兑换** | 系统以特定价格回收玩家特定物品。 | +| **`RECYCLE_COMMAND_ITEM`** | **指令回收** | 回收匹配物品后执行配置的指令。 | +| **`RECYCLE_CUSTOM_ITEM`** | **自定义回收** | 按自定义物品规则匹配并回收。 | | **`GROUP_BUY_VOUCHER`** | **团购/兑换码** | 交付特定的序列号或兑换凭证，支持群体核销。 | -## 2、玩家市场 +## 2. 玩家市场 玩家市场是由玩家自主驱动的 **C2C** 交易体系。它允许玩家上架物品、发布收购单、上架拍卖物品等进行剩余物资的流通，是服务器内部循环经济的核心载体。 -### (1)三个维度 +### (1) 三个维度 玩家市场支持多种交易方式，由以下三个维度组合而成（例如：**卖家出货 + 一口价 + 手动库存 = 普通上架**）。 @@ -41,7 +45,7 @@ sidebar_position: 4 | **成交机制 (TradeMode)** | `DIRECT` / `AUCTION` | **DIRECT**: 一口价即时交易；**AUCTION**: 竞价拍卖模式。 | | **库存来源 (SourceMode)** | `MANUAL` / `SUPPLY` | **MANUAL**: 手动上架库存；**SUPPLY**: 关联供货箱自动补货。 | -### (2)支持的上架模式 +### (2) 支持的上架模式 | **上架模式** | **Side (方向)** | **TradeMode (机制)** | **SourceMode (库存)** | **典型应用场景** | | -------------- | --------------- | -------------------- | --------------------- | ---------------------------------------------- | @@ -52,7 +56,7 @@ sidebar_position: 4 ## 3. 订单系统 -订单系统是市场交易的逻辑核心，负责记录并处理从“发起交易”到“物资交付”的全过程。它支持订单状态的实时追踪，并内置了完善的退款与冷却机制，确保在异步交易环境下买卖双方的利益不受损失。 +订单系统记录并处理从“发起交易”到“物资交付”的流程，提供状态追踪、退款策略与冷静期配置。具体结果仍取决于订单状态、库存、权限和服务器运行状况。 ### (1) 订单状态 @@ -93,11 +97,11 @@ sidebar_position: 4 ## 4. 其它 -### (1)动态价格 +### (1) 动态价格 -动态价格是一种基于 **供需算法** 实时调整的定价机制。系统根据特定周期内的交易频率、库存余量及成交额，自动计算并更新物品的基准单价。 +动态价格是一种根据市场压力调整价格的机制。购买会提高压力，回收会降低压力，周期任务让压力按配置步长向 0 回归；具体价格由所选算法、基础价格、压力值和价格边界共同决定。 -> 主条目：[动态价格](dynamic-pricing)、[动态价格算法](algorithm#-第二章动态价格算法全解析-7大基石模型) +> 主条目：[动态价格](dynamic-pricing)、[动态价格算法](algorithm#-第二章动态价格算法解析) | **模块** | **类型 / 模式** | **支持情况** | **驱动逻辑** | | ------------ | ------------------ | ------------ | ------------ | @@ -110,7 +114,7 @@ sidebar_position: 4 ### (2) 拍卖 -> 主条目：[拍卖](auctions)、[拍卖算法](algorithm#-第三章拍卖机制算法全解析-4大模式) +> 主条目：[拍卖](auctions)、[拍卖算法](algorithm#-第三章拍卖机制算法解析4-种模式) 拍卖是一种基于**竞价逻辑**的特殊交易形式。它适用于价值难以估量或极其稀缺的物品。卖家设定起拍价与加价阶梯，在限定时间内引导买家进行博弈。系统通过订单系统锁定出价最高者的资金，并在结标时自动完成所有权转移。 diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 9b0df79..76ce529 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -1,4 +1,4 @@ -import {themes as prismThemes} from 'prism-react-renderer'; +import {themes as prismThemes} from 'prism-react-renderer'; import type {Config} from '@docusaurus/types'; import type * as Preset from '@docusaurus/preset-classic'; import { docusaurusVersion } from '@generated/site-metadata'; diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/commands-permissions.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/commands-permissions.md index 5510f2f..0332a70 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/commands-permissions.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/commands-permissions.md @@ -7,7 +7,7 @@ sidebar_position: 7 # Commands & Permissions -`WebShopX-Payments` provides extremely simple in-game commands and permission nodes, mainly used by administrators for configuration hot-reloading and runtime troubleshooting. +`WebShopX-Payments` provides in-game commands and permission nodes for configuration hot-reloading and runtime troubleshooting. --- diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/faq.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/faq.md index b4a6634..3dbdeff 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/faq.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/faq.md @@ -71,10 +71,10 @@ For security reasons, the embedded backend validates whether the Hook helper sof ### Q: Java Class Version errors occur during Gradle builds? :::note[Recommended Build Environment] -The `WebShopX-Payments` source code utilizes modern Java features. **JDK 25 is recommended and required** for compilation. +The project CI currently builds with JDK 25, so using JDK 25 locally is recommended to match the official build environment. Plugin artifacts target Java 8 bytecode; this does not mean the Minecraft server runtime must use Java 25. In a Windows PowerShell terminal, you can temporarily specify the JDK path for compilation using: ```powershell -$env:JAVA_HOME='C:\Program Files\Java\jdk-25.0.3' +$env:JAVA_HOME='C:\Program Files\Java\jdk-25' $env:JAVA_TOOL_OPTIONS='-Duser.country=US' .\gradlew.bat :plugin:bukkit:with-backend:build ``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/hook-channels.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/hook-channels.md index e97c759..206685e 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/hook-channels.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/hook-channels.md @@ -114,7 +114,7 @@ WeChat Hook v4 is developed based on the principles of the [echotrace](https://g ### (3) Adjusting Timeout for Database Latency :::warning[Critical Configuration Tweak] Due to the persistence mechanism of the local WeChat database, it takes **about 10 seconds or longer** for the PC client to write messages into local database files after the mobile app receives a payment notification. -Therefore, when using the Hook v4 channel, you must increase the timeout in `config.yml` on the plugin side (we recommend 200 seconds or more); otherwise, players will easily trigger timeouts while waiting for decryption: +Because PC WeChat can delay writing payment messages to its local database, Hook v4 processing may not begin immediately. Increase the plugin-side timeout in `config.yml` based on observed latency; 200 seconds can be used as an initial troubleshooting value and then adjusted from logs and business requirements: ```yaml # config.yml payment: diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/install-deploy.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/install-deploy.md index 1e9c610..221e560 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/install-deploy.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/install-deploy.md @@ -11,8 +11,8 @@ Install `WebShopX-Payments` on the Minecraft server, launch the embedded payment ## 1. Environment Requirements -- **Java Version**: `Java 21` or higher is required for operation (we recommend `JDK 25` for compilation). -- **Minecraft Server**: `Paper 1.20.6+` (fully compatible with common server software like Spigot, Purpur, etc.). +- **Java Runtime**: Follow the requirement of your Minecraft server. The plugin artifacts target Java 8 bytecode; the JDK used by the project's build workflow does not set the server runtime requirement. +- **Minecraft Server**: The release contains multiple Bukkit/NMS adapters. Use the compatibility list in the release notes for the exact build you install; the current source tree includes adapters from older Bukkit versions through 1.21.x/26.1. - **Prerequisite Dependency**: You must install the [WebShopX Core Plugin](https://modrinth.com/plugin/webshopx) in the same directory. - **Network Connectivity**: The server requires stable internet access to reach Alipay, WeChat Pay, PayPal, MercadoPago, and other payment gateways. If you are deploying on a server inside mainland China and using PayPal or MercadoPago, we strongly advise configuring a proxy in the backend settings. @@ -86,5 +86,5 @@ sequenceDiagram ``` :::note[Transaction Failure Tolerance] -If, during step **14**, the billing listener on `WebShopX` fails to execute (e.g., due to temporary database locks), the successfully paid transaction will be saved as a pending confirmation state in `wsxpay-orders.yml`. The plugin will continually retry the notification until delivery is fully successful, thereby preventing any lost orders. +If a business listener does not confirm a payment-status notification, the record remains unnotified in `wsxpay-orders.yml`; the plugin retries it periodically while running. This reduces missed-notification risk during temporary failures, but operators should still monitor errors and reconcile payment-platform records with the WebShopX ledger. ::: diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/official-channels.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/official-channels.md index 98b8352..86944ff 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/official-channels.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/official-channels.md @@ -7,7 +7,7 @@ sidebar_position: 5 # Official Payment Channels Configuration -Official payment channels integrate directly with the official merchant APIs of each payment gateway, completing order pre-creation, QR code generation, and state synchronization. Because they are direct official channels, they possess absolute advantages such as **high concurrency capabilities**, **instantaneous status responses**, and **zero requirements for desktop Hook listener software**, making them the highly recommended choice for production environments. +Official payment channels use merchant APIs to create orders, present payment codes, and synchronize status. Compared with amount-matched Hook flows, they distinguish concurrent orders by platform order ID and do not require persistent Hook software. Before production use, still test in a sandbox or with a small amount, verify callbacks, and reconcile the resulting records. --- diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/overview.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/overview.md index 7522b66..23beddd 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/overview.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/overview.md @@ -9,7 +9,7 @@ sidebar_position: 1 ## Feedback & Issues -- Issues Repository: https://github.com/Prism-Committee/WebShopX-Issues +- Issues Repository: https://github.com/Prism-Committee/WebShopX-Payments This directory is aimed at plugin installers, system administrators, and server operators, detailing the deployment and configuration of the `WebShopX-Payments` integration plugin. @@ -44,7 +44,7 @@ This directory is aimed at plugin installers, system administrators, and server :::warning[Critical Configuration & Pitfall Warnings] 1. **Do not expose the embedded backend port**: The default port `62233` is used strictly for WebSocket/HTTP communications between the Bukkit plugin and the backend. The Hook receiver endpoint (`/api/hook/receive`) has no security signature validation. **Do not expose this backend port directly to the public internet!** -2. **Amount race conditions in Hook Mode**: All Hook modes (Alipay/WeChat Hook) rely solely on the **"exact payment amount"** to match orders. **Two players cannot create Hook orders with the exact same amount at the same time** (e.g., two concurrent WeChat scan orders for 1.00 USD). Subsequent players must wait for the preceding order to complete or time out. Official enterprise merchant APIs (WeChat Native, Alipay order codes, etc.) have no such restriction. +2. **Amount race conditions in Hook Mode**: All Hook modes (Alipay/WeChat Hook) rely solely on the **"exact payment amount"** to match orders. **Two players cannot create Hook orders with the exact same amount at the same time** (for example, two concurrent WeChat orders for CNY 1.00). Subsequent players must wait for the preceding order to complete or time out. Official merchant APIs match platform order IDs and do not have this same-amount restriction. 3. **Secret credentials safety**: Never upload configuration files or `secrets` credential folders containing production keys, merchant private keys, or Client Secrets to any public code repositories. ::: @@ -52,7 +52,7 @@ This directory is aimed at plugin installers, system administrators, and server 1. Ensure that the core `WebShopX` plugin is deployed, initialized, and its administration panel is fully accessible. 2. Install `WebShopX-Payments` and choose your preferred payment channel (we recommend starting with small-amount tests using PayPal Sandbox or standard WeChat/Alipay merchant QR codes). -3. Have a player perform a test payment, and verify that the player instantaneously receives the WebShopX credit and item delivery command execution in-game upon scanning the code. +3. Have a player perform a test payment and verify the payment state, WebShopX credit, and delivery result. Hook and asynchronous callback channels can introduce processing delay. 4. Launch officially in your production environment. --- @@ -72,8 +72,6 @@ This project is for **educational, research, and technical exchange purposes onl 3. **Acceptance of Terms** Using or retaining any portion of this project (including source code or compiled binaries) constitutes your reading and full acceptance of all terms in this disclaimer. **If you object to any terms, please stop using it immediately and delete all related files completely.** -:::info[💡 Supplemental note on "No Commissions"] -The "No Commissions/Fees" mentioned in the project description means that **this project never charges any middleman transaction processing fees or platform cuts**. - -* **Example**: If you use Alipay's official "Face-to-Face Payment/Order Code" interface, Alipay will charge its standard 0.6% merchant processing fee. As an open-source tool, this project does not add any extra commission or hidden fees on top of it. +:::info[💡 About "No Additional Platform Commission"] +This means WebShopX-Payments itself does not collect a commission from transactions. Payment providers, acquirers, currency conversion, or network services may still charge fees under the merchant's agreement; confirm current rates with the relevant provider. ::: diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/payment-solution.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/payment-solution.md index 63dbcc6..5162d2c 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/payment-solution.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx-payments/payment-solution.md @@ -9,6 +9,12 @@ sidebar_position: 4 `WebShopX-Payments` currently supports or implements the following payment solutions, which can be used to evaluate availability and integration priority. +:::info[Scope for v3.1.1] + +"Implemented" does not guarantee that a merchant account is eligible or correctly configured. Enable the channel in both the Bukkit configuration and `backend/config.json`, then verify it in a sandbox or with the smallest practical amount. + +::: + | **Status** | **Platform** | **Solution** | **Description** | | --- | --- | --- | --- | | 🟢 | Alipay | [Order Code Payment](https://open.alipay.com/api/detail?code=I1080300001000068149&index=0) | **Official API**. The server calls official APIs to generate dynamic checkout QR codes, which users scan to pay. | @@ -26,4 +32,4 @@ sidebar_position: 4 > - **🟡 Pending Verification**: Code implementation is complete. However, due to developers lacking sandbox/production credentials for these specific interfaces, real-world tests have not been executed. > - **🔴 Not Available**: The solution is currently unavailable or lacks an effective implementation methodology. > -> If you have successfully tested and verified any 🔵 or 🟡 channels, feel free to submit an issue to share your feedback! +> These statuses are project-side verification records, not payment-platform SLAs. When reporting a test for a 🔵 or 🟡 channel, include the plugin version, region, currency, and redacted logs. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/algorithm.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/algorithm.md index 9673eb2..f87f7a9 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/algorithm.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/algorithm.md @@ -5,7 +5,7 @@ sidebar_label: Algorithm sidebar_position: 8 --- -# WebShopX Algorithm Handbook (Detailed) +# WebShopX Algorithm Guide > **Document Type**: Deep Technical Manual @@ -13,19 +13,19 @@ sidebar_position: 8 ## Chapter 1: Core Architecture and Design Philosophy -Dynamic pricing and auction algorithms move WebShopX from a traditional "static shop" toward an adaptive economy engine driven by a **demand-driven feedback** mechanism. The core goal is to automatically regulate prices and use mathematical models to hedge server inflation. +Dynamic pricing and auction algorithms add market-pressure pricing and several bidding mechanisms alongside fixed prices. Administrators should configure price bounds from their own economy data and validate the behavior on a small set of products first. ### 1.1 Core Protection Mechanisms -- **Clamping Function**: After complex calculations, all dynamic prices are finally constrained to an owner-defined safe range: +- **Clamping Function**: When a floor or cap is configured, the calculated dynamic price is constrained to that range: $$P_{\text{final}} = \max(P_{\min}, \min(P_{\text{calc}}, P_{\max}))$$ - This means prices never break through $P_{\max}$ (ceiling) or $P_{\min}$ (floor), no matter how aggressive the algorithm behaves. -- **Transaction Traceability**: `MarketService` is deeply bound to persistence. Every order and every price evolution is logged in detail, enabling post-incident economic replay. -- **Optimistic-Lock Concurrency**: Uses DB optimistic locking based on `version` field to prevent overselling and read-write race vulnerabilities under high-frequency trading. + With both bounds configured, the final price does not exceed $P_{\max}$ or fall below $P_{\min}$. +- **Persistent Records**: Orders, trades, and price history are stored for operational investigation and economy review. +- **Transactional Concurrency Control**: Market transactions lock and re-read relevant database records to reduce stock and balance races during concurrent trades. --- -## Chapter 2: Full Dynamic Pricing Analysis (7 Foundation Models) +## Chapter 2: Dynamic Pricing Models By monitoring **demand heat ($D_t$)**, the system computes prices in real time with these models. Each model serves a different economic control objective. @@ -90,29 +90,29 @@ Simulates herd behavior and run-like spikes. --- -## Chapter 3: Full Auction Algorithm Analysis (4 Modes) +## Chapter 3: Auction Models ### 3.1 English Auction - **Mechanism**: Highest bidder wins; each valid bid updates reference price. -- **Anti-snipe**: If valid bid appears in final $N$ seconds, end time extends by $M$ seconds. -- **Asset freeze**: Bid amount is strongly frozen immediately; if outbid, `AsyncRefundTask` unfreezes and refunds promptly. +- **Anti-snipe**: If a valid bid appears in the final $N$ seconds, the end time extends by $M$ seconds, reducing the advantage of last-moment bidding. +- **Fund freeze**: A valid bid freezes the corresponding wallet funds; outbid and settlement paths handle unfreezing and refunds within database transactions. ### 3.2 Dutch Auction -- **Mechanism**: Starts high and decreases over time (for example, step-down per hour). +- **Mechanism**: Price decreases linearly from the starting price to the configured floor over the configured duration. - **Game dynamic**: Waiting can lower price but increases chance of being sniped by another buyer. - **Use cases**: Official clearance sales, high-value liquidation. ### 3.3 Vickrey Auction - **Mechanism**: Sealed bids. Highest bidder wins, but pays second-highest price. -- **Theory**: Encourages truthful bidding under mechanism design and reduces winner's curse effects. +- **Theory**: Under standard independent-private-value assumptions, a second-price auction encourages bidding at one's own valuation. Actual outcomes still depend on participants, reserve price, and server configuration. ### 3.4 Candle Auction -- **Mechanism**: Similar to English auction, but real ending point is hidden and random. -- **Result**: Players are encouraged to bid competitively earlier instead of waiting for last-second snipes. +- **Mechanism**: Similar to an English auction, but the actual end is selected within a random extension window after the public end time. +- **Result**: Because the final moment inside that window is unknown, participants are encouraged to place valid bids earlier. --- @@ -123,8 +123,7 @@ Simulates herd behavior and run-like spikes. Dynamic pricing is affected by both buy events and time: 1. **Positive feedback (event-driven)**: each purchase injects demand based on quantity. -2. **Negative feedback (time-driven decay)**: a periodic job decays demand by configured rate: - $$D_{\text{new}} = D_{\text{old}} \cdot (1 - \text{DecayRate})$$ +2. **Mean-reversion feedback (time-driven decay)**: a periodic job moves market pressure toward zero by a configured step. Positive values decrease and negative values increase without crossing zero. ### 4.2 Safety Protocols for Tuning @@ -136,11 +135,10 @@ Dynamic pricing is affected by both buy events and time: ## Chapter 5: Technical Troubleshooting and Support **Q1: Why does page show one price, but purchase says price changed?** -A: This is normal in high-frequency dynamic markets. Price can update between view and request due to other purchases. `version` optimistic lock is protecting consistency. +A: Another trade may complete between page display and submission, changing market pressure and the quote. Refresh the page and confirm the latest quote. **Q2: Why are frozen funds not refunded after auction failure?** -A: Most likely temporary TPS collapse or OOM paused async refund tasks (`AsyncRefundTask`). -**Fix**: Check backend logs, locate errors, then use admin commands or restart plugin to resync state if needed. +A: First check whether the auction has reached its actual end time; candle auctions can include a random extension window. Then review market records, wallet ledger entries, and server logs. If the state remains unchanged, keep the listing ID, timestamps, and relevant logs and submit an issue. Do not edit the database directly. --- @@ -150,5 +148,3 @@ WebShopX is continuously improving. If you encounter bugs during deployment or w Submit issues to the official GitHub repository: [WebShopX-Issues](https://github.com/Prism-Committee/WebShopX-Issues) - - diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/shop-and-orders.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/shop-and-orders.md index 8298a3c..e19836a 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/shop-and-orders.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/shop-and-orders.md @@ -17,8 +17,12 @@ The official shop is a server-admin-managed **B2C** trading system. Unlike the p | --- | --- | --- | | **`COMMAND`** | **Command Execution** | Executes predefined commands via console or player identity after purchase. | | **`GIVE_ITEM`** | **Item Delivery** | Directly generates physical items and puts them in player inventory. | +| **`GIVE_CUSTOM_ITEM`** | **Custom Item Delivery** | Executes the configured custom-item delivery logic. | | **`POTION_EFFECT`** | **Potion Effect** | Applies specific potion effects after purchase. | +| **`SNAPSHOT_ITEM`** | **Snapshot Item** | Delivers an item from a stored item snapshot. | | **`RECYCLE_ITEM`** | **Recycle/Exchange** | Buys back specific player items at configured prices. | +| **`RECYCLE_COMMAND_ITEM`** | **Command Recycle** | Recycles matching items and executes configured commands. | +| **`RECYCLE_CUSTOM_ITEM`** | **Custom Item Recycle** | Matches and recycles items with custom-item rules. | | **`GROUP_BUY_VOUCHER`** | **Group Voucher/Redeem Code** | Delivers serials or vouchers, supports group redemption. | ## 2. Player Market @@ -50,7 +54,7 @@ Not every combination is valid. See details below. ## 3. Order System -The order system is the logical core of market trading, recording and processing the full flow from "trade initiation" to "item delivery." It supports real-time status tracking and includes refund and cooldown logic to protect both buyer and seller in asynchronous scenarios. +The order system records and processes the flow from trade initiation to item delivery. It provides status tracking, refund policies, and cooldown configuration; outcomes still depend on order state, inventory, permissions, and server availability. ### (1) Order States @@ -90,9 +94,9 @@ After order status becomes **DELIVERED**, refund is usually unavailable. If refu ### (1) Dynamic Pricing -Dynamic pricing is a real-time pricing mechanism based on **supply-demand algorithms**. The system automatically recalculates and updates baseline unit prices from trade frequency, remaining stock, and traded volume within a time window. +Dynamic pricing adjusts prices from a market-pressure value. Purchases increase pressure, recycling decreases it, and a periodic task moves it toward zero by a configured step. The selected algorithm, base price, pressure, and configured bounds determine the quote. -> Main entries: +> Main entries: [Dynamic Pricing](dynamic-pricing) and [Dynamic Pricing Models](algorithm#chapter-2-dynamic-pricing-models). | **Module** | **Type / Mode** | **Supported** | **Driver Logic** | | --- | --- | --- | --- | @@ -105,7 +109,7 @@ Dynamic pricing is a real-time pricing mechanism based on **supply-demand algori ### (2) Auctions -> Main entry: +> Main entries: [Auctions](auctions) and [Auction Models](algorithm#chapter-3-auction-models). Auction is a special trade form based on **bidding logic**. It fits items with uncertain or extremely scarce value. Seller sets starting price and bid increments, then buyers compete within limited time. The order system locks top bidder funds and transfers ownership automatically at settlement.