Files
main/.claude/skills/fangjia-openapi-dev/references/database-tables.md
T
admin 106d0cdbad 新增小区第三方均价接口(ApiCode:3004)及测试脚本
- AverageStatistics 新增 xingfuliEsfPrice、maitianEsfPrice 字段
- AverageStatisticsService 新增 findRecentMonths 方法(查询最近N个月数据)
- PropertyController 新增 thirdPartyPriceAction(/property/thirdPartyPrice)
  - 返回幸福里、安居客、房天下、链家、城市房产、吉屋、淘房365、麦田均价
  - 仅取二手房价格,最多回溯3个月补全空值
- 新增 opentest 测试脚本:数据提取 + 多线程接口测试
- 更新 claude 技能文档:修正本地端口、seaweed集合字段说明、Groovy static 限制

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-02 16:27:26 +08:00

11 KiB
Raw Blame History

常用数据表参考

本文档记录开发OpenAPI接口时常用的数据表结构和用途,便于快速查询和复用。

数据库命名规范

@Table 注解格式

在 fangjia-dal 的实体类中,MongoDB 集合通过 JPA 的 @Table 注解来指定:

@Entity
@Table(name = "database.collection")
public class YourEntity implements MongoEntity {
    // ...
}

重要规则:

  • 点之前(.前):数据库名(database)
  • 点之后(.后):集合名(collection)

示例:

// business.open_uri_log → business 数据库,open_uri_log 集合
@Table(name = "business.open_uri_log")

// fangjia_stat.district_stat → fangjia_stat 数据库,district_stat 集合
@Table(name = "fangjia_stat.district_stat")

// fangjia.seaweed → fangjia 数据库,seaweed 集合
@Table(name = "fangjia.seaweed")

数据访问方式

1. 业务项目中(fangjia-open、fangjia-coresite 等)

推荐方式:通过 DAL 层的 Service 和 DAO 访问数据

// 使用 Service 层
@Autowired
private DistrictStatService districtStatService;

DistrictStat stat = districtStatService.findOneDistrictStatsSort(city, region, name, null);

不推荐:直接使用 MongoDB URI 连接数据库

2. Script 项目中(fangjia-script)

可以使用:MongoDB URI 常量直接查询

数据库名 MongoDB URI 常量 服务器地址
business Constants.SEAWATER_MONGO_URI 192.168.0.206:27020
fangjia、fangjia_stat 等 Constants.FANGJIA_MONGO_URI mongo.db.fangjia.com:28017
// Script 项目中可以直接使用 Mongo3Utils
MongoCollection<Document> coll = Mongo3Utils.getDbCollection(
    Constants.SEAWATER_MONGO_URI,
    "business",
    "open_uri_log"
)

原因:Script 项目主要用于数据分析、批处理、测试等场景,需要灵活直接的数据库访问


MongoDB数据表

1. business.open_uri_log

数据库:business (MongoDB 192.168.0.206:27020) 集合名:open_uri_log

作用:记录所有开放平台API的调用日志,包含请求参数、返回结果等

常用字段:

字段名 类型 说明
user_id String 调用用户ID
request_uri String 请求的API路径(如 /address/risk)
parameter_map Document 请求参数(嵌套文档)
res_map Document 返回结果(嵌套文档)
c_date Date 创建时间

访问方式:

Script 项目 - 直接使用 Mongo3Utils 查询:

import com.fangjia.core.Constants
import com.fangjia.core.util.Mongo3Utils

MongoCollection<Document> coll = Mongo3Utils.getDbCollection(
    Constants.SEAWATER_MONGO_URI,
    "business",
    "open_uri_log"
)

// 查询特定用户的API调用记录
Document query = new Document("user_id", "1007569")
    .append("request_uri", "/address/risk")

// 使用projection优化查询
Document projection = new Document("parameter_map", 1).append("_id", 0)
MongoCursor<Document> cursor = coll.find(query)
    .projection(projection)
    .limit(1000)
    .iterator()

使用场景:

  • 提取历史调用数据用于接口测试(Script项目)
  • 分析API调用量和参数分布(Script项目)
  • 排查接口调用问题

2. fangjia_stat.district_stat

数据库:fangjia_stat (MongoDB mongo.db.fangjia.com:28017) 集合名:district_stat

作用:存储小区级别的价格统计数据

常用字段:

字段名 类型 说明
city String 城市
region String 区域
name String 小区名称
avg_price_2b Integer 均价(优先使用,元/平米)
avgPrice Integer 均价(备选,元/平米)
weekend Date 数据更新时间

访问方式:

业务项目 - 通过 Service 层查询:

@Autowired
private DistrictStatService districtStatService;

// 查询最新的小区统计数据
DistrictStat latestStat = districtStatService.findOneDistrictStatsSort(
    city, region, name, null
);

// 优先使用avg_price_2b
Integer avgPrice = null;
if (latestStat.getAvg_price_2b() != null && latestStat.getAvg_price_2b() > 0) {
    avgPrice = latestStat.getAvg_price_2b();
} else if (latestStat.getAvgPrice() > 0) {
    avgPrice = latestStat.getAvgPrice();
}

Script 项目 - 可直接使用 Mongo3Utils 查询:

MongoCollection<Document> coll = Mongo3Utils.getDbCollection(
    Constants.FANGJIA_MONGO_URI,
    "fangjia_stat",
    "district_stat"
)

使用场景:

  • 查询小区参考均价
  • E基金地址匹配接口返回参考价格
  • 房价评估相关接口

3. fangjia.deal_price

数据库:fangjia (MongoDB mongo.db.fangjia.com:28017) 集合名:deal_price

作用:存储房产成交记录

常用字段:

