# Fonrey ADR 动态决策记录（Architecture & Requirement Decision Records）

> 目的：沉淀 Vibe Coding 过程中的**技术决策**与**需求决策**，避免跨会话后方案漂移。  
> 适用范围：全项目（TECH_STACK / DATA_MODEL / PRD / TEST_CASES / 开发流程）。  
> 维护原则：新增决策只追加，不覆盖历史；若决策被替代，必须新增 supersede 记录。

---

## 变更历史

| 日期 | 变更人 | 变更内容 |
|---|---|---|
| 2026-04-30 | Atlas | 初始化 ADR 动态决策记录；补录当日关键技术与需求决策 |

## 一、记录规范（必须遵守）

### 1.1 决策ID规则
- 格式：`ADR-YYYYMMDD-XXX`
- 例：`ADR-20260430-001`

### 1.2 决策类型
- `TECH`：技术决策（架构、接口、数据、测试、流程规范）
- `REQ`：需求决策（范围、术语、优先级、验收口径）

### 1.3 状态枚举
- `accepted`：已生效
- `superseded`：已被替代（需指向新 ADR）
- `deprecated`：废弃（不再执行）

### 1.4 最小字段
每条 ADR 必须包含：
1. 决策ID
2. 日期
3. 模块
4. 类型（TECH/REQ）
5. 状态
6. 背景
7. 决策内容
8. 影响范围
9. 关联文档
10. 备注（可选）

---

## 二、按日期记录（主索引）

## 2026-04-30

### ADR-20260430-001
- **类型**：REQ
- **模块**：测试治理（全局）
- **状态**：accepted
- **背景**：测试文档与沟通中存在“业务旅程/测试用例”术语混用，易导致执行偏差。
- **决策**：全项目统一使用“测试用例”术语，不再以“业务旅程”作为执行口径。
- **影响范围**：`TECH_STACK/测试规范.md`、`TEST_CASES/*`
- **关联文档**：`TECH_STACK/测试规范.md`

### ADR-20260430-002
- **类型**：TECH
- **模块**：测试治理（全局）
- **状态**：accepted
- **背景**：多模块并行时测试编号易重复、不可追溯。
- **决策**：采用全局唯一测试用例编号：`TC-FON-XXXXXX`，并建立注册表，禁止复用废弃编号。
- **影响范围**：所有测试用例文档与测试报告系统
- **关联文档**：
  - `TEST_CASES/TEST_CASE_ID_SPEC.md`
  - `TEST_CASES/TEST_CASE_REGISTRY.md`

### ADR-20260430-003
- **类型**：TECH
- **模块**：测试执行与报告
- **状态**：accepted
- **背景**：失败定位粒度不足，无法快速定位到具体步骤。
- **决策**：测试报告必须支持 `test_case_id + step_id` 级追踪，并记录 `expected/actual/error_message` 与证据路径。
- **影响范围**：CI 报告、自动化测试框架
- **关联文档**：`TECH_STACK/测试规范.md`

### ADR-20260430-004
- **类型**：REQ
- **模块**：登录管理
- **状态**：accepted
- **背景**：登录 PRD v2.0 与技术方案存在接口命名漂移。
- **决策**：登录模块接口路径以 PRD v2.0 为唯一权威，技术方案与测试用例全部对齐 PRD 路径。
- **影响范围**：登录模块 API 设计、自动化测试调用路径
- **关联文档**：
  - `PRD/登录管理/用户登录管理模块PRD.md`
  - `TECH_STACK/登录管理技术方案.md`
  - `TEST_CASES/TEST_CASES_LOGIN_MODULE.md`

### ADR-20260430-005
- **类型**：REQ
- **模块**：登录管理
- **状态**：accepted
- **背景**：Story 边界存在历史遗留混淆。
- **决策**：登录模块范围冻结为：短信验证码登录为 MVP 正式能力；“找回用户名”废弃；微信扫码保留为预留。
- **影响范围**：实现范围、测试覆盖边界
- **关联文档**：
  - `PRD/登录管理/用户登录管理模块PRD.md`
  - `TECH_STACK/登录管理技术方案.md`

### ADR-20260430-006
- **类型**：TECH
- **模块**：客户端发布管理
- **状态**：accepted
- **背景**：发布模块缺少可执行技术方案，无法指导实现与测试。
- **决策**：新增独立技术方案文档，明确 Electron 壳层边界、EV 签名、Heartbeat、自动更新、完整性校验、R2 版本管理、官网分发、便携版策略。
- **影响范围**：`apps/release` 设计与落地
- **关联文档**：
  - `TECH_STACK/客户端发布管理技术方案.md`
  - `PRD/发布管理/客户端发布管理模块PRD.md`

### ADR-20260430-007
- **类型**：TECH
- **模块**：客户端发布管理 / 数据模型
- **状态**：accepted
- **背景**：统计口径需支撑跨租户版本分布与活跃安装数。
- **决策**：以 `public.client_heartbeats` 作为心跳事实表，使用 `(tenant_id, device_id)` 为 Upsert 锚点，活跃定义为最近 24h。
- **影响范围**：统计接口、看板与聚合查询
- **关联文档**：`DATA_MODEL/DATA_MODEL_PUBLIC.md`

