说明文件

README.md

@@ -0,0 +1,190 @@
+# PBMDB 后端服务
+
+## 项目概述
+
+PBMDB（微生物数据库）后端服务基于 FastAPI 框架构建，提供 RESTful API 接口，用于支撑前端数据提交系统的核心业务逻辑。后端服务采用 PostgreSQL 数据库存储用户信息和操作记录，通过白名单机制控制数据提交权限，确保只有授权用户才能进行数据操作。
+
+## 技术栈
+
+- **编程语言**：Python 3.10+
+- **Web 框架**：FastAPI
+- **ASGI 服务器**：Uvicorn
+- **数据库**：PostgreSQL
+- **ORM 框架**：SQLAlchemy
+- **时区处理**：Pytz
+
+## 项目结构
+
+```
+backend/
+├── app/
+│   ├── __pycache__/           # Python 缓存文件目录
+│   ├── api/                   # API 路由模块
+│   │   ├── __pycache__/       # 缓存文件目录
+│   │   ├── db.py              # 数据库连接和会话管理
+│   │   ├── login.py           # 登录验证相关接口
+│   │   └── submit_record.py   # 提交记录相关接口
+│   ├── main.py                # FastAPI 应用主入口
+│   ├── settings.py            # 配置文件
+│   ├── base_packages.txt      # 基础依赖包列表
+│   └── requirements.txt       # Python 依赖包列表
+├── environment.yml            # Conda 环境配置文件
+└── start_server.py            # 服务启动脚本
+```
+
+## 核心模块详解
+
+### 1. 应用入口（main.py）
+
+main.py 是整个后端应用的入口文件，负责初始化 FastAPI 应用实例并配置中间件和路由。应用在启动时会自动创建数据库表结构，确保所有必要的表和字段都已存在。该模块还配置了 CORS（跨源资源共享）中间件，允许前端应用跨域调用 API 接口。路由模块通过前缀 `/api/v1` 组织所有 API 端点，这种设计方式便于后期版本升级和接口扩展。
+
+### 2. 配置模块（settings.py）
+
+settings.py 集中管理后端服务的所有配置信息。数据库连接字符串采用标准的 PostgreSQL 格式，包含主机地址、端口、数据库名称以及认证凭据。白名单配置指定了用于验证用户邮箱的数据表和字段名称，确保只有特定的用户群体能够访问数据提交功能。提交记录表名配置用于记录用户的操作历史，包括上传和删除操作的时间、类型和存储路径。这些配置信息统一管理，便于在不同环境（开发、测试、生产）之间切换。
+
+### 3. 数据库模块（db.py）
+
+db.py 封装了所有与数据库交互的底层逻辑。SQLAlchemy 引擎负责建立与 PostgreSQL 数据库的连接池，连接池技术能够有效管理数据库连接资源，提高并发访问性能。会话工厂 SessionLocal 创建独立的数据库会话，每个请求使用独立的会话对象，确保数据操作的隔离性和线程安全。get_db 是一个生成器函数，作为 FastAPI 的依赖项注入到各个路由处理函数中，自动管理数据库会话的创建和关闭，避免资源泄漏。
+
+### 4. 登录验证模块（login.py）
+
+login.py 实现了用户邮箱白名单验证功能，是数据提交系统的第一道安全屏障。当用户尝试访问数据提交功能时，系统会调用 `/api/v1/check-email` 接口验证用户邮箱是否在白名单中。该接口从 PostgreSQL 数据库的指定表中查询用户邮箱记录，如果邮箱存在于白名单中，则允许用户继续操作；否则返回 403 错误，拒绝用户请求。这种设计确保了数据提交权限的严格控制，只有经过授权的用户才能使用系统功能。
+
+### 5. 提交记录模块（submit_record.py）
+
+submit_record.py 负责记录用户在系统中的所有数据操作行为，包括数据上传和数据删除两类操作。每当用户执行这些操作时，系统会调用 `/api/v1/submit-record` 接口，将操作信息持久化存储到数据库中。记录内容包括用户邮箱、操作时间、操作类型和数据存储路径。操作时间采用中国时区（Asia/Shanghai）记录，确保时间信息的准确性和一致性。所有操作记录都存储在专用的提交记录表中，便于后续审计追溯和数据管理。系统通过事务机制确保记录插入的原子性，任何失败的操作都会触发回滚，保证数据完整性。
+
+## API 接口文档
+
+### 基础信息
+
+- **基础路径**：`/api/v1`
+- **数据格式**：JSON
+- **字符编码**：UTF-8
+
+### 接口列表
+
+#### 1. 邮箱白名单验证
+
+- **端点**：`POST /api/v1/check-email`
+- **功能描述**：检查用户邮箱是否在白名单中
+- **请求体**：
+  ```json
+  {
+    "email": "user@example.com"
+  }
+  ```
+- **成功响应**：
+  ```json
+  {
+    "status": "success",
+    "message": "继续操作"
+  }
+  ```
+- **错误响应**：
+  ```json
+  {
+    "detail": "邮箱不在白名单中，请联系管理员"
+  }
+  ```
+
+#### 2. 提交操作记录
+
+- **端点**：`POST /api/v1/submit-record`
+- **功能描述**：记录用户的数据上传或删除操作
+- **请求体**：
+  ```json
+  {
+    "user_email": "user@example.com",
+    "operation_type": "upload",
+    "storage_path": "/data/user/example/"
+  }
+  ```
+- **成功响应**：
+  ```json
+  {
+    "status": "success",
+    "message": "操作记录已保存"
+  }
+  ```
+- **错误响应**：
+  ```json
+  {
+    "detail": "操作类型必须是 'upload' 或 'delete'"
+  }
+  ```
+
+## 工作流程
+
+### 数据提交流程
+
+用户访问数据提交页面时，前端首先调用邮箱验证接口确认用户身份。系统查询数据库中的白名单表，验证用户邮箱是否具有提交权限。验证通过后，用户可以上传数据文件，上传完成后前端调用提交记录接口将操作信息写入数据库。整个流程采用同步方式处理，每个步骤的结果都会实时反馈给用户，确保操作的可控性和可追溯性。
+
+### 权限控制机制
+
+权限控制采用白名单模式实现，所有能够访问数据提交功能的用户邮箱必须预先录入系统数据库。白名单验证在用户首次访问提交页面时触发，通过后即可进行后续操作。这种设计简化了权限管理的复杂度，同时保证了数据访问的安全性。白名单数据存储在专用的数据库表中，管理员可以通过直接操作数据库的方式管理用户权限。
+
+### 操作审计机制
+
+系统自动记录所有数据操作行为，包括上传和删除两类操作。每条记录包含操作者的邮箱地址、操作发生的时间戳、操作的具体类型以及相关数据的存储位置。时间戳采用中国标准时间，确保审计日志的时间信息与实际业务操作一致。所有操作记录持久化存储到 PostgreSQL 数据库中，支持按时间范围、用户邮箱、操作类型等条件进行查询和筛选，便于事后审计和问题追溯。
+
+## 数据库配置
+
+### 连接信息
+
+当前数据库配置指向远程 PostgreSQL 服务器，连接信息如下：
+
+- **主机**：`122.205.95.244`
+- **端口**：`5433`
+- **数据库名称**：`ABM_DB`
+- **用户名**：`ABM_DB_user`
+- **密码**：`4FynWQfy0AEotP1dgyimrGF7PSDJh1nDYnDwg4hN`
+
+### 数据表结构
+
+系统依赖以下核心数据表：
+
+- **submit_user**：存储允许访问系统的用户邮箱白名单
+- **submit_record**：存储用户的数据操作记录，包括操作时间、类型和存储路径
+
+## 环境配置
+
+### Conda 环境
+
+使用 Conda 管理 Python 环境，可以通过 environment.yml 文件创建相同的运行环境：
+
+```bash
+conda env create -f environment.yml
+conda activate pbmdb_backend
+```
+
+### 依赖安装
+
+如果使用 pip 安装依赖，可以执行以下命令：
+
+```bash
+pip install -r app/requirements.txt
+```
+
+## 启动服务
+
+### 开发模式启动
+
+```bash
+cd backend
+python start_server.py
+```
+
+服务启动后，默认监听 `0.0.0.0:8000` 端口。开发模式下启用热重载功能，代码修改后服务会自动重启。
+
+### 生产模式启动
+
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+生产模式下建议关闭热重载，并配置进程管理器（如 systemd）管理服务生命周期。
+
+## 安全建议
+
+当前配置中存在一些安全隐患，需要在生产环境中进行加固。首先，数据库连接信息直接硬编码在配置文件中，建议使用环境变量或加密配置文件管理敏感信息。其次，CORS 配置允许所有来源的跨域请求，生产环境应该限制为前端应用的特定域名。此外，数据库账号密码等敏感凭据不应暴露在版本控制系统中，应通过安全的密钥管理方案进行管理。