更新日志

原文件：PCHSystem/CHANGELOG.md，每次构建自动拉取。

本项目所有显著变更记录于此文件。

格式遵循 Keep a Changelog 1.1.0，版本号遵循 Semantic Versioning 2.0.0。三端（后端 · 游戏端 · 前端）各自独立维护版本号。

阅读约定：[Unreleased] 段面向开发者，可含实现细节与提交引用；已发版段落（vX.Y.Z）面向使用者，只讲「能感知到什么变化」，用自然语言、尽量精简。

[Unreleased]

Added

暂无

Changed

暂无

Fixed

暂无

Security

暂无

[backend-v0.9.0] - 2026-07-28

施工进度上报层补齐「加入施工」机制、玩家可见上报事件流水、按材料封顶，并修复一批上报健壮性问题。

Added

加入施工机制：玩家可显式加入某项目的施工（Web Me 页 + 游戏内 !!PCH construction join）；备货/施工阶段认领与上交时自动加入该项目；同一 Web 账号同时最多活跃加入 1 个项目（admin 开关 enforce_single_construction，DB 部分唯一索引兜底；仅约束默认追踪器与 join 流程，/report API 仍允许多项目并发上报）。新增端点 GET /me/construction、POST /me/join、POST /me/switch、POST /me/leave、POST /active-by-uuids（迁移 0020 sheets.constructing_at + 0021 participants）。
上报事件流水：新增 GET /me/report-events——玩家查看本人完整上报事件（accepted + 全部 skip 原因：无活跃源 / 其他源上报 / 不在清单 / 已达上限 / 未归因等），让「为何我的上报被拒」可见（迁移 0023 report_events）。
按材料封顶：每种材料跨账号合计净放置不得超过需求总量，满额后整条或超额部分 skip 并回执，避免超量计入（迁移 0022 回填历史超额）。
批量提交端点：POST /sheets/{id}/submit-batch——第三方集成方传材料清单，后端按行 mode 自动分发 delivery/contribute 并逐行回执（双鉴权，决策逻辑为后端单一权威实现）。
施工进度上报层（迭代 1-3）：POST /v1/construction/report 等 11 端点——施工方上报 constructing 期各方块净放置，按 (项目×账号×方块) 聚合，归档喂给积分层；严格单源、归因三分支、切源两端点、admin 5+1 开关、服务端 mod 白名单、时序快照、方块清单校验、材料完成度与休眠源查询。

Fixed

上报写入健壮性（CR）：事件/时序快照写入包 SAVEPOINT，失败不再污染主事务致整次上报回滚；join_construction 并发兜底改有界重试（防无限递归）；Participant.updated_at 退出/切换时显式刷新；/me/switch 并发冲突返回 409 而非 500。

[frontend-v0.9.0] - 2026-07-28

施工进度图表时间轴与起点修复，新增「加入施工」入口与「我的上报历史」面板。

Added

图表时间轴修复：折线图 x 轴范围改为「施工开始 → 当前时间/归档时间」；折线从 y=0 升起（在施工开始处补 0 锚点），不再悬空于首个上报点。
加入施工入口：Me 页「当前施工项目」卡片（展示加入的项目 + 退出）；项目详情页「加入施工 / 切换到此项目」按钮。
我的上报历史：Me 页面板展示本人上报事件流水（accepted 绿、被拒红并标原因）。
施工管理模块（迭代 1-3）：admin 施工管理面板 + 项目详情「施工进度」tab（折线/柱/饼图，ECharts，具名 slot 自定义扩展点）+ Me「施工上报源」控件（server/local 切换 + 活跃源 + 历史 + 休眠源一键切回）+ 时序折线前向填充 + 材料完成度分页排序 + 数量单位统一显示。

Changed

管理员面板重构（迭代 3）：服务端 mod 由单全局开关改为逐源卡片启停；dev 代理 localhost:8000 → 127.0.0.1:8000（IPv6 歧义修复）。

[pch_system-v0.9.0] - 2026-07-29

服务端默认施工进度追踪器 + 加入/退出施工命令。

Added

