lixi
18746ce6fc
- 零数据窗口期定版：与本机开发库 18.6 对齐，Testcontainers/编排/交付统一 postgres:18 - 切换当日 37 测试于 postgres:18 全绿，Flyway V1 兼容 - 同步开发计划 5.1/M0/CI 门禁与进展看板的版本表述 - 门禁：mkdocs build --strict 通过
101 lines
6.6 KiB
Markdown
101 lines
6.6 KiB
Markdown
# 架构与技术决策记录（ADR）
|
||
|
||
> 状态：Accepted
|
||
> 决策日期：2026-09-03
|
||
> 决策人：产品负责人
|
||
> 背景：项目正式启动第一版（第一迭代「真实登录纵切」），基于 `iteration-1-reports/` 六份开工前分析报告确认以下决策。
|
||
|
||
## ADR-001 升级 Spring Boot 3 后再开发业务代码
|
||
|
||
**决策**：在编写第一迭代业务代码之前，先将 `patbond-api` 从 Spring Boot 2.7 升级到 Spring Boot 3（JDK 17 基线），升级工作时间盒为 1-2 天。
|
||
|
||
**理由**：
|
||
|
||
- 当前业务代码不足 10 个类，迁移成本处于历史最低点；随业务增长成本只会上升。
|
||
- 本迭代要新引入的 JWT、Flyway（PostgreSQL 16+）、Testcontainers、springdoc 在 Boot 2.7 下均为降级选型，按 2.7 编写等于主动制造返工。
|
||
- Spring Boot 2.7 / Spring Cloud 2021 已进入旧技术代际（开发计划第 11 节风险 8）。
|
||
|
||
**影响**：`javax.*` → `jakarta.*` 命名空间迁移；依赖版本随 Boot 3 BOM 统一管理。
|
||
|
||
## ADR-002 MVP 阶段移除 Nacos，微服务化阶段再引入服务发现
|
||
|
||
**决策**：MVP 阶段从 `patbond-api` 移除 Nacos（服务发现与配置中心）。`patbond-auth` 调用 `patbond-user` 改为通过配置注入的静态地址：
|
||
|
||
```java
|
||
@FeignClient(name = "patbond-user", url = "${patbond.user-service.url}")
|
||
```
|
||
|
||
**理由**：
|
||
|
||
- MVP 只有 auth/user 两个服务，服务发现解决的是「服务多、地址动态」的问题，当前并不存在。
|
||
- 移除后干净检出即可启动，消除本地开发和 CI 对 Nacos 实例的硬依赖。
|
||
- 升级 Boot 3 后原 Spring Cloud Alibaba 2021 版本线不再兼容，移除可避免本迭代被版本配套拖住。
|
||
|
||
**回补路线（重要）**：本决策是阶段性的，不是永久放弃。在后续真正拆分微服务（多服务、多实例、地址动态）时，重新引入服务发现：
|
||
|
||
1. 选用与当时 Spring Boot / Spring Cloud 版本配套的 Spring Cloud Alibaba 版本线（Boot 3 对应 2022/2023+，不得沿用 2021 坐标）。
|
||
2. 加回 discovery 依赖与注册配置，删除 Feign 的 `url` 属性即可切回服务发现，调用方接口代码无需改动。
|
||
3. 届时同步评估配置中心是否一并启用。
|
||
|
||
**影响**：开发计划第 5.1、5.2、5.3 节中涉及 Nacos 的环境要求与启动步骤在 MVP 阶段不再适用，以本决策为准。
|
||
|
||
## ADR-003 Token 有效期与多设备策略
|
||
|
||
**决策**：
|
||
|
||
- Access token 有效期 15 分钟。
|
||
- Refresh token 有效期 30 天，每次刷新即轮换（rotation），旧 token 立即失效。
|
||
- 允许多设备并行会话；退出仅撤销当前会话。
|
||
- 上述值实现为配置项，不硬编码。
|
||
|
||
## ADR-004 首版登录方式仅账号 + 密码
|
||
|
||
**决策**：第一版仅支持用户名 + 密码注册登录。不实现手机号登录、短信验证码和第三方登录，但凭证数据模型（`identity.user_credentials`）保留扩展能力，登录页 UI 预留不渲染的扩展区。
|
||
|
||
## ADR-005 品牌色以 iOS 设计手稿为正典
|
||
|
||
**决策**：产品视觉以 `AI宠物_iOS_UI设计稿.html`（珊瑚橙主色 `#FF6F4C`、奶油底、暖色系）为品牌正典。`patbond-flutter` 当前的靛蓝 `#4F46E5` 主题属早期脚手架占位实现，正式启动后迁移到手稿色系。
|
||
|
||
**补充规范**（详见 `iteration-1-reports/04-ui-login-design-spec.md`）：
|
||
|
||
- 主题以语义 token 组织（primary / canvas / ink / error 等），集中在单一主题文件。
|
||
- 新增 error 色 `#D0342C`（设计稿与现有主题均缺失）。
|
||
- 实心按钮使用加深的 `primaryStrong #D6431A` 以满足 WCAG AA 对比度；原珊瑚橙 `#FF6F4C` 用于装饰与非文字承载场景。
|
||
|
||
## ADR-006 测试与交付容器化策略
|
||
|
||
**决策**（2026-09-04）：
|
||
|
||
- 自动化测试中的数据库一律通过 Testcontainers 使用 Docker 临时容器（`postgres:18`，版本基线见 ADR-008），不依赖开发者本机数据库；每次测试在干净实例上执行全量 Flyway 迁移。
|
||
- 最终交付将提供 Docker 镜像/编排包（对应开发计划 M6 的容器镜像项）。
|
||
- 开发者本人手动测试/联调时可使用自己本机的 PostgreSQL，连接信息经环境变量注入，不入库。
|
||
|
||
**理由**：测试可复现、与目标版本（PostgreSQL 16）对齐、不受本机数据库账号/版本差异影响；交付形态与测试基础设施统一到 Docker。
|
||
|
||
## ADR-007 部署形态：容器化应用 + 分阶段数据库策略
|
||
|
||
**决策**（2026-09-04）：
|
||
|
||
- 应用（auth、user 及后续模块）以 Docker 容器交付部署，**容器保持无状态**：文件走对象存储、会话在数据库，任何状态不落容器本地。
|
||
- **MVP 阶段**：数据库使用 Docker 容器运行 PostgreSQL（数据挂载 volume 持久化），与应用同机以 docker compose 编排；配套每日 `pg_dump` 备份到独立存储，并演练过恢复流程。
|
||
- **规模化阶段**：当用户量与数据重要性上升后，数据库迁移至云托管数据库（RDS 类）或独立数据库服务器，应用容器不动。
|
||
- 数据库连接信息始终经环境变量注入（`PATBOND_DB_URL` 等），保证迁移数据库时应用层零改动。
|
||
|
||
**理由**：双人团队运维预算有限，容器数据库 + 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:18（18.6）容器上通过，Flyway V1 baseline 迁移执行无兼容问题。
|
||
|
||
**影响**：后续大版本变更须以新 ADR 决策并附全量测试验证；数据库特性使用以 18 为可用上限参考。
|