---
description: 数据库持久层架构规范(MyBatis)
globs: src/**/dbdao/**/*.java
alwaysApply: false
---

# 数据库持久层架构规范

## 一、目录结构

```
src/main/java/com/shkpr/service/mcpcenterservice/dbdao/
├── DBMgrProxy.java              # Service单例代理入口
├── mapper/                      # 主数据库访问的 Mapper 定义类
├── mapper2th/                   # 从数据库访问的 Mapper 定义类
├── mapperLSTM/                  # LSTM数据库访问的 Mapper 定义类
├── providers/                   # Mapper 动态 SQL 提供者
├── tables/                      # 表结构/字段定义说明
├── services/                    # DAO Service实现类
│   └── intef/                   # DAO Service接口定义类
├── pgtype/                      # PostgreSQL 自定义类型处理

```

## 二、核心调用链路

```
业务层 (XxxHandler/其他)
    ↓
DBMgrProxy.getInstance().applyXxxApi(XxxDBService.class)
    ↓
XxxDBService 继承 BaseDBFuncTemplate
    ↓
XxxServiceImpl 继承并实现对应的 XxxDBService (@Autowired XxxMapper)
    ↓
XxxMapper 继承 BaseDBMapper (并通过方法上的注入指定对应的XxxSqlProvider)
    ↓
XxxSqlProvider 继承 BaseSqlProvider
    ↓
pgtype (特殊类型处理)
    ↓
PostgreSQL
```

## 三、Table接口规范

- XxxTable接口**必须**定义 `R_INFO` 和 `W_INFO` 两个内部接口
  - `R_INFO.TABLE` 用于查询操作（可指向视图或表）
  - `W_INFO.TABLE` 用于写入操作（必须是物理表）
- XxxSqlProvider**必须**继承对应的XxxTable接口

## 四、Mapper规范

### 4.1 规则

- `BaseDBMapper`接口中定义了数据库可访问的基本方法
- XxxMapper不声明和使用任何实体对象，查询返回记录和插入请求记录只能是`List<Map<String,Object>>`、`Map<String,Object>`等结构
- XxxMapper必须继承`BaseDBMapper`，并实现对应的方法，同时在方法上指定对应的XxxSqlProvider
- XxxMapper可以根据需求扩展`BaseDBMapper`中没有的方法，同时在方法上指定对应的XxxSqlProvider
- XxxSqlProvider必须继承`BaseSqlProvider`
- 复杂动态SQL可在XxxSqlProvider中拼接，**禁止**字符串拼接直接嵌入不可信输入
- 批量操作默认每批200条

### 4.2 BaseDBMapper中基本方法

| 方法                  | 用途               |
|:--------------------|:-----------------|
| `totalCounts()`     | 查询统计             |
| `listAllWiths()`    | 分页列表查询（支持JOIN优化） |
| `batchQueryWiths()` | 多条件复合查询          |
| `batchQueryIn()`    | 多条件IN查询          |
| `getOne()`          | 单条查询             |
| `existLine()`       | 存在性判断            |
| `insertsWheres()`   | 带条件的单条插入         |
| `inserts()`         | 单条插入             |
| `batchInserts()`    | 多条插入             |
| `updateWiths()`     | 条件更新             |
| `insertOrUpdate()`  | 插入或更新            |

## 五、注意事项

1. 整个dbdao持久层**与实体对象解耦**，不在dbdao持久层的任何地方声明或使用实体对象
2. **禁止**修改`BaseSqlProvider`中的任意方法
3. **禁止**在XxxSqlProvider中直接字符串拼接嵌入不可信输入
4. **禁止**业务层直接`new Mapper`实例
5. **禁止**业务层直接`@Autowired`注入`Mapper`
6. **禁止**在Table接口中写业务逻辑