urbanLifeline/docs/数据库设计文档.md

# 泰豪电源AI数智化平台 - 数据库设计文档

## 一、系统概述

基于功能结构.xml的系统架构设计，本数据库设计遵循"一个底座、多种智能体"的核心理念，支持四大业务模块：

1. **资料管理智能化**
2. **招投标自动化**
3. **售后客服智能化**
4. **企业内部知识协同**

## 二、数据库架构设计

### 2.1 Schema划分

采用多Schema架构，按业务模块逻辑隔离：

| Schema | 说明 | 核心表数量 |
|--------|------|-----------|
| `sys` | 系统基础模块（用户、角色、权限、部门） | 11 |
| `file` | 文件管理模块 | 1 |
| `message` | 消息通知模块 | 4 |
| `log` | 日志审计模块 | 1 |
| `config` | 系统配置模块 | 1 |
| `knowledge` | 知识库管理模块 | 4 |
| `bidding` | 招投标智能体业务模块 | 8 |
| `customer_service` | 智能客服系统业务模块 | 9 |
| `agent` | 智能体管理和平台基础设施模块 | 11 |

**总计：50张核心业务表**

## 三、核心模块详细设计

### 3.1 系统基础模块 (sys)

#### 3.1.1 权限体系设计

采用**RBAC（基于角色的访问控制）+ ACL（访问控制列表）**混合模型：

**核心表：**
- `tb_sys_user` - 用户表
- `tb_sys_role` - 角色表（支持全局角色和部门私有角色）
- `tb_sys_permission` - 权限表
- `tb_sys_dept` - 部门表（树形结构）
- `tb_sys_acl` - 通用对象级权限表（支持细粒度权限控制）
- `tb_sys_acl_policy` - ACL策略表（层级可见/可编辑规则）

**设计亮点：**
1. **多租户支持**：通过`dept_path`字段实现数据隔离，支持部门级多租户
2. **角色作用域**：`scope`字段区分全局角色和部门私有角色
3. **细粒度权限**：ACL表支持对任意对象类型（文章、文件、课程等）的权限控制
4. **层级权限继承**：`include_descendants`支持子部门/子角色权限继承

#### 3.1.2 用户信息管理

```sql
-- 用户表结构优势
tb_sys_user:
  - 支持多种登录方式（email、phone、wechat_id）
  - 密码加密存储（建议bcrypt/argon2）
  - 软删除机制（deleted + delete_time）
  - 时区感知时间戳（timestamptz）
```

### 3.2 知识库管理模块 (knowledge)

#### 3.2.1 表结构设计

**核心表：**
- `tb_knowledge_base` - 知识库定义表
- `tb_knowledge_document` - 知识文档表
- `tb_knowledge_chunk` - 文档片段表（RAG检索）
- `tb_knowledge_access_log` - 访问日志表

**设计亮点：**

1. **多类型知识库支持**
```sql
kb_type: 
  - bidding        -- 招投标知识库
  - customer_service -- 客服知识库
  - internal       -- 内部协同知识库
```

2. **文档智能处理**
   - 自动分类（`category`字段）
   - AI摘要生成（`content_summary`）
   - 关键词提取（`keywords`数组）
   - 向量化状态跟踪（`embedding_status`）

3. **RAG检索支持**
   - `tb_knowledge_chunk`表存储文档切片
   - `embedding`字段存储向量（需pgvector扩展）
   - 支持语义检索和混合检索

4. **版本管理**
   - `version`字段跟踪文档版本
   - `parent_doc_id`构建版本树

### 3.3 招投标智能体业务模块 (bidding)

#### 3.3.1 核心业务流程

```
项目创建 → 文件采集 → 智能解读 → 要素提取 → 投标文件生成 → 审核提交 → 流程跟踪
```

#### 3.3.2 表结构设计

**核心表：**
1. `tb_bidding_project` - 招标项目表（主表）
2. `tb_bidding_document` - 招标文件表
3. `tb_bidding_requirement` - 要素提取表
4. `tb_bid_response` - 投标文件生成表
5. `tb_bidding_scoring_rule` - 评分规则表
6. `tb_bidding_process` - 流程节点表
7. `tb_bid_template` - 投标模板表

