# data-summary

**Repository Path**: kai_kai_chi/data-summary

## Basic Information

- **Project Name**: data-summary
- **Description**: Used to collect data from equipment.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-02-24
- **Last Updated**: 2026-05-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Data Summary 电表数据管理系统 - 微服务架构全面技术文档

## 一、项目概览

### 1.1 业务领域

智能电网/物联网电表管理系统，用于住宅或商业建筑的电表设备数据采集、用量统计、异常告警和AI辅助交互。系统支持多台电表设备的实时数据上报、自动计算用电量差值、异常检测与告警生成、日/月/年维度的统计聚合，以及基于RAG的智能问答助手。

### 1.2 核心数据流

```
电表设备 → Kafka(meter-data) → Receiver消费 → 计算用量差值 → 异常检测 → 入库
                                              ↓
                                    Statistics定时聚合 → 日/月/年报表 → Dashboard展示
```

**详细数据处理流程：**

```
┌─────────────────────────────────────────────────────────────────┐
│                        数据处理流程                              │
└─────────────────────────────────────────────────────────────────┘

1. 电表设备 → Kafka (meter-data主题)
       │
       ▼
2. Receiver Service 消费消息
       │
       ├──→ 解析JSON报文 {deviceSn, timestamp, meterReading}
       ├──→ 查询设备信息 (按SN查找)
       ├──→ 计算用电量增量 (当前读数 - 上次读数)
       ├──→ 异常检测 (负差值/超阈值)
       │
       ▼
3. 数据存储 (PostgreSQL)
       │
       ├──→ report_data表 (原始上报数据)
       ├──→ data_summary_each_piece表 (每次用电量)
       ├──→ equipment表 (更新最后上报信息)
       └──→ equipment_alert表 (如有异常)
       │
       ▼
4. 触发统计
       │
       └──→ 调用 Statistics Service /statistical/trigger
              │
              ├──→ data_summary_each_day表 (日统计)
              └──→ data_summary_each_month表 (月统计)
```

