financial-intelligence-system README

The project's README from github.com/zhangzf1119/financial-intelligence-system. As one markdown file: README.md.

FinSight Enterprise Backend

FinSight Enterprise Backend 是一个基于 Spring Boot 3 的企业级智能管理平台后端。项目围绕企业后台常见能力建设，提供用户、角色、菜单、部门、日志、监控、文件中心、工作流、即时通讯、AI 模型对话与 RAG 知识库能力，适合作为企业内部管理系统、智能办公平台、知识库问答平台的后端基础工程。

当前仓库是后端工程。前端工程位于 ../../1web/financial_intelligence_system/，前端技术栈为 Vue 3、TypeScript、Element Plus。

目录

项目特性

技术栈

类型 技术
基础框架 Java 21、Spring Boot 3.5.4
Web Spring MVC、Spring Validation
安全 Spring Security、JWT、BCrypt
数据库 PostgreSQL 16、pgvector
数据访问 Spring JDBC JdbcClient
数据迁移 Flyway
缓存/会话 Redis、Spring Data Redis
接口文档 SpringDoc OpenAPI、Swagger UI
文件存储 本地文件系统、MinIO/S3
工作流 Flowable 7.2
文档解析 PDFBox、Apache POI
Office 预览 LibreOffice/soffice 转 PDF
实时通信 Spring WebSocket

系统架构

前端 Vue 3
  |
  | HTTP / SSE / WebSocket
  v
Spring Boot Backend
  |
  |-- Security Filter Chain
  |     |-- JWT 校验
  |     |-- Redis Token 黑名单
  |     |-- 普通用户单设备在线校验
  |
  |-- Controller
  |     |-- AuthController
  |     |-- SystemController
  |     |-- AiController
  |     |-- KnowledgeController
  |     |-- FileController
  |     |-- WorkflowController
  |     |-- ImController
  |     |-- LogController
  |     |-- MonitorController
  |
  |-- Service
  |     |-- AI 调用与流式响应
  |     |-- RAG 文档解析、切片、向量化、混合检索
  |     |-- 文件存储、本地/MinIO 切换
  |     |-- Redis 会话安全
  |     |-- 审计日志
  |
  |-- PostgreSQL 16 + pgvector
  |-- Redis
  |-- MinIO/S3 可选
  |-- 大模型服务 OpenAI Compatible API

目录结构

Financial_Intelligence_System/
├── pom.xml
├── mvnw
├── README.md
├── HELP.md
├── data/
│   └── uploads/                  # 默认本地文件上传目录
└── src/
    ├── main/
    │   ├── java/com/rpa/financial_intelligence_system/
    │   │   ├── FinancialIntelligenceSystemApplication.java
    │   │   ├── common/            # 统一响应、全局异常处理
    │   │   ├── config/            # 安全、OpenAPI、异步、WebSocket 配置
    │   │   ├── controller/        # REST API 控制器
    │   │   ├── security/          # JWT、用户认证、操作日志过滤器
    │   │   └── service/           # 业务服务、AI、RAG、文件、Redis、IM
    │   └── resources/
    │       ├── application.yaml
    │       └── db/migration/      # Flyway 数据库迁移脚本
    └── test/

环境要求

快速启动

1. 创建数据库

请先确认 PostgreSQL 已安装 pgvector 扩展。macOS 可通过 Homebrew 安装：

brew install pgvector

创建数据库：

createdb -U postgres financial_ai

如果需要手动初始化扩展：

CREATE EXTENSION IF NOT EXISTS vector;

2. 启动 Redis

本地默认连接：

host: localhost
port: 6379
password: 空

3. 修改配置

默认配置位于 src/main/resources/application.yaml，也可以通过环境变量覆盖。

本地默认数据库配置：

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/financial_ai
    username: postgres
    password: 123456

4. 启动后端

./mvnw spring-boot:run

默认访问地址：

http://localhost:8080

5. 编译检查

./mvnw -DskipTests compile

配置说明

项目支持通过环境变量覆盖核心配置，适合本地开发、测试环境和生产环境分别配置。

环境变量 默认值 说明
SERVER_PORT 8080 后端服务端口
DB_URL jdbc:postgresql://localhost:5432/financial_ai PostgreSQL JDBC 地址
DB_USERNAME postgres 数据库用户名
DB_PASSWORD 123456 数据库密码
REDIS_HOST localhost Redis 地址
REDIS_PORT 6379 Redis 端口
REDIS_PASSWORD 空 Redis 密码
JWT_SECRET 开发默认值 JWT 签名密钥
JWT_EXPIRATION_HOURS 12 Token 有效小时数
LIBREOFFICE_COMMAND soffice LibreOffice 命令路径
OFFICE_PREVIEW_TIMEOUT_SECONDS 60 Office 转 PDF 超时时间
AI_BASE_URL https://api.openai.com/v1 默认 Chat API 基础地址
AI_API_KEY 空 默认模型 API Key
AI_CHAT_MODEL gpt-4.1-mini 默认 Chat 模型
AI_EMBEDDING_MODEL text-embedding-3-small 默认 Embedding 模型
AI_EMBEDDING_DIMENSIONS 1536 默认 Embedding 维度

