kknongchang_2506/app/Module/Farm/Docs/神像配置表使用说明.md

神像配置表使用说明

本文档详细说明神像配置表的设计、生成和使用方法

1. 概述

神像配置表是游戏中所有神像基础信息的集中配置，主要用于：

• 为客户端提供神像基础数据（名称、描述、持续时间等）
• 为服务端提供神像属性参考
• 支持游戏内神灵加持系统的正常运行

神像配置表通过JSON格式文件提供给客户端，由服务端根据数据库中的神像数据动态生成。

2. 数据来源

2.1 核心数据表

神像配置表的数据主要来源于以下数据库表：

表名	说明	主要字段
farm_shrine_configs	神像配置表	id, buff_type, name, description, duration_hours, item_id, display_attributes

2.2 farm_shrine_configs 表结构

神像配置表（farm_shrine_configs）是神像配置的核心表，包含以下主要字段：

字段名	类型	说明
id	bigint	主键ID
buff_type	tinyint	神像类型:1丰收之神,2雨露之神,3屠草之神,4拭虫之神
name	varchar	神像名称
description	varchar	神像描述
duration_hours	int	默认持续时间(小时)
item_id	bigint	对应物品ID
display_attributes	json	显示属性

3. 配置表生成机制

3.1 生成流程

神像配置表JSON的生成由GenerateFarmShrineConfigJson命令类负责，主要流程如下：

1. 从数据库查询神像基础信息
2. 提取需要的字段并格式化
3. 生成包含时间戳的JSON数据
4. 通过缓存系统存储生成的数据
5. 将JSON数据保存到public/json/farm_shrine.json文件

3.2 生成命令

可以通过以下命令手动触发神像配置表的生成：

php artisan farm:generate-shrine-json

也可以通过后台管理界面的"刷新"功能触发生成。

3.3 JSON数据结构

生成的神像配置表JSON结构如下：

{
  "generated_ts": 1621234567,
  "shrine_configs": [
    {
      "id": 1,
      "buff_type": 1,
      "name": "丰收之神",
      "description": "确保收获时获得最高产量",
      "duration_hours": 24,
      "item_id": 3001,
      "display_attributes": {
        "icon": "shrine_harvest.png",
        "color": "#FFD700",
        "description": "激活后，收获作物时将获得最高产量"
      }
    },
    // 更多神像...
  ]
}

3.4 缓存机制

神像配置表使用FarmShrineJsonConfig类进行缓存管理，主要特点：

• 缓存时间：3600秒（1小时）
• 防重复生成时间：600秒（10分钟）
• 支持通过事件触发更新

4. 配置表使用方法

4.1 客户端获取

客户端可以通过以下两种方式获取神像配置表数据：

1. API接口获取：通过API接口动态获取最新的神像配置数据
2. 静态文件获取：直接访问/json/farm_shrine.json文件获取神像配置数据

建议在游戏启动时获取并缓存神像配置数据。

4.2 服务端使用

服务端可以通过以下方式获取神像配置数据：

use App\Module\Game\DCache\FarmShrineJsonConfig;

// 获取神像配置数据
$shrineConfig = FarmShrineJsonConfig::getData();

// 强制刷新配置数据
$shrineConfig = FarmShrineJsonConfig::getData([], true);

4.3 与其他配置表的关系

神像配置表与其他配置表相互关联：

• 神像配置表引用物品配置表中的物品ID
• 神灵加持系统使用神像配置表中的buff_type

5. 配置表维护

5.1 更新触发

以下操作会触发神像配置表的更新：

1. 添加新神像
2. 修改神像基础信息
3. 删除神像
4. 手动触发更新

5.2 注意事项

1. 神像类型(buff_type)一旦分配不应更改，客户端依赖此类型进行识别
2. 神像属性修改后需要及时更新配置表
3. 大量神像数据变更时，应考虑性能影响

5.3 配置表监控

可以通过以下方式监控配置表状态：

1. 检查生成时间戳是否最新
2. 验证神像数量是否符合预期
3. 定期检查配置表完整性

6. 后台管理

6.1 访问路径

神像配置表的后台管理页面可以通过以下路径访问：

/admin/farm-shrine-configs

6.2 主要功能

后台管理页面提供以下主要功能：

1. 查看所有神像配置
2. 添加新神像配置
3. 编辑现有神像配置
4. 删除神像配置
5. 刷新神像配置JSON数据

6.3 刷新按钮

页面右上角的"立即刷新"按钮可以手动触发神像配置表的生成，确保客户端获取最新的配置数据。