service.xpcool.com/docs/house-system-design.md

看房系统（House）总设计文档

版本：v1.0　|　日期：2026-08-26　|　状态：开发中（阶段 0/1） 定位：贵阳购房决策辅助系统，从公开房源数据中筛选「最适合自己的房子」。

1. 项目概述

买房的核心矛盾是「信息高度不对称」。本系统通过 采集 → 存储 → 管理 → 可视化 → 推送 五段闭环，把贵阳公开房源数据沉淀成一份可管理、可分析、可对比的个人决策资产。

• 目标城市：贵阳（二线/省会，数据源以贝壳/安居客/房天下 + 住建局网签为主）
• 房源类型：新房 + 二手房都做（两套数据模型并存）
• 核心诉求：房价波动分析、楼盘楼栋级地图、多平台报价对比、个性化打分推荐、Bark 推送

2. 总体架构

2.1 五层架构

应用展示层  房价地图热力 · 楼盘对比看板 · 个性化榜单
分析计算层  价格趋势分析 · 匹配打分排序 · 通勤配套评估
数据治理层  清洗与标准化 · 房源去重对齐(改:软关联) · 小区实体映射
数据存储层  MySQL(house_* 表) · 价格时序快照
数据采集层  多平台采集器 · 调度与限频 · 代理与反反爬

2.2 落地拓扑（贴合现有项目）

贵阳公开数据源(贝壳/安居客/房天下/住建局网签)
        │ 抓取
Python 采集分析服务(独立进程: 采集/清洗/软关联/打分/调度)
        │ 写库
MySQL 共享库(house_* 表)  ←── 与 service 同库
        │ 读写
service.xpcool.com(GoFrame v2 · house 模块 REST API)
        ├── REST ──→ admin.xpcool.com(Vue3+Vben: 管理列表 + 可视化看板)
        └── 推送 ──→ Bark(苹果)

关键决策：Python 只负责「把数据搞干净写进库 + 算分」，不对外提供业务 API；所有查询/推送由 Go 的 house 模块统一暴露，保持单一出口。

3. 技术选型

层	选型	理由
后端	GoFrame v2.10（现有 service 栈）	复用分层 + RBAC + gf gen dao
数据库	MySQL 8（现有同库）	贵阳数据量级（房源几十万/快照百万）单机够用，不引 PostGIS/TimescaleDB
前端	Vben Admin 5（web-tdesign）+ echarts@6 + vxe-table@4	全部现成依赖，零新增
地图	腾讯地图 GL JS（合规）+ DataV GeoJSON	底图合规、支持 MultiMarker/热力/多边形
采集分析	Python（Scrapy/httpx + pandas）	爬虫与数据分析生态最强
推送	Bark（自建 Server 到腾讯云 / 官方免费版）	苹果原生推送，一条 HTTP 即可

4. 数据源规划（贵阳）

类别	数据源	备注
二手房挂牌	贝壳 gy.ke.com、安居客、房天下、58	贝壳最规整，MVP 首选
成交/网签	贵阳市住建局网签备案、贝壳成交频道	成交价是真实价，最大风险点
新房备案价	住建局预售许可 + 一房一价备案	新房「真价格」来源
配套/通勤	高德/百度地图 API	地铁、学校、商圈 POI + 真实通勤时间
学区划片	贵阳市/各区教育局划片文件	年度版本，半自动采集

5. 数据模型（9 张表）

5.1 house_community 小区/楼盘

字段	类型	说明
id	BIGINT UNSIGNED PK
name	VARCHAR	小区名
region	VARCHAR	区县（云岩/南明/观山湖/花溪…）
business_district	VARCHAR	板块
address / lng / lat	VARCHAR / DECIMAL(10,6)	定位（GCJ-02）
build_year / households	INT	建成年份/户数
plot_ratio / green_rate	DECIMAL	容积率/绿化率
property_company / property_fee	VARCHAR / DECIMAL	物业/物业费
developer	VARCHAR	开发商

5.2 house_building 楼栋

字段	说明
community_id	所属小区
building_no	栋号
units / total_floors / elevator_count / ladder_ratio	单元/总层/电梯/梯户比
building_type	板楼/塔楼
lng / lat	楼栋级坐标（三级落地：小区中心→楼栋图解析→重点盘人工校准）

5.3 house_listing 房源/挂牌（核心）

字段	说明
community_id / building_id / house_no	归属
layout / area / usable_area	户型 / 建面 / 套内（建面套内要标准化）
orientation / floor / total_floors / decoration	朝向/楼层/总层/装修
total_price / unit_price / list_price	总价/单价/挂牌价
source / source_house_id / source_url	来源平台（跨平台不去重）
match_group_id	疑似同房源软关联（对比用）
on_market_days / price_change_count	挂牌天数/调价次数
status	在售/下架/成交
confidence / is_bargain	可信度标记 / 笋盘标记

