2. 环境搭建：Python虚拟环境、FastAPI框架安装、PostgreSQL数据库配置

在开始《决策日志接口开发》之前，必须搭建一个隔离、可复现的开发环境。本章将依次完成 Python 虚拟环境、FastAPI 框架 以及 PostgreSQL 数据库 的配置，确保后续所有代码和依赖都在受控环境中运行。

2.1 Python 虚拟环境

虚拟环境为每个项目创建独立的 Python 解释器和包依赖空间，避免不同项目间的库版本冲突。推荐使用 Python 3.10+ 内置的 venv 模块。

2.1.1 创建与激活

# 在项目根目录下创建虚拟环境
python -m venv venv

# Windows 激活
venv\Scripts\activate

# macOS / Linux 激活
source venv/bin/activate

激活后，终端提示符前会出现 (venv) 标识，表示当前处于虚拟环境中。

2.1.2 依赖管理

使用 pip 安装包后，通过 requirements.txt 锁定版本，便于团队协作和部署。

# 生成当前环境的依赖清单
pip freeze > requirements.txt

# 在新环境中还原依赖
pip install -r requirements.txt

2.2 FastAPI 框架安装

FastAPI 是一个现代、高性能的 Python Web 框架，基于 Starlette 和 Pydantic，天然支持异步、自动生成 OpenAPI 文档，非常适合构建事件驱动的数据集成接口。

2.2.1 核心依赖安装

# 安装 FastAPI 和 ASGI 服务器
pip install fastapi uvicorn[standard]

# 安装数据库驱动和 ORM（后续章节使用）
pip install sqlalchemy asyncpg psycopg2-binary

包名	版本建议	用途
fastapi	>=0.110.0	Web 框架核心，路由、依赖注入、数据校验
uvicorn	>=0.29.0	ASGI 服务器，运行 FastAPI 应用
sqlalchemy	>=2.0.0	ORM 框架，数据库模型与查询
asyncpg	>=0.29.0	异步 PostgreSQL 驱动，高性能连接

2.2.2 验证安装

# 启动最小化 FastAPI 应用
uvicorn main:app --reload --host 0.0.0.0 --port 8000

访问 http://localhost:8000/docs 看到 Swagger UI 页面即表示安装成功。

2.3 PostgreSQL 数据库配置

PostgreSQL 是供应链控制塔场景的首选关系型数据库，支持 JSONB、窗口函数、事务隔离等高级特性，适合存储事件记录和决策日志。

2.3.1 数据库与用户创建

-- 登录 PostgreSQL
psql -U postgres

-- 创建数据库和专用用户
CREATE DATABASE supply_chain_ct;
CREATE USER scct_user WITH PASSWORD 'Scct@2024!';
GRANT ALL PRIVILEGES ON DATABASE supply_chain_ct TO scct_user;

-- 退出 psql
\q

2.3.2 连接配置

在项目根目录创建 .env 文件，存储数据库连接信息，避免硬编码。

# .env 文件
DATABASE_URL=postgresql+asyncpg://scct_user:Scct@2024!@localhost:5432/supply_chain_ct
DATABASE_SYNC_URL=postgresql+psycopg2://scct_user:Scct@2024!@localhost:5432/supply_chain_ct

2.3.3 连接测试

# test_connection.py
import asyncio
from sqlalchemy.ext.asyncio import create_async_engine

async def test():
    engine = create_async_engine("postgresql+asyncpg://scct_user:Scct@2024!@localhost:5432/supply_chain_ct")
    async with engine.connect() as conn:
        result = await conn.execute("SELECT version();")
        print(result.fetchone())
    await engine.dispose()

asyncio.run(test())

执行后输出 PostgreSQL 版本号即表示连接成功。

2.4 环境架构总览

下图展示了开发环境中各组件之间的调用关系与数据流向：

2.5 环境验证清单

完成上述步骤后，使用下表逐项确认环境就绪：

检查项	验证方法	预期结果
虚拟环境激活	终端输入 which python 或 where python	路径指向项目下的 venv/bin/python
FastAPI 安装	pip show fastapi	显示版本号 ≥ 0.110.0
Uvicorn 启动	uvicorn main:app --reload	控制台输出 Uvicorn running on http://127.0.0.1:8000
PostgreSQL 连接	运行 test_connection.py	打印 PostgreSQL 版本号
依赖锁定	pip freeze > requirements.txt	文件包含所有已安装包及其版本

至此，开发环境搭建完毕。下一阶段将基于此环境，开始设计事件记录的数据模型与决策日志的数据库表结构。