docs/17-season-backgrounds.md

# 四季背景与蜂巢预览

## 用户指令

`我的农场` 和 `我的农场 高清` 根据请求时刻的北京时间自动选择：

| 月份 | 主题 |
| --- | --- |
| 3～5 月 | 春季 spring |
| 6～8 月 | 夏季 summer |
| 9～11 月 | 秋季 autumn |
| 12～2 月 | 冬季 winter |

使用固定 UTC+8，不依赖宿主操作系统时区或额外时区数据包。
接入层只解析一次主题和当前时间，并将同一时间传给渲染服务。
主题参与底图缓存与成图缓存，跨季节不会命中上一季的图片。
服务无需重启即可在下一次请求时切换季节；没有后台定时广播。

按用户要求，蜂巢 bee 只生成离线预览，用户指令不支持蜂巢参数。
底层显式 RenderOptions(theme="bee") 供离线绘图使用；四季规则不会返回 bee。

## 建筑与定位

统一位置保存在 `src/farm_render/data/background_layout.json`。
以已完成对照的默认主题完整背景为参考，保留九个独立建筑及装饰。
配置保留每项来源依据：房屋原始变换链；矿洞和入口包含实例化行为推断；
其余为用户同意采用的截图反算位置，不能称为所有主题的官方原始配置。

各主题替换对应 PNG，使用相同底边中点与宽度，按本主题图片原始比例
计算高度。秋、冬房屋为 890×821，其余房屋为 890×981，底边保持一致，
不把较矮的房屋强行拉高。完整透明画布不裁剪，狗窝不额外镜像。
码头属于前景，在作物和虫子之后叠加，其余装饰绘入缓存底图。

## 缺失素材的明确回退

- 春、夏没有对应邮箱：使用默认邮箱。
- 秋季没有对应邮箱、加工坊标牌：使用默认图片。
- 五个主题没有单独的稻草人标牌：使用默认标牌。

导出的 metadata.decorations 为每项记录 source_theme、fallback 和 basis。
不丢失建筑，不用其他任意主题图片替代，也不修改旧参考素材。
主题图片均来自本地已有资源；没有为这些图片增加生成式美术内容。
许愿树、直升机等额外动态模块不包含在这九张装饰中。

## 打包与生成预览

`scripts/export_render_assets.py` 原样打包六套主题底图及现存独立 PNG，
并生成各主题九项定位数据。`--check` 验证可复现输出。
渲染器使用包内资源，不依赖旧目录或本机预览路径。

```text
python scripts/preview_seasons.py --output <输出目录>
```

输出五张 `background-主题.jpg` 完整底图、五张 `farm-主题-1536.png`
完整农场样图，以及 `all-themes.jpg` 总览。蜂巢仅存在于这类预览中。
底图预览为 3072×1872，农场样图为 1536×936。

本轮验证包含北京时间月份边界、缺图回退、房屋比例和落地点、
前景码头图层、主题缓存隔离、普通/高清 QQ 指令选图。
未部署正在运行的机器人，也未验证真实 QQ 上传。