面向中小房产中介门店的内部后台管理系统：管理房源、客户、带看，并通过数据看板掌握门店经营全貌。
- 前端：React 18（CDN + Babel，无构建，纯静态）—— 来自设计阶段产出，保留原样
- 后端：Python FastAPI + SQLAlchemy + Alembic + SQLite + JWT
- 角色：管理员（全门店 + 员工管理）/ 经纪人（仅本人客户与带看）
完整需求见 PRD.md，项目维基见 docs/PROJECT_WIKI.md。
| 模块 | 说明 |
|---|---|
| 数据看板 | 指标卡（在售房源/新增客户/带看/成交/成交额）、成交趋势、房源状态分布、客户来源分布、待办与经纪人排行 |
| 房源管理 | 列表筛选、详情、新增/编辑、状态流转（在售/在租/已售/已租/下架） |
| 客户 CRM | 列表筛选、档案与购租需求、跟进时间线、转交、电话脱敏 |
| 带看预约 | 列表 / 日历双视图、新建带看（多房源）、带看反馈、状态流转 |
| 员工管理 | 仅管理员：增改员工、角色权限、停用/启用、重置密码 |
cd backend
pip install -r requirements.txt
cp .env.example .env # 首次：配置环境变量
alembic upgrade head # 创建数据库 schema（迁移）
python -m app.seed # 灌入演示数据
python -m uvicorn app.main:app --reload --port 8000- API 文档（Swagger）：http://127.0.0.1:8000/docs
- 健康检查：http://127.0.0.1:8000/api/health
cd frontend
python -m http.server 5500 # 任意静态服务器均可
# 浏览器打开 http://127.0.0.1:5500| 角色 | 手机号 | 范围 |
|---|---|---|
| 管理员 | 13800138001 |
全门店数据 + 员工管理 |
| 经纪人 | 13700137003 |
仅本人客户与带看 |
real_estate/
├── PRD.md # 产品需求文档
├── frontend/ # 无构建静态前端（React via CDN）
│ ├── index.html # 入口（Babel 运行时编译）
│ ├── data.js # API 客户端 + 全局数据缓存(window.DB)
│ ├── app.js / ui.js / layout.js / charts.js / icons.js
│ └── pages/ # 各模块页面
├── backend/ # FastAPI 后端
│ ├── app/ # 业务代码（models/schemas/routers/...）
│ ├── migrations/ # Alembic 数据库迁移
│ ├── tests/ # pytest 测试（31 个）
│ └── README.md # 后端详细说明
└── docs/ # 架构 / 维基 / 决策 / 术语 / 变更日志
- 前后端分离：前端纯静态托管，后端提供
/apiJSON 接口，JWT 鉴权。 - 前端集成策略：登录后调
/api/bootstrap一次性拉取全量数据灌入window.DB，页面读取零改动；写操作调window.API.*后refreshDB()刷新。 - 权限：后端依赖注入强制数据范围（经纪人只见本人数据），前端按角色渲染。
- 数据库 schema：由 Alembic 管理（
alembic upgrade head），应用启动不自动建表。
详见 docs/architecture/（技术选型 / 数据库设计 / API 设计）与后端 backend/README.md。
cd backend && python -m pytest -q # 31 个测试，核心业务逻辑覆盖率 96%本项目使用 Claude Code 工作流模板进行开发，完整指令与流程见 CLAUDE.md。