> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zgi.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据库

> 面向业务智能场景的结构化数据能力底座

## 功能概述

ZGI 数据库不是一个单纯"存数据"的模块，而是一套面向业务智能场景的**结构化数据能力底座**。它支持用户从业务文档、表格或说明材料出发，快速生成数据表结构，并将后续的数据查询、统计分析、复杂计算、日志追踪、智能体问答等能力串联起来。

数据库功能既可以作为独立的数据管理工具，也可以作为**智能体工作流中的核心数据源**。对于合同管理、项目台账、经营数据统计、业务记录分析、规则管理等场景，数据库模块可以承担从"结构化建模"到"自然语言查询"的完整链路。

> **核心价值**
>
> 不只是"把数据存进去"，而是让这些数据可以被稳定地查、准确地算、清楚地追踪，并最终通过自然语言方式返回给业务人员。

数据库功能特别适合以下类型的业务问题：

* 查询单条或多条结构化信息
* 按条件筛选数据并输出明细
* 对数据做聚合、分组、排序、统计分析
* 支撑智能体进行自然语言问答
* 配合业务规则、条款数据、项目规则表做复杂计算
* 对数据库操作过程进行日志留痕和问题排查

## 核心能力总览

| 能力类别 | 包含能力 | 说明 |
| - | - | - |
| **表结构设计** | 字段定义、类型设置、必填标记、人工调整 | 支持手动建表和智能生成两种方式 |
| **智能生成表结构** | 上传业务文档自动生成表结构 | 从文档、表格、合同等材料自动识别字段 |
| **数据导入** | 结构化数据批量写入 | 单次支持 15 条数据导入，持续优化中 |
| **数据查询** | 精确查询、条件筛选、模糊匹配 | 支持多种查询类型满足不同业务需求 |
| **统计分析** | 聚合、分组、排序、多表联查 | 复杂分析与多维度统计 |
| **自然语言查询** | NL2SQL 自动转换与执行 | 业务人员用中文提问直接获得结果 |
| **操作日志** | SQL 执行记录、操作追踪 | 全链路审计，支撑排查与复盘 |
| **智能体联动** | 作为工作流数据源节点 | 数据库 + 智能体实现端到端业务闭环 |

## 支持的数据类型

| 数据类型 | 用途说明 | 典型场景 |
| - | - | - |
| `text` | 文本类型，存储字符串内容 | 名称、地址、描述、备注 |
| `numeric` | 精确数值类型 | 金额、费率、价格 |
| `integer` | 整数类型 | 数量、天数、序号 |
| `timestamp` | 时间戳类型 | 合同日期、操作时间 |
| `boolean` | 布尔类型 | 是否启用、是否完成 |

## 表结构设计

### 字段定义

每个字段包含以下信息：**存储字段名称**、**字段描述**、**数据类型**、**是否必填**。这种设计兼顾了技术可执行性和业务可理解性。

### 单表与多表设计

简单场景中，一张表即可承载完整数据（员工台账、设备清单等）。复杂场景推荐一库多表设计：

* **主表** — 承载核心结构化字段（如合同编号、金额、日期）

* **条款表** — 承载原文条款或说明性内容

* **规则表** — 承载项目级或业务级规则与计算标准

* **明细表** — 承载多条记录或变动明细

> 对于合同、规则、经营分析这类场景，多表设计通常更稳定，也更利于后续查询和复杂计算。

## 智能生成表结构

用户上传参考文件并填写需求描述，系统基于文件内容和业务意图自动识别关键字段，推断合理的表结构。

### 支持的输入来源

* 本地文件上传（DOC、DOCX、PDF、XLSX、XLS、PPTX、JPG）

* 自定义文本描述

* 从文件管理模块选择参考文件

### 生成内容

系统自动生成字段名称、字段描述、数据类型推荐、必填字段建议以及可能的业务主键 / 标识字段。

### 适用场景

* 对建模不熟悉，不知道如何起表
* 已有业务材料但还没有结构化数据设计
* 希望快速搭建 demo 或验证方案
* 想把文档内容转成可查询的结构化表

