106d0cdbad
- 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>
523 lines
17 KiB
Markdown
523 lines
17 KiB
Markdown
---
|
||
name: fangjia-openapi-dev
|
||
description: 房价开放平台(fangjia-open)接口开发技能。用于开发基于估家科技开放平台的RESTful API接口。当用户需要:(1) 开发新的OpenAPI接口,(2) 阅读接口需求文档并生成代码,(3) 生成OpenAPI接口文档,(4) 分析接口需求并给出开发建议时使用此技能。支持从Word/PDF需求文档自动提取接口信息、生成Controller/Service/DAO代码、生成API文档。
|
||
---
|
||
|
||
# 估家科技OpenAPI接口开发
|
||
|
||
本技能帮助开发房价开放平台(fangjia-open)的RESTful API接口,包括需求分析、代码生成、文档编写全流程。
|
||
|
||
## 何时使用此技能
|
||
|
||
- 用户提供接口需求文档(Word/PDF/Markdown)
|
||
- 用户要求开发新的OpenAPI接口
|
||
- 用户需要生成API接口文档
|
||
- 用户询问"如何开发XXX接口"
|
||
|
||
## 开发流程
|
||
|
||
### 阶段1:需求分析
|
||
|
||
**1.1 读取需求文档**
|
||
|
||
如果用户提供Word/PDF文档:
|
||
```bash
|
||
# 使用pandoc转换为Markdown
|
||
pandoc "文档路径.docx" -o "文档路径.md"
|
||
# 然后读取转换后的Markdown文件
|
||
```
|
||
|
||
**1.2 提取关键信息**
|
||
|
||
从需求文档中提取:
|
||
- 接口功能描述
|
||
- 输入参数(参数名、类型、是否必填、说明)
|
||
- 输出字段(字段名、类型、描述)
|
||
- 业务逻辑要求
|
||
|
||
**1.3 检查缺失信息**
|
||
|
||
必须向用户确认以下信息(如果文档中没有):
|
||
|
||
| 信息项 | 询问示例 |
|
||
|-------|---------|
|
||
| **接口URL** | "文档中没有指定接口URL,建议使用 `/property/priceQuery`,您确认吗?" |
|
||
| **数据来源** | "请问数据来自哪里?MongoDB的哪个Collection?还是MySQL的哪个表?" |
|
||
| **Service层** | "是否有现成的Service可以调用?如果没有,需要在哪个业务模块下创建?" |
|
||
| **DAO层** | "是否有现成的DAO?如果需要新建,数据库是MongoDB还是MySQL?" |
|
||
|
||
**1.4 给出合理性建议**
|
||
|
||
检查以下方面并给出建议:
|
||
- ✅ 参数命名是否符合驼峰命名规范
|
||
- ✅ 必填/可选参数设置是否合理
|
||
- ✅ 返回字段是否完整(建议添加时间戳、匹配置信度等)
|
||
- ✅ 是否考虑了异常情况(如地址未匹配)
|
||
|
||
---
|
||
|
||
### 阶段2:代码开发
|
||
|
||
按照顺序开发:**DAO → Service → Controller**
|
||
|
||
**注意**:由于返回字段使用下划线命名,通常**不需要创建专门的Model类**,直接使用`UniversalDto`封装返回结果。
|
||
|
||
**2.1 开发DAO层(如需要)**
|
||
|
||
- 优先询问是否有现成的DAO可用
|
||
- 如需新建,位置:`projects/fangjia-dal/src/main/java/com/fangjia/dal/`
|
||
- 根据数据库类型选择基类(AbstractMongoDao / AbstractSqlDao)
|
||
|
||
**2.2 开发Service层**
|
||
|
||
位置:`projects/fangjia-service/src/main/java/com/fangjia/service/{业务模块}/`
|
||
|
||
必须创建:
|
||
1. Service接口 - 参考 [code-templates.md](references/code-templates.md) "Service 接口模板"
|
||
2. Service实现类 - 参考 [code-templates.md](references/code-templates.md) "Service 实现类模板"
|
||
|
||
**注意**:
|
||
- 必须提供setter方法进行依赖注入
|
||
- 不需要使用注解(@Service等)
|
||
- 不需要手动配置Spring Bean
|
||
- 优先复用现有Service(见"常用Service参考"章节)
|
||
|
||
**2.3 开发Controller层**
|
||
|
||
位置:`projects/fangjia-open/src/main/java/com/fangjia/open/controllers/`
|
||
|
||
参考模板:[code-templates.md](references/code-templates.md) "Controller 模板"
|
||
|
||
**关键要点**:
|
||
- 方法名必须以 `Action` 结尾
|
||
- 添加 `@Authority(role = Role.USER)` 注解
|
||
- 使用 `RestfulModelAndView` 作为返回值
|
||
- 手动进行参数校验(使用 `StringUtils.isBlank` 等)
|
||
- **不要**使用try-catch(有统一异常处理)
|
||
|
||
---
|
||
|
||
### 阶段3:生成API文档
|
||
|
||
**3.1 使用API文档模板**
|
||
|
||
API文档模板位于(**相对于skill目录**):`assets\估家科技开放接口文档-模版.docx`
|
||
|
||
**注意**:这是相对路径,完整路径为:
|
||
```
|
||
.claude/skills/fangjia-openapi-dev/assets/估家科技开放接口文档-模版.docx
|
||
```
|
||
|
||
**3.2 生成文档内容**
|
||
|
||
按照模板格式生成:
|
||
|
||
1. **接口地址**:根据Controller和方法名确定URL
|
||
2. **输入参数表格**:
|
||
- 参数名
|
||
- 参数类型(String/Integer/Float等)
|
||
- 是否必填
|
||
- 说明
|
||
3. **响应参数表格**:
|
||
- 名称
|
||
- 类型
|
||
- 描述
|
||
4. **响应示例**:生成JSON格式示例
|
||
|
||
**3.3 文档生成方式**
|
||
|
||
### 方式1:使用docx-js生成(强烈推荐)
|
||
|
||
**重要**:为确保表格样式与模板完全一致,**强烈推荐**使用docx-js库直接生成Word文档。
|
||
|
||
使用pandoc转换可能导致:
|
||
- ❌ 表格边框样式不一致
|
||
- ❌ 表头背景色不匹配
|
||
- ❌ 单元格内边距不同
|
||
|
||
参考代码示例:
|
||
```javascript
|
||
// 创建表格时指定边框样式
|
||
const tableBorder = { style: BorderStyle.SINGLE, size: 6, color: "000000" };
|
||
const cellBorders = { top: tableBorder, bottom: tableBorder, left: tableBorder, right: tableBorder };
|
||
|
||
new Table({
|
||
columnWidths: [2340, 2340, 4680],
|
||
margins: { top: 100, bottom: 100, left: 100, right: 100 },
|
||
rows: [
|
||
new TableRow({
|
||
tableHeader: true,
|
||
children: [
|
||
new TableCell({
|
||
borders: cellBorders,
|
||
shading: { fill: "D3D3D3", type: ShadingType.CLEAR },
|
||
children: [new Paragraph({
|
||
alignment: AlignmentType.CENTER,
|
||
children: [new TextRun({ text: "参数名", bold: true })]
|
||
})]
|
||
})
|
||
]
|
||
})
|
||
]
|
||
});
|
||
```
|
||
|
||
### 方式2:使用pandoc快速生成(仅供参考)
|
||
|
||
仅用于快速预览,**最终交付文档必须使用方式1**:
|
||
```bash
|
||
pandoc api-doc.md -o api-doc.docx --reference-doc=".claude/skills/fangjia-openapi-dev/assets/估家科技开放接口文档-模版.docx"
|
||
```
|
||
|
||
---
|
||
|
||
## 开发规范
|
||
|
||
详见 [development-standards.md](references/development-standards.md)
|
||
|
||
### 关键规范速查
|
||
|
||
| 项目 | 规范 |
|
||
|-----|------|
|
||
| URL映射 | `XxxController.methodAction` → `/xxx/method` |
|
||
| 返回格式 | `RestfulModelAndView` + `BasicModel` |
|
||
| 参数校验 | 手动代码校验(`StringUtils.isBlank`) |
|
||
| 依赖注入 | 提供setter方法,不使用注解 |
|
||
| 异常处理 | 不需要try-catch |
|
||
| 字符编码 | UTF-8 |
|
||
|
||
---
|
||
|
||
## 常用Service参考
|
||
|
||
开发接口时经常需要使用以下核心Service:
|
||
|
||
### 地址匹配相关
|
||
|
||
**AddressMatchProxyService** (`com.fangjia.service.api.AddressMatchProxyService`)
|
||
|
||
- `newMatch(String city, String address, String category, boolean useMap)`
|
||
- 功能:地址匹配、property_type识别
|
||
- 返回:JSONObject包含匹配结果(id, city, district, name, propertyType, street, township, credit等)
|
||
- 示例:`addressMatchProxyService.newMatch(null, "上海市浦东新区唐安路199弄", null, true)`
|
||
|
||
### 房价查询相关
|
||
|
||
**DistrictStatService** (`com.fangjia.service.district.DistrictStatService`)
|
||
|
||
- `findLatestDistrictAvgPrice(String city, String region, String block, String name)`
|
||
- 功能:查询最新小区均价
|
||
- 返回:Integer(元/平方米)
|
||
|
||
- `findOneDistrictStatsSort(String city, String region, String name, Date weekend)`
|
||
- 功能:查询指定时间的小区统计信息
|
||
- 返回:DistrictStat对象(包含avgPrice, weekend等)
|
||
|
||
### 成交数据相关
|
||
|
||
**DealPriceService** (`com.fangjia.service.mongo.fangjia.DealPriceService`)
|
||
|
||
- `findHouseTradeHistoryLatest(DistrictKey key, int limit, boolean isVilla)`
|
||
- 功能:查询最近成交记录
|
||
- 用途:计算典型总价(找到成交单价最接近参考均价的记录)
|
||
- 返回:List<DealPrice>(包含avgPrice, totalPrice, area, tradeDate等)
|
||
|
||
- `findDealPriceList(String city, String region, String districtName, Date startDate, Date endDate)`
|
||
- 功能:查询指定时间范围的成交记录
|
||
- 注意:日期参数不要传null,传明确的日期值
|
||
- 返回:List<DealPrice>
|
||
|
||
### 小区数据相关
|
||
|
||
**DistrictService** (`com.fangjia.service.datastore.DistrictService`)
|
||
|
||
- `findById(String districtId)`
|
||
- 功能:根据ID查询小区信息(权威数据)
|
||
- 用途:地址匹配返回id后,查询权威的城市/区域/名称用于价格查询
|
||
- 返回:District对象(包含city, region, name, block等)
|
||
|
||
### 区域价格相关
|
||
|
||
**RegionSellStatService** (`com.fangjia.service.mongo.fangjia.RegionSellStatService`)
|
||
|
||
- `findNewestRegionPrice(String city, String region)`
|
||
- 功能:查询最新区域均价
|
||
- 注意:必须先用RegionData.formatCity和formatRegion格式化城市/区域为简称
|
||
- 返回:RegionSellStat对象(包含avgPrice, date, updateDate等)
|
||
|
||
### 使用示例
|
||
|
||
```java
|
||
// 1. 地址匹配
|
||
JSONObject matchResult = addressMatchProxyService.newMatch(null, address, null, true);
|
||
String city = matchResult.optString("city");
|
||
String name = matchResult.optString("name");
|
||
String propertyType = matchResult.optString("propertyType");
|
||
|
||
// 2. 查询房价
|
||
Integer avgPrice = districtStatService.findLatestDistrictAvgPrice(city, district, null, name);
|
||
|
||
// 3. 查询数据更新时间
|
||
DistrictStat latestStat = districtStatService.findOneDistrictStatsSort(city, district, name, null);
|
||
Date updateTime = latestStat.getWeekend();
|
||
|
||
// 4. 查询成交数据计算典型总价
|
||
DistrictKey key = new DistrictKey(city, district, null, name);
|
||
List<DealPrice> deals = dealPriceService.findHouseTradeHistoryLatest(key, 100, false);
|
||
// 找到成交单价最接近参考均价的记录
|
||
```
|
||
|
||
---
|
||
|
||
## 关键开发经验
|
||
|
||
以下是实际开发中总结的关键技术要点,必须严格遵循:
|
||
|
||
### 1. 地址匹配接口使用模式 ⭐⭐⭐
|
||
|
||
**核心原则**:判断是否有 `id` 字段来确定匹配是否成功。
|
||
|
||
```java
|
||
// 调用地址匹配服务
|
||
JSONObject matchResult = addressMatchProxyService.newMatch(city, address, null, true);
|
||
|
||
// 关键:检查是否有id字段
|
||
String id = (matchResult != null) ? matchResult.optString("id") : null;
|
||
if (StringUtils.isBlank(id)) {
|
||
// 没有id算匹配失败,需要调用标准化拆分
|
||
return handleAddressStructure(city, address);
|
||
}
|
||
|
||
// 有id表示匹配到具体POI,使用id查询权威数据
|
||
District district = districtService.findById(id);
|
||
```
|
||
|
||
**要点**:
|
||
- ✅ 有 `id` 字段 → 匹配成功,匹配到具体POI(小区/写字楼/建筑)
|
||
- ❌ 无 `id` 字段 → 匹配失败,调用 `addressStructure` 做标准化拆分
|
||
|
||
### 2. 直辖市特殊处理 ⭐⭐⭐
|
||
|
||
**问题**:直辖市的 `addressStructure` 返回结果中,城市名在 `province` 字段,不在 `city` 字段。
|
||
|
||
```java
|
||
// addressStructure返回示例(上海):
|
||
// { "province": "上海市", "city": "市辖区", "district": "浦东新区" }
|
||
|
||
// 正确处理方式
|
||
String province = structureResult.optString("province");
|
||
String cityField = structureResult.optString("city");
|
||
|
||
String structCity;
|
||
if (ProvinceData.isGovernmentCity(province)) {
|
||
// 直辖市:北京市、上海市、天津市、重庆市
|
||
structCity = province;
|
||
} else {
|
||
structCity = cityField;
|
||
}
|
||
```
|
||
|
||
**适用范围**:北京、上海、天津、重庆
|
||
|
||
### 3. 数据来源分离原则 ⭐⭐⭐
|
||
|
||
**核心原则**:展示字段和查询字段使用不同的数据源。
|
||
|
||
```java
|
||
// 从匹配结果获取展示用的数据(用户友好格式)
|
||
String matchCity = matchResult.optString("city"); // "上海"
|
||
String matchDistrict = matchResult.optString("district"); // "浦东"
|
||
String matchName = matchResult.optString("name");
|
||
|
||
// 从District对象获取权威数据(用于查询)
|
||
String districtCity = district.getCity(); // "上海市"
|
||
String districtRegion = district.getRegion(); // "浦东新区"
|
||
String districtName = district.getName();
|
||
|
||
// 返回给用户:使用匹配结果的数据
|
||
result.append("city", matchCity);
|
||
result.append("district", matchDistrict);
|
||
result.append("community_name", matchName);
|
||
|
||
// 查询价格和成交数据:使用District对象的权威数据
|
||
DistrictStat latestStat = districtStatService.findOneDistrictStatsSort(
|
||
districtCity, districtRegion, districtName, null);
|
||
```
|
||
|
||
**为什么分离**:
|
||
- 展示数据:用户输入什么格式,返回什么格式("上海" vs "上海市")
|
||
- 查询数据:使用数据库中存储的标准格式
|
||
|
||
### 4. 区域价格查询前必须格式化 ⭐⭐⭐
|
||
|
||
**问题**:区域价格查询必须使用城市和区域的简称,否则查不到数据。
|
||
|
||
```java
|
||
// 错误示例 ❌
|
||
RegionSellStat stat = regionSellStatService.findNewestRegionPrice(
|
||
"上海市", "浦东新区"); // 查不到数据
|
||
|
||
// 正确示例 ✅
|
||
String formattedCity = RegionData.formatCity("上海市"); // "上海"
|
||
String formattedRegion = RegionData.formatRegion(formattedCity, "浦东新区"); // "浦东"
|
||
RegionSellStat stat = regionSellStatService.findNewestRegionPrice(
|
||
formattedCity, formattedRegion);
|
||
```
|
||
|
||
**使用场景**:
|
||
- 查询区域价格(`RegionSellStatService.findNewestRegionPrice`)
|
||
- 任何需要使用城市/区域作为查询条件的场景
|
||
|
||
### 5. Service方法日期参数处理 ⭐⭐
|
||
|
||
**问题**:某些Service方法会直接将日期参数添加到查询条件,传 `null` 可能导致异常。
|
||
|
||
```java
|
||
// 错误示例 ❌
|
||
List<DealPrice> dealPrices = dealPriceService.findDealPriceList(
|
||
city, region, name, startDate, null); // endDate传null可能有问题
|
||
|
||
// 正确示例 ✅
|
||
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);
|
||
```
|
||
|
||
**建议**:始终传入明确的日期值,避免传 `null`。
|
||
|
||
### 6. 价格字段优先级 ⭐⭐
|
||
|
||
**规则**:`avg_price_2b` 字段优先于 `avgPrice` 字段。
|
||
|
||
```java
|
||
// DistrictStat中有两个均价字段
|
||
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(); // 降级使用
|
||
}
|
||
```
|
||
|
||
**原因**:`avg_price_2b` 是新版价格字段,数据更准确。
|
||
|
||
### 7. category字段判断POI类型 ⭐⭐
|
||
|
||
**规则**:使用 `category` 字段判断匹配结果的类型。
|
||
|
||
```java
|
||
String category = matchResult.optString("category");
|
||
|
||
if ("district".equals(category)) {
|
||
// 小区 → 输出房价
|
||
result.append("property_type", "住宅");
|
||
// 查询房价和成交数据
|
||
} else if ("office".equals(category)) {
|
||
// 写字楼 → 不输出房价
|
||
result.append("property_type", "写字楼");
|
||
} else {
|
||
// 其他类型建筑
|
||
String propertyType = matchResult.optString("propertyType");
|
||
result.append("property_type", propertyType);
|
||
}
|
||
```
|
||
|
||
**常见值**:
|
||
- `district` - 小区
|
||
- `office` - 写字楼
|
||
- 其他 - 使用 `propertyType` 字段判断
|
||
|
||
### 8. Controller参数必须使用@Param注解 ⭐
|
||
|
||
**规则**:所有Controller方法参数都需要 `@Param` 注解。
|
||
|
||
```java
|
||
import org.sothis.web.mvc.annotation.Param;
|
||
|
||
public RestfulModelAndView matchAction(
|
||
@Param(name = "address") String address,
|
||
@Param(name = "city") String city) {
|
||
// ...
|
||
}
|
||
```
|
||
|
||
**注意**:包路径是 `org.sothis.web.mvc.annotation.Param`,不是Spring的注解。
|
||
|
||
---
|
||
|
||
## 常见问题处理
|
||
|
||
### Q1: 返回数据格式规范
|
||
|
||
**重要**:接口返回的字段名使用**下划线分隔**,不使用驼峰命名。
|
||
|
||
- ✅ 正确:`community_name`, `reference_price`, `typical_total_price`
|
||
- ❌ 错误:`communityName`, `referencePrice`, `typicalTotalPrice`
|
||
|
||
因此,**不要创建专门的Model类**,直接使用 `UniversalDto` 封装结果:
|
||
|
||
```java
|
||
UniversalDto result = UniversalDto.newDto();
|
||
result.append("community_name", "陆家嘴花园");
|
||
result.append("city", "上海市");
|
||
result.append("reference_price", 126000);
|
||
result.append("update_time", "2026-01-31");
|
||
mav.setModel(BasicModel.buildOKModel().setResult(result));
|
||
```
|
||
|
||
### Q2: 如何处理参数校验?
|
||
|
||
手动代码校验,示例见 [development-standards.md](references/development-standards.md) "参数校验" 章节
|
||
|
||
### Q3: 需要配置Spring Bean吗?
|
||
|
||
不需要。约定大于配置,只要提供setter方法即可自动注入。
|
||
|
||
### Q4: 本地如何测试?
|
||
|
||
```bash
|
||
cd deliverables/fangjiaopen
|
||
mvn tomcat7:run
|
||
# 访问: http://localhost:9180/{controller}/{action}?param=value&token=xxx
|
||
```
|
||
|
||
### Q5: 如何构建部署?
|
||
|
||
```bash
|
||
cd deliverables/fangjiaopen
|
||
mvn clean package -Dmaven.test.skip=true
|
||
# WAR包位置: target/fangjia-open.war
|
||
# 后续通过Jenkins Pipeline自动部署到K8S
|
||
```
|
||
|
||
---
|
||
|
||
## 工作流程总结
|
||
|
||
1. **读取需求** → 使用pandoc转换Word/PDF
|
||
2. **分析需求** → 提取参数、字段、逻辑
|
||
3. **询问确认** → URL、数据源、Service/DAO
|
||
4. **给出建议** → 命名、字段、异常处理
|
||
5. **生成代码** → DAO(如需要) → Service → Controller
|
||
- 返回数据使用UniversalDto,字段名用下划线分隔
|
||
- 优先复用现有Service(AddressMatchProxyService、DistrictStatService等)
|
||
6. **生成文档** → 使用docx-js生成Word格式API文档(确保样式一致)
|
||
7. **接口测试** → 参考 [API测试指南](references/api-testing-guide.md)
|
||
|
||
---
|
||
|
||
## 参考资料
|
||
|
||
- **[代码模板](references/code-templates.md)** - Controller、Service代码模板
|
||
- **[开发规范](references/development-standards.md)** - 完整的开发规范文档
|
||
- **[API测试指南](references/api-testing-guide.md)** - 接口测试流程和脚本编写
|
||
- **[数据表参考](references/database-tables.md)** - 常用MongoDB数据表结构和查询方法
|
||
- **API文档模板**:`assets\估家科技开放接口文档-模版.docx`
|
||
|
||
---
|
||
|
||
## 常用工具类
|
||
|
||
详见项目根目录下的 `CLAUDE.md` 文件中的"常用工具类"章节。
|