施工进度追踪器：默认开启，自动读取在线玩家 stats 差值上报施工放置贡献（约 30 秒一次），无需客户端模组。
施工命令：!!PCH construction join [编号] / leave / current / status——加入、退出、查看当前项目与追踪器状态。
配置项：construction_enabled（总开关，默认开）、construction_flush_interval_seconds、world_stats_dir、construction_max_batch、construction_track_breaking（挖掘，预留关）。

Changed

!!submit 改走后端批量端点：逐行裁决由后端统一处理，回执观感不变。

Fixed

!!submit 回执对未知动作逐行展示，不再隐式折叠。

Notes

仅统计方块放置，不含挖掘。
多项目同时施工需 join 指定项目，或 Web 端切客户端模组精确上报。

[backend-v0.8.2] - 2026-07-26

补齐协管员授予联想的昵称显示与双向匹配。

Fixed

协管员联想完善（#41）：拥有者添加协管员时的联想下拉现在返回昵称（display_name）、可按昵称前缀搜索，并过滤未绑定网页账号的玩家（授予未绑玩家必 422，联想无意义）。

[frontend-v0.8.2] - 2026-07-26

修复登录会话过早失效；完善协管员联想与会话续签健壮性。

Fixed

登录会话不再过早失效（#42）：账号密码登录后数小时即被踢回登录页的问题已修复——访问令牌过期后前端自动续签并重放原请求，会话滑动保持 7 天，全程无感。
协管员联想完善（#41）：添加协管员的输入框主显昵称、可按昵称搜索，与游戏名不同时副显游戏名；未绑定网页账号的玩家不再出现在联想中。
会话续签健壮性：多个请求同时遇到令牌过期时不再重复跳转登录页；续签后请求仍被拒绝时不再无限重试。

[pch_system-v0.8.2] - 2026-07-25

重要更新（部署脚本热修）：修复 .env 已含全部所需键时 Scripts/update.sh 拉取新代码后静默退出、跳过后续部署步骤的问题。此前已运行过更新脚本但疑似未跑完的实例，请按下方「升级指引」重跑一次。

Fixed

更新脚本半途中断：当 .env 已补齐所有所需键时，Scripts/update.sh 会在拉取新版代码后立即静默退出，跳过容器重建、数据库迁移、前端构建与部署记录刷新，实例卡在「代码已新版、容器与迁移仍停留旧版」的半途中断状态。现已修复，更新可一次跑完全流程。
版本号元数据：McdrPlugin/mcdreforged.plugin.json 的 version 由 0.8.1 补齐为 0.8.2（与发版线一致）；archive_name: pch_system-v{version} 按 plugin.json 的 version 打包，漏改会使 v0.8.2 的 .mcdr 产物误命名（首次发版曾产出 pch_system-v0.8.1.mcdr）。

升级指引

已处于半途中断状态的实例（.env 无缺键，上一轮卡在拉取代码之后）：不能直接重跑 bash Scripts/update.sh——当前磁盘上的 update.sh 仍是旧的有 bug 版本（修复在 v0.8.2 才进入），bash 启动时已把有 bug 的 ensure_env_keys_update 读入内存，do_checkout 改磁盘不会重载内存函数，重跑仍会在同一处中断；且即便先手动切到 v0.8.2 再无参重跑，fetch_and_compare 会因工作树 HEAD 已等于最新 tag 而 exit 0，跳过迁移与重建。

正确做法是先把工作树切到 v0.8.2（让 bash 读到修复版脚本），再用 --no-sync 跳过 fetch/checkout、直接补齐后续步骤：
Terminal window
```
git fetch --all --tags
git checkout pch_system-v0.8.2
bash Scripts/update.sh --no-sync
```
--no-sync 用部署记录（仍停在中断前的旧版本）作 diff 基准，正确识别「代码已新版、容器与迁移仍滞后」，按需执行容器重建 / 数据库迁移 / 前端构建 / MCDR 更新，并在 verify_and_summary 把部署记录推进到 v0.8.2。若工作区存在本地改动，脚本自带的 dirty 保护会先提示并拒绝运行，按提示处理后再重跑即可。

[backend-v0.8.1] - 2026-07-25

