房产数据板块建设方案

一、背景与目标

adata 目前覆盖股票、ETF、债券、舆情四大板块，缺少房地产这座与宏观经济紧密联动、与个人财富高度相关的数据金矿。新增房产数据板块后，可以补齐「宏观—地产—股市—债市」的量化分析闭环。

核心目标：建成一个支持 省→市→区县→商圈→小区 五级粒度下钻、覆盖 价格+成交+挂牌+租赁 四维指标的房产数据模块，直接嵌入 adata 的 Python 包体系和 Web 可视化界面。

二、数据源全景分析

中国不存在全国统一的 MLS（多重上市服务）系统，各地房管局的网签数据也是一个信息孤岛。所有可用的数据源分为三个梯队：

2.1 第一梯队：免费开放 API（宏观+70城级别）

优点：免费、权威、稳定。 缺点：粒度仅仅到城市（且只有70个），没有区县级和小区级的数据。

结论：这个作为第一阶段的先发数据源。成本为零，实现 API 封装即可上线。

2.2 第二梯队：商业合作 API（城市→区县→商圈级别）

优点：结构化数据、粒度细、更新频率高。 缺点：需要付费或签订商业合同，成本每月数百到数千元不等。

结论：作为第二阶段的数据补充，按需接入。建议优先评估诸葛找房，因为它是聚合型平台，数据覆盖最广。

2.3 第三梯队：网页爬虫（小区→房源级别）

优点：粒度最细、指标最丰富、能拿到真实成交数据（链家）。 缺点：工程复杂度高，需要 Playwright/Selenium + 住宅代理池 + 反爬对抗，且存在法律合规风险。

结论：作为第三阶段的终极数据方案，仅对少数重点城市（北上广深+省会）开启爬虫采集。

三、实施路线图（分三个阶段）

第一阶段：宏观层（预计2-3天）

数据范围：全国+31省+70大中城市的房价指数及开发投资数据。

技术方案：

• 对接国家统计局 easyquery API，封装到 adata/real_estate/macro/ 模块下
• 核心接口：

# 获取70城新房价格指数（月度）
real_estate.macro.get_70city_new_house_price_index(city="北京", start="2020-01")

# 获取70城二手房价格指数（月度）
real_estate.macro.get_70city_second_hand_price_index(city="北京", start="2020-01")

# 获取分省房地产开发投资数据（年度）
real_estate.macro.get_province_investment(province="广东", year=2023)

# 获取全国商品房销售面积/额（月度）
real_estate.macro.get_national_sales(start="2020-01")

# 列出所有可用指标树
real_estate.macro.list_indicators()

数据表设计：

-- 70城房价指数月度表
CREATE TABLE IF NOT EXISTS real_estate_70city_price_monthly (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    city TEXT NOT NULL,           -- 城市名称
    data_type TEXT NOT NULL,      -- new_house / second_hand
    index_type TEXT NOT NULL,     -- month_on_month / year_on_year / fixed_base
    stat_month TEXT NOT NULL,     -- 统计月份 如 2024-06
    index_value REAL,             -- 指数值
    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(city, data_type, index_type, stat_month)
);

-- 分省房地产开发投资年度表
CREATE TABLE IF NOT EXISTS real_estate_province_annual (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    province TEXT NOT NULL,
    indicator TEXT NOT NULL,      -- 指标名称
    stat_year INTEGER NOT NULL,   -- 统计年份
    value REAL,                   -- 数值
    unit TEXT,                    -- 单位
    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(province, indicator, stat_year)
);

第二阶段：城市明细层（预计3-5天）

在第一阶段稳定后，引入诸葛找房或安居客的商业 API，获取城市→区县→商圈级别的日常挂牌、成交、租赁数据。

数据范围：重点20-30个城市，下钻到区县/商圈。

核心接口：

# 获取城市均价走势（日/周/月）
real_estate.city.get_price_trend(city="上海", district="浦东新区", freq="monthly")

# 获取商圈挂牌量&成交量
real_estate.city.get_district_supply_demand(city="上海", district="浦东新区")

# 获取城市整体租赁价格走势
real_estate.city.get_rental_trend(city="上海", district="浦东新区")

第三阶段：小区精微层（按需启动）

