# 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 连接、认证体系） |