经营养成一期实施切片 v1 · 玩法设计

状态：implementation_in_progress

日期：2026-07-30

上位真源：docs/design/backlog/gameplay/经营养成与生产玩法总纲-v1.md

用户拍板：按总纲推荐版推进

本期目标：在现有客栈经营中跑通“天气预报 -> 种子采购 -> 员工种植 -> 按日生长 -> 收获入后厨料仓 -> 做菜消耗 -> 获得经营收入”的第一条生产闭环。

当前进度：F1 数据契约 verified；F2 纯逻辑与回归 verified；F3 存档接线 verified；F4 事务控制器 verified；F5 后院 UI 与 F6 后厨闭环已实现、集中验收暂缓；F7 pending

1. 一句话边界

本期只证明种植能真实反哺后厨经营，不提前实现居民求助、野外采集、复杂合成、背包升级和酿酒。

2. 当前代码真值

2.1 关键命名区分

backyardPlots：现有后院功能区列表，不改名、不改语义。
farmingPlots：本期新增的农田运行态，记录播种、生长和成熟。
kitchenPantry：后厨料仓，是农作物收获后的唯一一期库存真源。

禁止因为中文都叫“地块”而把 backyardPlots 与 farmingPlots 合并。

3. 已拍板规则

使用员工体力，不增加全局玩家体力。
种植入口放在后院。
天气按游戏日确定，首屏显示今日和未来三日预报。
成熟作物不会因玩家离线而枯死。
收获物进入后厨料仓，不占现有 25 格装备行囊。
一期技能归属为本周目共享“种植技艺”，员工特长只做修正。
一期只做青菜和高粱两种作物、两块基础农田。
一期不实现酿酒；高粱先作为后厨细料进入现有料仓，酿酒期再复用该资源来源。

4. 玩家闭环

后院查看今日天气与三日预报
  -> 在后院购买青菜种子或高粱种子
  -> 选择空农田、作物和一名在店员工
  -> 校验铜钱、种子、时段与员工体力
  -> 播种并扣除成本
  -> 游戏日推进，农田自动生长
  -> 天气、季节与种植技艺修正成熟日和收获量
  -> 玩家收获，产物写入 kitchenPantry
  -> 后厨使用自产食材做菜
  -> 熟食进入现有售卖链并产生铜钱

5. 一期数据契约

以下为职责草案，最终字段可以在不改变语义的前提下微调。

type CropId = 'leafy_greens' | 'sorghum'

type FarmingPlotPhase = 'empty' | 'growing' | 'ready'

interface FarmingPlotState {
  id: 'plot_1' | 'plot_2'
  phase: FarmingPlotPhase
  cropId: CropId | null
  plantedDay: number | null
  readyDay: number | null
  assignedStaffId: StaffId | null
  forecastYield: number
}

interface FarmingSkillState {
  level: number
  experience: number
}

interface FarmingRuntimeState {
  plots: FarmingPlotState[]
  seedStock: Record<CropId, number>
  skill: FarmingSkillState
}

5.1 作物静态配置

interface CropDefinition {
  id: CropId
  name: string
  seedName: string
  seedPrice: number
  growDays: number
  baseYield: number
  pantryItemId: string
  seasonWeights: Record<SolarTermSeason, number>
  staminaCost: {
    plant: number
    harvest: number
  }
}

静态数据层不放生长、产量或购买函数。

5.2 一期建议值

| 作物 | 种子价 | 生长日 | 基础产量 | 料仓去向 | 播种 / 收获体力 | | :--- | ---: | ---: | ---: | :--- | :--- | | 青菜 | 18 文 | 2 日 | 3 份 | item_rough_ingredient | 4 / 3 | | 高粱 | 32 文 | 4 日 | 2 份 | item_fine_ingredient | 5 / 4 |

这些是纵切片验证值，不是最终经济平衡签字。

6. 天气和技能规则

6.1 一期天气影响

| 天气 | 农田影响 | | :--- | :--- | | 晴朗 / 多云 | 无修正 | | 细雨 | 本批收获 +1 | | 暴雨 | 本批收获 -1，最低仍为 1 | | 酷暑 | 成熟日 +1 | | 落雪 | 成熟日 +1 | | 大风 / 晨雾 | 一期无数值影响，只显示提示 |

天气修正以播种日至成熟日前的天气快照计算，必须确定性可复算。不得在每日渲染时重新掷随机数。

6.2 种植技艺

初始等级 1，经验 0。
播种成功获得少量经验，收获获得主要经验。
1 级：无加成。
2 级：每批收获 +1。
3 级：播种和收获体力消耗各 -1，最低为 1。
一期等级上限 3。

技艺升级只影响后续动作和批次，不回溯修改已经生成的成熟批次。