针对重点城市（北京、上海、深圳、广州、杭州）开启链家贝壳爬虫，获取小区级别的成交、挂牌数据。

技术栈：Python + Playwright + 住宅代理池 + Scrapy + SQLite 持久化。

爬虫策略：

• 只爬公开可访问的列表页和详情页
• 请求间隔 3-8 秒，日采集量控制在 5000 页以内
• 使用住宅代理轮换，避免触发 IP 风控
• 数据写入 SQLite，不对外重新分发原始房源数据

核心接口：

# 获取小区均价&走势
real_estate.community.get_community_price_trend(
    city="上海", district="浦东新区", community="陆家嘴花园"
)

# 获取小区历史成交明细
real_estate.community.get_transaction_history(
    city="上海", community="陆家嘴花园", start="2020-01"
)

# 获取小区在售房源列表（匿名化后的统计摘要）
real_estate.community.get_listing_summary(
    city="上海", community="陆家嘴花园"
)

四、代码架构设计

完全遵循 adata 现有的门面模式+模板模式：

adata/real_estate/                  # 新模块目录
├── __init__.py                     # RealEstate 门面类，导出 real_estate 单例
│   class RealEstate:
│       def __init__(self):
│           self.macro = RealEstateMacro()     # 宏观数据
│           self.city = RealEstateCity()       # 城市明细数据
│           self.community = RealEstateCommunity()  # 小区精微数据
│
├── macro/
│   ├── __init__.py                 # RealEstateMacro 聚合类
│   ├── nbs_api.py                  # 国家统计局 easyquery 接口实现
│   └── template.py                 # 列名常量和接口定义
│
├── city/
│   ├── __init__.py                 # RealEstateCity 聚合类
│   ├── zhuge.py                    # 诸葛找房 API 实现
│   └── template.py
│
├── community/
│   ├── __init__.py                 # RealEstateCommunity 聚合类
│   ├── lianjia_spider.py           # 链家爬虫实现
│   └── template.py
│
└── db/
    ├── __init__.py
    ├── schema.sql                  # 建表 SQL
    └── core.py                     # DB 连接和初始化

在顶级 adata/__init__.py 中注册：

from adata.real_estate import real_estate

五、Web 展示方案

在 unified_server.py 中新增数据展示入口：

5.1 导航入口

主页增加「🏠 房产」模块卡片，点击进入 /real-estate 页面。

5.2 数据仪表板

/real-estate/                     # 房产数据总览仪表板
├── /real-estate/overview         # 全国房价热力图 + 关键指标卡片
├── /real-estate/city/{city}      # 城市详情页（房价趋势图+供需分析）
└── /real-estate/community/{id}   # 小区详情页（历史成交+价格走势）

5.3 可视化方案

• 全国房价热力图：基于 Plotly Choropleth，展示70城新房/二手房价格指数
• 城市房价趋势图：Plotly 折线图，展示多城市房价对比
• 区县供需仪表盘：挂牌量 vs 成交量柱状图 + 去化周期
• 小区价格日历：类似 GitHub 贡献图，按日展示价格变化热度

5.4 REST API

为外部量化策略调用提供数据接口：

GET  /api/real-estate/price-index?city=上海&type=new_house&start=2020-01
GET  /api/real-estate/province-investment?province=广东&year=2023
GET  /api/real-estate/community-trend?city=上海&community=陆家嘴花园

六、数据缓存与更新策略

七、成本估算

八、风险与注意事项

• 行政区划变更：中国行政区划频繁调整，需要定期同步民政部最新区划代码，建议内置区划版本管理。
• 数据口径一致性：不同来源的「均价」定义不同（挂牌均价 vs 成交均价 vs 网签均价），展示时必须显式标注数据口径。
• 爬虫合规性：爬取链家/安居客等平台数据存在法律灰色地带，应只采集公开数据、控制频率、不商业转售原始房源信息。
• 数据质量验证：爬虫数据需要与统计局官方数据做交叉验证，设置异常值检测告警机制。

九、下一步行动

• 评审本方案，确认优先城市列表和数据粒度预期
• 确认第二阶段是否采购诸葛找房/安居客商业 API
• 第一阶段立即开工：封装国家统计局 API，搭建 real_estate 模块骨架
• 接入 unified_server.py Web 可视化界面

---

*方案起草日期：2026-06-28*