fix(docker): manage local postgres in default compose

document/development/2026-07-17/dev-logs/bugs/default-compose-local-postgres-lifecycle.md

@@ -0,0 +1,15 @@
+# 默认 Compose 未统一管理本地 PostgreSQL
+
+日期：2026-07-17
+文档路径：document/development/2026-07-17/dev-logs/bugs/default-compose-local-postgres-lifecycle.md
+
+## 修复记录
+- 22:47：记录 bug 修复：默认 Compose 未统一管理本地 PostgreSQL。（bug-log:787bc3a4）
+  - Git 提交检查：fetch 成功；upstream `origin/main`；upstream 新提交：未发现；本地 ahead 提交：787bc3a4 (HEAD -> main) feat(platform): close AI expense value loop；242d68c3 feat(approval): add task workflow and waiver decisions；28b834ed fix(approval): replay immutable action responses；4940ebc4 feat(approval): add safe risk disposition workflow；ee88a36b feat(ai): add tenant-safe hierarchical expense learning；6bdf65bc feat(expenses): add authoritative pre-review workflow；ae3f02c3 feat(expense): add persistent zero-entry receipt association；54754b55 feat(ai): add personal expense application memory；... 另有 10 条。
+  - 修改：`docker-compose.yml` 将 PostgreSQL、健康依赖、本机端口和持久卷并入默认启动链路；本地数据库插值改用独立的 `LOCAL_POSTGRES_*` 命名空间，避免根 `.env` 的外部数据库账号污染 Compose；`docker-compose.postgres.yml` 保留为空兼容覆盖文件。
+  - 修改：`start.sh` 与 `server_start.sh` 在读取 `.env` 前保存并在读取后恢复完整 PostgreSQL 运行参数，保证 Compose 注入的 host、port、database、user、password 和 URL 始终优先；`test_env_file_precedence.py` 增加根脚本、后端脚本和默认 Compose 回归。
+  - 操作：先将旧库备份到 `/tmp/x-financial-local-pre-compose-20260717.dump`，再把旧卷只读复制到 Compose 管理的 `x-financial_postgres-data`；旧卷未删除。统一本地开发角色凭据后执行 `docker compose up -d`，迁移前置检查从 `unversioned/base` 通过并升级到 `20260717_0028`。
+  - 过程披露：第一次 Compose 重建暴露环境优先级问题时，主容器仍沿用了根 `.env` 指向的外部数据库，并按既有启动流程将其从 `20260716_0006` 升级到 `20260717_0028`；迁移日志无失败，未对外部库执行回滚。修复后已确认当前主容器只连接本地 PostgreSQL 容器。
+  - 验证：容器内定向测试 `107 passed`；Ruff、格式、两个 shell 脚本语法、默认/兼容 Compose 配置和 `git diff --check` 均通过；重复执行 `docker compose up -d` 只保持两个服务运行，没有创建额外容器。
+  - 验证：`main` 与 `postgres` 均为 healthy；前端代理健康接口返回数据库 `ok=true`；应用实际连接 PostgreSQL 容器地址；本地库为 85 张 public 表、105 条员工数据、Alembic head `20260717_0028`，PostgreSQL 日志无 FATAL/ERROR/PANIC。
+  - 影响：以后在仓库根目录执行一次默认 `docker compose up -d` 即可同时启动应用和本地数据库，并复用 Compose 管理的数据卷；外部数据库 `.env` 配置不再悄悄覆盖本地 Compose 连接。