4aca0c7f6f
Some checks failed
Build and Deploy (service.xpcool.com) / build-and-deploy (push) Failing after 5m7s
- 新增 9 张房屋相关数据表（社区/楼宇/房源/价格快照/交易/设施/社区设施/学区/偏好） - 添加菜单权限种子数据并绑定超级管理员角色 - 生成 DAO 层代码和实体对象 - 实现房屋模块 API 接口（社区/房源/看板）和控制器服务层 - 支持多平台软关联匹配、笋盘标记和低可信度标记功能 - 更新超级管理员账号为 xxcool/xxCool@2026 - 调整 RBAC 菜单结构，移除管理员管理功能，新增日志管理菜单 - 修复 RBAC 安全漏洞，确保禁用角色权限失效 - 重构认证模块，将登录相关接口迁移到统一包结构下 - 移除废弃的管理模块和工具类接口定义 - 为通用工具包添加中文注释和文档说明
224 lines
9.6 KiB
Go
224 lines
9.6 KiB
Go
# 看房系统（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 用贝壳成交频道兜底
|