5.4 KiB
业务逻辑与一致性设计
状态：以下是建议约束。涉及用户资产归属、玩法与跨实例互通的选择， 需按 07-decisions.md 确认后进入正式规格。
身份与农场归属
框架（真寻/NoneBot/AstrBot）不等于消息平台（QQ/Telegram 等）。 玩家至少需要 deployment_id、realm_id、platform、platform_user_id； platform_user_id 保存字符串，禁止跨平台按相同数字自动认定同一人。
建议独立部署默认独立数据，realm 可配置群内或部署内共享。 各协议暴露的同平台 ID 也未必同义，官方 QQ 的开放标识与 OneBot 账号不能自动合并。迁移需要明确来源命名空间、人工确认映射与审计。
双人操作如偷菜必须确定双方处于同一允许交互的 realm， 检查自己偷自己、跨群目标、无农场目标和权限。@对象解析留在接入层。
货币与库存
- 内部货币、数量使用整数；设置合理上限并检查乘法后的范围。
- 增量和设置新值采用不同接口名称；应用层不能直接写余额缓存。
- 扣款使用数据库条件更新，例如余额足够才扣减，检查实际影响行数。
- 不足返回明确失败；不能静默把负余额截成零后继续发货。
- 每次资产变动记录 operation_id、actor、realm、币种、增量、原因、 关联物品和提交时间；日志不代替可查询的账本。
- 已锁定作物在单项出售、批量出售、交易与其他消耗入口采用一致规则。
- 所有数量入口测试 0、负数、缺省、超大值、全部数量与库存不足； 命令层的默认参数不得被误当成任意合法业务值。
购买与出售
购买：读取有效目录→校验数量/等级→同一事务中校验和扣款→增加种子 →写操作流水→提交→生成展示数据。任一步失败整体回滚。
出售：按明确数量计算可出售库存→同一事务中检查锁定和库存版本 →扣库存→只增加本次收益→流水→提交。返回实际成交数量与新余额。 网络发送失败不回滚已成交交易；重试同一 operation_id 返回原结果。
播种与收获
播种：空地校验、种子消耗、星级选择、作物实例创建在同一事务中。 土地收益与生长速度采用已确认公式，记录规则或目录版本， 不能让资源更新悄悄改变已播种作物的结算契约。
收获：每块地独立计算产量和经验，再求和；不对累计经验反复加成。 每轮作物有可辨识的 cycle_id/harvest_index，防止重试和并发重复领奖。 作物入仓、经验增加、收获次数、下一成熟时间或枯萎状态、偷取记录 的结算必须在同一业务事务内完成。精确的事务批次由全收获与部分成功 策略决定，先定义用户可见结果，不能任意留半完成状态。
未种植、生长中、成熟、枯萎是明确状态；不要用多组互相冲突的布尔值 表示同一阶段。除草、虫害、施肥等独立属性另行建模。
签到、升级与确认
签到采用明确业务时区，(realm、player、business_date) 唯一； 签到记录、奖励发放、累计奖励领取标记在同一事务内。 “已签到”与“新签到成功”分开返回，防止重复展示发奖。 补签与连续签到规则分别定义，不从字段名猜测。
开垦和土地升级在用户确认后重新读取余额与地块状态，重新校验条件。 确认凭据绑定发起人、会话、动作、参数、过期时间和一次性标识； 不能把任何消息里的“是”当作任意待办操作的确认。 升级使作物成熟这一旧行为需明确保留或调整。
幂等与并发
operation_id 由框架事件标识与部署作用域产生；没有稳定事件标识时， 用已持久化的交互操作标识，而不是每次重试生成新的随机 ID。 同一操作不同参数应拒绝，不能错误复用第一次结果。
唯一约束、条件更新或状态版本是最终防线。 进程内锁只作辅助，跨进程不能共享这把锁。 单实例 SQLite 的连接/事务应由一个明确管理者协调； BEGIN 的锁等待、busy timeout、取消回滚、事务嵌套和连接关闭都要测试。 WAL 是部署选项，不能解决错误的业务事务边界。
外部金币兑换
真寻金币和本地农场币位于不同存储，不能承诺一个本地 SQLite 事务 同时回滚两边。先核对外部钱包是否支持 operation_id、条件扣款、 查询和退款；使用持久化兑换单与可重试状态机协调。 无法确认结果时进入待对账状态，禁止直接重复扣款或盲目发币。
普通 NoneBot、AstrBot 默认只支持内部农场货币； 外部经济系统通过能力配置接入，不导入真寻代码。 兑换比例、手续费、舍入、最小单位和失败恢复写入明确规格。
时间、事件与展示
保存 UTC 时间戳，业务日期按配置时区计算；日志记录时区语义。 时钟可注入，覆盖午夜、闰日、月切换和重启后的结算。
核心状态改变必须由事务内显式步骤完成。 提交后的消息、图片、统计等副作用失败不撤销已提交业务； 需要可靠重试时使用操作结果或持久化任务。事件槽捕获异常不能把 必需的资产更新失败隐藏成成功。首期不必新增通用事件总线。
展示读取业务结果，不在绘图过程中更新余额或土地； 图片失败回退文本，不重复执行业务。