元数据补丁：v0.8.0 发版时 pyproject.toml 的 version 字段漏改（仍为 0.7.0），本次补齐到当前发版线。无代码 / 行为变更。

Fixed

版本号元数据：pyproject.toml（及 /info 返回的 version）由 0.7.0 更正为 0.8.1，与实际发版对齐。

[frontend-v0.8.1] - 2026-07-25

元数据补丁：v0.8.0 发版时 package.json / package-lock.json 的 version 字段漏改（仍为 0.7.0），本次补齐到当前发版线。无代码 / 行为变更。

Fixed

版本号元数据：package.json 与 package-lock.json 由 0.7.0 更正为 0.8.1，与实际发版对齐。

[backend-v0.8.0] - 2026-07-25

解析端点合并为单一批量端点。破坏性变更：删除旧的单文件解析端点。

Added

批量解析：一次上传多个投影 / 蓝图文件（可混合 .litematic 与 .nbt），每个文件独立预览，单文件解析失败不影响整批。

Changed

BREAKING（解析端点合并）：删除 POST /parsing/litematic 与 POST /parsing/nbt，统一由 POST /parsing/batch 承载（单文件等价于批量 1 个）。解析失败不再整请求报错，改为每文件独立返回成功 / 失败状态。

[frontend-v0.8.0] - 2026-07-25

解析页升级为批量入口，修复登录链路三处问题。破坏性变更：移除旧的单文件解析页。

Added

批量解析页：上传多个投影 / 蓝图，为每文件设建造份数（整数倍数），可调整源头数量；系统跨文件按物品汇总成一份材料清单，一次生成一张项目表。

Changed

BREAKING：移除单文件解析页，统一由新的批量解析页承载（单文件等价于批量 1 个）。

Fixed

登录链路修复：
- 登录后的欢迎语正确显示账号昵称 / 用户名，不再显示空白。
- 在登录 / 注册页时 token 过期不再清空表单并闪烁跳转。
- 后端不可用时不再误报「登录失败」，只提示网络异常并引导重试。

[pch_system-v0.8.1] - 2026-07-25

补齐项目阶段流转通知缺口（issue #4），参与者不再漏知关键进度。无破坏性变更。

Added

项目阶段流转通知：项目进入施工阶段或被归档时，全体参与者（拥有者、协管员、材料认领人、进度贡献者）都会收到一条游戏内通知；触发者本人不再收到自己触发的流转通知。

[backend-v0.7.0] - 2026-07-20

身份主锚升级为 Web 账号（可绑多个游戏身份），项目协作与协管员机制改为账号级，登录链路安全加固。破坏性变更：需跑数据库迁移，现有登录会话全部失效。

Added

Web 账号绑定多个游戏身份：一个账号可绑多个 Minecraft 身份，积分与贡献按账号归并。新增密码登录、临时账号转永久、双向绑定短码。
项目协管员角色：拥有者可授予其他玩家协管员身份，分担日常协作（增删改材料、认领、交付、推进施工），但无权删除 / 改名 / 管理协管员 / 归档；按账号生效，可自行卸任。
项目按账号统一：同一玩家不同身份建的项目、认领的行可互通操作；贡献按账号归并；支持自定义昵称（三端显示名主源）。
登录安全加固：密码登录双维度限频（IP + 账号）防撞库；token 校验身份归属，账号迁移后旧 token 立即失效。

Fixed

归档项目执行写操作返回「项目已归档，只读」，不再报 500（issue #7）。
注册撞用户名并发冲突改为返回已存在提示，不再报 500。

[pch_system-v0.8.0] - 2026-07-20

适配身份主锚升级与项目协管员机制，部署脚本健壮性增强。破坏性变更：所有玩家需重新 !!PCH login 登录。

Added

!!PCH bind 绑定多身份：游戏内出短码到网页端输入，或反向；一个账号可绑多个身份，换服 / 改名后积分与贡献不丢。
协管员命令：!!PCH sheet manager <编号> add|remove|list <玩家名>；协管员可见常规操作按钮，不见删除 / 改名 / 归档。
同账号不同身份建的项目、认领的行可互相操作。

