# introduction.md

## 1. 技术栈

- **框架**: Solon 3.10.3（非 Spring Boot，注入/切面/MVC 均使用 Solon 注解）
- **Java**: 25（如果可以，必须新特性）
- **ORM**: MyBatis-Plus 3.5.12 + Solon 插件（mapper 接口继承 `BaseMapper<T>`，lambda 查询用 `Wrappers.lambdaQuery()`）
- **序列化**: Jackson（`solon-serialization-jackson`）
- **模板**: Thymeleaf（`solon-view-thymeleaf`）
- **数据库**: SQLite（plat 库，通过 `org.sqlite.JDBC`）、DuckDB（case 库，通过 `duckdb_jdbc`）、RocksDB（本地 KV 存储）
- **搜索引擎**: Apache Lucene 10.3.2 + IK Analyzer
- **图计算**: JGraphT 1.5.2

## 2. 目录与约定（必须遵守）

```text
com.qingjian/
├── App.java                  # 入口：Solon.start()，端口 8980，contextPath "!/js/a/"
├── common/                   # 公共层
│   ├── cache/                # 缓存：GlobalCache（表/字段元数据）、CaseDataCache（人员/卡号映射）
│   ├── config/               # 配置：WebConfig（数据源/CORS）、MybatisPlusConfig（分页插件）
│   ├── constants/            # 常量（StrConsts, PathConst, RegConst）
│   ├── enums/                # 枚举
│   ├── model/<module>/       # 按模块组织的 DTO/Entity/Query，MapStruct 转换器
│   ├── rocksdb/              # RocksDB 封装（运营商归属、银行卡归属查询）
│   └── utils/                # 工具：GlobalPool（线程池）、Json、DataUtil、SlowDownProgress
└── module/                   # 业务模块（每个含 controller/mapper/service）
    ├── ai/                   # AI（Solon AI agent、chat、skill）
    ├── call/                 # 通话记录
    ├── dm/                   # 数据管理（文件导入、清洗、缓存构建）
    ├── govern/               # 数据治理（关系边计算、去重、时序图、分类树）
    ├── graph/                # 图谱/关系图
    ├── otg/                  # 对象轨迹生成
    ├── person/               # 人员信息（基本信息和证件号/手机号/银行卡号库）
    ├── plat/                 # 平台（SSE 推送、表管理、配置）
    ├── track/                # 轨迹追踪
    └── trans/                # 交易记录
```

## 3. 命名约定

- 统一使用lombok注解，如果有继承关系 必须加上 `@EqualsAndHashCode(callSuper = true)` 注解
- **类名**：使用帕斯卡命名法（如 `UserController`、`OrderService`）
- **方法和变量名**：使用驼峰命名法（如 `findUserById`、`isOrderValid`）
- **常量**：使用全大写下划线分隔（如 `MAX_RETRY_ATTEMPTS`、`DEFAULT_PAGE_SIZE`）
- **包名**：使用小写，按功能模块划分（如 `com.example.user.domain`）
- **响应对象**： 创建接口响应对象使用DTO结尾，示例：ResponseDTO
- **请求参数**： 创建接口请求参数对象使用Query结尾 必须继承 `com.qingjian.common.base.Query`，示例：RequestQuery
- **语言与风格**：保持现有包结构与命名风格；避免无意义抽象；方法保持短小可测。

## 4. 多数据源

数据源通过 Solon 的 `DynamicDataSource("db1")` 管理，在 `app.yml` 的 `qingjian.db1` 下配置：

| 数据源 key | 数据库 | 用途 |
|---|---|---|
| `plat` | SQLite | 平台配置、表字段元数据、运营商/银行字典 |
| `case` | DuckDB | 案件数据（通话/交易记录、关系边、去重中间表） |

切换数据源使用 `DynamicDsKey.with(StrConsts.DS_KEY_PLAT, () -> ...)` 或在注入时指定。

## 5.构建与运行

```bash
# 编译项目
mvn compile -f pom.xml
```

代码编写完成后，使用 IDEA MCP 工具进行代码编译验证。