生产环境必须覆盖 JWT_SECRET，并且不要把任何真实 API Key、MinIO Secret、数据库密码提交到 GitHub。

默认账号

Flyway 初始化脚本会创建一个超级管理员账号：

用户名：admin
密码：Admin@123

该账号拥有全部菜单和接口权限，建议首次部署后立即修改密码。

接口文档

启动后访问：

http://localhost:8080/swagger-ui.html

OpenAPI JSON：

http://localhost:8080/v3/api-docs

认证方式：

  1. 调用 /api/auth/login 获取 token。
  2. 打开 Swagger 右上角 Authorize。
  3. 填入登录返回的 JWT Token。
  4. 登录接口无需认证，其余业务接口默认需要认证。

核心模块说明

身份认证

对应控制器：AuthController

登录安全能力：

系统管理

对应控制器：SystemController

能力包括：

权限模型：

日志管理

对应控制器：LogController

操作日志通过过滤器采集接口、耗时、状态码、用户、IP、错误信息等内容。

系统监控

对应控制器：MonitorController

返回指标包括：

文件中心

对应控制器：FileController

能力包括：

常用接口：

默认本地上传目录：

data/uploads

Office 转 PDF 依赖 LibreOffice。若系统无法识别 soffice，请通过 LIBREOFFICE_COMMAND 指定完整路径。

工作流

对应控制器：WorkflowController

基于 Flowable BPMN 2.0，支持：

常用接口：

即时通讯

对应控制器：ImController

能力包括：

WebSocket 地址：

ws://localhost:8080/ws/chat?token=JWT_TOKEN

AI 智能中心

对应控制器：AiController

能力包括：

模型配置表：ai_model_config

配置项分为两组：

API Key 会加密后保存，密钥派生自 JWT_SECRET。生产环境必须固定且妥善保管 JWT_SECRET，否则已加密配置可能无法解密。

RAG 知识库说明

对应控制器：KnowledgeController

RAG 知识库模块用于把企业文档解析、切片、向量化，并在对话时进行知识库增强回答。

数据模型

核心表：

切片表使用 pgvector HNSW 索引：

CREATE INDEX idx_knowledge_chunk_embedding_hnsw
ON knowledge_chunk
USING HNSW (embedding vector_cosine_ops)
WHERE embedding IS NOT NULL;

同时使用 PostgreSQL GIN 全文索引：

CREATE INDEX idx_knowledge_chunk_search_vector
ON knowledge_chunk
USING GIN(search_vector);

文档处理流程

上传文档
  |
  v
写入 sys_file
  |
  v
创建 knowledge_document，状态 PENDING
  |
  v
后台异步解析文档，状态 PROCESSING
  |
  v
生成 Parent Chunk
  |
  v
生成 Child Chunk
  |
  v
调用 Embedding API
  |
  v
写入 pgvector
  |
  v
状态 COMPLETED

如果解析或向量化失败，文档状态会更新为 FAILED，并保存错误信息，不会导致主服务崩溃。

父子切片策略

混合检索策略

KnowledgeRetrievalService 实现了混合检索：

知识库问答

POST /api/ai/chat/stream 支持传入 knowledgeBaseIds。

请求示例：

{
  "message": "请总结这份部署手册的环境要求",
  "conversationId": 1,
  "knowledgeBaseIds": [1]
}

指定知识库后，后端会：

  1. 对用户问题生成 Query Embedding。
  2. 通过混合检索召回相关切片。
  3. 组装防幻觉 System Prompt。
  4. 调用 Chat 模型进行 SSE 流式回答。
  5. 返回答案和引用来源。

防幻觉原则：

数据库迁移

项目使用 Flyway 自动管理数据库结构，迁移脚本位于：

src/main/resources/db/migration

当前主要迁移：

版本 说明
V1 初始化系统管理、用户、角色、菜单、AI 基础知识表
V2 AI 模型配置
V3 Chat 模型和向量模型配置拆分
V4 登录日志、操作日志、模型对话日志
V5 系统监控菜单
V6 文件中心、存储配置、工作流基础表
V7 系统监控移动到系统管理
V8 文件设置菜单调整
V9 文件设置移动到系统管理
V10 Flowable BPMN 元数据
V11 模型设置、日志管理移动到系统管理
V12 企业即时通讯
V13 AI 会话历史
V14 RAG 知识库增强、父子切片、HNSW、全文索引