7. 状态机

empty
  -- plant --> growing
growing
  -- currentDay >= readyDay --> ready
ready
  -- harvest --> empty

7.1 播种事务

播种必须一次性校验并提交：

地块为空。
当前为允许后院生产的时段。
种子库存至少 1。
员工已解锁、在店且未被其他一期农田占用。
员工体力达到播种消耗。

任一条件失败时，铜钱、种子、体力和地块都不得发生变化。

7.2 日推进

readyDay 在播种事务中确定性生成。
进入新游戏日时，只把满足条件的 growing 地块转为 ready。
重复读取、保存恢复和离线结算不得重复增加产量或经验。

7.3 收获事务

收获必须一次性校验并提交：

地块为 ready。
执行员工仍有效且体力足够；玩家可改派另一名员工收获。
按成熟批次的 forecastYield 和当前技能规则生成最终产量。
产物写入 kitchenPantry。
增加种植经验。
地块恢复 empty。

不得先清地块再写料仓，也不得因 UI 重复点击收获两次。

8. UI 边界

8.1 后院农田区

在 BackyardTab 内增加一个不嵌套卡片的农田分区，包含：

今日天气、节气与三日预报。
种植技艺等级和经验进度。
两块固定尺寸农田。
每块地的作物、生长状态、预计成熟日、预计产量和负责人。
购买种子、播种、改派和收获命令。

业务计算全部来自 src/utils/farming/ 的视图模型，组件不得自行计算成熟日、天气倍率、体力消耗或经验阈值。

8.2 后厨反馈

料仓沿用现有入口。
青菜显示为粗食材来源，高粱显示为精良食材来源。
一期不新增独立“农产仓库”页。
做菜消费自产食材后，必须能从料仓数量变化和熟食增加中看见闭环。

8.3 日历展示

一期天气预报先进入后院农田区，避免立刻扩张全局顶栏。待闭环验证后再决定是否把“今日历”提到 AppHeaderBar。

9. 三层文件边界

9.1 数据层

首个代码任务只新增：

src/data/farming/types.ts
src/data/farming/crops.ts
src/data/farming/defaults.ts
src/data/farming/index.ts

只允许类型、常量和静态表；禁止函数。

9.2 逻辑层

src/utils/farming/farmingLogic.ts
src/utils/farming/farmingLogic.regression.ts

负责净化、播种计划、天气派生、日推进、收获计划、技能经验和 UI 视图模型。

逻辑层只能依赖数据层、既有天气 / 节气纯函数和通用类型，禁止依赖组件。

9.3 UI 层

src/components/farming/FarmingSection.tsx
src/components/farming/FarmingPlotCell.tsx
src/components/farming/WeatherForecastStrip.tsx

UI 通过逻辑层视图模型渲染，不导入原始作物配置做业务判断。

9.4 集成层

预计需要增量修改：

src/types.ts
src/App.tsx
src/components/BackyardTab.tsx
src/components/DesktopConsolePanel.tsx
src/components/app/useInnResourceController.ts
src/components/app/useSaveRestoreController.ts
src/utils/saveVersioning.ts

这些文件当前可能存在其他在途改动。进入对应任务前必须重新读取工作区差异，只做增量接线，禁止覆盖或整理无关内容。

10. 实施任务

F1：数据契约

