farm_service/docs/crop-catalogue-design.md

作物数据与素材独立维护设计

日期：2026-10-26。状态：用户已确认，实施中；本地完成后记录验证证据。

目标与已确认决定

• 作物数值及可维护素材的正式来源迁入 farm_service，不再从农场插件的 legacy 基线生成日常发布数据。
• 用户已明确选择：机器人仅在启动时检查更新。运行中不定时更新， 本次启动选定的版本持续使用到关闭。
• 真寻、NoneBot、AstrBot 共用同一加载实现，沿用已有 Github、Gitea、 farm_service 资源源选择与独立的服务基础地址配置。
• 保留玩家数据库、地块中保存的作物结算快照及旧迁移基线。
• 本轮只完成本地实现、验证和维护说明；提交、推送、部署及安装另行授权。

方案取舍

1. 启动时检查完整资源版本：用户最终选择。可以独立发布作物更新， 同一次机器人运行期间不切换规则，生命周期与缓存管理较简单。
2. 运行中定时更新：用户已改为不采用。需要额外处理交易和渲染任务 跨版本切换、任务取消与长期更新调度。
3. 只迁移维护源、插件固定版本：不采用。更新数值仍需重新发插件。

正式来源与发布产物

• Service 仓库保存可编辑的作物目录、图片源和绘图配置。旧目录中的 202 条作物及现有图片仅作为首次迁出的来源；迁出后不修改旧基线。
• 作物保留有业务意义的字段；移除将旧数据库摘要当成日常维护来源 的依赖。新增数据协议说明、字段校验和维护示例。
• 发布工具由上述来源可复现生成 plants.json、metadata.json 和 assets.zip、land-soils.zip，以及绑定四者的发布清单。字体继续单独维护。
• 清单包含协议版本、发布版本和各文件的大小、SHA256；下载路径固定， 不接受玩家输入路径。每个发布版本存于不可变版本目录，最新清单 仅作为版本发现入口，保留历史版本供旧客户端和回滚使用。
• GitHub/Gitea 从 Service 仓库读取公开文件；Service 提供等价的公开 只读清单及版本文件接口，不复用用户资料接口令牌。
• 发布工具先生成并校验完整版本，最后才更新最新版本指针。 发布后的版本目录不得原地覆盖；修正内容应生成新版本。

插件启动与失败处理

1. 日志初始化后、玩家数据库迁移和业务服务初始化前，读取本地当前版本。
2. 在线检查所选资源源的最新清单，限制大小、超时及 HTTPS 地址格式； 不自动跨源下载，不请求占位 Service 地址。
3. 若版本未变化，复核并复用本地内容；否则下载缺少文件至独立临时目录。
4. 校验协议、大小、SHA256、作物业务字段、唯一编号及名称、展示配置 与目录对应关系、ZIP 成员集合和图片内容。任何一项失败都不切换版本。
5. 校验全部通过后，以不可变目录保存候选版本，原子更新本地当前版本 指针。业务目录、绘图元数据和图片始终取自同一完整版本。
6. 在线检查或下载失败时使用当前已验证缓存；缓存缺失或损坏时使用 随插件生成的初始作物目录与匹配展示配置。初始版本图片仍按已有 外部资源策略加载；完全离线且没有图片缓存时提供文字功能。
7. 本次运行不再次切换目录，不创建更新定时任务。网络操作在后台线程 执行；超时、拒绝原因、采用版本和回退来源写入日志，不记录凭据。

启动前须确认选定目录覆盖现有玩家库使用的作物 ID。若缓存损坏且 初始目录不包含玩家已持有的新作物，应明确拒绝业务初始化并提示恢复 兼容版本；不得清除库存、替换 ID 或伪装成正常启动。空数据目录仍可 通过初始目录离线启动。读取玩家库仅用于兼容性检查，不导出真实数据。

最新清单通过已有发布方 HTTPS 地址获取，摘要用于一致性和损坏检测， 不宣称其可防御发布账号或源站被接管。未知协议版本必须拒绝并回退。

存量兼容与字段约束

