main_plugin_farm/docs/land-rules.md

# 土地配置与地块顺序

`src/farm_core/data/land_rules.json` 按用户提供的 `91.png` 逐行录入。
这是用户选定的参考规则，不标记为已验证的现行官方全量配置。

- 开垦保留图片序号 7～24 的付费条件；红、黑、金土地各保留 1～24。
- 图片金币单位为万，配置中的 `coin_cost` 为乘 10000 后的整数。
- 前 6 块由 `initial_plot_count: 6` 表示，不重复保存空条件记录。
  新用户默认6块；可靠识别为初始3块的旧用户一次性补3块普通空地。
- 开垦时，`expansion.rows.ordinal` 对应补偿完成后的下一实际地块编号。
  土地升级已接入，具体行为见下文。
- 表外序号，以及材料、星钻替代支付、冷却和额外解锁条件没有在图中
  给出。不能默认免费、默认通过，或套用最后一行。24 不是土地总上限。
- 已提供“开垦”（每次1块）和“开垦 条件”（查询等级及费用）。
  等级检查、扣币及新增空地在同一事务内完成，重放同消息不重复扣款。
  目前配置覆盖7～24号，25号起明确提示规则未配置，不扣币。

## 土地升级

- `土地升级 1 条件` 只查询1号地下一等级的条件；`土地升级 1` 扣费升级。
  地块编号来自“地块编号”，支持各平台共用命令。
- 普通→红→黑→金，逐级升级。每种目标等级的费用序号为：
  已达到该等级或更高等级的地块数加1，不等于地块编号。
  升为更高等级不会使低等级费用重新降低；表外序号拒绝，不猜测费用。
- 红土地增产10%，黑土地增产20%，金土地增产28%、经验加成28%。
  黑、金土地开始新一季时，生长时间取基础时长的80%，向上取整到秒。
  沿用旧实现加成，不叠加到原加成上；普通地的新账号规则不变。
- 升级使正在生长的作物当季立即成熟，不发放收获物、不增加收获次数。
  多季作物收获后才进入下一季。先结算升级时刻已发生的虫害，并冻结
  当前虫数对应的减产；不清除已经偷取的数量或偷取记录。
- 已成熟作物保持成熟，不恢复虫害损失；枯萎的是作物而非土地，
  升级不会使枯萎作物复活，仍需铲除。空地只改变土地等级。
- 扣币、土地加成、当前季成熟和操作回执在同一SQLite事务提交。
  同一消息重复处理返回原收据；等级不足、余额不足或中途失败全部回滚。
  不同消息各执行一次升级，因此不要重复发送不同的升级消息。
- schema v5 为地块增加land_level；v1～v4按顺序事务迁移。
  旧版导入账号从已保存的legacy_rows.userSoil恢复明确等级；
  没有旧版记录的地块默认普通，不按加成猜等级，不改资产与历史加成。
  原始记录非法时中止并回滚迁移，保留旧库。
- 三种升级土地图从legacy原样导出为包内land-soils.zip，约57KiB。
  保持既有外部assets.zip的内容、摘要和下载来源不变；绘图和底图缓存
  包含土地等级，升级后不会复用普通地旧图。

实现和验证使用临时构造玩家；未迁移生产数据、部署或重启机器人。

## 新用户注册

注册事务创建 1～6 号空地，初始农场币仍为 500。重复注册不额外发地。
不重编号已有地块。旧库迁入用户及首次成功注册回执未记录plot_count
或记录为3的用户，在首次业务访问时一次性追加3块普通空地，保留已付费
开垦成果：3→6、5→8、8→11。首次注册记录为6的用户不重复赠地。
补偿与版本标识保存在operations中，重试、并发及重启不重复发放。
来源不明、地块编号不连续/数量异常或补后超过当前30位置时明确报错、
保持原状，不截断、不折现，也不标记已补偿；管理员修复后可重试。
已迁移及后续迁入用户都通过共享服务处理，不直接改动旧farm.db。

## 绘图编号顺序

沿原有五条斜排的坐标方向，前两排交错推进，后续逐排推进：

```text
 1   3   5   7   9  11
 2   4   6   8  10  12
13  14  15  16  17  18
19  20  21  22  23  24
25  26  27  28  29  30
```

前 6 块地形成两排、每排 3 块；前 12 块完成后，13 号起按单排推进。
`metadata.json` 的 `positions[slot - 1]` 是统一的绘图映射，土地、作物、
虫子和详情中的地块标注都使用它。地形坐标不变，只重排前 12 项。
已有账号的同一 `slot` 保留原作物和资产，展示位置随此映射调整。

## 用户查询入口

真寻接入新增「地块编号」，使用统一图片质量配置。它复用正式渲染器，
按当前账号快照标注全部 30 个位置：浅色编号为已开垦，绿色为待开垦。
图片附带编号顺序和「农场详述」入口说明，并保留当前季节、作物及头像。
该查询无需消息写入标识，不更改作物、土地或资产。缺少字体时返回文字清单。

「农场帮助」包含该入口；首次注册成功回复显示本次实际初始地块数并提示
发送「地块编号」。重复注册只提示查询入口，不声称再次获得土地。
日常「我的农场」仍不显示编号，编号图与普通图使用不同的成图缓存键。