360 Ghar - Real Estate MCP Server

360 Ghar 后端

为 360 Ghar 统一房地产平台提供支持的高性能现代后端。该 API 基于 FastAPI 和 PostgreSQL 构建，服务于三个集成模块：

• 360 Ghar Core：房地产交易平台，提供房屋买卖和租赁服务，支持滑动式发现、看房和经纪人协调
• 360 Stays：短期住宿预订平台，适用于酒店、度假租赁和临时住宿
• Property Management：面向房东和物业经理的综合物业管理系统（租约、租金收取、维护、报告）

目录

• 关于项目
• 主要功能
• 技术栈
• 项目结构
• API 端点
• 开始使用
• 使用 Docker 运行
• 环境配置
• API 文档
• MCP HTTP 服务
• 关键实现细节
• 参与贡献
• 许可证

关于项目

360 Ghar 是一个统一的房地产平台，服务于房产的完整生命周期：

• 360 Ghar Core 通过引人入胜的滑动式界面，结合强大的地图搜索和专业经纪人协助，革新房屋买卖和租赁的房产发现体验。
• 360 Stays 提供完整的短期住宿预订系统，具备空房查询、动态定价以及酒店和度假租赁的住客管理功能。
• Property Management 为房东和物业经理提供租户管理、租约跟踪、租金收取、维护处理和财务报告工具。

三个模块共用后端基础设施、用户身份验证和房产数据库。

概览视频

一段 2-3 分钟的无声演示，介绍平台的六个模块和架构。请阅读完整 Wiki。

主要功能

360 Ghar Core（房地产交易平台）

• 类似 Tinder 的房产滑动浏览：通过直观的滑动界面，对房产表示喜欢或跳过
• 高级房产搜索：统一端点，支持地理空间、全文和筛选搜索
• 看房预约：由经纪人管理看房协调，并自动分配经纪人
• 经纪人管理：完善的经纪人系统，支持负载均衡和绩效跟踪
• 用户个性化：根据用户互动和搜索历史学习偏好

360 Stays（短期住宿预订）

• 短期住宿预订：完整的预订系统，支持空房查询和定价
• 动态定价：可配置每日费率和最短入住要求
• 住客管理：覆盖从预订到退房的完整预订生命周期

Property Management

• 租户与租约管理：跟踪租户、租约和租赁申请
• 租金收取：以手动操作为主的租金台账，支持生成费用和跟踪付款
• 维护请求：管理房产维护工单
• 文档保险库：安全存储租约、收据和房产文件
• 财务报告：租金明细表、收入报表、损益表和入住率报告

技术亮点

• 现代且快速：基于 FastAPI 构建，性能出色，并提供自动 API 文档
• 全异步：从 API 到数据库操作均采用异步架构
• 地理空间能力：使用 PostgreSQL + PostGIS 高效执行基于位置的查询
• 安全认证：集成 Supabase Auth，以手机号作为主要认证方式
• 性能优化：专为兼容 PgBouncer 和可扩展的连接池而设计
• 可用于生产环境：集成 Sentry，提供全面的日志记录和错误处理
• 容器化：全面支持 Docker，并通过 Docker Compose 进行开发

技术栈

类别	技术
后端框架	FastAPI
数据库	PostgreSQL + PostGIS
ORM	SQLAlchemy 2.0+ (Async)
数据验证	Pydantic
身份验证	Supabase Auth
缓存	Redis（可选）
迁移	Supabase Migrations
可观测性	Sentry
容器化	Docker 和 Docker Compose
地理空间	GeoAlchemy2

项目结构

