wangys/urbanLifeline
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

前端项目结构

Browse Source
This commit is contained in:
wangys
2025-12-02 15:55:30 +08:00
parent 2a9e624ba9
commit 28787e5b29
18 changed files with 2545 additions and 2167 deletions
Download Patch File Download Diff File Expand all files Collapse all files

563
docs/前端完整指南.md Normal file
View File

@@ -0,0 +1,563 @@
# 泰豪电源 AI 数智化平台 - 前端完整指南
## 📖 目录
1. [技术架构](#1-技术架构)
2. [共享组件方案](#2-共享组件方案)
3. [快速开始](#3-快速开始)
4. [开发指南](#4-开发指南)
5. [构建部署](#5-构建部署)
6. [常见问题](#6-常见问题)
---
## 1. 技术架构
### 1.1 技术栈
**前端框架**
- Vue 3.5+ (`<script setup>`)
- TypeScript 5.7+
- Vite 6.0+
- Pinia 2.2+
- Element Plus 2.9+
**工程化**
- pnpm 9.0+ Monorepo
- Turborepo 2.0+ 构建加速
- unplugin-auto-import 自动导入
- ESLint 9 + Prettier
**通信层**
- ofetch (替代 Axios)
- @vueuse/core
### 1.2 项目结构
```
urbanLifelineWeb/
├── packages/
│ ├── shared/ # 共享包 ⭐核心
│ │ ├── components/ # UI组件
│ │ ├── utils/ # 工具函数
│ │ ├── api/ # API封装
│ │ └── composables/ # 组合函数
│ ├── portal/ # 主应用
│ ├── app-bidding/ # 招投标应用
│ ├── app-customer-service/ # 智能客服应用
│ └── app-knowledge/ # 知识协同应用
├── pnpm-workspace.yaml
└── turbo.json
```
---
## 2. 共享组件方案
### 2.1 核心理念
**业务应用只需关心 `@shared/*` 导入，无需关心底层依赖（Vue、Element Plus 等）**
```
业务应用: import { UlTable } from '@shared/components'
↓
浏览器: GET /shared/components.js
↓
共享服务: 返回包含 Vue + Element Plus 的 ES Module
↓
✅ 所有应用共用，浏览器缓存
```
### 2.2 配置方式
**业务应用配置（极简）**
```html
<!-- index.html -->
<script type="importmap">
{
"imports": {
"@shared/components": "/shared/components.js",
"@shared/utils": "/shared/utils.js",
"@shared/api": "/shared/api.js"
}
}
</script>
```
**Vue 组件使用**
```vue
<script setup lang="ts">
// ✅ 直接从 HTTP URL 加载
import { UlTable } from '@shared/components'
import { http } from '@shared/utils'
import { authApi } from '@shared/api'
import { useTable } from '@shared/composables'
const { loading, tableData } = useTable({
fetchData: authApi.getUserList
})
</script>
<template>
<UlTable :data="tableData" :loading="loading" />
</template>
```
### 2.3 优势
| 特性 | 传统方式 | Import Maps 方案 |
|------|---------|-----------------|
| 代码共享 | ❌ 每个应用打包一份 | ✅ 所有应用共用一份 |
| 构建体积 | ❌ 重复打包 | ✅ 减少 30-50% |
| 依赖管理 | ❌ 每个应用配置 | ✅ 共享服务统一管理 |
| 版本升级 | ❌ 所有应用改 | ✅ 只改共享服务 |
| 浏览器缓存 | ⚠️ 独立缓存 | ✅ 统一缓存 |
---
## 3. 快速开始
### 3.1 Docker 环境（推荐）
```bash
# 1. 启动所有服务
make up
# 2. 查看状态
make ps
# 3. 访问应用
open http://localhost
```
**访问地址**
- 主应用: http://localhost/
- 招投标: http://localhost/bidding
- 智能客服: http://localhost/customer-service
- 共享组件: http://localhost/shared/components.js
- API网关: http://localhost/api
- Nacos: http://localhost/nacos
### 3.2 本地开发
```bash
# 1. 安装依赖
pnpm install
# 2. 启动所有应用
pnpm dev
# 或启动单个应用
pnpm --filter portal dev
pnpm --filter app-bidding dev
```
---
## 4. 开发指南
### 4.1 创建页面
```vue
<!-- packages/portal/src/views/UserList.vue -->
<script setup lang="ts">
import { UlTable } from '@shared/components'
import { authApi } from '@shared/api'
import { useTable } from '@shared/composables'
interface User {
id: string
username: string
email: string
}
const { loading, tableData, pagination, handlePageChange } = useTable<User>({
fetchData: authApi.getUserList
})
const columns = [
{ prop: 'username', label: '用户名', minWidth: 150 },
{ prop: 'email', label: '邮箱', minWidth: 200 }
]
</script>
<template>
<div class="user-list">
<UlTable
:data="tableData"
:columns="columns"
:loading="loading"
:pagination="pagination"
@page-change="handlePageChange"
/>
</div>
</template>
```
### 4.2 API 调用
```typescript
// 使用封装的 API
import { authApi, systemApi } from '@shared/api'
// GET 请求
const users = await authApi.getUserList({ page: 1, size: 10 })
// POST 请求
await authApi.createUser({ username: 'test', email: 'test@example.com' })
// 直接使用 http
import { http } from '@shared/utils'
const data = await http.get('/custom/endpoint')
```
### 4.3 状态管理
```typescript
// store/user.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
import { authApi } from '@shared/api'
export const useUserStore = defineStore('user', () => {
// State
const userInfo = ref(null)
const permissions = ref([])
// Getters
const isLoggedIn = computed(() => !!userInfo.value)
// Actions
const login = async (loginData) => {
const res = await authApi.login(loginData)
userInfo.value = res.userInfo
permissions.value = res.permissions
}
return { userInfo, permissions, isLoggedIn, login }
})
```
### 4.4 路由配置
```typescript
// router/index.ts
import { createRouter, createWebHistory } from 'vue-router'
const routes = [
{
path: '/',
component: () => import('@/layouts/MainLayout.vue'),
children: [
{
path: 'home',
component: () => import('@/views/home/index.vue'),
meta: { title: '首页' }
}
]
}
]
const router = createRouter({
history: createWebHistory(),
routes
})
export default router
```
### 4.5 常用命令
```bash
# 查看日志
make logs-portal # 主应用日志
make logs-gateway # 网关日志
make logs-shared # 共享包日志
# 重启服务
make restart-portal # 重启主应用
make restart # 重启所有服务
# 进入容器
make shell-portal # 进入容器调试
# 数据库
make db # 连接数据库
make db-init # 初始化数据
```
---
## 5. 构建部署
### 5.1 本地构建
```bash
# 构建所有应用
pnpm build
# 构建单个应用
pnpm --filter portal build
pnpm --filter shared build
# 预览
pnpm preview
```
### 5.2 部署到生产
**方式1: Docker 部署**
```bash
# 构建生产镜像
docker build -t urban-lifeline-web .
# 运行
docker run -p 80:80 urban-lifeline-web
```
**方式2: CDN 部署**
```bash
# 部署共享包到 CDN
cd packages/shared
pnpm build
ossutil cp -r dist/esm/ oss://cdn/shared/v1.0.0/
# 部署业务应用
cd packages/portal
pnpm build
ossutil cp -r dist/ oss://cdn/portal/
```
**方式3: Nginx 静态部署**
```nginx
server {
listen 80;
server_name taihao.com;
# 主应用
location / {
root /var/www/portal/dist;
try_files $uri $uri/ /index.html;
}
# 共享包
location /shared/ {
root /var/www/shared/dist;
add_header Access-Control-Allow-Origin "*";
expires 1y;
}
# API 代理
location /api/ {
proxy_pass http://gateway:8080/;
}
}
```
### 5.3 环境变量
```bash
# .env.development
VITE_API_BASE_URL=http://localhost/api
VITE_SHARED_URL=http://localhost/shared
# .env.production
VITE_API_BASE_URL=https://api.taihao.com/api
VITE_SHARED_URL=https://cdn.taihao.com/shared/v1.0.0
```
### 5.4 CI/CD
```yaml
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
with:
version: 9
- name: Build
run: pnpm install && pnpm build
- name: Deploy
run: ./scripts/deploy-production.sh
```
---
## 6. 常见问题
### 6.1 为什么使用 Import Maps？
**优势**：
- ✅ 浏览器原生支持，无需额外库
- ✅ 真正的运行时共享
- ✅ 开发体验好（支持 HMR）
- ✅ 减小构建体积
**对比 Module Federation**：
- Import Maps 更简单，配置少
- Module Federation 功能更强大，但复杂
- 两者可以结合使用
### 6.2 如何处理 TypeScript 类型？
```typescript
// packages/portal/src/types/shared.d.ts
declare module '@shared/components' {
export * from '../../../shared/src/components'
}
declare module '@shared/utils' {
export * from '../../../shared/src/utils'
}
```
### 6.3 如何更新共享组件？
```bash
# 1. 修改共享组件代码
vim packages/shared/src/components/UlTable/index.vue
# 2. 重启共享服务（HMR 自动生效）
make restart-shared
# 3. 浏览器刷新，所有应用自动获得最新版本
```
### 6.4 生产环境如何缓存？
```nginx
# Nginx 配置
location /shared/ {
# 基于版本号的长期缓存
expires 1y;
add_header Cache-Control "public, immutable";
}
# HTML 不缓存
location ~* \.html$ {
add_header Cache-Control "no-cache";
}
```
### 6.5 如何调试共享组件？
```bash
# 方式1: 查看网络请求
浏览器 F12 → Network → 筛选 JS → 查看 /shared/components.js
# 方式2: 查看日志
make logs-shared
# 方式3: 进入容器
make shell-shared
```
### 6.6 为什么不用 Webpack？
Vite 优势：
- ⚡ 开发启动快（秒级）
- 🔥 HMR 更快
- 📦 生产构建基于 Rollup（体积更小）
- 🎯 原生 ES Module 支持
### 6.7 如何处理样式？
```vue
<!-- 组件级样式 -->
<style scoped>
.ul-table {
width: 100%;
}
</style>
<!-- 全局样式 -->
<style>
@import '@shared/styles/variables.scss';
</style>
```
共享包会自动处理 CSS 提取和分割。
### 6.8 如何添加新的业务应用？
```bash
# 1. 复制现有应用作为模板
cp -r packages/portal packages/app-newapp
# 2. 修改 package.json
{
"name": "@apps/newapp",
"scripts": {
"dev": "vite --port 3003"
}
}
# 3. 添加到 pnpm-workspace.yaml（已自动包含）
# 4. 启动
pnpm --filter app-newapp dev
```
---
## 附录
### A. 常用脚本
```bash
# Makefile 命令
make up # 启动
make down # 停止
make logs # 日志
make ps # 状态
make restart # 重启
make clean # 清理
# pnpm 命令
pnpm dev # 开发
pnpm build # 构建
pnpm preview # 预览
pnpm lint # 检查
pnpm format # 格式化
```
### B. 目录说明
```
urbanLifeline/
├── urbanLifelineServ/ # 后端（Java Spring Boot）
├── urbanLifelineWeb/ # 前端（Vue 3 Monorepo）
├── docker-compose.dev.yml # Docker 开发环境
├── Makefile # 快捷命令
└── docs/ # 文档
└── 前端完整指南.md # 📖 本文档
```
### C. 技术支持
- 项目文档：`/docs`
- 问题反馈：GitHub Issues
- 开发规范：ESLint + Prettier
- 提交规范：Conventional Commits
---
**Happy Coding! 🚀**
*最后更新：2025-12-02*

357
docs/数据库优化方案总结.md
View File

@@ -1,357 +0,0 @@
# 城市生命线数据库优化方案总结
> 更新日期：2025-12-02
## 一、核心优化内容
### 1. 知识库版本管理（简化方案）
#### 设计原则
- 不创建额外的历史表或快照表
- 直接在现有表中添加版本字段
- 使用乐观锁防止并发编辑冲突
#### 文档表（tb_knowledge_document）新增字段
| 字段名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `version` | INTEGER | 1 | 版本号（整数递增） |
| `root_doc_id` | VARCHAR(50) | NULL | 根文档ID（版本组标识，首次上传时等于doc_id） |
| `is_current` | BOOLEAN | true | 是否当前使用的版本 |
**索引：**
```sql
CREATE INDEX idx_doc_root_current
ON knowledge.tb_knowledge_document(root_doc_id, is_current)
WHERE deleted = false;
```
#### 分段表（tb_knowledge_chunk）新增字段
| 字段名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `version` | INTEGER | 1 | 分段版本号（用于乐观锁，每次编辑+1） |
#### 使用示例
**创建新版本：**
```sql
-- 1. 标记旧版本为非当前
UPDATE knowledge.tb_knowledge_document
SET is_current = false
WHERE root_doc_id = 'root_xxx';
-- 2. 插入新版本
INSERT INTO knowledge.tb_knowledge_document (
doc_id, root_doc_id, version, is_current, ...
) VALUES (
'new_doc_id', 'root_xxx', 2, true, ...
);
```
**编辑分段（乐观锁）：**
```sql
UPDATE knowledge.tb_knowledge_chunk
SET content = '新内容', version = version + 1
WHERE chunk_id = 'xxx' AND version = 1; -- 版本检查
```
**查询当前版本：**
```sql
SELECT * FROM knowledge.tb_knowledge_document
WHERE root_doc_id = 'root_xxx'
AND is_current = true
AND deleted = false;
```
---
## 二、多服务数据隔离方案
### 设计原则
- 使用 `dept_path` 实现部门/租户隔离（已有字段）
- 添加 `service_type` 实现服务间隔离
- **不使用 tenant_id**（dept_path 已足够）
### 隔离层级
| 隔离级别 | 字段 | 用途 | 示例 |
|---------|------|------|------|
| **服务级** | service_type | 区分不同业务服务 | bidding / customer_service / internal |
| **部门级** | dept_path | 区分部门/租户 | /dept1/subdept1/ |
### 已添加 service_type 的表
| 表名 | 位置 | 说明 |
|------|------|------|
| `knowledge.tb_knowledge_base` | createTableKnowledge.sql | 知识库 |
| `knowledge.tb_knowledge_document` | createTableKnowledge.sql | 知识文档 |
| `file.tb_sys_file` | createTableFile.sql | 文件 |
| `file.tb_file_relation` | createTableFile.sql | 文件关联 |
| `message.tb_message` | createTableMessage.sql | 消息 |
| `message.tb_message_template` | createTableMessage.sql | 消息模板 |
| `log.tb_sys_log` | createTableLog.sql | 系统日志 |
### 查询示例
```java
// 招投标服务查询
public List<Document> getBiddingDocuments(String deptPath) {
return documentMapper.selectList(
new QueryWrapper<Document>()
.eq("service_type", "bidding") // 服务隔离
.likeRight("dept_path", deptPath) // 部门隔离
.eq("is_current", true) // 当前版本
.eq("deleted", false)
.orderByDesc("create_time")
);
}
```
---
## 三、知识库字段重命名
### 变更内容
将所有 `kb_id` 改为 `knowledge_id`，提升语义清晰度。
| 表名 | 变更 |
|------|------|
| `knowledge.tb_knowledge_base` | 主键：kb_id → knowledge_id |
| `knowledge.tb_knowledge_document` | 外键：kb_id → knowledge_id |
| `knowledge.tb_knowledge_chunk` | 外键：kb_id → knowledge_id |
| `knowledge.tb_knowledge_access_log` | 引用：kb_id → knowledge_id |
| `customer_service.tb_faq` | 引用：kb_id → knowledge_id |
### 影响范围
- ✅ 所有外键约束已更新
- ✅ 所有索引已更新
- ✅ 文档速查表已更新
---
## 四、智能体关联
### 知识库表新增字段
```sql
ALTER TABLE knowledge.tb_knowledge_base
ADD COLUMN agent_id VARCHAR(50); -- 关联智能体ID
```
### 说明
- 一个知识库可以关联一个智能体
- 智能体可以通过此字段快速查找其知识库
- 智能体表（tb_agent）当前已注释（暂不启用）
---
## 五、数据库初始化脚本
### initAll.sql（简化版）
```sql
-- =============================
-- 城市生命线AI数智化平台 - 数据库初始化脚本
-- 按顺序执行各模块建表SQL
-- =============================
\i createDB.sql
-- 1. 系统基础模块
\i createTablePermission.sql
\i createTableUser.sql
-- 2. 文件管理模块
\i createTableFile.sql
-- 3. 消息通知模块
\i createTableMessage.sql
-- 4. 日志模块
\i createTableLog.sql
-- 5. 配置管理模块
\i createTableConfig.sql
-- 6. 知识库管理模块
\i createTableKnowledge.sql
-- 7. 招投标业务模块
\i createTableBidding.sql
-- 8. 智能客服业务模块
\i createTableCustomerService.sql
-- 9. 智能体模块（暂不启用）
-- \i createTableAgent.sql
```
### 使用方式
```bash
# 进入PostgreSQL
psql -U postgres
# 执行初始化
\i /path/to/initAll.sql
```
---
## 六、测试/生产环境隔离方案
### 推荐方案：分别部署
```
测试环境：
├── 应用服务器：test-server:8080
├── 数据库：urbanlifeline_test
└── 配置：application-test.yml
生产环境：
├── 应用服务器：prod-server:8080
├── 数据库：urbanlifeline_prod
└── 配置：application-prod.yml
```
### 配置文件
**application-test.yml**
```yaml
spring:
datasource:
url: jdbc:postgresql://localhost:5432/urbanlifeline_test
username: postgres
password: test123
```
**application-prod.yml**
```yaml
spring:
datasource:
url: jdbc:postgresql://localhost:5432/urbanlifeline_prod
username: postgres
password: prod123
```
### 部署命令
```bash
# 测试服务器
java -jar urbanlifeline.jar --spring.profiles.active=test
# 生产服务器
java -jar urbanlifeline.jar --spring.profiles.active=prod
```
### 优势
✅ **简单清晰**：物理隔离，无需代码改动
✅ **安全可靠**：测试数据不会污染生产环境
✅ **易于维护**：独立部署，互不影响
✅ **性能独立**：测试压力不影响生产性能
---
## 七、SQL语法修复
### 修复内容
| 文件 | 问题 | 修复 |
|------|------|------|
| `createTableLog.sql` | 注释语句末尾使用逗号 | 改为分号 |
| `createTableMessage.sql` | service_type字段缺少逗号 | 添加逗号 |
---
## 八、数据库表结构总览
### 核心表关系
```
knowledge.tb_knowledge_base (知识库)
├── agent_id → agent.tb_agent (智能体)
└── knowledge_id ← knowledge.tb_knowledge_document (文档)
├── root_doc_id (版本组)
├── version (版本号)
├── is_current (当前版本)
└── knowledge_id ← knowledge.tb_knowledge_chunk (分段)
└── version (乐观锁版本)
```
### 隔离字段应用
```
所有业务表
├── service_type (服务隔离：bidding/customer_service/internal)
└── dept_path (部门隔离：/dept1/subdept1/)
```
---
## 九、最佳实践建议
### 1. 版本管理
✅ 每次上传新文档时设置 `root_doc_id = doc_id`
✅ 创建新版本前，标记旧版本 `is_current = false`
✅ 编辑分段时始终检查 `version` 字段（乐观锁）
### 2. 数据隔离
✅ 查询时始终添加 `service_type` 过滤
✅ 使用 MyBatis 拦截器自动注入隔离条件
✅ 敏感操作添加 `dept_path` 权限检查
### 3. 环境管理
✅ 测试/生产分别部署，使用不同数据库
✅ 配置文件使用 Spring Profile 管理
✅ Controller/Service/Mapper 层无需修改
---
## 十、待办事项
- [ ] 创建数据库迁移脚本（旧表 → 新表）
- [ ] 编写单元测试验证版本管理功能
- [ ] 配置 MyBatis 拦截器自动注入 service_type
- [ ] 准备生产环境部署文档
- [ ] 知识库数据导入/导出工具开发
---
## 附录：完整字段对照表
### tb_knowledge_document 字段清单
| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| doc_id | VARCHAR(50) | ✅ | 文档ID（主键） |
| knowledge_id | VARCHAR(50) | ✅ | 知识库ID |
| title | VARCHAR(500) | ✅ | 文档标题 |
| **version** | **INTEGER** | ✅ | **版本号（新增）** |
| **root_doc_id** | **VARCHAR(50)** | - | **根文档ID（新增）** |
| **is_current** | **BOOLEAN** | ✅ | **是否当前版本（新增）** |
| **service_type** | **VARCHAR(50)** | - | **服务类型（新增）** |
| dept_path | VARCHAR(255) | - | 部门路径 |
| deleted | BOOLEAN | ✅ | 软删除标记 |
### tb_knowledge_chunk 字段清单
| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| chunk_id | VARCHAR(50) | ✅ | 分段ID（主键） |
| doc_id | VARCHAR(50) | ✅ | 文档ID |
| knowledge_id | VARCHAR(50) | ✅ | 知识库ID |
| content | TEXT | ✅ | 分段内容 |
| **version** | **INTEGER** | ✅ | **版本号（乐观锁，新增）** |
| embedding | vector(1536) | - | 向量嵌入 |
| deleted | BOOLEAN | ✅ | 软删除标记 |
---
**文档生成时间：** 2025-12-02
**最后更新：** 知识库版本管理、多服务隔离、字段重命名

774
docs/数据库完整指南.md Normal file
View File

@@ -0,0 +1,774 @@
# 泰豪电源 AI 数智化平台 - 数据库完整指南
> **更新日期**: 2025-12-02
> **数据库**: PostgreSQL 16
> **总表数**: 50张核心业务表
---
## 📖 目录
1. [系统概述](#1-系统概述)
2. [Schema架构](#2-schema架构)
3. [核心模块设计](#3-核心模块设计)
4. [表结构速查](#4-表结构速查)
5. [优化方案](#5-优化方案)
6. [部署与维护](#6-部署与维护)
7. [常用查询示例](#7-常用查询示例)
---
## 1. 系统概述
### 1.1 设计理念
基于`功能结构.xml`的系统架构，遵循 **"一个底座、多种智能体"** 核心理念，支持四大业务模块：
1. **资料管理智能化**
2. **招投标自动化**
3. **售后客服智能化**
4. **企业内部知识协同**
### 1.2 技术选型
- **数据库**: PostgreSQL 16
- **连接池**: HikariCP
- **ORM**: MyBatis-Plus 3.5
- **迁移工具**: Flyway (可选)
### 1.3 设计原则
- ✅ **模块化**: 按业务模块划分 Schema
- ✅ **规范化**: 统一命名规范和字段设计
- ✅ **可扩展**: 预留扩展字段和软删除
- ✅ **高性能**: 合理索引和分区设计
- ✅ **安全性**: 行级安全和审计日志
---
## 2. Schema架构
### 2.1 Schema划分
采用多Schema架构，按业务模块逻辑隔离：
| Schema | 说明 | 核心表数量 | 用途 |
|--------|------|-----------|------|
| `sys` | 系统基础模块 | 11 | 用户、角色、权限、部门 |
| `file` | 文件管理模块 | 1 | 文件存储与管理 |
| `message` | 消息通知模块 | 4 | 站内信、系统通知 |
| `log` | 日志审计模块 | 1 | 操作日志、审计 |
| `config` | 系统配置模块 | 1 | 系统参数配置 |
| `knowledge` | 知识库管理模块 | 4 | 文档、分段、问答对 |
| `bidding` | 招投标智能体 | 8 | 招投标业务流程 |
| `customer_service` | 智能客服系统 | 9 | 客服、工单、对话 |
| `agent` | 智能体管理 | 11 | 智能体、API、监控 |
**总计: 50张核心业务表**
### 2.2 命名规范
```sql
-- Schema 命名: 小写字母
CREATE SCHEMA IF NOT EXISTS sys;
-- 表命名: tb_{schema}_{表名}
CREATE TABLE sys.tb_sys_user (...);
CREATE TABLE knowledge.tb_knowledge_document (...);
-- 字段命名: 小写字母 + 下划线
user_id, create_time, full_name
-- 索引命名: idx_{表名}_{字段名}
CREATE INDEX idx_user_email ON sys.tb_sys_user(email);
-- 外键命名: fk_{表名}_{关联表名}
CONSTRAINT fk_user_dept FOREIGN KEY (dept_id) ...
```
---
## 3. 核心模块设计
### 3.1 系统基础模块 (sys)
#### 权限体系设计
采用 **RBAC (基于角色的访问控制) + ACL (访问控制列表)** 混合模型
**核心表**:
- `tb_sys_user` - 用户表
- `tb_sys_role` - 角色表
- `tb_sys_permission` - 权限表
- `tb_sys_dept` - 部门表
- `tb_sys_acl` - 对象级权限表
- `tb_sys_user_role` - 用户角色关联表
**权限模型**:
```
用户 (User)
├─ 部门 (Dept) - 数据隔离
├─ 角色 (Role)
│ ├─ 权限 (Permission) - 功能权限
│ └─ 视图 (View) - 菜单权限
└─ ACL - 对象级权限（细粒度）
```
**设计亮点**:
1. 多租户支持: `dept_path` 字段实现部门级数据隔离
2. 角色作用域: `scope` 字段区分全局/部门角色
3. 对象权限: ACL表支持任意对象的细粒度权限
#### 核心表结构
```sql
-- 用户表
CREATE TABLE sys.tb_sys_user (
user_id VARCHAR(50) PRIMARY KEY,
username VARCHAR(50) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
email VARCHAR(100) UNIQUE,
phone VARCHAR(20),
wechat_id VARCHAR(100),
status VARCHAR(20) DEFAULT 'active',
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
update_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
deleted BOOLEAN DEFAULT false
);
-- 部门表（树形结构）
CREATE TABLE sys.tb_sys_dept (
dept_id VARCHAR(50) PRIMARY KEY,
dept_name VARCHAR(100) NOT NULL,
parent_id VARCHAR(50),
dept_path TEXT, -- 路径：/1/2/3/
sort_order INTEGER DEFAULT 0,
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
deleted BOOLEAN DEFAULT false,
CONSTRAINT fk_dept_parent FOREIGN KEY (parent_id)
REFERENCES sys.tb_sys_dept(dept_id)
);
-- 角色表
CREATE TABLE sys.tb_sys_role (
role_id VARCHAR(50) PRIMARY KEY,
role_name VARCHAR(100) NOT NULL,
role_code VARCHAR(50) UNIQUE NOT NULL,
scope VARCHAR(20) DEFAULT 'global', -- global/dept
owner_dept_id VARCHAR(50),
description TEXT,
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
deleted BOOLEAN DEFAULT false
);
-- ACL权限表
CREATE TABLE sys.tb_sys_acl (
acl_id VARCHAR(50) PRIMARY KEY,
object_type VARCHAR(50) NOT NULL, -- user/dept/document等
object_id VARCHAR(50) NOT NULL,
principal_type VARCHAR(20) NOT NULL, -- user/role/dept
principal_id VARCHAR(50) NOT NULL,
permission VARCHAR(50) NOT NULL, -- view/edit/delete/admin
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- 索引
CREATE INDEX idx_user_status ON sys.tb_sys_user(status) WHERE deleted = false;
CREATE INDEX idx_dept_path ON sys.tb_sys_dept USING GIN(dept_path gin_trgm_ops);
CREATE INDEX idx_acl_object ON sys.tb_sys_acl(object_type, object_id);
```
### 3.2 知识库管理模块 (knowledge)
#### 模块概述
支持文档管理、向量检索、RAG问答，版本控制。
**核心表**:
- `tb_knowledge_document` - 文档主表
- `tb_knowledge_chunk` - 文档分段表（向量检索）
- `tb_knowledge_qa_pair` - 问答对表
- `tb_knowledge_file_relation` - 文档文件关联表
#### 版本管理设计
采用 **简化版本管理** 方案：
```sql
-- 文档表（新增版本字段）
CREATE TABLE knowledge.tb_knowledge_document (
doc_id VARCHAR(50) PRIMARY KEY,
root_doc_id VARCHAR(50), -- ✨ 根文档ID（版本组标识）
version INTEGER DEFAULT 1, -- ✨ 版本号
is_current BOOLEAN DEFAULT true, -- ✨ 是否当前版本
title VARCHAR(500) NOT NULL,
content TEXT,
knowledge_base_id VARCHAR(50),
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
deleted BOOLEAN DEFAULT false
);
-- 分段表（向量检索）
CREATE TABLE knowledge.tb_knowledge_chunk (
chunk_id VARCHAR(50) PRIMARY KEY,
doc_id VARCHAR(50) NOT NULL,
chunk_index INTEGER NOT NULL,
content TEXT NOT NULL,
embedding VECTOR(1536), -- ✨ 向量字段（pgvector扩展）
version INTEGER DEFAULT 1, -- ✨ 乐观锁版本
tokens INTEGER,
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT fk_chunk_doc FOREIGN KEY (doc_id)
REFERENCES knowledge.tb_knowledge_document(doc_id)
);
-- 索引
CREATE INDEX idx_doc_root_current
ON knowledge.tb_knowledge_document(root_doc_id, is_current)
WHERE deleted = false;
CREATE INDEX idx_chunk_embedding
ON knowledge.tb_knowledge_chunk
USING ivfflat (embedding vector_cosine_ops) -- ✨ 向量索引
WITH (lists = 100);
```
**版本管理示例**:
```sql
-- 创建新版本
BEGIN;
-- 1. 标记旧版本为非当前
UPDATE knowledge.tb_knowledge_document
SET is_current = false
WHERE root_doc_id = 'root_xxx';
-- 2. 插入新版本
INSERT INTO knowledge.tb_knowledge_document (
doc_id, root_doc_id, version, is_current, title, content
) VALUES (
'new_doc_id', 'root_xxx', 2, true, '新版本标题', '内容'
);
COMMIT;
-- 查询当前版本
SELECT * FROM knowledge.tb_knowledge_document
WHERE root_doc_id = 'root_xxx' AND is_current = true;
-- 查询所有版本
SELECT version, title, create_time
FROM knowledge.tb_knowledge_document
WHERE root_doc_id = 'root_xxx'
ORDER BY version DESC;
```
### 3.3 招投标智能体模块 (bidding)
#### 核心表
```sql
-- 招标项目表
CREATE TABLE bidding.tb_bidding_project (
project_id VARCHAR(50) PRIMARY KEY,
project_name VARCHAR(500) NOT NULL,
project_code VARCHAR(100),
bidding_org VARCHAR(200), -- 招标单位
project_type VARCHAR(50), -- 项目类型
status VARCHAR(50) DEFAULT 'draft',
budget DECIMAL(18,2),
bid_deadline TIMESTAMP,
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
deleted BOOLEAN DEFAULT false
);
-- 招标文件表
CREATE TABLE bidding.tb_bidding_document (
doc_id VARCHAR(50) PRIMARY KEY,
project_id VARCHAR(50) NOT NULL,
doc_type VARCHAR(50), -- tender/technical/commercial
file_id VARCHAR(50),
parsed_content JSONB, -- ✨ 智能解析结果
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT fk_bdoc_project FOREIGN KEY (project_id)
REFERENCES bidding.tb_bidding_project(project_id)
);
-- 标书模板表
CREATE TABLE bidding.tb_bidding_template (
template_id VARCHAR(50) PRIMARY KEY,
template_name VARCHAR(200) NOT NULL,
template_type VARCHAR(50),
content JSONB, -- 模板结构化内容
variables JSONB, -- 可替换变量
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
### 3.4 智能客服系统模块 (customer_service)
#### 核心表
```sql
-- 对话会话表
CREATE TABLE customer_service.tb_cs_conversation (
conv_id VARCHAR(50) PRIMARY KEY,
customer_user_id VARCHAR(50),
customer_name VARCHAR(100),
channel VARCHAR(50), -- wechat/web/phone
source VARCHAR(50), -- miniprogram/h5/app
status VARCHAR(50) DEFAULT 'active',
start_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
end_time TIMESTAMP,
satisfaction_score INTEGER -- 满意度评分
);
-- 对话消息表
CREATE TABLE customer_service.tb_cs_message (
message_id VARCHAR(50) PRIMARY KEY,
conv_id VARCHAR(50) NOT NULL,
sender_type VARCHAR(20), -- customer/agent/bot
sender_id VARCHAR(50),
content TEXT,
message_type VARCHAR(50), -- text/image/file
ai_response JSONB, -- AI响应详情
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT fk_msg_conv FOREIGN KEY (conv_id)
REFERENCES customer_service.tb_cs_conversation(conv_id)
);
-- 工单表
CREATE TABLE customer_service.tb_cs_work_order (
order_id VARCHAR(50) PRIMARY KEY,
order_code VARCHAR(100) UNIQUE NOT NULL,
conv_id VARCHAR(50),
customer_user_id VARCHAR(50),
title VARCHAR(500) NOT NULL,
description TEXT,
category VARCHAR(100),
priority VARCHAR(20) DEFAULT 'medium',
status VARCHAR(50) DEFAULT 'pending',
assigned_to VARCHAR(50),
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
resolve_time TIMESTAMP
);
```
### 3.5 智能体管理模块 (agent)
#### 核心表
```sql
-- 智能体定义表
CREATE TABLE agent.tb_agent_definition (
agent_id VARCHAR(50) PRIMARY KEY,
agent_name VARCHAR(100) NOT NULL,
agent_type VARCHAR(50), -- bidding/cs/knowledge等
description TEXT,
config JSONB, -- 配置（模型、参数等）
status VARCHAR(20) DEFAULT 'active',
version VARCHAR(20),
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- API调用日志表
CREATE TABLE agent.tb_agent_api_log (
log_id VARCHAR(50) PRIMARY KEY,
agent_id VARCHAR(50),
api_endpoint VARCHAR(200),
request_params JSONB,
response_data JSONB,
status_code INTEGER,
duration_ms INTEGER,
create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- 智能体监控表（按月分区）
CREATE TABLE agent.tb_agent_monitor (
monitor_id VARCHAR(50) NOT NULL,
agent_id VARCHAR(50) NOT NULL,
metric_name VARCHAR(100),
metric_value NUMERIC,
timestamp TIMESTAMP NOT NULL,
PRIMARY KEY (monitor_id, timestamp)
) PARTITION BY RANGE (timestamp);
-- 创建分区
CREATE TABLE agent.tb_agent_monitor_2025_12
PARTITION OF agent.tb_agent_monitor
FOR VALUES FROM ('2025-12-01') TO ('2026-01-01');
```
---
## 4. 表结构速查
### 4.1 系统基础模块 (sys)
| 表名 | 主键 | 核心字段 | 说明 |
|------|------|----------|------|
| `tb_sys_user` | user_id | username, email, phone | 用户表 |
| `tb_sys_user_info` | user_id | avatar, full_name, level | 用户信息表 |
| `tb_sys_dept` | dept_id | name, parent_id, dept_path | 部门表 |
| `tb_sys_role` | role_id | name, scope, owner_dept_id | 角色表 |
| `tb_sys_permission` | permission_id | name, code, module_id | 权限表 |
| `tb_sys_acl` | acl_id | object_type, principal_type | 对象权限表 |
### 4.2 知识库管理 (knowledge)
| 表名 | 主键 | 核心字段 | 说明 |
|------|------|----------|------|
| `tb_knowledge_document` | doc_id | title, root_doc_id, version | 文档表 |
| `tb_knowledge_chunk` | chunk_id | doc_id, content, embedding | 分段表 |
| `tb_knowledge_qa_pair` | qa_pair_id | question, answer | 问答对表 |
### 4.3 招投标 (bidding)
| 表名 | 主键 | 核心字段 | 说明 |
|------|------|----------|------|
| `tb_bidding_project` | project_id | project_name, status | 招标项目表 |
| `tb_bidding_document` | doc_id | project_id, parsed_content | 招标文件表 |
| `tb_bidding_template` | template_id | template_name, content | 标书模板表 |
### 4.4 智能客服 (customer_service)
| 表名 | 主键 | 核心字段 | 说明 |
|------|------|----------|------|
| `tb_cs_conversation` | conv_id | customer_user_id, status | 对话会话表 |
| `tb_cs_message` | message_id | conv_id, content | 对话消息表 |
| `tb_cs_work_order` | order_id | title, status, assigned_to | 工单表 |
---
## 5. 优化方案
### 5.1 索引优化
```sql
-- 1. 复合索引（状态 + 时间查询）
CREATE INDEX idx_project_status_time
ON bidding.tb_bidding_project(status, create_time DESC)
WHERE deleted = false;
-- 2. 部分索引（只索引活跃数据）
CREATE INDEX idx_user_active
ON sys.tb_sys_user(user_id)
WHERE status = 'active' AND deleted = false;
-- 3. GIN索引（全文检索）
CREATE INDEX idx_doc_content_gin
ON knowledge.tb_knowledge_document
USING GIN(to_tsvector('chinese', title || ' ' || content));
-- 4. BRIN索引（时间序列）
CREATE INDEX idx_log_time_brin
ON log.tb_operation_log
USING BRIN(create_time);
```
### 5.2 分区策略
```sql
-- 按月分区（监控数据）
CREATE TABLE agent.tb_agent_monitor (
monitor_id VARCHAR(50) NOT NULL,
timestamp TIMESTAMP NOT NULL,
...
PRIMARY KEY (monitor_id, timestamp)
) PARTITION BY RANGE (timestamp);
-- 自动创建分区脚本
CREATE OR REPLACE FUNCTION create_monthly_partition()
RETURNS void AS $$
DECLARE
start_date DATE;
end_date DATE;
partition_name TEXT;
BEGIN
start_date := DATE_TRUNC('month', CURRENT_DATE + INTERVAL '1 month');
end_date := start_date + INTERVAL '1 month';
partition_name := 'tb_agent_monitor_' || TO_CHAR(start_date, 'YYYY_MM');
EXECUTE format(
'CREATE TABLE IF NOT EXISTS agent.%I PARTITION OF agent.tb_agent_monitor
FOR VALUES FROM (%L) TO (%L)',
partition_name, start_date, end_date
);
END;
$$ LANGUAGE plpgsql;
```
### 5.3 查询优化
```sql
-- 使用CTE优化复杂查询
WITH user_roles AS (
SELECT ur.user_id, r.role_id, r.role_code
FROM sys.tb_sys_user_role ur
JOIN sys.tb_sys_role r ON ur.role_id = r.role_id
WHERE r.deleted = false
),
user_permissions AS (
SELECT ur.user_id, p.permission_code
FROM user_roles 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
)
SELECT u.username, array_agg(DISTINCT up.permission_code) as permissions
FROM sys.tb_sys_user u
JOIN user_permissions up ON u.user_id = up.user_id
WHERE u.deleted = false
GROUP BY u.user_id, u.username;
```
### 5.4 并发控制
```sql
-- 乐观锁（版本号）
UPDATE knowledge.tb_knowledge_chunk
SET content = '新内容',
version = version + 1
WHERE chunk_id = 'xxx'
AND version = 1; -- 版本匹配才更新
-- 悲观锁
BEGIN;
SELECT * FROM bidding.tb_bidding_project
WHERE project_id = 'xxx'
FOR UPDATE; -- 锁定记录
-- 更新...
COMMIT;
```
---
## 6. 部署与维护
### 6.1 初始化脚本
```bash
# 位置: urbanLifelineServ/.bin/database/postgres/sql/
# 完整初始化
psql -U postgres -d urban_lifeline -f createTableAll.sql
# 分模块初始化
psql -U postgres -d urban_lifeline -f createTablePermission.sql
psql -U postgres -d urban_lifeline -f createTableKnowledge.sql
psql -U postgres -d urban_lifeline -f createTableBidding.sql
# 优化补丁
psql -U postgres -d urban_lifeline -f optimizations.sql
```
### 6.2 备份策略
```bash
# 全量备份
pg_dump -U postgres -d urban_lifeline -F c -f backup_$(date +%Y%m%d).dump
# 仅备份 Schema
pg_dump -U postgres -d urban_lifeline -s -f schema_backup.sql
# 仅备份数据
pg_dump -U postgres -d urban_lifeline -a -f data_backup.sql
# 还原
pg_restore -U postgres -d urban_lifeline backup_20251202.dump
```
### 6.3 监控指标
```sql
-- 表大小
SELECT
schemaname,
tablename,
pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) as size
FROM pg_tables
WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;
-- 索引使用情况
SELECT
schemaname, tablename, indexname,
idx_scan as index_scans,
idx_tup_read as tuples_read
FROM pg_stat_user_indexes
WHERE idx_scan = 0
ORDER BY schemaname, tablename;
-- 慢查询
SELECT
query,
calls,
total_time,
mean_time,
max_time
FROM pg_stat_statements
WHERE mean_time > 1000 -- 超过1秒
ORDER BY mean_time DESC
LIMIT 10;
```
---
## 7. 常用查询示例
### 7.1 用户权限查询
```sql
-- 查询用户的所有权限
SELECT DISTINCT p.permission_code, p.permission_name
FROM sys.tb_sys_user u
JOIN sys.tb_sys_user_role ur ON u.user_id = ur.user_id
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 u.username = 'admin'
AND u.deleted = false;
-- 查询部门下所有用户
WITH RECURSIVE dept_tree AS (
SELECT dept_id FROM sys.tb_sys_dept WHERE dept_id = 'target_dept_id'
UNION ALL
SELECT d.dept_id
FROM sys.tb_sys_dept d
JOIN dept_tree dt ON d.parent_id = dt.dept_id
)
SELECT u.*
FROM sys.tb_sys_user u
JOIN sys.tb_sys_user_dept ud ON u.user_id = ud.user_id
WHERE ud.dept_id IN (SELECT dept_id FROM dept_tree);
```
### 7.2 知识库查询
```sql
-- 向量相似度检索（Top 5）
SELECT
chunk_id,
content,
1 - (embedding <=> '[0.1, 0.2, ...]'::vector) as similarity
FROM knowledge.tb_knowledge_chunk
WHERE deleted = false
ORDER BY embedding <=> '[0.1, 0.2, ...]'::vector
LIMIT 5;
-- 查询文档的所有版本
SELECT
version,
title,
create_time,
is_current
FROM knowledge.tb_knowledge_document
WHERE root_doc_id = 'root_xxx'
ORDER BY version DESC;
```
### 7.3 招投标查询
```sql
-- 统计项目状态分布
SELECT
status,
COUNT(*) as count,
SUM(budget) as total_budget
FROM bidding.tb_bidding_project
WHERE deleted = false
GROUP BY status;
-- 查询即将截止的项目
SELECT
project_name,
bid_deadline,
EXTRACT(DAY FROM (bid_deadline - NOW())) as days_left
FROM bidding.tb_bidding_project
WHERE status = 'active'
AND bid_deadline > NOW()
AND deleted = false
ORDER BY bid_deadline ASC;
```
### 7.4 智能客服查询
```sql
-- 查询工单处理效率
SELECT
assigned_to,
COUNT(*) as total_orders,
AVG(EXTRACT(EPOCH FROM (resolve_time - create_time))/3600) as avg_hours,
COUNT(CASE WHEN status = 'resolved' THEN 1 END) as resolved_count
FROM customer_service.tb_cs_work_order
WHERE create_time > NOW() - INTERVAL '30 days'
GROUP BY assigned_to;
-- 查询满意度统计
SELECT
DATE(start_time) as date,
AVG(satisfaction_score) as avg_satisfaction,
COUNT(*) as total_conversations
FROM customer_service.tb_cs_conversation
WHERE satisfaction_score IS NOT NULL
AND start_time > NOW() - INTERVAL '7 days'
GROUP BY DATE(start_time)
ORDER BY date DESC;
```
---
## 附录
### A. SQL文件清单
```
urbanLifelineServ/.bin/database/postgres/sql/
├── createTableAll.sql # 完整初始化
├── createTablePermission.sql # 权限模块
├── createTableUser.sql # 用户模块
├── createTableFile.sql # 文件模块
├── createTableMessage.sql # 消息模块
├── createTableLog.sql # 日志模块
├── createTableConfig.sql # 配置模块
├── createTableKnowledge.sql # 知识库模块 ✨
├── createTableBidding.sql # 招投标模块 ✨
├── createTableCustomerService.sql # 智能客服模块 ✨
├── createTableAgent.sql # 智能体管理模块 ✨
├── optimizations.sql # 优化补丁 ✨
├── initDataPermission.sql # 权限初始数据
├── initDataUser.sql # 用户初始数据
└── initAll.sql # 完整初始化（表+数据）
```
### B. 扩展插件
```sql
-- 向量检索
CREATE EXTENSION IF NOT EXISTS vector;
-- 全文检索（中文）
CREATE EXTENSION IF NOT EXISTS zhparser;
CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser);
-- 模糊匹配
CREATE EXTENSION IF NOT EXISTS pg_trgm;
-- UUID生成
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
```
### C. 性能基准
| 指标 | 目标值 | 说明 |
|------|--------|------|
| 单表查询 | < 100ms | 主键/索引查询 |
| 复杂查询 | < 500ms | 多表JOIN |
| 向量检索 | < 200ms | Top-K检索 |
| 写入TPS | > 1000 | 批量插入 |
| 并发连接 | 200+ | HikariCP连接池 |
---
**最后更新**: 2025-12-02
**维护者**: Urban Lifeline Team

599
docs/数据库表结构速查.md
View File

@@ -1,599 +0,0 @@
# 数据库表结构速查手册
## 快速导航
- [系统基础模块 (sys)](#系统基础模块-sys)
- [文件管理模块 (file)](#文件管理模块-file)
- [消息通知模块 (message)](#消息通知模块-message)
- [日志模块 (log)](#日志模块-log)
- [配置管理模块 (config)](#配置管理模块-config)
- [知识库管理模块 (knowledge)](#知识库管理模块-knowledge)
- [招投标智能体模块 (bidding)](#招投标智能体模块-bidding)
- [智能客服系统模块 (customer_service)](#智能客服系统模块-customerservice)
- [智能体管理模块 (agent)](#智能体管理模块-agent)
---
## 系统基础模块 (sys)
### 核心表结构
| 表名 | 说明 | 主键 | 核心字段 |
|------|------|------|----------|
| `tb_sys_user` | 用户表 | user_id | email, phone, wechat_id, status |
| `tb_sys_user_info` | 用户信息表 | user_id | avatar, full_name, gender, level |
| `tb_sys_dept` | 部门表 | dept_id | name, parent_id, dept_path |
| `tb_sys_role` | 角色表 | role_id | name, scope, owner_dept_id |
| `tb_sys_permission` | 权限表 | permission_id | name, code, module_id |
| `tb_sys_user_role` | 用户角色关联表 | (user_id, role_id) | - |
| `tb_sys_role_permission` | 角色权限关联表 | (role_id, permission_id) | - |
| `tb_sys_view` | 视图/菜单表 | view_id | name, url, component, type |
| `tb_sys_module` | 模块表 | module_id | name, description |
| `tb_sys_acl` | 对象级权限表 | acl_id | object_type, object_id, principal_type, permission |
| `tb_sys_acl_policy` | ACL策略表 | policy_id | object_type, edit_hierarchy_rule, view_hierarchy_rule |
| `tb_sys_login_log` | 登录日志表 | optsn | user_id, ip_address, login_time, status |
| `tb_sys_user_dept` | 用户部门关联表 | (user_id, dept_id) | is_primary, position |
### 权限模型
```
用户 (tb_sys_user)
├─ 用户角色 (tb_sys_user_role)
│ └─ 角色 (tb_sys_role)
│ ├─ 角色权限 (tb_sys_role_permission)
│ │ └─ 权限 (tb_sys_permission)
│ │ └─ 模块 (tb_sys_module)
│ └─ 视图权限 (tb_sys_view_permission)
│ └─ 视图 (tb_sys_view)
└─ 对象权限 (tb_sys_acl)
└─ ACL策略 (tb_sys_acl_policy)
```
### 常用查询
```sql
-- 查询用户所有权限
SELECT p.code, p.name
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.user_id = 'USER_ID' AND ur.deleted = false;
-- 查询部门树
WITH RECURSIVE dept_tree AS (
SELECT *, 1 AS level FROM sys.tb_sys_dept WHERE parent_id IS NULL
UNION ALL
SELECT d.*, dt.level + 1
FROM sys.tb_sys_dept d
JOIN dept_tree dt ON d.parent_id = dt.dept_id
)
SELECT * FROM dept_tree ORDER BY level, dept_id;
```
---
## 文件管理模块 (file)
### 核心表结构
| 表名 | 说明 | 主键 | 核心字段 |
|------|------|------|----------|
| `tb_sys_file` | 文件表 | file_id | name, path, size, type, storage_type, url |
| `tb_file_relation` | 文件关联表 | relation_id | file_id, object_type, object_id, relation_type |
### 文件类型
- `storage_type`: local(本地存储) / oss(对象存储) / ftp / sftp
- `relation_type`: attachment(附件) / avatar(头像) / banner(横幅)
### 常用查询
```sql
-- 查询对象的所有附件
SELECT f.*
FROM file.tb_sys_file f
JOIN file.tb_file_relation fr ON f.file_id = fr.file_id
WHERE fr.object_type = 'bidding_project'
AND fr.object_id = 'PROJECT_ID'
AND fr.deleted = false;
```
---
## 消息通知模块 (message)
### 核心表结构
| 表名 | 说明 | 主键 | 核心字段 |
|------|------|------|----------|
| `tb_message` | 消息表 | message_id | title, content, type, status |
| `tb_message_range` | 消息发送范围表 | optsn | message_id, target_type, target_id, channel |
| `tb_message_receiver` | 用户消息接收表 | optsn | message_id, user_id, status, read_time |
| `tb_message_channel` | 消息渠道配置表 | channel_id | channel_code, channel_name, status |
| `tb_message_template` | 消息模板表 | template_id | template_code, title_template, content_template |
### 消息发送流程
```
创建消息 (tb_message)
↓
定义发送范围 (tb_message_range)
├─ target_type: user(指定用户) / dept(部门) / role(角色) / all(全员)
├─ channel: app / sms / email / wechat
↓
生成接收记录 (tb_message_receiver)
└─ status: unread → read → handled / deleted
```
### 常用查询
```sql
-- 查询用户未读消息
SELECT m.*, mr.create_time AS receive_time
FROM message.tb_message m
JOIN message.tb_message_receiver mr ON m.message_id = mr.message_id
WHERE mr.user_id = 'USER_ID'
AND mr.status = 'unread'
AND mr.deleted = false
ORDER BY mr.create_time DESC;
```
---
## 日志模块 (log)
### 核心表结构
| 表名 | 说明 | 主键 | 核心字段 |
|------|------|------|----------|
| `tb_sys_log` | 系统日志表 | log_id | type, level, module, message, data, trace_id |
### 日志级别
- `level`: debug / info / warn / error / fatal
- `type`: system / audit / security / business / api
### 常用查询
```sql
-- 查询错误日志
SELECT * FROM log.tb_sys_log
WHERE level IN ('error', 'fatal')
AND create_time > now() - interval '24 hours'
ORDER BY create_time DESC;
-- 链路追踪
SELECT * FROM log.tb_sys_log
WHERE trace_id = 'TRACE_ID'
ORDER BY create_time;
```
---
## 配置管理模块 (config)
### 核心表结构
| 表名 | 说明 | 主键 | 核心字段 |
|------|------|------|----------|
| `tb_sys_config` | 系统配置表 | config_id | key, name, value, config_type, render_type |
### 配置类型
- `config_type`: String / INTEGER / BOOLEAN / Float / Double
- `render_type`: select / input / textarea / checkbox / radio / switch
### 常用查询
```sql
-- 按模块查询配置
SELECT * FROM config.tb_sys_config
WHERE module_id = 'MODULE_ID' AND deleted = false
ORDER BY order_num;
```
---
## 知识库管理模块 (knowledge)
### 核心表结构
| 表名 | 说明 | 主键 | 核心字段 |
|------|------|------|----------|
| `tb_knowledge_base` | 知识库表 | knowledge_id | name, kb_type, access_level, version |
| `tb_knowledge_document` | 知识文档表 | doc_id | knowledge_id, title, doc_type, category, embedding_status |
| `tb_knowledge_chunk` | 文档片段表 | chunk_id | doc_id, knowledge_id, content, embedding |
| `tb_knowledge_access_log` | 知识访问日志表 | log_id | knowledge_id, doc_id, user_id, access_type |
### 知识库类型
- `kb_type`: bidding(招投标) / customer_service(客服) / internal(内部协同)
- `access_level`: public(公开) / private(私有) / internal(内部)
- `embedding_status`: pending(待处理) / processing(处理中) / completed(完成) / failed(失败)
### RAG检索流程
```
用户查询
↓
向量化查询文本
↓
在 tb_knowledge_chunk 中进行向量检索 (embedding)
↓
获取相关文档片段
↓
关联 tb_knowledge_document 获取完整文档信息
↓
返回结果 + 记录访问日志
```
### 常用查询
```sql
-- 查询知识库文档
SELECT d.*, kb.name AS kb_name
FROM knowledge.tb_knowledge_document d
JOIN knowledge.tb_knowledge_base kb ON d.knowledge_id = kb.knowledge_id
WHERE d.knowledge_id = 'knowledge_id'
AND d.embedding_status = 'completed'
AND d.deleted = false;
-- 向量检索（需要pgvector扩展）
-- SELECT chunk_id, content,
-- 1 - (embedding <=> '[查询向量]'::vector) AS similarity
-- FROM knowledge.tb_knowledge_chunk
-- WHERE knowledge_id = 'knowledge_id'
-- ORDER BY embedding <=> '[查询向量]'::vector
-- LIMIT 10;
```
---
## 招投标智能体模块 (bidding)
### 核心表结构
| 表名 | 说明 | 主键 | 核心字段 |
|------|------|------|----------|
| `tb_bidding_project` | 招标项目表 | project_id | project_no, project_name, project_status, deadline |
| `tb_bidding_document` | 招标文件表 | doc_id | project_id, doc_type, parse_status, parse_result |
| `tb_bidding_requirement` | 要素提取表 | req_id | project_id, req_category, is_veto, compliance_status |
| `tb_bid_response` | 投标文件生成表 | response_id | project_id, response_type, generation_status |
| `tb_bidding_scoring_rule` | 评分规则表 | rule_id | project_id, rule_category, max_score, our_score |
| `tb_bidding_process` | 流程节点表 | process_id | project_id, node_type, node_status |
| `tb_bid_template` | 投标模板表 | template_id | template_name, template_type, usage_count |
### 项目生命周期
```
collecting(收集中)
↓
analyzing(分析中) - 智能解读招标文件
↓
preparing(准备投标) - 生成投标文件
↓
submitted(已提交)
↓
opened(已开标)
↓
won(中标) / lost(未中标) / abandoned(放弃)
```
### 要素类别
- `req_category`:
- commercial: 商务要素
- technical: 技术参数
- veto: 否决项 ⚠️
- qualification: 资质要求
- delivery: 交付要求
- payment: 付款条件
- scoring: 评分标准
### 常用查询
```sql
-- 查询项目的所有否决项
SELECT * FROM bidding.tb_bidding_requirement
WHERE project_id = 'PROJECT_ID'
AND is_veto = true
AND deleted = false;
-- 查询项目评分预估
SELECT
rule_category,
SUM(max_score) AS total_max_score,
SUM(our_score) AS total_our_score,
ROUND(SUM(our_score) / SUM(max_score) * 100, 2) AS score_percentage
FROM bidding.tb_bidding_scoring_rule
WHERE project_id = 'PROJECT_ID' AND deleted = false
GROUP BY rule_category;
```
---
## 智能客服系统模块 (customer_service)
### 核心表结构
| 表名 | 说明 | 主键 | 核心字段 |
|------|------|------|----------|
| `tb_customer` | 客户信息表 | customer_id | customer_name, phone, wechat_openid, customer_level |
| `tb_conversation` | 会话表 | conversation_id | customer_id, conversation_type, agent_id, satisfaction_rating |
| `tb_conversation_message` | 会话消息表 | message_id | conversation_id, sender_type, content, is_ai_generated |
| `tb_ticket` | 工单表 | ticket_id | ticket_no, customer_id, ticket_type, ticket_status, sla_deadline |
| `tb_ticket_log` | 工单处理记录表 | log_id | ticket_id, action_type, action_content |
| `tb_faq` | FAQ表 | faq_id | category, question, answer, hit_count |
| `tb_service_evaluation` | 客服评价表 | evaluation_id | customer_id, evaluation_type, rating |
| `tb_crm_config` | CRM集成配置表 | config_id | crm_system, api_endpoint, sync_enabled |
### 会话流程
```
客户发起咨询
↓
创建会话 (tb_conversation)
├─ conversation_type: ai(AI客服) / human(人工) / transfer(转接)
↓
消息交互 (tb_conversation_message)
├─ sender_type: customer / agent / system
├─ is_ai_generated: true/false
├─ kb_references: [知识库文档ID]
↓
智能工单生成 (tb_ticket)
├─ ticket_source: ai / manual / system
↓
满意度评价 (tb_service_evaluation / tb_conversation)
```
### 工单状态
- `ticket_status`:
- pending: 待处理
- processing: 处理中
- resolved: 已解决
- closed: 已关闭
- cancelled: 已取消
### 常用查询
```sql
-- 查询客户的活跃会话
SELECT * FROM customer_service.tb_conversation
WHERE customer_id = 'CUSTOMER_ID'
AND conversation_status = 'active'
AND deleted = false;
-- 查询逾期工单
SELECT * FROM customer_service.tb_ticket
WHERE is_overdue = true
AND ticket_status IN ('pending', 'processing')
AND deleted = false
ORDER BY sla_deadline;
-- 查询AI回答质量
SELECT
DATE(create_time) AS stat_date,
AVG(confidence_score) AS avg_confidence,
COUNT(*) FILTER (WHERE confidence_score > 0.8) AS high_confidence_count,
COUNT(*) AS total_count
FROM customer_service.tb_conversation_message
WHERE is_ai_generated = true
AND deleted = false
GROUP BY DATE(create_time);
```
---
## 智能体管理模块 (agent)
### 核心表结构
| 表名 | 说明 | 主键 | 核心字段 |
|------|------|------|----------|
| `tb_agent` | 智能体定义表 | agent_id | agent_code, agent_name, agent_type, model_config |
| `tb_agent_session` | 智能体会话表 | session_id | agent_id, user_id, session_status, token_usage |
| `tb_agent_message` | 智能体消息表 | message_id | session_id, role, content, function_call |
| `tb_agent_tool` | 智能体工具表 | tool_id | tool_code, tool_type, function_schema, api_endpoint |
| `tb_api_integration` | API集成表 | integration_id | integration_name, base_url, auth_config |
| `tb_api_call_log` | API调用日志表 | log_id | integration_id, endpoint, response_status, duration_ms |
| `tb_agent_metrics` | 智能体监控指标表 | metric_id | agent_id, metric_date, total_sessions, total_tokens |
| `tb_agent_error_log` | 智能体异常日志表 | log_id | agent_id, error_type, error_message, severity |
| `tb_agent_rating` | 智能体评价表 | rating_id | agent_id, rating, feedback |
### 智能体类型
- `agent_type`:
- bidding: 招投标智能体
- customer_service: 客服智能体
- knowledge_assistant: 知识助手
- custom: 自定义智能体
### 工具类型
- `tool_type`:
- api: API调用
- function: 函数
- plugin: 插件
- integration: 集成
### 会话流程
```
用户请求
↓
创建会话 (tb_agent_session)
↓
消息交互 (tb_agent_message)
├─ role: user / assistant / system / function
├─ function_call: 工具调用
↓
工具执行 (tb_agent_tool)
├─ API调用记录 (tb_api_call_log)
↓
记录监控指标 (tb_agent_metrics)
├─ 错误记录 (tb_agent_error_log)
↓
用户评价 (tb_agent_rating)
```
### 常用查询
```sql
-- 查询智能体使用统计
SELECT * FROM agent.v_agent_usage_stats
WHERE agent_id = 'AGENT_ID';
-- 查询API健康状态
SELECT
integration_name,
health_status,
last_health_check,
EXTRACT(EPOCH FROM (now() - last_health_check))/60 AS minutes_since_check
FROM agent.tb_api_integration
WHERE deleted = false
ORDER BY health_status, last_health_check;
-- 查询智能体错误率
SELECT
a.agent_name,
COUNT(*) FILTER (WHERE e.severity = 'critical') AS critical_errors,
COUNT(*) FILTER (WHERE e.severity = 'error') AS errors,
COUNT(*) AS total_errors
FROM agent.tb_agent a
LEFT JOIN agent.tb_agent_error_log e ON a.agent_id = e.agent_id
WHERE e.create_time > now() - interval '24 hours'
GROUP BY a.agent_id, a.agent_name;
```
---
## 数据字典常用字段说明
### 通用字段
所有表都包含以下标准字段：
| 字段 | 类型 | 说明 |
|------|------|------|
| `optsn` | VARCHAR(50) | 流水号（唯一标识） |
| `xxx_id` | VARCHAR(50) | 主键ID |
| `dept_path` | VARCHAR(255) | 部门全路径（多租户隔离） |
| `creator` | VARCHAR(50) | 创建者ID |
| `updater` | VARCHAR(50) | 更新者ID |
| `create_time` | TIMESTAMPTZ | 创建时间（带时区） |
| `update_time` | TIMESTAMPTZ | 更新时间（触发器自动更新） |
| `delete_time` | TIMESTAMPTZ | 删除时间 |
| `deleted` | BOOLEAN | 软删除标记 |
### 时间戳说明
- 使用 `TIMESTAMPTZ` 类型（带时区的时间戳）
- 自动记录创建时间
- 更新时间由触发器自动维护
- 支持软删除（保留 delete_time）
### 部门路径（dept_path）
格式：`/1/2/3/`
- 用于多租户数据隔离
- 支持 LIKE 递归查询
- 示例查询：`WHERE dept_path LIKE '/1/2/%'`
---
## 视图速查
| 视图名 | Schema | 说明 |
|--------|--------|------|
| `v_user_full_info` | sys | 用户完整信息（含用户信息表） |
| `v_user_role_permission` | sys | 用户角色权限（含模块） |
| `v_user_full_permissions` | sys | 用户完整权限（含ACL） |
| `v_agent_usage_stats` | agent | 智能体使用统计 |
| `v_agent_realtime_status` | agent | 智能体实时状态 |
| `v_ticket_stats` | customer_service | 工单统计 |
| `v_ticket_efficiency` | customer_service | 工单处理效率 |
| `v_project_stats` | bidding | 招投标项目统计 |
---
## 函数速查
| 函数名 | Schema | 说明 |
|--------|--------|------|
| `update_modified_column()` | public | 自动更新update_time触发器函数 |
| `audit_trigger_func()` | public | 审计日志触发器函数 |
| `archive_old_logs()` | public | 归档旧日志数据 |
| `archive_api_logs()` | agent | 归档API调用日志 |
| `check_table_bloat()` | public | 检查表膨胀情况 |
| `create_update_triggers()` | public | 批量创建更新触发器 |
---
## 索引策略
### 主要索引类型
1. **B-Tree索引**（默认）：主键、外键、常规查询字段
2. **GIN索引**：JSONB字段、数组字段、全文搜索
3. **部分索引**：带WHERE条件的索引（如 `WHERE deleted = false`）
4. **表达式索引**：函数索引（如 `lower(email)`）
### 关键索引示例
```sql
-- 部分索引（减少索引大小）
CREATE INDEX idx_xxx ON table_name(column) WHERE deleted = false;
-- GIN索引（数组查询）
CREATE INDEX idx_xxx ON table_name USING gin(array_column);
-- 全文搜索索引
CREATE INDEX idx_xxx ON table_name USING gin(text_column gin_trgm_ops);
-- 表达式索引
CREATE INDEX idx_xxx ON table_name(lower(email));
```
---
## 性能优化建议
### 查询优化
1. **使用索引**：WHERE、JOIN、ORDER BY字段都要有索引
2. **避免SELECT ***：只查询需要的字段
3. **使用LIMIT**：分页查询限制返回行数
4. **使用EXPLAIN**：分析查询计划
### 批量操作
```sql
-- 批量插入（使用COPY或批量INSERT）
COPY table_name FROM '/path/to/file.csv' WITH CSV;
-- 批量更新（使用UPDATE...FROM）
UPDATE table_name t
SET column = data.value
FROM (VALUES (1, 'a'), (2, 'b')) AS data(id, value)
WHERE t.id = data.id;
```
### 定期维护
```sql
-- 分析表（更新统计信息）
ANALYZE table_name;
-- 清理和分析
VACUUM ANALYZE table_name;
-- 重建索引
REINDEX TABLE table_name;
```
---
**版本**: 1.0
**更新时间**: 2024-12-02

511
docs/数据库设计交付总结.md
View File

@@ -1,511 +0,0 @@
# 泰豪电源AI数智化平台 - 数据库设计交付总结
## 📋 交付概览
基于`功能结构.xml`中定义的系统架构，完成了泰豪电源AI数智化平台的完整数据库设计，覆盖"一个底座、多种智能体"的核心理念和四大业务模块。
---
## 📦 交付内容
### 1. SQL脚本文件
所有文件位于：`urbanLifelineServ\.bin\database\postgres\sql\`
| 文件名 | 说明 | 表数量 |
|--------|------|--------|
| `createTablePermission.sql` | 系统权限模块（现有优化） | 11张 |
| `createTableUser.sql` | 用户管理模块（现有优化） | 3张 |
| `createTableFile.sql` | 文件管理模块（现有） | 1张 |
| `createTableMessage.sql` | 消息通知模块（现有） | 4张 |
| `createTableLog.sql` | 日志模块（现有） | 1张 |
| `createTableConfig.sql` | 配置管理模块（现有） | 1张 |
| **`createTableKnowledge.sql`** | ✨ **知识库管理模块（新建）** | **4张** |
| **`createTableBidding.sql`** | ✨ **招投标智能体业务模块（新建）** | **8张** |
| **`createTableCustomerService.sql`** | ✨ **智能客服系统业务模块（新建）** | **9张** |
| **`createTableAgent.sql`** | ✨ **智能体管理模块（新建）** | **11张** |
| **`createTableAll.sql`** | ✨ **完整初始化脚本（新建）** | - |
| **`optimizations.sql`** | ✨ **数据库优化补丁（新建）** | - |
**总计：53张核心业务表**
### 2. 文档资料
所有文档位于：`docs\`
| 文件名 | 说明 |
|--------|------|
| **`数据库设计文档.md`** | 完整的数据库设计说明文档（23000+字） |
| **`数据库表结构速查.md`** | 表结构快速参考手册（含常用查询示例） |
| **`数据库设计交付总结.md`** | 本文档 |
---
## 🎯 核心设计亮点
### 1. 模块化架构设计
采用9个Schema实现业务逻辑隔离：
```
sys ← 系统基础（用户、权限、部门）
file ← 文件管理
message ← 消息通知
log ← 日志审计
config ← 系统配置
knowledge ← 知识库管理（支持RAG检索）
bidding ← 招投标智能体业务
customer_service ← 智能客服系统业务
agent ← 智能体管理和平台基础设施
```
### 2. 权限体系设计
**RBAC + ACL混合模型**
- **RBAC（基于角色的访问控制）**：
- 支持全局角色和部门私有角色
- 角色-权限-模块三层结构
- 视图/菜单权限独立管理
- **ACL（访问控制列表）**：
- 对象级细粒度权限控制
- 支持任意对象类型（文章、文件、课程等）
- 权限位设计（读/写/执行）
- 支持显式拒绝和权限继承
### 3. 多租户支持
- **部门路径隔离**（`dept_path`字段）：格式 `/1/2/3/`
- **行级安全策略**（RLS）：基于用户部门自动过滤数据
- **作用域控制**：角色和权限的作用域管理
### 4. 知识库智能管理
**支持RAG（检索增强生成）流程：**
```
文档上传 → 智能分类 → AI摘要 → 关键词提取 → 文档切片 → 向量化 → 存储
↓ ↓
tb_knowledge_document tb_knowledge_chunk
(支持向量检索)
```
**特性：**
- 多类型知识库（招投标/客服/内部协同）
- 版本管理和历史追溯
- 向量化状态跟踪
- 访问日志记录
### 5. 招投标全流程管理
**完整业务流程覆盖：**
```
项目创建 → 文件采集 → 智能解读 → 要素提取 → 评分分析
↓ ↓
流程跟踪 ← 投标提交 ← 文件审核 ← 投标文件生成 ← 模板管理
```
**核心功能：**
- **智能要素提取**：7大类要素（商务/技术/否决项/资质/交付/付款/评分）
- **AI文件生成**：支持技术标/商务标/综合标
- **评分规则分析**：自动解析评分标准，预估得分
- **流程节点管理**：完整的项目生命周期跟踪
### 6. 智能客服系统
**全渠道客服支持：**
```
微信小程序 → AI问答 → 知识库检索 → 工单生成 → CRM同步
↓ ↓ ↓ ↓
客户管理 会话记录 工单处理 满意度评价
```
**特性：**
- **双终端知识库**：客户咨询知识库（外部）+ 内部资料知识库（内部）
- **智能会话管理**：AI/人工/转接会话类型，情感分析，意图识别
- **工单智能处理**：AI自动生成工单，SLA超时预警，CRM双向同步
- **评价体系**：多维度评价（准确性、速度、友好度等）
### 7. 智能体管理平台
**智能体广场 + 工具集成 + 运维监控：**
```
智能体定义 → 工具配置 → API集成 → 会话管理 → 监控运维 → 评价反馈
↓ ↓ ↓ ↓ ↓
多模型支持 Function 健康检查 Token统计 错误追踪
```
**特性：**
- **智能体广场**：发布/评分/分类/标签管理
- **工具生态**：支持API调用、函数、插件、集成
- **监控体系**：实时指标、错误日志、性能分析
- **成本跟踪**：Token使用量、API调用费用统计
---
## 📊 数据库架构统计
### 表结构统计
| Schema | 表数量 | 主要功能 |
|--------|--------|----------|
| sys | 13 | 用户、角色、权限、部门、ACL |
| file | 2 | 文件管理、文件关联 |
| message | 5 | 消息、发送范围、接收记录、渠道、模板 |
| log | 1 | 系统日志 |
| config | 1 | 系统配置 |
| knowledge | 4 | 知识库、文档、片段、访问日志 |
| bidding | 8 | 项目、文件、要素、投标、评分、流程、模板 |
| customer_service | 9 | 客户、会话、消息、工单、FAQ、评价、CRM |
| agent | 11 | 智能体、会话、消息、工具、API、监控、错误 |
| **总计** | **54** | - |
### 索引策略
- **B-Tree索引**：100+ 个（主键、外键、常规查询）
- **GIN索引**：20+ 个（JSONB、数组、全文搜索）
- **部分索引**：50+ 个（WHERE deleted = false）
- **表达式索引**：5+ 个（函数索引）
### 视图和函数
- **业务视图**：8个（权限视图、统计视图）
- **触发器函数**：2个（自动更新时间、审计日志）
- **业务函数**：4个（数据归档、性能监控）
---
## 🔧 技术特性
### 1. 数据类型使用
- **TIMESTAMPTZ**：全部时间字段（带时区支持）
- **JSONB**：配置、元数据、扩展字段
- **数组（TEXT[]）**：标签、关键词、ID列表
- **DECIMAL**：金额、评分（精确计算）
- **vector**：向量嵌入（需pgvector扩展，可选）
### 2. 软删除机制
所有业务表支持软删除：
- `deleted` 字段：BOOLEAN类型，默认false
- `delete_time` 字段：删除时间戳
- 索引优化：`WHERE deleted = false`
### 3. 审计追踪
- **通用字段**：creator、updater、create_time、update_time
- **自动触发器**：update_time自动更新
- **审计日志**：可选的审计触发器（记录所有变更）
- **链路追踪**：trace_id、span_id支持分布式追踪
### 4. 性能优化
- **分区表设计**：日志表、指标表建议按时间分区
- **物化视图**：权限视图可物化提升性能
- **数据归档**：提供自动归档函数
- **表膨胀监控**：check_table_bloat()函数
---
## 📈 业务价值
### 1. 支撑功能结构.xml定义的四大业务模块
✅ **资料管理智能化** → knowledge模块
✅ **招投标自动化** → bidding模块
✅ **售后客服智能化** → customer_service模块
✅ **企业内部知识协同** → knowledge + agent模块
### 2. 实现"一个底座、多种智能体"
- **统一的智能体管理平台**（agent模块）
- **共享的知识库体系**（knowledge模块）
- **统一的权限和用户管理**（sys模块）
- **统一的文件和消息服务**（file、message模块）
### 3. 可扩展性设计
- **新增智能体类型**：在agent.tb_agent中添加新的agent_type
- **新增业务模块**：创建新的Schema和表
- **集成外部系统**：通过API集成表和CRM配置表
- **自定义权限**：通过ACL表实现任意对象的权限控制
---
## 🚀 部署指南
### 快速部署
```bash
# 进入SQL脚本目录
cd urbanLifelineServ\.bin\database\postgres\sql
# 1. 创建数据库
createdb urbanlifeline
# 2. 执行完整初始化脚本（推荐）
psql -d urbanlifeline -f createTableAll.sql
# 或者手动按顺序执行
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 optimizations.sql
# 4. 初始化基础数据
psql -d urbanlifeline -f initDataConfig.sql
```
### 依赖扩展
```sql
-- 必需扩展
CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; -- UUID生成
CREATE EXTENSION IF NOT EXISTS "pg_trgm"; -- 全文搜索
CREATE EXTENSION IF NOT EXISTS "btree_gin"; -- GIN索引支持
-- 可选扩展
CREATE EXTENSION IF NOT EXISTS "pgcrypto"; -- 数据加密
CREATE EXTENSION IF NOT EXISTS "vector"; -- 向量检索（需单独安装）
```
---
## 🔍 现有SQL文件的优化建议
### 已实施的优化
✅ **createTableUser.sql**
- 移除登录日志表的password字段（安全性）
- 添加用户部门关联表（多对多关系）
- 添加主部门字段
✅ **createTablePermission.sql**
- 添加角色排序字段
- 添加权限类型字段（操作/数据/菜单权限）
✅ **createTableFile.sql**
- 添加版本管理字段
- 添加分类和标签
- 创建文件关联表（统一文件关联机制）
✅ **createTableMessage.sql**
- 创建消息模板表（支持模板化发送）
✅ **createTableLog.sql**
- 添加链路追踪字段（trace_id、span_id）
### 建议的补充优化
详见：`optimizations.sql`文件
---
## 📚 参考文档
### 1. 数据库设计文档.md
**内容包含：**
- 系统概述和架构设计
- 核心模块详细设计
- 数据库优化建议
- 现有SQL文件修改建议
- 数据安全建议
- 部署和维护建议
**适用场景：**
- 系统架构师了解整体设计
- 开发人员理解业务逻辑
- DBA进行数据库优化
### 2. 数据库表结构速查.md
**内容包含：**
- 所有模块的表结构快速参考
- 常用查询示例
- 视图和函数速查
- 索引策略说明
- 性能优化建议
**适用场景：**
- 日常开发查询表结构
- 编写业务SQL
- 快速定位相关表
### 3. 功能结构.xml
**原始需求文档：**
- 系统目标定义
- 四大业务模块功能划分
- 平台基础设施模块
- Draw.io格式的架构图
---
## ✅ 验证检查清单
### 数据完整性
- [x] 所有表都有主键
- [x] 外键关系正确定义
- [x] 唯一约束合理设置
- [x] 非空约束符合业务逻辑
### 性能优化
- [x] 高频查询字段都有索引
- [x] 外键字段都有索引
- [x] 使用部分索引减少索引大小
- [x] JSONB和数组字段使用GIN索引
### 安全性
- [x] 敏感字段移除或加密
- [x] 软删除机制
- [x] 审计日志支持
- [x] 行级安全策略（可选启用）
### 可维护性
- [x] 表名和字段名规范统一
- [x] 所有表和字段都有注释
- [x] 触发器自动维护update_time
- [x] 提供数据归档函数
### 可扩展性
- [x] Schema分离便于模块扩展
- [x] JSONB字段支持灵活扩展
- [x] 标签和分类字段
- [x] 元数据字段预留
---
## 📊 后续优化方向
### 短期（1-3个月）
1. **向量检索优化**
- 安装pgvector扩展
- 优化embedding索引参数
- 实现混合检索（向量+全文）
2. **监控告警**
- 集成pgBadger日志分析
- 配置慢查询告警
- 设置表膨胀告警
3. **数据初始化**
- 编写初始化数据脚本
- 创建测试数据集
- 准备演示数据
### 中期（3-6个月）
1. **性能优化**
- 分析慢查询并优化
- 实施分区表策略
- 创建物化视图
2. **读写分离**
- 配置主从复制
- 实现读写分离中间件
- 优化读库查询
3. **备份策略**
- 实施全量+增量备份
- 配置WAL归档
- 演练灾难恢复
### 长期（6-12个月）
1. **分布式部署**
- 评估Citus扩展
- 设计分片策略
- 实现水平扩展
2. **多数据中心**
- 配置异地备份
- 实现数据同步
- 制定灾备方案
3. **智能优化**
- 自动索引推荐
- 查询性能自动优化
- 存储自动扩容
---
## 🎓 技术栈总结
### 数据库技术
- **PostgreSQL 14+**：主数据库
- **pgvector**：向量检索（可选）
- **pg_trgm**：全文搜索
- **JSONB**：半结构化数据存储
- **Row Level Security**：行级安全策略
### 设计模式
- **RBAC + ACL**：混合权限模型
- **软删除**：数据安全保护
- **多租户**：部门路径隔离
- **审计追踪**：完整的变更记录
- **事件驱动**：触发器自动化
### 性能优化
- **索引策略**：B-Tree + GIN + 部分索引
- **查询优化**：视图、CTE、窗口函数
- **数据归档**：自动归档函数
- **分区表**：时间序列数据分区
---
## 📞 技术支持
### 问题反馈
如在使用过程中遇到问题，请提供：
1. 问题描述
2. 错误信息
3. 执行的SQL语句
4. PostgreSQL版本
### 文档维护
本文档随数据库设计持续更新：
- **当前版本**：v1.0
- **更新日期**：2024-12-02
- **维护团队**：泰豪电源AI数智化平台开发组
---
## 🎉 交付完成
✅ **50+张核心业务表设计完成**
✅ **12个SQL脚本文件交付**
✅ **3份完整技术文档**
✅ **覆盖4大业务模块**
✅ **支持"一个底座、多种智能体"架构**
**数据库设计已完全就绪，可直接用于项目开发！** 🚀
---
**感谢使用！**

698
docs/数据库设计文档.md
View File

@@ -1,698 +0,0 @@
# 泰豪电源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数智化平台开发组