• 作物 ID 永不重排、复用或更换含义。新增作物使用从未使用过的新 ID。
• 本轮不支持删除或更名已有作物；发布工具对照前一版本拒绝这类操作。 下架用 isBuy=0，禁止新购买和新播种用 enabled=0，保留旧库存结算。
• 已播种地块继续使用数据库中的不可变作物定义，更新不重写成熟时间、 产量、经验、季数和再生长规则；新播种使用本次启动加载的目录。
• 出售使用当前目录价格，包含更新前已存在的库存。这沿用现有行为， 必须在维护说明中提示调价影响。
• 新版本应保留已有作物的展示资源引用及存量绘制所需阶段图片； 原有缺图占位行为保留，不要求首次迁移凭空补齐历史缺图。
• 回滚采用“发布新的兼容版本恢复旧数值”，保留期间新增的全部 ID 及其图片，必要时禁售或禁播。不能将最新指针直接退回缺少新增作物 的历史版本。客户端对照本地已验证版本拒绝删除和更名，避免旧库存 无法查询或出售。这是实现者根据稳定 ID 约束提出的回滚方案。
• 不执行玩家数据清理、重置、隐式批量迁移或远程管理写入。

代码和 CI 调整

• Service 实现发布文件校验、公开只读分发与可重复构建工具；提供独立 源目录和更新步骤，日常维护不要求旁边存在 Farm 开发仓库。
• Farm 核心继续只处理已校验的离线目录，不增加网络或 Pillow 依赖。
• 共享适配层负责启动下载、完整版本选择和故障回退；渲染器支持传入 同版本元数据，避免继续强制读取插件内固定 metadata.json。
• Farm 保留一套可复现的初始数据产物，提供显式刷新初始版本的工具； CI 校验该版本自身一致性，不访问生产最新数据，不要求相邻 Service 仓库，也不再要求日常目录与旧 plant.db 字节导出一致。
• 旧基线完整性与迁移测试继续独立运行；不能通过刷新基线哈希来放行 新作物。三个框架打包包含共享加载模块及必要初始数据，继续不捆绑 大型 assets.zip 或字体 ZIP。

验收场景

1. 首次迁出作物数值、图片与现有版本一致，旧基线保持原样。
2. 在 Service 正式来源新增作物或调整数值，发布工具生成有效新版本； 不修改 Farm 业务源码或旧基线，重启测试运行实例即可加载。
3. 一次启动只采用一个完整版本；文件混用、摘要错误、非法字段、未知 协议、删除/复用旧 ID 等情况被拒绝，当前缓存不受损。
4. 网络超时、404、资源源不可用时优先复用已验证缓存；无缓存时初始 目录仍能提供文字业务，图片不可用有明确日志。
5. 旧种植快照结算不变，新播种使用新规则，旧库存按当前价格出售。 更新后新增作物已进入库存时，缺少该 ID 的回滚版本会被拒绝； 兼容回滚保留该 ID。缓存丢失且初始目录不兼容时拒绝业务初始化。
6. Service 与 GitHub/Gitea 使用同样的发布内容；历史版本可读取，未知 路径和版本拒绝，用户资料鉴权及字体分发行为保持有效。
7. 三框架包与离线 CI 通过，不依赖真实远端或相邻开发仓库；提供 “编辑—检查—生成—发布—重启生效—回滚”的维护说明。

实施与验证边界

使用 Python 标准库为主的共享下载与缓存，沿用 Rust/Axum 服务结构。 开发测试使用临时目录和人工测试数据，不访问真实玩家库或启动机器人。 覆盖发布生成、HTTP 路由、异常缓存、并发写入、规则快照及三端打包； Rust 执行格式、测试和静态检查，Python 执行针对性与最终离线检查。 真实 GitHub/Gitea 发布、生产下载、Service 部署及宿主消息验证不作为 本地通过的结论，单独列出尚未执行事项。

实施决定

• 用户已确认本设计作为实施与验收依据，采用当前工作区，不提交、合并或推送。
• 实施前重新查询 Comet，返回无可恢复的 active change，未强建额外工作流。
• Service 已迁出独立源并生成初始四文件版本，提供启动校验和公开只读分发； 维护步骤见 catalogue.md。跨端最终验证由实施计划统一记录。