文档更新

Project/fonrey/ADR.md

@@ -11,6 +11,8 @@
 | 日期 | 变更人 | 变更内容 |
 |---|---|---|
 | 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 |
 
 ## 一、记录规范（必须遵守）
 
@@ -155,6 +157,96 @@
 
 ---
 
+## 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 测试治理（全局）
@@ -167,7 +259,7 @@
 - `ADR-20260430-005`：MVP 范围冻结（REQ）
 
 ## 3.3 客户端发布管理
-- `ADR-20260430-006`：新增独立技术方案（TECH）
+- `ADR-20260430-006`：新增独立技术方案（TECH） *(superseded by `ADR-20260502-002`，技术方案已合并至『平台管理后台技术方案』)*
 - `ADR-20260430-008`：SHA256 完整性校验强制（TECH）
 - `ADR-20260430-009`：API 命名空间统一 `/api/release/...`（TECH）
 
@@ -176,6 +268,11 @@
 
 ## 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）
 
 ---
 
@@ -195,6 +292,9 @@
 | 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 |
 
 ---