🏗️ 文字版农场游戏 ------ 架构设计文档
基于《农场文字版策划案.md》的软件架构设计
目标语言：Python 3.10+ | 运行模式：终端 CLI | 存储：JSON 本地持久化
运行游戏
基本集成了土地，播种，浇水，售后，商店等功能，随时间而收获
一、整体架构概览
┌─────────────────────────────────────────────────────┐
│ main.py │
│ (游戏入口 / 主循环) │
└──────────┬──────────────────────────────┬───────────┘
│ │
┌──────▼──────┐ ┌───────▼──────────┐
│ Game │ │ MenuManager │
│ (游戏核心) │◄────────────►│ (选单导航引擎) │
└──┬──┬──┬──┬─┘ └──────────────────┘
│ │ │ │
┌────┘ │ │ └──────┐
▼ ▼ ▼ ▼
┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐
│ Land │ │ Crop │ │ Econ │ │ Inventory│
│ System│ │System│ │System│ │(背包/装饰)│
└───────┘ └──────┘ └──────┘ └──────────┘
┌──────────┐
│ SaveLoad │
│ (数据持久化)│
└──────────┘二、目录结构
farm_game/
├── main.py # 程序入口，启动游戏
├── game.py # Game 类 ------ 游戏核心状态与主循环
├── menu.py # MenuManager ------ 选单导航与渲染
│
├── systems/
│ ├── __init__.py
│ ├── land.py # LandSystem ------ 地块管理
│ ├── crop.py # CropSystem ------ 作物数据与生长逻辑
│ ├── economy.py # EconomySystem ------ 金币/经验/等级
│ ├── store.py # StoreSystem ------ 商店购买逻辑
│ ├── inventory.py # InventorySystem ------ 背包与装饰
│ └── achievement.py # AchievementSystem ------ 成就/签到
│
├── data/
│ └── crops.json # 作物静态数据表
│
├── save/
│ └── (运行时生成) # save_*.json 存档文件
│
└── utils/
├── __init__.py
├── display.py # 格式化输出（表格、颜色、图标）
└── time_helper.py # 时间工具（倒计时、时间戳转换）三、核心类设计
1. Game ------ 游戏核心
┌─────────────────────────────────────────────┐
│ Game │
├─────────────────────────────────────────────┤
│ - player_data: dict │
│ - land_system: LandSystem │
│ - crop_system: CropSystem │
│ - economy: EconomySystem │
│ - store: StoreSystem │
│ - inventory: InventorySystem │
│ - achievement: AchievementSystem │
│ - menu: MenuManager │
├─────────────────────────────────────────────┤
│ + new_game() │
│ + load_game(save_id) │
│ + save_game() │
│ + main_loop() │
│ + tick() # 检查成熟/枯萎状态 │
│ + get_overview() # 主界面概况文本 │
└─────────────────────────────────────────────┘Game是唯一的状态持有者，所有子系统通过它访问共享数据。main_loop()驱动「显示菜单 → 等待输入 → 分发动作 → 刷新状态」循环。tick()在每次操作前调用，检查所有地块的成熟/枯萎状态。
2. LandSystem ------ 地块管理
┌─────────────────────────────────────────────┐
│ LandSystem │
├─────────────────────────────────────────────┤
│ - lands: list[dict] # 地块数组 │
│ # 每块: { id, status, crop_id, │
│ # plant_time, water_count } │
│ - max_lands: int │
├─────────────────────────────────────────────┤
│ + get_land(land_id) -> dict │
│ + get_lands_by_status(status) -> list │
│ + plant(land_id, crop_id) -> bool │
│ + harvest(land_id) -> dict # 收益 │
│ + water(land_id) -> bool │
│ + fertilize(land_id) -> bool │
│ + till(land_id) -> bool # 翻地 │
│ + unlock_lands(count) -> bool │
│ + update_all(timestamp) # 更新生长状态 │
└─────────────────────────────────────────────┘地块状态机：
┌──────────┐ 播种 ┌──────────┐ 时间到 ┌──────────┐
│ 空地 │ ──────► │ 生长中 │ ────────► │ 成熟 │
│ (闲置) │ │ (倒计时) │ │ (可收获) │
└──────────┘ └──────────┘ └────┬─────┘
▲ │ 30min未收
│ 翻地 ▼
│ ┌──────────┐
└────────────────────────────────────── │ 枯萎 │
│ (需翻地) │
└──────────┘3. CropSystem ------ 作物数据
┌─────────────────────────────────────────────┐
│ CropSystem │
├─────────────────────────────────────────────┤
│ - crops_db: dict[str, CropData] │
│ # crop_id -> { name, price, mature_time, │
│ # sell_price, exp, level_req }│
├─────────────────────────────────────────────┤
│ + get_crop(crop_id) -> CropData │
│ + get_available_crops(level) -> list │
│ + get_mature_seconds(crop_id, planted_at) │
│ -> int # 剩余秒数 │
│ + load_from_json(path) │
└─────────────────────────────────────────────┘CropData 可定义为 dataclass：
python
@dataclass
class CropData:
crop_id: str
name: str
seed_price: int
mature_seconds: int # 成熟所需秒数
sell_price: int
exp: int
level_required: int4. EconomySystem ------ 经济与等级
┌─────────────────────────────────────────────┐
│ EconomySystem │
├─────────────────────────────────────────────┤
│ - gold: int │
│ - exp: int │
│ - level: int │
├─────────────────────────────────────────────┤
│ + add_gold(amount) │
│ + spend_gold(amount) -> bool │
│ + add_exp(amount) │
│ + get_level() -> int │
│ + get_exp_to_next_level() -> int │
│ - _calculate_level(exp) -> int │
└─────────────────────────────────────────────┘等级公式（示例）：
下一级所需总经验 = 100 × level²| 等级 | 总经验 |
|---|---|
| 1 | 0 |
| 2 | 100 |
| 3 | 400 |
| 4 | 900 |
| 5 | 1600 |
| ... | ... |
5. StoreSystem ------ 商店
┌─────────────────────────────────────────────┐
│ StoreSystem │
├─────────────────────────────────────────────┤
│ (依赖 CropSystem 和 EconomySystem) │
├─────────────────────────────────────────────┤
│ + buy_seed(crop_id) -> bool │
│ + get_store_list(level) -> list │
│ + buy_decoration(item_id) -> bool │
└─────────────────────────────────────────────┘6. InventorySystem ------ 背包与装饰
┌─────────────────────────────────────────────┐
│ InventorySystem │
├─────────────────────────────────────────────┤
│ - decorations: list[str] # 已购装饰 ID │
│ - seeds: dict[str, int] # 种子库存 │
├─────────────────────────────────────────────┤
│ + add_seed(crop_id, count) │
│ + use_seed(crop_id) -> bool │
│ + add_decoration(item_id) │
│ + get_active_decoration_text() -> str │
└─────────────────────────────────────────────┘7. AchievementSystem ------ 成就与签到
┌─────────────────────────────────────────────┐
│ AchievementSystem │
├─────────────────────────────────────────────┤
│ - achievements: dict[str, bool] │
│ - total_harvests: int │
│ - planted_set: set[str] │
│ - sign_in_days: int │
│ - last_sign_in: str / None │
├─────────────────────────────────────────────┤
│ + check_achievements() -> list[str] # 新成就│
│ + record_harvest(crop_id) │
│ + sign_in() -> dict # 签到奖励 │
│ + get_achievement_list() -> list │
└─────────────────────────────────────────────┘8. MenuManager ------ 选单导航引擎
┌─────────────────────────────────────────────┐
│ MenuManager │
├─────────────────────────────────────────────┤
│ - game: Game (反向引用) │
├─────────────────────────────────────────────┤
│ + show_main_menu() │
│ + show_farm_view() │
│ + show_store() │
│ + show_plant_menu() │
│ + show_harvest_menu() │
│ + show_water_menu() │
│ + show_till_menu() │
│ + show_inventory() │
│ + show_achievements() │
│ + show_decoration_shop() │
│ - _get_input(prompt) -> int │
│ - _wait_return() │
└─────────────────────────────────────────────┘- 每个
show_xxx()方法对应策划案中的一个选单界面。 - 方法内部：打印界面 → 读取数字输入 → 调用
game对应方法 → 回到主菜单。 - 选单之间不嵌套调用 ，全部归流到
main_loop()。
四、数据存储设计 (JSON Schema)
存档文件 save_001.json
json
{
"version": 1,
"player": {
"name": "玩家",
"gold": 520,
"exp": 350,
"level": 3
},
"lands": [
{
"id": 1,
"status": "growing",
"crop_id": "carrot",
"plant_time": 1719715200.0,
"water_count": 0
},
{
"id": 2,
"status": "mature",
"crop_id": "strawberry",
"plant_time": 1719714000.0,
"water_count": 1
}
],
"inventory": {
"seeds": {
"carrot": 5,
"potato": 2
},
"decorations": []
},
"achievements": {
"first_harvest": true,
"total_harvests": 12,
"planted_crops": ["carrot", "potato"],
"sign_in": {
"last_date": "2026-07-01",
"continuous_days": 3
}
}
}静态作物数据 crops.json
json
[
{
"crop_id": "carrot",
"name": "萝卜",
"seed_price": 10,
"mature_seconds": 120,
"sell_price": 20,
"exp": 1,
"level_required": 1
}
]五、主循环流程（伪代码）
function main_loop():
while True:
tick() # 刷新所有地块状态
print(main_menu_text()) # 渲染主界面
choice = input("请输入数字选择: ")
if choice == 0: # 退出
save_game()
break
elif choice == 1: menu.show_farm_view()
elif choice == 2: menu.show_store()
elif choice == 3: menu.show_plant_menu()
elif choice == 4: menu.show_harvest_menu()
elif choice == 5: menu.show_water_menu()
elif choice == 6: menu.show_unlock_land()
elif choice == 7: menu.show_till_menu()
elif choice == 8: menu.show_inventory()
elif choice == 9: menu.show_achievements()数据流方向：
输入 ──► MenuManager ──► Game ──► SubSystem
│
◄─────────────┘
返回结果/状态
│
┌──────────▼──────────┐
│ 自动保存 (每3次操作) │
└─────────────────────┘六、时间机制
-
使用
time.time()记录plant_time（播种时间戳）。 -
每次用户操作时调用
tick()：剩余时间 = (plant_time + mature_seconds) - now -
不依赖后台线程 / 定时器，纯被动刷新。
-
浇水效果：
mature_seconds -= 60（减少 1 分钟），最少不低于 10 秒。 -
枯萎判定：成熟时间戳 + 1800 秒（30 分钟）→ 标记为
withered。
七、浇水/施肥机制
| 动作 | 效果 | 冷却 |
|---|---|---|
| 浇水 | 剩余生长时间 -60s | 每块地每 30s 可浇一次 |
| 施肥 | 剩余生长时间 -120s | 消耗背包中的肥料（后续版本） |
八、依赖关系图
Game
/ | \
/ | \
▼ ▼ ▼
LandSystem EconomySystem InventorySystem
| | |
▼ ▼ |
CropSystem StoreSystem |
| |
▼ ▼
AchievementSystem (装饰数据)- 所有子系统之间不直接依赖 ，仅通过
Game协调。 MenuManager依赖Game（通过它访问所有子系统）。StoreSystem依赖CropSystem（读取作物数据）和EconomySystem（扣钱判断）。
九、开发路线（对应策划案 MVP）
| 阶段 | 内容 | 涉及模块 |
|---|---|---|
| Phase 1 | 核心循环：土地 + 种植 + 收获 + 倒计时 | LandSystem, CropSystem, Game, MenuManager |
| Phase 2 | 商店 + 经济系统 + 等级解锁 | StoreSystem, EconomySystem |
| Phase 3 | 多作物 + 等级解锁过滤 | CropSystem 完善 + 等级校验 |
| Phase 4 | 装饰 + 成就 + 签到 | InventorySystem, AchievementSystem |