仍在开发中：积分、称号等核心玩法尚未落地。见开发状态。

Wiki 文档：完整使用文档与玩法指引见 PCHSystem Wiki（搭建中，内容持续补充）。

---

功能特性

核心特性

• 后端分离 — 游戏内端与后端完全分离（不强制绑定 MCDR），后端可独立部署，游戏内端仅作为客户端
• 独立前端 — 提供独立 Web 前端，玩家不进游戏也能查看项目进度、编辑材料清单、上传投影 / 蓝图；游戏端或 MCDR 重启时，Web 端仍可独立访问
• 兼容性强 — 基于 MCDR 的强大兼容性，可在几乎所有 Minecraft 版本上运行

已实现功能

登录鉴权

• !!PCH login 一键生成登录链接，点击直接进入 Web 页面

项目协作（在线表格）

完整的项目材料清单协作——认领材料、多人累计上交、交付确认、打回返工、解除锁定，Web 端与游戏端对等操作。

• 一键提交：支持扫描背包（含潜影盒内物品）上报进度，提供双维度抽象层方便二次开发
• 投影 / 蓝图一键建表：上传 .litematic 投影或 Create .nbt 蓝图，自动解析方块、翻译中文名、生成材料清单（支持原版与模组物品；多份投影合并为同一项目；单投影倍数设置）（仅 Web 端）
• 子物品：通过倍数（支持小数）直接生成子一级合成物品清单
• 快捷命令：游戏内大量命令支持可点击交互，减少手打
• 智能换算：自动将数量换算为可读性更高的 个 / 组 / 盒
• 手持读取：游戏内读取手持物品 registry-id，直接更改 / 新增所需物品，免去手打 ID
• Web 端行编辑：在线编辑材料行（名称 / 数量 / registry-id），与游戏端对等

项目协作（施工阶段）

完成施工阶段对不同参与者的贡献统计。

• 开放统计层：提供面向客户端 / 服务端两种鉴权方式的 API，复用 JWT 与 service-token
• 默认服务端统计层：轮询玩家 json 文件进行 diff，汇报项目相关数据
• 多种图表：提供多种图表直观、准确地显示项目进度，前端已预留接口随时切换

项目归档

项目完结自动生成归档文档 + 贡献占比饼图，精确记录每位参与者的贡献。

通知投递

认领 / 交付 / 打回 / 项目状况变化 / 上交等事件游戏内自动通知，离线期间通知上线补推。

效果一览

游戏内 · 材料清单	Web 端 · 施工贡献图表

查看更多截图

Web 端 · 在线表格	游戏内 · 登录链接
游戏内 · 数量换算	Web 端 · 子物品提交
项目归档	通知投递

规划中

• 积分体系 — 统一积分入账 / 出账层 + 排行榜 + 项目归档自动结算
• 指数增长称号 — 积分达标自动解锁，聊天前缀差异化，高阶全服公告
• 施工阶段 — 真正校验建造放置（主体已完成）+ 实时计分板进度
• Wiki 归档同步 — 归档内容双向同步到 wiki.js + 项目权限继承
• 管理员面板 — 服务器管理面板

---

快速开始

一键脚本（推荐）

面向服主，一条命令完成 Docker 安装、国内网络镜像自适应、配置生成、起服务、数据库迁移、前端构建、pch_system 插件部署与 token 双写：

git clone https://github.com/YuShenLiu06/PCHSystem.git

# 或使用 Gitee 镜像
git clone https://gitee.com/yushenliu03/PCHSystem.git

cd PCHSystem
bash Scripts/install.sh    # 首次安装（交互式、幂等）
bash Scripts/update.sh     # 日常更新

完整选项（镜像策略、排错、密钥轮换、禁用前端容器等）见 Scripts/README.md。

手动（Docker Compose）

cp .env.example .env       # 按需改密钥
docker compose up -d       # 起 postgres + backend + web（前端默认由 web 容器托管）
curl http://localhost:8000/healthz

.env 的 COMPOSE_PROFILES=web 默认启用前端 web 容器（nginx 托管 dist + 反代 /api）；清空即禁用，改由自有 nginx 托管。详见 Docs/RUNBOOK.md。

本项目不含 Minecraft 服务端：MCDReforged 由你持有，插件经 HTTP 与后端通信。MCDR 插件本身的部署见 McdrPlugin/README.md。

---

架构

三端分离：后端（FastAPI + PostgreSQL） 是唯一数据拥有者；Web 端（Vue3） 是浏览器后台；游戏端（MCDR 插件） 是纯客户端，不直连数据库，只经 HTTP 与后端通信。

完整架构图、ADR、跨服务流程见 Docs/architecture.md。

---

开发状态

状态	模块
已交付	登录鉴权（Web 账号绑多身份 + 密码登录）、项目协作（在线表格 + 协管员角色）、投影 / 蓝图解析、材料上交、项目归档、通知投递、一键部署
规划中	积分结算、指数称号、Wiki 管理

详见 CHANGELOG.md。

---

开发与贡献

文档	说明
PCHSystem Wiki	使用文档与玩法指引（搭建中）
Docs/RUNBOOK.md	部署 / 排错 / 回滚
CONTRIBUTING.md	分支 / Commit / 发布规范
CLAUDE.md	根规范（红线、命名）
Backend/CLAUDE.md · Frontend/CLAUDE.md · McdrPlugin/CLAUDE.md	各端开发指引

提 PR 前请先读 CONTRIBUTING.md 与 CLAUDE.md §3 红线；涉及 MCDR 的改动须先联网核实 API（根 CLAUDE.md §0 S-1）。

---