LQMDRetrieval 项目结构说明
1. 项目概述
LQMDRetrieval 是一个多维度文档检索应用端，提供基于文档类型、发布日期、发布部门、关键词的多维度检索能力。检索引擎直接调用外部检索接口，实现在精准查询的同时支持文档在线预览。
| 功能域 |
说明 |
| 多维检索 |
按文档类型、发布日期、部门、关键词四维组合筛选与检索（调用外部接口） |
| 文档预览 |
通过文件 UUID 读取 OSS 源文件，实现在线预览展示（调用外部接口） |
| 分页与排序 |
支持检索结果分页展示与多维度排序管理（调用外部接口） |
| 数据统计 |
统计检索结果文档总量，展示数据概览（调用外部接口） |
2. 技术栈
| 类别 |
技术 |
| 语言 |
Python 3.12 |
| Web 框架 |
FastAPI 0.104 + Uvicorn 0.24 |
| ORM |
SQLAlchemy 2.0（异步） |
| 主数据库 |
MySQL（aiomysql） |
| 缓存 |
Redis（aioredis） |
| 搜索引擎 |
调用外部检索接口 |
| 认证 |
python-jose (JWT) + passlib + bcrypt |
| 数据校验 |
Pydantic 2.x |
| 容器化 |
Docker + Docker Compose |
| 前端框架 |
Vue 3 + Vite + Element Plus |
| 路由 |
Vue Router 4 |
| PDF 预览 |
PDF.js |
3. 顶层目录结构
LQMDRetrieval/
├── backend/ # 后端项目（FastAPI）
│ ├── requirements/ # Python 依赖管理
│ │ ├── base.txt # 生产依赖
│ │ └── requirements.txt # 完整依赖
│ ├── docker/ # Docker Compose 编排
│ │ ├── docker-compose.yml
│ │ ── nginx/
│ ├── run.sh # 服务管理脚本
│ ├── run_server.py # Python 入口
│ ├── Dockerfile
│ ├── src/ # 后端源代码
│ └── .gitignore
│
├── web/ # 前端项目（Vue 3）
│ ├── src/
│ ├── index.html
│ ├── package.json
│ ├── vite.config.ts
│ ├── tsconfig.json
│ └── .gitignore
│
├── docker/ # 顶层 Docker 编排（前后端统一启动）
│ └── docker-compose.yml
│
├── 项目/ # 设计文档、API 接口定义、需求文档
│
├── README.md
└── .gitignore
4. 后端源代码目录结构（backend/src/）
backend/src/
├── path_config.py # 自动配置 Python 导入路径
│
── app/
├── server/ # FastAPI 应用工厂 & 入口
│ ── app.py # 主 FastAPI 实例：中间件、CORS、异常处理、路由注册
│
├── base/ # 基础设施 / 连接管理
│ ├── async_mysql_connection.py # SQLAlchemy 异步 MySQL 连接
│ └── async_redis_connection.py # Redis 连接
│
├── core/ # 核心框架代码
│ ├── config.py # ConfigHandler — 全局配置解析
│ └── exceptions.py # 自定义异常 BaseAPIException
│
├── middleware/ # HTTP 中间件
│ └── token_refresh_middleware.py # JWT Token 自动刷新中间件
│
├── models/ # 通用 SQLAlchemy 模型
│ └── base.py # 基础模型类
│
├── schemas/ # 基础 Pydantic 响应结构
│ └── base.py # ResponseSchema / PaginationSchema
│
├── utils/ # 工具函数
│ ├── auth_dependency.py # 认证依赖注入
│ └── security.py # 安全工具（密码哈希、Token 生成）
│
├── services/ # 业务逻辑层
│ ├── auth_service.py # 用户登录认证
│ ├── jwt_token.py # JWT Token 管理
│ └── retrieval_service.py # 多维检索服务（调用外部接口）
│
├── retrieval/ # 【多维检索模块】
│ ├── models/ # 检索相关 SQLAlchemy 模型
│ │ └── search_history.py # 搜索历史模型（暂保留）
│ └── schemas/
│
── auth/ # 【授权管理模块】
├── models/ # 认证 SQLAlchemy 模型
│ └── user.py # 用户模型
└── schemas/ # 认证 Pydantic 结构
└── auth_schema.py
├── views/ # HTTP 路由定义（API 端点）
│ ├── auth_view.py # 认证路由（登录、Token 刷新）
│ └── retrieval_view.py # 多维检索路由（核心接口）
│
└── api/ # 对外 API 定义（v1 版本）
└── v1/
└── retrieval/ # 检索对外 API
5. 前端项目结构（web/）
web/
├── src/
│ ├── main.ts # 应用入口
│ ├── App.vue # 根组件
│ ├── router/ # 路由配置
│ │ └── index.ts
│ ├── api/ # API 请求（按模块划分）
│ │ ├── auth.ts # 认证 API
│ │ └── retrieval.ts # 检索 API
│ ├── components/ # 可复用组件
│ │ ├── SearchBar.vue # 搜索栏组件
│ │ ├── FilterPanel.vue # 筛选面板组件
│ │ ├── ResultCard.vue # 结果卡片组件
│ │ ├── Pagination.vue # 分页组件
│ │ ├── SortDropdown.vue # 排序下拉组件
│ │ └── StatsOverview.vue # 统计概览组件
│ ├── layouts/ # 布局组件
│ │ └── DefaultLayout.vue
│ ├── views/ # 页面视图
│ │ ├── SearchPage.vue # 检索主页
│ │ └── Auth/
│ │ ├── Login.vue # 登录页
│ │ └── OAuthCallback.vue # SSO 回调页
│ ├── utils/ # 工具函数
│ │ ├── request.ts # Fetch 封装
│ │ └── helpers.ts
│ ── styles/ # 全局样式
│ └── index.css
│
├── index.html
├── package.json
├── vite.config.ts
├── tsconfig.json
└── .gitignore
6. 功能模块详细说明
6.1 多维检索（retrieval/）— 调用外部接口
| 子功能 |
说明 |
| 按文档类型检索 |
根据文档类型进行筛选（法规制度、技术标准、操作指南、通知公告、工作报告等） |
| 按发布日期检索 |
根据发布时间进行范围筛选 |
| 按部门检索 |
根据发布部门进行筛选（工程管理部、安全管理部、财务部、采购部、人力资源部） |
| 按关键词检索 |
调用外部检索接口，实现精准查询 |
| 多维组合检索 |
支持上述维度任意组合，实现交叉筛选 |
6.2 文档预览（preview/）— 调用外部接口
| 子功能 |
说明 |
| 在线预览 |
通过文件 UUID 从 OSS 读取源文件，实现在线预览展示 |
| PDF 预览 |
支持 PDF 文档在线渲染，包含放大、缩小、旋转、打印功能 |
| 分页导航 |
预览面板支持文档页码跳转与缩略图导航 |
6.3 分页与排序 — 调用外部接口
| 子功能 |
说明 |
| 分页展示 |
支持检索结果分页（默认每页 20 条） |
| 多维度排序 |
支持按相关性、发布时间、浏览量等多维度排序 |
6.4 数据统计 — 调用外部接口
| 子功能 |
说明 |
| 结果总量统计 |
统计当前检索条件下匹配的文档总量 |
| 数据概览 |
按文档类型、发布部门、时间维度展示统计概览 |
7. 关键文件说明
| 文件 |
作用 |
backend/src/app/server/app.py |
FastAPI 应用实例，负责中间件、CORS、异常处理、路由注册 |
backend/src/app/core/config.py |
全局配置读取（数据库连接、外部接口地址等） |
backend/src/app/base/async_mysql_connection.py |
异步 MySQL 连接池管理 |
backend/src/app/base/async_redis_connection.py |
Redis 连接池管理 |
backend/src/app/services/retrieval_service.py |
多维检索服务：调用外部检索接口 |
backend/src/app/services/auth_service.py |
用户登录认证服务 |
backend/src/app/services/jwt_token.py |
JWT Token 管理 |
backend/src/app/middleware/token_refresh_middleware.py |
Token 自动刷新中间件 |
backend/run_server.py |
应用启动入口，uvicorn 启动器 |
backend/run.sh |
Shell 服务管理脚本 |
8. 数据流向
客户端请求
↓
Nginx 反向代理
↓
FastAPI (uvicorn :8000)
↓
middleware/token_refresh_middleware.py（Token 刷新）
↓
views/retrieval_view.py（检索路由匹配）
↓
services/retrieval_service.py（调用外部检索接口）
↓
MySQL（本地用户数据存储）
Redis（缓存 / Session）
9. 核心检索流程
用户输入关键词 + 筛选条件
↓
retrieval_service.py 转发请求到外部检索接口
↓
外部接口返回检索结果
↓
返回分页结果给前端
10. 项目架构分层
┌─────────────────────────────────────────────
│ views/ (路由层) │ ← HTTP 端点定义，按功能划分
├─────────────────────────────────────────────┤
│ services/ (业务逻辑层) │ ← 检索转发、认证业务规则
├─────────────────────────────────────────────┤
│ retrieval/ (检索模块) │ auth/ (认证模块) │ ← 按功能域划分的 models + schemas
├─────────────────────────────────────────────┤
│ utils/ (工具层) │ ← 认证依赖、安全工具
├─────────────────────────────────────────────┤
│ base/ (基础设施层) │ ← MySQL / Redis 连接
├─────────────────────────────────────────────┤
│ core/ (核心框架) │ middleware/ (中间件) │ ← 配置、异常、Token 刷新
└─────────────────────────────────────────────
11. 前端页面结构
┌─────────────────────────────────────────────────┐
│ Header │ ← Logo + 多维度检索标题
─────────────────────────────────────────────────┤
│ ┌───────────────────────────────────────────┐ │
│ │ SearchBar │ │ ← 搜索输入框 + 搜索按钮
│ └───────────────────────────────────────────┘ │
─────────────────────────────────────────────────┤
│ ┌───────────────────────────────────────────┐ │
│ │ FilterPanel │ │ ← 文档类型/日期/部门/关键词筛选
│ │ - 文档类型标签（全部/法规/标准/指南...） │ │
│ │ - 发布日期范围选择器 │ │
│ │ - 发布部门标签（全部/工程/安全/财务...） │ │
│ │ - 精准关键词输入 │ │
│ └───────────────────────────────────────────┘ │
├─────────────────────────────────────────────────┤
│ ──────────────┐ ┌──────────────────────────┐ │
│ │ StatsOverview│ │ Sort & Pagination │ │ ← 统计概览 + 排序/分页
│ │ (找到 N 个文档)│ │ 相关性排序 / 时间排序 │ │
│ └──────────────┘ └──────────────────────────┘ │
─────────────────────────────────────────────────┤
│ ───────────────────────────────────────────┐ │
│ │ ResultCard (列表) │ │ ← 检索结果卡片列表
│ │ - 文档标题 │ │
│ │ - 类型/部门/日期/浏览量 │ │
│ │ - 摘要（关键词高亮） │ │
│ │ - 标签 │ │
│ │ - 操作：文档预览 / 下载 │ │
│ └───────────────────────────────────────────┘ │
─────────────────────────────────────────────────┘
文档预览弹窗（侧边抽屉）:
┌─────────────────────────────────────────────────┐
│ PDF 标题 + 操作栏（放大/缩小/旋转/打印） │
├─────────────────────────────────────────────────┤
│ ──────────────────────────────────────────┐ │
│ │ PDF.js 渲染区域 │ │ ← PDF 文档在线预览
│ │ (支持翻页、缩放) │ │
│ └───────────────────────────────────────────┘ │
├─────────────────────────────────────────────────┤
│ 下载按钮 │
└─────────────────────────────────────────────────┘
12. 数据库设计概要
12.1 搜索历史表（t_doc_search_history）
| 字段 |
类型 |
说明 |
| id |
BIGINT |
主键 |
| user_id |
BIGINT |
用户 ID |
| keywords |
VARCHAR(255) |
搜索关键词 |
| filters |
JSON |
筛选条件快照 |
| result_count |
INT |
结果数量 |
| created_at |
DATETIME |
搜索时间 |
13. 与 LQAdminPlatform 的关系
| 维度 |
LQAdminPlatform |
LQMDRetrieval |
| 定位 |
综合管理平台（系统管理+SSO+样本中心） |
专用检索应用端 |
| 检索能力 |
样本中心内嵌语义检索 |
调用外部检索接口 |
| 文档预览 |
样本中心文档管理 |
调用外部预览接口 |
| 前端 |
Vue 3 + Element Plus 管理后台 |
Vue 3 + Element Plus 检索应用 |
| 后端架构 |
多模块（system/oauth/sample） |
双模块（retrieval/auth） |
| 技术复用 |
- |
复用 LQAdminPlatform 的基础设施层（MySQL/Redis 连接、认证体系） |