字段名 类型 说明
city String 城市
region String 区域
name String 小区名称
avgPrice Integer 成交单价(元/平米)
totalPrice Integer 成交总价(万元)
成交时间 Date 成交日期

访问方式:

业务项目 - 通过 Service 层查询:

@Autowired
private DealPriceService dealPriceService;

// 查询近半年成交记录
Date halfYearAgo = new Date(System.currentTimeMillis() - 180L * 24 * 60 * 60 * 1000);
Date now = new Date();

List<DealPrice> dealPrices = dealPriceService.findDealPriceList(
    city, region, name, halfYearAgo, now
);

// 找到单价最接近参考均价的成交记录
DealPrice closestDeal = null;
int minDiff = Integer.MAX_VALUE;
for (DealPrice deal : dealPrices) {
    if (deal.getAvgPrice() != null && deal.getTotalPrice() != null) {
        int diff = Math.abs(deal.getAvgPrice() - referencePrice);
        if (diff < minDiff) {
            minDiff = diff;
            closestDeal = deal;
        }
    }
}

Script 项目 - 可直接使用 Mongo3Utils 查询:

MongoCollection<Document> coll = Mongo3Utils.getDbCollection(
    Constants.FANGJIA_MONGO_URI,
    "fangjia",
    "deal_price"
)

使用场景:

  • 查询成交记录
  • 计算典型总价(最接近参考均价的成交总价)
  • 成交数据分析

4. fangjia_stat.region_sell_stat

数据库:fangjia_stat (MongoDB mongo.db.fangjia.com:28017) 集合名:region_sell_stat

作用:存储区域级别的销售价格统计

常用字段:

字段名 类型 说明
city String 城市(简称格式)
region String 区域(简称格式)
avgPrice Integer 区域均价(元/平米)
date Integer 数据日期(yyyyMM格式)
updateDate Date 更新时间

访问方式:

业务项目 - 通过 Service 层查询:

@Autowired
private RegionSellStatService regionSellStatService;

// 需要先格式化城市和区域为简称
String formattedCity = RegionData.formatCity(city);
String formattedRegion = RegionData.formatRegion(formattedCity, district);

// 查询最新区域价格
RegionSellStat regionSellStat = regionSellStatService.findNewestRegionPrice(
    formattedCity, formattedRegion
);

if (regionSellStat != null && regionSellStat.getAvgPrice() != null) {
    Integer avgPrice = regionSellStat.getAvgPrice();
    // 格式化日期
    String updateTime = DateUtil.formatByPattern(
        DateUtil.parseDate(regionSellStat.getDate().toString(), "yyyyMM"),
        "yyyy-MM-dd"
    );
}

Script 项目 - 可直接使用 Mongo3Utils 查询:

MongoCollection<Document> coll = Mongo3Utils.getDbCollection(
    Constants.FANGJIA_MONGO_URI,
    "fangjia_stat",
    "region_sell_stat"
)

使用场景:

  • 查询区域级别参考价格
  • 地址匹配失败时返回区域价格
  • 区域价格趋势分析

5. fangjia.seaweed

数据库:fangjia (MongoDB mongo.db.fangjia.com:28017) 集合名:seaweed (实体类为 District,通过 @DatastoreCategory("district") 标识)

作用:存储小区、写字楼等建筑的基础信息(权威数据源)

常用字段:

字段名 类型 说明
_id ObjectId 小区唯一标识
city String 城市
region String 区域
name String 小区/建筑名称
cat String 分类(district=小区, office=写字楼)⚠️ 注意:字段名是 cat,不是 category
status Integer 状态(0=正常,其他=已删除/无效)
estate_type2 String 物业类型

⚠️ 注意事项:

  • 分类字段名是 cat,不是 category
  • 查询时必须加 status: 0 过滤无效数据,否则会包含已删除的记录

访问方式:

业务项目 - 通过 Service 层查询:

@Autowired
private DistrictService districtService;

// 根据ID查询小区信息
District district = districtService.findById(id);

if (district != null) {
    String city = district.getCity();
    String region = district.getRegion();
    String name = district.getName();
}

Script 项目 - 可直接使用 Mongo3Utils 查询:

MongoCollection<Document> coll = Mongo3Utils.getDbCollection(
    Constants.FANGJIA_MONGO_URI,
    "fangjia",
    "seaweed"
)

// ⚠️ 典型查询:注意用 cat 不是 category,必须加 status=0
Document query = new Document("city", "福州")
    .append("cat", "district")   // ⚠️ 字段名是 cat,不是 category
    .append("status", 0)         // ⚠️ 必须加,过滤已删除/无效数据
Document projection = new Document("_id", 1).append("city", 1)
    .append("region", 1).append("name", 1)

MongoCursor<Document> cursor = coll.find(query)
    .projection(projection)
    .limit(1000)
    .iterator()

使用场景:

  • 根据ID查询小区权威信息
  • 获取小区的城市、区域、名称用于后续查询
  • 提取测试数据(测试脚本中批量获取小区列表)
  • 验证POI信息的准确性

如何记录新数据表

遇到新数据表时,请主动询问用户是否需要记录,格式如下:

我在开发过程中用到了数据表 XXX.YYY,是否需要记录到技能文档中供以后复用?

如果需要,请告诉我:

  1. 这个表的主要作用
  2. 常用的查询场景
  3. 是否有特殊的查询方式或注意事项

记录模板:

### N. database.table_name

**服务器/数据库**:服务器地址或数据库类型

**作用**:简要说明表的用途

**常用字段**:
| 字段名 | 类型 | 说明 |
|-------|------|------|
| `field1` | Type | 说明 |
| `field2` | Type | 说明 |

**连接方式**:(如果有特殊连接方式)
```groovy
// 代码示例

典型查询:

// 常用查询示例

使用场景:

  • 场景1
  • 场景2