Files
main/.claude/skills/fangjia-openapi-dev/SKILL.md
T

17 KiB
Raw Blame History

name, description
name description
fangjia-openapi-dev 房价开放平台(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文档:

# 使用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 "Service 接口模板"
  2. Service实现类 - 参考 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 "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转换可能导致:

  • ❌ 表格边框样式不一致
  • ❌ 表头背景色不匹配
  • ❌ 单元格内边距不同

参考代码示例:

// 创建表格时指定边框样式
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:

pandoc api-doc.md -o api-doc.docx --reference-doc=".claude/skills/fangjia-openapi-dev/assets/估家科技开放接口文档-模版.docx"

开发规范

详见 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等)

使用示例

// 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 字段来确定匹配是否成功。

// 调用地址匹配服务
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 字段。

// 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. 数据来源分离原则 ⭐⭐⭐

核心原则:展示字段和查询字段使用不同的数据源。

// 从匹配结果获取展示用的数据(用户友好格式)
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. 区域价格查询前必须格式化 ⭐⭐⭐

问题:区域价格查询必须使用城市和区域的简称,否则查不到数据。

// 错误示例 ❌
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 可能导致异常。

// 错误示例 ❌
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 字段。

// 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 字段判断匹配结果的类型。

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 注解。

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 封装结果:

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 "参数校验" 章节

Q3: 需要配置Spring Bean吗?

不需要。约定大于配置,只要提供setter方法即可自动注入。

Q4: 本地如何测试?

cd deliverables/fangjiaopen
mvn tomcat7:run
# 访问: http://localhost:8032/{controller}/{action}?param=value&token=xxx

Q5: 如何构建部署?

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测试指南

参考资料

  • 代码模板 - Controller、Service代码模板
  • 开发规范 - 完整的开发规范文档
  • API测试指南 - 接口测试流程和脚本编写
  • 数据表参考 - 常用MongoDB数据表结构和查询方法
  • API文档模板:assets\估家科技开放接口文档-模版.docx

常用工具类

详见项目根目录下的 CLAUDE.md 文件中的"常用工具类"章节。