# 看房系统（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 用贝壳成交频道兜底