**设计亮点：**

1. **完整项目生命周期管理**
```sql
project_status:
  - collecting    -- 收集中
  - analyzing     -- 分析中
  - preparing     -- 准备投标
  - submitted     -- 已提交
  - opened        -- 已开标
  - won/lost      -- 中标/未中标
  - abandoned     -- 放弃
```

2. **智能要素提取**
   - 支持7大类要素（商务、技术、否决项、资质、交付、付款、评分）
   - AI提取置信度跟踪
   - 来源位置记录（页码、段落）
   - 合规状态跟踪

3. **投标文件生成**
   - 支持多种生成方式（AI生成、模板生成、人工编写）
   - 版本管理（`parent_version_id`）
   - 审批流程状态跟踪

4. **评分规则智能分析**
   - 多维度评分（技术分、商务分、价格分、信誉分）
   - 公式计算支持
   - 得分预估和优化建议

### 3.4 智能客服系统业务模块 (customer_service)

#### 3.4.1 核心业务流程

```
客户咨询 → AI问答 → 人工转接 → 工单生成 → 工单处理 → CRM同步 → 满意度评价
```

#### 3.4.2 表结构设计

**核心表：**
1. `tb_customer` - 客户信息表
2. `tb_conversation` - 会话表
3. `tb_conversation_message` - 会话消息表
4. `tb_ticket` - 工单表
5. `tb_ticket_log` - 工单处理记录表
6. `tb_faq` - FAQ表
7. `tb_service_evaluation` - 客服评价表
8. `tb_crm_config` - CRM集成配置表

**设计亮点：**

1. **全渠道客户管理**
   - 支持多渠道（微信、网页、APP、电话）
   - 客户等级分层（VIP、重要、普通、潜在）
   - 标签化管理
   - CRM系统ID映射

2. **智能会话管理**
   - AI/人工/转接会话类型
   - 会话摘要自动生成
   - 满意度评价跟踪
   - 消息情感分析和意图识别

3. **工单智能处理**
   - AI自动生成工单
   - SLA超时预警
   - 优先级智能判定
   - CRM双向同步

4. **知识库引用跟踪**
   - `kb_references`字段记录引用的知识库文档
   - 支持回答溯源
   - 知识库质量评估数据

### 3.5 智能体管理模块 (agent)

#### 3.5.1 核心功能

```
智能体定义 → 工具集成 → API管理 → 会话管理 → 监控运维 → 评价反馈
```

#### 3.5.2 表结构设计

**核心表：**
1. `tb_agent` - 智能体定义表
2. `tb_agent_session` - 智能体会话表
3. `tb_agent_message` - 智能体消息表
4. `tb_agent_tool` - 智能体工具表
5. `tb_api_integration` - API集成注册表
6. `tb_api_call_log` - API调用日志表
7. `tb_agent_metrics` - 智能体监控指标表
8. `tb_agent_error_log` - 智能体异常日志表
9. `tb_agent_rating` - 智能体评价表

**设计亮点：**

1. **智能体广场**
   - `is_published`字段支持发布到广场
   - 评分和使用次数统计
   - 分类和标签管理
   - 访问级别控制

2. **工具和API集成**
   - 标准化工具定义（OpenAI Function Calling格式）
   - 多种认证方式支持
   - 健康检查机制
   - 调用日志完整记录

3. **监控和运维**
   - 按日期/小时的指标聚合
   - 成本跟踪（Token使用量、API调用费用）
   - 错误日志和堆栈跟踪
   - 成功率和响应时间监控

4. **会话管理**
   - 支持对话、任务、工作流多种类型
   - 上下文管理（JSONB格式）
   - Token使用量统计
   - 知识库引用跟踪

## 四、数据库优化建议

### 4.1 索引优化

#### 4.1.1 已实现的索引策略