Fixed

对归档项目操作显示「项目已归档，只读」，不再报服务暂不可用；一键提交整体短路不刷屏（issue #7）。

运维（部署脚本）

重装 / 更新自动补全 .env 新增项；撞 web 端口自动清理残留容器并询问，不再异常退出。

[frontend-v0.7.0] - 2026-07-20

适配身份主锚升级与协管员机制，新增身份管理页面。

Added

身份管理：新增密码登录、注册（临时转永久）、绑定确认、身份列表页；网页端可发起绑定或追加身份。
个人中心升级：展示账号 + 绑定的所有身份；临时账号显示升级引导；可设昵称。
协管员管理面板：拥有者可在详情页增删协管员（玩家名联想），所有人可见列表。
同账号多身份建的项目、认领的行可互通操作。

Fixed

[pch_system-v0.7.1] - 2026-07-14

更新脚本支持 mac 修复python 依赖无法正确解读的问题

Added

macOS 部署支持：一键安装 / 更新脚本（install.sh / update.sh）现可在 macOS 上运行（此前仅支持 Linux），自动适配 Docker Desktop 与 BSD 版工具差异。

Fixed

从 catalogue 安装时自动装依赖：经 !!MCDR plugin install 或 PluginCatalogue 安装本插件时，现在会正确一并安装 Python 依赖；此前因依赖清单未放在插件根，依赖不会被自动安装。

Docs

更新 README 的表现效果

[pch_system-v0.7.0] - 2026-07-12

插件 id 由 htcmc_auth 改为 pch_system（与项目名一致），首个以新 id 发布的正式版本；同步改进项目部署与发布流程。

Changed

插件 id 改名 htcmc_auth → pch_system：插件不止登录鉴权，还含材料协作 / 一键提交 / 通知。已部署实例需迁移：删旧 plugins/htcmc_auth/（否则双注册 !!PCH 冲突），config/htcmc_auth/ 搬到 config/pch_system/；Scripts/update.sh 自动处理。

Added

部署与发布流程改进：tag 驱动半自动发布（push pch_system-v* → CI 构建 .mcdr + 草稿 Release）；前端默认 docker compose 容器托管（nginx + /api 反代，COMPOSE_PROFILES=web 可关）；端口可配（*_PORT）+ 镜像构建走国内源加速；update.sh 按变更智能重建 web 镜像。

Fixed

update.sh 不再误报「需重启 MCDR」：plugin.json 字段变更统一提示 !!MCDR plugin reload（reload 重校依赖，无需重启）。
自检「部署」链接更精准：!!PCH status 后端未配置提示改为指向 RUNBOOK 部署手册。

[htcmc_auth-v0.6.1] - 2026-07-11

Fixed

一键提交回执进一步降噪：已备齐 / 进度已满的材料行不再逐行占用「跳过」段，改为折叠成末尾一行计数；回执只保留你本次实际还能操作的行（认领未完成、需补货等），看一眼就知道还要做什么，不再被早已完成的行刷屏。

[frontend-v0.6.1] - 2026-07-11

Fixed

打开大项目（上百行）更快：首屏渲染从约 2.6s 降到约 1.2s；二次进入同一项目命中本地缓存几乎瞬开，不再每次等加载。
拖拽调整过的列宽在刷新或自动刷新后不再被重置。

[htcmc_auth-v0.6.0] - 2026-07-11

Added

一键提交快捷命令：新增 !!submit，直接重开上次查看的项目并扫描背包一次性上交；!!submit <编号> 可指定项目。与 !!PCH sheet submit 等效。

Fixed

一键提交回执精简：提交后只逐行显示与你相关的跳过（你认领的、已备齐 / 无需求的），其余跳过项折叠为末尾一行计数，不再被无关行刷屏淹没。

[backend-v0.6.0] - 2026-07-10

Added

子物品嵌套行：材料支持挂子件（如「机械臂」配「齿轮×2」），系统按单位用量自动算出子件需求；认领或交付父行时自动级联其所有子行。单位用量支持小数（如 0.5）。
材料行智能排序：打开项目时，你认领的、你参与的行排前面，最缺的数量优先；CSV 导出仍是自然序。
材料行搜索：项目详情可按物品名 / 注册名过滤材料行。

