diff --git a/.dev/dev/admin-api.md b/.dev/dev/admin-api.md deleted file mode 100644 index 7c667d7..0000000 --- a/.dev/dev/admin-api.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -id: webshopx-dev-admin-api -title: 后台 API -sidebar_label: 后台 API -sidebar_position: 6 ---- - -# 后台 API - -## 1. 认证与权限模型 - -后台接口由两层校验： - -1. 必须是有效会话 -2. 必须具备对应 `AdminPermission` - -Super admin 额外专属：管理员账号管理相关接口。 - -## 2. 管理认证接口 - -| Method | Path | Auth | Permission | -| --- | --- | --- | --- | -| POST | `/api/admin/auth/login` | none | - | -| GET | `/api/admin/auth/me` | admin | - | -| POST | `/api/admin/auth/logout` | admin | - | - -## 3. 核心业务分组 - -### 3.1 兑换码 - -- `POST /api/admin/redeem/create` (`REDEEM_MANAGE`) -- `GET /api/admin/redeem/list` (`REDEEM_MANAGE`) - -### 3.2 商品与订单 - -- `GET /api/admin/products/list` (`PRODUCT_MANAGE`) -- `POST /api/admin/products/upsert` (`PRODUCT_MANAGE`) -- `POST /api/admin/products/icon` (`PRODUCT_MANAGE`) -- `POST /api/admin/products/active` (`PRODUCT_MANAGE`) -- `POST /api/admin/products/reset-limit` (`PRODUCT_MANAGE`) -- `POST /api/admin/group-buy/consume` (`PRODUCT_MANAGE`) -- `GET /api/admin/orders/list` (`ORDER_VIEW`) - -### 3.3 经济与系统配置 - -- `GET /api/admin/economy/settings` (`ECONOMY_MANAGE`) -- `POST /api/admin/economy/exchange` -- `POST /api/admin/economy/market` -- `POST /api/admin/economy/leaderboard` -- `POST /api/admin/economy/currency` -- `GET/POST /api/admin/market/tags-config` -- `GET/POST /api/admin/market/limitation-config` -- `POST /api/admin/system/webshop` -- `POST /api/admin/system/market` -- `POST /api/admin/system/maintenance` -- `POST /api/admin/system/logging` -- `POST /api/admin/system/broadcast` -- `POST /api/admin/system/notification` - -### 3.4 视觉与材质覆盖 - -- `GET/POST /api/admin/visual/settings` (`ECONOMY_MANAGE`) -- `GET /api/admin/material-overrides/list` -- `POST /api/admin/material-overrides/upsert` -- `POST /api/admin/material-overrides/delete` -- `POST /api/admin/material-overrides/icon` - -### 3.5 市场监管与用户支持 - -- `GET /api/admin/market/listings` (`MARKET_MANAGE`) -- `POST /api/admin/market/unlist` (`MARKET_MANAGE`) -- `GET /api/admin/users/lookup` (`USER_SUPPORT`) -- `GET /api/admin/users/list` (`USER_SUPPORT`) -- `POST /api/admin/users/reset-password` (`USER_SUPPORT`) -- `POST /api/admin/users/unbind` (`USER_SUPPORT`) -- `POST /api/admin/users/logout` (`USER_SUPPORT`) -- `POST /api/admin/users/wallet-adjust` (`USER_SUPPORT`) -- `GET/POST /api/admin/users/visual-permission` (`USER_SUPPORT`) -- `GET /api/admin/audit/list` (`AUDIT_VIEW`) - -### 3.6 系统公告 - -- `POST /api/admin/notifications/announce` (`ECONOMY_MANAGE`) - -## 4. Super Admin 专属接口 - -- `GET /api/admin/admin-users/meta` -- `GET /api/admin/admin-users/list` -- `POST /api/admin/admin-users/upsert` -- `POST /api/admin/admin-users/active` - -## 5. 后台写接口的统一行为 - -- 输入校验失败返回 `bad_request` -- 权限不满足返回 `forbidden` -- 大部分写操作会写入审计日志 -- runtime_config 类更新会触发配置版本升级与集群刷新 diff --git a/.dev/dev/api-basics.md b/.dev/dev/api-basics.md deleted file mode 100644 index 6a16654..0000000 --- a/.dev/dev/api-basics.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -id: webshopx-dev-api-basics -title: API 基础协议 -sidebar_label: API 基础协议 -sidebar_position: 2 ---- - -# API 基础协议 - -这页定义 WebShopX API 的传输、鉴权和响应约定。 - -:::info[本页导读] -- 监听模式与可用性 -- CORS/预检行为 -- 状态码与错误结构 -- 时间字段注意事项 -::: - -## 1. 服务监听与模式 - -- 内置监听：`webshop.embedded-http.host:port`（默认 `0.0.0.0:8819`） -- `server-mode=internal`：插件托管 API + 静态资源 -- `server-mode=external`：插件只提供 API，静态由外部托管 -- `cluster.role=node`：不启动内置 Web/API - -## 2. CORS 与预检 - -固定返回头： - -- `Access-Control-Allow-Origin: *` -- `Access-Control-Allow-Headers: Content-Type, Authorization` -- `Access-Control-Allow-Methods: GET, POST, OPTIONS` - -`OPTIONS` 预检返回 `204`。 - -## 3. 请求与响应格式 - -- 请求体：UTF-8 JSON 对象 -- 返回体：UTF-8 JSON - -统一错误结构： - -```json -{ - "error": "error_code", - "message": "error message" -} -``` - -## 4. HTTP 状态码约定 - -| 状态码 | 含义 | -| --- | --- | -| `200` | 成功 | -| `204` | 预检成功 | -| `400` | 业务异常（`ServiceException`） | -| `404` | API 或静态资源不存在 | -| `405` | 方法不允许 | -| `500` | 服务端内部错误 | - -## 5. 时间字段与时区 - -当前实现中存在两类时间输出： - -- `LocalDateTime#toString()`（无偏移） -- 业务时区格式（如拍卖时间，受 `webshop.time-zone` 影响） - -建议前端做统一解析容错。 - -## 6. 健康检查 - -- `GET /health` - -返回示例： - -```json -{ - "status": "ok", - "time": "2026-04-29T10:00:00" -} -``` diff --git a/.dev/dev/auth-and-session.md b/.dev/dev/auth-and-session.md deleted file mode 100644 index 43dcdeb..0000000 --- a/.dev/dev/auth-and-session.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -id: webshopx-dev-auth-session -title: 认证与会话 -sidebar_label: 认证与会话 -sidebar_position: 3 ---- - -# 认证与会话 - -## 1. 玩家登录 - -- `POST /api/auth/login` - -请求： - -```json -{ - "identifier": "player_name_or_uuid", - "password": "your_password" -} -``` - -兼容字段：`identifier` 缺失时可用 `username`。 - -返回： - -- `sessionToken` -- `expiresAt` -- `user` -- `username` -- `boundUuid` - -## 2. 玩家会话接口 - -- `GET /api/auth/me` -- `POST /api/auth/logout` - -注意：`/api/auth/logout` 仅读取 `Authorization` 头部 token。 - -## 3. 管理员登录 - -- `POST /api/admin/auth/login` - -返回为玩家会话字段 + `admin` 资料（角色、权限、是否 super admin）。 - -## 4. 鉴权提取顺序 - -源码 `requireAuth(exchange, payload)` 行为： - -1. 优先读 `Authorization: Bearer ` -2. 其次读 body `sessionToken` - -缺失 token：`auth_required` - -无效或过期：`auth_invalid` - -## 5. token 生命周期 - -- 登录时按 `sessionExpireHours` 生成到期时间 -- 过期后需重新登录 -- 重置密码、管理员强制下线会清除该用户全部 session - -## 6. 用户名与密码校验 - -- 用户名正则：`^[A-Za-z0-9_]{3,32}$` -- 密码长度：`8..64` - -常见错误： - -- `invalid_username` -- `invalid_password` -- `invalid_credentials` -- `username_exists` diff --git a/.dev/dev/enums-errors-and-idempotency.md b/.dev/dev/enums-errors-and-idempotency.md deleted file mode 100644 index 63f03ca..0000000 --- a/.dev/dev/enums-errors-and-idempotency.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -id: webshopx-dev-enums-errors-idempotency -title: 枚举、错误码与幂等 -sidebar_label: 枚举、错误码与幂等 -sidebar_position: 7 ---- - -# 枚举、错误码与幂等 - -## 1. 常用枚举 - -### 1.1 币种 - -- `SHOP_COIN` -- `GAME_COIN` - -### 1.2 市场侧 - -- `MarketSide`：`SELL` / `BUY` -- `TradeMode`：`DIRECT` / `AUCTION` -- `SupplyMode`：`MANUAL` / `SUPPLY` -- `AuctionAlgorithm`： - - `ENGLISH_AUCTION_V1` - - `DUTCH_AUCTION_V1` - - `VICKREY_AUCTION_V1` - - `CANDLE_AUCTION_V1` -- `DynamicAlgorithm`： - - `LINEAR_DEMAND_V1` - - `DIMINISHING_RETURN_V1` - - `LOG_SMOOTH_V1` - - `EXPONENTIAL_DEFENSE_V1` - - `THRESHOLD_STEP_V1` - - `ELASTICITY_V1` - - `PANIC_BUYING_V1` - -### 1.3 商品类型 - -- `COMMAND` -- `GIVE_ITEM` -- `POTION_EFFECT` -- `RECYCLE_ITEM` -- `GROUP_BUY_VOUCHER` - -## 2. 典型错误码分组 - -### 2.1 认证类 - -- `auth_required` -- `auth_invalid` -- `invalid_credentials` -- `not_admin` - -### 2.2 参数类 - -- `bad_request` -- `method_not_allowed` -- `invalid_quantity` -- `invalid_delivery_mode` - -### 2.3 钱包/兑换类 - -- `invalid_exchange` -- `exchange_disabled` -- `invalid_ratio` -- `insufficient_funds` -- `vault_unavailable` -- `vault_error` - -### 2.4 市场类 - -- `listing_missing` -- `listing_unavailable` -- `buy_requires_direct_mode` -- `buy_requires_manual_source` -- `buy_requires_fixed_price` -- `buy_order_not_active` -- `auction_only_bid` -- `auction_only_buy` -- `auction_closed` -- `bid_too_low` -- `limitation_item_forbidden` -- `limitation_side_not_allowed` -- `limitation_trade_mode_not_allowed` -- `limitation_currency_not_allowed` - -### 2.5 领取/退款类 - -- `claim_token_invalid` -- `claim_forbidden` -- `refund_not_allowed` -- `refund_disabled` -- `refund_expired` -- `already_refunded` - -## 3. 幂等实践 - -## 3.1 建议带幂等键的接口 - -- `POST /api/wallet/exchange` -- `POST /api/orders` -- `POST /api/market/buy` -- `POST /api/market/sell-to-buy` -- `POST /api/market/bid` - -## 3.2 服务端行为 - -- 未传 `idempotencyKey`：服务端生成随机值 -- 幂等命中：返回既有结果（常见 `state=EXISTING`） -- 键冲突：部分路径会返回 `idempotency_conflict` - -## 3.3 客户端建议 - -1. 用户每次提交生成稳定幂等键。 -2. 超时重试时复用同一键。 -3. 幂等键长度控制在 96 字符以内。 diff --git a/.dev/dev/integration-playbook.md b/.dev/dev/integration-playbook.md deleted file mode 100644 index b04203d..0000000 --- a/.dev/dev/integration-playbook.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -id: webshopx-dev-integration-playbook -title: 接入实施清单 -sidebar_label: 接入实施清单 -sidebar_position: 9 ---- - -# 接入实施清单 - -## 1. 最小可用接入流程 - -1. `POST /api/auth/login` -2. `GET /api/meta/currency` -3. `GET /api/products` -4. `POST /api/orders` -5. `GET /api/orders/list` -6. `GET /api/notifications/unread-count` - -## 2. 市场接入流程 - -1. `GET /api/market/listings` -2. `POST /api/market/buy` 或 `POST /api/market/sell-to-buy` -3. 轮询列表与通知 -4. 需要拍卖则使用 `POST /api/market/bid` - -## 3. 后台接入流程 - -1. `POST /api/admin/auth/login` -2. `GET /api/admin/economy/settings` -3. 分权限接入各子模块接口 -4. 审计日志与公告能力最后接入 - -## 4. 客户端必做健壮性 - -- 为写请求生成稳定 `idempotencyKey` -- 全局处理 `auth_invalid` 并引导重登 -- 将 `400` 的 `error` 作为业务分支主键 -- 统一时间解析（兼容无偏移与带偏移） - -## 5. 版本升级建议 - -1. 每次升级先跑健康检查与关键读接口。 -2. 回归：登录、下单、退款、市场买卖、管理员登录。 -3. 若启用集群，验证 runtime_config 改动能跨节点生效。 diff --git a/.dev/dev/market-api.md b/.dev/dev/market-api.md deleted file mode 100644 index 69106a5..0000000 --- a/.dev/dev/market-api.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -id: webshopx-dev-market-api -title: 市场 API -sidebar_label: 市场 API -sidebar_position: 5 ---- - -# 市场 API - -## 1. 接口总表 - -| Method | Path | Auth | 说明 | -| --- | --- | --- | --- | -| GET | `/api/market/listings` | none/user | 查询挂单列表 | -| POST | `/api/market/listings/create` | user | 创建挂单 | -| POST | `/api/market/buy` | user | 购买 SELL 挂单 | -| POST | `/api/market/sell-to-buy` | user | 向 BUY 挂单履约 | -| POST | `/api/market/bid` | user | 拍卖出价 | -| POST | `/api/market/unlist` | user | 下架 | -| POST | `/api/market/pause` | user | 暂停 | -| POST | `/api/market/resume` | user | 恢复 | -| POST | `/api/market/price` | user | 改价 | -| POST | `/api/market/remark` | user | 改备注 | -| POST | `/api/market/settings` | user | 综合更新（交易模式/动态/拍卖等） | -| POST | `/api/market/icon/upload` | user | 上传挂单图标 | -| POST | `/api/market/supply/refresh` | user | 补货刷新 | - -## 2. 列表查询 `GET /api/market/listings` - -关键查询参数： - -- `mine`（`true` 时必须登录） -- `limit` -- `sort` / `order` -- `currency` -- `minPrice` / `maxPrice` -- `material` -- `keyword` -- `side` -- `tag` -- `tags` 或 `tags[]`（逗号分隔） - -## 3. 创建挂单 `POST /api/market/listings/create` - -请求字段： - -- `side`（默认 `SELL`） -- `currency`（默认 `GAME_COIN`） -- `price` -- `quantity`（兼容 `amount`） -- `tag` -- `tradeMode` - -当前源码限制： - -- `BUY` 仅支持 `DIRECT` -- `SELL` 创建接口当前也仅支持 `DIRECT` -- 需要拍卖时，先创建再通过 `POST /api/market/settings` 切换 - -## 4. 交易接口 - -### 4.1 `POST /api/market/buy` - -请求字段： - -- `listingId` -- `buyQuantity` -- `deliveryMode` -- `idempotencyKey` - -### 4.2 `POST /api/market/sell-to-buy` - -请求字段： - -- `listingId` -- `sellQuantity`（兼容 `fulfillQuantity` / `quantity`） -- `deliveryMode` -- `idempotencyKey` - -## 5. 出价接口 `POST /api/market/bid` - -请求字段： - -- `listingId` -- `bidAmount` -- `idempotencyKey` - -返回字段包含： - -- `sealedBid` -- `minimumRequiredBid` -- `currentHighestBid` -- `auctionEndAt` - -## 6. 综合设置 `POST /api/market/settings` - -可更新： - -- 基础：`price`、`currency`、`tag`、`remark` -- 展示：`displayNameOverride`、`displayMaterial`、`displayIconPath` -- 补货：`supplyBatchSize`、`supplyMaxStock` -- 交易模式：`tradeMode` -- 动态价：`dynamic*` -- 拍卖：`auction*` - -注意事项： - -- 自定义名称/图标受 `visualPermission` 约束 -- BUY 挂单禁止改固定价格约束 -- 切换拍卖参数时如存在挂起 bids，可能触发退款重置 - -## 7. 常见错误 - -- `invalid_listing` -- `listing_unavailable` -- `invalid_quantity` -- `insufficient_quantity` -- `invalid_trade_mode` -- `buy_order_not_active` -- `buy_requires_direct_mode` -- `buy_requires_manual_source` -- `buy_requires_fixed_price` -- `buy_escrow_insufficient` -- `auction_only_bid` / `auction_only_buy` -- `auction_closed` -- `bid_too_low` -- `limitation_*` diff --git a/.dev/dev/overview.md b/.dev/dev/overview.md deleted file mode 100644 index 3339fd5..0000000 --- a/.dev/dev/overview.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -id: webshopx-dev -title: WebShopX 开发文档 -sidebar_label: 开发文档 -sidebar_position: 1 ---- - -# WebShopX 开发文档 - -本文面向对接 WebShopX API 的开发者，内容按当前源码行为整理。 - -:::info[推荐阅读顺序] -1. [API 基础协议](./webshopx-dev-api-basics) -2. [认证与会话](./webshopx-dev-auth-session) -3. [玩家侧 API](./webshopx-dev-player-api) -4. [市场 API](./webshopx-dev-market-api) -5. [后台 API](./webshopx-dev-admin-api) -6. [枚举、错误码与幂等](./webshopx-dev-enums-errors-idempotency) -7. [上传与静态资源](./webshopx-dev-uploads-static) -8. [接入实施清单](./webshopx-dev-integration-playbook) -::: - -## 快速结论 - -| 项 | 结论 | -| --- | --- | -| 数据格式 | 全部 UTF-8 JSON | -| 成功状态码 | 常规 `200`，预检 `204` | -| 业务错误 | `400 + { error, message }` | -| 写接口建议 | 全量携带 `idempotencyKey` | - -## 典型接入顺序 - -1. 登录拿 `sessionToken` -2. 拉基础元信息（币种、商品、规则） -3. 接订单与市场写接口（务必幂等） -4. 补通知、排行榜、后台能力 - -:::tip[实现建议] -把 `error` 作为前端分支主键，不要只靠 `message` 文案匹配。 -::: diff --git a/.dev/dev/player-api.md b/.dev/dev/player-api.md deleted file mode 100644 index 349b65e..0000000 --- a/.dev/dev/player-api.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -id: webshopx-dev-player-api -title: 玩家侧 API -sidebar_label: 玩家侧 API -sidebar_position: 4 ---- - -# 玩家侧 API - -## 1. 接口总表 - -| Method | Path | Auth | 说明 | -| --- | --- | --- | --- | -| GET | `/api/wallet` | user | 钱包余额 + 兑换信息 | -| GET | `/api/wallet/ledger` | user | 钱包流水（`limit`） | -| POST | `/api/wallet/exchange` | user | 币种兑换 | -| POST | `/api/redeem/use` | user | 使用兑换码 | -| GET | `/api/products` | optional | 商品列表 | -| POST | `/api/orders` | user | 下单 | -| GET | `/api/orders/list` | user | 订单列表 | -| POST | `/api/orders/refund` | user | 订单退款 | -| GET | `/api/orders/policy` | none | 订单/市场策略 | -| GET | `/api/notifications/list` | user | 通知列表 | -| GET | `/api/notifications/unread-count` | user | 未读数量 | -| POST | `/api/notifications/mark-read` | user | 标记已读 | -| GET | `/api/meta/currency` | none | 币种显示与兑换配置 | -| GET | `/api/meta/materials` | none | 材质枚举 | -| GET | `/api/meta/material-overrides` | none | 材质覆盖与视觉策略 | -| GET | `/api/meta/market-tags` | none | 市场标签元信息 | -| GET | `/api/leaderboard/config` | none | 排行榜配置 | -| GET | `/api/leaderboard/list` | optional | 排行榜数据 | - -## 2. 钱包与兑换 - -### 2.1 `GET /api/wallet` - -返回：`shopCoin`、`gameCoin`、`exchange`、`visualPermission` 等。 - -### 2.2 `POST /api/wallet/exchange` - -请求字段： - -- `fromCurrency` -- `toCurrency` -- `amount` -- `idempotencyKey`（建议） - -常见错误： - -- `invalid_exchange` -- `invalid_amount` -- `exchange_disabled` -- `invalid_ratio` -- `insufficient_funds` -- `vault_unavailable` - -## 3. 商品与订单 - -### 3.1 `POST /api/orders` - -请求字段： - -- `productId` -- `quantity` -- `deliveryMode`（可选，`IMMEDIATE` / `CLAIM`） -- `idempotencyKey`（建议） - -默认发货模式： - -- `COMMAND`、`POTION_EFFECT` -> `CLAIM` -- `GIVE_ITEM`、`RECYCLE_ITEM`、`GROUP_BUY_VOUCHER` -> `IMMEDIATE` - -### 3.2 `POST /api/orders/refund` - -请求字段： - -- `orderNo` - -支持官方订单（`ODR-*`）与市场订单（`MKT-*`）路径。 - -## 4. 通知 - -### 4.1 `GET /api/notifications/list` - -查询参数： - -- `limit` -- `cursor` -- `unreadOnly` - -### 4.2 `POST /api/notifications/mark-read` - -两种模式： - -- `{"all": true}` -- `{"id": }` - -## 5. 排行榜 - -`GET /api/leaderboard/list` 支持参数： - -- `metric` -- `order` -- `range` -- `limit` -- `showOnline` - -如排行榜被关闭会返回 `feature_disabled`。 diff --git a/.dev/dev/uploads-and-static-assets.md b/.dev/dev/uploads-and-static-assets.md deleted file mode 100644 index 1cbb2a2..0000000 --- a/.dev/dev/uploads-and-static-assets.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -id: webshopx-dev-uploads-static -title: 上传与静态资源 -sidebar_label: 上传与静态资源 -sidebar_position: 8 ---- - -# 上传与静态资源 - -## 1. 上传接口清单 - -- 玩家挂单图标：`POST /api/market/icon/upload?listingId=...` -- 后台商品图标：`POST /api/admin/products/icon?productId=...` -- 后台材质图标：`POST /api/admin/material-overrides/icon?material=...` - -## 2. 上传限制 - -统一限制： - -- 最大体积：`2MB` -- 允许格式：`png`、`webp`、`jpg`、`jpeg`、`gif` - -扩展名判定优先级： - -1. query `filename` -2. header `X-File-Name` -3. header `Content-Type` - -## 3. 请求方式 - -- 请求体直接发送文件字节流 -- 非 multipart 上传 -- 文件为空会返回 `bad_request` - -## 4. 返回路径规则 - -上传后通常返回可直接访问的 `iconPath`，例如： - -- `/uploads/listing-icons/...` -- `/uploads/product-icons/...` -- `/uploads/material-icons/...` - -## 5. 旧图清理 - -当同一对象替换图标时，源码会尝试清理旧的“受管路径”文件，防止资源泄漏。 - -## 6. 静态资源与路由 - -- `server-mode=internal`：插件托管 `/` 静态页面 -- `server-mode=external`：只提供 API；静态资源需外部托管 - -静态路由有目录穿越防护：包含 `..` 的路径会被拒绝。 diff --git a/docs/intro.mdx b/docs/intro.mdx index 2e8c6ad..849d832 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -2,45 +2,36 @@ sidebar_position: 1 --- -# 文档首页 +# Prism-Committee 文档 -欢迎来到 **Prism-Committee 文档站**。 +这里是 Prism-Committee 项目的统一文档站。 -## 文档分区 +## WebShopX -- [WebShopX](./category/webshopx) - 玩家文档、服主文档、开发者文档。 -- [WebShopX Payments](./category/webshopx-payments) - 支付插件安装部署、配置、支付通道与常见问题。 +**WebShopX** 是面向 Paper、Purpur、Spigot 与 Folia 服务端的 Web 商城系统，包含官方商城、玩家市场、钱包、订单与发货、充值和管理后台。 -## 建议阅读路径 +根据你的角色进入对应文档： -### 玩家 -1. [总览](./webshopx/player/overview) -2. [快速上手](./webshopx/player/quick-start) -3. [钱包与兑换](./webshopx/player/wallet-and-exchange) +- **玩家**：从 [玩家指南](./category/player-guide) 开始，了解登录、购买、市场、钱包、背包与领取。 +- **服务器管理员**：从 [服务器管理员](./category/server-admin) 开始，完成安装、部署、配置、升级和运维。 +- **开发者**：从 [开发者文档](./category/webshopx-developer) 开始，查看 HTTP API、认证与支付 Provider 集成。 -### 服主 -1. [总览](./webshopx/admin/overview) -2. [v2 → v3 迁移](./webshopx/admin/v2-to-v3-migration) -3. [安装与部署](./webshopx/admin/install-deploy) -4. [配置](./webshopx/admin/configuration) +## WebShopX-Payments -### 支付插件作者 -1. [WebShopXPaymentApi 接入指南](./webshopx/webshopx-payment-api) -2. [WebShopX Payments 总览](./webshopx-payments/overview) -3. [官方支付通道](./webshopx-payments/official-channels) -4. [Hook 支付通道](./webshopx-payments/hook-channels) +**WebShopX-Payments** 是 WebShopX 的独立支付扩展插件，用于接入官方或第三方支付渠道。 -## 使用建议 +- [WebShopX-Payments 文档](./category/webshopx-payments) +- 第三方插件作者如需实现自己的支付 Provider，请阅读 [WebShopXPaymentApi 接入指南](./webshopx/webshopx-payment-api) -1. 先看总览，再看安装与配置，最后看专题页。 -2. 遇到问题优先查看对应目录下的 FAQ / 排障章节。 -3. 若你在维护多服环境，建议先统一版本再逐步升级。 +## 文档使用原则 -## 反馈与协作 +1. 教程页面回答“怎样完成一件事”。 +2. 配置、命令和 API 页面以当前 WebShopX 实现为准。 +3. 标记为测试或实验性的功能，不应视为所有稳定版本都默认可用。 +4. 遇到问题时先查看对应角色目录下的 FAQ / 排障章节。 -如果你发现文档问题或希望补充内容，欢迎提交 issue： +## 反馈 -- GitHub: [https://github.com/Prism-Committee](https://github.com/Prism-Committee) +WebShopX 问题与文档反馈： +- [Prism-Committee/WebShopX-Issues](https://github.com/Prism-Committee/WebShopX-Issues) diff --git a/docs/webshopx/admin/commands-and-permissions.md b/docs/webshopx/admin/commands-and-permissions.md deleted file mode 100644 index cea48d7..0000000 --- a/docs/webshopx/admin/commands-and-permissions.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -id: commands-permissions -title: 命令与权限体系 -sidebar_label: 命令与权限体系 -sidebar_position: 4 ---- - -# 命令与权限体系 - -## 1. 游戏内主命令 - -主命令：`/webshopx`，别名：`/ws` - -### 1.1 玩家常用 - -```text -/ws help -/ws home -/ws password -/ws market -/ws market gui -/ws market sell [amount] [currency] -/ws market logs [count] -/ws claim [all|ODR-|MKT-|CLM-|MCL-] -/ws mailbox -/ws mailbox collect -``` - -### 1.2 管理常用 - -```text -/ws reload -/ws mode setup relay -/ws mode switch -/ws recharge fix -/ws gamecoin <用户|UUID|ID> <±数量> [原因] -/ws shopcoin <用户|UUID|ID> <±数量> [原因] -/ws market recalc-tags [active|all] -``` - -:::info[v3 命令变化] - -`/ws mailbox claim` 已改为 `/ws mailbox collect`。兑换码在 v3 中由 Web 后台管理，不再把旧版 `/ws redeem create ...` 作为当前游戏命令。 - -::: - -## 2. Bukkit 权限节点 - -- `webshop.use`（默认 `true`） -- `webshop.admin`（默认 `op`） -- `webshop.market.auction`（默认 `op`） -- `webshop.market.limitation.bypass`（默认 `op`） - -## 3. 后台细粒度权限（AdminPermission） - -- `REDEEM_MANAGE` -- `PRODUCT_MANAGE` -- `PRODUCT_ZERO_PRICE` -- `ORDER_VIEW` -- `ECONOMY_MANAGE` -- `MARKET_MANAGE` -- `USER_SUPPORT` -- `AUDIT_VIEW` - -## 4. 内置角色模板（AdminRole） - -- `SUPER_ADMIN`：全部权限 -- `SHOP_ADMIN`：商品/兑换码/订单/经济设置 -- `MARKET_MODERATOR`：市场监管 -- `SUPPORT_ADMIN`：用户支持 + 订单查看 -- `AUDITOR`：审计只读 - -## 5. Super Admin 专属能力 - -只有 super admin 可访问： - -- 管理员权限组元信息 -- 管理员列表 -- 新增/更新管理员权限 -- 启用/禁用管理员账号 - -## 6. 权限分配建议 - -1. 将 `PRODUCT_ZERO_PRICE` 单独控制，只授予少数运营。 -2. `USER_SUPPORT` 与 `ECONOMY_MANAGE` 尽量分离。 -3. `AUDIT_VIEW` 建议给审计角色，不给写权限。 -4. 保持至少 1 个激活的 super admin，避免锁死后台。 diff --git a/docs/webshopx/admin/commands-permissions.md b/docs/webshopx/admin/commands-permissions.md new file mode 100644 index 0000000..06212b5 --- /dev/null +++ b/docs/webshopx/admin/commands-permissions.md @@ -0,0 +1,93 @@ +--- +id: commands-permissions +title: 命令与权限体系 +sidebar_label: 命令与权限体系 +sidebar_position: 4 +--- + +# 命令与权限体系 + +WebShopX 主命令为 `/webshopx`，别名为 `/ws`。 + +## 玩家常用命令 + +```text +/ws help +/ws home +/ws password +/ws market +/ws market gui +/ws market sell [amount] [currency] +/ws market logs [count] +/ws claim [all|ODR-|MKT-|CLM-|MCL-] +/ws mailbox +/ws mailbox collect +``` + +### 说明 + +| 命令 | 用途 | +| --- | --- | +| `/ws home` | 获取服主配置的 WebShopX 网页地址 | +| `/ws password ` | 设置或重置网页登录密码 | +| `/ws market` / `/ws market gui` | 打开市场 GUI | +| `/ws market sell ...` | 快捷出售手中物品 | +| `/ws market logs [count]` | 查看最近市场记录 | +| `/ws claim ...` | 领取待发货内容 | +| `/ws mailbox` | 打开信箱 | +| `/ws mailbox collect` | 一键收取信箱内容 | + +## 管理员常用命令 + +```text +/ws reload +/ws mode setup relay +/ws mode switch +/ws recharge fix +/ws gamecoin <用户|UUID|ID> <±数量> [原因] +/ws shopcoin <用户|UUID|ID> <±数量> [原因] +/ws market recalc-tags [active|all] +``` + +:::info[v3 变化] +- 信箱一键领取使用 `/ws mailbox collect`；旧文档中的 `/ws mailbox claim` 不再作为当前写法。 +- 兑换码主要由 Web 管理后台维护；旧版 `/ws redeem create ...` 不应继续作为 v3 当前命令示例。 +- Relay 推荐使用 `/ws mode setup relay` 完成授权，再使用 `/ws mode switch relay` 切换模式。 +::: + +## Bukkit 权限节点 + +| 权限 | 默认 | 用途 | +| --- | --- | --- | +| `webshop.use` | `true` | 普通玩家功能 | +| `webshop.admin` | `op` | 管理员操作 | +| `webshop.market.auction` | `op` | 在限制规则要求时使用拍卖 | +| `webshop.market.limitation.bypass` | `op` | 绕过市场创建 / 编辑限制 | + +## 后台细粒度权限 + +当前后台权限模型包含： + +- `REDEEM_MANAGE` +- `PRODUCT_MANAGE` +- `PRODUCT_ZERO_PRICE` +- `ORDER_VIEW` +- `ECONOMY_MANAGE` +- `MARKET_MANAGE` +- `USER_SUPPORT` +- `AUDIT_VIEW` + +## 内置角色 + +- `SUPER_ADMIN`：全部权限； +- `SHOP_ADMIN`：商品、兑换码、订单与经济设置； +- `MARKET_MODERATOR`：市场监管； +- `SUPPORT_ADMIN`：用户支持与订单查看； +- `AUDITOR`：审计只读。 + +## 权限分配建议 + +1. `PRODUCT_ZERO_PRICE` 仅授予确实需要的运营人员； +2. 用户支持和经济调整权限尽量分离； +3. 审计角色保持只读； +4. 至少保留一个可用的 `SUPER_ADMIN`，避免后台权限锁死。 diff --git a/docs/webshopx/admin/configuration.md b/docs/webshopx/admin/configuration.md index e852140..5d4e965 100644 --- a/docs/webshopx/admin/configuration.md +++ b/docs/webshopx/admin/configuration.md @@ -7,167 +7,181 @@ sidebar_position: 3 # 配置 -:::info[本页导读] -- 当前最小启动配置怎么改 -- v2 旧配置怎么看 -- 新旧字段迁移对照 -- 服主上线前检查清单 -::: +本页只记录 **当前 WebShopX `config.yml` 中实际存在的运行配置**。市场税率、币种、排行榜等业务规则在 v3 中主要由 Web 管理后台和数据库维护，不应继续复制旧版大配置。 + +## 配置职责 -## 1. 先看结论（服主必读） +当前 `config.yml` 主要负责： -1. 当前版本：`config.yml` 主要保留部署模式、数据库、集群、Redis、内置 Web/API 启动和本地安全开关。 -2. v2 及更早版本：`config.yml` 同时包含大量业务规则参数（兑换、币种、市场税费、排行榜、广播模板等）。 -3. v3 中很多旧字段已迁移到 Web 后台和数据库，不建议继续在 `config.yml` 里维护这些业务项。 +- Web/API 运行模式； +- 首次管理员引导； +- 内置 HTTP 与 CORS； +- 业务账本日志； +- Relay； +- 数据库； +- 集群与 Redis。 -## 2. 当前最小配置（推荐做法） +:::warning +不要把旧版本、开发草案或其他页面中的字段直接复制进生产配置。字段是否有效应以当前版本生成的 `plugins/WebShopX/config.yml` 为准。 +::: -下面是面向服主的“默认风格示例”（已去掉个性化值）： +## 当前默认结构 ```yaml webshop: - # internal=插件内置 Web+API；external=只提供 API；relay=通过 Relay 公网访问 server-mode: internal - # 用户实际访问的前端地址；留空时由请求推断 - public-url: '' + public-url: "" + admin-bootstrap: - # 首次启动自动创建管理员；上线稳定后可改为 false enabled: true - # 首个管理员账号 username: admin - # 首个管理员密码（务必改成强密码） - password: change-me - # 初始角色，通常保持 SUPER_ADMIN + password: admin123456 role: SUPER_ADMIN + embedded-http: - # 内置 HTTP 监听地址；0.0.0.0 表示监听全部网卡 host: 0.0.0.0 - # 内置 Web/API 端口 port: 8819 - # 静态资源目录（相对插件目录） static-root: web - # 对外公开的完整 API 根地址，应包含 /api；同源部署可留空 - public-api-url: '' + public-api-url: "" cors: enabled: false allowed-origins: - - '*' - inventory-read-snapshots: + - "*" + + business-ledger: + enabled: true + directory: logs/business-ledger retention-days: 30 relay: - url: '' - # 推荐用 /ws mode setup relay 授权，不要公开此值 - access-key: '' + url: "" + access-key: "" database: - # mysql | mariadb | sqlite type: sqlite - # 数据库地址（推荐内网地址或本机） host: 127.0.0.1 port: 3306 - # 数据库名 - schema: webshopx - # 数据库账号（建议最小权限） - username: root - # 数据库密码（不要提交到公开仓库） - password: change-me - # 是否启用 TLS + schema: webshop + username: webshop + password: change_me use-ssl: false - # MySQL8/MariaDB 非 TLS 兼容项（按需开启） allow-public-key-retrieval: true - # 可选：服务端 RSA 公钥文件路径或 PEM 文本 - server-rsa-public-key-file: '' + server-rsa-public-key-file: "" sqlite-file: plugins/WebShopX/webshopx.db - # 连接池大小（小服 5-10，大服按并发调优） pool-size: 10 cluster: - # standalone=单服；master/node=多节点 role: standalone - # 当前节点唯一 ID（多节点必须唯一） server-id: standalone - # 节点在线状态 TTL（秒） presence-ttl-seconds: 120 redis: - # 单服可关；跨服广播/多节点建议开 enabled: false host: 127.0.0.1 port: 6379 - # Redis 密码，无密码留空 - password: '' - # 市场广播频道 + password: "" broadcast-channel: webshopx:market:broadcast - # 集群事件频道（配置刷新、节点同步等） cluster-channel: webshopx:cluster:event - # 兼容旧字段（可与 broadcast-channel 保持一致） channel: webshopx:market:broadcast - -safety: - # 本地紧急开关；true 时禁止后台开启离线 playerdata 写入 - force-disable-offline-inventory-write: false ``` -### 2.1 关键字段说明 +## `webshop` -字段说明已集成在上方 YAML 注释中，按注释逐项填写即可。 +### `server-mode` -### 2.2 新版配置原则 +可选值： -1. `config.yml` 只放运行参数和必须保留在本机的安全开关。 -2. 业务规则优先在 Web 后台改（币种、兑换、市场税费、排行榜等）。 -3. 不把数据库真实密码提交到 Git 仓库。 +- `internal`：插件同时提供 API 和内置静态网页； +- `external`：插件提供 API，前端由 Nginx / CDN 等外部服务托管； +- `relay`：插件主动连接 WebShopX Relay，不需要直接向公网开放 Web 端口。 -## 3. v2 及更早版本的旧配置（识别用） +### `public-url` -旧版里常见这类业务字段（新版通常已迁移到后台）： +用户实际访问的 WebShopX 前端地址。留空时可由请求环境推断；生产环境建议显式配置正确的公网 HTTPS 地址。 -- `exchange.*` -- `currency.*` -- `economy.market.trade-fee-percent / trade-tax-percent` -- `webshop.leaderboard.*` -- `webshop.market.*` -- `webshop.broadcast.*` -- `sample-products` +### `admin-bootstrap` + +用于首次初始化管理员。 + +默认账号是 `admin / admin123456`。首次成功登录后应创建正式管理员，并关闭引导账号或更换其凭据。 + +### `embedded-http` + +- `host`：监听地址； +- `port`：默认 `8819`； +- `static-root`：内置静态资源目录； +- `public-api-url`：外部前端访问 API 时使用的完整 API 根地址，应包含 `/api`； +- `cors`：仅在需要跨域访问时开启，并尽量限制允许来源。 + +### `business-ledger` + +控制本地业务账本日志是否启用、日志目录以及保留天数。 + +## `relay` + +仅在 `webshop.server-mode=relay` 时需要关注。 + +- `url` 留空时使用项目默认 Relay 地址； +- `access-key` 是敏感信息，不要提交到公开仓库或工单截图。 -如果你还在维护旧版本，以上字段仍可能有效；升级 v3 后请按新版管理方式迁移。 +推荐优先通过游戏内 Relay 设置流程完成授权，而不是手工传播访问密钥。 -## 4. 新旧字段对照（迁移重点） +## `database` -| v2 旧字段 | v3 建议 | -| --- | --- | -| `exchange.*` | 改到 Web 后台管理 | -| `currency.*` | 改到 Web 后台管理 | -| `economy.market.trade-fee-percent` | 改到 Web 后台管理 | -| `economy.market.trade-tax-percent` | 改到 Web 后台管理 | -| `webshop.leaderboard.*` | 改到 Web 后台管理 | -| `webshop.market.*` | 以后台配置为准（按版本能力） | -| `webshop.broadcast.*` | 优先后台配置；无对应项时再看运行配置 | -| `sample-products` | 不再作为主配置入口，建议后台维护商品 | +### SQLite -## 5. 服主升级步骤（旧 -> 新） +默认： -1. 先备份旧 `config.yml`（建议重命名为 `config.legacy.bak.yml`）。 -2. 用新版最小配置启动（先保证数据库、端口、管理员引导可用）。 -3. 登录后台，把币种/兑换/税费/排行榜等业务项逐项补回。 -4. 完成后删除或注释旧版业务字段，避免“双份配置”产生歧义。 +```yaml +database: + type: sqlite + sqlite-file: plugins/WebShopX/webshopx.db + pool-size: 10 + +cluster: + role: standalone +``` -## 6. 上线前检查清单 +SQLite 适合单服和轻量部署。使用 SQLite 时，集群角色必须保持 `standalone`。 -1. 管理员默认密码是否已修改。 -2. `database` 账号是否仅授予必要权限。 -3. 是否误把生产密码写进公开仓库。 -4. 单服是否误开集群模式。 -5. 需要跨服广播时，Redis 和频道名是否一致。 -6. Relay 访问密钥是否被提交到仓库或截图中。 -7. 未完成离线背包测试时，是否保持离线写入关闭。 +### MySQL / MariaDB + +生产或更高并发场景建议使用 MySQL / MariaDB，并修改数据库地址、库名、用户名和密码。 + +:::danger +当选择 MySQL / MariaDB 时，不要保留示例数据库凭据。数据库密码属于敏感信息，不应提交到 Git 仓库。 +::: +## `cluster` 与 `redis` + +- `standalone`：单服； +- `master` / `node`：多节点部署； +- `server-id`：多节点环境必须保证唯一； +- Redis 用于跨节点事件和市场广播。 + +多服部署前应统一 WebShopX 版本、数据库和 Redis 配置，并完成备份与回滚预案。 + +## v2 → v3 配置变化 + +v2 及更早版本的 `config.yml` 可能包含大量业务字段，例如： + +- `exchange.*` +- `currency.*` +- `economy.market.*` +- `webshop.leaderboard.*` +- `webshop.market.*` +- `webshop.broadcast.*` +- `sample-products` -## SQLite 配置补充（新增） +v3 中这些业务设置不再以旧版大配置作为唯一入口。升级时请优先使用新版生成的最小配置启动，再在 Web 后台恢复业务设置。 -`database.type` 现支持：`mysql | mariadb | sqlite` +详见 [v2 → v3 迁移](./v2-to-v3-migration)。 -当前默认模板中的 SQLite 专用字段为 `sqlite-file`。旧版本或开发构建中出现的调优字段，不应在确认当前版本支持前照搬。 +## 上线前检查 -重要限制：`database.type=sqlite` 时，`cluster.role` 必须是 `standalone`。 +1. 修改或关闭默认管理员引导账号； +2. 确认数据库真实凭据没有进入公开仓库； +3. 单服不要误设为 `master` / `node`； +4. 外置前端时确认 `public-api-url` 与 CORS； +5. Relay 密钥不要出现在截图和公开日志中； +6. 定期备份数据库和 `plugins/WebShopX/` 数据目录。 diff --git a/docs/webshopx/admin/install-and-deploy.md b/docs/webshopx/admin/install-and-deploy.md deleted file mode 100644 index 7029bc3..0000000 --- a/docs/webshopx/admin/install-and-deploy.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -id: install-deploy -title: 安装与部署 -sidebar_label: 安装与部署 -sidebar_position: 2 ---- - -# 安装与部署 - -> 新增SQLite模式，该模式无需额外配置但仅支持单服，可直接跳转至第 9 点 - -## 1. 环境要求 - -- 服务端构建与 Java 必须匹配： - - Minecraft `1.18.2+` 构建：Java `17` - - Minecraft `1.20.6+` 构建：Java `21` - - Minecraft `26.1+ / 26.2+` 构建：Java `25` -- 推荐 Paper；Folia 请使用对应的 Folia 构建。 -- 数据库：默认 SQLite；生产或高并发场景推荐 MariaDB / MySQL -- 可选依赖：Vault（用于 `GAME_COIN` 对接） - -## 2. 获取插件 - -- [modrinth](https://modrinth.com/plugin/webshopx) -- [minebbs](https://www.minebbs.com/resources/webshopx-minecraft.15688/updates) - -## 3. 部署前准备 - -1. 已安装数据库。推荐MariaDB：https://mariadb.org/download/ -2. 已下载 WebShopX 插件 -3. 已准备数据库、数据库账户及密码（示例）： - -```yaml -schema: db_01 -username: user_01 -password: admin123 -``` - -## 4. 数据库初始化（首次部署） - -### (1) 登录数据库 - -以管理员身份登录： - -```text -mysql -u root -p -``` - -### (2) 创建数据库与用户 - -```sql --- 1. 创建数据库 -CREATE DATABASE db_01 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; - --- 2. 创建用户（允许本地访问） -CREATE USER 'user_01'@'localhost' IDENTIFIED BY 'admin123'; - --- 3. 授予该用户对 db_01 的所有权限 -GRANT ALL PRIVILEGES ON db_01.* TO 'user_01'@'localhost'; - --- 4. 刷新权限使配置生效 -FLUSH PRIVILEGES; -``` - -> **注意**：如果你的插件运行在 Docker 容器或另一台服务器上，请将 `'localhost'` 改为 `'%'`。 - -## 5. 首次部署流程 - -1. 将插件 jar 放入服务器 `plugins/` 目录。 -2. 启动服务器一次，生成默认配置。 -3. 编辑 `plugins/WebShopX/config.yml`。默认 SQLite 可直接试运行；使用 MariaDB/MySQL 时必须修改 `database.*`。 -4. 重启服务器。 -5. 玩家在游戏内执行： - -```text -/ws password <新密码> -``` - -6. 打开站点根路径： - -```text -http://:8819/ -``` - -7. 登录后从站点导航进入后台。`/admin.html` 仅作为 v2 兼容重定向，不再是 v3 的主入口。 - -:::danger[默认数据库占位会阻止启动] - -选择 MySQL/MariaDB 且仍使用以下占位值时： - -- `database.host: 127.0.0.1` -- `database.schema: webshop` -- `database.username: webshop` -- `database.password: change_me` - -插件会拒绝正常启动。默认 SQLite 模式不受这组占位值影响。 - -::: - ---- - -### (1) 默认管理员引导账号 - -`webshop.admin-bootstrap` 默认启用，初始账号： - -- 用户名：`admin` -- 密码：`admin123456` - -:::warning[提示] - -生产环境务必立即修改或关闭该配置。 - -::: - -### (2) 运行模式选择 - -#### `internal`（默认） - -- 插件同时提供 API 与静态网页。 -- 适合快速上线和测试。 - -#### `external` - -- 插件只提供 API。 -- 静态文件导出到 `plugins/WebShopX/web/`。 -- 可配合 Nginx/CDN 反代。 - -建议在 `external` 下设置： - -- `webshop.public-url` -- `webshop.embedded-http.public-api-url` -- `webshop.embedded-http.cors` -- 反向代理 HTTPS -- 合理的缓存与访问控制 - -#### `relay` - -- 通过 WebShopX Relay 提供公网访问，不需要直接开放 `8819`。 -- 推荐由游戏内管理员执行 `/ws mode setup relay` 完成设备授权。 -- 授权完成后执行 `/ws mode switch relay`，再用 `/ws home` 验证。 - -完整步骤见 [Relay 公网访问](./relay-access.md)。 - -## 6. 生产环境安全清单 - -- 修改数据库账号密码，限制数据库访问来源。 -- 关闭或重置 `admin-bootstrap` 默认管理员。 -- 不公开 Relay 授权链接和 `relay.access-key`。 -- 通过 Nginx / CDN 提供 HTTPS。 -- 仅开放必要端口（默认 8819）。 -- 定期备份数据库与 `plugins/WebShopX` 数据目录。 -- 监控日志目录（`webshop.logging.directory`）。 - -## 7. 反向代理建议（external 模式） - -- 将前端静态资源目录指向导出的 `web` 目录。 -- 将 `/api/` 转发到插件服务地址。 -- 透传 `X-Forwarded-For`，便于审计记录来源 IP。 - -## 8.升级建议 - -1. 升级前备份数据库。 -2. 停服。 -3. 移除`web`文件夹。(可选，用于强制更新前端页面) -4. 替换 jar。 -5. 启动服务器。 -6. 验证以下关键功能： - - 登录与会话 - - 下单与退款 - - 市场购买/竞拍 - - 管理后台登录与权限 - -## 9. SQLite 单服部署（新增） - -WebShopX 已支持 `database.type=sqlite`，适合单服/轻量场景。 - -### 必须满足 - -1. `database.type=sqlite` -2. `cluster.role=standalone` - -当 `cluster.role=master` 或 `cluster.role=node` 时，插件会拒绝启动（设计如此）。 - -该方式无需额外配置。 - -### 推荐配置 - -```yaml -database: - type: sqlite - sqlite-file: plugins/WebShopX/webshopx.db - pool-size: 10 - -cluster: - role: standalone -``` - -### 运维建议 - -- SQLite 适用于单节点，不适合跨节点集群。 -- 高并发写入场景优先选择 MySQL/MariaDB。 -- 备份时请同时备份 SQLite 文件与 `plugins/WebShopX` 数据目录。 diff --git a/docs/webshopx/admin/install-deploy.md b/docs/webshopx/admin/install-deploy.md new file mode 100644 index 0000000..c3f1ed8 --- /dev/null +++ b/docs/webshopx/admin/install-deploy.md @@ -0,0 +1,145 @@ +--- +id: install-deploy +title: 安装与部署 +sidebar_label: 安装与部署 +sidebar_position: 2 +--- + +# 安装与部署 + +本页用于完成 WebShopX 的首次安装，并选择合适的 Web 部署模式。 + +## 1. 环境要求 + +| Minecraft 运行时 | Java | Folia 构建 | +| --- | ---: | --- | +| `1.18.2+` | 17 | 不提供 | +| `1.20.6+` | 21 | 提供 | +| `26.1+` | 25 | 提供 | +| `26.2+` | 25 | 提供 | + +- 推荐 Paper / Purpur；Spigot 也受支持； +- Folia 必须使用对应 Folia 构建； +- 默认数据库为 SQLite； +- 生产或高并发场景推荐 MySQL / MariaDB； +- Vault、WebShopX-Payments 与 YuPay 都是可选软依赖。 + +## 2. 获取插件 + +请选择与你的 Minecraft 版本和服务端类型匹配的 JAR： + +- [Modrinth](https://modrinth.com/plugin/webshopx) +- [MineBBS](https://www.minebbs.com/resources/webshopx-minecraft.15688/updates) + +## 3. 最快部署：SQLite + internal + +适合单服体验和首次安装。 + +1. 将 JAR 放入 `plugins/`； +2. 启动服务器一次，生成配置； +3. 保持默认 `database.type=sqlite`； +4. 确认 `cluster.role=standalone`； +5. 再次启动服务器； +6. 玩家执行 `/ws password <新密码>`； +7. 执行 `/ws home` 获取网页地址。 + +默认 internal 模式监听： + +```text +http://<服务器地址>:8819/ +``` + +:::warning +首次管理员引导账号默认为 `admin / admin123456`。首次成功登录后台后，请立即创建正式管理员并关闭或修改 `webshop.admin-bootstrap`。 +::: + +## 4. 使用 MySQL / MariaDB + +创建独立数据库和最小权限账户后，在 `config.yml` 中填写： + +```yaml +database: + type: mariadb + host: 127.0.0.1 + port: 3306 + schema: webshop + username: webshop + password: change_me +``` + +生产环境不要使用示例密码，也不要把真实凭据提交到公开仓库。 + +## 5. 选择部署模式 + +### `internal` + +插件同时提供 API 与静态网页，最适合快速部署。 + +```yaml +webshop: + server-mode: internal + public-url: "https://shop.example.com" + embedded-http: + host: 0.0.0.0 + port: 8819 +``` + +公网部署时建议通过 Nginx / CDN 提供 HTTPS，而不是直接暴露未加密的管理入口。 + +### `external` + +插件只提供 API，前端静态文件交给 Nginx / CDN 等外部服务。 + +重点配置： + +- `webshop.public-url` +- `webshop.embedded-http.public-api-url` +- `webshop.embedded-http.cors` + +`public-api-url` 应填写完整 API 根地址，并包含 `/api`。 + +### `relay` + +Relay 模式下，Minecraft 服务器不需要直接向公网开放 Web 端口。插件主动连接 WebShopX Relay。 + +推荐使用游戏内命令完成授权： + +```text +/ws mode setup relay +/ws mode switch relay +/ws home +``` + +完整说明见 [Relay 公网访问](./relay-access.md)。 + +## 6. 管理后台入口 + +v3 中应从 WebShopX 站点登录后进入管理后台。`/admin.html` 仅用于兼容旧链接，不应再作为部署文档中的主要后台入口。 + +## 7. 生产环境安全 + +上线前至少完成： + +- 修改或关闭默认管理员引导账号； +- 使用独立数据库账户和强密码； +- 通过 HTTPS 对外提供站点； +- 仅开放必要端口； +- 不公开 Relay access key、数据库密码和支付密钥； +- 定期备份数据库与 `plugins/WebShopX/` 数据目录； +- 关注业务账本与服务日志。 + +## 8. 升级 + +1. 备份数据库与 `plugins/WebShopX/`； +2. 停服； +3. 替换 JAR； +4. 启动服务器，让新版完成必要迁移； +5. 验证登录、下单、市场、领取、后台和支付链路； +6. 如从 v2 升级，继续阅读 [v2 → v3 迁移](./v2-to-v3-migration)。 + +## 9. 相关文档 + +- [配置](./configuration) +- [命令与权限体系](./commands-permissions) +- [v2 → v3 迁移](./v2-to-v3-migration) +- [运维排障](./faq) diff --git a/docs/webshopx/admin/overview.md b/docs/webshopx/admin/overview.md index eeab717..2c87532 100644 --- a/docs/webshopx/admin/overview.md +++ b/docs/webshopx/admin/overview.md @@ -1,46 +1,53 @@ ---- +--- id: overview title: 总览 sidebar_label: 总览 sidebar_position: 1 --- -# WebShopX 服主文档 - -## 问题反馈 +# WebShopX 服务器管理员指南 -- Issues 仓库：https://github.com/Prism-Committee/WebShopX-Issues +本目录面向插件安装者、服务器运维与 WebShopX 后台管理员。 -本目录面向插件安装者、运维与后台管理员。 +## 推荐阅读路径 -:::info[阅读地图] 1. [安装与部署](./install-deploy) -2. [v2 → v3 迁移](./v2-to-v3-migration) -3. [配置与运行时参数](./configuration) -4. [命令与权限体系](./commands-permissions) -5. [市场治理与风控](./governance) -6. [发货、领取与退款运维](./delivery-refund-ops) -7. [运维排障手册](./faq) -::: +2. [配置与运行时参数](./configuration) +3. [命令与权限体系](./commands-permissions) +4. [Relay 公网访问](./relay-access) +5. [市场治理与风控](./market-governance) +6. [背包与离线库存运维](./inventory-operations) +7. [发货、领取与退款运维](./delivery-and-refund-ops) +8. [v2 → v3 迁移](./v2-to-v3-migration) +9. [常见问题](./faq) -## WebShopX 拓扑 +## 部署组件 | 组件 | 说明 | | --- | --- | -| 插件进程 | 内置 API 服务，可选托管静态页 | -| SQLite 或 MySQL/MariaDB | 单服可用 SQLite；生产和集群推荐 MySQL/MariaDB | -| Vault（可选） | `GAME_COIN` 经济挂接 | -| Redis（可选） | 集群配置刷新与市场广播 | -| Relay（可选） | 不直接开放 Web 端口时的公网访问入口 | - -## 你最需要先关心的风险点 - -:::warning[高危配置提醒] -1. 使用 MySQL/MariaDB 时不要保留默认数据库占位值；默认 SQLite 不受该检查影响。 -2. 生产环境建议首启后立刻替换 `admin-bootstrap` 初始密码。 -3. SQLite 只能用于 standalone；集群不要启用实验性的离线背包写入。 -4. Relay 访问密钥、数据库密码和支付凭证都不能出现在公开仓库或工单截图中。 +| WebShopX 插件 | 核心业务、HTTP API，可选托管静态网页 | +| SQLite | 默认单服数据库，必须搭配 `cluster.role=standalone` | +| MySQL / MariaDB | 生产或多服部署推荐 | +| Vault（可选） | 将 `GAME_COIN` 对接游戏经济 | +| Redis（可选） | 多节点配置刷新、市场广播等集群能力 | +| WebShopX Relay（可选） | 不直接向公网暴露 Minecraft 服务器 Web 端口 | +| WebShopX-Payments（可选） | 在线支付渠道扩展 | + +## 上线前优先检查 + +:::warning[高风险项] +1. 首次登录后立即更换/关闭 `admin-bootstrap` 默认管理员； +2. 数据库、Relay 和支付凭据不要进入公开仓库或工单截图； +3. SQLite 只用于 standalone，不用于多节点集群； +4. 公网部署优先使用 HTTPS 和反向代理，不直接暴露不必要端口； +5. 离线 playerdata 写入属于实验性高风险能力，默认保持关闭； +6. 升级前同时备份数据库与 `plugins/WebShopX/` 数据目录。 ::: +## 配置职责 + +v3 中 `config.yml` 主要保存本机部署参数、安全开关和数据库/集群设置。市场税率、币种、排行榜等业务规则优先由 Web 管理后台维护，不要在多个位置重复配置。 +## 问题反馈 +发现文档和实际版本不一致时，请在 Prism-Committee 的 Issue 渠道反馈，并附上 WebShopX 版本、服务端版本和相关日志片段（注意脱敏）。 diff --git a/docs/webshopx/developer/admin-api.md b/docs/webshopx/developer/admin-api.md new file mode 100644 index 0000000..a498e74 --- /dev/null +++ b/docs/webshopx/developer/admin-api.md @@ -0,0 +1,100 @@ +--- +id: admin-api +title: 后台 API +sidebar_label: 后台 API +sidebar_position: 5 +--- + +# 后台 API + +## 认证与权限模型 + +后台接口通常同时要求： + +1. 有效管理员会话； +2. 对应的 `AdminPermission`。 + +Super Admin 还拥有管理员账号与权限组管理等专属能力。 + +## 管理认证 + +| Method | Path | Auth | +| --- | --- | --- | +| POST | `/api/admin/auth/login` | none | +| GET | `/api/admin/auth/me` | admin | +| POST | `/api/admin/auth/logout` | admin | + +## 核心业务分组 + +### 兑换码 + +- `POST /api/admin/redeem/create` +- `GET /api/admin/redeem/list` + +### 商品与订单 + +- `GET /api/admin/products/list` +- `POST /api/admin/products/upsert` +- `POST /api/admin/products/icon` +- `POST /api/admin/products/active` +- `POST /api/admin/products/reset-limit` +- `POST /api/admin/group-buy/consume` +- `GET /api/admin/orders/list` + +### 经济与系统设置 + +常见接口包括： + +- `GET /api/admin/economy/settings` +- `POST /api/admin/economy/exchange` +- `POST /api/admin/economy/market` +- `POST /api/admin/economy/leaderboard` +- `POST /api/admin/economy/currency` +- `GET/POST /api/admin/market/tags-config` +- `GET/POST /api/admin/market/limitation-config` +- `POST /api/admin/system/webshop` +- `POST /api/admin/system/market` +- `POST /api/admin/system/maintenance` +- `POST /api/admin/system/logging` +- `POST /api/admin/system/broadcast` +- `POST /api/admin/system/notification` + +### 视觉与材质覆盖 + +- `GET/POST /api/admin/visual/settings` +- `GET /api/admin/material-overrides/list` +- `POST /api/admin/material-overrides/upsert` +- `POST /api/admin/material-overrides/delete` +- `POST /api/admin/material-overrides/icon` + +### 市场监管与用户支持 + +- `GET /api/admin/market/listings` +- `POST /api/admin/market/unlist` +- `GET /api/admin/users/lookup` +- `GET /api/admin/users/list` +- `POST /api/admin/users/reset-password` +- `POST /api/admin/users/unbind` +- `POST /api/admin/users/logout` +- `POST /api/admin/users/wallet-adjust` +- `GET/POST /api/admin/users/visual-permission` +- `GET /api/admin/audit/list` + +### 系统公告 + +- `POST /api/admin/notifications/announce` + +## Super Admin 专属接口 + +- `GET /api/admin/admin-users/meta` +- `GET /api/admin/admin-users/list` +- `POST /api/admin/admin-users/upsert` +- `POST /api/admin/admin-users/active` + +## 写接口约定 + +后台写操作通常会经过参数校验和权限检查，重要操作还会记录审计信息。客户端应处理 `bad_request`、`forbidden`、`auth_invalid` 等错误，并在修改运行时设置后考虑集群同步所需时间。 + +:::warning +不要把后台 API 暴露给不受信任的浏览器应用或第三方站点。管理员 token 应视为高敏感凭据。 +::: diff --git a/docs/webshopx/developer/api-basics.md b/docs/webshopx/developer/api-basics.md new file mode 100644 index 0000000..dd016c0 --- /dev/null +++ b/docs/webshopx/developer/api-basics.md @@ -0,0 +1,74 @@ +--- +id: api-basics +title: HTTP API 基础 +sidebar_label: HTTP API 基础 +sidebar_position: 1 +--- + +# HTTP API 基础 + +本页作为 WebShopX HTTP API 的公开入口。具体接口字段和行为应以你正在使用的 WebShopX 版本为准。 + +## 服务模式 + +WebShopX 的 API 监听由 `webshop.embedded-http.host` 和 `webshop.embedded-http.port` 控制，默认端口为 `8819`。 + +- `server-mode=internal`：插件提供 API 和内置静态网页； +- `server-mode=external`：插件提供 API，前端由外部托管； +- `server-mode=relay`：通过 WebShopX Relay 提供公网访问。 + +外置前端通常还需要正确设置： + +- `webshop.embedded-http.public-api-url` +- `webshop.embedded-http.cors` + +## 请求与响应 + +API 主要使用 UTF-8 JSON 请求与响应。错误响应通常包含可用于前端处理的错误码和消息，例如： + +```json +{ + "error": "error_code", + "message": "error message" +} +``` + +客户端不应只依赖自然语言 `message` 判断业务状态，应优先处理稳定的错误码。 + +## 鉴权 + +需要登录态的接口使用 WebShopX 会话 token。常见方式为： + +```http +Authorization: Bearer +``` + +详细流程见 [认证与会话](./authentication)。 + +## CORS + +跨域前端需要管理员显式配置 CORS。不要假设所有 WebShopX 实例都允许任意 Origin。 + +同源 `internal` 部署通常不需要额外开启跨域；`external` 部署则应只允许实际使用的前端来源。 + +## API 地址 + +同源部署时，网页通常通过 `/api` 访问后端。外置部署时，实际 API 根地址由服务器管理员的 `public-api-url` 与反向代理配置决定。 + +## 健康检查 + +WebShopX 提供健康检查入口： + +```text +GET /health +``` + +可用于反向代理或基础存活检测。 + +## 开发建议 + +1. 在集成前先确认目标服务器的 WebShopX 版本； +2. 为请求失败保留错误码和 HTTP 状态码； +3. 对创建订单、支付、市场交易等写操作设计幂等与重试策略； +4. 不要在客户端代码中保存管理员凭据、数据库密码或支付密钥； +5. 升级 WebShopX 后对关键 API 流程做一次回归测试。 diff --git a/docs/webshopx/developer/authentication.md b/docs/webshopx/developer/authentication.md new file mode 100644 index 0000000..82a5b77 --- /dev/null +++ b/docs/webshopx/developer/authentication.md @@ -0,0 +1,82 @@ +--- +id: authentication +title: 认证与会话 +sidebar_label: 认证与会话 +sidebar_position: 2 +--- + +# 认证与会话 + +本页介绍 WebShopX HTTP API 的基础登录与会话模型。接口字段可能随版本调整，集成时请以目标服务器版本为准。 + +## 玩家登录 + +```text +POST /api/auth/login +``` + +典型请求： + +```json +{ + "identifier": "player_name_or_uuid", + "password": "your_password" +} +``` + +成功后会返回会话 token 以及当前用户信息。玩家密码通常通过游戏内命令设置： + +```text +/ws password +``` + +## 当前用户与退出 + +常见会话接口： + +```text +GET /api/auth/me +POST /api/auth/logout +``` + +需要鉴权的请求通常携带： + +```http +Authorization: Bearer +``` + +## 管理员登录 + +管理员使用独立登录入口： + +```text +POST /api/admin/auth/login +``` + +管理员会话除基本用户信息外，还会关联后台角色和权限。 + +## 会话失效 + +客户端应处理以下情况： + +- token 已过期； +- 玩家重置密码； +- 管理员强制结束会话； +- 服务端升级或安全操作导致现有会话失效。 + +常见错误码： + +- `auth_required`：缺少有效登录态； +- `auth_invalid`：token 无效或已过期； +- `invalid_credentials`：账号或密码不正确； +- `invalid_password`：密码不符合当前规则。 + +收到 `auth_invalid` 后，前端应清理本地登录态并引导用户重新登录。 + +## 安全建议 + +1. 生产站点使用 HTTPS； +2. 不在 URL 查询参数中传播 session token； +3. 不把管理员 token 写入日志或公开截图； +4. 前端退出登录时同时清理本地会话状态； +5. 第三方集成不要复用管理员账号作为长期机器凭据，除非对应版本明确提供这种集成方式。 diff --git a/docs/webshopx/developer/errors-and-idempotency.md b/docs/webshopx/developer/errors-and-idempotency.md new file mode 100644 index 0000000..416b28a --- /dev/null +++ b/docs/webshopx/developer/errors-and-idempotency.md @@ -0,0 +1,106 @@ +--- +id: errors-and-idempotency +title: 错误码、枚举与幂等 +sidebar_label: 错误码与幂等 +sidebar_position: 6 +--- + +# 错误码、枚举与幂等 + +## 常用枚举 + +### 币种 + +- `SHOP_COIN` +- `GAME_COIN` + +### 市场 + +- `MarketSide`：`SELL` / `BUY` +- `TradeMode`：`DIRECT` / `AUCTION` +- `SupplyMode`：`MANUAL` / `SUPPLY` + +拍卖与动态定价算法会随版本演进，客户端应优先使用服务端返回的能力和枚举，而不是把完整列表永久写死在前端。 + +### 商品类型 + +常见类型包括： + +- `COMMAND` +- `GIVE_ITEM` +- `POTION_EFFECT` +- `RECYCLE_ITEM` +- `GROUP_BUY_VOUCHER` + +## 典型错误码 + +### 认证与权限 + +- `auth_required` +- `auth_invalid` +- `invalid_credentials` +- `not_admin` +- `forbidden` + +### 参数 + +- `bad_request` +- `method_not_allowed` +- `invalid_quantity` +- `invalid_delivery_mode` + +### 钱包与兑换 + +- `invalid_exchange` +- `exchange_disabled` +- `invalid_ratio` +- `insufficient_funds` +- `vault_unavailable` +- `vault_error` + +### 市场 + +常见前缀和错误包括： + +- `listing_missing` +- `listing_unavailable` +- `buy_requires_*` +- `buy_order_not_active` +- `auction_only_bid` +- `auction_only_buy` +- `auction_closed` +- `bid_too_low` +- `limitation_*` + +### 领取与退款 + +- `claim_token_invalid` +- `claim_forbidden` +- `refund_not_allowed` +- `refund_disabled` +- `refund_expired` +- `already_refunded` + +:::tip +业务客户端应以 `error` 字段作为程序分支主键，`message` 仅用于展示和辅助排障。 +::: + +## 幂等 + +建议对可能造成资产或状态变化的写请求使用稳定 `idempotencyKey`，尤其是： + +- `POST /api/wallet/exchange` +- `POST /api/orders` +- `POST /api/market/buy` +- `POST /api/market/sell-to-buy` +- `POST /api/market/bid` + +### 客户端建议 + +1. 每次用户动作生成一个稳定幂等键； +2. 网络超时后重试同一动作时复用同一键； +3. 不要为每次重试重新生成键； +4. 对服务端返回的既有结果按成功重放处理； +5. 遇到 `idempotency_conflict` 时停止盲目重试并重新获取业务状态。 + +幂等键的长度和具体服务端回放行为可能随版本调整，应以当前版本实现为准。 diff --git a/docs/webshopx/developer/integration-playbook.md b/docs/webshopx/developer/integration-playbook.md new file mode 100644 index 0000000..0a784ae --- /dev/null +++ b/docs/webshopx/developer/integration-playbook.md @@ -0,0 +1,68 @@ +--- +id: integration-playbook +title: 接入实施清单 +sidebar_label: 接入实施清单 +sidebar_position: 8 +--- + +# 接入实施清单 + +## 最小玩家端接入 + +建议先打通： + +1. `POST /api/auth/login` +2. `GET /api/meta/currency` +3. `GET /api/products` +4. `POST /api/orders` +5. `GET /api/orders/list` +6. `GET /api/notifications/unread-count` + +完成后再增加钱包流水、退款、排行榜等非核心功能。 + +## 市场接入 + +1. `GET /api/market/listings` +2. `POST /api/market/buy` 或 `POST /api/market/sell-to-buy` +3. 刷新挂单状态和通知 +4. 需要拍卖时接入 `POST /api/market/bid` +5. 最后接入创建、改价、补货和综合设置等卖家能力 + +所有涉及资产变化的写请求都应设计幂等重试。 + +## 后台接入 + +1. `POST /api/admin/auth/login` +2. 获取当前管理员身份和权限 +3. 按权限逐步接入商品、订单、经济、市场和用户支持模块 +4. 最后接入审计、管理员管理和高风险系统设置 + +不要只根据前端菜单隐藏按钮；服务端权限错误仍必须被正确处理。 + +## 客户端健壮性 + +- 为关键写请求生成稳定 `idempotencyKey`； +- 全局处理 `auth_invalid` 并引导重新登录； +- 使用 `error` 字段做业务分支； +- 对时间字段做兼容解析； +- 网络失败后先确认业务状态，再决定是否重试； +- 将 API 根地址作为部署配置，不硬编码服务器地址； +- 日志中避免输出完整 token 和敏感配置。 + +## 升级回归清单 + +WebShopX 升级后至少验证： + +- `/health` +- 玩家登录 / 退出 +- 商品列表和下单 +- 订单查询与领取/退款路径 +- 市场列表、购买、履约、竞拍 +- 管理员登录与权限 +- 关键后台写操作 +- External/Relay 部署下的 API 地址和静态资源 +- 集群环境下的运行时配置传播 + +## Payment Provider + +开发第三方支付插件时，不应通过后台 HTTP API 模拟支付成功，而应使用 WebShopX 提供的 Payment Provider API。参见 [WebShopXPaymentApi 接入指南](../webshopx-payment-api)。 diff --git a/docs/webshopx/developer/market-api.md b/docs/webshopx/developer/market-api.md new file mode 100644 index 0000000..63c22cb --- /dev/null +++ b/docs/webshopx/developer/market-api.md @@ -0,0 +1,95 @@ +--- +id: market-api +title: 市场 API +sidebar_label: 市场 API +sidebar_position: 4 +--- + +# 市场 API + +## 接口总表 + +| Method | Path | Auth | 说明 | +| --- | --- | --- | --- | +| GET | `/api/market/listings` | none/user | 查询挂单 | +| POST | `/api/market/listings/create` | user | 创建挂单 | +| POST | `/api/market/buy` | user | 购买 SELL 挂单 | +| POST | `/api/market/sell-to-buy` | user | 向 BUY 挂单履约 | +| POST | `/api/market/bid` | user | 拍卖出价 | +| POST | `/api/market/unlist` | user | 下架 | +| POST | `/api/market/pause` | user | 暂停 | +| POST | `/api/market/resume` | user | 恢复 | +| POST | `/api/market/price` | user | 改价 | +| POST | `/api/market/remark` | user | 修改备注 | +| POST | `/api/market/settings` | user | 综合更新市场设置 | +| POST | `/api/market/icon/upload` | user | 上传挂单图标 | +| POST | `/api/market/supply/refresh` | user | 刷新供货 | + +## 查询挂单 + +`GET /api/market/listings` 常见查询参数： + +- `mine` +- `limit` +- `sort` / `order` +- `currency` +- `minPrice` / `maxPrice` +- `material` +- `keyword` +- `side` +- `tag` +- `tags` / `tags[]` + +当 `mine=true` 时需要有效用户会话。 + +## 创建挂单 + +`POST /api/market/listings/create` 常见字段包括： + +- `side` +- `currency` +- `price` +- `quantity`（部分版本兼容 `amount`） +- `tag` +- `tradeMode` + +市场能力受服务器侧限制规则、物品状态、权限和当前版本实现共同约束。创建或修改失败时，应根据返回错误码而不是仅根据文案处理。 + +## 交易 + +### `POST /api/market/buy` + +常见字段：`listingId`、`buyQuantity`、`deliveryMode`、`idempotencyKey`。 + +### `POST /api/market/sell-to-buy` + +常见字段：`listingId`、`sellQuantity`、`deliveryMode`、`idempotencyKey`。 + +### `POST /api/market/bid` + +常见字段：`listingId`、`bidAmount`、`idempotencyKey`。拍卖响应可能包含最低要求出价、当前最高价和结束时间等信息。 + +## 综合设置 + +`POST /api/market/settings` 用于更新一个挂单的多项设置，可能涉及价格、币种、标签、备注、展示、补货、交易模式、动态价格和拍卖参数。 + +:::warning +变更拍卖或交易模式时可能影响已有出价、托管资产或挂单状态。第三方客户端不要把该接口视为普通的无副作用配置写入。 +::: + +## 常见错误 + +包括但不限于： + +- `invalid_listing` +- `listing_unavailable` +- `invalid_quantity` +- `insufficient_quantity` +- `invalid_trade_mode` +- `buy_order_not_active` +- `buy_requires_direct_mode` +- `auction_closed` +- `bid_too_low` +- `limitation_*` + +完整错误处理建议见 [错误码、枚举与幂等](./errors-and-idempotency)。 diff --git a/docs/webshopx/developer/overview.md b/docs/webshopx/developer/overview.md new file mode 100644 index 0000000..42bc1de --- /dev/null +++ b/docs/webshopx/developer/overview.md @@ -0,0 +1,38 @@ +--- +id: overview +title: 开发者总览 +sidebar_label: 总览 +sidebar_position: 1 +--- + +# WebShopX 开发者文档 + +本目录面向需要调用 WebShopX HTTP API 或开发第三方支付 Provider 的开发者。 + +:::info[推荐阅读顺序] +1. [HTTP API 基础](./api-basics) +2. [认证与会话](./authentication) +3. [玩家侧 API](./player-api) +4. [市场 API](./market-api) +5. [后台 API](./admin-api) +6. [错误码、枚举与幂等](./errors-and-idempotency) +7. [上传与静态资源](./uploads-and-static-assets) +8. [接入实施清单](./integration-playbook) +9. [Payment Provider API](../webshopx-payment-api) +::: + +## 接口边界 + +WebShopX HTTP API 面向网页前端、管理后台和受信任的集成客户端。第三方支付插件则通过独立的 Java Payment Provider API 与 WebShopX 协作。 + +## 接入原则 + +- 先确认目标服务器所运行的 WebShopX 版本； +- 优先依据稳定错误码处理业务分支，不依赖自然语言提示； +- 对下单、兑换、市场交易等写请求实现幂等和安全重试； +- 不在浏览器端或公开仓库中保存管理员凭据、数据库密码、Relay 密钥或支付密钥； +- 升级 WebShopX 后重新验证登录、订单、市场和后台关键流程。 + +:::warning[版本说明] +API 会随开发版本演进。本文档描述当前 v3 文档基线；字段、路径或能力存在疑问时，以对应版本 WebShopX 源码和实际响应为准。 +::: diff --git a/docs/webshopx/developer/player-api.md b/docs/webshopx/developer/player-api.md new file mode 100644 index 0000000..71ba058 --- /dev/null +++ b/docs/webshopx/developer/player-api.md @@ -0,0 +1,83 @@ +--- +id: player-api +title: 玩家侧 API +sidebar_label: 玩家侧 API +sidebar_position: 3 +--- + +# 玩家侧 API + +## 接口总表 + +| Method | Path | Auth | 说明 | +| --- | --- | --- | --- | +| GET | `/api/wallet` | user | 钱包余额与兑换信息 | +| GET | `/api/wallet/ledger` | user | 钱包流水 | +| POST | `/api/wallet/exchange` | user | 币种兑换 | +| POST | `/api/redeem/use` | user | 使用兑换码 | +| GET | `/api/products` | optional | 商品列表 | +| POST | `/api/orders` | user | 下单 | +| GET | `/api/orders/list` | user | 订单列表 | +| POST | `/api/orders/refund` | user | 订单退款 | +| GET | `/api/orders/policy` | none | 订单/市场策略 | +| GET | `/api/notifications/list` | user | 通知列表 | +| GET | `/api/notifications/unread-count` | user | 未读数量 | +| POST | `/api/notifications/mark-read` | user | 标记已读 | +| GET | `/api/meta/currency` | none | 币种显示与兑换配置 | +| GET | `/api/meta/materials` | none | 材质枚举 | +| GET | `/api/meta/material-overrides` | none | 材质覆盖与视觉策略 | +| GET | `/api/meta/market-tags` | none | 市场标签元信息 | +| GET | `/api/leaderboard/config` | none | 排行榜配置 | +| GET | `/api/leaderboard/list` | optional | 排行榜数据 | + +## 钱包与兑换 + +### `GET /api/wallet` + +返回当前用户钱包及与兑换相关的信息。客户端应把具体字段视为版本化响应，不要假定所有版本字段完全一致。 + +### `POST /api/wallet/exchange` + +常见请求字段： + +- `fromCurrency` +- `toCurrency` +- `amount` +- `idempotencyKey`（建议） + +常见错误包括 `invalid_exchange`、`invalid_amount`、`exchange_disabled`、`invalid_ratio`、`insufficient_funds`、`vault_unavailable`。 + +## 商品与订单 + +### `POST /api/orders` + +常见请求字段： + +- `productId` +- `quantity` +- `deliveryMode`（可选） +- `idempotencyKey`（建议） + +`deliveryMode` 的可用值和默认行为以当前服务端策略为准。客户端应允许订单进入待领取或其他非即时完成状态。 + +### `POST /api/orders/refund` + +常见请求字段： + +- `orderNo` + +退款是否允许由当前订单状态和服务器策略共同决定。 + +## 通知 + +`GET /api/notifications/list` 常见查询参数： + +- `limit` +- `cursor` +- `unreadOnly` + +`POST /api/notifications/mark-read` 支持按单条或全部标记已读，具体请求结构以对应版本为准。 + +## 排行榜 + +`GET /api/leaderboard/list` 常见参数包括 `metric`、`order`、`range`、`limit`、`showOnline`。排行榜未启用时，客户端应正确处理 `feature_disabled`。 diff --git a/docs/webshopx/developer/uploads-and-static-assets.md b/docs/webshopx/developer/uploads-and-static-assets.md new file mode 100644 index 0000000..f84ce95 --- /dev/null +++ b/docs/webshopx/developer/uploads-and-static-assets.md @@ -0,0 +1,52 @@ +--- +id: uploads-and-static-assets +title: 上传与静态资源 +sidebar_label: 上传与静态资源 +sidebar_position: 7 +--- + +# 上传与静态资源 + +## 上传接口 + +常见上传入口： + +- 玩家挂单图标：`POST /api/market/icon/upload?listingId=...` +- 后台商品图标：`POST /api/admin/products/icon?productId=...` +- 后台材质图标：`POST /api/admin/material-overrides/icon?material=...` + +## 请求方式 + +这些上传接口使用原始文件字节流，而不是 multipart 表单。文件名或扩展名可能从 query、`X-File-Name` 或 `Content-Type` 推断。 + +当前文档基线下常见限制： + +- 最大体积：约 `2 MB` +- 常见格式：`png`、`webp`、`jpg`、`jpeg`、`gif` + +具体限制以目标 WebShopX 版本实际响应为准。 + +## 返回与访问 + +上传成功后通常返回可用于网页显示的资源路径，例如： + +- `/uploads/listing-icons/...` +- `/uploads/product-icons/...` +- `/uploads/material-icons/...` + +替换同一对象的受管图标时，服务端会尽量清理旧资源；客户端不应依赖旧路径永久有效。 + +## Internal / External 模式 + +- `internal`：插件同时托管 API 和内置静态页面； +- `external`：插件主要提供 API，前端与静态资源访问由外部 Web 服务、反向代理或 CDN 配置决定。 + +外置部署时，请同时确认上传后的资源路径能够被浏览器访问，而不是只验证上传请求返回成功。 + +## 安全建议 + +1. 不允许用户通过文件名控制服务器任意路径； +2. 不绕过服务端格式和大小校验； +3. 外部反向代理应限制请求体大小并配置合理超时； +4. 不把上传目录当作可执行脚本目录； +5. 对用户自定义图标保留审核和删除能力。 diff --git a/docs/webshopx/overview.md b/docs/webshopx/overview.md new file mode 100644 index 0000000..63faec7 --- /dev/null +++ b/docs/webshopx/overview.md @@ -0,0 +1,38 @@ +--- +id: webshopx-overview +title: WebShopX 开始使用 +sidebar_label: 开始使用 +sidebar_position: 0 +--- + +# WebShopX + +WebShopX 是面向 Paper、Purpur、Spigot 与 Folia 服务端的 Web 商城系统，整合官方商城、玩家市场、钱包、订单与发货、充值以及管理后台。 + +## 选择你的阅读路径 + +| 你是谁 | 建议入口 | +| --- | --- | +| 普通玩家 | [玩家指南](./player/overview) | +| 服主 / 运维 / 管理员 | [服务器管理员](./admin/overview) | +| HTTP API / 插件开发者 | [开发者文档](./developer/overview) | +| 只想查参数、命令或错误码 | [Reference](./reference/overview) | + +## 当前文档基线 + +本文档以 WebShopX v3 开发线为主要基线。不同发行版本可能存在功能、字段或界面差异；涉及部署、配置和 API 时，请同时确认你实际安装的 WebShopX 版本。 + +## WebShopX 与 WebShopX-Payments + +WebShopX 核心负责商城、资产、订单和业务状态。WebShopX-Payments 是独立的可选支付扩展，用于连接具体支付渠道。 + +- 只使用游戏内经济或不需要在线支付：不必安装 WebShopX-Payments； +- 需要充值渠道：阅读 [WebShopX-Payments 文档](../webshopx-payments/overview)； +- 开发自己的支付 Provider：阅读 [Payment Provider API](./webshopx-payment-api)。 + +## 文档维护原则 + +- 配置字段以 WebShopX 当前 `config.yml` 为事实源； +- 命令与权限以当前插件实现和 `plugin.yml` 为事实源； +- API 以目标版本源码与实际响应为事实源； +- 教程只解释如何完成任务，不重复维护整套参数表。 diff --git a/docs/webshopx/player/inventory.md b/docs/webshopx/player/inventory.md index febcb6a..f89d5d2 100644 --- a/docs/webshopx/player/inventory.md +++ b/docs/webshopx/player/inventory.md @@ -6,48 +6,51 @@ sidebar_position: 4 --- # 网页背包与快捷交易 -> 这是内测功能，正式版可能暂未接入此功能，请以实际为准。你也可以加入QQ群进行后续新功能内测。 -网页的“背包”页面可以查看真实背包和末影箱，并直接从物品槽位直接发起交易。 -## 1. 现状 +:::caution[功能状态：测试 / 实验性] +网页背包能力会随服务器版本和管理员设置而变化。在线背包操作与离线背包能力并不等价；是否开放离线写入由服务器管理员决定。 +::: -玩家在线时可以安全进行背包管理，玩家离线时背包管理为实验性功能，可能暂未稳定，默认关闭，可由管理员开启。 +网页的“背包”页面用于查看当前玩家的背包或末影箱，并在服务器允许时直接从物品槽位发起市场操作。 -`我的背包` 页面会显示当前登录玩家的背包，以及物品名称、数量、附魔、Lore、装备位置等。支持直接从背包上架到玩家市场（包含求购和售卖）、拍卖行等。 +## 可以做什么 -## 2. 可用操作 +根据服务器启用的功能，你可能可以： -- **满足收购**：选择与物品完整匹配的官方或玩家收购挂单，确认预计收入、手续费和实际到账。 -- **固定价上架**：设置数量、单价、币种和展示信息。 -- **发起拍卖**：设置起拍价、持续时间等拍卖参数。 +- 查看物品名称、数量、附魔、Lore 和装备位置； +- 将物品按固定价上架到玩家市场； +- 使用物品满足匹配的收购单； +- 发起拍卖。 -提交前服务器会再次校验真实槽位和物品内容。若物品已移动、数量改变或不再满足限制，请刷新页面后重试。 +提交交易前，服务器会再次核对真实槽位和物品内容。如果物品已经移动、数量改变或不再满足交易限制，请刷新页面后重试。 -## 3. 在线与离线状态 +## 在线与离线的区别 -| 状态 | 含义 | 可否交易 | +| 页面状态 | 你看到的内容 | 是否可直接交易 | | --- | --- | --- | -| 玩家在线 | 读取服务器中的实时背包或末影箱 | 可以 | -| 离线只读快照 | 显示玩家最后在线时保存的内容 | 不可以 | -| 服务器持久化背包 | 服主已显式开启实验性的离线即时管理 | 可以，但有一定风险 | -| 尚无快照 | 玩家从未在支持快照的版本中上线 | 不可以 | - -离线只读快照仅用于查看，不能视为可写库存。快照保留时间由服主设置，玩家重新上线后会刷新。 - -:::warning[离线即时管理/持久化背包] +| 在线实时背包 | 当前服务器中的实时库存 | 通常可以 | +| 离线只读内容 | 玩家离线前保存的可查看内容 | 不可以 | +| 离线可管理库存 | 服务器管理员显式开放的实验性能力 | 取决于服务器配置 | +| 暂无可用数据 | 尚未取得可展示的库存信息 | 不可以 | -介绍：该功能默认关闭。该功能目前仅支持单服模式，若服务器需跨服同步背包、多服部署等，请谨慎开启。 - -风险来源：该功能会直接修改服务器保存的玩家数据，当服务器修改玩家数据文件时，如果服务端也同步修改（如在同时或几乎同时玩家上线，或服务器关闭可能会造成数据损坏），尽管它发生的可能性极小但依旧无法避免。WebShopX已经尽可能把风险控制在最小范围：WebShopX不会直接写入、只会在临时备份写入并在替换时进行数据锁。 +:::warning +离线状态下看到的内容不一定代表当前磁盘中的最终玩家数据，也不能默认视为可写库存。请以页面显示的状态和按钮是否可用为准。 ::: -## 4. 常见问题 +## 常见问题 ### 页面显示的物品和游戏内不一致 -先确认页面顶部显示的是实时库存还是离线快照，再点击“刷新”。离线只读快照不会跟随离线期间的外部数据变更实时更新。 +先确认页面显示的是“在线实时”还是“离线只读”，然后刷新页面。离线数据不会在玩家离线期间持续同步所有外部变化。 ### 按钮不可用 -常见原因包括：玩家离线且只有只读快照、物品被服务器规则禁止交易、没有匹配的收购单、没有自定义展示权限，或服务器已关闭对应能力。 +常见原因包括： + +- 当前只有离线只读数据； +- 物品被服务器规则禁止交易； +- 没有匹配的收购单； +- 当前账号没有对应权限； +- 服务器管理员没有开放该能力。 +涉及离线 playerdata 写入、数据锁、回滚和风险控制的内容属于服务器管理员 / 运维范围，不在玩家指南中展开。 diff --git a/docs/webshopx/player/overview.md b/docs/webshopx/player/overview.md index 7e37cca..f018690 100644 --- a/docs/webshopx/player/overview.md +++ b/docs/webshopx/player/overview.md @@ -5,53 +5,50 @@ sidebar_label: 总览 sidebar_position: 1 --- -# 总览 +# WebShopX 玩家指南 -## 问题反馈 +这里面向普通玩家，只解释你在游戏内和网页商城中需要完成的操作。 -- Issues 仓库：https://github.com/Prism-Committee/WebShopX-Issues +## 从这里开始 -:::tip[导读] -适合玩家阅读：功能说明、使用教程、常见问题与术语解释。 -::: - -## 先看哪里 +| 你要做什么 | 阅读 | +| --- | --- | +| 第一次登录网页商城 | [快速上手](./quick-start) | +| 买东西、查订单、退款 | [官方商店、玩家市场与订单](./shop-and-orders) | +| 查看余额、兑换或充值 | [钱包与兑换](./wallet-and-exchange) | +| 查看网页背包或从背包发起交易 | [网页背包与快捷交易](./inventory) | +| 领取待发货物品或查看信箱 | [领取与信箱](./claim-and-mailbox) | +| 参与拍卖 | [拍卖](./auctions) | +| 理解动态价格 | [动态价格](./dynamic-pricing) | +| 上架被拒或交易失败 | [上架限制](./limits) 和 [常见问题](./faq) | +| 看不懂术语 | [名词解释](./glossary) | +| 想理解算法机制 | [算法](./algorithm) | -| 目标 | 先看 | 收获 | -| --- | --- | --- | -| 第一次使用 | [快速上手](./quick-start) | 登录、密码、基础操作 | -| 网页管理真实背包（内测中） | [网页背包与快捷交易](./inventory) | 背包/末影箱、快捷上架与离线状态 | -| 余额/充值兑换 | [钱包与兑换](./wallet-and-exchange) | 双币体系、兑换与常见报错 | -| 买东西、下单、查订单 | [官方商店、玩家市场与订单](./shop-and-orders) | 购买流程、订单状态、发货与退款 | -| 领取失败订单或补发物品 | [领取与信箱](./claim-and-mailbox) | `claim` 与信箱领取的正确姿势 | -| 理解拍卖机制 | [拍卖](./auctions) | 四种拍卖模式与实战差异 | -| 理解价格变化 | [动态价格](./dynamic-pricing) | 为什么会涨跌、不同算法的体感区别 | -| 上架被拒/交易失败排查 | [上架限制](./limits) + [常见问题](./faq) | 错误码含义与排查顺序 | -| 想看机制原理 | [算法](./algorithm) | 动态定价与拍卖机制的底层思路 | -| 看不懂术语 | [名词解释](./glossary) | 常用词快速对照 | - -## 常用命令速查 +## 最常用命令 ```text -/ws #打开商店GUI菜单 -/ws help #查看命令描述 -/ws home #获取网页商店网址 -/ws password #设置/重置密码 -/ws market #同/ws -/ws market gui #同/ws -/ws market sell [amount] [currency] #使用命令快捷上架 -/ws market logs [count] #查看最近日志 -/ws claim [all|ODR-|MKT-|CLM-|MCL-] #领取待发货物品 -/ws mailbox #打开信箱GUI菜单 -/ws mailbox collect #一键领取信箱物品 +/ws +/ws home +/ws password <新密码> +/ws market sell [amount] [currency] +/ws market logs [count] +/ws claim [all|ODR-|MKT-|CLM-|MCL-] +/ws mailbox +/ws mailbox collect ``` -## 入门时遇到的常见问题 +完整命令和权限说明由管理员 Reference 统一维护，不在玩家教程中复制整套参数。 -:::warning -1. 先在游戏里设置网页密码：`/ws password <新密码>`。 -2. 钱包是双币系统：`SHOP_COIN` 和 `GAME_COIN`。 -3. 自动发货失败会转为 `WAIT_CLAIM`，要手动 `claim`。 -4. 背包放不下会进入信箱，可用 `/ws mailbox` 查看或 `/ws mailbox collect` 收取。 -::: +## 功能状态说明 +文档中可能看到以下状态： + +- **稳定**：正常面向用户使用； +- **测试中**：功能已可使用，但界面或行为仍可能调整； +- **实验性**：默认可能关闭，存在明确限制或风险。 + +网页离线背包写入属于实验性能力；是否可用由服务器管理员决定。玩家只需要根据页面显示的“实时 / 只读 / 可操作”状态进行操作。 + +:::tip +遇到交易或领取问题时，不要连续重复提交。先刷新订单/挂单状态，再按错误提示或 [常见问题](./faq) 排查。 +::: diff --git a/docs/webshopx/player/quick-start.md b/docs/webshopx/player/quick-start.md index fc22e71..41a58b8 100644 --- a/docs/webshopx/player/quick-start.md +++ b/docs/webshopx/player/quick-start.md @@ -1,4 +1,4 @@ ---- +--- id: quick-start title: 快速上手 sidebar_label: 快速上手 @@ -7,40 +7,50 @@ sidebar_position: 2 # 快速上手 -本页内容：进行账号准备并成功进入 WebShopX。 - -:::info[本页导读] -- 第 1 部分：首登前 3 步 -- 第 2 部分：常见错误与处理 -::: +本页只解决一件事：**从游戏内完成账号准备，并成功登录 WebShopX 网页。** -## 1. 首次登录 +## 1. 设置网页密码 -1. 在游戏内执行： +在游戏内执行： ```text /ws password <你的新密码> ``` -2. 执行 `/ws home` 打开服主配置的 Web 页面。 -3. 用游戏内提示的用户名和刚设置的密码登录。 +密码应使用 8 到 64 个字符。设置或重置密码后，旧会话可能失效，需要重新登录。 + +## 2. 获取网页地址 + +执行： + +```text +/ws home +``` + +服务器会返回服主配置的 WebShopX 地址。若没有可用地址，请联系服务器管理员。 + +## 3. 登录 + +打开网页后，使用你的 Minecraft 玩家名（或服务器允许的玩家标识）和刚刚设置的密码登录。 + +:::tip +正常玩家不需要自行“注册一个新的 WebShopX 用户名”。账号身份来自服务器中的玩家资料，`/ws password` 用于设置或重置网页登录密码。 +::: + +## 常见问题 + +### `invalid_password` + +密码格式或长度不符合要求。请重新设置 8 到 64 位密码。 +### `invalid_credentials` -## 2. 常见错误与处理 +登录凭证不正确。确认玩家名和密码后重试；必要时在游戏内重新执行 `/ws password`。 -| 错误码 | 含义 | 处理建议 | -| --- | --- | --- | -| `invalid_username` | 用户名格式不合法 | 检查长度和字符（字母/数字/下划线） | -| `invalid_password` | 密码长度不合法 | 改为 8 到 64 位 | -| `username_exists` | 用户名冲突 | 更换用户名并重试 | -| `invalid_credentials` | 登录凭证错误 | 核对账号、密码、大小写 | -| `auth_invalid` | 会话失效或过期 | 重新登录获取新 token | +### `auth_invalid` -
- 排障顺序（建议） +当前会话已经失效或过期。退出网页账号后重新登录。 -1. 先确认你是否在游戏里执行过 `/ws password`。 -2. 再确认密码长度是否满足 8 到 64。 -3. 若网页提示会话失效，先完整退出再重新登录。 +### `/ws home` 没有给出可用网址 -
+这通常是服务器端的 WebShopX 公网地址或部署模式尚未配置完成，请联系服务器管理员。 diff --git a/docs/webshopx/reference/overview.md b/docs/webshopx/reference/overview.md new file mode 100644 index 0000000..a320834 --- /dev/null +++ b/docs/webshopx/reference/overview.md @@ -0,0 +1,35 @@ +--- +id: overview +title: Reference +sidebar_label: Reference +sidebar_position: 1 +--- + +# WebShopX Reference + +这里集中提供“去哪里查准确参数”的索引，不再复制维护第二套配置、命令或错误码。 + +| 需要查询 | 权威页面 | +| --- | --- | +| `config.yml` 字段 | [配置与运行时参数](../admin/configuration) | +| 游戏命令与 Bukkit 权限 | [命令与权限体系](../admin/commands-permissions) | +| 玩家常用术语 | [名词解释](../player/glossary) | +| HTTP API 协议 | [HTTP API 基础](../developer/api-basics) | +| HTTP API 认证 | [认证与会话](../developer/authentication) | +| 玩家 API | [玩家侧 API](../developer/player-api) | +| 市场 API | [市场 API](../developer/market-api) | +| 后台 API | [后台 API](../developer/admin-api) | +| API 错误码与幂等 | [错误码、枚举与幂等](../developer/errors-and-idempotency) | +| 上传资源 | [上传与静态资源](../developer/uploads-and-static-assets) | +| v2 → v3 差异 | [v2 → v3 迁移](../admin/v2-to-v3-migration) | + +## 事实源优先级 + +遇到文档与实际版本不一致时，按下面顺序判断： + +1. 你正在运行的 WebShopX 版本代码 / 配置模板； +2. 本 Reference 指向的对应文档； +3. 玩家/管理员教程； +4. README、旧截图或第三方教程。 + +发现不一致时欢迎在 Prism-Committee 的 Issue 渠道反馈，并注明 WebShopX 版本和相关页面。 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx b/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx index 0f4c483..2814f2f 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx @@ -2,44 +2,36 @@ sidebar_position: 1 --- -# Documentation Home +# Prism-Committee Docs -Welcome to **Prism-Committee Docs**. +This is the unified documentation site for Prism-Committee projects. -## Documentation Sections +## WebShopX -- [WebShopX](./category/webshopx) - Player docs, admin docs, and developer docs. -- [WebShopX Payments](./category/webshopx-payments) - Installation/deployment, configuration, payment channels, and FAQ for the payments plugin. +WebShopX is a web-first shop system for Paper, Purpur, Spigot, and Folia servers. It combines the official shop, player market, wallets, orders and delivery, recharge, and administration. -## Suggested Reading Paths +Choose a path: -### Players -1. [Overview](./webshopx/player/overview) -2. [Quick Start](./webshopx/player/quick-start) -3. [Wallet & Exchange](./webshopx/player/wallet-and-exchange) +- **Start here**: [WebShopX Overview](./webshopx/overview) +- **Players**: [Player Guide](./category/player-guide) +- **Server administrators**: [Server Administrator](./category/server-admin) +- **Developers**: [Developer Docs](./category/webshopx-developer) +- **Reference**: [WebShopX Reference](./category/webshopx-reference) -### Server Admins -1. [Overview](./webshopx/admin/overview) -2. [Install & Deploy](./webshopx/admin/install-deploy) -3. [Configuration](./webshopx/admin/configuration) +## WebShopX-Payments -### Payment Plugin Developers -1. [WebShopXPaymentApi Integration Guide](./webshopx/webshopx-payment-api) -2. [WebShopX Payments Overview](./webshopx-payments/overview) -3. [Official Payment Channels](./webshopx-payments/official-channels) -4. [Hook Payment Channels](./webshopx-payments/hook-channels) +WebShopX-Payments is the optional standalone payment extension for WebShopX. -## Usage Tips +- [WebShopX-Payments documentation](./category/webshopx-payments) +- Third-party payment plugin developers: [WebShopXPaymentApi Integration Guide](./webshopx/webshopx-payment-api) -1. Start with overview pages, then installation/configuration, then topic-specific details. -2. Check each section's FAQ/troubleshooting pages first when debugging issues. -3. For multi-server environments, align versions first, then upgrade incrementally. +## Documentation Rules -## Feedback - -If you find documentation issues or want to suggest additions, please open an issue: +1. Tutorials explain how to complete a task. +2. Configuration, commands, and API reference should follow the current WebShopX implementation. +3. Beta or experimental features should not be assumed to exist or be enabled on every stable server. +4. When behavior differs, verify the exact WebShopX version first. -- GitHub: [https://github.com/Prism-Committee](https://github.com/Prism-Committee) +## Feedback +- [Prism-Committee/WebShopX-Issues](https://github.com/Prism-Committee/WebShopX-Issues) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/commands-and-permissions.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/commands-and-permissions.md deleted file mode 100644 index dc8b623..0000000 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/commands-and-permissions.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -id: commands-permissions -title: Commands and Permission System -sidebar_label: Commands and Permission System -sidebar_position: 4 ---- - -# Commands and Permission System - -## 1. Main In-Game Commands - -Main command: `/webshopx`, alias: `/ws` - -### 1.1 Common Player Commands - -```text -/ws help -/ws password -/ws market -/ws market gui -/ws market sell [amount] [currency] -/ws market logs [count] -/ws claim [all|ODR-|MKT-|CLM-|MCL-] -/ws mailbox claim -``` - -### 1.2 Common Admin Commands - -```text -/ws reload -/ws redeem create [maxUses] [perUserMaxUses] [minutes] [code] -/ws market recalc-tags [active|all] -``` - -## 2. Bukkit Permission Nodes - -- `webshop.use` (default `true`) -- `webshop.admin` (default `op`) -- `webshop.market.auction` (default `op`) -- `webshop.market.limitation.bypass` (default `op`) - -## 3. Fine-Grained Admin Permissions (`AdminPermission`) - -- `REDEEM_MANAGE` -- `PRODUCT_MANAGE` -- `PRODUCT_ZERO_PRICE` -- `ORDER_VIEW` -- `ECONOMY_MANAGE` -- `MARKET_MANAGE` -- `USER_SUPPORT` -- `AUDIT_VIEW` - -## 4. Built-In Role Templates (`AdminRole`) - -- `SUPER_ADMIN`: full permissions -- `SHOP_ADMIN`: products/redeem codes/orders/economy settings -- `MARKET_MODERATOR`: market governance -- `SUPPORT_ADMIN`: user support + order view -- `AUDITOR`: read-only auditing - -## 5. Super Admin Exclusive Capabilities - -Only super admin can access: - -- Admin permission-group metadata -- Admin list -- Create/update admin permissions -- Enable/disable admin accounts - -## 6. Permission Assignment Recommendations - -1. Isolate `PRODUCT_ZERO_PRICE` and grant it to very few operators. -2. Separate `USER_SUPPORT` from `ECONOMY_MANAGE` when possible. -3. Grant `AUDIT_VIEW` to audit roles without write permissions. -4. Keep at least 1 active super admin to avoid locking out the admin panel. - diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/commands-permissions.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/commands-permissions.md new file mode 100644 index 0000000..9dd0caa --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/commands-permissions.md @@ -0,0 +1,70 @@ +--- +id: commands-permissions +title: Commands and Permissions +sidebar_label: Commands and Permissions +sidebar_position: 4 +--- + +# Commands and Permissions + +Main command: `/webshopx`, alias: `/ws`. + +## Common Player Commands + +```text +/ws help +/ws home +/ws password +/ws market +/ws market gui +/ws market sell [amount] [currency] +/ws market logs [count] +/ws claim [all|ODR-|MKT-|CLM-|MCL-] +/ws mailbox +/ws mailbox collect +``` + +## Common Administrator Commands + +```text +/ws reload +/ws mode setup relay +/ws mode switch +/ws recharge fix +/ws gamecoin <±amount> [reason] +/ws shopcoin <±amount> [reason] +/ws market recalc-tags [active|all] +``` + +:::info[v3 changes] +`/ws mailbox claim` has been replaced by `/ws mailbox collect`. Redeem-code management is handled in the Web admin panel in v3 instead of treating the old `/ws redeem create ...` command as the current primary workflow. +::: + +## Bukkit Permission Nodes + +- `webshop.use` — default: everyone +- `webshop.admin` — default: OP +- `webshop.market.auction` — default: OP +- `webshop.market.limitation.bypass` — default: OP + +## Admin Permissions + +Common fine-grained permissions include: + +- `REDEEM_MANAGE` +- `PRODUCT_MANAGE` +- `PRODUCT_ZERO_PRICE` +- `ORDER_VIEW` +- `ECONOMY_MANAGE` +- `MARKET_MANAGE` +- `USER_SUPPORT` +- `AUDIT_VIEW` + +Built-in role templates include `SUPER_ADMIN`, `SHOP_ADMIN`, `MARKET_MODERATOR`, `SUPPORT_ADMIN`, and `AUDITOR`. + +## Assignment Guidance + +1. Keep `PRODUCT_ZERO_PRICE` tightly restricted. +2. Separate user-support and economy-management duties when possible. +3. Give auditors read access without write permissions. +4. Keep at least one active super administrator to avoid locking out the admin panel. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/configuration.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/configuration.md index 8bb26fe..ab250cc 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/configuration.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/configuration.md @@ -7,159 +7,99 @@ sidebar_position: 3 # Configuration -:::info[In This Page] -- How to configure 1.1.5+ -- How to read legacy config in 1.1.5 and below -- Field migration mapping -- Pre-production checklist for server owners -::: - -## 1. Key Takeaways First (Must Read) +## Key Principle -1. `1.1.5+`: `config.yml` mainly keeps runtime environment parameters (database, cluster, Redis, built-in Web/API startup). -2. `1.1.5 and below`: `config.yml` also contains many business-rule parameters (exchange, currencies, market tax, leaderboard, broadcast templates, etc.). -3. After upgrading to `1.1.5+`, many old fields moved to visual management in the Web admin panel. It is not recommended to keep maintaining these business items in `config.yml`. +In the current v3 line, `config.yml` is intentionally small. It mainly contains deployment mode, local HTTP settings, database, cluster, Redis, Relay, and local safety/runtime options. Business rules should normally be managed through the Web admin panel and stored in the database. -## 2. New Configuration for 1.1.5+ (Recommended) - -Below is a default-style example for server owners (personalized values removed): +## Current Configuration Shape ```yaml webshop: - # internal=built-in Web+API; external=API backend only (frontend via external reverse proxy/CDN) server-mode: internal - # In external mode, set full public URL; can be empty in internal mode - api-base-url: '' + public-url: "" admin-bootstrap: - # Auto-create admin at first startup; set false after production is stable enabled: true - # First admin username username: admin - # First admin password (must be changed to a strong password) - password: change-me - # Initial role, usually keep SUPER_ADMIN + password: admin123456 role: SUPER_ADMIN embedded-http: - # Built-in HTTP listen address; 0.0.0.0 means all interfaces host: 0.0.0.0 - # Built-in Web/API port port: 8819 - # Static resource directory (relative to plugin directory) static-root: web + public-api-url: "" + cors: + enabled: false + allowed-origins: + - "*" + business-ledger: + enabled: true + directory: logs/business-ledger + retention-days: 30 -economy: - inflation-control: - # burn=remove from economy; treasury=move into treasury account (depends on plugin implementation) - mode: burn - # Treasury user ID (effective when mode=treasury) - treasury-user-id: 0 +relay: + url: "" + access-key: "" database: - # Database host (LAN address or localhost recommended) + type: sqlite host: 127.0.0.1 port: 3306 - # Database schema - schema: webshopx - # DB user (least privilege recommended) - username: root - # DB password (do not commit to public repositories) - password: change-me - # Enable TLS or not + schema: webshop + username: webshop + password: change_me use-ssl: false - # Non-TLS compatibility option for MySQL8/MariaDB (enable if needed) allow-public-key-retrieval: true - # Optional: server RSA public key file path or PEM text - server-rsa-public-key-file: '' - # Connection pool size (small server 5-10, tune for concurrency on large servers) + server-rsa-public-key-file: "" + sqlite-file: plugins/WebShopX/webshopx.db pool-size: 10 cluster: - # standalone=single server; master/node=multi-node role: standalone - # Unique current node ID (must be unique in multi-node setup) server-id: standalone - # Node presence TTL in seconds presence-ttl-seconds: 120 redis: - # Can be off in single-server setup; recommended on for cross-server broadcast/multi-node enabled: false host: 127.0.0.1 port: 6379 - # Redis password; empty if no password - password: '' - # Market broadcast channel + password: "" broadcast-channel: webshopx:market:broadcast - # Cluster event channel (config refresh, node sync, etc.) cluster-channel: webshopx:cluster:event - # Legacy compatible field (can match broadcast-channel) channel: webshopx:market:broadcast ``` -### 2.1 Key Field Notes +## Deployment Notes -Field explanations are already included as YAML comments above. Fill values field by field following those comments. +- `server-mode=internal`: built-in API + web UI. +- `server-mode=external`: API only; static frontend is hosted externally. +- `server-mode=relay`: public access through WebShopX Relay. +- `database.type=sqlite` requires `cluster.role=standalone`. +- MySQL/MariaDB is recommended for production or multi-server deployments. +- Keep CORS disabled unless an external frontend actually needs cross-origin API access. -### 2.2 New Configuration Principles +## What No Longer Belongs in `config.yml` -1. Keep only runtime parameters in `config.yml`. -2. Prefer editing business rules in Web admin (currencies, exchange, market tax, leaderboard, etc.). -3. Never commit real database passwords to Git repositories. - -## 3. Legacy Config in 1.1.5 and Below (For Identification) - -In older versions, these business fields are common (and usually moved to admin panel in newer versions): +Older releases may contain business settings such as: - `exchange.*` - `currency.*` -- `economy.market.trade-fee-percent / trade-tax-percent` -- `webshop.leaderboard.*` -- `webshop.market.*` -- `webshop.broadcast.*` -- `sample-products` - -If you still maintain old versions, these fields may still work. For `1.1.5+`, migrate using the new management model. - -## 4. Old vs New Field Mapping (Migration Focus) +- market fees/taxes +- leaderboard settings +- market rules +- broadcast templates +- sample products -| Old field (1.1.5 and below) | Recommendation in 1.1.5+ | -| --- | --- | -| `exchange.*` | Move to Web admin management | -| `currency.*` | Move to Web admin management | -| `economy.market.trade-fee-percent` | Move to Web admin management | -| `economy.market.trade-tax-percent` | Move to Web admin management | -| `webshop.leaderboard.*` | Move to Web admin management | -| `webshop.market.*` | Prefer admin-panel config (based on version capability) | -| `webshop.broadcast.*` | Prefer admin-panel config first; fall back to runtime config if needed | -| `sample-products` | No longer a primary config entry; maintain products in admin panel | +In v3, treat those as migration references rather than the primary configuration source. Re-create or verify them in the Web admin panel after upgrading. -## 5. Upgrade Steps for Server Owners (Old -> New) +## Security Checklist -1. Back up old `config.yml` first (recommended rename: `config.legacy.bak.yml`). -2. Start with minimal new config (ensure database, ports, and admin bootstrap are usable). -3. Log in to admin panel and restore business settings one by one (currencies, exchange, taxes, leaderboard, etc.). -4. Remove or comment legacy business fields to avoid ambiguity from duplicate config sources. +1. Replace/disable the default bootstrap administrator after initialization. +2. Do not commit database passwords or Relay keys to Git. +3. Restrict database access to the required hosts only. +4. Use HTTPS for public deployments. +5. Keep experimental offline-inventory write features disabled unless explicitly tested. +6. Back up both database state and `plugins/WebShopX/` before upgrades. -## 6. Pre-Launch Checklist - -1. Default admin password has been changed. -2. `database` account has only required privileges. -3. No production passwords were committed to public repositories. -4. Cluster mode was not enabled accidentally on a single server. -5. If cross-server broadcast is needed, Redis and channel names are consistent. - - -## SQLite Config Addendum (New) - -`database.type` now supports: `mysql | mariadb | sqlite` - -SQLite-specific fields: - -- `sqlite-file` -- `sqlite-journal-mode` -- `sqlite-synchronous` -- `sqlite-busy-timeout-ms` -- `sqlite-max-retries` -- `sqlite-retry-backoff-ms` - -Hard limit: when `database.type=sqlite`, `cluster.role` must be `standalone`. +:::warning +When documentation and a specific release differ, the `config.yml` shipped with that WebShopX release is the source of truth. +::: diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/install-and-deploy.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/install-and-deploy.md deleted file mode 100644 index fbb1454..0000000 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/install-and-deploy.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -id: install-deploy -title: Install and Deploy -sidebar_label: Install and Deploy -sidebar_position: 2 ---- - -# Install and Deploy - -## 1. Requirements - -- Java: `21` -- Server: `Paper 1.20.6+` (compatible with Spigot) -- Database: MariaDB / MySQL -- Optional dependency: Vault (for `GAME_COIN` integration) - -## 2. Get the Plugin - -- [modrinth](https://modrinth.com/plugin/webshopx) -- [minebbs](https://www.minebbs.com/resources/webshopx-minecraft.15688/updates) - -## 3. Pre-Deployment Checklist - -1. Database is installed. MariaDB recommended: https://mariadb.org/download/ -2. WebShopX plugin is downloaded. -3. Database name, username, and password are prepared (example): - -```yaml -schema: db_01 -username: user_01 -password: admin123 -``` - -## 4. Database Initialization (First Deployment) - -### (1) Log In to the Database - -Log in as an administrator: - -```text -mysql -u root -p -``` - -### (2) Create Database and User - -```sql --- 1. Create database -CREATE DATABASE db_01 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; - --- 2. Create user (local access) -CREATE USER 'user_01'@'localhost' IDENTIFIED BY 'admin123'; - --- 3. Grant all privileges on db_01 -GRANT ALL PRIVILEGES ON db_01.* TO 'user_01'@'localhost'; - --- 4. Flush privileges -FLUSH PRIVILEGES; -``` - -> **Note**: If your plugin runs in Docker or on another host, change `'localhost'` to `'%'`. - -## 5. First-Time Deployment Flow - -1. Put the plugin JAR into the server `plugins/` directory. -2. Start the server once to generate default configs. -3. Edit `plugins/WebShopX/config.yml`, at least `database.*`. -4. Restart the server. -5. In game, run: - -```text -/ws password -``` - -6. Open the player page: - -```text -http://:8819/ -``` - -7. Open the admin page: - -```text -http://:8819/admin.html -``` - -:::danger[Default Database Placeholders Block Startup] - -Default values: - -- `database.host: 127.0.0.1` -- `database.schema: webshop` -- `database.username: webshop` -- `database.password: change_me` - -If these placeholders remain unchanged, the plugin will refuse normal startup. - -::: - ---- - -### (1) Default Admin Bootstrap Account - -`webshop.admin-bootstrap` is enabled by default. Initial account: - -- Username: `admin` -- Password: `admin123456` - -:::warning[Reminder] -In production, change this immediately or disable this setting. -::: - -### (2) Runtime Mode Selection - -#### `internal` (default) - -- Plugin serves both API and static web pages. -- Best for quick launch and testing. - -#### `external` - -- Plugin serves API only. -- Static files are exported to `plugins/WebShopX/web/`. -- Can be used with Nginx/CDN reverse proxy. - -Recommended settings in `external` mode: - -- `webshop.api-base-url` -- HTTPS reverse proxy -- Reasonable caching and access control - -## 6. Production Security Checklist - -- Change database credentials and restrict DB access sources. -- Disable or reset the default `admin-bootstrap` admin account. -- Provide HTTPS via Nginx / CDN. -- Expose only required ports (default 8819). -- Regularly back up database and `plugins/WebShopX` data directory. -- Monitor the log directory (`webshop.logging.directory`). - -## 7. Reverse Proxy Recommendations (`external` mode) - -- Point frontend static root to the exported `web` directory. -- Forward `/api/` to the plugin service address. -- Pass through `X-Forwarded-For` for source IP auditing. - -## 8. Upgrade Recommendations - -1. Back up the database before upgrading. -2. Stop the server. -3. Remove the `web` folder (optional, to force-refresh frontend pages). -4. Replace the JAR. -5. Start the server. -6. Verify these key features: - - Login and session - - Order placement and refund - - Market buy/bid flow - - Admin panel login and permissions - - -## SQLite Support (New) - -WebShopX now supports `database.type=sqlite` for single-node deployment. - -### Scope - -- Recommended: single server, lightweight deployment, medium traffic. -- Not recommended: multi-node cluster or heavy write contention. - -### Hard Guard - -When using SQLite: - -- `cluster.role` **must** be `standalone` -- `master/node` roles are intentionally rejected at startup diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/install-deploy.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/install-deploy.md new file mode 100644 index 0000000..46323d0 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/install-deploy.md @@ -0,0 +1,75 @@ +--- +id: install-deploy +title: Install and Deploy +sidebar_label: Install and Deploy +sidebar_position: 2 +--- + +# Install and Deploy + +## Requirements + +Choose a WebShopX build that matches both your Minecraft runtime and Java version: + +- Minecraft `1.18.2+`: Java `17` +- Minecraft `1.20.6+` (default line): Java `21` +- Minecraft `26.1+ / 26.2+`: Java `25` + +SQLite is the default database for quick single-server setup. MySQL or MariaDB is recommended for production or multi-server deployments. Vault is optional for `GAME_COIN` integration. + +## First Startup + +1. Put the WebShopX JAR in `plugins/`. +2. Start the server once. +3. Review `plugins/WebShopX/config.yml`. +4. Restart the server. +5. Players set their web password with `/ws password `. +6. In `internal` mode, open `http://:8819/`. +7. Enter administration from the web UI; `/admin.html` is only a compatibility redirect in v3. + +Default bootstrap administrator: + +```text +username: admin +password: admin123456 +``` + +Replace or disable it immediately after initialization. + +## Deployment Modes + +### `internal` + +WebShopX serves both API and built-in static web pages. This is the simplest deployment mode. + +### `external` + +WebShopX serves the API while static files are hosted by Nginx/CDN or another web server. Configure `webshop.embedded-http.public-api-url`, CORS only when required, HTTPS, and reverse proxy rules. + +### `relay` + +WebShopX connects outbound to WebShopX Relay, so the Minecraft host does not need to expose the Web port directly. Prefer the in-game Relay setup workflow and keep the access key secret. + +## SQLite + +SQLite requires: + +```yaml +database: + type: sqlite + sqlite-file: plugins/WebShopX/webshopx.db + +cluster: + role: standalone +``` + +Do not use SQLite with `master` or `node` cluster roles. + +## Production Checklist + +- replace default administrator credentials; +- use strong database credentials and restrict access; +- use HTTPS for public access; +- never expose Relay/payment/database secrets; +- back up database and `plugins/WebShopX/` before upgrades; +- after upgrading, verify login, orders, delivery/refund, market trading, and admin access. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/overview.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/overview.md index 03b8807..8bf27e1 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/overview.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/admin/overview.md @@ -1,53 +1,47 @@ ---- +--- id: overview title: Overview sidebar_label: Overview sidebar_position: 1 --- -# WebShopX Server Owner Docs - -## Issue Tracking +# WebShopX Server Administrator Guide -- Issues repository: https://github.com/Prism-Committee/WebShopX-Issues +This section is for plugin installers, server operators, and WebShopX administrators. -This section is for plugin installers, operators, and admin-panel managers. +## Recommended Reading Path -:::info[Reading Map] 1. [Install and Deploy](./install-deploy) -2. [Configuration and Runtime Parameters](./configuration) -3. [Commands and Permission System](./commands-permissions) -4. [Market Governance and Risk Control](./governance) -5. [Delivery, Claim, and Refund Operations](./delivery-refund-ops) -6. [Operations Troubleshooting FAQ](./faq) -::: - -## WebShopX Topology at a Glance - -| Component | Description | +2. [Configuration](./configuration) +3. [Commands and Permissions](./commands-permissions) +4. [Relay Access](./relay-access) +5. [Market Governance](./market-governance) +6. [Inventory Operations](./inventory-operations) +7. [Delivery and Refund Operations](./delivery-and-refund-ops) +8. [v2 to v3 Migration](./v2-to-v3-migration) +9. [FAQ](./faq) + +## Deployment Components + +| Component | Purpose | | --- | --- | -| Plugin Process | Built-in API service, can optionally host static pages | -| MySQL/MariaDB | Core business data storage | -| Vault (Optional) | `GAME_COIN` economy integration | -| Redis (Optional) | Cluster config refresh and market broadcast | - -## Risks You Should Prioritize First - -:::warning[High-Risk Configuration Reminder] -1. Do not keep placeholder database values (`127.0.0.1:3306/webshop/webshop/change_me`), or the plugin will refuse to start. -2. In production, replace the initial `admin-bootstrap` password immediately after first startup. -3. In cluster mode, `cluster.role=node` will not start Web/API. This is expected by design. -::: - -## Recommended Operations Rhythm - -1. First, make sure "can start, can log in, can place orders" works. -2. Then tune fees, limitation rules, and broadcast strategy. -3. Finally run high-concurrency and failure-scenario regression (refund, claim, restock, cluster sync). - -## SQLite Deployment Scope (New) - -- Best for single-node, lightweight deployments. -- Not suitable for multi-node cluster roles (`master/node`). -- With SQLite, `cluster.role` must stay `standalone`. - +| WebShopX plugin | Core business logic, HTTP API, optional built-in web UI | +| SQLite | Default single-server database; requires `cluster.role=standalone` | +| MySQL / MariaDB | Recommended for production or multi-server deployments | +| Vault (optional) | Connects `GAME_COIN` to the game economy | +| Redis (optional) | Cluster config refresh and market broadcast | +| WebShopX Relay (optional) | Public access without exposing the server web port directly | +| WebShopX-Payments (optional) | Online payment-channel extension | + +## High-Priority Checks + +1. Replace or disable the default `admin-bootstrap` account after first login. +2. Never expose database, Relay, or payment credentials in public repositories or screenshots. +3. SQLite is standalone-only. +4. Use HTTPS and a reverse proxy for public deployments. +5. Offline playerdata writes are experimental and should stay disabled unless explicitly required and tested. +6. Back up both the database and `plugins/WebShopX/` before upgrades. + +## Configuration Responsibility + +In v3, `config.yml` mainly stores local deployment, security, database, and cluster parameters. Business rules such as market fees, currencies, and leaderboard settings should normally be managed in the web admin panel instead of duplicated in local YAML. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/admin-api.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/admin-api.md new file mode 100644 index 0000000..7b60206 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/admin-api.md @@ -0,0 +1,26 @@ +--- +id: admin-api +title: Admin API +sidebar_label: Admin API +sidebar_position: 5 +--- + +# Admin API + +Admin endpoints require a valid administrator session and, for most operations, the corresponding fine-grained permission. + +Major endpoint groups include: + +- `/api/admin/auth/*` — administrator authentication +- `/api/admin/redeem/*` — redeem codes +- `/api/admin/products/*` — products +- `/api/admin/orders/*` — order inspection +- `/api/admin/economy/*` — currency/exchange/market/leaderboard settings +- `/api/admin/market/*` — market configuration and moderation +- `/api/admin/users/*` — user support and wallet adjustment +- `/api/admin/audit/*` — audit logs +- `/api/admin/admin-users/*` — super-admin account management + +Important write operations are permission checked and may be audited. Clients must handle `bad_request`, `forbidden`, and `auth_invalid` correctly. + +Administrator session tokens are sensitive credentials and should never be exposed to untrusted browser applications or third-party sites. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/api-basics.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/api-basics.md new file mode 100644 index 0000000..5fa1da7 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/api-basics.md @@ -0,0 +1,30 @@ +--- +id: api-basics +title: HTTP API Basics +sidebar_label: HTTP API Basics +sidebar_position: 1 +--- + +# HTTP API Basics + +WebShopX exposes its HTTP API through `webshop.embedded-http.host` and `webshop.embedded-http.port` (default port `8819`). + +- `internal`: API + built-in static web UI. +- `external`: API only; frontend is hosted separately. +- `relay`: public access is provided through WebShopX Relay. + +API requests and responses primarily use UTF-8 JSON. Error responses normally include a stable `error` code and a human-readable `message`. + +```json +{"error":"error_code","message":"error message"} +``` + +Authenticated requests commonly use: + +```http +Authorization: Bearer +``` + +For cross-origin frontends, explicitly configure CORS and only allow the origins you need. The health endpoint is `GET /health`. + +Use the exact WebShopX version you target as the final authority for paths, fields, and response behavior. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/authentication.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/authentication.md new file mode 100644 index 0000000..1e15350 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/authentication.md @@ -0,0 +1,34 @@ +--- +id: authentication +title: Authentication and Sessions +sidebar_label: Authentication +sidebar_position: 2 +--- + +# Authentication and Sessions + +## Player Login + +`POST /api/auth/login` + +Typical request: + +```json +{ + "identifier": "player_name_or_uuid", + "password": "your_password" +} +``` + +Successful login returns a session token and user/session metadata. Authenticated requests normally use `Authorization: Bearer `. + +Player session endpoints include: + +- `GET /api/auth/me` +- `POST /api/auth/logout` + +Administrator login uses `POST /api/admin/auth/login` and returns administrator role/permission information in addition to session data. + +Common authentication errors include `auth_required`, `auth_invalid`, and `invalid_credentials`. + +Resetting a password or forcing a user logout may invalidate existing sessions. Clients should handle `auth_invalid` globally and return the user to login. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/errors-and-idempotency.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/errors-and-idempotency.md new file mode 100644 index 0000000..f0d5461 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/errors-and-idempotency.md @@ -0,0 +1,22 @@ +--- +id: errors-and-idempotency +title: Errors and Idempotency +sidebar_label: Errors and Idempotency +sidebar_position: 6 +--- + +# Errors and Idempotency + +Use the stable `error` field as the programmatic branch key. Human-readable `message` text is for display and troubleshooting. + +Common groups include: + +- Authentication: `auth_required`, `auth_invalid`, `invalid_credentials`, `forbidden` +- Parameters: `bad_request`, `method_not_allowed`, `invalid_quantity` +- Wallet: `insufficient_funds`, `exchange_disabled`, `vault_unavailable` +- Market: `listing_unavailable`, `buy_requires_*`, `auction_closed`, `bid_too_low`, `limitation_*` +- Delivery/refund: `claim_forbidden`, `refund_not_allowed`, `refund_expired`, `already_refunded` + +Use stable `idempotencyKey` values for state-changing requests such as exchange, order creation, market purchases, fulfilling BUY orders, and bids. + +When retrying after a timeout, reuse the same key. Do not generate a new key for every retry of the same user action. If the server reports an idempotency conflict, stop blind retries and refresh the current business state first. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/integration-playbook.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/integration-playbook.md new file mode 100644 index 0000000..b93ce9f --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/integration-playbook.md @@ -0,0 +1,44 @@ +--- +id: integration-playbook +title: Integration Playbook +sidebar_label: Integration Playbook +sidebar_position: 8 +--- + +# Integration Playbook + +## Minimal Player Integration + +1. `POST /api/auth/login` +2. `GET /api/meta/currency` +3. `GET /api/products` +4. `POST /api/orders` +5. `GET /api/orders/list` +6. `GET /api/notifications/unread-count` + +## Market Integration + +1. Query listings. +2. Implement direct purchase / BUY-order fulfillment. +3. Refresh listing state and notifications after writes. +4. Add bidding only after the basic market flow is stable. +5. Add seller configuration, restock, and advanced settings last. + +## Admin Integration + +1. Authenticate as an administrator. +2. Read the current administrator role/permissions. +3. Add modules according to permissions. +4. Add auditing and high-risk system settings last. + +## Reliability Checklist + +- reuse stable idempotency keys for retries; +- globally handle `auth_invalid`; +- branch on `error`, not localized messages; +- parse time fields defensively; +- confirm current business state before retrying a timed-out write; +- configure the API root instead of hardcoding a host; +- never log full tokens or secrets. + +After every WebShopX upgrade, regression-test login, orders, delivery/refund, market trading, admin authentication, and your deployment mode. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/market-api.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/market-api.md new file mode 100644 index 0000000..55a5222 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/market-api.md @@ -0,0 +1,26 @@ +--- +id: market-api +title: Market API +sidebar_label: Market API +sidebar_position: 4 +--- + +# Market API + +Common market endpoints include listing queries, listing creation, direct purchases, fulfilling BUY orders, bidding, unlisting, pausing/resuming, repricing, settings updates, icon uploads, and supply refresh. + +Key paths include: + +- `GET /api/market/listings` +- `POST /api/market/listings/create` +- `POST /api/market/buy` +- `POST /api/market/sell-to-buy` +- `POST /api/market/bid` +- `POST /api/market/unlist` +- `POST /api/market/settings` +- `POST /api/market/icon/upload` +- `POST /api/market/supply/refresh` + +State-changing market requests should use stable idempotency keys where supported. Server-side listing limitations, permissions, item state, trade mode, and auction state can all reject a request even when the JSON is syntactically valid. + +Handle errors by `error` code, including `listing_unavailable`, `invalid_quantity`, `buy_requires_*`, `auction_closed`, `bid_too_low`, and `limitation_*`. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/overview.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/overview.md new file mode 100644 index 0000000..2dae7de --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/overview.md @@ -0,0 +1,30 @@ +--- +id: overview +title: Developer Overview +sidebar_label: Overview +sidebar_position: 1 +--- + +# WebShopX Developer Docs + +This section is for developers integrating with the WebShopX HTTP API or implementing a third-party payment provider. + +Recommended reading order: + +1. [HTTP API Basics](./api-basics) +2. [Authentication and Sessions](./authentication) +3. [Player API](./player-api) +4. [Market API](./market-api) +5. [Admin API](./admin-api) +6. [Errors and Idempotency](./errors-and-idempotency) +7. [Uploads and Static Assets](./uploads-and-static-assets) +8. [Integration Playbook](./integration-playbook) +9. [Payment Provider API](../webshopx-payment-api) + +## Integration Rules + +- Verify the exact WebShopX version first. +- Branch on stable error codes rather than human-readable messages. +- Use idempotency for state-changing requests. +- Do not expose administrator credentials, Relay keys, database passwords, or payment secrets in browser code. +- Re-run critical login, order, market, and admin flows after upgrades. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/player-api.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/player-api.md new file mode 100644 index 0000000..cc3c695 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/player-api.md @@ -0,0 +1,30 @@ +--- +id: player-api +title: Player API +sidebar_label: Player API +sidebar_position: 3 +--- + +# Player API + +Common endpoints include wallet, exchange, redeem codes, products, orders, notifications, metadata, and leaderboards. + +| Method | Path | Auth | +| --- | --- | --- | +| GET | `/api/wallet` | user | +| GET | `/api/wallet/ledger` | user | +| POST | `/api/wallet/exchange` | user | +| POST | `/api/redeem/use` | user | +| GET | `/api/products` | optional | +| POST | `/api/orders` | user | +| GET | `/api/orders/list` | user | +| POST | `/api/orders/refund` | user | +| GET | `/api/notifications/list` | user | +| GET | `/api/notifications/unread-count` | user | +| POST | `/api/notifications/mark-read` | user | +| GET | `/api/meta/currency` | none | +| GET | `/api/meta/materials` | none | +| GET | `/api/meta/market-tags` | none | +| GET | `/api/leaderboard/list` | optional | + +Use stable `idempotencyKey` values for state-changing requests such as exchange and order creation. Delivery/refund behavior is also affected by server-side policy and the current order state. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/uploads-and-static-assets.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/uploads-and-static-assets.md new file mode 100644 index 0000000..778d254 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/developer/uploads-and-static-assets.md @@ -0,0 +1,18 @@ +--- +id: uploads-and-static-assets +title: Uploads and Static Assets +sidebar_label: Uploads and Static Assets +sidebar_position: 7 +--- + +# Uploads and Static Assets + +Common upload endpoints include player listing icons, admin product icons, and material override icons. + +These endpoints use raw file bytes rather than multipart form uploads. The server may infer the filename/extension from query parameters, `X-File-Name`, or `Content-Type`. + +Current documented limits are approximately 2 MB and common image formats such as PNG, WebP, JPEG, and GIF. Always treat the target WebShopX version as authoritative. + +Successful uploads normally return a managed path under locations such as `/uploads/listing-icons/`, `/uploads/product-icons/`, or `/uploads/material-icons/`. + +In `external` deployments, verify that uploaded asset paths are actually reachable through your reverse proxy/CDN, not just that the upload request succeeded. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/overview.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/overview.md new file mode 100644 index 0000000..9257ab0 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/overview.md @@ -0,0 +1,31 @@ +--- +id: webshopx-overview +title: Getting Started with WebShopX +sidebar_label: Getting Started +sidebar_position: 0 +--- + +# WebShopX + +WebShopX is a web-first shop system for Paper, Purpur, Spigot, and Folia servers. It combines the official shop, player market, wallets, orders and delivery, recharge, and administration. + +## Choose Your Path + +| Role | Start here | +| --- | --- | +| Player | [Player Guide](./player/overview) | +| Server owner / operator | [Server Administrator](./admin/overview) | +| HTTP API / plugin developer | [Developer Docs](./developer/overview) | +| Looking for exact parameters | [Reference](./reference/overview) | + +## Documentation Baseline + +These docs primarily track the WebShopX v3 development line. Confirm the exact WebShopX version installed on your server before relying on configuration or API details. + +## WebShopX and WebShopX-Payments + +WebShopX owns the shop, assets, orders, and business state. WebShopX-Payments is the optional standalone extension that connects payment channels. + +- No online payments: WebShopX-Payments is optional. +- Need recharge channels: read [WebShopX-Payments](../webshopx-payments/overview). +- Building your own payment provider: read [Payment Provider API](./webshopx-payment-api). diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/inventory.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/inventory.md new file mode 100644 index 0000000..d6a267a --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/inventory.md @@ -0,0 +1,40 @@ +--- +id: inventory +title: Web Inventory and Quick Trading +sidebar_label: Web Inventory +sidebar_position: 4 +--- + +# Web Inventory and Quick Trading + +The WebShopX inventory page can display your inventory/end chest and, when the server allows it, start market actions directly from an item slot. + +## Feature Status + +Inventory behavior depends on your online/offline state and the features enabled by the server administrator. + +| State | Meaning | Trading | +| --- | --- | --- | +| Online | Live server inventory | Available when allowed | +| Offline read-only snapshot | Last saved view | Not writable | +| Offline persistent inventory access | Experimental server-side capability | May be writable, with explicit risk controls | +| No snapshot | No supported saved state exists | Not available | + +## Common Actions + +Depending on server rules, the page may allow you to: + +- fulfill a compatible BUY order; +- create a fixed-price listing; +- start an auction; +- inspect item name, amount, enchantments, lore, and equipment slot information. + +Before a write action is accepted, WebShopX validates the actual slot/item again. If the item moved or changed, refresh the page and retry from the new state. + +:::warning +Offline playerdata writes are experimental and may be disabled entirely by the server owner. A read-only snapshot is not a writable inventory. +::: + +## Troubleshooting + +If the web page differs from the game, first check whether the page is showing a live inventory or an offline snapshot, then refresh. Disabled actions usually mean the inventory is read-only, the item is restricted, no compatible order exists, or the server has disabled that capability. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/overview.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/overview.md index a7c3b86..a0be0b6 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/overview.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/overview.md @@ -1,61 +1,47 @@ ---- +--- id: overview title: Overview sidebar_label: Overview sidebar_position: 1 --- -# Overview - -## Issue Tracking - -- Issues repository: https://github.com/Prism-Committee/WebShopX-Issues +# WebShopX Player Guide -This player documentation works as a roadmap from beginner to advanced usage. Content is based on current version behavior. +This section is for regular players. It focuses on actions you perform in game or on the WebShopX site. -:::tip[Guide] -Great for regular players: feature explanations, usage tutorials, FAQs, and terminology. -::: +## Start Here -## Which Page Should You Read First? +| Goal | Read | +| --- | --- | +| First web login | [Quick Start](./quick-start) | +| Buy items, view orders, refund | [Shop, Market, and Orders](./shop-and-orders) | +| Check balances, exchange, recharge | [Wallet and Exchange](./wallet-and-exchange) | +| View web inventory or start a trade | [Web Inventory](./inventory) | +| Claim pending deliveries or mailbox items | [Claim and Mailbox](./claim-and-mailbox) | +| Use auctions | [Auctions](./auctions) | +| Understand dynamic pricing | [Dynamic Pricing](./dynamic-pricing) | +| Troubleshoot listing rejection | [Listing Limits](./limits) and [FAQ](./faq) | +| Look up terminology | [Glossary](./glossary) | -| Your Goal | Start Here | What You Get | -| --- | --- | --- | -| First-time use | [Quick Start](./quick-start) | Login, password, and basic actions | -| Check balance / exchange | [Wallet and Exchange](./wallet-and-exchange) | Dual-currency model, exchange flow, common errors | -| Buy items, place orders, check orders | [Official Shop, Player Market, and Orders](./shop-and-orders) | Purchase flow, order states, delivery, and refunds | -| Claim failed orders or redelivered items | [Claim and Mailbox](./claim-and-mailbox) | Correct usage of `claim` and mailbox claiming | -| Understand auctions | [Auctions](./auctions) | Four auction modes and practical differences | -| Understand price changes | [Dynamic Pricing](./dynamic-pricing) | Why prices rise/fall and how algorithms feel in practice | -| Investigate listing rejection / trade failure | [Listing Limits](./limits) + [FAQ](./faq) | Error code meanings and troubleshooting sequence | -| Learn underlying mechanics | [Algorithm](./algorithm) | Core logic behind dynamic pricing and auction systems | -| Don't understand terms | [Glossary](./glossary) | Quick lookup of common terms | - -## Common Commands Quick Reference +## Common Commands ```text -/ws help +/ws +/ws home /ws password -/ws market -/ws market gui /ws market sell [amount] [currency] /ws market logs [count] /ws claim [all|ODR-|MKT-|CLM-|MCL-] -/ws mailbox claim +/ws mailbox +/ws mailbox collect ``` -## 4 Things New Players Most Often Miss - -:::warning[Remember These 4 First] -1. Set your web password in game first: `/ws password `. -2. Wallet is dual-currency: `SHOP_COIN` and `GAME_COIN`. -3. Auto-delivery failure becomes `WAIT_CLAIM`, and you must `claim` manually. -4. If inventory is full, items go to mailbox; use `/ws mailbox claim` to retrieve. -::: +Full command and permission details are maintained in the administrator/reference documentation rather than duplicated here. -## Fast Navigation Recommendations +## Feature Status -- To finish your first trade quickly: read `Quick Start -> Wallet and Exchange -> Official Shop, Player Market, and Orders`. -- To reduce trading mistakes: read `Listing Limits` and `FAQ` first. -- To improve trading strategy: then read `Auctions`, `Dynamic Pricing`, and `Algorithm`. +- **Stable**: intended for normal use. +- **Beta**: usable, but behavior or UI may still change. +- **Experimental**: may be disabled by default or have explicit risks/limitations. +Offline playerdata writes are experimental. Whether they are available is controlled by the server administrator. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/quick-start.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/quick-start.md index dafa466..f8bcd43 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/quick-start.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/player/quick-start.md @@ -7,48 +7,34 @@ sidebar_position: 2 # Quick Start -Goal of this page is simple: prepare your account and enter WebShopX successfully in 3 minutes. +Use this page to set your WebShopX password and enter the web shop. -:::info[In This Page] -- Part 1: 3 steps before first login -- Part 2: Account and password rules (validated in source code) -- Part 3: Session and common errors -::: - -## 1. First Login +## First Login -1. Run this in game: +1. In game, run: ```text /ws password ``` -2. Log in to the web page with the same account (default is your Minecraft username) and that password. - -## 2. Commands - -```text -/ws market -/ws claim -/ws mailbox claim -``` +2. Run `/ws home` to get the web-shop address configured by the server owner. +3. Log in with your Minecraft identity and the password you just set. -## 3. Common Errors and Fixes +## Common Problems -| Error Code | Meaning | Suggested Fix | +| Error | Meaning | What to do | | --- | --- | --- | -| `invalid_username` | Invalid username format | Check length and characters (letters/numbers/underscore) | -| `invalid_password` | Invalid password length | Change to 8-64 characters | -| `username_exists` | Username conflict | Use another username and retry | -| `invalid_credentials` | Wrong login credentials | Verify account, password, and case | -| `auth_invalid` | Session expired/invalid | Log in again for a new token | +| `invalid_password` | Password does not meet current rules | Choose a valid password and retry | +| `invalid_credentials` | Login credentials are wrong | Recheck identity, password, and case | +| `auth_invalid` | Session expired or is no longer valid | Log in again | -
- Recommended Troubleshooting Order - -1. Confirm you already ran `/ws password` in game. -2. Confirm password length is between 8 and 64. -3. If web session is invalid, fully log out and log in again. +:::tip +Do not treat old registration-oriented errors such as `username_exists` as part of the normal v3 player flow. The current onboarding path starts with `/ws password` in game. +::: -
+## After Login +- Shop and orders: [Shop, Market, and Orders](./shop-and-orders) +- Balance and exchange: [Wallet and Exchange](./wallet-and-exchange) +- Pending deliveries: [Claim and Mailbox](./claim-and-mailbox) +- Web inventory: [Web Inventory](./inventory) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/webshopx/reference/overview.md b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/reference/overview.md new file mode 100644 index 0000000..e5812ea --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/webshopx/reference/overview.md @@ -0,0 +1,32 @@ +--- +id: overview +title: Reference +sidebar_label: Reference +sidebar_position: 1 +--- + +# WebShopX Reference + +Use this page to find the authoritative documentation for exact parameters instead of maintaining duplicate copies. + +| Need | Reference | +| --- | --- | +| `config.yml` fields | [Configuration](../admin/configuration) | +| Commands and Bukkit permissions | [Commands and Permissions](../admin/commands-permissions) | +| Player terminology | [Glossary](../player/glossary) | +| HTTP API basics | [HTTP API Basics](../developer/api-basics) | +| Authentication | [Authentication and Sessions](../developer/authentication) | +| Player API | [Player API](../developer/player-api) | +| Market API | [Market API](../developer/market-api) | +| Admin API | [Admin API](../developer/admin-api) | +| Errors and idempotency | [Errors and Idempotency](../developer/errors-and-idempotency) | +| v2 to v3 migration | [Migration Guide](../admin/v2-to-v3-migration) | + +## Source-of-Truth Order + +When documentation conflicts with a specific release, use this order: + +1. Code/configuration shipped with the WebShopX version you run. +2. Reference documentation. +3. Task-oriented guides. +4. README files, old screenshots, or third-party tutorials. diff --git a/sidebars.ts b/sidebars.ts index 912bda3..67a781b 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -4,16 +4,6 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs'; const currentLocale = process.env.DOCUSAURUS_CURRENT_LOCALE ?? 'zh-CN'; const isZh = currentLocale === 'zh-CN'; -/** - * Creating a sidebar enables you to: - - create an ordered group of docs - - render a sidebar for each doc of that group - - provide next/previous navigation - - The sidebars can be generated from the filesystem, or explicitly defined here. - - Create as many sidebars as you want. - */ const sidebars: SidebarsConfig = { tutorialSidebar: [ 'intro', @@ -22,49 +12,68 @@ const sidebars: SidebarsConfig = { label: 'WebShopX', link: { type: 'generated-index', - title: 'webshopx', - description: isZh ? 'WebShopX 文档导航' : 'WebShopX docs navigation', + title: 'WebShopX', + description: isZh + ? '从开始使用进入玩家、服务器管理员、开发者与 Reference 文档。' + : 'Start with WebShopX, then continue to player, server administrator, developer, or reference docs.', slug: '/category/webshopx', }, items: [ + {type: 'doc', id: 'webshopx/webshopx-overview'}, { type: 'category', - label: isZh ? '玩家文档' : 'Player Docs', + label: isZh ? '玩家指南' : 'Player Guide', link: { type: 'generated-index', - title: isZh ? '玩家文档' : 'Player Docs', + title: isZh ? '玩家指南' : 'Player Guide', description: isZh - ? '面向普通玩家的使用说明与排障。' - : 'Usage guides and troubleshooting for players.', - slug: '/category/player-docs', + ? '登录、购买、玩家市场、钱包、背包、领取与常见问题。' + : 'Login, shopping, player market, wallet, inventory, claiming, and troubleshooting.', + slug: '/category/player-guide', }, items: [{type: 'autogenerated', dirName: 'webshopx/player'}], }, { type: 'category', - label: isZh ? '服主文档' : 'Admin Docs', + label: isZh ? '服务器管理员' : 'Server Administrator', link: { type: 'generated-index', - title: isZh ? '服主文档' : 'Admin Docs', + title: isZh ? '服务器管理员' : 'Server Administrator', description: isZh - ? '面向服主和管理员的部署、配置与运维文档。' - : 'Deployment, configuration, and operations docs for server admins.', - slug: '/category/admin-docs', + ? '安装、部署、配置、权限、运维、安全与升级。' + : 'Installation, deployment, configuration, permissions, operations, security, and upgrades.', + slug: '/category/server-admin', }, items: [{type: 'autogenerated', dirName: 'webshopx/admin'}], }, { type: 'category', - label: isZh ? '开发者文档' : 'Developer Docs', + label: isZh ? '开发者' : 'Developer', + link: { + type: 'generated-index', + title: isZh ? '开发者' : 'Developer', + description: isZh + ? 'HTTP API、认证、市场与后台接口，以及第三方支付 Provider 集成。' + : 'HTTP API, authentication, market/admin endpoints, and third-party payment provider integration.', + slug: '/category/webshopx-developer', + }, + items: [ + {type: 'autogenerated', dirName: 'webshopx/developer'}, + {type: 'doc', id: 'webshopx/webshopx-payment-api'}, + ], + }, + { + type: 'category', + label: 'Reference', link: { type: 'generated-index', - title: isZh ? '开发者文档' : 'Developer Docs', + title: 'WebShopX Reference', description: isZh - ? '面向插件开发者的 API 对接文档。' - : 'API integration docs for plugin developers.', - slug: '/category/developer-docs', + ? '配置、命令、权限、API、错误码与版本差异的权威索引。' + : 'Authoritative index for configuration, commands, permissions, APIs, errors, and version differences.', + slug: '/category/webshopx-reference', }, - items: [{type: 'doc', id: 'webshopx/webshopx-payment-api'}], + items: [{type: 'autogenerated', dirName: 'webshopx/reference'}], }, ], }, @@ -75,8 +84,8 @@ const sidebars: SidebarsConfig = { type: 'generated-index', title: isZh ? 'WebShopX-Payments' : 'WebShopX Payments', description: isZh - ? 'WebShopX-Payments 插件的安装、配置、渠道与常见问题。' - : 'Payment plugin docs for installation, configuration, channels, and FAQ.', + ? 'WebShopX 的独立支付扩展插件：安装、配置、支付渠道与常见问题。' + : 'The standalone payment extension for WebShopX: installation, configuration, channels, and FAQ.', slug: '/category/webshopx-payments', }, items: [{type: 'autogenerated', dirName: 'webshopx-payments'}],