--- 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 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 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 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` 文件中的"常用工具类"章节。