# dbms 模块说明

## 模块定位

`dbms` 是 `system-ops` 下的数据库运维模块，当前面向 Oracle 数据库提供连接配置、连接测试、表列表查询、备份、恢复、任务状态查询和删除接口。

## 当前接口

- `GET /database/overview`
  - 查询数据库运维概览信息。
- `POST /database/connections/list`
  - 查询数据库连接配置。
- `POST /database/connections/add`
  - 新增 Oracle 数据库连接配置。
- `POST /database/connections/update`
  - 修改 Oracle 数据库连接配置。
- `POST /database/connections/delete`
  - 删除数据库连接配置。
- `POST /database/connections/test`
  - 测试 Oracle 数据库连接。
- `POST /database/connections/tables`
  - 查询 Oracle 表列表。
- `POST /database/backups/create`
  - 创建备份任务，默认使用 `DATA_PUMP`，可选 `JDBC_EXPORT`。
- `POST /database/backups/tasks/list`
  - 查询备份任务列表。
- `GET /database/backups/tasks/status`
  - 查询任务状态。
- `POST /database/backups/files/list`
  - 查询备份文件记录。
- `POST /database/restores/create`
  - 创建恢复任务。
- `GET /database/restores/tasks/status`
  - 查询恢复任务状态。
- `POST /database/delete/backup-file`
  - 删除备份文件，要求 `confirmText=确认删除`。
- `POST /database/delete/task`
  - 删除任务记录，要求 `confirmText=确认删除`。

## 数据脚本

- `src/main/resources/sql/system-ops/system-ops-init.sql`
  - 系统运维菜单初始化脚本。
- `src/main/resources/sql/system-ops/dbms-database-ops-init.sql`
  - 数据库运维连接、任务、备份文件和恢复记录表结构。

## 配置项

建议通过环境配置覆盖：

```yaml
dbms:
  backup:
    storage-path: D:/dbms-backup
    default-max-file-size-mb: 512
  tools:
    expdp-path:
    impdp-path:
```

说明：

- `backup.storage-path`
  - `JDBC_EXPORT` 生成的 CSV 和元数据 JSON 的受管根目录。
- `tools.expdp-path`、`tools.impdp-path`
  - Oracle Data Pump 工具路径；为空时尝试走系统 `PATH`。

## 当前行为

- 一期仅支持 `ORACLE`。
- 连接密码支持两种运行方式：
  - 前端每次传 `temporaryPassword`。
  - 连接已保存密文，且公共 `Sm4Utils` 提供 `decryptData_ECB` 时由后端自动解密复用。
- 新增连接前的测试接口允许只传 `temporaryPassword`，不强制把密码写进 `connection.password`。
- 备份任务异步执行，只有实际文件生成成功后才会写入 `dbms_backup_file` 记录。
- `JDBC_EXPORT` 当前会生成两类文件：
  - 主数据文件：`*.csv`
  - 元数据文件：`*_metadata_yyyyMMdd_<taskNo>.json`
- `JDBC_EXPORT` 恢复依赖元数据文件，不再允许缺少元数据直接发起恢复。
- 删除备份文件时，会校验目标路径必须位于受管备份目录下，避免误删非备份文件。

## 当前限制

- `DATA_PUMP` 仍依赖部署机器可执行 `expdp`、`impdp`，并且 Oracle 侧已准备好 `directory` 对象和权限。
- 当前代码要求 `DATA_PUMP` 连接配置里补齐可管理的 `directoryPath`，否则虽然 Oracle 端可能已导出成功，后端无法安全管理文件记录与删除。
- `JDBC_EXPORT` 恢复当前仅覆盖表数据，不承诺恢复索引、约束、触发器、序列、存储过程、权限等 Oracle 对象。
- `TIME_RANGE` 模式当前只在 `JDBC_EXPORT` 场景真正参与查询过滤；`DATA_PUMP` 尚未接入 Oracle `QUERY` 参数。
- `SIZE_SPLIT` 参数目前已做入参校验，但尚未实现真正的导出分片。
- 本轮仅完成代码路径和文档收口，未执行 `mvn` 编译、测试或真实库联调。