init: 初始化 dpb 桃育种系统代码库

前后端 + 后端 FastAPI 全量源码、部署脚本与文档。
2026-08-06 00:17:49 +08:00
commit b95053c52c
1469 changed files with 322298 additions and 0 deletions
@@ -0,0 +1,70 @@
+# breeding 迁移机制
+
+breeding 模块无 alembic 基线（表由 `create_all` 创建），直接 `alembic revision --autogenerate`
+会试图重建全部表、风险高。故所有结构/数据变更统一走**幂等迁移脚本**：每支脚本可重复执行，
+重复运行不产生副作用，单支失败不影响其余。
+
+## 统一入口：run_migrations.py
+
+按依赖顺序执行整套迁移，并依据数据库方言（`settings.DATABASE_TYPE`）自动跳过不支持的脚本：
+
+| 脚本 | 作用 | PostgreSQL |
+|---|---|---|
+| fix_breeding_columns.py | ORM 与库列补齐（生成器改字段后同步） | ✔ |
+| schema_align.py | 审计列统一新契约（uuid/is_deleted bool/审计 FK） | ✔ |
+| align_columns.py | 业务必填列 NOT NULL 对齐（无 NULL 才收紧） | ✔ |
+| add_unique_constraints.py | 业务唯一约束落库（部分唯一索引，未软删） | ✔ |
+| migrate_dict_english.py | 字典存量中文 label → 英码 value | ✔ |
+
+说明：
+- 生产仅使用 PostgreSQL；PostgreSQL 专属语法（部分唯一索引 `WHERE is_deleted = false`、
+  `gen_random_uuid()` 等）在非 postgres 方言下自动跳过并提示。
+- 每支脚本均幂等；`--check` 仅对声明支持的脚本生效，不支持的（schema_align.py）在预览模式下跳过。
+
+### 本地开发（Windows，conda `dpb`）
+
+```powershell
+cd backend
+$env:ENVIRONMENT = "dev"
+uv run python scripts/run_migrations.py --check   # 预览
+uv run python scripts/run_migrations.py            # 执行
+```
+（无 uv 时可用 conda 环境的 `python` 替代 `uv run python`。）
+
+### Docker 部署
+
+```bash
+cd docker
+docker compose exec -T backend python /home/scripts/run_migrations.py
+```
+或直接 `deploy.sh migrate`（已接此入口）。容器内挂载 backend 代码到 `/home`，
+`ENVIRONMENT` 由 compose 注入（prod 默认 postgres，runner 自动只跑适用迁移）。
+
+## 单支脚本用法
+
+每支脚本同样支持单独执行/预览：
+
+```powershell
+uv run python scripts/fix_breeding_columns.py --check      # 仅预览 DDL，不落库
+uv run python scripts/fix_breeding_columns.py              # 执行补齐
+uv run python scripts/schema_align.py                      # 审计列统一（幂等）
+uv run python scripts/add_unique_constraints.py --check    # 唯一约束预览
+uv run python scripts/add_unique_constraints.py            # 执行
+uv run python scripts/migrate_dict_english.py --check      # 字典迁移预览
+uv run python scripts/migrate_dict_english.py              # 执行（自动备份 bre_backup_*）
+```
+
+## 连接串来源
+
+各脚本读取 `app.config.setting.settings.DB_URI / ASYNC_DB_URI`（与后端运行时一致），无需手动配置。
+
+## 输出示例
+
+```
+[run_migrations] 数据库方言: postgres  模式: 执行
+[run_migrations] 执行 fix_breeding_columns.py ...
+[run_migrations] 执行 schema_align.py ...
+[run_migrations] 执行 add_unique_constraints.py ...
+[run_migrations] 执行 migrate_dict_english.py ...
+[run_migrations] 全部迁移完成
+```