1. **主键索引**：所有表都有主键（通常为业务ID）
2. **唯一索引**：关键业务字段（email、phone、编号等）
3. **外键索引**：关联查询字段
4. **复合索引**：高频查询组合字段
5. **部分索引**：带WHERE条件的索引（减少索引大小）
6. **GIN索引**：数组字段（tags、keywords等）

#### 4.1.2 建议增加的索引

```sql
-- 知识库文档全文搜索索引（需要pg_trgm扩展）
CREATE INDEX idx_knowledge_doc_title_trgm 
ON knowledge.tb_knowledge_document USING gin(title gin_trgm_ops);

-- 会话消息内容全文搜索
CREATE INDEX idx_message_content_trgm 
ON customer_service.tb_conversation_message USING gin(content gin_trgm_ops);

-- 招标项目名称搜索
CREATE INDEX idx_project_name_trgm 
ON bidding.tb_bidding_project USING gin(project_name gin_trgm_ops);
```

### 4.2 性能优化建议

#### 4.2.1 分区表设计

对于数据量大、查询集中在时间范围的表，建议使用分区：

```sql
-- 示例：API调用日志按月分区
CREATE TABLE agent.tb_api_call_log (
  -- ... 字段定义
) PARTITION BY RANGE (create_time);

CREATE TABLE agent.tb_api_call_log_2024_01 
PARTITION OF agent.tb_api_call_log
FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');
```

**建议分区的表：**
- `agent.tb_api_call_log` - API调用日志
- `log.tb_sys_log` - 系统日志
- `knowledge.tb_knowledge_access_log` - 知识访问日志
- `agent.tb_agent_metrics` - 智能体监控指标（已按日期设计）

#### 4.2.2 JSONB字段优化

```sql
-- 为JSONB字段创建GIN索引
CREATE INDEX idx_agent_model_config_gin 
ON agent.tb_agent(model_config) USING gin;

-- 为JSONB内特定键创建表达式索引
CREATE INDEX idx_agent_config_model_name 
ON agent.tb_agent((model_config->>'model_name'));
```

#### 4.2.3 数组字段优化

```sql
-- 使用GIN索引支持数组查询
CREATE INDEX idx_kb_doc_tags_gin 
ON knowledge.tb_knowledge_document USING gin(tags);

-- 查询示例
SELECT * FROM knowledge.tb_knowledge_document 
WHERE tags @> ARRAY['技术文档'];
```

### 4.3 数据归档策略

#### 4.3.1 软删除设计

当前设计使用软删除（`deleted`字段），建议：

1. **定期归档**：将deleted=true且超过6个月的数据移至归档表
2. **归档表命名**：`tb_xxx_archived`
3. **保留必要索引**：归档表仅保留时间范围查询索引

#### 4.3.2 日志数据归档

```sql
-- 日志归档策略
-- 1. API调用日志：保留近3个月，其余归档
-- 2. 系统日志：保留近6个月，其余归档
-- 3. 访问日志：保留近1个月，其余归档

-- 归档函数示例
CREATE OR REPLACE FUNCTION archive_old_logs()
RETURNS void AS $$
BEGIN
  -- 归档API调用日志
  INSERT INTO agent.tb_api_call_log_archived
  SELECT * FROM agent.tb_api_call_log
  WHERE create_time < now() - interval '3 months';
  
  DELETE FROM agent.tb_api_call_log
  WHERE create_time < now() - interval '3 months';
END;
$$ LANGUAGE plpgsql;
```

### 4.4 查询优化建议

#### 4.4.1 常用查询模式

```sql
-- 1. 用户权限检查（高频查询）
-- 建议：创建物化视图
CREATE MATERIALIZED VIEW sys.mv_user_permissions AS
SELECT 
  ur.user_id,
  array_agg(DISTINCT p.code) AS permissions
FROM sys.tb_sys_user_role ur
JOIN sys.tb_sys_role_permission rp ON ur.role_id = rp.role_id
JOIN sys.tb_sys_permission p ON rp.permission_id = p.permission_id
WHERE ur.deleted = false AND rp.deleted = false
GROUP BY ur.user_id;

CREATE UNIQUE INDEX ON sys.mv_user_permissions(user_id);

-- 定期刷新
REFRESH MATERIALIZED VIEW CONCURRENTLY sys.mv_user_permissions;
```