### 1.3 系统架构总览

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              用户浏览器                                      │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           Nginx (前端 :3000)                                │
│   ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                      │
│   │  /api/* │  │/chat-api│  │/equipment│ │/statistical│                    │
│   └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘                      │
└────────┼────────────┼────────────┼────────────┼────────────────────────────┘
         │            │            │            │
         ▼            ▼            ▼            ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    Spring Cloud Gateway (:8080)                             │
│   ┌─────────────────────────────────────────────────────────────────┐      │
│   │  路由: /equipment/* → equipment:8081                            │      │
│   │  路由: /statistical/* → statistics:8083                         │      │
│   │  路由: /dashboard/* → statistics:8083                           │      │
│   │  路由: /alert/* → equipment:8081                                │      │
│   └─────────────────────────────────────────────────────────────────┘      │
└─────────────────────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│Equipment Service│  │Receiver Service │  │Statistics Service│
│    (:8081)      │  │    (:8082)      │  │    (:8083)      │
│                 │  │                 │  │                 │
│ - 设备CRUD      │  │ - Kafka消费     │  │ - 日/月/年统计  │
│ - 告警管理      │  │ - 报文解析      │  │ - 数据导出      │
│ - 上报数据      │  │ - 用电量计算    │  │ - 仪表盘数据    │
└────────┬────────┘  └────────┬────────┘  └────────┬────────┘
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              数据存储层                                      │
│  ┌─────────────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐              │
│  │ PostgreSQL 16   │  │  Redis  │  │  Kafka  │  │PGVector │              │
│  │  (主库+向量库)  │  │  :6379  │  │  :9092  │  │  (内置) │              │
│  │     :5432       │  │         │  │         │  │         │              │
│  └─────────────────┘  └─────────┘  └─────────┘  └─────────┘              │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           可观测性平台                                       │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐         │
│  │Prometheus│ │ Grafana │  │  Jaeger │  │   Loki  │  │Promtail │         │
│  │  :9090  │  │  :3001  │  │ :16686  │  │  :3100  │  │         │         │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘         │
└─────────────────────────────────────────────────────────────────────────────┘
```

## 二、微服务架构详解

### 2.1 四层架构

| 层级 | 组件 | 端口 | 技术栈 | 职责 |
|------|------|------|--------|------|
| **展示层** | Frontend | 3000 | Vue 3 + Vuetify + Vite + TypeScript | 用户界面、数据可视化、AI聊天 |
| **网关层** | Gateway | 8080 | Spring Cloud Gateway (WebFlux) + JWT | 路由转发、JWT认证、安全头注入 |
| **业务层** | Equipment Service | 8081 | Spring Boot 3.4.5 + MyBatis | 设备CRUD、告警管理 |
| | Receiver Service | 8082 | Spring Boot + Kafka Consumer | 消息消费、数据处理、异常检测 |
| | Statistics Service | 8083 | Spring Boot + 定时任务 | 统计聚合、Dashboard、数据导出 |
| | Chat-Boot | 9999 | FastAPI + LangChain/LangGraph + RAG | AI助手、文档问答、会话管理 |
| **数据层** | PostgreSQL 16 (pgvector) | 5432 | 主存储 + 向量库 | 持久化存储、向量检索 |
| | Redis 7 | 6379 | 缓存 + 会话存储 | 会话缓存、语义缓存 |
| | Apache Kafka 3.8 | 9092 | 异步消息队列 | 设备数据异步处理 |

### 2.2 服务端口与路由

| 服务 | 端口 | 说明 |
|------|------|------|
| Frontend | 3000 | Nginx代理转发至gateway/chat-boot |
| Gateway | 8080 | 统一API入口 |
| Equipment | 8081 | 设备CRUD + 告警 |
| Receiver | 8082 | Kafka消费、数据处理 |
| Statistics | 8083 | 统计聚合 + Dashboard |
| Chat-boot | 9999 | AI助手 + 认证 |
| Grafana | 3001 | 监控面板 (admin/admin) |
| Jaeger | 16686 | 分布式链路追踪 |
| Prometheus | 9090 | 指标查询 |

### 2.3 Gateway路由配置

```yaml
# application.yml 路由规则
routes:
  - id: equipment
    uri: http://equipment:8081
    predicates: Path=/equipment/**
  - id: alert
    uri: http://equipment:8081
    predicates: Path=/alert/**
  - id: statistical
    uri: http://statistics:8083
    predicates: Path=/statistical/**
  - id: dashboard
    uri: http://statistics:8083
    predicates: Path=/dashboard/**
```

### 2.4 前端代理配置

**Vite开发服务器代理：**

```typescript
// vite.config.ts
server: {
  port: 3000,
  proxy: {
    '/api/auth/': {
      target: 'http://127.0.0.1:9999',
      rewrite: path => path.replace(/^\/api/, '')
    },
    '/api': {
      target: 'http://127.0.0.1:8080',
      rewrite: path => path.replace(/^\/api/, '')
    },
    '/chat-api': {
      target: 'http://127.0.0.1:9999',
      rewrite: path => path.replace(/^\/chat-api/, '')
    }
  }
}
```

**Nginx生产环境配置：**

```nginx
# frontend/nginx.conf 关键规则
location /api/auth/ {
    proxy_pass http://chat-boot:9999;  # 认证路由优先匹配
    rewrite ^/api(.*)$ $1 break;
}

location /api/ {
    proxy_pass http://gateway:8080;
    rewrite ^/api(.*)$ $1 break;
}

location /chat-api/ {
    proxy_pass http://chat-boot:9999;
    proxy_buffering off;      # SSE支持
    proxy_cache off;
    proxy_http_version 1.1;
    chunked_transfer_encoding off;
}
```

**关键规则**：`/api/auth/` 必须在 `/api/` 之前匹配，否则认证请求会被错误路由到Gateway。

## 三、后端Java深度分析

### 3.1 技术栈详情

| 组件 | 技术 | 版本 | 说明 |
|------|------|------|------|
| **开发语言** | Java | 21 LTS | 长期支持版本，支持虚拟线程 |
| **基础框架** | Spring Boot | 3.4.5 | 2026年主流版本 |
| **微服务框架** | Spring Cloud | 2024.0.1 | 微服务全家桶 |
| **API网关** | Spring Cloud Gateway | 4.1+ | 响应式网关 (WebFlux) |
| **ORM框架** | MyBatis | 3.0.4 | XML映射 |
| **安全** | JJWT | 0.12.6 | JWT令牌生成与验证 |
| | Spring Security | 6.x | 认证授权框架 |
| **文档** | SpringDoc | 2.7.0 | Swagger/OpenAPI文档 |
| **工具** | Lombok | - | 代码简化 |
| | Apache POI | - | Excel导出 |
| | OpenCSV | - | CSV导出 |

### 3.2 模块结构

```
back-end/
├── common-module/          # 共享库
│   ├── ApiResponse.java    # 统一响应格式 {code, message, data}
│   ├── PageResult.java     # 分页结果封装 {items, total, page, size}
│   ├── SummaryData.java    # 统计数据DTO
│   ├── DateUtil.java       # 日期工具
│   └── GatewayAuthFilter   # 网关认证过滤器
│
├── gateway-service/        # API网关 (:8080)
│   ├── SecurityConfig.java         # 安全配置
│   ├── JwtAuthenticationFilter.java # JWT认证过滤器
│   ├── JwtTokenProvider.java       # JWT工具
│   └── application.yml             # 路由配置
│
├── equipment-service/      # 设备服务 (:8081)
│   ├── controller/
│   │   ├── EquipmentController.java      # 设备API
│   │   └── EquipmentAlertController.java # 告警API
│   ├── mapper/
│   │   ├── EquipmentMapper.java          # 设备Mapper
│   │   └── EquipmentAlertMapper.java     # 告警Mapper
│   ├── model/
│   │   ├── po/                           # 持久化对象
│   │   │   ├── Equipment.java            # 设备实体
│   │   │   └── EquipmentAlert.java       # 告警实体
│   │   └── dto/                          # 数据传输对象
│   │       ├── EquipmentCreateRequest.java
│   │       └── EquipmentUpdateRequest.java
│   └── service/
│       ├── EquipmentService.java
│       ├── EquipmentAlertService.java
│       └── impl/
│           ├── EquipmentServiceImpl.java
│           └── EquipmentAlertServiceImpl.java
│
├── receiver-service/       # 数据接收服务 (:8082)
│   ├── kafka/
│   │   └── MeterMessageConsumer.java     # Kafka消费者
│   ├── mapper/
│   │   ├── EquipmentMapper.java
│   │   ├── ReportDataMapper.java
│   │   ├── DataSummaryEachPieceMapper.java
│   │   └── EquipmentAlertMapper.java
│   ├── model/
│   │   ├── Equipment.java
│   │   ├── ReportData.java
│   │   ├── DataSummaryEachPiece.java
│   │   └── EquipmentAlert.java
│   └── service/
│       ├── DataReceiverService.java
│       ├── StatisticalTriggerService.java
│       └── impl/
│           ├── DataReceiverServiceImpl.java
│           └── StatisticalTriggerServiceImpl.java
│
└── statistics-service/     # 统计服务 (:8083)
    ├── controller/
    │   ├── StatisticalController.java    # 统计API
    │   └── DashboardController.java      # 仪表盘API
    ├── mapper/
    │   ├── DataSummaryEachPieceMapper.java
    │   ├── DataSummaryEachDayMapper.java
    │   ├── DataSummaryEachMonthMapper.java
    │   ├── EquipmentMapper.java
    │   └── EquipmentAlertMapper.java
    ├── model/
    │   ├── SummaryData.java
    │   ├── DashboardVO.java
    │   ├── DataSummaryEachPiece.java
    │   ├── DataSummaryEachDay.java
    │   ├── DataSummaryEachMonth.java
    │   ├── Equipment.java
    │   └── EquipmentAlert.java
    └── service/
        ├── StatisticalService.java
        ├── DashboardService.java
        ├── ScheduledTaskService.java
        └── impl/
            ├── StatisticalServiceImpl.java
            ├── DashboardServiceImpl.java
            └── ScheduledTaskServiceImpl.java
```

### 3.3 核心Entity/Model类

#### Equipment（设备实体）

```java
@Data
public class Equipment implements Serializable {
    private Long id;
    private String equipmentName;       // 设备名称
    private String deviceSn;            // 设备SN号（唯一标识）
    private String deviceCode;          // 设备编码
    private String deviceType;          // 设备类型: single_phase / three_phase
    private String location;            // 安装位置
    private LocalDate installationDate; // 安装日期
    private String status;              // 状态: online / offline / maintenance
    private String ratedVoltage;        // 额定电压
    private String ratedCurrent;        // 额定电流
    private String manufacturer;        // 制造商
    private Double initNumber;          // 初始读数 (kWh)
    private LocalDateTime lastReportTime;  // 最后上报时间
    private Double lastReportData;         // 最后上报读数
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}
```

#### EquipmentAlert（告警实体）

```java
@Data
public class EquipmentAlert implements Serializable {
    private Long id;
    private Long equipmentId;
    private String equipmentName;    // 关联查询自equipment表
    private String alertType;        // 告警类型: over_threshold / offline / data_abnormal
    private String alertLevel;       // 告警级别: info / warning / critical
    private Double thresholdValue;   // 阈值
    private Double actualValue;      // 实际值
    private String message;          // 告警描述
    private String status;           // 状态: active / acknowledged / resolved
    private LocalDateTime createdAt;
    private LocalDateTime resolvedAt;
}
```

#### ReportData（上报数据实体）

```java
@Data
public class ReportData implements Serializable {
    private Long id;
    private Long equipmentId;
    private String deviceSn;
    private Double reportData;           // 电表读数 (kWh)
    private LocalDateTime reportDate;    // 上报时间
    private String dataQuality;          // 数据质量: normal / abnormal
    private LocalDateTime createdAt;
}
```

#### DashboardVO（仪表盘视图对象）

```java
@Data
public class DashboardVO {
    private int totalEquipment;
    private int onlineCount;
    private int offlineCount;
    private int maintenanceCount;
    private double todayTotalUsage;
    private int activeAlertCount;
    private List<SummaryData> todayUsageByEquipment;
    private List<AlertVO> recentAlerts;
    
    @Data
    public static class AlertVO {
        private Integer id;
        private Integer equipmentId;
        private String equipmentName;
        private String alertType;
        private String alertLevel;
        private String message;
        private String status;
        private String createdAt;
    }
}
```

### 3.4 核心API端点

#### 设备管理 (`/equipment`)

| 方法 | 路径 | 说明 | 查询参数 |
|------|------|------|----------|
| GET | `/equipment` | 分页设备列表 | `keyword`, `status`, `page`, `size` |
| GET | `/equipment/{id}` | 按ID查询设备 | - |
| GET | `/equipment/sn/{deviceSn}` | 按SN号查询设备 | - |
| GET | `/equipment/all` | 获取所有设备 | - |
| POST | `/equipment` | 新增设备 | Body: EquipmentCreateRequest |
| PUT | `/equipment/{id}` | 更新设备 | Body: EquipmentUpdateRequest |
| DELETE | `/equipment/{id}` | 删除设备 | - |

#### 告警管理 (`/alert`)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/alert` | 分页告警列表 |
| GET | `/alert/active` | 获取活跃告警列表 |
| GET | `/alert/count` | 获取活跃告警数量 |
| PUT | `/alert/{id}/acknowledge` | 确认告警 |
| PUT | `/alert/{id}/resolve` | 解决告警 |

#### 统计服务 (`/statistical`)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/statistical/today` | 今日统计 |
| GET | `/statistical/month` | 本月统计 |
| GET | `/statistical/year` | 本年统计 |
| GET | `/statistical/day?startDate=&endDate=` | 指定日期范围统计 |
| GET | `/statistical/export/day` | 导出日统计CSV |
| GET | `/statistical/export/month` | 导出月统计Excel |
| POST | `/statistical/trigger` | 手动触发统计 |

#### Dashboard (`/dashboard`)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/dashboard` | 获取仪表盘概览数据 |

### 3.5 核心业务逻辑

#### DataReceiverServiceImpl 数据处理流程

```java
@Transactional
public void processMeterMessage(String deviceSn, String timestamp, Double meterReading) {
    // 1. 按SN查找设备
    Equipment equipment = equipmentMapper.findByDeviceSn(deviceSn);
    if (equipment == null) {
        log.warn("设备不存在: {}", deviceSn);
        return;
    }
    
    // 2. 解析时间戳（失败回退到当前时间）
    LocalDateTime reportTime;
    try {
        reportTime = LocalDateTime.parse(timestamp, DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
    } catch (Exception e) {
        reportTime = LocalDateTime.now();
    }
    
    // 3. 计算用量差值
    Double lastReportData = equipment.getLastReportData();
    Double usage;
    if (lastReportData == null) {
        // 首次上报: 用量 = meterReading - initNumber
        usage = meterReading - equipment.getInitNumber();
    } else {
        // 后续上报: 用量 = 当前读数 - 上次读数
        usage = meterReading - lastReportData;
    }
    
    // 4. 异常检测
    if (usage < 0) {
        // 负差值 → data_abnormal告警 (critical级别)
        createAlert(equipment.getId(), "data_abnormal", "critical", 
                    lastReportData, meterReading, "读数异常减少");
    } else if (usage > 1000) {
        // 差值 > 1000kWh → over_threshold告警 (warning级别)
        createAlert(equipment.getId(), "over_threshold", "warning",
                    1000.0, usage, "单次用电量超过阈值");
    }
    
    // 5. 保存report_data和data_summary_each_piece
    saveReportData(equipment.getId(), deviceSn, meterReading, reportTime);
    saveUsageData(equipment.getId(), usage, reportTime);
    
    // 6. 更新设备最后上报信息
    updateEquipmentLastReport(equipment.getId(), reportTime, meterReading);
    
    // 7. 触发统计服务日聚合
    statisticalTriggerService.triggerTodayStatistical();
}
```

#### 定时任务

| 任务 | Cron表达式 | 说明 |
|------|-----------|------|
| `statisticalDay()` | `0 0 0 1/1 * ?` | 每日午夜执行，聚合前一日piece数据为日统计 |
| `statisticalMonth()` | `0 0 0 1 * ?` | 每月1日午夜执行，聚合日数据为月统计 |
| `triggerTodayStatistical()` | 手动触发 | 删除当日已有统计后重新聚合（幂等） |

### 3.6 安全认证流程

```
1. 用户登录 → Chat-Boot验证(sys_user表, bcrypt) → 返回JWT
2. 前端存储JWT到localStorage
3. 请求携带Authorization: Bearer <token>
4. Gateway验证JWT → 提取用户名 → 注入X-User-Name + X-Gateway-Token头
5. 下游服务验证Gateway Token → 设置Spring Security上下文
```

**关键配置：**
- `JWT_SECRET`：Gateway和Chat-Boot必须使用相同的JWT签名密钥
- `GATEWAY_SECURITY_TOKEN`：服务间认证令牌，防止绕过Gateway直接访问下游服务

### 3.7 统一设计模式

1. **统一响应格式**: `ApiResponse<T>` → `{code, message, data}`
2. **分页封装**: `PageResult<T>` → `{items, total, page, size}`
3. **全局异常处理**: `@RestControllerAdvice` 统一捕获异常
4. **DTO/VO分离**: 请求DTO使用Jakarta验证注解，响应VO裁剪敏感字段
5. **Gateway安全头注入**: JWT解析后注入 `X-User-Name` + `X-Gateway-Token`
6. **幂等统计**: 先删后插，保证重复触发结果一致
7. **手动Kafka ACK**: `enable-auto-commit: false`, `ack-mode: manual_immediate`，至少一次语义
8. **SSE流式响应**: Vercel AI SDK Data Stream Protocol

## 四、前端Vue 3深度分析

### 4.1 技术栈

| 组件 | 技术 | 版本 | 说明 |
|------|------|------|------|
| **框架** | Vue | 3.4+ | 渐进式JavaScript框架 |
| **UI库** | Vuetify | 3.5+ | Material Design组件库 |
| **构建工具** | Vite | 5.2+ | 下一代前端构建工具 |
| **路由** | Vue Router | 4.3+ | 单页应用路由 |
| **状态管理** | Pinia | 3.0+ | Vue 3官方状态管理 |
| **图表** | ECharts | 5.5+ | 数据可视化 |
| **HTTP客户端** | Axios | 1.x | Promise based HTTP client |
| **语言** | TypeScript | 5.x | 类型安全 |

### 4.2 页面路由

```
/login          → 登录页
/dashboard      → 仪表盘 (默认首页)
/               → 设备管理
/statistics     → 统计分析
/equipment/:id  → 设备详情
/alerts         → 告警管理
/documents      → 文档管理
/prompts        → 提示词管理
```

### 4.3 Pinia状态管理（6个Store）

| Store | 职责 | 关键功能 |
|-------|------|----------|
| `auth` | 认证状态 | 登录/注册/登出, localStorage持久化 |
| `chat` | 聊天管理 | 多会话管理, Vercel AI SDK协议支持 |
| `equipment` | 设备管理 | 设备CRUD + 分页获取 |
| `dashboard` | 仪表盘 | 仪表盘数据获取 |
| `alert` | 告警管理 | 告警列表、确认/解决告警 |
| `notification` | 通知系统 | 全局通知 |

### 4.4 ChatBot实现

- 使用**Vercel AI SDK Data Stream Protocol**进行SSE流式通信
- 支持文本增量和工具调用卡片实时更新
- 多会话管理，localStorage持久化
- 支持多模态（图片理解/OCR）

## 五、Chat-Boot Python深度分析

### 5.1 技术栈

| 组件 | 技术 | 版本 | 用途 |
|------|------|------|------|
| **Web框架** | FastAPI | 0.136+ | Python异步Web框架 |
| **LLM框架** | LangChain | 1.2+ | LLM应用开发框架 |
| **Agent编排** | LangGraph | 1.1+ | Agent状态图编排 |
| **向量库** | langchain-postgres | 0.0.12+ | PGVector集成 |
| **数据验证** | Pydantic | 2.0+ | 数据模型验证 |
| **HTTP客户端** | httpx | - | 异步HTTP请求 |
| **数据库驱动** | psycopg2-binary | - | PostgreSQL驱动 |
| **LLM** | Zhipu AI SDK | - | 智谱AI (默认) |
| | OpenAI | - | OpenAI兼容接口 |
| | Ollama | - | 本地模型 |
| **PDF解析** | pypdf | 4.0+ | PDF文档解析 |
| **Word解析** | python-docx | 1.0+ | Word文档解析 |
| **Excel解析** | openpyxl / xlrd | 3.1+ / 2.0+ | Excel文档解析 |
| **网络搜索** | duckduckgo-search | - | 联网搜索 |

### 5.2 模块结构

```
chat-boot/src/chat_boot/
├── __init__.py
├── app.py                      # FastAPI应用入口
├── agent/
│   ├── agent.py                # Agent核心逻辑 (LangGraph)
│   ├── llm.py                  # LLM工厂 (多模型支持)
│   ├── session.py              # 会话管理 (Redis持久化)
│   ├── common.py               # 通用工具函数
│   └── tools/
│       └── agent_tools.py      # 14个Agent工具定义
├── api/
│   ├── middleware/
│   │   └── jwt.py              # JWT认证中间件
│   └── routers/
│       ├── chat.py             # 聊天API (SSE流式)
│       ├── sessions.py         # 会话管理API
│       ├── documents.py        # 文档上传API
│       ├── document.py         # 文档管理API
│       ├── prompts.py          # Prompt版本管理API
│       └── auth.py             # 认证API
├── core/
│   ├── config.py               # 配置管理 (Pydantic Settings)
│   ├── security.py             # 安全防护 (XSS/SQL注入/脱敏)
│   ├── logging.py              # 日志配置
│   ├── monitoring.py           # 性能监控
│   ├── enhanced_monitoring.py  # 增强监控
│   └── status.py               # 系统状态
├── models/
│   └── schemas.py              # Pydantic模型定义
├── rag/
│   ├── standard_rag.py         # 标准RAG链
│   ├── document_pipeline.py    # 文档处理管道
│   ├── embeddings.py           # 嵌入模型管理
│   ├── vectorstore.py          # 向量存储 (PGVector/FAISS)
│   ├── retriever.py            # 混合检索器 (BM25+向量+RRF)
│   ├── indexer.py              # 文档索引器
│   ├── index_manager.py        # 异步索引管理器
│   ├── query_rewriter.py       # 查询改写 (扩展/分解/HyDE)
│   ├── reranker.py             # 重排序 (Cross-Encoder)
│   ├── evaluation.py           # RAG评估
│   ├── cache.py                # 语义缓存
│   ├── hallucination.py        # 幻觉检测
│   ├── multimodal.py           # 多模态处理
│   └── prompt_manager.py       # Prompt版本管理
└── services/
    ├── document_service.py     # 文档处理服务
    ├── equipment_service.py    # 设备服务客户端
    ├── statistical_service.py  # 统计服务客户端
    ├── alert_service.py        # 告警服务客户端
    └── dashboard_service.py    # 仪表盘服务客户端
```

### 5.3 Agent工具（14个）

| 工具 | 功能 | 调用服务 |
|------|------|----------|
| `count_equipment` | 统计设备总数 | Equipment Service |
| `get_all_equipment` | 列出所有设备 | Equipment Service |
| `add_equipment` | 新增设备 | Equipment Service |
| `update_equipment` | 更新设备初始值 | Equipment Service |
| `delete_equipment` | 删除设备 | Equipment Service |
| `get_equipment_by_name` | 按名称查询设备 | Equipment Service |
| `get_today_statistical` | 今日用量统计 | Statistics Service |
| `get_month_statistical` | 月度用量统计 | Statistics Service |
| `get_year_statistical` | 年度用量统计 | Statistics Service |
| `get_active_alerts` | 获取活跃告警 | Equipment Service |
| `get_equipment_alerts` | 设备专属告警 | Equipment Service |
| `get_dashboard_summary` | 系统概览 | Statistics Service |
| `document_qa` | RAG文档问答 | 内部RAG管道 |
| `web_search` | 网络搜索 | duckduckgo-search |

### 5.4 Chat-Boot API端点

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/auth/login` | 用户登录 |
| POST | `/auth/register` | 用户注册 |
| POST | `/chat-api/api/chat/stream` | SSE流式对话 |
| GET | `/chat-api/api/sessions` | 获取会话列表 |
| POST | `/chat-api/api/sessions` | 创建新会话 |
| GET | `/chat-api/api/sessions/{id}` | 获取会话详情 |
| GET | `/chat-api/api/sessions/{id}/messages` | 获取会话消息 |
| DELETE | `/chat-api/api/sessions/{id}` | 删除会话 |
| GET | `/chat-api/api/documents` | 获取文档列表 |
| POST | `/chat-api/api/documents/upload` | 上传文档 |
| POST | `/chat-api/api/documents/{id}/process` | 处理文档（切分+向量化） |
| POST | `/chat-api/api/documents/upload-and-process` | 上传并处理文档 |
| DELETE | `/chat-api/api/documents/{id}` | 删除文档 |
| GET | `/chat-api/api/prompts/` | 获取Prompt模板列表 |
| GET | `/chat-api/api/prompts/{name}` | 获取Prompt内容 |
| POST | `/chat-api/api/prompts/` | 创建Prompt |
| PUT | `/chat-api/api/prompts/{name}` | 更新Prompt |
| DELETE | `/chat-api/api/prompts/{name}` | 删除Prompt |
| GET | `/chat-api/api/prompts/{name}/versions` | 获取版本列表 |
| POST | `/chat-api/api/prompts/{name}/versions` | 添加版本 |
| PUT | `/chat-api/api/prompts/{name}/versions/activate` | 激活版本 |
| GET | `/health` | 健康检查 |

### 5.5 RAG管道架构

```
用户查询
    │
    ▼
┌─────────────┐
│ QueryRewriter│ ← 查询扩展/分解/HyDE
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────────┐
│        Hybrid Retriever             │
│  ┌──────────┐  ┌──────────────────┐ │
│  │ BM25关键词│  │ 向量语义检索     │ │
│  └─────┬────┘  └───────┬──────────┘ │
│        │               │            │
│        └───────┬───────┘            │
│                ▼                    │
│         RRF融合排序                  │
└─────────────────┬───────────────────┘
                  │
                  ▼
           ┌─────────────┐
           │  Reranker    │ ← BAAI/bge-reranker-base交叉编码器
           └──────┬──────┘
                  │
                  ▼
           ┌─────────────┐
           │Semantic Cache│ ← 相似度阈值0.95
           └──────┬──────┘
                  │
                  ▼
           ┌─────────────┐
           │    LLM       │ ← 生成回答
           └──────┬──────┘
                  │
                  ▼
           ┌──────────────────┐
           │Hallucination     │ ← 基于LLM的事实性检测
           │Detector          │
           └──────────────────┘
```

**RAG核心组件：**

| 组件 | 技术 | 说明 |
|------|------|------|
| Embeddings | Zhipu embedding-3 | 2048维向量 |
| VectorStore | PGVector (langchain-postgres) | PostgreSQL向量扩展 |
| Retriever | 混合检索 | BM25关键词 + 向量语义 + RRF融合 |
| QueryRewriter | LLM驱动 | 查询扩展/分解/HyDE |
| Reranker | BAAI/bge-reranker-base | 交叉编码器重排 |
| Cache | 语义缓存 | 相似度阈值0.95 |
| HallucinationDetector | LLM驱动 | 事实性检测 |

### 5.6 会话管理架构

```python
@dataclass
class SessionState:
    session_id: str
    history: List[Dict]         # 最大50条消息
    pending_action: Optional[str]
    created_at: datetime
    last_active: datetime
    metadata: Dict
```

| 存储方式 | 实现 | 用途 |
|----------|------|------|
| `MemorySessionStore` | 内存dict存储 | 开发环境 |
| `RedisSessionStore` | Redis存储，TTL 3600s | 生产环境 |

- `SessionManager`: 工厂模式，根据 `SESSION_STORAGE` 配置自动选择存储
- Session ID验证: 字母数字 + 下划线/连字符，最大100字符
- 后台每5分钟清理过期会话

### 5.7 系统提示词结构（184行）

1. 核心原则: 基于事实、诚实回答、中文响应
2. 训练数据截止日期感知 (触发web_search获取最新信息)
3. 工具Schema描述
4. 代指消解指令 (pronoun resolution)
5. 决策流程: 意图分析 → 工具选择 → 参数检查 → 结果整合
6. 文档QA指南 (反幻觉策略)
7. 数据展示格式模板

## 六、数据库设计

### 6.1 数据库表结构（8张核心表）

```sql
-- PostgreSQL 数据库初始化

-- 启用 pgvector 扩展（用于向量存储）
CREATE EXTENSION IF NOT EXISTS vector;

-- 1. 设备表
CREATE TABLE equipment (
    id BIGSERIAL PRIMARY KEY,
    device_sn VARCHAR(50) UNIQUE NOT NULL,      -- 设备SN号(唯一)
    equipment_name VARCHAR(100),                 -- 设备名称
    device_code VARCHAR(50),                     -- 设备编码
    device_type VARCHAR(20),                     -- 设备类型(single_phase/three_phase)
    location VARCHAR(200),                       -- 安装位置
    installation_date DATE,                      -- 安装日期
    status VARCHAR(20) DEFAULT 'online',         -- 状态(online/offline/maintenance)
    rated_voltage VARCHAR(20),                   -- 额定电压
    rated_current VARCHAR(20),                   -- 额定电流
    manufacturer VARCHAR(100),                   -- 制造商
    init_number DOUBLE PRECISION DEFAULT 0,      -- 初始读数(kWh)
    last_report_time TIMESTAMP,                  -- 最后上报时间
    last_report_data DOUBLE PRECISION,           -- 最后上报读数
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 2. 原始上报数据表
CREATE TABLE report_data (
    id BIGSERIAL PRIMARY KEY,
    equipment_id BIGINT NOT NULL,                -- 设备ID
    device_sn VARCHAR(50),                       -- 设备SN号
    report_data DOUBLE PRECISION NOT NULL,       -- 上报读数(kWh)
    report_date TIMESTAMP NOT NULL,              -- 上报时间
    data_quality VARCHAR(20) DEFAULT 'normal',   -- 数据质量(normal/abnormal)
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 3. 逐条用电量表（每次上报的差值）
CREATE TABLE data_summary_each_piece (
    id BIGSERIAL PRIMARY KEY,
    equipment_id BIGINT NOT NULL,                -- 设备ID
    dosage DOUBLE PRECISION NOT NULL,            -- 用电量(kWh)
    date TIMESTAMP NOT NULL,                     -- 数据时间
    report_date TIMESTAMP NOT NULL               -- 上报时间
);

-- 4. 日统计表
CREATE TABLE data_summary_each_day (
    id BIGSERIAL PRIMARY KEY,
    stat_date DATE NOT NULL,                     -- 统计日期
    equipment_id BIGINT NOT NULL,                -- 设备ID
    dosage_day DOUBLE PRECISION NOT NULL,        -- 日用电量(kWh)
    date TIMESTAMP                               -- 记录时间
);

-- 5. 月统计表
CREATE TABLE data_summary_each_month (
    id BIGSERIAL PRIMARY KEY,
    stat_month DATE NOT NULL,                    -- 统计月份
    equipment_id BIGINT NOT NULL,                -- 设备ID
    dosage_month DOUBLE PRECISION NOT NULL,      -- 月用电量(kWh)
    date TIMESTAMP                               -- 记录时间
);

-- 6. 告警表
CREATE TABLE equipment_alert (
    id BIGSERIAL PRIMARY KEY,
    equipment_id BIGINT NOT NULL,                -- 设备ID
    alert_type VARCHAR(50) NOT NULL,             -- 告警类型(over_threshold/offline/data_abnormal)
    alert_level VARCHAR(20) NOT NULL,            -- 告警级别(info/warning/critical)
    threshold_value DOUBLE PRECISION,            -- 阈值
    actual_value DOUBLE PRECISION,               -- 实际值
    message VARCHAR(500),                        -- 告警描述
    status VARCHAR(20) DEFAULT 'active',         -- 状态(active/acknowledged/resolved)
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    resolved_at TIMESTAMP                        -- 解决时间
);

-- 7. 系统用户表
CREATE TABLE sys_user (
    id BIGSERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,        -- 用户名
    password VARCHAR(100) NOT NULL,              -- 密码(BCrypt加密)
    display_name VARCHAR(50),                    -- 显示名称
    role VARCHAR(20) DEFAULT 'user',             -- 角色
    status VARCHAR(20) DEFAULT 'active',         -- 状态
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 8. Kafka消息日志表
CREATE TABLE kafka_message_log (
    id BIGSERIAL PRIMARY KEY,
    topic VARCHAR(100),                          -- 主题
    partition_id INTEGER,                        -- 分区
    offset_value BIGINT,                         -- 偏移量
    device_sn VARCHAR(50),                       -- 设备SN号
    message_content TEXT,                        -- 消息内容
    process_status VARCHAR(20),                  -- 处理状态
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 向量存储表 (LangChain PGVector)
CREATE TABLE langchain_pg_collection (
    name VARCHAR,
    cmetadata JSONB,
    uuid UUID NOT NULL DEFAULT gen_random_uuid() PRIMARY KEY
);

CREATE TABLE langchain_pg_embedding (
    collection_id UUID,
    embedding vector(2048),                      -- 2048维向量
    document VARCHAR,
    cmetadata JSONB,
    custom_id VARCHAR,
    id VARCHAR NOT NULL PRIMARY KEY,
    CONSTRAINT langchain_pg_embedding_collection_id_fkey
        FOREIGN KEY (collection_id)
        REFERENCES langchain_pg_collection(uuid)
        ON DELETE CASCADE
);
```

### 6.2 初始数据

```sql
-- 管理员用户(密码: admin123)
INSERT INTO sys_user (username, password, display_name, role) VALUES
('admin', '$2a$10$N.zmdr9k7uOCQb376NoUnuTJ8iAt6Z5EHsM8lE9lBOsl7iAt6Z5EH', '管理员', 'admin');

-- 示例设备
INSERT INTO equipment (device_sn, equipment_name, device_code, device_type, location, init_number) VALUES
('SN00000001', '电表001', 'EM001', 'single_phase', '1号楼1单元', 1000),
('SN00000002', '电表002', 'EM002', 'single_phase', '1号楼2单元', 2000),
('SN00000003', '电表003', 'EM003', 'three_phase', '2号楼1单元', 1500);
```

### 6.3 数据库关系图

```
equipment (1) ──── (N) report_data
    │                     │
    │                     └── device_sn (冗余)
    │
    ├── (N) data_summary_each_piece
    ├── (N) data_summary_each_day
    ├── (N) data_summary_each_month
    └── (N) equipment_alert

sys_user (独立表，认证用)
kafka_message_log (独立表，消息日志)
langchain_pg_collection (1) ──── (N) langchain_pg_embedding
```

## 七、Kafka消息处理

### 7.1 电表报文格式

发送到 `meter-data` 主题的JSON报文：

```json
{
  "deviceSn": "SN00000001",
  "timestamp": "2026-05-10 14:00:00",
  "meterReading": 1600.00
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| deviceSn | String | ✅ | 设备SN号，必须在equipment表中存在 |
| timestamp | String | ✅ | 上报时间，格式：yyyy-MM-dd HH:mm:ss |
| meterReading | Double | ✅ | 电表读数（累计值，单位kWh） |

### 7.2 Kafka消费者配置

```yaml
spring:
  kafka:
    consumer:
      group-id: receiver-group
      auto-offset-reset: earliest
      enable-auto-commit: false        # 手动ACK
      ack-mode: manual_immediate
    topic:
      name: meter-data
```

### 7.3 用电量计算逻辑

```
本次用电量 = 本次上报读数 - 上次上报读数
```

**示例：**
- 设备初始读数：1000.0 kWh
- 第一次上报：1600.0 kWh → 用电量 = 1600 - 1000 = 600 kWh
- 第二次上报：1800.0 kWh → 用电量 = 1800 - 1600 = 200 kWh

### 7.4 异常处理

| 场景 | 处理方式 | 告警类型 | 告警级别 |
|------|----------|----------|----------|
| 设备不存在 | 忽略消息，记录警告日志 | - | - |
| 时间戳格式错误 | 使用当前时间替代 | - | - |
| 读数小于上次 | 标记为异常数据，创建告警 | data_abnormal | critical |
| 单次用电量 > 1000 kWh | 创建超阈值告警 | over_threshold | warning |

### 7.5 发送测试消息

```bash
echo '{"deviceSn":"SN00000001","timestamp":"2026-05-10 14:00:00","meterReading":1600.00}' | docker exec -i data-summary-kafka kafka-console-producer --bootstrap-server localhost:9092 --topic meter-data
```

## 八、前端技术详解

### 8.1 支持的文档格式

| 格式 | 后缀 | 解析库 | 说明 |
|------|------|--------|------|
| PDF | .pdf | pypdf | 按页解析 |
| Word | .docx/.doc | python-docx | 按段落解析 |
| Excel | .xlsx | openpyxl | 按工作表解析，保留表头 |
| Excel | .xls | xlrd | 旧版格式，按工作表解析 |
| 文本 | .txt | 内置 | 直接读取 |
| Markdown | .md/.markdown | 内置 | 直接读取 |

### 8.2 数据导出功能

- **CSV导出** (日统计): OpenCSV，UTF-8 BOM编码（支持中文字符）
- **Excel导出** (月统计): Apache POI XSSFWorkbook，带样式表头

### 8.3 AI助手功能特性

- **设备查询**: 查询设备信息、初始值、状态
- **用电统计**: 查询今日/本月/今年用电量
- **告警查询**: 查看活跃告警、设备告警
- **系统概览**: 查看系统整体运行状态
- **文档问答**: 基于RAG的技术文档问答
- **上下文记忆**: 支持多轮对话，理解上下文
- **知识库管理**: 支持上传PDF/Word/Excel/TXT/MD文档，自动切分向量化
- **多会话管理**: 支持创建多个独立会话，会话历史本地持久化
- **会话持久化**: Redis存储，重启不丢失会话数据
- **Prompt版本管理**: 支持Prompt配置化管理、版本控制、热更新
- **多模态支持**: 图片理解/OCR

### 8.4 测试问题示例

```
用户：系统有多少台设备？
AI：当前系统共有3台设备。

用户：电表001的详细信息？
AI：电表001的详细信息如下：
    - 设备编号：SN00000001
    - 设备类型：单相
    - 安装位置：1号楼1单元
    - 设备状态：在线
    - 初始读数：1000.0 kWh

用户：它的初始值是多少？  <-- 理解上下文（代指消解）
AI：电表001的初始读数为1000.0 kWh。
```

## 九、基础设施与DevOps

### 9.1 Docker Compose服务（15个）

```yaml
# docker-compose.yml 核心服务
services:
  postgres:      # pgvector/pgvector:pg16
  redis:         # redis:7-alpine
  zookeeper:     # confluentinc/cp-zookeeper:7.6.0
  kafka:         # confluentinc/cp-kafka:7.6.0
  gateway:       # Spring Cloud Gateway
  equipment:     # Equipment Service
  receiver:      # Receiver Service
  statistics:    # Statistics Service
  chat-boot:     # FastAPI + LangChain
  frontend:      # Vue 3 + Nginx
  prometheus:    # prom/prometheus
  grafana:       # grafana/grafana
  jaeger:        # jaegertracing/all-in-one
  cadvisor:      # gcr.io/cadvisor/cadvisor
  promtail:      # grafana/promtail
```

### 9.2 监控体系

| 组件 | 端口 | 用途 |
|------|------|------|
| **Prometheus** | 9090 | 采集Spring Boot Actuator指标 |
| **Grafana** | 3001 | 3个数据源 (Prometheus, Loki, Jaeger) |
| **Jaeger** | 16686 | 分布式链路追踪 (OTLP) |
| **Promtail** | - | Docker容器日志收集 → Loki |
| **cAdvisor** | - | 容器资源监控 |

### 9.3 Kubernetes部署

- 14个YAML文件: Namespace, ConfigMap, Secrets, Deployments, Services, Ingress
- `deploy.ps1` 自动化部署脚本
- 详细部署文档: `KUBERNETES_DEPLOYMENT.md`

## 十、环境变量配置

### 10.1 环境变量说明

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `DB_USER` | postgres | PostgreSQL用户名 |
| `DB_PASSWORD` | postgres123 | PostgreSQL密码 |
| `DB_NAME` | data_summary | 数据库名 |
| `REDIS_PASSWORD` | redis123 | Redis密码 |
| `JWT_SECRET` | - | JWT密钥（Gateway和Chat-Boot共享，生产必填） |
| `GATEWAY_SECURITY_TOKEN` | dev-gateway-token-2024 | Gateway安全令牌（服务间认证） |
| `LLM_TYPE` | zhipu | LLM类型: zhipu / openai / ollama / lmstudio |
| `ZHIPU_API_KEY` | - | 智谱AI API密钥 |
| `ZHIPU_MODEL` | glm-4-flash | 智谱AI模型名 |
| `CORS_ORIGINS` | ["http://localhost:3000",...] | 跨域来源 |
| `LANGSMITH_TRACING` | true | LangSmith追踪开关 |
| `LANGSMITH_PROJECT` | chat-boot | LangSmith项目名 |
| `LANGSMITH_API_KEY` | - | LangSmith API密钥 |
| `LOG_LEVEL` | INFO | 日志级别 |

### 10.2 .env示例

```bash
# PostgreSQL 数据库配置
DB_USER=postgres
DB_PASSWORD=postgres123
DB_NAME=data_summary

# Redis配置
REDIS_PASSWORD=redis123

# JWT密钥（生产环境必须修改！）
JWT_SECRET=your-secure-secret-key-at-least-32-chars

# AI模型配置
LLM_TYPE=zhipu
ZHIPU_API_KEY=你的智谱AI_API_Key
ZHIPU_MODEL=glm-4-flash

# CORS跨域配置
CORS_ORIGINS=["http://localhost:3000","http://localhost:3001","http://localhost:5173"]

# LangSmith可观测性配置
LANGSMITH_TRACING=true
LANGSMITH_PROJECT=chat-boot
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
```

## 十一、快速开始

### 11.1 前置条件

| 软件 | 版本要求 | 说明 |
|------|----------|------|
| Docker | 25.0+ | 容器运行环境 |
| Docker Compose | v2.0+ | 容器编排工具 |
| JDK | 21+ | Java开发环境（可选，本地开发用） |
| Maven | 3.9+ | Java构建工具（可选，本地开发用） |
| Node.js | 18+ | 前端运行环境（可选，本地开发用） |

### 11.2 Docker Compose部署（推荐）

```bash
# 1. 克隆项目
git clone <repository-url>
cd data-summary

# 2. 配置环境变量
cp .env.example .env
vim .env

# 3. 启动所有服务
docker compose up -d

# 4. 访问系统
# 前端: http://localhost:3000
# API网关: http://localhost:8080
# Grafana: http://localhost:3001 (admin/admin)
# Jaeger: http://localhost:16686
```

### 11.3 本地开发环境

```bash
# 1. 启动基础设施
docker compose up -d postgres redis kafka zookeeper

# 2. 后端开发
cd back-end
cd common-module && mvn clean install -DskipTests && cd ..
cd equipment-service && mvn spring-boot:run

# 3. 前端开发
cd frontend
npm install
npm run dev

# 4. Chat-Boot开发
cd chat-boot
pip install -r requirements.txt
PYTHONPATH=src python -m chat_boot.app
```

## 十二、代码修改与重新部署

### 12.1 修改代码后如何在Docker中生效

| 修改类型 | 修改内容 | 执行命令 |
|----------|----------|----------|
| Python代码 | chat-boot/*.py | `docker compose up -d --build chat-boot` |
| 前端代码 | frontend/src/*.vue | `cd frontend && npm run build && cd .. && docker compose up -d --build frontend` |
| Java代码 | back-end/*.java | `cd back-end && mvn clean package -DskipTests && cd .. && docker compose up -d --build <服务名>` |
| 配置文件 | .env, docker-compose.yml | `docker compose up -d` |
| 所有服务 | 任意修改 | `docker compose up -d --build` |

### 12.2 常用命令速查

| 场景 | 命令 |
|------|------|
| 修改chat-boot代码 | `docker compose up -d --build chat-boot` |
| 修改frontend代码 | `cd frontend && npm run build && cd .. && docker compose up -d --build frontend` |
| 修改Java代码 | `cd back-end && mvn clean package -DskipTests && cd .. && docker compose up -d --build <服务名>` |
| 修改配置文件 | `docker compose up -d` |
| 查看日志 | `docker compose logs -f <服务名>` |
| 进入容器 | `docker compose exec <服务名> bash` |
| 重启单个服务 | `docker compose restart <服务名>` |
| 停止所有服务 | `docker compose down` |

### 12.3 Docker Compose常用命令

```bash
# 启动所有服务
docker compose up -d

# 停止所有服务
docker compose down

# 查看服务状态
docker compose ps

# 查看服务日志
docker compose logs -f [service-name]

# 重新构建并启动
docker compose up -d --build [service-name]

# 进入容器
docker exec -it data-summary-[service-name] bash
```

### 12.4 数据库操作

```bash
# 连接PostgreSQL
docker exec -it data-summary-postgres psql -U postgres -d data_summary

# 查看设备数据
docker exec data-summary-postgres psql -U postgres -d data_summary -c "SELECT * FROM equipment;"

# 查看用电量统计
docker exec data-summary-postgres psql -U postgres -d data_summary -c "SELECT * FROM data_summary_each_piece;"
```

### 12.5 Kafka操作

```bash
# 发送测试消息
echo '{"deviceSn":"SN00000001","timestamp":"2026-05-10 14:00:00","meterReading":1600.00}' | docker exec -i data-summary-kafka kafka-console-producer --bootstrap-server localhost:9092 --topic meter-data

# 消费消息
docker exec -it data-summary-kafka kafka-console-consumer --bootstrap-server localhost:9092 --topic meter-data --from-beginning
```

## 十三、故障排查

### 13.1 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| Docker build失败（Java服务） | JAR包未构建 | 先执行 `mvn clean package -DskipTests` |
| Chat-boot导入错误 | PYTHONPATH未设置 | 确保 `PYTHONPATH=src` |
| 前端API调用失败（Docker） | Nginx代理规则错误 | 检查 `/api/auth/` 必须在 `/api/` 之前匹配 |
| Kafka连接问题 | 启动顺序 | 确保zookeeper先于kafka启动 |
| Gateway 401/403 | JWT密钥不匹配 | 检查 `JWT_SECRET` 在gateway和chat-boot中一致 |

### 13.2 调试命令

```bash
# 查看服务日志
docker compose logs [service-name]

# 检查端口占用
netstat -ano | findstr :8080

# 检查PostgreSQL状态
docker compose ps postgres

# 测试数据库连接
docker exec -it data-summary-postgres psql -U postgres -c "SELECT 1;"

# 进入容器内部调试
docker compose exec chat-boot bash

# 查看容器内的环境变量
docker compose exec chat-boot env

# 实时查看日志
docker compose logs -f --tail=50 chat-boot

# 查看容器资源使用
docker stats
```

## 十四、版本历史

| 版本 | 日期 | 更新内容 |
|------|------|----------|
| 4.2.0 | 2026-05 | Chat-Boot升级: 多模态支持、语义缓存、幻觉检测、RAG评估 |
| 4.0.0 | 2026-05 | Chat-Boot重构: LangGraph集成、混合检索(BM25+向量+RRF)、Cross-Encoder重排序 |
| 3.0.0 | 2026-05 | 基础架构升级 |
| 2.3.0 | 2026-05 | 添加会话持久化(Redis)、Prompt版本管理 |
| 2.2.0 | 2026-05 | 添加Excel文档支持(.xlsx/.xls)，知识库管理功能 |
| 2.1.0 | 2026-05 | 数据库从MySQL迁移到PostgreSQL，启用PGVector |
| 2.0.0 | 2026-05 | 升级到Spring Boot 3.4.5、Java 21、添加可观测性 |
| 1.0.0 | 2024-01 | 初始版本 |

## 十五、许可证

MIT License