306 lines
20 KiB
Markdown
306 lines
20 KiB
Markdown
# Fonrey ADR 动态决策记录（Architecture & Requirement Decision Records）
|
||
|
||
> 目的：沉淀 Vibe Coding 过程中的**技术决策**与**需求决策**，避免跨会话后方案漂移。
|
||
> 适用范围：全项目（TECH_STACK / DATA_MODEL / PRD / TEST_CASES / 开发流程）。
|
||
> 维护原则：新增决策只追加，不覆盖历史；若决策被替代，必须新增 supersede 记录。
|
||
|
||
---
|
||
|
||
## 变更历史
|
||
|
||
| 日期 | 变更人 | 变更内容 |
|
||
|---|---|---|
|
||
| 2026-04-30 | Atlas | 初始化 ADR 动态决策记录；补录当日关键技术与需求决策 |
|
||
| 2026-05-02 | Sisyphus | 新增 ADR-20260502-001：合并系统管理与客户端发布两份 PRD 为统一的『平台管理后台 PRD』，原文件删除 |
|
||
| 2026-05-02 | Sisyphus | 新增 ADR-20260502-003：定义『PRD 与 Tech 文档职责边界』规则（PRD 管 what/why、Tech 管 how）；首次落地于登录管理 PRD v3.0 |
|
||
|
||
## 一、记录规范（必须遵守）
|
||
|
||
### 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`
|
||
|
||
---
|
||
|
||
## 2026-05-02
|
||
|
||
### ADR-20260502-001
|
||
- **类型**：REQ
|
||
- **模块**：平台管理后台（PRD 治理）
|
||
- **状态**：accepted
|
||
- **背景**：原 `PRD/系统管理/系统管理模块PRD.md`（v1.3）与 `PRD/发布管理/客户端发布管理模块PRD.md`（v1.2）虽分别归口「系统管理」与「客户端发布」，但二者实际受众均为**平台管理员**（Platform Admin / 运营人员 / 只读审计员），分别描述会导致：① 页面路由与权限矩阵在两份 PRD 中各自演化、容易割裂；② API 操作清单缺乏统一规划；③ 客户端发布 v1.1 已明确归属"平台运营后台"，与系统管理同处一域。
|
||
- **决策**：
|
||
1. 合并为单一文档 `PRD/平台管理后台/平台管理后台PRD.md`（v1.0），定位「面向平台管理员的统一后台 PRD」；以产品视角统一规划页面清单、访问权限、页面间导航逻辑、业务 API 操作清单（不绑定具体路径）。
|
||
2. 原两份 PRD 文件**直接删除**，由新文档完全取代；新文档头部声明 supersede 关系。
|
||
3. 客户端运行时与平台之间的接口（如查询最新版本、上报心跳）维持在 `TECH_STACK/客户端发布管理技术方案.md` 中描述，本 PRD 仅描述平台管理员可执行的业务操作。
|
||
4. 角色权限矩阵、租户状态机、客户端版本治理（含全平台租户活跃榜）等内容统一并入新 PRD 第 5–7 章。
|
||
- **影响范围**：
|
||
- PRD：删除 `PRD/系统管理/系统管理模块PRD.md`、`PRD/发布管理/客户端发布管理模块PRD.md`；新增 `PRD/平台管理后台/平台管理后台PRD.md`
|
||
- README：模块入口索引同步更新，原「系统管理」「客户端发布」入口指向新 PRD（客户端技术方案文档保留）
|
||
- TECH_STACK：`客户端发布管理技术方案.md` 关联 PRD 的引用需同步指向新 PRD
|
||
- **关联文档**：
|
||
- `PRD/平台管理后台/平台管理后台PRD.md`
|
||
- `README.md`
|
||
- `TECH_STACK/客户端发布管理技术方案.md`
|
||
- `TECH_STACK/系统设置技术方案.md`
|
||
- **备注**：本决策不改变任何技术口径（API 命名空间、`client_heartbeats` 表结构、SHA256 校验等），仅是 PRD 文档治理层面的合并与归属调整。`ADR-20260430-006/007/008/009` 全部继续生效。
|
||
|
||
### ADR-20260502-002
|
||
- **类型**：TECH
|
||
- **模块**：平台管理后台（TECH_STACK 治理）
|
||
- **状态**：accepted
|
||
- **背景**：随 `ADR-20260502-001` 完成 PRD 合并后，TECH_STACK 域仍存在两份独立技术方案：`TECH_STACK/客户端发布管理技术方案.md`（v1.0）与 `TECH_STACK/系统管理技术文档.md`（v1.x）。两者受众一致（平台管理员后台），却分别演化路由表、API 命名空间、Mixin 守卫链与错误码，存在以下风险：① 路由守卫与 step-up MFA 协议在两文档中各自定义，易割裂；② API 命名空间（`/admin/...` 后台 vs `/api/release/...` 客户端运行时）缺乏统一约束；③ Celery 队列、Redis Key、错误码族无法横向对齐。
|
||
- **决策**：
|
||
1. 合并为单一文档 `TECH_STACK/平台管理后台技术方案.md`（v1.0），覆盖 PRD 要求的三维度——**技术选型**（实现路由与 API 的框架）、**页面路由表**（路径定义、动态参数、路由守卫、懒加载）、**API 设计**（RESTful 路径、HTTP 方法、请求/响应、错误码、版本控制、认证方式）。
|
||
2. 原 `TECH_STACK/客户端发布管理技术方案.md` 与 `TECH_STACK/系统管理技术文档.md` **直接删除**，由新文档完全取代。
|
||
3. 双 API 命名空间最终落地：`/admin/...`（HTMX Partial，Session+CSRF+TOTP，无路径版本号）、`/admin/api/client-releases/...`（管理端 JSON 写操作）、`/api/release/v1/...`（客户端运行时，路径版本号 `v1`）。
|
||
4. App 拆分：`apps/admin_console`（租户/备份/导出/升级/审计/管理员/Feature Flag）+ `apps/release`（客户端发布 + 客户端运行时 API），后者仅依赖前者的 `permissions / middleware / services.audit_service`。
|
||
5. `TECH_STACK/TECH_STACK.md` §8 模块表合并「系统设置」「客户端发布」相关行为单行「平台管理后台」入口；README 模块入口同步指向新文档。
|
||
- **影响范围**：
|
||
- TECH_STACK：新增 `平台管理后台技术方案.md`；删除 `客户端发布管理技术方案.md`、`系统管理技术文档.md`
|
||
- TECH_STACK：`TECH_STACK.md` §8 模块表
|
||
- README：模块入口索引（平台管理后台一行）
|
||
- **关联文档**：
|
||
- `TECH_STACK/平台管理后台技术方案.md`
|
||
- `TECH_STACK/TECH_STACK.md`
|
||
- `PRD/平台管理后台/平台管理后台PRD.md`
|
||
- `ADR-20260502-001`、`ADR-20260430-006/007/008/009`
|
||
- **备注**：本决策不变更任何技术口径（API 命名空间、`/api/release/v1/...` 版本号、SHA256 校验、`client_heartbeats` Upsert + 24h 活跃口径、审计不可变约束等），仅在 TECH_STACK 文档治理层面执行合并与归属调整。
|
||
|
||
### ADR-20260502-003
|
||
- **类型**：REQ
|
||
- **模块**：文档治理（全局）
|
||
- **状态**：accepted
|
||
- **背景**：历史 PRD（如 `PRD/登录管理/用户登录管理模块PRD.md` v2.0、`PRD/平台管理后台/平台管理后台PRD.md` v1.0）混杂大量实现细节——具体 API 路径与 HTTP 方法、Redis Key 格式与 TTL、Django 字段类型与中间件类名、Electron API 名、CSS 类名、Cookie 属性等。这导致：① PRD 评审被技术细节淹没，业务边界讨论失焦；② 实现口径出现"PRD 写一份、Tech 写一份"的双源头，长期产生漂移（参见 `ADR-20260430-004` 已为登录模块单独修过一次）；③ 业务变更与技术调整混在同一份文档里，变更范围与责任人难以拆分。
|
||
- **决策**：自本 ADR 起，全项目 PRD 与 Tech 文档严格遵循以下职责边界，任何新建/修订必须自检通过。
|
||
|
||
**PRD 应包含（"是什么 / 为什么"）**：
|
||
1. **页面与导航**：列出页面清单、访问权限（角色矩阵）、用户视角的页面间跳转逻辑、登录态/未登录态分支。✅ "/dashboard 需登录后访问"；✅ "用户点击『详情』后跳转到订单详情页"。
|
||
2. **业务操作清单**：以业务动词描述用户/角色可执行的能力。✅ "用户可查询自己的订单列表"；✅ "管理员可批量更新商品状态"。
|
||
3. **业务规则与数据约束**：抽象层面的规则与数值阈值（如『密码连续错误 5 次锁定 30 分钟』『短信验证码有效期 10 分钟』），但仅以业务语言表达，不绑定 Redis Key 或字段名。
|
||
4. **状态机**：业务状态枚举与合法跃迁。
|
||
5. **验收标准**：可由产品/QA 验证的用户可见行为。
|
||
|
||
**PRD 必须移出（移交 Tech / DATA_MODEL）**：
|
||
1. ❌ 具体 API 路径（如 `POST /api/auth/login/phone/`）与 HTTP 方法。
|
||
2. ❌ 请求/响应 JSON Schema、字段名、错误码常量。
|
||
3. ❌ Redis Key 格式、TTL、缓存策略、消息队列名。
|
||
4. ❌ 数据库字段名、字段类型（`CharField(30)`、`OneToOneField`）、表名、索引名、中间件类名。
|
||
5. ❌ 前端框架/库的 API 名（`BrowserWindow.loadURL`、`electron-store`、`HX-Request` 头）、CSS 类名、Cookie 属性（`SameSite=Strict`、`HttpOnly`）。
|
||
6. ❌ 实现选型与库依赖清单（除非业务上明确强制，如"必须由具备短信资质的服务商发送"）。
|
||
|
||
**PRD 引用 Tech 的标准格式**：当业务规则需要技术细节落地时，PRD 用以下任一方式引用：
|
||
- "（实现细节详见 `TECH_STACK/<模块>技术方案.md` §X.Y）"
|
||
- "（数据结构见 `DATA_MODEL/<模块>.md`）"
|
||
- "（端点契约见 `TECH_STACK/API_CONTRACT.md`）"
|
||
|
||
**Tech 文档应承接**：上述被移出的全部内容；若 PRD 移出某项时 Tech 文档尚未承接，**必须在同一次提交内同步补齐 Tech**，禁止信息丢失。
|
||
|
||
**测试用例不受本 ADR 约束**：测试用例本质上需要可执行的实现细节（路径、字段、错误码），保留细节不动；但其引用 PRD 章节时应同步更新章节号。
|
||
|
||
- **影响范围**：
|
||
- PRD：所有 PRD 文档需按本规则审视并修订（首批落地：登录管理 PRD → v3.0；后续模块按需推进）
|
||
- TECH_STACK：所有 Tech 文档需承接对应实现细节，缺口必须同步补齐
|
||
- 未来所有新建 PRD：必须自检本规则
|
||
- CI/Review：建议在 PR Review checklist 增加"PRD 是否含具体 API 路径/Redis Key/字段类型"的反向检查项
|
||
- **关联文档**：
|
||
- `AGENTS.md` §9.1（ADR 治理联动规则）
|
||
- `PRD/登录管理/用户登录管理模块PRD.md`（v3.0 首批落地）
|
||
- `TECH_STACK/登录管理技术方案.md`（同步承接被移出细节）
|
||
- `ADR-20260430-004`（登录接口路径以 PRD 为准 → 本 ADR 后语义升级为：业务能力以 PRD 为准，具体路径以 Tech 为准；不冲突，互补）
|
||
- **备注**：本 ADR 不更改任何已实现的技术口径，仅约束**文档承载位置**。`ADR-20260430-004` 关于"登录接口最终路径"的权威源仍以两份文档同步为准（PRD 描述业务操作、Tech 描述具体路径），二者不应再次出现漂移。
|
||
|
||
---
|
||
|
||
## 三、按模块分类记录（视图索引）
|
||
|
||
## 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） *(superseded by `ADR-20260502-002`，技术方案已合并至『平台管理后台技术方案』)*
|
||
- `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）
|
||
- `ADR-20260502-003`：PRD 与 Tech 文档职责边界（REQ）
|
||
|
||
## 3.6 平台管理后台
|
||
- `ADR-20260502-001`：合并系统管理 PRD 与客户端发布 PRD 为统一的『平台管理后台 PRD』（REQ）
|
||
- `ADR-20260502-002`：合并系统管理技术文档与客户端发布技术方案为统一的『平台管理后台技术方案』（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` |
|
||
| ADR-20260502-001 | 2026-05-02 | 平台管理后台 | REQ | accepted | 合并系统管理 PRD + 客户端发布 PRD 为『平台管理后台 PRD』，原文件删除 | `PRD/平台管理后台/平台管理后台PRD.md` |
|
||
| ADR-20260502-002 | 2026-05-02 | 平台管理后台 | TECH | accepted | 合并系统管理技术文档 + 客户端发布技术方案为『平台管理后台技术方案』（覆盖技术选型/页面路由表/API 设计三维度），原文件删除 | `TECH_STACK/平台管理后台技术方案.md` |
|
||
| ADR-20260502-003 | 2026-05-02 | 文档治理 | REQ | accepted | PRD 管 what/why、Tech 管 how；PRD 必须移出 API 路径/Redis Key/字段类型/框架 API 等实现细节，由 Tech 与 DATA_MODEL 承接 | `PRD/登录管理/用户登录管理模块PRD.md` v3.0 |
|
||
|
||
---
|
||
|
||
## 五、后续维护约定
|
||
|
||
1. 每当接受新技术或需求决策，**当天必须新增 ADR 条目**。
|
||
2. 若新决策替代旧决策，在新 ADR 中写明 `supersedes: ADR-xxxx`，并将旧条目标记 `superseded`。
|
||
3. PRD / TECH_STACK / DATA_MODEL / TEST_CASES 发生关键口径变化时，必须同步更新本文件。
|
||
4. 本文件是跨 Session 的决策权威输入之一，和 PRD 一起喂给 Agent。 |