docs: 增加 ADR-008 将 PostgreSQL 版本基线定为 18

- 零数据窗口期定版:与本机开发库 18.6 对齐,Testcontainers/编排/交付统一 postgres:18
- 切换当日 37 测试于 postgres:18 全绿,Flyway V1 兼容
- 同步开发计划 5.1/M0/CI 门禁与进展看板的版本表述
- 门禁:mkdocs build --strict 通过
This commit is contained in:
2026-09-04 11:33:58 +08:00
parent b747e09af8
commit 18746ce6fc
3 changed files with 19 additions and 5 deletions
+15 -1
View File
@@ -66,7 +66,7 @@
**决策**2026-09-04):
- 自动化测试中的数据库一律通过 Testcontainers 使用 Docker 临时容器(`postgres:16`),不依赖开发者本机数据库;每次测试在干净实例上执行全量 Flyway 迁移。
- 自动化测试中的数据库一律通过 Testcontainers 使用 Docker 临时容器(`postgres:18`,版本基线见 ADR-008),不依赖开发者本机数据库;每次测试在干净实例上执行全量 Flyway 迁移。
- 最终交付将提供 Docker 镜像/编排包(对应开发计划 M6 的容器镜像项)。
- 开发者本人手动测试/联调时可使用自己本机的 PostgreSQL,连接信息经环境变量注入,不入库。
@@ -84,3 +84,17 @@
**理由**:双人团队运维预算有限,容器数据库 + volume + 备份在 MVP 阶段完全够用,且与 Testcontainers 测试、Docker 交付包(ADR-006)同一体系;把高可用、故障转移等重运维在需要时外包给云托管,是成本与可靠性的最优路径。守住「应用无状态」这一条纪律,数据库放哪都可随时更换。
**注意**:数据库大版本升级即使在 Docker 中也需要数据迁移(`pg_upgrade` 或 dump/restore),属 ADR 级决策,不随镜像标签随意变更;小版本安全更新随镜像自动跟进。
## ADR-008 PostgreSQL 版本基线定为 18
**决策**(2026-09-04):数据库版本基线从开发计划最初的「PostgreSQL 16+」明确定为 **PostgreSQL 18**。Testcontainers 测试镜像、未来的 compose 编排与交付镜像统一锁 `postgres:18`
**理由**
- 项目尚无生产数据,大版本选择处于零成本窗口;一旦有数据,大版本升级即为一次真实迁移(见 ADR-007 注意事项)。
- PostgreSQL 18 已是发布满一年的稳定版本,与团队本机开发库(18.6)一致,消除本机与基线的版本偏差。
- 不违背开发计划「16+」的原始约束。
**验证**:切换当日 `./mvnw clean test` 全量 37 测试在 postgres:1818.6)容器上通过,Flyway V1 baseline 迁移执行无兼容问题。
**影响**:后续大版本变更须以新 ADR 决策并附全量测试验证;数据库特性使用以 18 为可用上限参考。
+3 -3
View File
@@ -116,7 +116,7 @@ Page/Widget -> Feature Controller -> Repository -> API Client
- JDK 17。不要使用更高版本 JDK 代替团队基线进行发布构建。
- Maven 3.9+M0 完成后改用仓库内 Maven Wrapper。
- PostgreSQL 16+,现有本地库作为开发数据源。
- PostgreSQL 18(版本基线见 ADR-008,现有本地库作为开发数据源。
- Nacos,供当前 `patbond-auth` 发现 `patbond-user`
- Flutter/Dart 版本需满足 `patbond-flutter/pubspec.yaml`M0 完成后通过版本管理工具锁定。
@@ -199,7 +199,7 @@ NACOS_SERVER_ADDR=127.0.0.1:8848
目标:让所有开发者能用一致方式启动、测试和联调。
- 确认 Java 17、Flutter SDK、PostgreSQL 16 的固定版本。
- 确认 Java 17、Flutter SDK、PostgreSQL 18 的固定版本。
- 增加 Maven Wrapper 和 Flutter 版本固定方案。
- 提供可提交的 `application.yml` 默认配置,敏感值全部由环境变量注入。
- 增加本地基础设施编排:PostgreSQL、NacosRabbitMQ 在异步任务阶段启用。
@@ -322,7 +322,7 @@ flutter test
mkdocs build --strict
```
数据库迁移还需在全新 PostgreSQL 16 实例执行一次,并对升级路径执行一次。
数据库迁移还需在全新 PostgreSQL 18 实例执行一次,并对升级路径执行一次。
### 可观测性与产品验证
@@ -36,7 +36,7 @@
## 环境与构建(新成员必读)
- 后端构建:`JAVA_HOME=/usr/lib/jvm/java-17-openjdk ./mvnw clean test`(本机默认 JDK 版本过高,必须显式指 17;需 Docker 供 Testcontainers 起 postgres:16)。
- 后端构建:`JAVA_HOME=/usr/lib/jvm/java-17-openjdk ./mvnw clean test`(本机默认 JDK 版本过高,必须显式指 17;需 Docker 供 Testcontainers 起 postgres:18,见 ADR-008)。
- Flutter 门禁:`dart format --output=none --set-exit-if-changed lib test` / `flutter analyze` / `flutter test`
- 文档门禁:`mkdocs build --strict`
- 测试数据库策略见 ADR-006:自动化测试一律 Testcontainers,个人手动联调用本机 PostgreSQL(环境变量注入连接信息)。