Fixed

修改材料名不再误建重复行；新建同名材料会被拦截并提示。
调整子件用量导致需求超过已交量时，行状态不再卡在「已完成」，会正确回退为「进行中」。
删除带子件的材料行时，认领人 / 贡献者会收到子件被删的通知。

[frontend-v0.6.0] - 2026-07-10

Added

子物品树状展示：材料行按父子关系分组显示，子件缩进排列，可在行内直接增删与编辑子件。

Fixed

编辑材料保存时改名生效、不再重复建行。
打开上百行的大项目时不再每秒卡顿，自动刷新不会丢失正在编辑的草稿。
添加子物品成功后弹窗正常关闭。

[htcmc_auth-v0.5.0] - 2026-07-10

Added

子物品命令：新增 !!PCH sheet addsub / delsub / setsub 管理子物品；查看项目时子件缩进显示，父行标注子件数量。
项目分页查看：!!PCH sheet view 每页 30 行，避免超出聊天框截断；支持 -p <页码> 翻页。
项目关键词搜索：!!PCH sheet view <id> -s <关键词> 按物品名 / 注册名过滤，底栏常驻「搜索」按钮。

Changed

材料数量显示改为友好单位（个 / 组 / 盒），如 1728 个显示为「1 盒」，与 Web 端一致。
行显示精简：进度行显示「当前/需求」，锁定行只显示需求值。

Fixed

修复 addsub / setsub 指定 progress 模式时实际仍建成 lock 行的问题（v0.3.0 起遗留）。

[backend-v0.5.0] - 2026-07-07

Added

解析 Create 蓝图：上传 .nbt 蓝图文件（机械动力模组 / 原版结构），系统自动解析材料清单并翻译成中文名，预览与生成项目流程同投影文件。
（运维）一键安装 / 更新脚本：首次部署一条命令完成（检测安装 Docker、国内网络自动选镜像、生成配置、起服务 + 跑数据库迁移、构建前端、装好游戏端插件并填好令牌）；后续更新按代码改动智能决定重建哪些容器、迁移前自动备份数据库、校验游戏端令牌一致性、拒绝在未提交改动上运行。

[frontend-v0.5.0] - 2026-07-07

Added

解析 Create 蓝图：投影 / 蓝图上传页新增 .nbt 文件支持，按扩展名自动选择解析方式，预览与生成项目流程不变。

[backend-v0.4.1] - 2026-07-07

Fixed

修复上传 Create（机械动力）蓝图经投影 mod 转出的 .litematic 时解析失败、整份材料清单被丢弃的问题；解析失败时会提示可读的中文原因（#8）。

[backend-v0.4.0] - 2026-07-06

Added

项目归档自动生成贡献占比饼图，直观展示每位参与者贡献了多少材料。
归档文件改为按项目独立文件夹存放（说明文档 + 贡献图集中在一起），便于查找。
支持记住玩家上次打开的项目，供游戏端「快速重开」使用。
项目列表可按请求把自己参与的项目排在前面。
（运维）wiki 内容同步改为经 git 仓库双向同步，默认关闭，需配置 WIKI_GIT_* 环境变量开启。

[htcmc_auth-v0.4.0] - 2026-07-06

Added

一键提交：查看项目时点按钮即可扫描整个背包，把匹配的材料一次性上交（支持潜影盒内的物品）。
快速重开上次项目：直接输入 !!sheet 重开上次查看的项目，或 !!sheet <编号> 打开指定项目；!!PCH sheet last 同效。
更聪明的项目列表：默认只显示进行中的项目；自己参与的（作为创建者 / 认领人 / 贡献者）排在最前；每行标注所处阶段（收集中 / 建造中）。
列表筛选简写旗标：!!sheet list 支持 -m(我的) / -c(收集中) / -t(建造中) / -a(已归档) / -l(全部)，可组合如 -ma。
拥有者改物品 ID：项目拥有者可在行上点「改ID」直接修改材料对应的游戏物品（缺省读取手持物品）。
查看界面美化：物品列表新增分节标题，按钮右对齐、底栏按钮居中，显示更整齐。

