# 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-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 设备数据管理系统 - 微服务架构 (2026版) 一个完整的电表设备数据管理系统，采用2026年主流微服务架构，包含前端、后端微服务、AI聊天功能和完整的可观测性体系。 ## 系统架构 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 用户浏览器 │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ 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 │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ## 技术栈详情 ### 核心框架 | 组件 | 技术 | 版本 | 说明 | |------|------|------|------| | **开发语言** | Java | 21 LTS | 长期支持版本，支持虚拟线程 | | **基础框架** | Spring Boot | 3.4.5 | 2026年主流版本 | | **微服务框架** | Spring Cloud | 2024.0.1 | 微服务全家桶 | | **API网关** | Spring Cloud Gateway | 4.1+ | 响应式网关 | | **ORM框架** | MyBatis | 3.0.4 | SQL映射框架 | ### 前端技术 | 组件 | 技术 | 版本 | 说明 | |------|------|------|------| | **框架** | Vue | 3.4+ | 渐进式JavaScript框架 | | **UI库** | Vuetify | 3.5+ | Material Design组件库 | | **构建工具** | Vite | 5.4+ | 下一代前端构建工具 | | **图表** | ECharts | 5.x | 数据可视化 | | **HTTP客户端** | Axios | 1.x | Promise based HTTP client | ### 基础设施 | 组件 | 技术 | 版本 | 用途 | |------|------|------|------| | **容器** | Docker | 25.x+ | 容器化 | | **编排** | Docker Compose | v2.x+ | 本地开发编排 | | **数据库** | PostgreSQL | 16 | 主数据存储 + 向量存储 | | **缓存** | Redis | 7.x | 分布式缓存 | | **消息队列** | Apache Kafka | 3.8+ | 异步消息、事件驱动 | | **Web服务器** | Nginx | 1.29+ | 反向代理、静态资源 | ### 可观测性 | 组件 | 技术 | 版本 | 用途 | |------|------|------|------| | **指标采集** | Prometheus | 2.50+ | 时序数据存储 | | **可视化** | Grafana | 10.3+ | 监控仪表盘 | | **链路追踪** | Jaeger | 1.54+ | 分布式链路追踪 | | **日志聚合** | Loki | 2.9+ | 日志存储查询 | | **日志收集** | Promtail | 2.9+ | 日志采集代理 | | **容器监控** | cAdvisor | 0.47+ | 容器资源监控 | ### AI服务 | 组件 | 技术 | 版本 | 用途 | |------|------|------|------| | **LLM框架** | LangChain | 1.2+ | LLM应用开发框架 | | **LLM** | 智谱AI | GLM-4 | 大语言模型 | | **向量库** | PGVector | 0.4+ | PostgreSQL向量扩展 | | **Web框架** | FastAPI | 0.136+ | Python异步Web框架 | | **PDF解析** | pypdf | 4.0+ | PDF文档解析 | | **Word解析** | python-docx | 1.0+ | Word文档解析 | | **Excel解析** | openpyxl / xlrd | 3.1+ / 2.0+ | Excel文档解析(.xlsx/.xls) | ## 项目结构 ``` data-summary/ ├── back-end/ # 后端微服务 │ ├── common-module/ # 共享模块 │ │ └── src/main/java/com/example/common/ │ │ ├── dto/ # 数据传输对象 │ │ │ ├── ApiResponse.java # 统一响应格式 │ │ │ ├── PageResult.java # 分页结果 │ │ │ └── SummaryData.java # 统计数据DTO │ │ └── utils/ # 工具类 │ │ └── DateUtil.java # 日期工具 │ │ │ ├── gateway-service/ # API网关服务 (:8080) │ │ └── src/main/ │ │ ├── java/com/example/gateway/ │ │ │ ├── config/ │ │ │ │ └── SecurityConfig.java # 安全配置 │ │ │ ├── security/ │ │ │ │ ├── JwtAuthenticationFilter.java # JWT认证过滤器 │ │ │ │ └── JwtTokenProvider.java # JWT工具 │ │ │ └── GatewayServiceApplication.java # 应用入口 │ │ └── resources/ │ │ └── application.yml # 网关配置 │ │ │ ├── equipment-service/ # 设备服务 (:8081) │ │ └── src/main/ │ │ ├── java/com/example/equipment/ │ │ │ ├── config/ │ │ │ │ └── SecurityConfig.java # 安全配置 │ │ │ ├── controller/ │ │ │ │ ├── EquipmentController.java # 设备API │ │ │ │ └── EquipmentAlertController.java # 告警API │ │ │ ├── mapper/ │ │ │ │ ├── EquipmentMapper.java # 设备Mapper │ │ │ │ └── EquipmentAlertMapper.java # 告警Mapper │ │ │ ├── model/ │ │ │ │ ├── po/ │ │ │ │ │ ├── Equipment.java # 设备实体 │ │ │ │ │ └── EquipmentAlert.java # 告警实体 │ │ │ │ └── dto/ # 请求/响应DTO │ │ │ │ ├── EquipmentCreateRequest.java # 创建设备请求 │ │ │ │ └── EquipmentUpdateRequest.java # 更新设备请求 │ │ │ ├── service/ │ │ │ │ ├── EquipmentService.java # 设备服务接口 │ │ │ │ ├── EquipmentAlertService.java # 告警服务接口 │ │ │ │ └── impl/ │ │ │ │ ├── EquipmentServiceImpl.java # 设备服务实现 │ │ │ │ └── EquipmentAlertServiceImpl.java # 告警服务实现 │ │ │ └── EquipmentServiceApplication.java # 应用入口 │ │ └── resources/ │ │ ├── mapper/ │ │ │ ├── EquipmentMapper.xml # 设备SQL │ │ │ └── EquipmentAlertMapper.xml # 告警SQL │ │ └── application.yml # 服务配置 │ │ │ ├── receiver-service/ # 数据接收服务 (:8082) │ │ └── src/main/ │ │ ├── java/com/example/receiver/ │ │ │ ├── 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 # 统计触发服务实现 │ │ │ └── ReceiverServiceApplication.java # 应用入口 │ │ └── resources/ │ │ ├── mapper/ │ │ │ ├── EquipmentMapper.xml # 设备SQL │ │ │ ├── ReportDataMapper.xml # 上报数据SQL │ │ │ ├── DataSummaryEachPieceMapper.xml # 用电量SQL │ │ │ └── EquipmentAlertMapper.xml # 告警SQL │ │ └── application.yml # 服务配置 │ │ │ ├── statistics-service/ # 统计服务 (:8083) │ │ └── src/main/ │ │ ├── java/com/example/statistics/ │ │ │ ├── config/ │ │ │ │ └── SecurityConfig.java # 安全配置 │ │ │ ├── controller/ │ │ │ │ ├── StatisticalController.java # 统计API │ │ │ │ └── DashboardController.java # 仪表盘API │ │ │ ├── mapper/ │ │ │ │ ├── EquipmentMapper.java # 设备数据访问 │ │ │ │ ├── EquipmentAlertMapper.java # 告警数据访问 │ │ │ │ ├── DataSummaryEachPieceMapper.java # 每次用电量 │ │ │ │ ├── DataSummaryEachDayMapper.java # 日用电量 │ │ │ │ └── DataSummaryEachMonthMapper.java # 月用电量 │ │ │ ├── model/ │ │ │ │ ├── SummaryData.java # 统计数据VO │ │ │ │ ├── DashboardVO.java # 仪表盘数据VO │ │ │ │ ├── DataSummaryEachPiece.java # 每次用电量实体 │ │ │ │ ├── DataSummaryEachDay.java # 日用电量实体 │ │ │ │ ├── DataSummaryEachMonth.java # 月用电量实体 │ │ │ │ ├── Equipment.java # 设备实体 │ │ │ │ └── EquipmentAlert.java # 告警实体 │ │ │ ├── service/ │ │ │ │ ├── StatisticalService.java # 统计服务接口 │ │ │ │ ├── DashboardService.java # 仪表盘服务接口 │ │ │ │ ├── ScheduledTaskService.java # 定时任务服务接口 │ │ │ │ └── impl/ │ │ │ │ ├── StatisticalServiceImpl.java # 统计服务实现 │ │ │ │ ├── DashboardServiceImpl.java # 仪表盘服务实现 │ │ │ │ └── ScheduledTaskServiceImpl.java # 定时任务服务实现 │ │ │ └── StatisticsServiceApplication.java # 应用入口 │ │ └── resources/ │ │ ├── mapper/ │ │ │ ├── DataSummaryEachPieceMapper.xml # 每次用电量SQL │ │ │ ├── DataSummaryEachDayMapper.xml # 日用电量SQL │ │ │ └── DataSummaryEachMonthMapper.xml # 月用电量SQL │ │ └── application.yml # 服务配置 │ │ │ └── doc/ # 文档和SQL脚本 │ └── init-postgres.sql # PostgreSQL初始化脚本 │ ├── frontend/ # 前端项目 │ ├── src/ │ │ ├── api/ # API调用 │ │ │ ├── dashboard.ts # 仪表盘API │ │ │ ├── equipment.ts # 设备API │ │ │ ├── statistics.ts # 统计API │ │ │ ├── alert.ts # 告警API │ │ │ └── chat.ts # 聊天API │ │ ├── views/ # 页面组件 │ │ │ ├── Dashboard.vue # 仪表盘 │ │ │ ├── EquipmentManagement.vue # 设备管理 │ │ │ ├── Statistics.vue # 统计分析 │ │ │ ├── AlertManagement.vue # 告警管理 │ │ │ ├── DocumentManagement.vue # 知识库管理 │ │ │ ├── PromptManagement.vue # Prompt管理 │ │ │ ├── ChatBot.vue # AI聊天（支持多模态） │ │ │ ├── EquipmentDetail.vue # 设备详情 │ │ │ └── Login.vue # 登录页 │ │ ├── stores/ # Pinia状态管理 │ │ │ ├── chat.ts # 聊天状态（多会话、持久化） │ │ │ ├── auth.ts # 认证状态 │ │ │ ├── alert.ts # 告警状态 │ │ │ ├── dashboard.ts # 仪表盘状态 │ │ │ ├── equipment.ts # 设备状态 │ │ │ └── notification.ts # 通知状态 │ │ ├── router/ # 路由配置 │ │ │ └── index.ts │ │ ├── types/ # TypeScript类型 │ │ │ └── index.ts │ │ ├── utils/ # 工具函数 │ │ │ └── request.ts # HTTP请求封装 │ ├── nginx.conf # Nginx配置 │ ├── Dockerfile # Docker构建文件 │ └── package.json # 依赖配置 │ ├── chat-boot/ # AI聊天服务 (v4.2.0) │ ├── src/chat_boot/ │ │ ├── __init__.py # 包初始化 │ │ ├── app.py # 应用入口(FastAPI) │ │ ├── agent/ # Agent层 │ │ │ ├── __init__.py │ │ │ ├── agent.py # Agent核心逻辑 │ │ │ ├── llm.py # LLM工厂(智谱/OpenAI/Ollama/LMStudio) │ │ │ ├── session.py # 会话管理(Redis持久化) │ │ │ ├── common.py # 通用工具函数 │ │ │ └── tools/ # 工具定义 │ │ │ ├── __init__.py │ │ │ └── agent_tools.py # 设备/统计/告警/文档工具 │ │ ├── api/ # API层 │ │ │ ├── __init__.py │ │ │ ├── middleware/ │ │ │ │ ├── __init__.py │ │ │ │ └── jwt.py # JWT中间件 │ │ │ └── routers/ │ │ │ ├── __init__.py │ │ │ ├── chat.py # 聊天API (SSE流式+多模态) │ │ │ ├── sessions.py # 会话管理API │ │ │ ├── documents.py # 文档上传API │ │ │ ├── document.py # 文档管理API │ │ │ ├── prompts.py # Prompt版本管理API │ │ │ └── auth.py # 认证API │ │ ├── core/ # 核心层 │ │ │ ├── __init__.py │ │ │ ├── config.py # 配置管理(Pydantic Settings) │ │ │ ├── security.py # 安全防护(XSS/SQL注入/脱敏) │ │ │ ├── logging.py # 日志配置 │ │ │ ├── monitoring.py # 性能监控 │ │ │ ├── enhanced_monitoring.py # 增强监控 │ │ │ └── status.py # 系统状态 │ │ ├── models/ # 数据模型层 │ │ │ ├── __init__.py │ │ │ └── schemas.py # Pydantic模型 │ │ ├── rag/ # RAG层 │ │ │ ├── __init__.py │ │ │ ├── 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 # 查询改写 │ │ │ ├── reranker.py # 重排序(Cross-Encoder) │ │ │ ├── evaluation.py # RAG评估 │ │ │ ├── cache.py # 语义缓存 │ │ │ ├── hallucination.py # 幻觉检测 │ │ │ ├── multimodal.py # 多模态处理(图片理解/OCR) │ │ │ └── prompt_manager.py # Prompt版本管理 │ │ └── services/ # 业务服务层 │ │ ├── __init__.py │ │ ├── document_service.py # 文档处理服务(PDF/Word/Excel/TXT/MD) │ │ ├── equipment_service.py # 设备服务客户端 │ │ ├── statistical_service.py # 统计服务客户端 │ │ ├── alert_service.py # 告警服务客户端 │ │ └── dashboard_service.py # 仪表盘服务客户端 │ ├── Dockerfile # Docker构建文件 │ ├── pyproject.toml # 项目配置(Python 3.10+) │ ├── requirements.txt # Python依赖(生成) │ ├── setup.bat / setup.ps1 / setup.sh # 环境配置脚本 │ └── run.bat / run.sh # 启动脚本 │ ├── monitoring/ # 监控配置 │ ├── prometheus.yml # Prometheus采集配置 │ ├── promtail-config.yml # Promtail日志采集配置 │ └── grafana/ # Grafana可视化配置 │ └── provisioning/ │ └── datasources.yml # 数据源配置(Prometheus+Loki) │ ├── docker-compose.yml # Docker Compose单文件配置(含全部环境) ├── k8s/ # Kubernetes部署配置 │ ├── 00-namespace.yaml ~ 13-ingress.yaml # K8s资源配置 │ └── deploy.ps1 # 部署脚本 ├── .env.example # 环境变量示例 ├── KUBERNETES_DEPLOYMENT.md # K8s部署文档 └── README.md # 项目说明 ``` ## 数据库设计 ### 数据库表结构 ```sql -- PostgreSQL 数据库初始化 -- 启用 pgvector 扩展（用于向量存储） CREATE EXTENSION IF NOT EXISTS vector; -- 设备表 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 ); -- 上报数据表 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 ); -- 用电量统计表(每次) 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 -- 上报时间 ); -- 用电量统计表(每日) 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 -- 记录时间 ); -- 用电量统计表(每月) 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 -- 记录时间 ); -- 告警表 CREATE TABLE equipment_alert ( id BIGSERIAL PRIMARY KEY, equipment_id BIGINT NOT NULL, -- 设备ID alert_type VARCHAR(50) NOT NULL, -- 告警类型 alert_level VARCHAR(20) NOT NULL, -- 告警级别 threshold_value DOUBLE PRECISION, -- 阈值 actual_value DOUBLE PRECISION, -- 实际值 message VARCHAR(500), -- 告警描述 status VARCHAR(20) DEFAULT 'active', -- 状态 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, resolved_at TIMESTAMP -- 解决时间 ); -- 系统用户表 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 ); -- 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), 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 ); ``` ### 初始数据 ```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); ``` ## 快速开始 ### 前置条件 | 软件 | 版本要求 | 说明 | |------|----------|------| | Docker | 25.0+ | 容器运行环境 | | Docker Compose | v2.0+ | 容器编排工具 | | JDK | 21+ | Java开发环境(可选，本地开发用) | | Maven | 3.9+ | Java构建工具(可选，本地开发用) | | Node.js | 18+ | 前端运行环境(可选，本地开发用) | ### 方式一：Docker Compose 部署（推荐） #### 1. 克隆项目 ```bash git clone cd data-summary ``` #### 2. 配置环境变量 ```bash # 复制环境变量示例文件 cp .env.example .env # 编辑环境变量 vim .env ``` **.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 ``` #### 3. 启动服务 ```bash # 启动所有服务（开发/生产使用同一配置，通过 .env 区分） docker compose up -d ``` #### 4. 访问系统 | 服务 | 地址 | 说明 | |------|------|------| | 前端 | http://localhost:3000 | Web界面 | | API网关 | http://localhost:8080 | 统一入口 | | 设备服务 | http://localhost:8081 | 设备API | | 统计服务 | http://localhost:8083 | 统计API | | Chat-Boot | http://localhost:9999 | AI服务 | | Grafana | http://localhost:3001 | 监控面板 (admin/admin) | | Jaeger | http://localhost:16686 | 链路追踪 | | Prometheus | http://localhost:9090 | 指标查询 | | PostgreSQL | localhost:5432 | 数据库 | ### 方式二：本地开发环境 #### 1. 启动基础设施 ```bash docker compose up -d postgres redis kafka zookeeper ``` #### 2. 后端开发 ```bash cd back-end # 安装公共模块 cd common-module && mvn clean install -DskipTests && cd .. # 启动各个服务（分别在不同终端） cd equipment-service && mvn spring-boot:run cd receiver-service && mvn spring-boot:run cd statistics-service && mvn spring-boot:run cd gateway-service && mvn spring-boot:run ``` #### 3. 前端开发 ```bash cd frontend npm install npm run dev ``` ## 代码修改与重新部署 ### 修改代码后如何在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` | ### 修改Python代码（chat-boot） ```bash # 修改 chat-boot/src/chat_boot/ 下的Python文件后 docker compose up -d --build chat-boot ``` ### 修改前端代码（frontend） ```bash # 1. 进入前端目录 cd frontend # 2. 修改代码（src/views/*.vue, src/stores/*.ts等） # 3. 本地构建 npm run build # 4. 回到项目根目录 cd .. # 5. 重新构建Docker镜像并启动 docker compose up -d --build frontend ``` ### 修改Java代码（back-end） ```bash # 1. 进入后端目录 cd back-end # 2. 修改代码（例如修改 equipment-service） # 3. 重新构建单个服务的JAR包 cd equipment-service mvn clean package spring-boot:repackage -DskipTests # 4. 回到项目根目录 cd ../.. # 5. 重新构建Docker镜像并启动 docker compose up -d --build equipment ``` ### 修改配置文件 ```bash # 修改 .env 或 docker-compose.yml 后，只需重启服务 docker compose up -d ``` ### 修改多个服务后的批量部署 ```bash # 重新构建所有后端服务 cd back-end mvn clean package -DskipTests # 回到项目根目录 cd .. # 重新构建所有服务 docker compose up -d --build ``` ### 常用命令速查 | 场景 | 命令 | |------|------| | 修改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` | ### 查看服务日志 ```bash # 查看单个服务日志 docker compose logs -f chat-boot # 查看多个服务日志 docker compose logs -f gateway equipment statistics # 查看最近100行日志 docker compose logs --tail=100 chat-boot ``` ### 重启服务 ```bash # 重启单个服务 docker compose restart chat-boot # 重启多个服务 docker compose restart gateway equipment statistics # 重新创建并启动（使用新镜像） docker compose up -d --force-recreate chat-boot ``` ### 调试技巧 ```bash # 进入容器内部调试 docker compose exec chat-boot bash # 查看容器内的环境变量 docker compose exec chat-boot env # 查看容器内的文件 docker compose exec chat-boot ls -la /app # 实时查看日志 docker compose logs -f --tail=50 chat-boot # 查看容器资源使用 docker stats ``` ## API接口文档 ### 设备服务 API | 方法 | 路径 | 说明 | |------|------|------| | GET | /equipment | 获取设备列表(分页) | | GET | /equipment/{id} | 获取设备详情 | | GET | /equipment/sn/{deviceSn} | 根据SN号查询设备 | | GET | /equipment/all | 获取所有设备 | | POST | /equipment | 添加设备 | | PUT | /equipment/{id} | 更新设备 | | DELETE | /equipment/{id} | 删除设备 | ### 告警服务 API | 方法 | 路径 | 说明 | |------|------|------| | GET | /alert | 获取告警列表(分页) | | GET | /alert/active | 获取活跃告警 | | GET | /alert/count | 获取活跃告警数量 | | PUT | /alert/{id}/acknowledge | 确认告警 | | PUT | /alert/{id}/resolve | 解决告警 | ### 统计服务 API | 方法 | 路径 | 说明 | |------|------|------| | 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 | 手动触发统计 | ### 仪表盘 API | 方法 | 路径 | 说明 | |------|------|------| | GET | /dashboard | 获取仪表盘数据 | ### Chat-Boot API | 方法 | 路径 | 说明 | |------|------|------| | POST | /chat-api/api/chat/stream | SSE流式对话 | | GET | /chat-api/api/sessions | 获取会话列表 | | POST | /chat-api/api/sessions | 创建新会话 | | DELETE | /chat-api/api/sessions/{id} | 删除会话 | | GET | /chat-api/api/documents | 获取文档列表 | | POST | /chat-api/api/documents/upload | 上传文档 | | POST | /chat-api/api/documents/{id}/process | 处理文档(切分+向量化) | | DELETE | /chat-api/api/documents/{id} | 删除文档 | | GET | /health | 健康检查 | ### 支持的文档格式 | 格式 | 后缀 | 解析库 | 说明 | |------|------|--------|------| | PDF | .pdf | pypdf | 按页解析 | | Word | .docx/.doc | python-docx | 按段落解析 | | Excel | .xlsx | openpyxl | 按工作表解析，保留表头 | | Excel | .xls | xlrd | 旧版格式，按工作表解析 | | 文本 | .txt | 内置 | 直接读取 | | Markdown | .md/.markdown | 内置 | 直接读取 | ## Kafka消息格式 ### 电表报文格式 发送到 `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） | ### 用电量计算逻辑 ``` 本次用电量 = 本次上报读数 - 上次上报读数 ``` **示例：** - 设备初始读数：1000.0 kWh - 第一次上报：1600.0 kWh → 用电量 = 1600 - 1000 = 600 kWh - 第二次上报：1800.0 kWh → 用电量 = 1800 - 1600 = 200 kWh ### 发送测试消息 ```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 ``` ### 异常处理 | 场景 | 处理方式 | |------|----------| | 设备不存在 | 忽略消息，记录警告日志 | | 时间戳格式错误 | 使用当前时间替代 | | 读数小于上次 | 标记为异常数据，创建告警 | | 单次用电量 > 1000 kWh | 创建超阈值告警 | ## 数据流向 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 数据处理流程 │ └─────────────────────────────────────────────────────────────────┘ 1. 电表设备 → Kafka (meter-data主题) │ ▼ 2. Receiver Service 消费消息 │ ├──→ 解析JSON报文 ├──→ 查询设备信息 ├──→ 计算用电量增量 ├──→ 异常检测 │ ▼ 3. 数据存储 (PostgreSQL) │ ├──→ report_data表 (原始上报数据) ├──→ data_summary_each_piece表 (每次用电量) ├──→ equipment表 (更新最后上报信息) └──→ equipment_alert表 (如有异常) │ ▼ 4. 触发统计 │ └──→ 调用 Statistics Service /statistical/trigger │ ├──→ data_summary_each_day表 (日统计) └──→ data_summary_each_month表 (月统计) ``` ## AI助手功能 ### 功能特性 - **设备查询**：查询设备信息、初始值、状态 - **用电统计**：查询今日/本月/今年用电量 - **告警查询**：查看活跃告警、设备告警 - **系统概览**：查看系统整体运行状态 - **文档问答**：基于RAG的技术文档问答 - **上下文记忆**：支持多轮对话，理解上下文 - **知识库管理**：支持上传PDF/Word/Excel/TXT/MD文档，自动切分向量化 - **多会话管理**：支持创建多个独立会话，会话历史本地持久化 - **会话持久化**：Redis存储，重启不丢失会话数据 - **Prompt版本管理**：支持Prompt配置化管理、版本控制、热更新 ### 测试问题 ``` 用户：系统有多少台设备？ AI：当前系统共有3台设备。 用户：电表001的详细信息？ AI：电表001的详细信息如下： - 设备编号：SN00000001 - 设备类型：单相 - 安装位置：1号楼1单元 - 设备状态：在线 - 初始读数：1000.0 kWh 用户：它的初始值是多少？ <-- 理解上下文 AI：电表001的初始读数为1000.0 kWh。 ``` ## 常用命令 ### 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 ``` ### 数据库操作 ```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;" ``` ### 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 ``` ## 故障排查 ### 服务无法启动 ```bash # 查看服务日志 docker compose logs [service-name] # 检查端口占用 netstat -ano | findstr :8080 ``` ### 数据库连接失败 ```bash # 检查PostgreSQL状态 docker compose ps postgres # 测试连接 docker exec -it data-summary-postgres psql -U postgres -c "SELECT 1;" ``` ### Kafka消息消费失败 ```bash # 检查Kafka状态 docker compose ps kafka # 查看receiver日志 docker compose logs -f receiver ``` ## 环境变量说明 | 变量名 | 默认值 | 说明 | |--------|--------|------| | DB_USER | postgres | PostgreSQL用户名 | | DB_PASSWORD | postgres123 | PostgreSQL密码 | | DB_NAME | data_summary | 数据库名 | | REDIS_PASSWORD | redis123 | Redis密码 | | JWT_SECRET | - | JWT密钥(生产必填) | | GATEWAY_SECURITY_TOKEN | dev-gateway-token-2024 | Gateway安全令牌(用于微服务间认证) | | LLM_TYPE | zhipu | LLM类型(zhipu/openai/ollama/lmstudio) | | ZHIPU_API_KEY | - | 智谱AI密钥 | | 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 | 日志级别 | ## 版本历史 | 版本 | 日期 | 更新内容 | |------|------|----------| | 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