Files
main/CLAUDE.md
T

425 lines
13 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.
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 项目概述
这是一个房地产信息平台的Java代码仓库,采用Maven多模块管理。本文档聚焦于四个核心可交付项目及其相关模块。
## 核心可交付项目
### 1. deliverables/fangjia - 房价核心系统
主要的房价查询和展示系统,包含以下模块:
- **fangjia-core**: 核心工具类和基础框架
- **fangjia-dal**: 数据访问层(DAL)
- **fangjia-service**: 业务服务层
- **fangjia-coresite**: 核心网站Web层(WAR包)
- **chafangtong-dal**: 查房通数据访问层
- **fangjia-static**: 静态资源服务
- **fangjia-script**: 脚本工具集
**打包产物**: fangjia-coresite.war
### 2. deliverables/fangjiaopen - 开放API系统
对外提供的RESTful API接口系统,包含以下模块:
- **fangjia-core**: 核心工具类
- **fangjia-dal**: 房价数据访问层
- **fangjia-service**: 房价业务服务
- **chafangtong-dal**: 查房通数据访问层
- **fangjia-loan-dal**: 房贷数据访问层
- **fangjia-loan-service**: 房贷业务服务
- **fangjia-open**: 开放API Web层(WAR包)
**打包产物**: fangjia-open.war
**本地开发端口**: 8032 (通过tomcat7-maven-plugin)
### 3. deliverables/fangjiastatic - 静态资源服务
静态文件托管服务,包含以下模块:
- **fangjia-core**: 核心工具类
- **fangjia-static**: 静态资源Web层(WAR包)
**打包产物**: fangjia-static.war
### 4. deliverables/script - 脚本工具集
数据处理、爬虫、分析等维护脚本集合,包含以下模块:
- **fangjia-core**: 核心工具类
- **fangjia-script**: Groovy脚本集合(JAR包)
**打包产物**: fangjia-script.jar
## 核心模块详解
### fangjia-core
所有项目的基础依赖模块,包含通用工具类和基础配置。
### fangjia-dal
数据访问层,提供DAO实现:
- 位置: `projects/fangjia-dal/src/main/java/com/fangjia/dal/`
- 基类: `AbstractEntityDao`, `AbstractJpaCompatibleDao`, `AbstractMongoDao`, `AbstractSqlDao`
- 数据库: MySQL + MongoDB混合存储
### fangjia-service
业务服务层,实现核心业务逻辑:
- 位置: `projects/fangjia-service/src/main/java/com/fangjia/service/`
- 包结构: address, auto, bkoff, city, chart等业务模块
- 依赖: fangjia-dal
### fangjia-coresite
核心网站Web层,房价信息展示的主要入口:
- 打包: WAR文件
- 框架: Spring 3.0.5 + Sothis Web + Freemarker
- Docker镜像: 192.168.0.19:9011/fangjia-coresite
### fangjia-open
开放API接口层:
- 打包: WAR文件
- 技术栈: Apache CXF 2.2.3(Web服务), Redis(缓存), Groovy支持
- 功能: 对外提供RESTful API和SOAP Web Service
- 特色依赖: JFreeChart(图表生成), xhtmlrenderer(HTML转PDF)
### fangjia-static
静态资源服务:
- 打包: WAR文件
- 极简依赖: 仅包含Sothis框架和Commons-IO
- 用途: 托管静态文件(图片、CSS、JS等)
### fangjia-script
Groovy脚本集合,包含大量数据处理脚本:
- 打包: JAR文件(包含所有依赖到lib目录)
- 语言: Groovy 2.4.13
- Java版本: 1.8 (其他模块多为1.6)
- 主要脚本类别:
- **数据导入导出**: dataImport, dataExport, backup
- **爬虫**: crawl, webCrawl, sampleSpider, thirdPriceCrawl
- **数据分析**: dataAna, analy, statistic, searchanalysis
- **批处理任务**: BaseBatch.groovy, BatchOwner.groovy
- **第三方集成**: baidu, dianping, aliyun
- **数据同步**: sync, datastore
- **工具脚本**: tool, util, temp(临时脚本)
脚本位置: `projects/fangjia-script/src/main/groovy/com/fangjia/script/`
## 构建和开发命令
### 构建单个项目
所有构建命令在 `deliverables/` 目录下执行:
```bash
# 构建fangjia核心系统
cd deliverables/fangjia
mvn clean package -Dmaven.test.skip=true
# 构建开放API系统
cd deliverables/fangjiaopen
mvn clean package -Dmaven.test.skip=true
# 构建静态资源服务
cd deliverables/fangjiastatic
mvn clean package -Dmaven.test.skip=true
# 构建脚本工具集
cd deliverables/script
mvn clean package -Dmaven.test.skip=true
```
### 本地运行fangjia-open
```bash
cd deliverables/fangjiaopen
mvn tomcat7:run
# 访问 http://localhost:8032
```
### 生成Eclipse项目文件
```bash
cd deliverables/<project-name>
mvn eclipse:clean
mvn eclipse:eclipse -Dwtpversion=1.0 -DdownloadSources=true
```
### 运行Groovy脚本
```bash
cd deliverables/script
mvn package # 先打包生成jar和依赖
# 然后执行特定脚本
groovy -cp "target/classes:target/classes/lib/*" <script-path>
```
## 字符编码
**重要**: 所有核心模块现在统一使用 UTF-8 编码:
| 模块 | 编码格式 |
|-----|---------|
| fangjia-coresite | UTF-8 |
| fangjia-open | UTF-8 |
| fangjia-script | UTF-8 |
| fangjia-static | UTF-8 |
## 技术栈
### Web应用 (fangjia-coresite, fangjia-open, fangjia-static)
- **Java**: 1.6
- **Spring**: 3.0.5.RELEASE
- **Hibernate**: 4.0.1.Final (JPA)
- **Sothis Framework**: 0.1.0/0.2.0-SNAPSHOT (自研Web框架)
- **模板引擎**: Freemarker 2.3.16+
- **Web容器**: Tomcat 6
- **数据库**: MySQL 5.x, MongoDB
- **缓存**: Redis (仅fangjia-open)
### 脚本工具 (fangjia-script)
- **Java**: 1.8
- **Groovy**: 2.4.13
- **数据库**: MySQL, Oracle, PostgreSQL, ClickHouse, Elasticsearch
- **消息队列**: ActiveMQ 5.5.0, RabbitMQ 4.12.0
- **爬虫**: Selenium 3.14.0, HttpClient, Jsoup
- **数据处理**: Apache POI, EasyExcel, Apache Commons
- **分析**: Apache Mahout 0.5, JFreeChart
- **全文搜索**: Solr 3.5.0, IK Analyzer
- **OCR**: Tess4j 3.4.0
### 公共依赖
- Google Guava (版本在不同模块间有差异: r09, 19.0, 22.0)
- Apache Commons系列 (lang, codec, collections, io, email等)
- SLF4J + Log4j (日志)
## 部署流程
使用Jenkins Pipeline自动化部署(见Jenkinsfile):
1. **Git Checkout**: 从GitLab拉取代码
2. **Maven Build**: 在deliverables目录下构建
3. **Docker Build**: 构建镜像并推送到 192.168.0.19:9011
4. **K8S Deploy**: 应用Kubernetes配置
### Docker镜像
每个Web项目都有对应的Dockerfile:
- `projects/fangjia-coresite/Dockerfile` → fangjia-coresite镜像
- `projects/fangjia-open/Dockerfile` → fangjia-open镜像
- `projects/fangjia-static/Dockerfile` → fangjia-static镜像
标准格式:
```dockerfile
FROM 192.168.0.19:9012/tomcat6:220713
COPY target/*.war /home/goojia/webapps/ROOT.war
```
## 常用工具类
### fangjia-script 工具类 (Groovy)
位于 `projects/fangjia-script/src/main/groovy/com/fangjia/script/util/`
**ExcelUtils** - Excel读写处理,支持并发
- `read(file, sheetIndex=0, skipRow=1)` - 读取Excel为List
- `write(fileName, data, sheetName)` - 写入数据到Excel
- `multiThreadingModify(fileName, closure, sheetIndex, destSheetName)` - 多线程修改(CPU核心数x4)
- `distinct(inputFile, rowIndexs, sheetIndex)` - 按列去重
- `filter(fileName, closure, sheetIndex)` - 按条件过滤行
**CsvUtils** - CSV文件处理
- `read(file, skipFirstLine=true)` - 读取CSV为List
- `write(file, data)` - 写入数据到CSV
**ElasticUtils** - Elasticsearch操作
- `getClient(host)` - 获取ES客户端
- `executeSimpleQuery(host, indexName, queryBuilder)` - 执行查询
- `modify(id, map, host, indexName)` - 更新文档
**JacksonUtil** - JSON序列化
- `jsonToBean(jsonString, resultClass)` - JSON转对象(自动忽略未知属性)
- `jsonToList(jsonString, elementClass)` - JSON转List
- `getMapper(ignoreUnknownProperties)` - 获取ObjectMapper
**GeoUtils** (Groovy) - 地理位置计算
- `calculateDistance(lng1, lat1, lng2, lat2)` - 计算两点距离(米)
- `geoconvBaiduToGoogle(lng, lat)` - 百度坐标转谷歌坐标
**DESUtil** - DES加密
- `encrypt(data, secretKey)` - 加密字符串
- `decrypt(encryptedData, secretKey)` - 解密字符串
- `generateKey()` - 生成密钥
**DbUtils** - MongoDB操作(Groovy)
- `executeQueryOnline(collName, query, closure, fields)` - 线上库查询
- `seaweed` / `seabird` - 预定义的常用Collection
### fangjia-core 工具类 (Java)
位于 `projects/fangjia-core/src/main/java/com/fangjia/core/util/`
**StringUtil** - 字符串处理
- `getFirstSpell(spell, upCase)` - 获取首字母拼音
- `cutString(targetString, targetLength)` - 截断字符串
- `isDirtyWord(word)` - 脏词检测
**Mongo3Utils** - MongoDB 3.6+ 客户端
- `getMongoClient(uri)` - 获取MongoClient(带连接池)
- `getDbCollection(uri, db, collection)` - 获取MongoCollection
**MongoUtils** - MongoDB旧版API
- `getDbCollection(db, name)` - 获取DBCollection
- `getDbCollection(uri, db, name)` - 带URI的获取方式
- 常量: `MongoDB_Domain_mongo`, `MongoDB_Domain_artemis` 等
**GeoUtils** (Java) - 地理位置计算
- `calculateDistance(lng1, lat1, lng2, lat2, gaussSphere)` - 计算距离(支持不同坐标系)
- `geoconvBaiduToGoogle(lng, lat)` - 百度转谷歌坐标
**DataUtil** - 数据处理
- `getPinyin(chinese)` - 汉字转拼音
- `cleanString(str)` - 清理特殊字符
- `roundDouble(value, scale)` - 四舍五入
- `cellPhonePattern` - 手机号正则
**DateUtil** - 日期处理
- `formatDate(date, pattern)` - 日期格式化
- `parseDate(dateStr, pattern)` - 字符串解析为日期
- `getBeforeDay(date, days)` - 获取N天前/后的日期
- `truncateDay(date)` - 截断到日期(去除时分秒)
**HttpRequest** - HTTP请求
- `sendGet(url, params)` - 发送GET请求
- `sendPost(url, params)` - 发送POST请求
- `get(url, charset)` / `post(url, params, charset)` - 简化方法
**DingDingMessageUtil** - 钉钉通知
- `sendTextMessage(msg)` - 发送文本消息(使用默认token)
- `sendTextMessage(token, msg)` - 发送文本消息(指定token)
需要详细用法时直接查看工具类源码
## 代码组织
### 包结构约定
```
com.fangjia.dal.* - 数据访问层
com.fangjia.service.* - 业务服务层
com.fangjia.*.controllers - Web控制器(Sothis框架)
com.fangjia.script.* - Groovy脚本
```
### 模块依赖关系
**fangjia核心系统**:
```
fangjia-coresite (WAR)
└── fangjia-service
└── fangjia-dal
└── fangjia-core
```
**fangjiaopen系统**:
```
fangjia-open (WAR)
├── fangjia-service → fangjia-dal → fangjia-core
└── fangjia-loan-service → fangjia-loan-dal
```
**fangjiastatic系统**:
```
fangjia-static (WAR)
└── fangjia-core
```
**script工具集**:
```
fangjia-script (JAR)
└── fangjia-core
```
## 文档转换工具
系统已安装 **pandoc**,可直接用于文档格式转换:
```bash
# Word转Markdown
pandoc input.docx -o output.md
# Markdown转Word
pandoc input.md -o output.docx
# 指定格式转换
pandoc -f <源格式> -t <目标格式> input -o output
# 常用格式: docx, md, html, pdf, rst等
```
## 开发注意事项
### 1. 编码问题
不同模块使用不同编码(UTF-8/GBK),修改代码前先确认pom.xml中的`<project.build.sourceEncoding>`设置。
### 2. Java版本
- fangjia-script: Java 1.8
- 其他模块: Java 1.6
避免在1.6模块中使用Java 7+特性。
### 3. 构建位置
始终在`deliverables/`目录下构建,而不是`projects/`目录。
### 4. Groovy脚本开发
- 脚本源码位置: `projects/fangjia-script/src/main/groovy/com/fangjia/script/`
- 临时脚本建议放在: `temp/` 目录
- 脚本会被打包到jar中,依赖会被复制到`target/classes/lib/`
### 5. Web服务开发(fangjia-open)
- 支持RESTful API和SOAP Web Service(CXF 2.2.3)
- 使用Redis做缓存(Jedis 2.9.0)
- 支持HTML转PDF功能(xhtmlrenderer)
- 支持图表生成(JFreeChart)
### 6. 共享代码
需要在多个模块间共享的代码应放入fangjia-core,然后在pom.xml中添加依赖。
## 常见任务
### 如何添加新的Groovy脚本?
1. 在`projects/fangjia-script/src/main/groovy/com/fangjia/script/`下创建脚本
2. 确定脚本分类,放入对应目录(如dataImport, crawl, tool等)
3. 在`deliverables/script`目录构建: `mvn package`
4. 运行脚本
### 如何修改开放API?
1. 找到对应的Controller: `projects/fangjia-open/src/main/java/`
2. 修改业务逻辑: `projects/fangjia-service/` 或 `projects/fangjia-loan-service/`
3. 修改数据层: `projects/fangjia-dal/` 或 `projects/fangjia-loan-dal/`
4. 在`deliverables/fangjiaopen`构建测试
### 如何运行测试?
```bash
cd deliverables/<project>
mvn test
# 运行单个测试类
mvn test -Dtest=YourTestClass
# 跳过测试
mvn package -Dmaven.test.skip=true
```
### 如何查看构建产物?
WAR文件位置: `deliverables/<project>/target/<project-name>.war`
JAR文件位置: `deliverables/script/target/fangjia-script.jar`
## Maven仓库配置
项目使用多个Maven仓库(deliverables/settings.xml):
### 依赖仓库
- **阿里云中央仓库**: https://maven.aliyun.com/repository/central (首选,加速国内下载)
- **Maven中央仓库**: https://repo1.maven.org/maven2
- **内部Nexus仓库**: https://repo.fangjia.com/repository/
- maven-public: 发布版本 (releases)
- maven-snapshots: 快照版本 (snapshots)
- maven-releases: 发布版本 (releases)
### 插件仓库
- **内部Nexus**: https://repo.fangjia.com/repository/maven-public/
- **Maven中央仓库**: https://repo.maven.apache.org/maven2
### 认证信息
内部仓库需要使用 deployment 账户进行认证(已在settings.xml中配置)