#### 4.4.2 复杂统计查询优化

```sql
-- 使用CTE和窗口函数优化统计查询
WITH daily_stats AS (
  SELECT 
    DATE(create_time) AS stat_date,
    agent_id,
    COUNT(*) AS session_count,
    SUM(message_count) AS total_messages
  FROM agent.tb_agent_session
  WHERE deleted = false
  GROUP BY DATE(create_time), agent_id
)
SELECT 
  agent_id,
  stat_date,
  session_count,
  total_messages,
  SUM(session_count) OVER (
    PARTITION BY agent_id 
    ORDER BY stat_date 
    ROWS BETWEEN 6 PRECEDING AND CURRENT ROW
  ) AS rolling_7day_sessions
FROM daily_stats;
```

## 五、现有SQL文件修改建议

### 5.1 createTableUser.sql 优化

**当前问题：**
1. 登录日志表中存储密码不安全
2. 缺少用户部门关联

**建议修改：**

```sql
-- 1. 移除登录日志表的password字段
ALTER TABLE sys.tb_sys_login_log DROP COLUMN IF EXISTS password;

-- 2. 添加用户部门关联表
CREATE TABLE sys.tb_sys_user_dept (
  optsn       VARCHAR(50)   NOT NULL,
  user_id     VARCHAR(50)   NOT NULL,
  dept_id     VARCHAR(50)   NOT NULL,
  is_primary  BOOLEAN       DEFAULT false,  -- 是否主部门
  position    VARCHAR(100),                 -- 职位
  creator     VARCHAR(50)   DEFAULT NULL,
  create_time timestamptz   NOT NULL DEFAULT now(),
  update_time timestamptz   DEFAULT NULL,
  deleted     BOOLEAN       NOT NULL DEFAULT false,
  PRIMARY KEY (user_id, dept_id),
  UNIQUE (optsn)
);

-- 3. 用户表添加默认部门字段
ALTER TABLE sys.tb_sys_user 
ADD COLUMN IF NOT EXISTS primary_dept_id VARCHAR(50);
```

### 5.2 createTablePermission.sql 优化

**建议修改：**

```sql
-- 1. 角色表添加排序字段
ALTER TABLE sys.tb_sys_role 
ADD COLUMN IF NOT EXISTS order_num INTEGER DEFAULT 0;

-- 2. 权限表添加权限类型字段
ALTER TABLE sys.tb_sys_permission 
ADD COLUMN IF NOT EXISTS permission_type VARCHAR(20) DEFAULT 'action';
-- permission_type: action-操作权限/data-数据权限/menu-菜单权限

COMMENT ON COLUMN sys.tb_sys_permission.permission_type 
IS '权限类型：action-操作权限/data-数据权限/menu-菜单权限';
```

### 5.3 createTableFile.sql 扩展

**建议添加：**

```sql
-- 1. 文件版本管理
ALTER TABLE file.tb_sys_file 
ADD COLUMN IF NOT EXISTS version VARCHAR(20) DEFAULT '1.0',
ADD COLUMN IF NOT EXISTS parent_file_id VARCHAR(50),
ADD COLUMN IF NOT EXISTS is_latest BOOLEAN DEFAULT true;

-- 2. 文件分类
ALTER TABLE file.tb_sys_file 
ADD COLUMN IF NOT EXISTS category VARCHAR(100),
ADD COLUMN IF NOT EXISTS tags TEXT[];

-- 3. 文件关联（支持文件和业务对象关联）
CREATE TABLE file.tb_file_relation (
  optsn         VARCHAR(50)   NOT NULL,
  relation_id   VARCHAR(50)   NOT NULL,
  file_id       VARCHAR(50)   NOT NULL,
  object_type   VARCHAR(50)   NOT NULL,  -- 对象类型：bidding_project/ticket/document等
  object_id     VARCHAR(50)   NOT NULL,  -- 对象ID
  relation_type VARCHAR(30)   DEFAULT 'attachment', -- 关联类型：attachment-附件/avatar-头像/banner-横幅
  order_num     INTEGER       DEFAULT 0,
  creator       VARCHAR(50)   DEFAULT NULL,
  create_time   timestamptz   NOT NULL DEFAULT now(),
  deleted       BOOLEAN       NOT NULL DEFAULT false,
  PRIMARY KEY (relation_id),
  UNIQUE (optsn),
  FOREIGN KEY (file_id) REFERENCES file.tb_sys_file(file_id)
);

CREATE INDEX idx_file_relation_object 
ON file.tb_file_relation(object_type, object_id) WHERE deleted = false;
```

