Files
nexus/Project/fonrey/ADR.md
2026-06-04 14:34:32 +08:00

24 KiB
Raw Blame History

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
2026-06-04 Sisyphus 新增 ADR-20260604-001列表分页全局采用 Keyset(cursor),允许 page-based 作过渡兼容;同步修订 UI_DESIGN/ROUTES.mdUI_DESIGN/房源管理/房源列表_UI.md
2026-06-04 Sisyphus 新增 ADR-20260604-002ROUTES.md 客源条目"重复客源(成交)"与"重复客源(公客)"合并为单条 /clients/duplicates/?tab=transacted|public,客源条目数稳定为 19

一、记录规范(必须遵守)

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/测试规范.mdTEST_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.mdv1.3)与 PRD/发布管理/客户端发布管理模块PRD.mdv1.2)虽分别归口「系统管理」与「客户端发布」,但二者实际受众均为平台管理员Platform Admin / 运营人员 / 只读审计员),分别描述会导致:① 页面路由与权限矩阵在两份 PRD 中各自演化、容易割裂;② API 操作清单缺乏统一规划;③ 客户端发布 v1.1 已明确归属"平台运营后台",与系统管理同处一域。
  • 决策
    1. 合并为单一文档 PRD/平台管理后台/平台管理后台PRD.mdv1.0),定位「面向平台管理员的统一后台 PRD」以产品视角统一规划页面清单、访问权限、页面间导航逻辑、业务 API 操作清单(不绑定具体路径)。
    2. 原两份 PRD 文件直接删除,由新文档完全取代;新文档头部声明 supersede 关系。
    3. 客户端运行时与平台之间的接口(如查询最新版本、上报心跳)维持在 TECH_STACK/客户端发布管理技术方案.md 中描述,本 PRD 仅描述平台管理员可执行的业务操作。
    4. 角色权限矩阵、租户状态机、客户端版本治理(含全平台租户活跃榜)等内容统一并入新 PRD 第 57 章。
  • 影响范围
    • PRD删除 PRD/系统管理/系统管理模块PRD.mdPRD/发布管理/客户端发布管理模块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/客户端发布管理技术方案.mdv1.0)与 TECH_STACK/系统管理技术文档.mdv1.x。两者受众一致平台管理员后台却分别演化路由表、API 命名空间、Mixin 守卫链与错误码,存在以下风险:① 路由守卫与 step-up MFA 协议在两文档中各自定义,易割裂;② API 命名空间(/admin/... 后台 vs /api/release/... 客户端运行时)缺乏统一约束;③ Celery 队列、Redis Key、错误码族无法横向对齐。
  • 决策
    1. 合并为单一文档 TECH_STACK/平台管理后台技术方案.mdv1.0),覆盖 PRD 要求的三维度——技术选型(实现路由与 API 的框架)、页面路由表(路径定义、动态参数、路由守卫、懒加载)、API 设计RESTful 路径、HTTP 方法、请求/响应、错误码、版本控制、认证方式)。
    2. TECH_STACK/客户端发布管理技术方案.mdTECH_STACK/系统管理技术文档.md 直接删除,由新文档完全取代。
    3. 双 API 命名空间最终落地:/admin/...HTMX PartialSession+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_STACKTECH_STACK.md §8 模块表
    • README模块入口索引平台管理后台一行
  • 关联文档
    • TECH_STACK/平台管理后台技术方案.md
    • TECH_STACK/TECH_STACK.md
    • PRD/平台管理后台/平台管理后台PRD.md
    • ADR-20260502-001ADR-20260430-006/007/008/009
  • 备注本决策不变更任何技术口径API 命名空间、/api/release/v1/... 版本号、SHA256 校验、client_heartbeats Upsert + 24h 活跃口径、审计不可变约束等),仅在 TECH_STACK 文档治理层面执行合并与归属调整。

ADR-20260502-003

  • 类型REQ

  • 模块:文档治理(全局)

  • 状态accepted

  • 背景:历史 PRDPRD/登录管理/用户登录管理模块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.loadURLelectron-storeHX-Request、CSS 类名、Cookie 属性(SameSite=StrictHttpOnly)。
    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.1ADR 治理联动规则)
    • PRD/登录管理/用户登录管理模块PRD.mdv3.0 首批落地)
    • TECH_STACK/登录管理技术方案.md(同步承接被移出细节)
    • ADR-20260430-004(登录接口路径以 PRD 为准 → 本 ADR 后语义升级为:业务能力以 PRD 为准,具体路径以 Tech 为准;不冲突,互补)
  • 备注:本 ADR 不更改任何已实现的技术口径,仅约束文档承载位置ADR-20260430-004 关于"登录接口最终路径"的权威源仍以两份文档同步为准PRD 描述业务操作、Tech 描述具体路径),二者不应再次出现漂移。


2026-06-04

