From ca8cb725547293b49de3296e7dd47a1e38468f8c Mon Sep 17 00:00:00 2001
From: Lixi20 <lixi0506cd@gmail.com>
Date: Thu, 3 Sep 2026 18:00:52 +0800
Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=E5=BC=80=E5=8F=91=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/architecture/decisions.md | 63 ++++++++++++++++++++++++++++++++++
 mkdocs.yml                     |  2 ++
 2 files changed, 65 insertions(+)
 create mode 100644 docs/architecture/decisions.md

diff --git a/docs/architecture/decisions.md b/docs/architecture/decisions.md
new file mode 100644
index 0000000..e17e735
--- /dev/null
+++ b/docs/architecture/decisions.md
@@ -0,0 +1,63 @@
+# 架构与技术决策记录（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` 用于装饰与非文字承载场景。
diff --git a/mkdocs.yml b/mkdocs.yml
index 01084d2..a072cf1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -5,3 +5,5 @@ nav:
   - 首页: index.md
   - 开发文档:
       - 开发实施计划: development/development-plan.md
+  - 架构:
+      - 技术决策记录: architecture/decisions.md