### 5.4 createTableMessage.sql 增强

**建议添加：**

```sql
-- 1. 消息模板表
CREATE TABLE message.tb_message_template (
  optsn         VARCHAR(50)   NOT NULL,
  template_id   VARCHAR(50)   NOT NULL,
  template_code VARCHAR(100)  NOT NULL,  -- 模板编码
  template_name VARCHAR(255)  NOT NULL,  -- 模板名称
  template_type VARCHAR(30)   NOT NULL,  -- 模板类型：system-系统/business-业务
  title_template TEXT,                   -- 标题模板（支持变量）
  content_template TEXT NOT NULL,        -- 内容模板（支持变量）
  variables     JSONB,                   -- 变量定义
  dept_path     VARCHAR(255)  DEFAULT NULL,
  creator       VARCHAR(50)   DEFAULT NULL,
  updater       VARCHAR(50)   DEFAULT NULL,
  create_time   timestamptz   NOT NULL DEFAULT now(),
  update_time   timestamptz   DEFAULT NULL,
  deleted       BOOLEAN       NOT NULL DEFAULT false,
  PRIMARY KEY (template_id),
  UNIQUE (optsn),
  UNIQUE (template_code)
);

COMMENT ON TABLE message.tb_message_template IS '消息模板表';
```

## 六、数据安全建议

### 6.1 敏感数据加密

**需要加密的字段：**
1. `sys.tb_sys_user.password` - 用户密码（使用bcrypt/argon2）
2. `agent.tb_agent_tool.auth_config` - API认证配置
3. `agent.tb_api_integration.auth_config` - 集成认证配置
4. `customer_service.tb_crm_config.api_key` - CRM API密钥

**建议使用PostgreSQL的pgcrypto扩展：**

```sql
CREATE EXTENSION IF NOT EXISTS pgcrypto;

-- 加密示例
INSERT INTO agent.tb_agent_tool (auth_config)
VALUES (pgp_sym_encrypt('{"api_key": "secret"}', 'encryption_key'));

-- 解密示例
SELECT pgp_sym_decrypt(auth_config::bytea, 'encryption_key')
FROM agent.tb_agent_tool;
```

### 6.2 行级安全策略（RLS）

```sql
-- 启用行级安全
ALTER TABLE knowledge.tb_knowledge_document ENABLE ROW LEVEL SECURITY;

-- 创建策略：用户只能访问自己部门的文档
CREATE POLICY dept_isolation_policy ON knowledge.tb_knowledge_document
FOR SELECT
USING (
  dept_path LIKE (
    SELECT dept_path || '%' 
    FROM sys.tb_sys_user 
    WHERE user_id = current_setting('app.current_user_id')
  )
);
```

### 6.3 审计日志增强

