数据模型

ApiGo 的持久化层使用 MySQL，初始化脚本 db/mysql/ddl.sql 创建 45 张核心表，升级脚本 db/mysql/update_ddl.sql 另补充 AI 场景与字典表。本文按业务域说明表之间的关系，帮助理解功能背后的数据边界。

无物理外键

整套模型不使用数据库外键，关联完整性由应用层保证。这样做的目的是：支持分库分表与数据迁移、避免级联删除误伤、便于按项目清理数据。阅读表结构时应关注唯一键与索引，它们才是真正的约束。

全局关系

表	作用	关键字段 / 约束
`base_project`	项目（租户空间）	项目编码、名称、状态；所有业务数据带 `project_id`
`base_project_member`	项目成员及角色	项目 + 用户 + 角色；决定项目级数据可见性
`base_sys_user`	平台用户	`user_name` 唯一；密码、状态、部门
`base_sys_role` / `base_sys_role_menu`	角色与菜单权限	角色-菜单多对多
`base_sys_menu`	菜单与按钮权限	树形结构，前端动态路由来源
`base_sys_dept`	部门	`wecom_dept_id` 唯一，用于企业微信同步
`base_sys_sso_bind`	第三方账号绑定	`(provider, provider_user_id)` 唯一
`base_sys_log`	管理端操作日志	操作人、模块、动作、请求与结果
`base_sys_message`	站内消息	接收人、类型、已读状态
`base_sys_params`	系统参数	参数键值，运行期可调整

隔离规则：除平台级系统表外，接口、分组、数据源、规则、告警、AI 会话均以 project_id 隔离。用户只能看到自己所属项目的业务数据；超级管理员可跨项目操作。

表	作用	关键字段 / 约束
`base_api_info`	接口设计态主表	`api_path + api_method` 唯一；`api_type` 为 `sql/table/proxy`；`api_status` 为 `edit/audit/release/destroy`；`api_link_id` 标识版本族；`parent_id` 支持派生接口
`base_api_param`	接口参数定义	入参/出参、类型、必填、默认值、排序；发布时快照到发布表
`base_api_proxy`	代理模式配置	目标地址、请求方法、超时、鉴权、报文模式、错误码映射
`base_api_env`	环境定义	`(project_id, env_code)` 唯一；路径前缀、访问地址、MCP 前缀、访问模式、是否生产
`base_auth_env`	环境访问授权	环境 + 用户，限定非公开环境的可见范围
`base_api_release`	发布快照	`(api_link_id, env_code, deploy_revision)` 唯一；`source_api_id` 指向设计态接口；`is_current` 标识当前生效版本
`base_group`	接口分组	树形分组，工作台左侧导航来源
`base_category`	接口分类	跨分组的横向标签
`base_api_test_case`	自动化测试用例	按 `api_id + env_code` 组织，保存请求快照、断言与最近执行结果
`base_api_mock_rule`	Mock 规则	按 `api_id + env_code` 配置，含优先级、延迟、状态码、响应体与匹配条件
`base_api_log`	接口调用日志	请求/响应、耗时、状态码、traceId、应用与发布版本；未启用 ES 时的主要日志存储

设计要点：

表	作用	关键字段 / 约束
`base_app`	调用方应用	`app_code` 唯一；`app_key/app_secret`；`ips` 凭证级 IP 白名单；`scope` 为 `api/project`；`mcp_enabled`
`base_app_api`	应用-接口授权	`(project_id, api_id, app_id, grant_source)` 唯一；`grant_type` 永久/有效期；关联审批单
`base_audit`	调用审批单	审批类型、状态 `process/pass/reject/revoke`、认证方式、有效期、日限额
`base_subscription`	订阅	状态 `pending/active/expired/unsubscribed/frozen`；生效起止、日限额、提醒级别
`base_ip_rule`	IP 访问控制规则	环境、黑白名单类型、IP 列表；通过 `base_rule_api` 绑定接口
`base_rule_api`	规则-接口绑定	`ruleType` 区分 `flow/degrade/cache/ip/warn`；`api_id + env_code`
`base_flow_rule`	流控规则	环境、QPS 阈值、规则名
`base_degrade_rule`	熔断规则	慢调用比例 / 异常比例 / 异常数、时间窗口、最小请求数、熔断时长
`base_cache_rule`	接口缓存规则	过期时间、最大响应体、缓存 Key 规则
`base_warn_rule`	告警规则	告警类型、比较条件、阈值、时间窗口、最小请求数、通知方式与频率
`base_warn_record`	告警记录	触发值、发送状态、关联日志与 traceId

授权模型：应用获得接口调用权限有两条路径——手工授权（grant_source=manual）与审批通过（grant_source=audit）。订阅是另一层「按接口订阅 + 配额」的控制，独立于应用授权；运行时两者都会校验。

表	作用	关键字段 / 约束
`base_ai_agent`	智能体配置	`agent_code` 唯一；`api_key_hash` 只存 SHA-256 哈希，`api_key_prefix` 用于展示
`base_ai_agent_tool`	智能体可用工具	`(agent_id, tool_code)` 唯一；控制读写权限与启用状态
`base_ai_conversation`	会话	会话归属、场景、状态
`base_ai_agent_turn`	对话轮次	一轮问答的输入、SQL、结果、耗时、成功状态
`base_ai_agent_message`	轮次内消息	`(conversation_id, turn_id, seq)` 唯一；保存用户/助手/工具消息
`base_ai_agent_session_state`	会话运行态	待确认操作、上下文状态，支持多轮确认
`base_ai_audit_log`	AI 调用审计	动作、问题、Token、耗时、成功状态；异步写入
`base_ai_agent_call_log`	工具调用日志	工具名、入参、结果、耗时
`base_ai_semantic_term`	语义层术语	业务词 → 表/字段/口径
`base_ai_semantic_metric`	语义层指标	指标公式、维度、过滤条件

设计要点：智能体密钥只保存哈希，创建后无法再次查看明文；会话与轮次分离，便于按轮次统计成功率；session_state 支撑「生成 SQL → 用户确认 → 执行」的确认卡片流程。

发布链路还会对版本族根接口加行锁（lockVersionRoot），保证多实例并发发布时修订号不冲突。

生产环境建议对 base_api_log、base_ai_audit_log、base_ai_agent_message 设置分区或定期归档，避免单表无限增长。