首次启动时 Flyway 会自动执行迁移。已有数据库升级时请勿手动修改 flyway_schema_history。

常用接口

模块 路径
登录 POST /api/auth/login
当前用户 GET /api/auth/me
用户管理 /api/system/users
角色管理 /api/system/roles
菜单管理 /api/system/menus
部门管理 /api/system/departments
系统监控 GET /api/monitor/system
文件中心 /api/files
存储设置 /api/storage/settings
工作流 /api/workflow/**
即时通讯 /api/im/**
模型对话 /api/ai/chat
流式对话 /api/ai/chat/stream
模型设置 /api/ai/settings
知识库 /api/knowledge/**
日志管理 /api/logs/**

完整接口以 Swagger UI 为准。

开发规范

安全建议

开源或生产部署前请重点检查：

常见问题

1. 启动时报 extension "vector" is not available

说明 PostgreSQL 未安装 pgvector。请先安装 pgvector，并确认当前数据库可以执行：

CREATE EXTENSION IF NOT EXISTS vector;

2. Redis 连接失败

请确认 Redis 正在运行，并检查以下配置：

spring:
  data:
    redis:
      host: localhost
      port: 6379

3. Office 文件无法转 PDF 预览

请安装 LibreOffice，并确认命令可执行：

soffice --version

如果命令不在 PATH 中，请设置：

export LIBREOFFICE_COMMAND=/Applications/LibreOffice.app/Contents/MacOS/soffice

4. RAG 文档一直是 FAILED

常见原因：

请先在管理员后台测试向量化模型，再重新处理文档。

5. 普通用户登录后另一个设备被挤下线

这是系统设计。普通用户只允许一台设备在线，超级管理员除外。

开源说明

建议开源前补充以下文件：

本项目 README 不包含任何真实密钥。提交 GitHub 前请再次检查：

git diff --cached
git status

如果仓库历史中曾经提交过密钥，请在公开前先轮换密钥，并清理 Git 历史。

financial-intelligence-system (zhangzf1119/financial-intelligence-system)

Searching Database…

170 ·GitHub
Financial-intelligence-system
What is this?FinSight Enterprise Backend is a Spring Boot 3 backend for an enterprise intelligent management platform, covering RBAC, logging, monitoring, a file center, workflow approvals, in-app instant messaging, AI model chat and a RAG knowledge base.
Is this a standalone app or just the backend?It is purely the backend service (REST API plus WebSocket). It is meant to be paired with a separate Vue 3 + TypeScript + Element Plus frontend that lives in a sibling repository folder.
How do I get it running?Create a PostgreSQL 16 database with the pgvector extension, start Redis, adjust config in application.yaml (or override via environment variables), then launch with the bundled Maven wrapper.
What do I need installed before running this?JDK 21+, Maven 3.9+ (or the included ./mvnw), PostgreSQL 16+ with the pgvector extension, and Redis 6+. MinIO/S3-compatible storage and LibreOffice are optional, needed only for S3 file storage and Office-to-PDF preview.
What are common setup pitfalls?Startup fails with an 'extension vector is not available' error if pgvector isn't installed in PostgreSQL. Office-to-PDF preview needs the LibreOffice 'soffice' binary findable or set via LIBREOFFICECOMMAND, and RAG documents can get stuck in FAILED status if the embedding API key or vector dimensions are misconfigured.
How does the RAG knowledge base retrieve answers?It uses PostgreSQL + pgvector with parent/child chunking: small child chunks (about 200-300 tokens) are embedded and retrieved via vector similarity, then expanded to larger parent chunks (about 800-1000 tokens) for context. Results from vector search and PostgreSQL full-text search are merged with Reciprocal Rank Fusion, and answers are generated with an anti-hallucination prompt that cites page sources.
Is there a default admin account?Yes, the Flyway migration scripts create a super-admin account with full menu and API permissions; it's strongly recommended to change the password right after first deployment.
Does it support real-time chat between users?Yes, it includes a built-in IM module with 1-on-1 and group chats, file/image messages, unread counts, typing indicators, a 2-minute message recall window, and WebSocket push for live delivery.
How does it limit concurrent logins?Normal users are restricted to one active device at a time (a new login logs out the old session via Redis), while super-admin accounts are exempt from this limit.
What are similar projects?financial_intelligence_system_web, JeecgBoot, open-webui, bisheng, WeKnora, Prism-Legal-OS, eladmin, zilan
Which topics is it in?cache, file-manager, full-text-search, spring-boot, openapi, jwt, rbac, knowledge-management, messaging, vector-database, semantic-search, chat
Creator
zhangzf1119
Size
0.1 MB
Stars
170
Updated
CommitSep 16
Age
2mo
Commits · 90 Days