> ## 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 管理** | 员工信息、考勤、绩效结构化存储       | 精确查询 + 筛选     |
| **设备资产**  | 设备清单、巡检记录、维保信息        | 条件查询 + 日志追踪   |