|
|
@@ -0,0 +1,308 @@
|
|
|
+# LQAdminPlatform 项目结构说明
|
|
|
+
|
|
|
+## 1. 项目概述
|
|
|
+
|
|
|
+LQAdminPlatform 是一个基于 **FastAPI** 的后端管理平台，主要服务于"四川路桥"业务场景，包含三大核心功能域：
|
|
|
+
|
|
|
+| 功能域 | 说明 |
|
|
|
+|---|---|
|
|
|
+| 系统管理 | 用户、角色、菜单、权限、日志、仪表盘、字典管理 |
|
|
|
+| 授权管理 (SSO) | OAuth2 认证流程、JWT Token 管理、子系统单点登录 |
|
|
|
+| 样本中心 | 知识库、文档管理、知识片段、标签管理、语义检索（Milvus 向量搜索）、图片管理 |
|
|
|
+
|
|
|
+## 2. 技术栈
|
|
|
+
|
|
|
+| 类别 | 技术 |
|
|
|
+|---|---|
|
|
|
+| 语言 | Python 3.12 |
|
|
|
+| Web 框架 | FastAPI 0.104 + Uvicorn 0.24 |
|
|
|
+| ORM | SQLAlchemy 2.0（异步） |
|
|
|
+| 数据库迁移 | Alembic 1.12 |
|
|
|
+| 主数据库 | MySQL（aiomysql） |
|
|
|
+| 缓存 | Redis（aioredis） |
|
|
|
+| 向量数据库 | Milvus（pymilvus） |
|
|
|
+| 对象存储 | MinIO |
|
|
|
+| 认证 | python-jose (JWT) + passlib + bcrypt |
|
|
|
+| 数据校验 | Pydantic 2.x |
|
|
|
+| 任务队列 | Celery 5.3 + Flower |
|
|
|
+| AI/ML | langchain-openai、langchain-milvus、sentence-transformers |
|
|
|
+| 文档解析 | MinerU |
|
|
|
+| 日志 | loguru |
|
|
|
+| 容器化 | Docker + Docker Compose（MySQL / Milvus / Nginx） |
|
|
|
+
|
|
|
+## 3. 顶层目录结构
|
|
|
+
|
|
|
+```
|
|
|
+LQAdminPlatform/
|
|
|
+├── Dockerfile # Docker 镜像构建（python:3.12-slim，暴露 8000 端口）
|
|
|
+├── README_deploy.md # Docker 部署说明
|
|
|
+├── run.sh # 服务管理脚本（start/stop/restart/status）
|
|
|
+├── run_server.py # Python 入口（uvicorn 启动器，自动查找可用端口）
|
|
|
+├── requirements/ # Python 依赖管理
|
|
|
+│ ├── base.txt # 生产依赖
|
|
|
+│ ├── dev.txt # 开发工具（pytest, black, flake8, mypy, mkdocs）
|
|
|
+│ └── requirements.txt # 完整依赖（base + dev 合并）
|
|
|
+├── docker/ # Docker Compose 编排
|
|
|
+│ ├── docker-compose.yml # 总入口编排文件
|
|
|
+│ ├── mysql/ # MySQL 服务
|
|
|
+│ ├── milvus/ # Milvus 向量数据库
|
|
|
+│ └── nginx/ # Nginx 反向代理
|
|
|
+├── logs/ # 应用日志输出目录
|
|
|
+├── scripts/ # SQL 脚本及工具脚本
|
|
|
+├── src/ # 全部应用源代码
|
|
|
+├── 项目/ # 设计文档、API 接口定义、需求文档
|
|
|
+└── .gitignore
|
|
|
+```
|
|
|
+
|
|
|
+## 4. 源代码目录结构（src/）
|
|
|
+
|
|
|
+```
|
|
|
+src/
|
|
|
+├── path_config.py # 自动配置 Python 导入路径
|
|
|
+├── deploy/ # 前端部署脚本
|
|
|
+│ ├── admin_front_deploy.py
|
|
|
+│ ├── admin_front_deploy.sh
|
|
|
+│ └── admin_front_dempoy_README.md
|
|
|
+│
|
|
|
+└── app/
|
|
|
+ ├── __init__.py
|
|
|
+ │
|
|
|
+ ├── server/ # FastAPI 应用工厂 & 入口
|
|
|
+ │ └── app.py # 主 FastAPI 实例：中间件、CORS、异常处理、路由注册、lifespan
|
|
|
+ │
|
|
|
+ ├── base/ # 基础设施 / 连接管理
|
|
|
+ │ ├── async_mysql_connection.py # SQLAlchemy 异步 MySQL 连接（get_db, init_db, close_db）
|
|
|
+ │ ├── async_redis_connection.py # Redis 连接（init_redis, close_redis）
|
|
|
+ │ ├── milvus_connection.py # Milvus 向量数据库连接
|
|
|
+ │ ├── minio_connection.py # MinIO 对象存储连接
|
|
|
+ │ ├── mineru_connection.py # MinerU 文档解析连接
|
|
|
+ │ ├── embedding_connection.py # Embedding 模型配置
|
|
|
+ │ └── pymilvus_store_database.py # Milvus 存储抽象
|
|
|
+ │
|
|
|
+ ├── core/ # 核心框架代码
|
|
|
+ │ ├── config.py # ConfigHandler — INI 配置文件解析器（全局实例: config_handler）
|
|
|
+ │ ├── exceptions.py # 自定义异常 BaseAPIException
|
|
|
+ │ └── sliding_token_config.py # 滑动窗口 Token 配置
|
|
|
+ │
|
|
|
+ ├── logger/ # 日志配置
|
|
|
+ │ ├── config.py
|
|
|
+ │ └── loggering.py
|
|
|
+ │
|
|
|
+ ├── middleware/ # HTTP 中间件
|
|
|
+ │ └── token_refresh_middleware.py # JWT Token 自动刷新中间件
|
|
|
+ │
|
|
|
+ ├── models/ # 通用 / 全局 SQLAlchemy 模型
|
|
|
+ │ ├── base.py # 基础模型类
|
|
|
+ │ ├── user.py
|
|
|
+ │ ├── token.py
|
|
|
+ │ ├── log.py
|
|
|
+ │ ├── app.py
|
|
|
+ │ └── knowledge_base.py
|
|
|
+ │
|
|
|
+ ├── schemas/ # 基础 Pydantic 响应结构
|
|
|
+ │ ├── base.py # ResponseSchema
|
|
|
+ │ ├── auth.py
|
|
|
+ │ └── user.py
|
|
|
+ │
|
|
|
+ ├── utils/ # 工具函数
|
|
|
+ │ ├── auth_decorator.py # 认证装饰器
|
|
|
+ │ ├── auth_dependency.py # 认证依赖注入
|
|
|
+ │ ├── security.py # 安全工具（密码哈希、Token 生成等）
|
|
|
+ │ └── vector_utils.py # 向量工具
|
|
|
+ │
|
|
|
+ ├── services/ # 业务逻辑层（Service 类）
|
|
|
+ │ ├── auth_service.py # 用户登录认证
|
|
|
+ │ ├── system_service.py # 系统管理
|
|
|
+ │ ├── system_service_ext.py # 系统管理扩展
|
|
|
+ │ ├── user_service.py # 用户服务
|
|
|
+ │ ├── oauth_service.py # OAuth 服务
|
|
|
+ │ ├── jwt_token.py # JWT Token 管理
|
|
|
+ │ ├── sample_service.py # 样本中心管理
|
|
|
+ │ ├── knowledge_base_service.py # 知识库服务
|
|
|
+ │ ├── snippet_service.py # 知识片段服务
|
|
|
+ │ ├── tag_category_service.py # 标签分类服务
|
|
|
+ │ ├── dict_category_service.py # 字典分类服务
|
|
|
+ │ ├── dict_item_service.py # 字典项服务
|
|
|
+ │ ├── milvus_service.py # Milvus 向量搜索服务
|
|
|
+ │ ├── search_engine_service.py # 搜索引擎服务
|
|
|
+ │ ├── image_service.py # 图片服务
|
|
|
+ │ └── task_service.py # 任务服务
|
|
|
+ │
|
|
|
+ │
|
|
|
+ │ ====== 以下三大模块按功能域划分 ======
|
|
|
+ │
|
|
|
+ ├── system/ # 【系统管理模块】
|
|
|
+ │ ├── models/ # 系统相关 SQLAlchemy 模型
|
|
|
+ │ └── schemas/ # 系统相关 Pydantic 结构
|
|
|
+ │ ├── dict_category_schema.py
|
|
|
+ │ ├── dict_item_schema.py
|
|
|
+ │ └── system_schemas.py
|
|
|
+ │
|
|
|
+ ├── oauth/ # 【授权管理 / SSO 模块】
|
|
|
+ │ ├── models/ # OAuth SQLAlchemy 模型
|
|
|
+ │ └── schemas/ # OAuth Pydantic 结构
|
|
|
+ │
|
|
|
+ └── sample/ # 【样本中心模块】
|
|
|
+ ├── models/ # 样本中心 SQLAlchemy 模型
|
|
|
+ │ ├── knowledge_base.py # 知识库模型
|
|
|
+ │ ├── metadata.py # 元数据模型
|
|
|
+ │ ├── tag_category.py # 标签分类模型
|
|
|
+ │ ├── search_engine.py # 搜索引擎模型
|
|
|
+ │ ├── base_info.py # 基本信息模型
|
|
|
+ │ └── custom_schema.py # 自定义结构模型
|
|
|
+ └── schemas/ # 样本中心 Pydantic 结构
|
|
|
+ ├── knowledge_base.py
|
|
|
+ ├── sample_schemas.py
|
|
|
+ ├── search_engine.py
|
|
|
+ └── tag_category.py
|
|
|
+
|
|
|
+├── views/ # HTTP 路由定义（API 端点）
|
|
|
+│ ├── system_view.py # 系统管理路由（用户、角色、菜单、权限等）
|
|
|
+│ ├── auth_view.py # 认证路由（登录、验证码、刷新 Token）
|
|
|
+│ ├── sso_view.py # SSO 授权路由
|
|
|
+│ ├── oauth_view.py # OAuth 路由
|
|
|
+│ ├── sample_view.py # 样本中心路由
|
|
|
+│ ├── knowledge_base_view.py # 知识库 CRUD 路由
|
|
|
+│ ├── snippet_view.py # 知识片段 CRUD 路由
|
|
|
+│ ├── tag_view.py # 标签管理路由
|
|
|
+│ ├── search_engine_view.py # 搜索/检索引擎路由
|
|
|
+│ ├── image_view.py # 图片管理路由
|
|
|
+│ ├── dict_category_view.py # 字典分类管理路由
|
|
|
+│ └── dict_item_view.py # 字典项管理路由
|
|
|
+│
|
|
|
+└── api/ # 对外 API 定义（v1 版本）
|
|
|
+ └── v1/
|
|
|
+ ├── api_router.py # 路由聚合（向后兼容）
|
|
|
+ ├── system_api_view.py # 外部系统 API
|
|
|
+ └── document/
|
|
|
+ └── knowledge_base.py # 知识库对外 API
|
|
|
+```
|
|
|
+
|
|
|
+## 5. 功能模块详细说明
|
|
|
+
|
|
|
+### 5.1 系统管理（system/）
|
|
|
+
|
|
|
+| 子功能 | 说明 |
|
|
|
+|---|---|
|
|
|
+| 用户管理 | 用户 CRUD、状态管理、密码重置 |
|
|
|
+| 角色管理 | 角色 CRUD、角色权限分配 |
|
|
|
+| 菜单管理 | 菜单树、权限关联 |
|
|
|
+| 权限管理 | 权限粒度控制 |
|
|
|
+| 系统日志 | 操作日志记录与查询 |
|
|
|
+| 仪表盘 | 数据统计与展示 |
|
|
|
+| 应用管理 | 子系统注册与管理 |
|
|
|
+| 字典管理 | 数据字典分类与字典项维护 |
|
|
|
+
|
|
|
+### 5.2 授权管理（oauth/）
|
|
|
+
|
|
|
+| 子功能 | 说明 |
|
|
|
+|---|---|
|
|
|
+| SSO 认证流程 | 验证凭证 → 生成授权码 → 重定向回子系统 → 授权码换 Token → 获取用户信息 |
|
|
|
+| JWT Token 管理 | Token 生成、验证、刷新（滑动窗口机制） |
|
|
|
+| 子系统登录认证 | 子系统通过 OAuth2 流程接入统一认证平台 |
|
|
|
+
|
|
|
+### 5.3 样本中心（sample/）
|
|
|
+
|
|
|
+| 子功能 | 说明 |
|
|
|
+|---|---|
|
|
|
+| 知识库管理 | 知识库 CRUD、权限控制 |
|
|
|
+| 文档管理 | 文档上传、解析（MinerU）、元数据管理 |
|
|
|
+| 知识片段管理 | 文档切片、片段 CRUD |
|
|
|
+| 标签管理 | 标签分类、标签关联 |
|
|
|
+| 检索引擎 | 全文检索 + Milvus 向量语义检索 |
|
|
|
+| 图片管理 | 图片上传、存储（MinIO）、检索 |
|
|
|
+
|
|
|
+## 6. 关键文件说明
|
|
|
+
|
|
|
+| 文件 | 作用 |
|
|
|
+|---|---|
|
|
|
+| `run_server.py` | 应用启动入口，通过 uvicorn 启动 FastAPI，自动查找可用端口 |
|
|
|
+| `run.sh` | Shell 服务管理脚本，支持 start/stop/restart/status |
|
|
|
+| `src/app/server/app.py` | FastAPI 应用实例，负责中间件、CORS、异常处理、路由注册 |
|
|
|
+| `src/app/core/config.py` | INI 配置文件解析器，全局配置读取 |
|
|
|
+| `src/app/base/async_mysql_connection.py` | 异步 MySQL 连接池管理 |
|
|
|
+| `src/app/base/async_redis_connection.py` | Redis 连接池管理 |
|
|
|
+| `src/app/base/milvus_connection.py` | Milvus 向量数据库连接 |
|
|
|
+| `src/app/middleware/token_refresh_middleware.py` | Token 自动刷新中间件 |
|
|
|
+| `src/app/config/config.ini` | 应用运行时配置（数据库连接、端口、日志级别等） |
|
|
|
+
|
|
|
+## 7. 数据流向
|
|
|
+
|
|
|
+```
|
|
|
+客户端请求
|
|
|
+ ↓
|
|
|
+Nginx 反向代理（可选）
|
|
|
+ ↓
|
|
|
+FastAPI (uvicorn :8000)
|
|
|
+ ↓
|
|
|
+middleware/token_refresh_middleware.py（Token 刷新）
|
|
|
+ ↓
|
|
|
+views/*.py（路由匹配）
|
|
|
+ ↓
|
|
|
+services/*.py（业务逻辑）
|
|
|
+ ↓
|
|
|
+models/*.py（数据模型）
|
|
|
+ ↓
|
|
|
+MySQL（主数据存储）
|
|
|
+Redis（缓存 / Session）
|
|
|
+Milvus（向量检索）
|
|
|
+MinIO（对象存储）
|
|
|
+```
|
|
|
+
|
|
|
+## 8. 前端项目（LQAdminFront，独立仓库）
|
|
|
+
|
|
|
+```
|
|
|
+LQAdminFront/
|
|
|
+├── src/
|
|
|
+│ ├── router/ # 路由配置
|
|
|
+│ ├── components/ # 可复用组件
|
|
|
+│ ├── layouts/ # 布局组件
|
|
|
+│ ├── utils/ # 工具函数
|
|
|
+│ ├── api/ # API 请求（按模块划分）
|
|
|
+│ │ ├── system/ # 系统管理 API 请求
|
|
|
+│ │ │ ├── admin.ts
|
|
|
+│ │ │ ├── app.ts
|
|
|
+│ │ │ ├── user.ts
|
|
|
+│ │ │ ├── role.ts
|
|
|
+│ │ │ └── menu.ts
|
|
|
+│ │ ├── oauth/ # 授权管理 API 请求
|
|
|
+│ │ └── sample/ # 样本中心 API 请求
|
|
|
+│ │ └── document.ts
|
|
|
+│ └── views/ # 页面视图
|
|
|
+│ ├── auth/ # 登录认证
|
|
|
+│ │ ├── Login.vue
|
|
|
+│ │ ├── OAuthCallback.vue
|
|
|
+│ │ └── Register.vue
|
|
|
+│ ├── system/ # 系统管理页面
|
|
|
+│ │ ├── Apps.vue
|
|
|
+│ │ ├── Dashboard.vue
|
|
|
+│ │ ├── Menus.vue
|
|
|
+│ │ ├── Permissions.vue
|
|
|
+│ │ ├── Roles.vue
|
|
|
+│ │ ├── Settings.vue
|
|
|
+│ │ └── Users.vue
|
|
|
+│ └── sample/ # 样本中心页面
|
|
|
+│ ├── knowledge_base/
|
|
|
+│ ├── documents/
|
|
|
+│ ├── knowledge_chunk/
|
|
|
+│ ├── tag/
|
|
|
+│ ├── knowledge_chunk_search/
|
|
|
+│ ├── base_info/
|
|
|
+│ └── image/
|
|
|
+```
|
|
|
+
|
|
|
+## 9. 项目架构分层
|
|
|
+
|
|
|
+```
|
|
|
+┌─────────────────────────────────────────────┐
|
|
|
+│ views/ (路由层) │ ← HTTP 端点定义，按功能划分
|
|
|
+├─────────────────────────────────────────────┤
|
|
|
+│ services/ (业务逻辑层) │ ← 业务规则、数据处理
|
|
|
+├─────────────────────────────────────────────┤
|
|
|
+│ models/ (数据模型) │ schemas/ (数据校验) │ ← SQLAlchemy 模型 + Pydantic 结构
|
|
|
+├─────────────────────────────────────────────┤
|
|
|
+│ base/ (基础设施层) │ ← MySQL / Redis / Milvus / MinIO 连接
|
|
|
+├─────────────────────────────────────────────┤
|
|
|
+│ core/ (核心框架) │ middleware/ (中间件) │ ← 配置、异常、Token 刷新
|
|
|
+└─────────────────────────────────────────────┘
|
|
|
+```
|
