-- ============================================================================
-- Agent 工具清单表（agent_tool）
--
-- 设计要点：
--   1) 这张表是**代码的镜像**：应用启动时用反射扫出 module/agent/tools 下所有 @Tool 方法，
--      再与 agent 运行时装配（工具组、入参 JSON Schema）对照，按工具名 upsert；
--   2) 页面「插件与技能 → 工具」只读展示，不做人工维护，因此没有业务外键、也没有编辑入口；
--   3) code 里删掉的工具不删行，只置 status = 'DELETED'（保留行便于追溯历史工具）；
--   4) tool_name 唯一：模型调用工具只认它，重名会让调用落到不确定的实现。
--
-- 执行库：PostgreSQL（master）
--
-- ⚠️ 建表由**人工执行本脚本**完成，应用启动时不做 DDL。
--    项目约定：固定表名的建表语句只放 sql/ 脚本；代码里 @Update("CREATE TABLE ...") 仅限
--    表名动态生成、无法预先写死的场景（如 rag_ws{workspaceId}_d{dims} 向量表）。
--    表不存在时应用仍能正常启动，只是工具清单不同步、页面展示空清单（启动日志会提示执行本脚本）。
-- ============================================================================

CREATE TABLE IF NOT EXISTS agent_tool (
  id                 BIGINT       PRIMARY KEY,               -- 应用侧生成（雪花 ID）
  tool_name          VARCHAR(128) NOT NULL,                  -- 工具名（@Tool(name=...)），模型调用标识
  tool_class         VARCHAR(255),                           -- 声明该工具的类（便于从表反查代码）
  tool_method        VARCHAR(128),                           -- 方法名
  group_code         VARCHAR(32),                            -- 工具组编码：call/trans/track/graph/person/file；基础工具为 base
  group_label        VARCHAR(64),                            -- 工具组中文名
  group_description  TEXT,                                   -- 工具组描述（写给模型的「什么时候该激活我」）
  group_sort         INTEGER,                                -- 分组排序位（业务组按注册顺序，基础工具最后）
  default_active     BOOLEAN,                                -- 是否新会话默认装备
  description        TEXT,                                   -- 工具描述（@Tool(description=...)）
  parameters         JSONB,                                  -- 入参 JSON Schema（框架从 @ToolParam 推导，原样存）
  read_only          BOOLEAN,                                -- 是否只读工具（@Tool(readOnly=true)）
  status             VARCHAR(16),                            -- ACTIVE | DELETED
  create_at          TIMESTAMP,
  update_at          TIMESTAMP
);

-- 同步按工具名 upsert，唯一约束放在数据库侧兜底
CREATE UNIQUE INDEX IF NOT EXISTS uk_agent_tool_name ON agent_tool (tool_name);

COMMENT ON TABLE  agent_tool                    IS 'Agent 工具清单：启动时反射扫描 @Tool 后与运行时装配合并同步，页面只读';
COMMENT ON COLUMN agent_tool.tool_name          IS '工具名（@Tool(name=...)）：模型调用时使用的标识，全表唯一';
COMMENT ON COLUMN agent_tool.tool_class         IS '声明该工具的类，便于从表反查代码';
COMMENT ON COLUMN agent_tool.tool_method        IS '方法名，与 tool_class 一起定位实现';
COMMENT ON COLUMN agent_tool.group_code         IS '工具组编码；不属于任何业务组的归到 base（基础工具，会话里始终可用）';
COMMENT ON COLUMN agent_tool.group_label        IS '工具组中文名（页面分组标题）';
COMMENT ON COLUMN agent_tool.group_description  IS '工具组描述原文，写给模型看「什么时候该激活我」';
COMMENT ON COLUMN agent_tool.group_sort         IS '分组排序位：业务组按注册表顺序，基础工具排最后';
COMMENT ON COLUMN agent_tool.default_active     IS '是否新会话默认装备（其余组由模型用 reset_equipped_tools 按需激活）';
COMMENT ON COLUMN agent_tool.description        IS '工具描述，模型选型的主要依据';
COMMENT ON COLUMN agent_tool.parameters         IS '入参 JSON Schema（{type,properties,required,$defs}），页面按它渲染参数表';
COMMENT ON COLUMN agent_tool.read_only          IS '是否只读工具（当前全部为只读：不写案件数据）';
COMMENT ON COLUMN agent_tool.status             IS 'ACTIVE | DELETED；代码里已删除的工具置 DELETED 而不删行';