app/
├── api/                 # API endpoints and routing
│   └── api_v1/
│       └── endpoints/   # Individual endpoint modules
├── config/              # Compatibility config package; implementation remains in core/config.py
├── core/                # Core components (config, db, auth, logging)
├── infrastructure/      # App factory helpers, adapters, lifespan, middleware wiring
├── middleware/          # Custom middleware (rate limiting, security)
├── models/              # SQLAlchemy ORM models and enums  
├── modules/             # Reserved namespace for future physical domain packages
├── schemas/             # Pydantic schemas for data validation
├── services/            # Business logic and database operations (legacy implementation layer)
├── shared/              # Reserved namespace for future physical shared packages
└── utils/               # Utility functions

supabase/
└── migrations/          # Database schema migrations

populate_data/           # Legacy data files (preserved for reference)
seed_data/               # Data seeding system (hardcoded, seed, generated categories)
tests/                   # Test files

API 端点

所有端点的前缀均为 /api/v1。

🔑 身份验证模型

• 客户端直接使用 Supabase Auth SDK 进行身份验证（手机号优先，电子邮件可选）。
• 受保护的路由要求后端提供 Authorization: Bearer <supabase_access_token>。
• 后端不再提供 /api/v1/auth/* 用户会话端点。

👤 用户（/users）

• GET /profile/：获取当前用户资料
• PUT /profile/：更新用户资料信息
• PUT /preferences/：更新房产搜索偏好
• PUT /location/：更新用户当前位置

🏠 房产（/properties）

• GET /：使用地理空间、文本搜索和高级筛选的统一房产搜索
• GET /recommendations/：获取个性化房产推荐
• GET /{property_id}/：获取房产详情
• POST /：创建房产（已认证用户）
• PUT /{property_id}/：更新房产（房产所有者）
• DELETE /{property_id}/：删除房产（房产所有者）

↔️ 滑动（/swipes）

• POST /：记录房产滑动操作（喜欢/跳过）
• GET /：获取滑动历史，支持完整的搜索和筛选功能
• DELETE /undo/：撤销上一次滑动操作
• PUT /{swipe_id}/toggle/：切换之前滑过的房产的喜欢状态
• GET /stats/：获取用户滑动统计信息

📅 看房（/visits）

• POST /：预约看房
• GET /：列出用户的看房安排（全部/即将进行/过往）
• GET /{visit_id}/：获取看房详情
• POST /reschedule/：重新安排已有的看房
• POST /cancel/：取消已预约的看房

🏨 预订（/bookings）

• POST /：创建短期住宿预订
• GET /：列出用户的预订
• GET /{booking_id}/：获取预订详情
• POST /check-availability/：检查房产是否可用
• POST /calculate-pricing/：获取预订价格明细
• POST /cancel/：取消预订

🧑‍💼 经纪人（/agents）

• GET /assigned/：获取分配给用户的经纪人
• POST /assign/：将经纪人分配给用户（如果未指定经纪人，则自动分配）
• GET /available/：列出可用的经纪人
• GET /{agent_id}/：获取经纪人详情
• GET /{agent_id}/stats/：获取经纪人绩效统计

🏢 房产管理（/pm）

• /pm/dashboard：资产组合概览和指标
• /pm/properties：管理房产的增删改查
• /pm/tenants：租户目录
• /pm/applications：租房申请和表单
• /pm/leases：租约管理
• /pm/rent：租金账单和付款
• /pm/expenses：费用跟踪
• /pm/maintenance：维修请求
• /pm/documents：文档库
• /pm/inspections：房产检查
• /pm/reports：财务报告

入门指南

前置条件

• Python 3.12+
• Docker 和 Docker Compose
• 用于身份验证的 Supabase 项目

本地开发设置

1. 克隆代码库：

   git clone https://github.com/your-username/360ghar-backend.git
   cd 360ghar-backend
   

2. 安装依赖项：

   选项 A：使用 uv（推荐）

   # Install uv if not already installed
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Install dependencies (reads pyproject.toml)
   uv sync
   

   选项 B：使用 pip

   # Create virtual environment
   python -m venv .venv
   
   # Activate it (Linux/Mac)
   source .venv/bin/activate
   # Or on Windows:
   # .venv\Scripts\activate
   
   # Install dependencies
   uv sync
   

   注意： 此项目使用 uv 管理依赖项。依赖项定义在 pyproject.toml 中，并锁定在 uv.lock 中。

3. 设置环境变量：

   cp .env.example .env
   

   编辑 .env 文件，填写数据库、Supabase 和其他凭据。

4. 启动数据库服务：

   docker-compose up -d db redis
   

5. 应用数据库迁移：

   supabase db push
   

6. 加载示例数据（可选）：

   # Load all seed data (hardcoded + generated)
   uv run python seed_data/01_load_all.py
   
   # Quick mode — skip generated activity
   uv run python seed_data/01_load_all.py --only hardcoded,seed
   
   # Clear and reload
   uv run python seed_data/02_clear_data.py --confirm
   uv run python seed_data/01_load_all.py
   

7. 启动应用：

   使用 uv 时（推荐）：

   # Run with uv (no need to activate virtual environment)
   uv run python run.py
   
   # Or using FastAPI CLI with hot reload (recommended for development)
   uv run fastapi dev app/main.py --port 3600 --host 0.0.0.0
   

   使用 pip 时（已激活虚拟环境）：

   # Run directly
   python run.py
   
   # Or using FastAPI CLI with hot reload (recommended for development)
   fastapi dev app/main.py --port 3600 --host 0.0.0.0
   

API 将在 http://localhost:3600 上提供服务。

💡 开发提示：FastAPI CLI 可提供更出色的热重载性能和额外的开发功能。建议在活跃开发时使用。

MCP HTTP 服务

后端为 AI 助手和支持 MCP 的客户端提供 Model Context Protocol（MCP）HTTP 服务。

端点

端点	用途
/mcp	用户 MCP 服务（业主、租户、普通用户）
/mcp-admin	管理员 MCP 服务（Agent、管理员）

身份验证

两个服务均使用 OAuth 2.1 身份验证（通过 Supabase 使用手机号和密码）：

• 授权： GET /mcp/oauth/authorize（基于浏览器的登录和授权页面）
• 令牌： POST /mcp/oauth/token
• 授权服务器元数据： GET /.well-known/oauth-authorization-server/mcp/oauth

客户端配置

面向终端用户应用：

{
  "mcpServers": {
    "ghar360": {
      "transport": "http",
      "url": "https://api.360ghar.com/mcp"
    }
  }
}

面向 Agent／管理员应用：

{
  "mcpServers": {
    "ghar360-admin": {
      "transport": "http",
      "url": "https://api.360ghar.com/mcp-admin"
    }
  }
}

配置完成后，客户端将在浏览器中发起 OAuth 流程；授权后，即可通过 MCP 调用房产搜索、滑动浏览和预约看房等工具。

使用 Docker 运行

要在容器中运行整个服务栈：

# Build and start all services
docker-compose up --build

# Or run in detached mode
docker-compose up -d --build

环境配置

根据 .env.example 创建 .env 文件：

# Database Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/ghar360

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_PUBLISHABLE_KEY=your_publishable_key
SUPABASE_SECRET_KEY=your_service_role_key
# Storage uses Cloudinary (configured via CLOUDINARY_* env vars)

# JWT Configuration
SECRET_KEY=your_jwt_secret_key
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Optional Services
REDIS_URL=redis://localhost:6379
SENTRY_DSN=your_sentry_dsn_here
ENABLE_SENTRY_TEST_ENDPOINT=false

# Environment
ENVIRONMENT=development
 
# Push Notifications (FCM + Supabase)
FIREBASE_PROJECT_ID=your_firebase_project_id
GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account.json
ENABLE_NOTIF_SCHEDULER=false
NOTIF_SCHED_TZ=Asia/Kolkata

# Vector Embeddings / Semantic Search
GOOGLE_API_KEY=
GEMINI_EMBED_MODEL=gemini-embedding-2
VECTOR_SYNC_ENABLED=true
# Either provide CRON schedule or interval seconds (defaults to CRON below)
VECTOR_SYNC_CRON=*/10 * * * *
VECTOR_SYNC_INTERVAL_SECONDS=300
VECTOR_SYNC_BATCH_SIZE=500
VECTOR_SYNC_MAX_RETRIES=3

