# Fonrey（房睿）项目文档入口（README）

> **文档定位**：本文件是 Fonrey 项目的统一入口，供开发者与 AI Agent 快速定位权威文档。  
> **适用范围**：PRD / TASK / TECH_STACK / DATA_MODEL / TEST_CASES / ADR。  
> **维护原则**：目录与治理规则变更时，必须同步更新本文件。  
> **最后更新**：2026-04-30

---

## 变更历史

| 日期 | 变更人 | 变更内容 |
|---|---|---|
| 2026-04-30 | Atlas | 新建 README.md，建立项目文档统一入口与 ADR 治理门禁 |
| 2026-05-02 | Sisyphus | 模块入口索引更新：合并『系统管理』与『客户端发布』为『平台管理后台』；同步 `ADR-20260502-001` |
| 2026-05-02 | Sisyphus | TECH_STACK 入口更新：合并为 `平台管理后台技术方案.md`，原 `客户端发布管理技术方案.md` / `系统管理技术文档.md` 已删除；同步 `ADR-20260502-002` |

## 1. 项目核心入口（必读顺序）

1. **开发总约束（先读）**：[`AGENTS.md`](./AGENTS.md)
2. **需求范围（产品口径）**：[`PRD/PRD_MVP.md`](./PRD/PRD_MVP.md)
3. **任务看板（执行口径）**：[`PRD/TASK.md`](./PRD/TASK.md)
4. **技术总纲（实现口径）**：[`TECH_STACK/TECH_STACK.md`](./TECH_STACK/TECH_STACK.md)
5. **数据模型总览（数据口径）**：[`DATA_MODEL/DATA_MODEL.md`](./DATA_MODEL/DATA_MODEL.md)
6. **测试用例与编号规则（验证口径）**：[`TEST_CASES/`](./TEST_CASES/)
7. **ADR 动态决策记录（变更追溯口径）**：[`ADR.md`](./ADR.md)

---

## 2. 文档导航（按域）

| 域 | 权威文档 | 说明 |
|---|---|---|
| 需求（MVP） | [`PRD/PRD_MVP.md`](./PRD/PRD_MVP.md) | MVP 范围、模块边界、非目标项 |
| 任务拆解 | [`PRD/TASK.md`](./PRD/TASK.md) | User Story 与实施任务 |
| 技术总纲 | [`TECH_STACK/TECH_STACK.md`](./TECH_STACK/TECH_STACK.md) | 跨模块技术决策、模块索引、测试策略 |
| 数据模型总览 | [`DATA_MODEL/DATA_MODEL.md`](./DATA_MODEL/DATA_MODEL.md) | 全局数据架构与子文档索引 |
| API 全局契约 | [`TECH_STACK/API_CONTRACT.md`](./TECH_STACK/API_CONTRACT.md) | 请求/响应、错误码、分页、上传下载规范 |
| 本地开发与启动 | [`TECH_STACK/本地开发手册.md`](./TECH_STACK/本地开发手册.md) | 前置依赖、环境变量、`django-tenants` 初始化、种子数据、本地启动与验证 |
| 路由与组件映射 | [`UI_DESIGN/ROUTES.md`](./UI_DESIGN/ROUTES.md) | 全局唯一权威：模块 → 页面 → URL → 复用组件 → 四态 |
| 状态机权威 | [`DATA_MODEL/STATE_MACHINE.md`](./DATA_MODEL/STATE_MACHINE.md) | 全局唯一权威：所有实体生命周期与状态迁移规则 |
| 测试规范 | [`TECH_STACK/测试规范.md`](./TECH_STACK/测试规范.md) | 测试流程、报告字段、CI 要求 |
| 测试编号规则 | [`TEST_CASES/TEST_CASE_ID_SPEC.md`](./TEST_CASES/TEST_CASE_ID_SPEC.md) | `TC-FON-XXXXXX` 规则 |
| 测试注册表 | [`TEST_CASES/TEST_CASE_REGISTRY.md`](./TEST_CASES/TEST_CASE_REGISTRY.md) | 测试编号水位与批次登记 |
| ADR 决策 | [`ADR.md`](./ADR.md) | 按日期/按模块/历史流水的 append-only 决策记录 |

---

## 3. 开发与文档治理门禁（强制）

- 涉及**跨模块规则、接口口径、测试治理、范围边界**的变更：
  1) 先更新 [`ADR.md`](./ADR.md)（新增 `accepted` 记录）  
  2) 再更新 PRD / TECH_STACK / DATA_MODEL / TEST_CASES 对应文档。
- 若旧决策被替代，必须新增 `superseded` 记录并关联新 ADR ID。
- 提交 PR 时，命中上述变更域必须在描述中附 ADR ID（`ADR-YYYYMMDD-XXX`）。
- 测试用例编号必须全局唯一、不可复用，失败定位必须落到 `test_case_id + step_id`。

---

## 4. 模块文档入口

- 登录管理：[`PRD/登录管理/`](./PRD/登录管理/) ｜ [`TECH_STACK/登录管理技术方案.md`](./TECH_STACK/登录管理技术方案.md) ｜ [`TEST_CASES/TEST_CASES_LOGIN_MODULE.md`](./TEST_CASES/TEST_CASES_LOGIN_MODULE.md)
- 平台管理后台（含原『系统管理』+ 原『客户端发布』，详见 `ADR-20260502-001` / `ADR-20260502-002`）：[`PRD/平台管理后台/平台管理后台PRD.md`](./PRD/平台管理后台/平台管理后台PRD.md) ｜ [`TECH_STACK/平台管理后台技术方案.md`](./TECH_STACK/平台管理后台技术方案.md) ｜ [`TEST_CASES/TEST_CASES_RELEASE_MODULE.md`](./TEST_CASES/TEST_CASES_RELEASE_MODULE.md)
- 权限管理：[`PRD/权限管理/`](./PRD/权限管理/) ｜ [`TECH_STACK/权限管理系统技术方案.md`](./TECH_STACK/权限管理系统技术方案.md)
- 房源管理：[`PRD/房源管理/`](./PRD/房源管理/) ｜ [`TECH_STACK/房源管理技术方案.md`](./TECH_STACK/房源管理技术方案.md)
- 客源管理：[`PRD/客源管理/`](./PRD/客源管理/) ｜ [`TECH_STACK/客源管理技术方案.md`](./TECH_STACK/客源管理技术方案.md)
- 楼盘管理：[`PRD/房源管理/楼盘管理模块PRD.md`](./PRD/房源管理/楼盘管理模块PRD.md) ｜ [`TECH_STACK/楼盘管理技术方案.md`](./TECH_STACK/楼盘管理技术方案.md)
- 组织人事：[`PRD/组织人事管理/`](./PRD/组织人事管理/) ｜ [`TECH_STACK/组织人事技术方案.md`](./TECH_STACK/组织人事技术方案.md)
- 系统设置：[`PRD/系统配置/`](./PRD/系统配置/) ｜ [`TECH_STACK/系统设置技术方案.md`](./TECH_STACK/系统设置技术方案.md)（系统管理域已并入"平台管理后台"）

---

## 5. 说明

- 本 README 是入口索引，不替代各域权威文档。
- 若发现索引与实际文件不一致，以实际文件为准，并在同一变更中回补本 README。