Files
main/.claude/skills/fangjia-openapi-dev/SKILL.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

523 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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&lt;DealPrice&gt;(包含avgPrice, totalPrice, area, tradeDate等)
- `findDealPriceList(String city, String region, String districtName, Date startDate, Date endDate)`
- 功能:查询指定时间范围的成交记录
- 注意:日期参数不要传null,传明确的日期值
- 返回:List&lt;DealPrice&gt;
### 小区数据相关
**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` 文件中的"常用工具类"章节。