优化

docs/OPERATIONS.md

@@ -12,6 +12,7 @@
 - **Compose 运行**：compose 文件用 `${VAR}` 从同目录 `.env` 注入容器环境变量（见 [docker-compose.yml](../docker-compose.yml)）。
 - **键值约定**：
   - `DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD`：**惰性校验、无代码默认**——缺失时 import 不报错（便于测试/静态分析），真正连库时才失败。生产必须显式配置。
+  - `AUTO_MIGRATE`：应用启动时是否自动执行 alembic 迁移，默认 `true`（单机开发语义）；**多副本 / 容器编排部署应设 `false`**，改由部署流程单点执行 `alembic upgrade head` 或 `python -m shared.database.init_db`（迁移脚本已随镜像分发于 `/app/migrations/`）。
   - `SECRET_KEY`：JWT 签名密钥，**无默认**；生产必须 ≥32 字符强随机。
   - `ADMIN_PASSWORD`：初始管理员密码，**无默认**；首次建库前必须设置。
   - `RUSTFS_*`：对象存储（兼容 `MINIO_*` 别名写法）；本地开发缺省值仅为占位，连不上会在用到存储的链路报错。
@@ -26,7 +27,7 @@
 - 后端依赖：`pip install -r requirements.txt`。
 - **OCC 几何能力**：PythonOCC 不走 pip 主路径，通过 conda 环境提供（本项目实践环境名 `gemold`）。无 OCC 环境时项目可启动，但几何分析契约测试自动 skip。
 - 前端：`cd frontend && npm install`。
-- 数据库迁移：`alembic/`（`alembic.ini` 在仓库根）；数据修复类一次性脚本在 `scripts/migrations/` 与 `scripts/db/`，**不是运行时代码**，勿在服务内引用。
+- 数据库迁移：`migrations/`（`alembic.ini` 在仓库根；2026-09-16 由 `alembic/` 改名——原目录名与 alembic 包重名，应用内 import 会被遮蔽导致启动期迁移静默失败）；数据修复类一次性脚本在 `scripts/migrations/` 与 `scripts/db/`，**不是运行时代码**，勿在服务内引用。
 
 ## 3. 本地启动