91 lines
2.4 KiB
Markdown
91 lines
2.4 KiB
Markdown
# Server
|
||
|
||
后端已按 `FastAPI + PostgreSQL + SQLAlchemy + Alembic` 起好基础工程。
|
||
|
||
## 为什么先选 PostgreSQL
|
||
|
||
这个项目是报销、审批、员工、流程、审计记录为主，核心特点是：
|
||
|
||
- 强事务
|
||
- 多表关联明显
|
||
- 审批流和审计日志需要一致性
|
||
- 后续大概率要做复杂查询、统计和条件筛选
|
||
|
||
这类系统优先选关系型数据库更合适，`PostgreSQL` 是当前默认推荐。
|
||
|
||
## Redis 要不要现在上
|
||
|
||
现在 **不是必须**。
|
||
|
||
先不把 Redis 作为启动前置，原因很直接：
|
||
|
||
- 当前第一阶段先把核心业务表、接口、权限、审批流跑通
|
||
- 如果一开始就把 Redis 绑死，会增加部署和排障复杂度
|
||
|
||
Redis 更适合后面这些场景：
|
||
|
||
- 登录态 / token 黑名单
|
||
- 热点数据缓存
|
||
- 限流
|
||
- 分布式锁
|
||
- 消息队列 / 后台任务
|
||
|
||
所以现在的策略是：
|
||
|
||
- 主数据库：`PostgreSQL`
|
||
- Redis：`可选能力`，配置已预留，但不是必需依赖
|
||
|
||
## 目录
|
||
|
||
- `src/app/`：应用代码
|
||
- `alembic/`：数据库迁移
|
||
- `tests/`：测试
|
||
|
||
## 启动
|
||
|
||
1. 创建虚拟环境并安装依赖
|
||
|
||
```bash
|
||
cd server
|
||
python -m venv .venv
|
||
.venv\\Scripts\\activate
|
||
pip install -e .[dev]
|
||
```
|
||
|
||
2. 在项目根目录准备环境变量
|
||
|
||
```bash
|
||
copy ..\\.env.example ..\\.env
|
||
```
|
||
|
||
3. 使用标准入口启动服务
|
||
|
||
```bash
|
||
cd ..
|
||
./start.sh server
|
||
```
|
||
|
||
标准入口在启动新的 FastAPI 进程前会自动执行 `alembic upgrade head`，迁移成功后才会
|
||
启动 Uvicorn。`./start.sh all` 在需要启动后端时也会复用同一流程。不要把直接运行
|
||
`uvicorn` 当作标准启动方式；手工调试 Uvicorn 时，需要先自行完成迁移。
|
||
|
||
## 迁移
|
||
|
||
```bash
|
||
cd server
|
||
alembic -c alembic.ini upgrade head
|
||
```
|
||
|
||
一次性 PostgreSQL 迁移测试默认跳过，只有显式提供
|
||
`MIGRATION_TEST_DATABASE_URL` 时才会执行。为避免误操作开发库，测试会同时要求主机名
|
||
和数据库名使用 `migration-probe` 或 `disposable-probe` 安全前缀，并要求数据库初始为空。
|
||
|
||
```bash
|
||
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 容器。
|