### One-time backfill
Run a single incremental sync pass (first run will process all properties):

```bash
uv run python -m app.vector.backfill

该服务会创建一个 property_embeddings 表（pgvector），并在 vector_sync_state 中跟踪增量进度。

## API Documentation

Once running, access the interactive API documentation:

- **Swagger UI**: [http://localhost:3600/api/v1/docs](http://localhost:3600/api/v1/docs)
- **ReDoc**: [http://localhost:3600/api/v1/redoc](http://localhost:3600/api/v1/redoc)
- **OpenAPI YAML**: [http://localhost:3600/api/v1/openapi.yaml](http://localhost:3600/api/v1/openapi.yaml)

Additional endpoints:
- **Health Check**: [http://localhost:3600/health](http://localhost:3600/health)
- **Config Info**: [http://localhost:3600/config](http://localhost:3600/config)

### Notifications API

- `POST /api/v1/notifications/devices/register` — Register or refresh device token (uses auth header when present)
- `POST /api/v1/notifications/send/token` — Send to a single token (admin only)
- `POST /api/v1/notifications/send/user` — Send to all tokens for a user (admin only)
- `POST /api/v1/notifications/send/topic` — Broadcast to an FCM topic (admin only)
- `POST /api/v1/notifications/send/bulk` — Bulk send to up to 500 tokens (admin only)
- `POST /api/v1/notifications/deliveries/{delivery_id}/opened` — Mark a delivery as opened

## Key Implementation Details

### Authentication System
- **Phone-First Authentication**: Uses phone numbers as primary identifiers with Supabase Auth
- **JWT Token Validation**: Local token verification for optimal performance
- **Flexible Verification**: Supports both email and phone verification
- **User Sync**: Automatic synchronization between Supabase and local database

### Database Architecture
- **Async SQLAlchemy 2.0+**: Modern async database operations
- **PostGIS Integration**: Efficient geospatial queries with proper indexing
- **PgBouncer Ready**: Configured for production connection pooling
- **Full-Text Search**: PostgreSQL native text search capabilities
- **Comprehensive Indexing**: Optimized indexes for common query patterns

### Property Search System
- **Unified Search Endpoint**: Single endpoint supporting multiple search types
- **Geospatial Optimization**: PostGIS `ST_DWithin` for radius-based searches
- **Full-Text Search**: PostgreSQL TSVECTOR for relevant text matching
- **Semantic Search**: Hybrid vector + text relevance scoring for richer discovery
- **Advanced Filtering**: Support for 25+ property filters
- **Pagination**: Efficient cursor-based pagination for large datasets
- **Endpoints**: `GET /api/v1/properties` (set `semantic_search=true&q=` for hybrid) and `GET /api/v1/properties/semantic-search` (pure semantic + filters)

### Agent Management
- **Auto-Assignment**: Round-robin agent assignment based on workload
- **Load Balancing**: Distributes users across available agents
- **Performance Tracking**: Comprehensive agent statistics and metrics
- **Availability Management**: Real-time agent availability tracking

### Performance Optimizations
- **Async Throughout**: Non-blocking operations from API to database
- **Efficient Queries**: Optimized database queries with proper joins and indexes
- **Caching Ready**: Redis integration for caching expensive operations
- **Error Handling**: Comprehensive error handling with Sentry integration

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

---

**360 Ghar Development Team** - [[email protected]](mailto:[email protected])

Project Link: [https://github.com/your-username/360ghar-backend](https://github.com/your-username/360ghar-backend)