### ADR-20260430-008
- **类型**：TECH
- **模块**：客户端发布管理 / 安全
- **状态**：accepted
- **背景**：下载链路存在篡改与损坏风险。
- **决策**：客户端更新包必须进行 SHA256 完整性校验，校验失败禁止安装并保留当前版本可用。
- **影响范围**：客户端更新器、发布接口响应字段
- **关联文档**：
  - `TECH_STACK/客户端发布管理技术方案.md`
  - `PRD/发布管理/客户端发布管理模块PRD.md`

### ADR-20260430-009
- **类型**：TECH
- **模块**：客户端发布管理 / API
- **状态**：accepted
- **背景**：历史文档存在 `/api/client/updates/*` 与 `/api/release/updates/*` 双口径。
- **决策**：发布模块统一采用 `/api/release/...` 命名空间。
- **影响范围**：服务端路由、客户端调用、测试用例
- **关联文档**：
  - `PRD/发布管理/客户端发布管理模块PRD.md`
  - `TECH_STACK/TECH_STACK.md`
  - `TECH_STACK/客户端发布管理技术方案.md`

### ADR-20260430-010
- **类型**：TECH
- **模块**：文档治理（全局）
- **状态**：accepted
- **背景**：多目录文档缺少统一变更追溯入口。
- **决策**：`TECH_STACK / DATA_MODEL / TEST_CASES` 下文档统一添加“变更历史”章节，并规范位置：**头部元信息之后、正文主章节（## 一/## 1）之前**。
- **影响范围**：全量技术文档与测试文档
- **关联文档**：
  - `TECH_STACK/*.md`
  - `DATA_MODEL/*.md`
  - `TEST_CASES/*.md`

---

## 三、按模块分类记录（视图索引）

## 3.1 测试治理（全局）
- `ADR-20260430-001`：术语统一为“测试用例”（REQ）
- `ADR-20260430-002`：全局唯一测试编号机制（TECH）
- `ADR-20260430-003`：报告粒度到 step_id（TECH）

## 3.2 登录管理
- `ADR-20260430-004`：接口路径以 PRD 为准（REQ）
- `ADR-20260430-005`：MVP 范围冻结（REQ）

## 3.3 客户端发布管理
- `ADR-20260430-006`：新增独立技术方案（TECH）
- `ADR-20260430-008`：SHA256 完整性校验强制（TECH）
- `ADR-20260430-009`：API 命名空间统一 `/api/release/...`（TECH）

## 3.4 数据模型（public schema）
- `ADR-20260430-007`：`client_heartbeats` Upsert + 24h 活跃口径（TECH）

## 3.5 文档治理（全局）
- `ADR-20260430-010`：变更历史章节统一规则（TECH）

---

## 四、历史记录（Append-Only Log）

> 说明：本节为机器可检索的历史流水，不删改旧记录。

| ADR ID | 日期 | 模块 | 类型 | 状态 | 摘要 | 关联 |
|---|---|---|---|---|---|---|
| ADR-20260430-001 | 2026-04-30 | 测试治理 | REQ | accepted | 术语统一为“测试用例” | `TECH_STACK/测试规范.md` |
| ADR-20260430-002 | 2026-04-30 | 测试治理 | TECH | accepted | 测试编号全局唯一 `TC-FON-XXXXXX` | `TEST_CASES/TEST_CASE_ID_SPEC.md` |
| ADR-20260430-003 | 2026-04-30 | 测试执行 | TECH | accepted | 报告必须定位到 `test_case_id+step_id` | `TECH_STACK/测试规范.md` |
| ADR-20260430-004 | 2026-04-30 | 登录管理 | REQ | accepted | 登录接口路径全部按 PRD v2.0 | `TECH_STACK/登录管理技术方案.md` |
| ADR-20260430-005 | 2026-04-30 | 登录管理 | REQ | accepted | 登录模块范围冻结（含废弃/预留） | `PRD/登录管理/用户登录管理模块PRD.md` |
| ADR-20260430-006 | 2026-04-30 | 客户端发布 | TECH | accepted | 新建独立技术方案文档 | `TECH_STACK/客户端发布管理技术方案.md` |
| ADR-20260430-007 | 2026-04-30 | 数据模型 | TECH | accepted | `client_heartbeats` Upsert + 24h 活跃 | `DATA_MODEL/DATA_MODEL_PUBLIC.md` |
| ADR-20260430-008 | 2026-04-30 | 客户端发布安全 | TECH | accepted | SHA256 校验失败禁止安装 | `TECH_STACK/客户端发布管理技术方案.md` |
| ADR-20260430-009 | 2026-04-30 | 客户端发布 API | TECH | accepted | 统一 `/api/release/...` 路径 | `TECH_STACK/TECH_STACK.md` |
| ADR-20260430-010 | 2026-04-30 | 文档治理 | TECH | accepted | 变更历史章节位置统一规范 | `TECH_STACK/*.md` `DATA_MODEL/*.md` `TEST_CASES/*.md` |

---

## 五、后续维护约定

1. 每当接受新技术或需求决策，**当天必须新增 ADR 条目**。  
2. 若新决策替代旧决策，在新 ADR 中写明 `supersedes: ADR-xxxx`，并将旧条目标记 `superseded`。  
3. PRD / TECH_STACK / DATA_MODEL / TEST_CASES 发生关键口径变化时，必须同步更新本文件。  
4. 本文件是跨 Session 的决策权威输入之一，和 PRD 一起喂给 Agent。