ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

文档更新

Browse Source
This commit is contained in:
admin
2026-06-04 14:34:32 +08:00
parent 7b91c310eb
commit e01ca79bdc
7 changed files with 1036 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
Project/fonrey/ADR.md
View File

@@ -13,6 +13,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 |
| 2026-06-04 | Sisyphus | 新增 ADR-20260604-001：列表分页全局采用 Keyset(cursor)，允许 page-based 作过渡兼容；同步修订 `UI_DESIGN/ROUTES.md` 与 `UI_DESIGN/房源管理/房源列表_UI.md` |
| 2026-06-04 | Sisyphus | 新增 ADR-20260604-002：ROUTES.md 客源条目"重复客源(成交)"与"重复客源(公客)"合并为单条 `/clients/duplicates/?tab=transacted\|public`，客源条目数稳定为 19 |
## 一、记录规范（必须遵守）
@@ -247,6 +249,43 @@
---
## 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-04（Keyset 分页规范缺位）由本 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 测试治理（全局）
@@ -274,6 +313,12 @@
- `ADR-20260502-001`：合并系统管理 PRD 与客户端发布 PRD 为统一的『平台管理后台 PRD』（REQ）
- `ADR-20260502-002`：合并系统管理技术文档与客户端发布技术方案为统一的『平台管理后台技术方案』（TECH）
## 3.7 列表分页（全局）
- `ADR-20260604-001`：Keyset(cursor) 为目标口径；MVP 期允许 page-based 作过渡兼容（TECH）
## 3.8 客源管理（路由）
- `ADR-20260604-002`：重复客源合并为单条 `/clients/duplicates/?tab=transacted|public`，客源条目数=19（REQ）
---
## 四、历史记录（Append-Only Log）
@@ -295,6 +340,8 @@
| 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 |
| ADR-20260604-001 | 2026-06-04 | 列表分页（全局） | TECH | accepted | Keyset(cursor) 为目标口径；MVP 期允许 page-based 作过渡兼容 | `UI_DESIGN/ROUTES.md`、`UI_DESIGN/房源管理/房源列表_UI.md` |
| ADR-20260604-002 | 2026-06-04 | 客源管理（路由） | REQ | accepted | 重复客源合并为单条 `/clients/duplicates/?tab=transacted\|public`，客源条目数=19 | `UI_DESIGN/ROUTES.md` |
---