范围：只新增 src/data/farming/**。

交付：

两种作物配置。
两块默认农田。
默认种子与种植技艺状态。
数据层无函数。

验收：TypeScript 可导入、字段完整、无反向依赖。

F2：纯逻辑与回归

范围：只新增 src/utils/farming/**。

交付：

旧档净化。
三日天气预报派生。
播种、日推进、收获事务计划。
天气和技能修正。
至少覆盖正常闭环、资源不足、体力不足、重复收获、离线跨日和异常存档六类回归。

验收：聚焦回归通过，数据层零函数，逻辑层零 UI 依赖。

F3：存档接线

范围：src/types.ts、保存 / 恢复控制器、必要的存档版本逻辑。

交付：

farming 运行态写入保存数据。
新档使用默认值。
旧档缺字段时安全回退。
异常地块和负库存被净化。

验收：新档、旧档、保存恢复三种回归；不破坏既有 backyardPlots 和 kitchenPantry。

验证记录（2026-07-30）：

新周目保存数据显式写入独立默认 farming 运行态。
旧档缺字段时由 normalizeFarmingRuntime() 回退，异常地块、负库存和错误技能值均被净化。
App 实时状态、自动保存、恢复控制器与多周目存档类型已完成接线；未提升存档 schema。
种地 / 新周目 / 既有存档迁移聚焦回归 20/20，后厨回归 22/22，tsc --noEmit 与生产构建通过。

F4：事务控制器

范围：资源控制器及最小 App 接线。

交付：

买种子。
播种。
改派员工。
跨日成熟。
收获写入 kitchenPantry。
员工体力扣减和日志反馈。

验收：所有操作原子化，重复点击无双发，失败不产生部分扣款。

验证记录（2026-07-30）：

新增采购、播种、改派和收获事务组合器；失败结果不修改铜钱、种子、员工或料仓输入。
播种与收获扣除现有员工体力，收获写入现有 kitchenPantry，没有新增平行库存。
游戏日变化统一推进农田成熟；跨多日只切换为待收获，不自动产出，重复收获被拒绝。
资源控制器沿用现有事务锁并在成功后立即保存，四个操作句柄尚未接入 UI。
种地 / 新周目 / 存档迁移聚焦回归 24/24，后厨回归 22/22，全量 tsc --noEmit 与生产构建通过。

F5：后院 UI

范围：src/components/farming/**、BackyardTab.tsx 和必要的父组件 props。

交付：

三日预报。
种子购买。
两块农田状态。
员工选择。
播种、成熟和收获反馈。
桌面与移动端文本不溢出。

验收：UI 不含业务计算；无卡片套卡片；操作按钮有清晰禁用原因。

实现记录（2026-07-30）：

后院已接入三日天气、种子采购、两块固定农田、员工选择及播种 / 改派 / 收获命令。
修复桌面主渲染链漏传 farming 与后院生产时段策略的问题，真实桌面入口不再因状态缺失空白。
农田区使用容器查询适配桌面窄控制台和移动端抽屉，预报保持三列、田垄在窄容器下单列排列。
按功能优先安排，本阶段不继续追加门禁；集中验证并入 F7。

F6：后厨闭环

范围：后厨料仓展示与必要的显示映射。

交付：

收获后料仓数量立即变化。
青菜 / 高粱来源以玩家文案可读。
现有做菜入口可以真实消耗该批食材并增加熟食。
熟食继续进入现有售卖链。

验收：从播种到卖钱完成一次真实点击链，不能只在测试 fixture 中成立。

实现记录（2026-07-30）：

后厨“加料”入口收束为“料仓”，继续直接读取唯一库存真源 kitchenPantry。
逻辑层从作物配置派生来源文案：粗食材显示“后院青菜收获”，精良食材显示“后院高粱收获”，不向玩家暴露内部道具 ID。
自产食材按钮明确显示“做菜 +2 / +5”；操作继续复用现有扣料、增加熟食、即时保存事务。
熟食打包售卖链未另建平行实现，仍走现有 5 件 / 20 件售卖入口；集中点击验收并入 F7。

F7：综合验收

范围：只修本期引入问题。

必跑：

npx tsx --test src/utils/farming/farmingLogic.regression.ts
npm run test:kitchen
npm run lint
npm run build

浏览器场景：

新档进入后院。
看见今日和三日天气。
买青菜种子并派员工播种。
推进到成熟日。
收获后确认料仓增加。
后厨消耗食材做菜。
售出熟食获得铜钱。
保存并刷新，农田、种子、技艺和料仓保持一致。

lint 若仍命中仓库既有错误，必须证明本期目标文件无新增错误；不得把既有错误写成全绿。

11. 依赖顺序

F1 数据契约
  -> F2 纯逻辑
  -> F3 存档接线
  -> F4 事务控制器
  -> F5 后院 UI
  -> F6 后厨闭环
  -> F7 综合验收

F1 与 F2 完成前不进入共享集成文件。F3-F6 涉及当前脏工作区中的高冲突文件，每个任务开始前必须重新确认差异。

12. 本期非目标

居民求助和好感奖励。
钓鱼、打猎、挖矿、野外采集。
旅行背包、负重和背包升级。
工具耐久、肥料和复杂品质。
酿酒、酒窖和酒水售卖。
每名员工独立种植技能树。
作物枯死、虫害、杂草和每日强制浇水。
全局月历编辑器和拖拽排班。
大范围重构 App.tsx 或现有后院 / 后厨。

13. 完成定义

只有同时满足以下条件，一期才可称为完成：

玩家完成一次真实“买种 -> 播种 -> 生长 -> 收获 -> 做菜 -> 售卖”闭环。
天气和员工体力至少各真实影响一个结果。
种植技艺至少完成一次升级并影响后续批次。
农产进入现有后厨料仓，没有新增平行库存。
保存恢复和离线跨日不重复结算。
聚焦回归与 build 通过，lint 无本期新增错误。
桌面和移动端完成浏览器点击验收。

14. Phase 2 功能堆叠记录

居民求助进阶（2026-07-30）

每日求助扩展为交货、加工、跑腿三类，继续复用每日三件事轮换和人缘簿完成记录。
跑腿任务可选择已招募、未离店且体力足够的员工；完成后真实扣除员工体力并即时保存。
求助榜直接展示员工当前体力和不可出发原因，体力不足、未招募或已离店的员工不可选择。
陌生、熟识、信赖、知己四个好感阶段分别提供 1.00 / 1.10 / 1.20 / 1.35 倍求助回礼，结算日志使用实际铜钱和声望奖励。
按功能优先安排，本阶段未运行测试、构建或浏览器验收。

物资采购扩展（2026-07-30）

新增 src/data/procurement/** 静态货品配置，首批上架急用柴捆、清水小桶、家常菜篮、精料小箱。
新增 src/utils/procurement/procurementLogic.ts，采购成功后原子扣铜钱并直接写入现有 wood、water 或 kitchenPantry，不创建平行库存。
后院新增“集市采购”面板，普通入口与桌面入口共用同一个采购 handler；铜钱不足或柴水容量已满时给出禁用原因。
成功采购会同步 React 状态、stateRef.current、日志、飘字和即时存档。
按用户要求，本阶段未运行测试、构建或浏览器验收。

采集与基础加工（2026-07-30）

新增 src/data/gathering/**，首批近郊采集点为后山林边、河岸芦苇荡、镇边菜圃；首批加工配方为择洗野菜、磨粮备料、调香料包。
新增 src/utils/gathering/gatheringLogic.ts，采集和加工都通过现有员工体力结算，员工效率影响体力消耗和额外产出。
产出直接写入现有 wood、water 或 kitchenPantry，加工成本也直接扣现有柴水与料仓食材，不创建平行背包库存。
后院新增“采集与加工”面板，普通入口与桌面入口共用同一套 handler；成功后同步 React 状态、stateRef.current、日志、飘字和即时存档。
按用户要求，本阶段未运行测试、构建或浏览器验收。

野外系统骨架（2026-07-30）

新增 src/data/wilderness/**，首批近郊野外活动为后山打猎、溪边钓鱼、近郊探索、旧矿洞挖矿。
新增 src/utils/wilderness/wildernessLogic.ts，野外行动按员工体力、员工效率、活动风险和当日天气进行一次性结算。
产出直接写入现有资源真源：食材进 kitchenPantry，矿货和旧寨遗物进 banditLoot，官道凭据进 guanzhongBills，见闻回流进 reputation，不创建平行野外背包。
天气先做轻量影响：暴雨、雾、雪、大风、酷暑会改变体力或安定风险；细雨 / 晴朗等对部分活动提供额外收益。
后院新增“近郊野外”面板，普通入口与桌面入口共用 handleRunWildernessActivity；成功后同步 React 状态、stateRef.current、日志、飘字和即时存档。
按用户要求，本阶段未运行测试、构建或浏览器验收。

行囊整备与容量升级（2026-07-30）

新增 src/data/baggage/** 静态等级配置，行囊等级只记录运行态 level，不新增平行物资库存。
新增 src/utils/baggage/baggageLogic.ts，集中处理旧档净化、等级查询、容量加成、升级消耗判断和行囊页 view model。
行囊升级消耗真实 coins、wood、guanzhongBills、banditLoot，成功后同步 React 状态、stateRef.current、日志、飘字和即时存档。
装备掉落容量由固定 25 改为读取行囊等级；柴水资源上限在库房、后院功能区基础上叠加行囊周转加成。
行囊页新增“行囊整备”侧滑面板，展示当前等级、装备容量占用、事件收获数量、柴水周转加成、下级预览和整备消耗。
按用户要求，本阶段未运行测试、构建或浏览器验收。

共享客栈技艺（2026-07-30）

新增 src/data/lifeSkills/**，首批共享技艺为采买、采集、野外；本轮不做员工个人技能树，也不迁移农田区已有种植技艺。
新增 src/utils/lifeSkills/lifeSkillLogic.ts，集中处理旧档净化、等级派生、经验增长、产出 / 体力 / 折扣 / 风险加成和面板 view model。
新增 src/components/lifeSkills/LifeSkillsPanel.tsx，后院页展示三条共享技艺等级、经验进度和当前效果。
采买成功获得采买经验，并按采买技艺等级降低集市采购价格；采购卡片显示折扣标签。
采集与加工成功获得采集经验，并按采集技艺等级提高产出、降低体力消耗；近郊采集和后厨加工共用同一条共享技艺。
野外行动成功获得野外经验，并按野外技艺等级提高收获、降低体力与安定风险；打猎、钓鱼、探索、挖矿先共用一条野外技艺。
lifeSkills 写入运行存档和多周目快照；旧档缺字段时回退默认 Lv.1 / 0 经验。
按用户要求，本阶段未运行测试、构建或浏览器验收。