lixi
209021e7d2
- 新增 development/iterations/iteration-1/：15 份角色报告 + 进展看板（已完成/未闭环/下一步），作为双人协作的进度事实来源 - 新增 ADR-006：测试与交付容器化策略（Testcontainers / 交付 Docker 包 / 本机库仅个人联调） - Git 工作流规范补充：敏感信息只进忽略文件或 sample、测试数据不入库、测试代码限标准测试目录 - 门禁：mkdocs build --strict 通过（零警告）
4.3 KiB
架构与技术决策记录（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 改为通过配置注入的静态地址：
@FeignClient(name = "patbond-user", url = "${patbond.user-service.url}")
理由：
- MVP 只有 auth/user 两个服务，服务发现解决的是「服务多、地址动态」的问题，当前并不存在。
- 移除后干净检出即可启动，消除本地开发和 CI 对 Nacos 实例的硬依赖。
- 升级 Boot 3 后原 Spring Cloud Alibaba 2021 版本线不再兼容，移除可避免本迭代被版本配套拖住。
回补路线（重要）：本决策是阶段性的，不是永久放弃。在后续真正拆分微服务（多服务、多实例、地址动态）时，重新引入服务发现：
- 选用与当时 Spring Boot / Spring Cloud 版本配套的 Spring Cloud Alibaba 版本线（Boot 3 对应 2022/2023+，不得沿用 2021 坐标）。
- 加回 discovery 依赖与注册配置，删除 Feign 的
url属性即可切回服务发现，调用方接口代码无需改动。 - 届时同步评估配置中心是否一并启用。
影响：开发计划第 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:16），不依赖开发者本机数据库；每次测试在干净实例上执行全量 Flyway 迁移。 - 最终交付将提供 Docker 镜像/编排包（对应开发计划 M6 的容器镜像项）。
- 开发者本人手动测试/联调时可使用自己本机的 PostgreSQL，连接信息经环境变量注入，不入库。
理由：测试可复现、与目标版本（PostgreSQL 16）对齐、不受本机数据库账号/版本差异影响；交付形态与测试基础设施统一到 Docker。