> **使用建议**
>
> 智能生成适合做"起步"，但核心字段命名、字段语义、字段拆分方式仍建议由业务或实施人员做最终确认。

## 数据导入与维护

表结构建好后，通过数据库模块自身的导入能力将业务数据写入表中。当前单次支持导入 **15 条**数据，该能力持续优化中。

### 适用场景

初始台账建立、合同样本导入、项目规则数据录入、表格型数据快速入库、demo 数据准备。

> **推荐流程**
>
> 先设计表 → 分批导入 → 验证查询，避免一次性导入后发现字段设计不合理。

## 数据查询能力

| 查询类型 | 说明 | 示例 |
| - | - | - |
| 精确查询 | 按主键或唯一字段定位单条记录 | "阳光公司的合同信息" |
| 条件筛选 | 按条件过滤多条记录 | "本月到期的所有合同" |
| 模糊匹配 | 关键词模糊搜索 | "包含'物业'的项目" |
| 聚合统计 | 汇总、计数、分组、排序 | "每栋楼的年租金合计" |
| 多表联查 | 跨表关联查询 | "合同主表 + 条款表联合查询" |
| 复杂计算 | 多字段运算与规则判断 | "违约金 = 日租金 × 逾期天数 × 费率" |

## 自然语言查询（NL2SQL）

业务人员可以直接用中文提问，系统自动将自然语言转换为 SQL 并执行。

### 查询示例

```text theme={null}
用户提问：阳光公司的物业费支付方式是什么？

→ 系统自动生成 SQL：
  SELECT payment_method FROM contracts WHERE company_name = '阳光公司';
→ 返回自然语言结果：
  阳光公司的物业费支付方式为"季度预付"。
```

### 转换流程

### 理解问题

系统识别查询对象、查询指标和查询类型

### 生成 SQL

根据表结构自动生成对应的 SQL 语句

### 执行查询

在数据库中执行 SQL 并获取原始结果

### 自然语言回复

将查询结果转换为业务人员可理解的自然语言回答

## 复杂业务计算

数据库不仅适合"查数据"，也可以为复杂业务计算提供结构化支撑。配合规则表和条款表，可以实现：

* **违约金计算** — 根据逾期天数、日租金和费率自动计算

* **物业费计算** — 按面积、单价、周期等多维度计算

* **押金退还判断** — 基于合同条款与实际履约情况综合判断

* **付款周期预警** — 自动识别即将到期的付款节点

## 操作日志与追踪

| 维度 | 说明 |
| - | - |
| 操作时间 | 精确到秒的操作时间戳 |
| 操作类型 | 创建表、查询、更新、删除等 |
| 执行状态 | 成功/失败及错误原因 |
| 操作表 | 涉及的数据表名称 |
| 操作用户 | 执行操作的账号 |
| 执行 SQL | 实际执行的 SQL 语句，便于排查 |

日志支持按操作类型、状态、时间范围筛选，适用于查询报错排查、提示词优化复盘、业务数据修改追踪、智能体结果异常定位等场景。

## 与智能体工作流联动

* **作为数据源**：提供查询对象、核心字段、统计数据，让智能体直接消费结构化数据
* **统计分析链路**：经营分析、合同统计等场景中，直接承担统计与返回结果的角色
* **复杂计算支撑**：提供核心数值字段与规则字段，为规则驱动的业务计算提供数据基础
* **自然语言回复**：查询结果直接生成自然语言回答，不只是返回表格，而是服务业务问答

## 典型业务场景

| 场景 | 数据库的角色 | 核心能力 |
| - | - | - |
| **合同管理** | 存储合同主表 + 条款表，支持自然语言问答 | 多表查询 + NL2SQL |
| **项目台账** | 项目进度、预算、负责人等结构化管理 | 条件筛选 + 聚合统计 |
| **经营分析** | 多维度数据统计与可视化 | 分组统计 + 复杂计算 |
| **物业管理** | 租金、物业费、押金等台账式管理 | 规则计算 + 预警 |
| **HR 管理** | 员工信息、考勤、绩效结构化存储 | 精确查询 + 筛选 |
| **设备资产** | 设备清单、巡检记录、维保信息 | 条件查询 + 日志追踪 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.