ADR-20260604-001

  • 类型TECH
  • 模块:列表分页(全局)
  • 状态accepted
  • 背景AGENTS.md §4.5 与 UI_DESIGN/ROUTES.md §1 全局约定明文要求"所有列表查询必须使用 Keyset 分页(参数禁止包含 offset,统一使用 cursor"。但 UI_DESIGN/房源管理/房源列表_UI.md 现存示例(行 97 query params 列表、行 741 HTMX hx-vals='{"page": N}')仍是 page-based 风格与全局规范冲突。MVP 阶段一次性切到 Keyset 会拖慢前端模板与示例代码改造节奏,且页码 UI[1][2][3]...[N])已被多份截图与组件清单采用。
  • 决策
    1. 目标口径:列表分页长期统一为 Keyset(cursor);新增列表页与新增分页 API 不得使用 page/offset。
    2. 过渡兼容MVP Phase 1 期间,已有 page-based 示例的模块文档与代码可保留 page UI 表现(页码导航 + 跳页),但数据获取层必须支持 cursor 参数;后端 API 接受 cursor 为主参数,page 仅作过渡兼容输入且不得用于 1000 条以上数据集。
    3. 文档承接UI_DESIGN/ROUTES.md §1 通用约定新增"过渡兼容"说明;UI_DESIGN/房源管理/房源列表_UI.md 示例代码改为 cursor,分页 UI 表现保留。
    4. 退出条件MVP GA 后 1 个版本内,所有 page-based 示例必须清理;届时新增 ADR 关闭本过渡条款。
  • 影响范围
    • UI_DESIGN/ROUTES.md §1
    • UI_DESIGN/房源管理/房源列表_UI.md §2.1.1、§2.1.3 分页栏
    • 后续所有列表页 HTMX 模板与 API 视图
  • 关联文档
    • AGENTS.md §4.5
    • UI_DESIGN/ROUTES.md
    • UI_DESIGN/房源管理/房源列表_UI.md
  • 备注B-04Keyset 分页规范缺位)由本 ADR 部分关闭;剩余的列表索引矩阵补全留待后续 Major 修订。

ADR-20260604-002

  • 类型REQ
  • 模块:客源管理(路由汇总)
  • 状态accepted
  • 背景UI_DESIGN/ROUTES.md §5 客源条目数与历史 handoff 口径"客源 19 项"不一致——实际列出 20 行,多出的 1 行来自将"重复客源(成交)"与"重复客源(公客)"拆分为两条独立路由。两者复用同一列表页结构、同一权限范围、同一组件清单,仅业务子集不同,符合 ROUTES.md 全局约定中"Tab 维度统一用 ?tab= 表达"的模式。
  • 决策:将两条重复客源路由合并为单条 /clients/duplicates/,子集通过 ?tab=transacted|public 区分;客源条目总数稳定为 19。
  • 影响范围
    • UI_DESIGN/ROUTES.md §5合并 2 行为 1 行)
  • 关联文档
    • UI_DESIGN/ROUTES.md
    • UI_DESIGN/客源管理/客源列表_UI.md
  • 备注:本 ADR 不变更任何业务规则,仅统一 URL 表达形式与条目计数。

三、按模块分类记录(视图索引)

3.1 测试治理(全局)

  • ADR-20260430-001术语统一为“测试用例”REQ
  • ADR-20260430-002全局唯一测试编号机制TECH
  • ADR-20260430-003:报告粒度到 step_idTECH

3.2 登录管理

  • ADR-20260430-004:接口路径以 PRD 为准REQ
  • ADR-20260430-005MVP 范围冻结REQ

3.3 客户端发布管理

  • ADR-20260430-006新增独立技术方案TECH (superseded by ADR-20260502-002,技术方案已合并至『平台管理后台技术方案』)
  • ADR-20260430-008SHA256 完整性校验强制TECH
  • ADR-20260430-009API 命名空间统一 /api/release/...TECH

3.4 数据模型public schema

  • ADR-20260430-007client_heartbeats Upsert + 24h 活跃口径TECH

3.5 文档治理(全局)

  • ADR-20260430-010变更历史章节统一规则TECH
  • ADR-20260502-003PRD 与 Tech 文档职责边界REQ

3.6 平台管理后台

  • ADR-20260502-001:合并系统管理 PRD 与客户端发布 PRD 为统一的『平台管理后台 PRD』REQ
  • ADR-20260502-002合并系统管理技术文档与客户端发布技术方案为统一的『平台管理后台技术方案』TECH

3.7 列表分页(全局)

  • ADR-20260604-001Keyset(cursor) 为目标口径MVP 期允许 page-based 作过渡兼容TECH

3.8 客源管理(路由)

  • ADR-20260604-002:重复客源合并为单条 /clients/duplicates/?tab=transacted|public,客源条目数=19REQ

四、历史记录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 管 howPRD 必须移出 API 路径/Redis Key/字段类型/框架 API 等实现细节,由 Tech 与 DATA_MODEL 承接 PRD/登录管理/用户登录管理模块PRD.md v3.0
ADR-20260604-001 2026-06-04 列表分页(全局) TECH accepted Keyset(cursor) 为目标口径MVP 期允许 page-based 作过渡兼容 UI_DESIGN/ROUTES.mdUI_DESIGN/房源管理/房源列表_UI.md
ADR-20260604-002 2026-06-04 客源管理(路由) REQ accepted 重复客源合并为单条 /clients/duplicates/?tab=transacted|public,客源条目数=19 UI_DESIGN/ROUTES.md

五、后续维护约定

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