X-Financial/server/README.md

Server

后端已按 FastAPI + PostgreSQL + SQLAlchemy + Alembic 起好基础工程。

为什么先选 PostgreSQL

这个项目是报销、审批、员工、流程、审计记录为主，核心特点是：

• 强事务
• 多表关联明显
• 审批流和审计日志需要一致性
• 后续大概率要做复杂查询、统计和条件筛选

这类系统优先选关系型数据库更合适，PostgreSQL 是当前默认推荐。

Redis 要不要现在上

现在 不是必须。

先不把 Redis 作为启动前置，原因很直接：

• 当前第一阶段先把核心业务表、接口、权限、审批流跑通
• 如果一开始就把 Redis 绑死，会增加部署和排障复杂度

Redis 更适合后面这些场景：

• 登录态 / token 黑名单
• 热点数据缓存
• 限流
• 分布式锁
• 消息队列 / 后台任务

所以现在的策略是：

• 主数据库：PostgreSQL
• Redis：可选能力，配置已预留，但不是必需依赖

目录

• src/app/：应用代码
• alembic/：数据库迁移
• tests/：测试

启动

1. 创建虚拟环境并安装依赖

cd server
python -m venv .venv
.venv\\Scripts\\activate
pip install -e .[dev]

2. 在项目根目录准备环境变量

copy ..\\.env.example ..\\.env

3. 使用标准入口启动服务

cd ..
./start.sh server

标准入口在启动新的 FastAPI 进程前会自动执行 alembic upgrade head，迁移成功后才会 启动 Uvicorn。./start.sh all 在需要启动后端时也会复用同一流程。不要把直接运行 uvicorn 当作标准启动方式；手工调试 Uvicorn 时，需要先自行完成迁移。

迁移

cd server
alembic -c alembic.ini upgrade head

一次性 PostgreSQL 迁移测试默认跳过，只有显式提供 MIGRATION_TEST_DATABASE_URL 时才会执行。为避免误操作开发库，测试会同时要求主机名 和数据库名使用 migration-probe 或 disposable-probe 安全前缀，并要求数据库初始为空。

cd server
MIGRATION_TEST_DATABASE_URL='postgresql+psycopg://migration_probe:migration_probe_pw@x-financial-migration-probe-123:5432/migration_probe' \
  pytest -q tests/test_alembic_migrations.py

该测试覆盖首次升级、重复升级、关键表/约束/索引、外键级联、降级到 base、无关旧表 及哨兵数据保留，以及再次升级。请只把它指向无持久卷的一次性 PostgreSQL 容器。