chore: 工程化改造前的基线快照

在引入 uv 依赖管理、ruff 静态检查与格式化、pyright 类型检查之前，
先把当前可正常运行的状态固定下来，作为后续大规模自动改动的回滚点。

此时状态：97 项测试全绿，HTTP + WebSocket 多牧场服务器可用。

farm/models.py

@@ -0,0 +1,324 @@
+"""游戏数据模型。
+
+设计原则：模型只负责"持有数据 + 结构化转换"，所有规则判定放在 engine.py。
+这样 HTTP 层和 TUI 层都能拿到同一份状态快照。
+"""
+
+from __future__ import annotations
+
+import itertools
+from typing import Any, Dict, List, Optional
+
+from . import config
+
+
+def clamp(value: float, low: float, high: float) -> float:
+    """把 value 限制在 [low, high] 区间内。"""
+    return max(low, min(high, value))
+
+
+class Plot:
+    """一块土地。"""
+
+    __slots__ = ("index", "crop", "growth", "moisture", "planted_day")
+
+    def __init__(self, index: int) -> None:
+        self.index = index          # 0-based 下标，对外展示用 index+1
+        self.crop: Optional[str] = None
+        self.growth: float = 0.0    # 已生长天数
+        self.moisture: int = 0      # 剩余可支撑天数
+        self.planted_day: int = 0
+
+    # ---------------------------------------------------------------- 查询
+    @property
+    def is_empty(self) -> bool:
+        return self.crop is None
+
+    @property
+    def grow_days(self) -> int:
+        if self.crop is None:
+            return 0
+        return int(config.CROPS[self.crop]["grow_days"])
+
+    @property
+    def is_ripe(self) -> bool:
+        return self.crop is not None and self.growth >= self.grow_days
+
+    @property
+    def days_left(self) -> int:
+        if self.crop is None:
+            return 0
+        return max(0, self.grow_days - int(self.growth))
+
+    @property
+    def stage(self) -> str:
+        """人类可读的生长阶段。"""
+        if self.crop is None:
+            return "空地"
+        progress = self.growth / max(1, self.grow_days)
+        name = "已播种"
+        for threshold, label in config.GROWTH_STAGES:
+            if progress >= threshold:
+                name = label
+        return name
+
+    # ---------------------------------------------------------------- 序列化
+    def to_dict(self) -> Dict[str, Any]:
+        info = config.CROPS.get(self.crop) if self.crop else None
+        return {
+            "index": self.index,
+            "position": self.index + 1,
+            "crop": self.crop,
+            "crop_name": info["name"] if info else None,
+            "growth": round(self.growth, 2),
+            "grow_days": self.grow_days,
+            "days_left": self.days_left,
+            "is_ripe": self.is_ripe,
+            "is_empty": self.is_empty,
+            "moisture": self.moisture,
+            "water_capacity": config.WATER_CAPACITY,
+            "stage": self.stage,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Plot":
+        plot = cls(int(data.get("index", 0)))
+        crop = data.get("crop")
+        # 校验存档里的作物名仍然合法，避免旧存档导致 KeyError
+        plot.crop = crop if crop in config.CROPS else None
+        plot.growth = float(data.get("growth", 0.0))
+        plot.moisture = int(data.get("moisture", 0))
+        plot.planted_day = int(data.get("planted_day", 0))
+        return plot
+
+
+class Animal:
+    """一只牲畜。"""
+
+    _id_counter = itertools.count(1)
+
+    __slots__ = ("aid", "kind", "fed", "progress", "starve", "pending")
+
+    def __init__(self, kind: str, aid: Optional[int] = None) -> None:
+        self.aid = aid if aid is not None else next(Animal._id_counter)
+        self.kind = kind
+        self.fed = False        # 今天是否已喂食
+        self.progress = 0       # 距下次产出的累计天数
+        self.starve = 0         # 连续未进食天数
+        self.pending = 0        # 待收集的产出数量
+
+    # ---------------------------------------------------------------- 查询
+    @property
+    def info(self) -> Dict[str, Any]:
+        return config.ANIMALS[self.kind]
+
+    @property
+    def name(self) -> str:
+        return self.info["name"]
+
+    @property
+    def product(self) -> str:
+        return self.info["product"]
+
+    @property
+    def cycle(self) -> int:
+        return int(self.info["cycle"])
+
+    @property
+    def days_to_product(self) -> int:
+        return max(0, self.cycle - self.progress)
+
+    @property
+    def is_sick(self) -> bool:
+        """连续 2 天没吃东西，进入"虚弱"状态。"""
+        return self.starve >= 2
+
+    # ---------------------------------------------------------------- 序列化
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.aid,
+            "kind": self.kind,
+            "name": self.name,
+            "product": self.product,
+            "fed": self.fed,
+            "progress": self.progress,
+            "cycle": self.cycle,
+            "days_to_product": self.days_to_product,
+            "pending": self.pending,
+            "starve": self.starve,
+            "is_sick": self.is_sick,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> Optional["Animal"]:
+        kind = data.get("kind")
+        if kind not in config.ANIMALS:
+            return None
+        animal = cls(kind, int(data.get("id", 0)) or None)
+        animal.fed = bool(data.get("fed", False))
+        animal.progress = int(data.get("progress", 0))
+        animal.starve = int(data.get("starve", 0))
+        animal.pending = int(data.get("pending", 0))
+        # 恢复 id 计数器，避免新动物与旧动物 id 冲突
+        Animal._id_counter = itertools.count(max(animal.aid + 1, next(Animal._id_counter)))
+        return animal
+
+
+class GameState:
+    """完整的游戏状态。所有字段都必须是可 JSON 序列化的。"""
+
+    def __init__(self) -> None:
+        self.day: int = 1
+        self.gold: int = config.START_GOLD
+        self.level: int = config.START_LEVEL
+        self.exp: int = 0
+        self.ap: int = config.START_AP
+        self.feed: int = config.START_FEED
+        self.plots: List[Plot] = [Plot(i) for i in range(config.BASE_PLOTS)]
+        self.animals: List[Animal] = []
+        self.log: List[Dict[str, Any]] = []
+
+        # 市场价格（每天波动）：key -> 当前单价
+        self.market: Dict[str, float] = {
+            key: float(info["base_price"]) for key, info in config.CROPS.items()
+        }
+        for key, info in config.ANIMALS.items():
+            self.market[f"animal:{key}"] = float(info["base_price"])
+
+        # 统计
+        self.total_harvested: int = 0
+        self.total_collected: int = 0
+        self.total_earned: int = 0
+        self.total_spent: int = 0
+        self.plots_bought: int = 0
+
+    # ---------------------------------------------------------------- 派生属性
+    @property
+    def max_ap(self) -> int:
+        return config.START_AP
+
+    @property
+    def max_plots(self) -> int:
+        """当前等级允许持有的土地上限。"""
+        allowed = config.BASE_PLOTS + config.PLOTS_PER_LEVEL * (self.level - 1)
+        return int(clamp(allowed, config.BASE_PLOTS, config.MAX_PLOTS))
+
+    @property
+    def next_plot_price(self) -> int:
+        """下一块土地的价格；已达上限时返回 -1。"""
+        if len(self.plots) >= self.max_plots:
+            return -1
+        return int(config.PLOT_BASE_PRICE * (config.PLOT_PRICE_GROWTH ** self.plots_bought))
+
+    @property
+    def exp_needed(self) -> int:
+        return config.exp_to_next(self.level)
+
+    @property
+    def inventory_value(self) -> float:
+        return self.feed * config.FEED_UNIT_PRICE
+
+    @property
+    def livestock_value(self) -> float:
+        return sum(
+            a.pending * self.market.get(f"animal:{a.kind}", 0) + a.info["cost"] * 0.5
+            for a in self.animals
+        )
+
+    @property
+    def net_worth(self) -> float:
+        """净资产：金币 + 已购地价 + 牲畜折价 + 库存 + 地里未收的作物。"""
+        land = sum(
+            config.PLOT_BASE_PRICE * (config.PLOT_PRICE_GROWTH ** i)
+            for i in range(self.plots_bought)
+        )
+        crops = 0.0
+        for plot in self.plots:
+            if plot.crop:
+                crops += self.market.get(plot.crop, 0) * (plot.growth / max(1, plot.grow_days))
+        return self.gold + land + self.livestock_value + self.inventory_value + crops
+
+    @property
+    def goal_index(self) -> int:
+        return config.goal_index(self.net_worth)
+
+    @property
+    def next_goal(self) -> Optional[Dict[str, Any]]:
+        nxt = self.goal_index + 1
+        if nxt >= len(config.GOALS):
+            return None
+        amount, text = config.GOALS[nxt]
+        return {"amount": amount, "text": text}
+
+    # ---------------------------------------------------------------- 序列化
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "day": self.day,
+            "gold": self.gold,
+            "level": self.level,
+            "exp": self.exp,
+            "exp_needed": self.exp_needed,
+            "ap": self.ap,
+            "max_ap": self.max_ap,
+            "feed": self.feed,
+            "plots": [p.to_dict() for p in self.plots],
+            "plot_count": len(self.plots),
+            "max_plots": self.max_plots,
+            "next_plot_price": self.next_plot_price,
+            "animals": [a.to_dict() for a in self.animals],
+            "animal_count": len(self.animals),
+            "max_animals": config.MAX_ANIMALS,
+            "market": {k: round(v, 2) for k, v in self.market.items()},
+            "net_worth": round(self.net_worth, 2),
+            "goal_index": self.goal_index,
+            "next_goal": self.next_goal,
+            "stats": {
+                "harvested": self.total_harvested,
+                "collected": self.total_collected,
+                "earned": self.total_earned,
+                "spent": self.total_spent,
+            },
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "GameState":
+        state = cls()
+        state.day = max(1, int(data.get("day", 1)))
+        state.gold = max(0, int(data.get("gold", config.START_GOLD)))
+        state.level = max(1, int(data.get("level", 1)))
+        state.exp = max(0, int(data.get("exp", 0)))
+        state.feed = max(0, int(data.get("feed", 0)))
+        state.ap = int(clamp(int(data.get("ap", state.max_ap)), 0, state.max_ap))
+
+        plots = [Plot.from_dict(p) for p in data.get("plots", []) if isinstance(p, dict)]
+        # 保证至少有初始土地，且不超过硬上限
+        count = int(clamp(len(plots) or config.BASE_PLOTS, config.BASE_PLOTS, config.MAX_PLOTS))
+        if len(plots) < count:
+            plots.extend(Plot(i) for i in range(len(plots), count))
+        state.plots = plots[:config.MAX_PLOTS]
+        for i, plot in enumerate(state.plots):
+            plot.index = i
+
+        animals: List[Animal] = []
+        for item in data.get("animals", [])[: config.MAX_ANIMALS]:
+            if isinstance(item, dict):
+                animal = Animal.from_dict(item)
+                if animal is not None:
+                    animals.append(animal)
+        state.animals = animals
+
+        market = data.get("market", {})
+        for key in list(state.market.keys()):
+            try:
+                value = float(market.get(key, state.market[key]))
+            except (TypeError, ValueError):
+                continue
+            state.market[key] = clamp(value, 1.0, 100000.0)
+
+        stats = data.get("stats", {})
+        state.total_harvested = max(0, int(stats.get("harvested", 0)))
+        state.total_collected = max(0, int(stats.get("collected", 0)))
+        state.total_earned = max(0, int(stats.get("earned", 0)))
+        state.total_spent = max(0, int(stats.get("spent", 0)))
+        state.plots_bought = max(0, len(state.plots) - config.BASE_PLOTS)
+        return state