多平台对比策略：同平台 source+source_house_id 唯一（防重复抓）；跨平台各存一条，用「小区+楼栋+户型+面积±3%+楼层」算相似度打 match_group_id，用于「疑似同房源」对比视图（不合并）。

5.4 house_price_snapshot 价格快照（时序）

listing_id + snap_date 唯一；list_price / deal_price 分列。趋势分析命脉，长期保留 1–2 年。

5.5 house_transaction 成交记录

deal_price / deal_unit_price / list_days（挂牌到成交天数）/ deal_date。

5.6 house_facility 配套 POI

name / type(地铁/学校/医院/商圈) / lng/lat / line(地铁线路)。

5.7 house_community_facility 小区-配套关系

community_id + facility_id，distance(米) + commute_minutes(通勤分钟)。

5.8 house_school_district 学区划片

school_name / community_id / district_polygon(GeoJSON) / district_year(划片年度，版本化)。

5.9 house_preference 用户偏好画像

budget_min/max / area_min/max / layouts(JSON) / subway_lines(JSON) / school_required / commute_target / commute_limit_min / weights(权重 JSON)。

6. 后端模块设计（service.xpcool.com）

6.1 目录落位

api/house/<resource>/<resource>.go        # 契约(g.Meta path/method)
internal/controller/house/*.go            # 适配层
internal/service/house/<resource>/        # 领域服务(接口+实现+Register)
internal/model/dto/house.go               # 服务边界 dto
internal/model/{entity,do}                # gf gen dao 生成
manifest/sql/010_house_tables.sql         # 建表
manifest/sql/011_house_menu.sql           # 菜单+权限种子

6.2 接口清单（全 POST 动作式，前缀 /api/service/admin/house）

管理 CRUD：

/house/community/{list|create|update|delete}
/house/listing/{list|create|update|delete|batch-mark}
/house/snapshot/{list}
/house/transaction/{list}
/house/facility/{list|create|update|delete}
/house/district/{list|create|update|delete}
/house/crawl-task/{list|trigger|log}

看板聚合/筛选（统一 FilterDto 入参）：

/house/dashboard/{overview|map-points|price-trend|aggregate-region}
/house/compare
/house/rank

6.3 权限

admin_menu：type=1 菜单（component 指向前端组件）+ type=2 API 权限（path=POST /api/service/admin/house/...）；admin_role_menu 绑定超管（role_id=1）。

7. 前端模块设计（admin.xpcool.com）

7.1 页面

分组	页面	组件路径
数据管理	小区/楼盘管理	house/community/index
数据管理	房源管理（筛选/标记/批量）	house/listing/index
数据管理	价格快照/成交/配套/学区	house/data/index（后续拆分）
可视化看板	看板（筛选器+图表联动）	house/dashboard/index

7.2 交互

• 管理列表：查询表单 + vxe-table + 分页 + 行内操作 + 批量，复用 RBAC
• 看板：全局筛选器（区域/价格/户型/面积/地铁/学区/通勤）驱动图表联动；筛选器→图表、图表交叉过滤、列表↔地图双向；状态放 Pinia

8. Python 采集分析服务

house-data/
├── crawlers/   各平台采集器
├── pipeline/   清洗→软关联→标准化→入库
├── analysis/   pandas 趋势/议价空间/打分
├── scheduler/  APScheduler 调度 + 限频
└── notify/     触发 Bark

只写库，不对外 API；独立 git 仓库（建议 E:\xxcool\project\house-data\）。

9. 可视化设计（地图图层）

底图腾讯地图 GL JS，自下而上叠加：区县/板块边界(DataV GeoJSON) → 地铁线(1/2/3号线 Polyline) → 学区划片(polygon，年度版本) → 楼盘/楼栋点(MultiMarker) → 价格热力(可切换)。

10. 推送设计（Bark）

触发	level	group	附 url
降价>3%	timeSensitive	降价	跳房源对比页
新房上架	active	新房	跳详情
划片变更	timeSensitive	学区	跳小区
每日汇总	passive	汇总	跳看板

11. 分阶段路线图

阶段	周期	交付
0 方案定稿	1–2 天	建表 + gf gen dao + Python 骨架
1 MVP	~1 周	贝壳二手房挂牌 + 价格快照；房源列表/详情 API；列表 + 趋势图
2 分析	~1 周	成交/网签 + 软关联对比 + 地图热力 + 楼盘对比
3 决策	~1 周	新房备案价 + 学区/配套 + 偏好打分
4 自动化	~1 周	Bark 推送 + 迁腾讯云 7×24

12. 合规与风险

• 地图：仅腾讯/高德/百度/天地图；区县边界用 DataV 审图号数据；key 走代理不外泄；不采集他人个人位置
• 爬虫：遵守 robots、低频、代理池、只存公开信息、个人自用
• 最大风险：贵阳网签/成交数据公开程度不如一线，MVP 用贝壳成交频道兜底