# 数据库设计 **本文引用的文件** - [sql/gateway.sql](file://sql/gateway.sql) - [sql/user.sql](file://sql/user.sql) - [sql/agent_expert.sql](file://sql/agent_expert.sql) - [sql/agent_tool.sql](file://sql/agent_tool.sql) - [sql/chat_attachment.sql](file://sql/chat_attachment.sql) - [sql/ai_clean.sql](file://sql/ai_clean.sql) - [sql/ai_clean_field_short_names.sql](file://sql/ai_clean_field_short_names.sql) - [sql/ai_clean_row_stats.sql](file://sql/ai_clean_row_stats.sql) - [sql/ai_clean_synonym_init.sql](file://sql/ai_clean_synonym_init.sql) - [sql/ai_clean_template_drop_case_src.sql](file://sql/ai_clean_template_drop_case_src.sql) - [sql/case_table.sql](file://sql/case_table.sql) - [sql/external_tables.sql](file://sql/external_tables.sql) - [sql/external_table_field.sql](file://sql/external_table_field.sql) - [sql/insight_agent_tables.sql](file://sql/insight_agent_tables.sql) - [sql/insight_agent_tables_align.sql](file://sql/insight_agent_tables_align.sql) - [sql/plat.sql](file://sql/plat.sql) ## 目录 1. [引言](#引言) 2. [项目结构与数据边界](#项目结构与数据边界) 3. [核心业务域与表结构](#核心业务域与表结构) 4. [架构总览](#架构总览) 5. [详细组件分析](#详细组件分析) 6. [依赖关系分析](#依赖关系分析) 7. [初始化脚本执行顺序与迁移规范](#初始化脚本执行顺序与迁移规范) 8. [性能与索引建议](#性能与索引建议) 9. [数据安全、访问控制与备份恢复](#数据安全访问控制与备份恢复) 10. [故障排查指南](#故障排查指南) 11. [结论](#结论) ## 引言 本设计文档梳理本项目在 PostgreSQL 主库中的持久化数据结构,覆盖网关路由、用户与授权、Agent 专家与工具、聊天附件、清洗模板与同义词、行统计、案件动态表、外部数据表、研判会话消息、平台元数据等。同时说明 pgvector 向量表与 DuckDB 临时数据源的用途差异,给出 ER 关系图、关键字段定义、主外键、索引约束和业务规则,并补充初始化顺序、迁移规范和回滚注意事项。 ## 项目结构与数据边界 项目 SQL 脚本集中在 `sql/` 目录,按业务功能拆分: - 网关路由:`gateway.sql` - 用户体系与案件归属:`user.sql` - Agent 专家与工具:`agent_expert.sql`、`agent_tool.sql` - 聊天附件:`chat_attachment.sql` - AI 清洗链路:`ai_clean.sql`、`ai_clean_field_short_names.sql`、`ai_clean_row_stats.sql`、`ai_clean_synonym_init.sql`、`ai_clean_template_drop_case_src.sql` - 案件动态表:`case_table.sql`、`create_table_2.sql` - 外部数据表:`external_tables.sql`、`external_table_field.sql` - 研判会话消息:`insight_agent_tables.sql`、`insight_agent_tables_align.sql` - 平台元数据:`plat.sql` ```mermaid graph TB PG["PostgreSQL 主库"] subgraph "系统配置" GW["gateway_service / gateway_node
gateway_user_route"] SYS["sys_user"] AG["agent
agent_tool"] end subgraph "对话与附件" ATT["chat_attachment"] INS_S["agent_insight_session"] INS_M["agent_insight_message"] end subgraph "AI 清洗" TPL["ai_clean_template / ai_clean_field"] RULE["ai_clean_rule"] JOB["ai_clean_job / ai_clean_batch"] SYN["ai_clean_synonym"] end subgraph "案件数据" CT["case_table.*
DuckDB 动态表"] EXT["external_tables.*
DuckDB 外部数据"] end subgraph "平台元数据" PLAT["plat.sql 中的 table_info / table_field
chat_session / chat_model 等"] end SYS --> GW SYS --> INS_S SYS --> JOB SYS --> ATT TPL --> JOB RULE --> JOB SYN --> TPL ATT --> INS_M CT --> PLAT EXT --> PLAT ``` **图表来源** - [sql/gateway.sql:1-107](file://sql/gateway.sql#L1-L107) - [sql/user.sql:1-75](file://sql/user.sql#L1-L75) - [sql/agent_expert.sql:1-47](file://sql/agent_expert.sql#L1-L47) - [sql/agent_tool.sql:1-52](file://sql/agent_tool.sql#L1-L52) - [sql/chat_attachment.sql:1-39](file://sql/chat_attachment.sql#L1-L39) - [sql/ai_clean.sql:1-214](file://sql/ai_clean.sql#L1-L214) - [sql/insight_agent_tables.sql:1-107](file://sql/insight_agent_tables.sql#L1-L107) - [sql/case_table.sql:1-200](file://sql/case_table.sql#L1-L200) - [sql/external_tables.sql:1-200](file://sql/external_tables.sql#L1-L200) - [sql/plat.sql:1-154](file://sql/plat.sql#L1-L154) **章节来源** - [sql/gateway.sql:1-107](file://sql/gateway.sql#L1-L107) - [sql/user.sql:1-75](file://sql/user.sql#L1-L75) - [sql/agent_expert.sql:1-47](file://sql/agent_expert.sql#L1-L47) - [sql/agent_tool.sql:1-52](file://sql/agent_tool.sql#L1-L52) - [sql/chat_attachment.sql:1-39](file://sql/chat_attachment.sql#L1-L39) - [sql/ai_clean.sql:1-214](file://sql/ai_clean.sql#L1-L214) - [sql/insight_agent_tables.sql:1-107](file://sql/insight_agent_tables.sql#L1-L107) - [sql/case_table.sql:1-200](file://sql/case_table.sql#L1-L200) - [sql/external_tables.sql:1-200](file://sql/external_tables.sql#L1-L200) - [sql/plat.sql:1-154](file://sql/plat.sql#L1-L154) ## 核心业务域与表结构 ### 网关服务与节点 | 表名 | 主键 | 关键字段 | 约束与索引 | 业务含义 | |---|---|---|---|---| | `gateway_service` | `id VARCHAR(64)` | `name`、`path_prefix`、`login_path`、`health_path`、`default_node_id`、`enabled` | `path_prefix` 唯一;`enabled` 默认 1 | 一个对外路径前缀对应一组后端节点,首次启动可从配置播种 | | `gateway_node` | `id VARCHAR(64)` | `service_id`、`name`、`base_url`、`enabled` | `service_id + base_url` 唯一;外键指向 `gateway_service.id` | 一台后端 ai-server 实例 | | `gateway_user_route` | `id BIGSERIAL` | `service_id`、`user_id`、`username`、`node_id` | `ck_gateway_user_route_owner` 保证至少一个用户标识;部分唯一索引分别约束 `user_id` 和 `lower(username)`;`node_id` 有普通索引;两个外键分别指向服务和节点 | 用户粘性绑定到某个节点,不可用时返回 503,不自动切换 | 业务规则: - `path_prefix` 全局唯一,不能以 `/` 结尾,且不是 `/gateway`。 - `base_url` 不含上下文路径,同一服务内地址必须唯一。 - 用户绑定支持先按用户名预绑定,再关联真实用户 ID。 **章节来源** - [sql/gateway.sql:1-107](file://sql/gateway.sql#L1-L107) ### 用户与授权 | 表名 | 主键 | 关键字段 | 约束与索引 | 业务含义 | |---|---|---|---|---| | `sys_user` | `id BIGSERIAL` | `username`、`pwd_hash`、`display_name`、`is_admin`、`status`、`last_login_time` | `lower(username)` 唯一;`is_admin` 仅控制是否可调用用户管理接口;`status` 默认启用 | 系统认证用户,不实现角色菜单权限体系 | | `case_info` | `id INTEGER`(自增) | `owner_id BIGINT`(新增列) | 对 `owner_id` 建索引 | 案件归属用户,仅创建者可见;存量未归属案件统一归给内置管理员 | 注意: - 本项目明确不做 `sys_role`、`sys_menu`、`sys_permission`、`sys_user_role` 等完整权限体系。 - `case_info.owner_id` 是应用层“允许同名案件”的归属边界,数据库侧只加索引,不加唯一约束。 **章节来源** - [sql/user.sql:1-75](file://sql/user.sql#L1-L75) ### Agent 专家与工具 | 表名 | 主键 | 关键字段 | 约束与索引 | 业务含义 | |---|---|---|---|---| | `agent` | `row_id`(通过脚本补主键) | `user_id`、`is_builtin`、`skills_allow_json`、`tools_allow_json` | `user_id` 有索引;内置专家全局可见不可编辑;非内置专家按创建者隔离 | 智能体配置,内置标记区分平台级和用户级 | | `agent_tool` | `id BIGINT` | `tool_name`、`tool_class`、`tool_method`、`group_code`、`parameters`、`status` | `tool_name` 唯一;`status` 取 ACTIVE 或 DELETED | 启动时反射扫描 @Tool 后 upsert 的工具清单,页面只读 | 业务规则: - 内置专家 `is_builtin=1`,归属平台管理员;用户自建专家 `is_builtin=0`,按 `user_id` 过滤。 - 已删除代码中的工具保留行,状态置为 DELETED,便于追溯。 - 脚本会修复历史重复主键、对齐序列,并补主键约束。 **章节来源** - [sql/agent_expert.sql:1-47](file://sql/agent_expert.sql#L1-L47) - [sql/agent_tool.sql:1-52](file://sql/agent_tool.sql#L1-L52) ### 聊天附件 | 表名 | 主键 | 关键字段 | 约束与索引 | 业务含义 | |---|---|---|---|---| | `chat_attachment` | `id BIGINT` | `user_id`、`case_id`、`session_id`、`file_name`、`file_path`、`sidecar_path`、`mime`、`kind`、`size_bytes`、`char_count`、`row_count`、`truncated`、`inline_text`、`index_blocks`、`index_status`、`link_message_id`、`fail_reason` | 索引:`session_id`、`status+link_message_id` | 附件问答三路的元数据锚点:内联文本、Python 直读文件、RAG 分块向量化 | 业务规则: - 三路处理:A 内联小文档、B Python 大表格、C RAG 大文档。 - 加载时必须校验 `user_id/case_id/session_id` 三重归属。 - RAG 向量侧另按会话过滤,检索 SQL 强制带 `sessionId`。 **章节来源** - [sql/chat_attachment.sql:1-39](file://sql/chat_attachment.sql#L1-L39) ### 清洗模板、字段、规则与任务 | 表名 | 主键 | 关键字段 | 约束与索引 | 业务含义 | |---|---|---|---|---| | `ai_clean_template` | `id BIGINT` | `table_name_cn`、`table_name_en`、`headers`、`header_md5`、`func_regex`、`struct_ops`、`needs_struct`、`category`、`match_tier`、`status`、`ver`、`confidence` | `header_md5` 唯一;`status`、`category` 有索引 | AI 模板,等价于既有 `table_info`,但完全独立存储 | | `ai_clean_field` | `id BIGINT` | `ai_template_id`、`column_name`、`field_name_cn`、`field_name_en`、`field_type`、`required`、`field_len`、`field_sort`、`col_index`、`matched` | 按 `ai_template_id` 索引 | 动态表 DDL 真源,物理列固定为 `c0/c1/…` | | `ai_clean_rule` | `id BIGINT` | `ai_template_id`、`col_index`、`field_name_en`、`hints`、`ref_template_id` | 按 `ai_template_id` 索引 | 扁平枚举 hint 的规则快照,避免反序列化任意类 | | `ai_clean_job` | `id BIGINT` | `case_id`、`file_id`、`sheet_id`、`block_no`、`ver`、`status`、`exit_code`、`token_in/out`、`cost_ms`、`row_total/loaded/rejected/warned/unprocessed` | 唯一键 `(case_id, file_id, sheet_id, block_no, ver)`;`status`、`file_id` 有索引 | 幂等游标 + 状态线 + 成本埋点 | | `ai_clean_batch` | `id BIGINT` | `case_id`、`batch_id`、`stage`、`file_count`、`sheet_total`、`matched_count`、`ai_judged_count`、`loaded_rows`、`rejected_rows`、`unprocessed_rows`、`self_built_count` | 唯一键 `(case_id, batch_id)`;`stage` 有索引 | 智能清洗批次状态机 | | `ai_clean_synonym` | `id BIGINT` | `std_word`、`alias_word`、`remark`、`status` | `(std_word, alias_word)` 唯一 | 表头同义词星型词组,用于评分和绑定域 | 重要变更: - `ai_clean_field.column_name` 与 `field_name_en` 统一为 `c{位置}`,宽度收窄为 `VARCHAR(5)`。 - 新增行统计列:`job.row_rejected`、`job.row_warned`、`job.row_unprocessed`,以及 `batch.loaded_rows`、`rejected_rows`、`unprocessed_rows`、`self_built_count`。 - 同义词表可通过管理接口运行期维护,内置词条由初始化脚本填充。 - 模板不再记录 `case_id_src`,跨案件共享。 **章节来源** - [sql/ai_clean.sql:1-214](file://sql/ai_clean.sql#L1-L214) - [sql/ai_clean_field_short_names.sql:1-16](file://sql/ai_clean_field_short_names.sql#L1-L16) - [sql/ai_clean_row_stats.sql:1-21](file://sql/ai_clean_row_stats.sql#L1-L21) - [sql/ai_clean_synonym_init.sql:1-42](file://sql/ai_clean_synonym_init.sql#L1-L42) - [sql/ai_clean_template_drop_case_src.sql:1-10](file://sql/ai_clean_template_drop_case_src.sql#L1-L10) ### 案件动态表 `case_table.sql` 中定义了多个案件相关表,例如: - `trans_record`、`trans_record_all`:交易流水 - `call_record`、`call_record_all`:通话记录 - `use_open_info_call_record`:开户信息通话记录 - `account_opening_info`:账户开户信息 这些表通常作为 DuckDB 临时数据源使用,包含高频定位列的索引约定,如姓名、身份证号、卡号、手机号、证件号等。 **章节来源** - [sql/case_table.sql:1-200](file://sql/case_table.sql#L1-L200) ### 外部数据表 `external_tables.sql` 描述来自“表结构信息.txt”的外部数据表,包括: - `cert_info`:出入境证件信息 - `entry_rec`:出入境记录 - `vehicle_info`:机动车信息 - `lic_info`:驾驶证信息 - `veh_violation`:机动车违章 - `household`:同户人 - `co_resident`:同住址 - `co_veh_viol`:同车违章 - `criminal`:违法犯罪人员信息 这些表与 `external_table_field.sql` 一起,映射到平台 `table_info` 与 `table_field`,用于外部数据语义检索。 **章节来源** - [sql/external_tables.sql:1-200](file://sql/external_tables.sql#L1-L200) - [sql/external_table_field.sql:1-80](file://sql/external_table_field.sql#L1-L80) ### 研判会话与消息 | 表名 | 主键 | 关键字段 | 约束与索引 | 业务含义 | |---|---|---|---|---| | `agent_insight_session` | `id BIGINT` | `case_id`、`biz_type`、`scope`、`agent_row_id`、`model_id`、`title`、`context`、`context_hash`、`sys_prompt`、`message_count`、`last_seq`、`total_tokens`、`last_message_at`、`pinned`、`status` | `case_id+biz_type+last_message_at` 列表索引;`case_id+context_hash` 复用索引 | 独立于通用对话表的研判会话,强制案件级隔离 | | `agent_insight_message` | `id BIGINT` | `session_id`、`case_id`、`seq`、`role`、`content`、`content_type`、`message_type`、`metadata`、`tool_events`、`output_json`、`token_count`、`reply_to_message_id`、`starred`、`status` | 唯一键 `(session_id, seq)`;外键级联删除会话;`case_id+create_at` 部分索引过滤结构化产物 | 研判消息,排序列必须是 `seq` | 注意: - 初次建表用 `insight_agent_tables.sql`;已有库需用 `insight_agent_tables_align.sql` 补齐约束与索引。 - `seq` 通过 `UPDATE ... RETURNING last_seq` 原子分配,禁止 `SELECT MAX(seq)+1`。 **章节来源** - [sql/insight_agent_tables.sql:1-107](file://sql/insight_agent_tables.sql#L1-L107) - [sql/insight_agent_tables_align.sql:1-88](file://sql/insight_agent_tables_align.sql#L1-L88) ### 平台元数据 `plat.sql` 包含一些平台基础表和旧版聊天元数据,例如: - `bank_card_issuer_info`:银行卡发卡方 - `case_info`:案件基础信息 - `phone_isp`:手机号运营商归属 - `system_info`:系统激活信息 - `table_info`、`table_field`:表与字段元数据 - `chat_message`、`chat_session`、`chat_model`、`chat_provider`、`knowledge_attach`、`knowledge_fragment`、`knowledge_info` 这些表与 AI 清洗、外部数据、图谱等业务配合,但不直接承载主业务流程的核心行数据。 **章节来源** - [sql/plat.sql:1-154](file://sql/plat.sql#L1-L154) ## 架构总览 ```mermaid erDiagram sys_user { bigint id PK varchar username varchar pwd_hash smallint is_admin smallint status timestamp last_login_time } gateway_service { varchar id PK varchar name varchar path_prefix UK varchar login_path varchar health_path varchar default_node_id smallint enabled } gateway_node { varchar id PK varchar service_id FK varchar name varchar base_url smallint enabled } gateway_user_route { bigint id PK varchar service_id FK bigint user_id varchar username varchar node_id FK } agent { bigint row_id PK bigint user_id smallint is_builtin text skills_allow_json text tools_allow_json } agent_tool { bigint id PK varchar tool_name UK varchar tool_class varchar tool_method varchar group_code jsonb parameters varchar status } chat_attachment { bigint id PK bigint user_id bigint case_id bigint session_id varchar file_name varchar file_path varchar kind integer row_count varchar status } ai_clean_template { bigint id PK varchar header_md5 UK varchar table_name_en varchar status numeric confidence } ai_clean_field { bigint id PK bigint ai_template_id varchar column_name varchar field_name_en varchar field_type } ai_clean_rule { bigint id PK bigint ai_template_id integer col_index text hints } ai_clean_job { bigint id PK bigint case_id bigint file_id bigint sheet_id integer block_no integer ver varchar status integer row_rejected integer row_warned integer row_unprocessed } ai_clean_batch { bigint id PK bigint case_id bigint batch_id varchar stage bigint loaded_rows bigint rejected_rows bigint unprocessed_rows } ai_clean_synonym { bigint id PK varchar std_word varchar alias_word } agent_insight_session { bigint id PK bigint case_id varchar biz_type bigint model_id jsonb context varchar context_hash bigint last_seq varchar status } agent_insight_message { bigint id PK bigint session_id FK bigint case_id bigint seq varchar role jsonb output_json varchar status } sys_user ||--o{ gateway_user_route : "绑定" gateway_service ||--o{ gateway_node : "包含" gateway_service ||--o{ gateway_user_route : "路由范围" agent ||--o{ agent_insight_session : "可选使用" ai_clean_template ||--o{ ai_clean_field : "包含字段" ai_clean_template ||--o{ ai_clean_rule : "包含规则" ai_clean_job ||--o{ ai_clean_batch : "属于批次" agent_insight_session ||--o{ agent_insight_message : "包含消息" chat_attachment ||--o{ agent_insight_message : "可选关联" ``` **图表来源** - [sql/gateway.sql:1-107](file://sql/gateway.sql#L1-L107) - [sql/user.sql:1-75](file://sql/user.sql#L1-L75) - [sql/agent_expert.sql:1-47](file://sql/agent_expert.sql#L1-L47) - [sql/agent_tool.sql:1-52](file://sql/agent_tool.sql#L1-L52) - [sql/chat_attachment.sql:1-39](file://sql/chat_attachment.sql#L1-L39) - [sql/ai_clean.sql:1-214](file://sql/ai_clean.sql#L1-L214) - [sql/insight_agent_tables.sql:1-107](file://sql/insight_agent_tables.sql#L1-L107) ## 详细组件分析 ### 网关粘性路由流程 ```mermaid sequenceDiagram participant Client as "客户端" participant Gateway as "ai-gateway" participant Service as "gateway_service" participant Node as "gateway_node" participant Route as "gateway_user_route" participant Server as "ai-server 实例" Client->>Gateway: "请求 /js/a/... 路径" Gateway->>Service: "根据 path_prefix 查找服务" Service-->>Gateway: "返回服务配置" Gateway->>Route: "按 user_id 或 lower(username) 查绑定" Route-->>Gateway: "返回 node_id" Gateway->>Node: "检查节点可用" alt "节点可用" Gateway->>Server: "转发原始路径" Server-->>Client: "响应" else "节点不可用" Gateway-->>Client: "返回 503" end ``` **图表来源** - [sql/gateway.sql:1-107](file://sql/gateway.sql#L1-L107) **章节来源** - [sql/gateway.sql:1-107](file://sql/gateway.sql#L1-L107) ### 清洗模板匹配与入库流程 ```mermaid flowchart TD Start(["上传文件"]) --> Parse["解析表头与内容"] Parse --> Fingerprint["计算 header_md5"] Fingerprint --> Match{"命中既有模板?"} Match -->|是| Existing["走出口 A:复用既有模板"] Match -->|否| LLM["调用模型判定结构"] LLM --> SaveTpl["保存 ai_clean_template / ai_clean_field"] SaveTpl --> Rule["生成 ai_clean_rule"] Rule --> Job["写入 ai_clean_job"] Existing --> Batch["写入 ai_clean_batch"] Rule --> Batch Batch --> Validate["逐行校验类型/必填/长度"] Validate --> Load{"是否通过"} Load -->|是| Insert["写入 DuckDB 动态表"] Load -->|否| Reject["计入 rejected_rows / row_rejected"] Insert --> Done(["批次完成"]) Reject --> Partial["部分成功"] Partial --> Done ``` **图表来源** - [sql/ai_clean.sql:1-214](file://sql/ai_clean.sql#L1-L214) **章节来源** - [sql/ai_clean.sql:1-214](file://sql/ai_clean.sql#L1-L214) ### 研判会话消息写入流程 ```mermaid sequenceDiagram participant User as "用户" participant Session as "agent_insight_session" participant Message as "agent_insight_message" participant DB as "PostgreSQL" User->>Session: "发起研判会话" Session->>DB: "INSERT session (case_id, biz_type, context)" DB-->>Session: "返回 session.id" User->>Message: "发送消息" Message->>DB: "UPDATE session SET last_seq = last_seq + 1 RETURNING last_seq" DB-->>Message: "返回 seq" Message->>DB: "INSERT message (session_id, case_id, seq, role, content)" DB-->>User: "返回消息结果" ``` **图表来源** - [sql/insight_agent_tables.sql:1-107](file://sql/insight_agent_tables.sql#L1-L107) - [sql/insight_agent_tables_align.sql:1-88](file://sql/insight_agent_tables_align.sql#L1-L88) **章节来源** - [sql/insight_agent_tables.sql:1-107](file://sql/insight_agent_tables.sql#L1-L107) - [sql/insight_agent_tables_align.sql:1-88](file://sql/insight_agent_tables_align.sql#L1-L88) ## 依赖关系分析 ```mermaid graph LR SYS["sys_user"] --> GWU["gateway_user_route"] GWS["gateway_service"] --> GWN["gateway_node"] GWS --> GWU GWN --> GWU AG["agent"] --> INS_S["agent_insight_session"] TPL["ai_clean_template"] --> FL["ai_clean_field"] TPL --> RU["ai_clean_rule"] TPL --> JB["ai_clean_job"] SY["ai_clean_synonym"] --> TPL JB --> BA["ai_clean_batch"] ATT["chat_attachment"] --> INS_M["agent_insight_message"] INS_S --> INS_M CT["case_table.*"] --> PT["platform meta"] EX["external_tables.*"] --> PT ``` **图表来源** - [sql/gateway.sql:1-107](file://sql/gateway.sql#L1-L107) - [sql/user.sql:1-75](file://sql/user.sql#L1-L75) - [sql/agent_expert.sql:1-47](file://sql/agent_expert.sql#L1-L47) - [sql/ai_clean.sql:1-214](file://sql/ai_clean.sql#L1-L214) - [sql/insight_agent_tables.sql:1-107](file://sql/insight_agent_tables.sql#L1-L107) - [sql/chat_attachment.sql:1-39](file://sql/chat_attachment.sql#L1-L39) **章节来源** - [sql/gateway.sql:1-107](file://sql/gateway.sql#L1-L107) - [sql/user.sql:1-75](file://sql/user.sql#L1-L75) - [sql/agent_expert.sql:1-47](file://sql/agent_expert.sql#L1-L47) - [sql/ai_clean.sql:1-214](file://sql/ai_clean.sql#L1-L214) - [sql/insight_agent_tables.sql:1-107](file://sql/insight_agent_tables.sql#L1-L107) - [sql/chat_attachment.sql:1-39](file://sql/chat_attachment.sql#L1-L39) ## 初始化脚本执行顺序与迁移规范 ### 推荐执行顺序 1. **平台元数据**:`plat.sql` - 建立 `table_info`、`table_field`、`case_info`、`chat_*`、`knowledge_*` 等基础表。 2. **用户体系**:`user.sql` - 创建 `sys_user`,插入内置管理员,为 `case_info` 添加 `owner_id` 并回填。 3. **网关路由**:`gateway.sql` - 创建 `gateway_service`、`gateway_node`、`gateway_user_route`,并建立外键与索引。 4. **Agent 专家**:`agent_expert.sql` - 补齐 `agent.user_id`、`is_builtin`、主键、序列和对齐逻辑。 5. **Agent 工具清单**:`agent_tool.sql` - 人工执行一次,后续由应用启动反射同步。 6. **AI 清洗链路**:`ai_clean.sql` - 创建模板、字段、规则、任务、批次、同义词表。 7. **清洗字段列宽修正**:`ai_clean_field_short_names.sql` - 将历史 `field_name_en` 与 `column_name` 对齐为 `c{位置}`,收窄列宽。 8. **清洗行统计扩展**:`ai_clean_row_stats.sql` - 为 `ai_clean_job` 和 `ai_clean_batch` 增加行统计列。 9. **清洗同义词初始化**:`ai_clean_synonym_init.sql` - 为已有环境补建同义词表并插入内置词条。 10. **移除模板案件来源列**:`ai_clean_template_drop_case_src.sql` - 删除 `ai_clean_template.case_id_src`。 11. **研判会话与消息**:`insight_agent_tables.sql` - 空库首次建表;若表已存在,需继续执行对齐脚本。 12. **研判会话约束对齐**:`insight_agent_tables_align.sql` - 补齐 `uk_aim_session_seq`、`fk_aim_session`、列表索引、部分索引、注释。 13. **案件动态表**:`case_table.sql`、`create_table_2.sql` - 按需重建 DuckDB 临时表,注意主键和索引约定。 14. **外部数据表与字段映射**:`external_tables.sql`、`external_table_field.sql` - 创建外部数据表并写入 `table_info`、`table_field`。 ### 迁移规范 - 所有脚本均标注幂等性,优先使用 `CREATE TABLE IF NOT EXISTS`、`ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`DROP CONSTRAINT IF EXISTS`、`CREATE INDEX IF NOT EXISTS`。 - 涉及锁升级的约束修改(如唯一约束、外键)应设置 `lock_timeout`,避免长事务阻塞。 - 不要在生产环境直接执行 `DROP TABLE` 脚本;现有脚本多为测试或演示用途,实际部署应改用增量迁移。 - 对于 `agent_tool`,DDL 由人工执行一次,运行时只 upsert 数据。 - 对于 `insight_agent_tables`,已有库必须执行 `insight_agent_tables_align.sql`,否则缺失唯一约束和外键会导致孤儿消息。 ### 回滚注意事项 - 删除列或表前确认没有外键引用;当前多数外键为 `ON DELETE RESTRICT`,可直接阻止危险删除。 - 对 `agent` 主键修复和序列对齐脚本会清理脏数据,回滚前需备份。 - 清洗模板移除 `case_id_src` 后,不应再通过该列做案件归属判断。 - 同义词表初始化使用 `on conflict do nothing`,重复执行不会破坏数据。 - 研判消息 `seq` 的唯一约束由 `UPDATE ... RETURNING last_seq` 和唯一索引共同保障,回滚后重新执行对齐脚本即可。 **章节来源** - [sql/agent_tool.sql:1-52](file://sql/agent_tool.sql#L1-L52) - [sql/insight_agent_tables.sql:1-107](file://sql/insight_agent_tables.sql#L1-L107) - [sql/insight_agent_tables_align.sql:1-88](file://sql/insight_agent_tables_align.sql#L1-L88) - [sql/ai_clean_synonym_init.sql:1-42](file://sql/ai_clean_synonym_init.sql#L1-L42) - [sql/ai_clean_template_drop_case_src.sql:1-10](file://sql/ai_clean_template_drop_case_src.sql#L1-L10) ## 性能与索引建议 ### PostgreSQL 主库 - 网关路由: - `gateway_service.path_prefix` 唯一索引保证路径分发稳定。 - `gateway_user_route` 使用部分唯一索引分别约束 `user_id` 和 `lower(username)`,避免并发冲突。 - `node_id` 普通索引加速节点可用性查询。 - 用户与授权: - `sys_user.username` 使用 `lower()` 唯一索引,兼容大小写不敏感登录。 - `case_info.owner_id` 索引支持按归属用户过滤。 - Agent 工具: - `agent_tool.tool_name` 唯一索引防止模型调用落到错误实现。 - 清洗链路: - `ai_clean_template.header_md5` 唯一索引用于零模型重放。 - `ai_clean_job` 唯一键保证同一文件块只处理一次。 - `ai_clean_batch` 唯一键保证重复点击返回同一批次。 - `ai_clean_synonym` 唯一键防止标准词与别名组合重复。 - 研判会话: - `agent_insight_session` 列表索引按 `case_id`、`biz_type`、`last_message_at` 排序。 - `context_hash` 索引用于同条件复用。 - `agent_insight_message` 唯一键 `(session_id, seq)` 防重号。 - 部分索引 `idx_aim_output` 只索引有结构化产出的消息。 ### DuckDB 临时数据源 - 主要面向单案分析,利用 zonemap 和少量 ART 索引优化高频定位列。 - 时间、日期、金额等分析过滤依赖自动 zonemap,不建议盲目加索引。 - 仅对人、卡、账号、手机、证件号等高频筛选列建索引。 ### pgvector 向量表 - 聊天附件 RAG 路径 C 会为每个会话生成向量表,命名约定为 `chat_att_vec_{caseId}_d{dims}`。 - 向量检索必须强制带 `sessionId`,避免跨会话泄露。 - 向量表不在仓库 DDL 中显式声明,而是按维度动态生成;其生命周期与附件、会话、工作区强绑定。 **章节来源** - [sql/gateway.sql:1-107](file://sql/gateway.sql#L1-L107) - [sql/agent_tool.sql:1-52](file://sql/agent_tool.sql#L1-L52) - [sql/ai_clean.sql:1-214](file://sql/ai_clean.sql#L1-L214) - [sql/insight_agent_tables.sql:1-107](file://sql/insight_agent_tables.sql#L1-L107) - [sql/case_table.sql:1-200](file://sql/case_table.sql#L1-L200) - [sql/chat_attachment.sql:1-39](file://sql/chat_attachment.sql#L1-L39) ## 数据安全、访问控制与备份恢复 ### 数据安全 - 密码存储:`sys_user.pwd_hash` 使用 BCrypt 哈希,明文不得进入脚本或日志。 - 敏感字段:`chat_attachment.file_path`、`sidecar_path`、`inline_text` 可能包含隐私数据,应限制文件系统访问权限。 - 向量表:`chat_att_vec_{caseId}_d{dims}` 包含文档切片向量,应按会话隔离访问。 - 工具参数:`agent_tool.parameters` 存 JSON Schema,不应直接拼接执行。 - 清洗规则:`ai_clean_rule.hints` 使用枚举 hint,避免反序列化任意 Java 类。 - 研判提示词:`agent_insight_session.sys_prompt` 仅运维追溯,不通过接口下发。 ### 访问控制 - 用户权限:仅 `is_admin=1` 可调用用户管理接口,前端静态菜单仍由本地配置生成。 - 网关粘性:用户绑定节点失败时返回 503,不自动切换到其他节点,避免越权路由。 - 研判会话:所有查询强制携带 `case_id`,消息表冗余 `case_id` 以强化 SQL 层隔离。 - 附件加载:必须校验 `user_id/case_id/session_id`,任一不匹配即拒绝。 ### 备份恢复建议 - 主库: - 定期备份 `sys_user`、`gateway_*`、`agent`、`agent_tool`、`chat_attachment`、`ai_clean_*`、`agent_insight_*`。 - 重点保护 `pwd_hash`、`context`、`sys_prompt`、`tool_events`、`output_json` 等高价值或高敏感字段。 - 向量表: - 按会话维度备份,避免误删他人向量数据。 - 恢复时需重建对应 `d{dims}` 维度的向量表。 - DuckDB 临时表: - 一般可按案件重建;若需要离线分析,应单独归档原始文件和 DuckDB 数据文件。 - 迁移回滚: - 先停写,再回滚数据,最后执行反向 DDL。 - 对含外键的表,应先解除引用或删除子表数据。 **章节来源** - [sql/user.sql:1-75](file://sql/user.sql#L1-L75) - [sql/chat_attachment.sql:1-39](file://sql/chat_attachment.sql#L1-L39) - [sql/insight_agent_tables.sql:1-107](file://sql/insight_agent_tables.sql#L1-L107) - [sql/agent_tool.sql:1-52](file://sql/agent_tool.sql#L1-L52) - [sql/ai_clean.sql:1-214](file://sql/ai_clean.sql#L1-L214) ## 故障排查指南 ### 用户无法登录或账号被顶下线 - 检查 `sys_user.status` 是否为启用。 - 检查 `sys_user.pwd_hash` 是否为有效 BCrypt 值。 - 网关粘性路由异常时,确认 `gateway_user_route` 是否存在对应用户绑定。 **章节来源** - [sql/user.sql:1-75](file://sql/user.sql#L1-L75) - [sql/gateway.sql:1-107](file://sql/gateway.sql#L1-L107) ### Agent 主键重复或序列异常 - 执行 `agent_expert.sql` 清理重复行、对齐序列并补主键。 - 确认 `agent.row_id` 已有主键约束。 **章节来源** - [sql/agent_expert.sql:1-47](file://sql/agent_expert.sql#L1-L47) ### 工具清单为空或不同步 - 确认已执行 `agent_tool.sql`。 - 检查 `agent_tool.tool_name` 是否有重复值。 - 查看应用启动日志是否提示执行脚本。 **章节来源** - [sql/agent_tool.sql:1-52](file://sql/agent_tool.sql#L1-L52) ### 清洗任务重复或状态不一致 - 检查 `ai_clean_job` 唯一键是否命中。 - 核对 `ai_clean_batch` 唯一键是否重复触发。 - 查看 `row_rejected`、`row_warned`、`row_unprocessed` 定位失败原因。 **章节来源** - [sql/ai_clean.sql:1-214](file://sql/ai_clean.sql#L1-L214) - [sql/ai_clean_row_stats.sql:1-21](file://sql/ai_clean_row_stats.sql#L1-L21) ### 研判会话消息重号或缺失 - 确认已执行 `insight_agent_tables_align.sql`。 - 检查 `uk_aim_session_seq` 是否存在。 - 检查 `fk_aim_session` 是否级联删除。 - 确认 `seq` 通过 `UPDATE ... RETURNING last_seq` 原子分配。 **章节来源** - [sql/insight_agent_tables.sql:1-107](file://sql/insight_agent_tables.sql#L1-L107) - [sql/insight_agent_tables_align.sql:1-88](file://sql/insight_agent_tables_align.sql#L1-L88) ### 附件无法加载或向量检索越界 - 校验 `chat_attachment.session_id`、`user_id`、`case_id`。 - 确认 RAG 向量表存在且按会话过滤。 - 检查 `index_status` 是否为 READY。 **章节来源** - [sql/chat_attachment.sql:1-39](file://sql/chat_attachment.sql#L1-L39) ## 结论 本项目 PostgreSQL 主库采用多业务域分离设计:网关路由、用户认证、Agent 专家与工具、聊天附件、AI 清洗链路、研判会话消息、案件动态表和外部数据表各司其职。PG 负责持久化、一致性、会话隔离和审计追踪;DuckDB 承担案件级临时分析和外部数据快速查询;pgvector 向量表按会话和维度动态组织,服务于 RAG 检索。迁移应以幂等脚本为主,严格遵循初始化顺序,并在生产环境谨慎执行 DROP 操作。安全方面重点保护密码、向量数据、提示词、工具参数和案件归属关系,备份恢复应覆盖主库、向量表和 DuckDB 临时数据。