房地产房源信息收集与可视化分析 | Real Estate Filing Query

房地产房源与备案价数据的查询、标准化与可视化分析工作流：「定位项目→定位数据源→提取→标准化→多 Sheet Excel 报告→跨期对比与异常告警」，可迁移到不同城市/平台的公开房源信息公示。所有采集须遵守平台服务条款、robots 与适用法律，仅用于公开公示数据。Keywords: real estate listing data, filing price, presale, multi-sheet Excel report, visualization.

房地产房源信息收集与可视化分析

合规前提：本工作流仅用于采集各城市住建/房管部门依法主动公开公示的房源、备案价等数据。任何采集行为都必须遵守目标平台的《服务条款》、robots 协议及所在司法辖区的法律法规；不得尝试规避、绕过或破坏平台已设置的访问控制、身份认证或速率限制。若某平台要求授权登录、内网可达或明确禁止自动化访问，应停止自动采集、改以人工合规方式获取，或放弃该数据源。

把"定位项目 → 定位数据源 → 提取 → 标准化 → 可视化统计 + 跨期对比 + 异常告警" 的方法封装为可复用工作流。核心方法论跨城市通用；具体数据源端点与字段随平台变化， 需按同法重新探查（参考文档给出一套已验证的探查基准，仅作示例，不含任何绕过访问控制的做法）。

何时使用

• 采集某个房地产项目（楼盘）的全部房源数据并产出 Excel 报告。
• 需要做日/周/月/季的去化对比、价格/状态突变告警。
• 把同样的"定位 + 标准化 + 统计"方式套用到新城市、新平台、新项目。

工作流（SOP）

1. 定位列表/搜索入口：在平台内找到"项目列表/在售楼盘搜索"页（哈希路由或独立路径），定位其数据接口（多数平台为单页应用，数据经异步接口返回，可用浏览器自动化拦截响应来读取公开返回的数据）。
2. 搜索项目名 → 拿全预售证：列表接口返回每条的 项目ID(ysProjectId) + 预售证ID(preSellId) + 预售证号。一个项目常有多张预售证、各证 ysProjectId 可能不同，务必拿全，否则丢楼栋。
3. 逐证访问详情页：用 详情页URL?项目ID&预售证ID 构造地址。详情页会自动发起楼栋/单元枚举接口：
   • 楼栋列表接口 → 楼栋名与楼栋ID
   • 单元/楼层枚举接口 → 单元名列表与楼层列表 读取页面自动发起的公开响应来发现全部楼栋与全部单元。
4. 逐楼栋、逐单元取数（关键，不可漏）：房源接口通常是 POST，请求体带 楼栋ID + 单元 过滤，默认只返回当前选中单元（通常是 1单元）。务必对每个 (楼栋, 单元) 组合各发一次请求，否则会大面积漏栋漏单元。遍历方式：
   • 用会话令牌（从任意公开请求 URL 提取）在该上下文中 POST 该接口；
   • 楼栋切换：触发新的单元枚举，再取该栋单元。
5. 拦截并提取房源：房源响应按楼层分组 data:[{floor, list:[house,...]}]，提取须遍历 data[].list；最后按 (楼栋,单元,楼层,房号) 去重。
6. 标准化字段：映射到 楼栋/楼层/房号/建筑面积/套内/分摊/备案总价/备案单价/状态/合同编号。
7. 写历史快照：把当前聚合（总套数、各状态计数、均价、按 日期/周/月/季 分桶）写入 history/snapshots.json，存聚合不存全量。
8. 生成 Excel：≥5 Sheet（房源明细 / 统计分析 / 分析总结 / 数据变化对比 / 异常与告警）。
9. 异常与对比：用上一快照做 delta 检测突变（总套数/期房待售/备案均价），区分 异常/提示 两级；首跑无基准不报。

关键工程约定

• 平台多为单页应用 + 动态令牌，纯静态直连常不可用 → 需用浏览器自动化读取页面已公开返回的接口数据（方法见参考文档）。
• request/response handler 用 x.url，不是 x（对象不可直接 in 字符串）。
• ⚠️ 房源接口按「楼栋+单元」范围返回（最易漏的坑）：POST 带 单元 过滤，默认仅返回 1单元。某项目 1栋有 5 单元共 2746 套，若只取默认 1单元会漏掉 2293 套（占 84%）。必须枚举全部楼栋+全部单元、逐组合取数并去重。
• 枚举接口不能简单直连：楼栋/单元枚举接口直接请求会报错，必须依赖页面加载/切换楼栋时自动发起的响应来读取；只有房源接口可逐单元 POST。
• 价格行为：很多平台只给"期房待售"公开备案价，已备案/已售等不公开 → 缺失价是正常，勿当异常；缺失单价可用 总价/面积 回算。
• 列表页先于详情页：详情页接口只返回当前预售证数据，从详情页挖不到其他证/楼栋；但详情页内要主动遍历楼栋/单元。
• ⚠️ "lite" 不能作为自动化(automation)的 modelId："lite" 是 Agent 工具的模型变体名，自动化运行时不认，设成 "lite" 会导致定时任务启动失败、完全不执行（实测：8/7 设置后 8/8 全天 + 8/9 上午的任务全部缺席）。自动化 modelId 需用具体模型标识符或 "default"；在确认某 modelId 对自动化有效前，勿盲目设置。交互式 Agent 调用仍可用 model: "lite" 变体省钱。
• 历史快照去重：save_history() 应按"日期+小时"去重（同小时只留最新一条），避免短时多次运行（如手动+自动化撞车）导致快照堆积膨胀。

可复用资源

• references/real-estate-guide.md：完整技术参考（示例平台的列表/房源接口、字段映射表、状态取值、价格行为、脚本骨架函数、避坑清单、复制粘贴提示词）。
• 项目脚本骨架（换项目只改配置与字段映射，逻辑零重写）：PERMITS 列表遍历、compute_snapshot() 聚合快照、find_baseline() 取对比基准、detect_anomalies() 突变检测、add_comparison_sheet() / add_alert_sheet() 生成对比/告警 Sheet。