```sql
-- 添加审计触发器
CREATE OR REPLACE FUNCTION audit_trigger_func()
RETURNS TRIGGER AS $$
BEGIN
  IF (TG_OP = 'DELETE') THEN
    INSERT INTO log.tb_sys_log (
      log_id, type, level, module, message, data, creator
    ) VALUES (
      gen_random_uuid()::text,
      'audit',
      'info',
      TG_TABLE_SCHEMA || '.' || TG_TABLE_NAME,
      'Record deleted',
      row_to_json(OLD),
      current_setting('app.current_user_id', true)
    );
    RETURN OLD;
  ELSIF (TG_OP = 'UPDATE') THEN
    INSERT INTO log.tb_sys_log (
      log_id, type, level, module, message, data, creator
    ) VALUES (
      gen_random_uuid()::text,
      'audit',
      'info',
      TG_TABLE_SCHEMA || '.' || TG_TABLE_NAME,
      'Record updated',
      jsonb_build_object('old', row_to_json(OLD), 'new', row_to_json(NEW)),
      current_setting('app.current_user_id', true)
    );
    RETURN NEW;
  END IF;
END;
$$ LANGUAGE plpgsql;

-- 为敏感表添加审计触发器
CREATE TRIGGER audit_user_changes
AFTER UPDATE OR DELETE ON sys.tb_sys_user
FOR EACH ROW EXECUTE FUNCTION audit_trigger_func();
```

## 七、部署和维护建议

### 7.1 初始化顺序

```bash
# 1. 创建扩展
psql -d urbanlifeline -f extensions.sql

# 2. 按依赖顺序执行建表脚本
psql -d urbanlifeline -f createTablePermission.sql
psql -d urbanlifeline -f createTableUser.sql
psql -d urbanlifeline -f createTableFile.sql
psql -d urbanlifeline -f createTableMessage.sql
psql -d urbanlifeline -f createTableLog.sql
psql -d urbanlifeline -f createTableConfig.sql
psql -d urbanlifeline -f createTableKnowledge.sql
psql -d urbanlifeline -f createTableBidding.sql
psql -d urbanlifeline -f createTableCustomerService.sql
psql -d urbanlifeline -f createTableAgent.sql

# 3. 执行完整初始化（包含触发器和视图）
psql -d urbanlifeline -f createTableAll.sql

# 4. 初始化基础数据
psql -d urbanlifeline -f initDataConfig.sql
```

### 7.2 定期维护任务

```sql
-- 1. 分析和优化表
ANALYZE VERBOSE;
VACUUM ANALYZE;

-- 2. 重建索引（处理索引膨胀）
REINDEX DATABASE urbanlifeline;

-- 3. 更新表统计信息
VACUUM ANALYZE sys.tb_sys_user;
VACUUM ANALYZE agent.tb_agent_session;

-- 4. 检查慢查询
SELECT query, calls, total_time, mean_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 20;
```

### 7.3 备份策略

```bash
# 全量备份（每日）
pg_dump -Fc urbanlifeline > backup_$(date +%Y%m%d).dump

# 增量备份（使用WAL归档）
# 在postgresql.conf中配置：
# wal_level = replica
# archive_mode = on
# archive_command = 'cp %p /path/to/archive/%f'

# 恢复示例
pg_restore -d urbanlifeline -c backup_20240101.dump
```

## 八、总结

### 8.1 设计优势

1. **模块化架构**：9个Schema清晰划分业务边界
2. **可扩展性**：支持多租户、多智能体、多业务类型
3. **性能优化**：合理的索引设计、分区策略、视图优化
4. **数据安全**：软删除、审计日志、权限控制、数据加密
5. **业务完整**：覆盖招投标、客服、知识库全流程

### 8.2 后续优化方向

1. **向量检索优化**：引入pgvector扩展，优化RAG检索性能
2. **分布式部署**：考虑Citus扩展实现水平扩展
3. **实时数据同步**：使用Logical Replication实现异地备份
4. **监控告警**：集成pgBadger、pg_stat_statements等工具
5. **读写分离**：主从复制实现读写分离

### 8.3 关键指标

- **总表数**：50+ 张核心表
- **Schema数**：9 个业务Schema
- **索引类型**：B-Tree、GIN、部分索引、表达式索引
- **数据类型**：标准类型 + JSONB + 数组 + 向量（可选）
- **时区支持**：全部使用timestamptz
- **软删除**：全表支持deleted标记

---

**文档版本**: 1.0  
**最后更新**: 2024-12-02  
**维护团队**: 泰豪电源AI数智化平台开发组