Fixed

空项目（无任何物品行）不再错误显示「一键提交」按钮，并补回物品列表的分节标题。

[frontend-v0.4.0] - 2026-07-06

Added

项目归档预览中显示贡献占比图，与后端生成的饼图同步。

[backend-v0.3.0] - 2026-07-03

Added

投影文件一键生成材料清单：上传 .litematic 投影文件，系统自动解析其中的方块并翻译成中文名，一键生成项目材料清单（支持原版与 Create 模组物品）。
多人上报进度：材料行支持多人累计上交，不再限定单人认领。
统一通知系统：认领 / 交付 / 打回 / 上交等事件会自动生成通知，游戏端玩家上线即可收到。
游戏端代玩家操作：游戏端的命令可以代表玩家执行写操作（如提交材料），权限与 Web 端完全一致。

[mcdr-v0.3.0] - 2026-07-03

Added

!!PCH sheet 命令树：游戏内全套项目管理命令（查看 / 认领 / 交付 / 打回 / 解除 / 上交等共 14 条）。
通知轮询：玩家在线时自动接收通知，离线期间的通知在上线时补发。
可点击的聊天按钮：项目查看界面里的操作改成可点击按钮，点一下自动填好对应命令。

Changed

主菜单视觉重做：!!PCH 帮助菜单重新设计，命令分类清晰、可点击。

Fixed

修复命令参数被强制要求输入导致「未知命令」、通知文案缺项目名、轮询间隔配置漂移等问题。

[frontend-v0.3.0] - 2026-07-03

Added

投影上传页：浏览器端上传 .litematic，预览解析结果并勾选生成项目。
自动刷新：项目列表与详情页自动轮询刷新，正在编辑的草稿不会丢失。
进度上交 / 调整：上报式材料的上交入口，以及拥有者调整进度的入口。

Fixed

修复拥有者在自己项目里看到重复按钮的问题。

[v0.2.0] - 2026-07-02

Added

材料清单协作：材料行支持认领 / 标记备齐 / 交付 / 打回 / 解除，Web 端与游戏端对等操作；列表与详情显示认领人的游戏名。

[v0.1.0] - 2026-07-02

首个可用版本，三端骨架与核心登录链路打通。

Added

后端：FastAPI + PostgreSQL 骨架 + 数据库迁移机制；登录鉴权链路（游戏端 !!PCH login → 浏览器兑换进入后台）；材料清单基础增删改查与 CSV 导出。
游戏端（MCDR 插件）：插件骨架 + !!PCH login 登录命令（可点击链接）。
前端：Vue3 后台骨架 + 登录兑换页 / 个人信息页 / 材料清单表格（增删改查）。
工程：根规范（红线 R-1~R-12 / 命名 / 分布式文档体系）+ Docker Compose 部署 + 集成测试服。

版本化策略

三端各自独立 SemVer，按 CONTRIBUTING.md §4 维护。

组件	tag 约定
后端	`backend-vX.Y.Z`
游戏端（MCDR 插件）+ 项目级部署脚本	`pch_system-vX.Y.Z`（plugin id 由 `htcmc_auth` 改为 `pch_system`，与 `mcdreforged.plugin.json` id / 文件夹 / 内部包名一致；历史 tag `htcmc_auth-v` / `mcdr-v0.3.0` 保留不重打，均符合 MCDR PluginCatalogue 合法格式）。该 tag 同时承载 `Scripts/` 部署脚本（install.sh / update.sh）与跨端基础设施变更*——使用者主要通过部署脚本统一拉取三端更新，故项目级工具链修复也归入此版本线
前端	`frontend-vX.Y.Z`

发版流程：

把 [Unreleased] 段浓缩为面向使用者的自然语言（去掉实现细节与提交哈希）。
固化为 ## [<组件>-vX.Y.Z] - YYYY-MM-DD 段，置顶于已发版段落上方。
重置 [Unreleased] 段为空占位。
打对应 tag。

MCDR tag 改名背景见 Docs/Reports/mcdr-publishing-strategy.md。