主题
AI引擎底座 · 数据库设计
文档版本：3.01 ｜ 最近核对日期：2026-11-10
1. 范围与核验状态
首期未新增平台业务表：模块映射（前端配置）、智能体环境绑定（.env）、路A白名单（catalog.json）均为版本化配置；模型、会话、知识库和短期记忆复用 SnailAI 存储（SAI_* 表，与平台同库）。路A专用只读账号 DCP_MCP_PUBLIC（仅 CREATE SESSION + PUBLIC + 3 表 SELECT，2026-11-10 经纳管入口创建并回读）。
2026-11-10 开发库新增测试数据（B03 用例）：角色 AI路B权限测试（ai_b03_test）、用户 ai_b03_test#01（15号线整线授权、无工程菜单权限）。属测试资产，后续可清理，不构成业务表结构变更。
2026-11-08历史回读记录：开发库已有AI引擎底座、AI控制台、AI会话菜单，两个子菜单权限码为空。该记录不证明当前库状态；本轮未回读数据库、未执行DDL/DML。菜单及角色关系归系统设置数据库设计。
SnailAI实际表、字段、索引、向量存储结构尚未逐项回读。本页不构成其全库物理结构验收。新增视图/字段/表时按数据库设计特别检查补齐对应实际字段矩阵及差异，不以逻辑配置表代替。
2. 数据归属与关系
| 数据 | 权威来源 | 首期处理 |
|---|---|---|
| 平台userId、登录、角色、动作权限 | 平台用户及认证服务 | 查询时验证，不复制一套AI权限表 |
| openId、externalId、内部用户ID | SnailAI OpenAPI映射 | externalId对应平台userId字符串；三个ID不互换 |
| 智能体、会话、消息 | SnailAI | conversation同时匹配内部用户和agent |
| 工程业务与授权表 | 工程基础业务模块 | 路B复用服务；路A不直接开放 |
| 知识文档与向量 | SnailAI实际检索存储 | 按模块绑定，不另建向量平台 |
| 来源及发布记录 | 版本化清单及SnailAI文档标识 | 记录版本、摘要、索引结果，不复制业务规则正文 |
| 公共数据对象 | 原业务所属模块 | 必要时固定裁剪视图，不复制业务库 |
逻辑关系：平台userId → externalId → 指定appId下的openId/内部用户 → 该用户与智能体的会话。工程授权仍以平台userId为主体，appId不是个人或工程范围标识。
3. 模块绑定配置（拟实施）
| 字段 | 逻辑类型 | 必需 | 约束及来源 |
|---|---|---|---|
| moduleKey | string | 是 | 首期engineering-foundation |
| displayName | string | 是 | 工程基础管理 |
| componentKeys | string[] | 是 | 精确组件标识，见详细设计，不存猜测URL |
| agentKey | string | 是 | 跨环境稳定逻辑标识 |
| agentId | string | 启用时是 | 环境实际智能体ID，不丢大整数精度 |
| knowledgeBaseId | string | 启用时是 | 依赖返回的真实知识库标识 |
| enabled | boolean | 是 | 未配置/未验证false，不授予业务权限 |
前端只需展示与路由字段，知识库绑定由服务/控制台管理，无需全部下发。字段不要求集中在一个配置文件。物理ID不得硬编码为另一环境值。
4. 语料清单字段（拟实施）
| 字段 | 类型 | 含义与约束 |
|---|---|---|
| moduleKey | string | 知识所属模块 |
| sourcePath | string | 仓库相对路径，不含本机绝对路径 |
| sourceVersion | string | 文档两位小数版本 |
| sourceRevision | string | 来源提交或明确工作区摘要 |
| contentHash | string | 规范化输入内容摘要，发现内容变化，不代替业务版本 |
| sections | string[] | 纳入章节，历史/冲突章节不纳入 |
| knowledgeDocumentIds | string[] | 实际导入返回ID，不提前编造 |
| batchId | string | 联系本次解析、索引与回归的标识 |
| activatedAt | datetime/null | 实际生效时间，未就绪为空 |
| result | string | 待处理、成功或失败及必要原因 |
首期受控清单即可，不要求建表。短期会话记忆不能承担来源版本管理。原始截图/日志按过程产物规则存放，不挤入版本清单。
5. 路A目录字段（已实现于 catalog.json）
| 字段 | 类型 | 约束 |
|---|---|---|
| object | string | 精确模式名与对象名，无通配符 |
| objectType | enum | 实际TABLE或VIEW |
| description / grain | string | 业务含义及一行代表什么 |
| columns | object[] | 允许列、实际类型、中文含义、单位、空值、枚举；全部可引用列都登记 |
| relations | object[] | 允许关联对象、键、基数，无需要则空 |
| fixedScope | string | 固定公共行范围与逻辑删除口径；优先视图落实 |
| allowFullAggregate | boolean | 默认false，小对象验证后才允许 |
| maxRows / maxBytes / timeoutSeconds | integer | 服务端限制，可统一默认，不重复配置 |
| schemaVersion | string | 目录版本，与实际结构一起核验 |
| approvalBasis | string | 公开依据与受众，不能仅写“无工程过滤” |
连接凭据和工具服务认证不进入模型schema。目录同时驱动schema暴露和SQL校验。首期准入对象（版本 2026-11-10.1）：BIZ_MAJOR_DICT（29 行，公共列白名单，审计列不入目录）、SYS_DICT_TYPE（71 行）、SYS_DICT_DATA（277 行，含批准关联 DICT_TYPE 1:N）；公开依据与受众、体量均经开发库实际核对（见 catalog.json approvalBasis）。行数上限/超时由服务端统一配置，不逐对象重复。
6. 对象准入与注释治理
- 使用纳管入口核实环境、模式、对象、用途。本轮不访问生产。
- 核对实际列、类型、长度、空值、默认值、注释、主键、索引、逻辑删除及依赖对象。
- 对照模块需求和实际服务确认粒度、枚举、单位；STATUS/TYPE/AMOUNT等列不能只按英文猜义。
- 确认所有工具调用者可读的行列。部分公开则建立固定视图，只授视图SELECT，不授底表。
- 记录体量、代表查询执行计划/耗时；视图仍需检查底层扫描成本。
- 注释和视图变更经纳管入口执行，写后回读；不在仓库新增业务SQL文件。
- 目录、SQL规则和数据库授权同步核对，正常与拒绝样例通过后启用。
对每个实际新建/修改对象补字段矩阵：列名、中文业务含义、逻辑/物理类型、长度精度、可空性、默认值、主外键/唯一约束、索引、来源及核验状态。未确认的列不准入。逻辑过滤条件只能作为公开范围，不能模拟动态工程权限。
7. 身份、存储与缓存
委托凭据仅在可信服务间传输，主体权限按当前实际状态查询。模型Key、服务令牌不进入语料、向量、工具参数或结果。配置存放遵循私有配置，不在本模块另建凭据入库禁令。
首期不建设跨用户业务结果缓存。SnailAI已有缓存/记忆需核实隔离键；“存在数据库”不证明用户与agent隔离。正文、附件、历史消息同样受可见范围约束。会话ID由既有服务机制产生，不能用平台userId替代。
8. 开发与生产变更
本轮开发库变更：路A只读账号及 3 表授权；B03 测试角色/用户/授权（测试资产）。SnailAI 知识库（ragId=3）、智能体（工程基础 agentId=4、通用 agentId=5）、MCP 服务器配置（路A/路B）为 dev 环境数据；生产部署时按环境独立创建，物理 ID 不跨环境复制（前端 agentId 经 .env 环境注入）。后续待发布清单：生产环境建只读账号与授权、SnailAI 生产库智能体/知识库/MCP 配置、前端 .env.production agentId 填入、委托密钥生产覆盖。
普通AI建设不属于Warm-Flow流程定义双库例外；开发授权不自动允许生产访问或发布。若确需新增平台表，先说明配置/SnailAI存储为何不能承载，再补全字段、继承审计列、索引及真实读写验证。
9. 四能力数据影响（未设计，本轮无结构变更）
2026-11-10 需求方确认智办、智审、智控、智管四类能力；本节只界定数据设计边界，不表示已新增表、字段或接口，本轮未执行 DDL/DML。
| 能力 | 已有数据基础 | 后续可能的数据需求 | 设计门槛 |
|---|---|---|---|
| 智办 | SAI_* 会话/消息/知识/智能体；模块映射与 agentId 为配置；路A目录为 catalog.json | 扩模块时按模块新增语料/智能体环境绑定；不复制环境物理 ID | 沿用现有归属；新增模块先核语料和授权 |
| 智审 | 审批任务、表单、附件、流程历史归 Warm-Flow 与业务模块 | 审查建议、依据引用、审批人反馈、模型/提示词/知识版本、建议与最终决定的关联 | 本期不实施；确认后先定数据归属（平台审计表或业务表）、保留期、权限和敏感材料处理；不得把完整附件复制进 AI 表 |
| 智管 | 用户、角色、组织、数据范围、授权、流程定义均有既有权威表和服务 | 运维意图、目标解析、影响预览、确认/审批、执行回执、变更前后值和失败恢复记录；专用读写 MCP（候选）的调用审计和事务回执 | 先确认风险分级、确认/审批矩阵、在途实例保护和审计保留；优先复用既有服务；若建专用读写 MCP，明确库账号、白名单、事务、权限、回读和审计，不接受模型自由 SQL |
| 智控 | 主数据、进度与手续数据、业务数据、流程状态、组织/权限由平台和业务模块维护 | 佳都的数据/接口交换、风险预警分析所需数据、调用审计、限流和 SLA 记录；不新增平台业务表 | 先确认数据/接口清单、风险场景、最小权限、脱敏和审计；佳都不直连生产库、不共享应用账号 |
数据设计原则：
- AI 会话与知识数据不能替代业务主数据；审批结论、用户权限、流程定义仍以各自权威表和服务为准。
- 智审/智管的建议、确认和回执必须可追溯到发起人、目标、依据版本、时间和结果；敏感内容最小化，不记录凭据。
- 智管的执行记录不能作为业务变更的唯一事实源；以既有服务或受控 MCP 回读的实际状态为准，失败时保留恢复依据。
- 智控只通过接口/数据服务交换，不复制生产库；接口调用审计和限流数据归平台或接口网关，具体表结构待方案确认。
- 上述能力进入设计时，按数据库设计特别检查补齐实际字段矩阵、索引、约束、权限和回读证据，不以逻辑配置或会话记录代替。