优化项目架构

2025-09-15 19:10:37 +08:00
parent 4119ed3445
commit 26b856d74e
1361 changed files with 4 additions and 0 deletions
--- a/SproutFarm-Backend/test/文档/特殊农场管理系统说明.md
+++ b/SproutFarm-Backend/test/文档/特殊农场管理系统说明.md
@@ -0,0 +1,218 @@
+# 特殊农场管理系统
+
+## 概述
+
+特殊农场管理系统是一个自动化的农场维护工具，用于管理游戏中的特殊农场，为玩家提供特殊的不可购买作物。系统支持定时任务和手动维护两种模式。
+
+## 功能特性
+
+### 1. 自动定时维护
+- **执行时间**: 每天凌晨0点自动执行
+- **维护内容**: 为特殊农场种植指定的作物
+- **日志记录**: 详细记录维护过程和结果
+
+### 2. 手动维护模式
+- 支持即时手动维护指定农场
+- 可用于测试和紧急维护
+
+### 3. 多环境支持
+- **测试环境**: 用于开发和测试
+- **生产环境**: 用于正式运行
+
+## 当前支持的特殊农场
+
+### 杂交农场
+- **农场ID**: `689b4b9286cf953f2f4e56ee`
+- **种植作物**: 0号杂交树、1号杂交树
+- **种植方式**: 随机全屏种植
+- **土地要求**: 仅在已开垦的土地上种植
+- **作物状态**: 自动设置为已浇水、已施肥、立即成熟
+
+## 使用方法
+
+### 方法一：使用启动脚本（推荐）
+```bash
+# Windows
+start_special_farm.bat
+
+# 然后选择运行模式：
+# 1. 测试环境
+# 2. 生产环境  
+# 3. 手动维护模式
+```
+
+### 方法二：直接命令行
+
+#### 自动模式（定时任务）
+```bash
+# 测试环境
+python SpecialFarm.py test
+
+# 生产环境
+python SpecialFarm.py production
+```
+
+#### 手动维护模式
+```bash
+# 手动维护杂交农场（测试环境）
+python SpecialFarm.py test manual 杂交农场
+
+# 手动维护杂交农场（生产环境）
+python SpecialFarm.py production manual 杂交农场
+```
+
+### 方法三：运行测试
+```bash
+# 运行完整测试
+python test_special_farm.py
+```
+
+## 系统架构
+
+### 核心组件
+
+1. **SpecialFarmManager**: 主管理类
+   - 负责农场配置管理
+   - 处理定时任务调度
+   - 执行种植逻辑
+
+2. **MongoDB集成**: 
+   - 使用 `SMYMongoDBAPI` 进行数据库操作
+   - 支持玩家数据和作物配置的读写
+
+3. **定时任务**: 
+   - 使用 `schedule` 库实现定时功能
+   - 支持每日凌晨0点自动执行
+
+### 数据结构
+
+#### 农场配置
+```python
+special_farms = {
+    "杂交农场": {
+        "object_id": "689b4b9286cf953f2f4e56ee",
+        "crop_types": ["杂交树1", "杂交树2"]
+    }
+}
+```
+
+#### 作物种植逻辑
+- 随机选择配置的作物类型
+- 仅在已开垦（`is_diged=True`）的土地上种植
+- 自动设置作物状态：
+  - `is_planted=True`
+  - `is_watered=True` 
+  - `is_fertilized=True`
+  - `growth_time=0`（立即成熟）
+
+## 日志系统
+
+### 日志文件
+- **文件名**: `special_farm.log`
+- **位置**: 与脚本同目录
+- **格式**: `时间 - 级别 - 模块 - 消息`
+
+### 日志级别
+- **INFO**: 正常操作信息
+- **WARNING**: 警告信息
+- **ERROR**: 错误信息
+
+### 示例日志
+```
+2024-01-15 00:00:01,123 - INFO - __main__ - 开始执行每日特殊农场维护任务...
+2024-01-15 00:00:02,456 - INFO - __main__ - 成功为 杂交农场 种植了 40 块土地的作物
+2024-01-15 00:00:02,789 - INFO - __main__ - 每日维护任务完成: 1/1 个农场维护成功
+```
+
+## 依赖要求
+
+### Python包
+```
+schedule>=1.2.0
+pymongo>=4.0.0
+```
+
+### 系统要求
+- Python 3.7+
+- MongoDB数据库连接
+- 有效的游戏数据库配置
+
+## 扩展指南
+
+### 添加新的特殊农场
+
+1. **在数据库中创建农场数据**
+   - 在 `playerdata` 集合中添加新的农场文档
+   - 记录文档的 `ObjectId`
+
+2. **更新农场配置**
+   ```python
+   # 在 SpecialFarm.py 中的 special_farms 字典添加
+   "新农场名称": {
+       "object_id": "新农场的ObjectId",
+       "crop_types": ["作物类型1", "作物类型2"]
+   }
+   ```
+
+3. **测试新农场**
+   ```bash
+   python SpecialFarm.py test manual 新农场名称
+   ```
+
+### 自定义种植逻辑
+
+可以在 `plant_crops_in_farm` 方法中修改种植逻辑：
+- 改变作物选择算法
+- 调整作物生长参数
+- 添加特殊种植条件
+
+## 故障排除
+
+### 常见问题
+
+1. **数据库连接失败**
+   - 检查MongoDB服务是否运行
+   - 验证数据库连接配置
+
+2. **农场数据不存在**
+   - 确认农场ObjectId是否正确
+   - 检查数据库中是否存在对应文档
+
+3. **作物配置错误**
+   - 验证作物类型名称是否正确
+   - 检查作物配置数据是否完整
+
+### 调试模式
+
+运行测试脚本获取详细信息：
+```bash
+python test_special_farm.py
+```
+
+## 安全注意事项
+
+1. **生产环境使用**
+   - 确保在生产环境中使用正确的数据库配置
+   - 定期备份重要数据
+
+2. **权限管理**
+   - 确保脚本有足够的数据库读写权限
+   - 限制对生产数据库的访问
+
+3. **监控和告警**
+   - 定期检查日志文件
+   - 设置维护任务失败的告警机制
+
+## 版本历史
+
+- **v1.0.0**: 初始版本，支持杂交农场的自动维护
+  - 实现定时任务功能
+  - 支持手动维护模式
+  - 完整的日志系统
+  - 测试和生产环境分离
+
+---
+
+**作者**: AI Assistant  
+**创建时间**: 2024年  
+**最后更新**: 2024年