# add-ledger 模块说明

## 模块定位

`add-ledger` 是 `tools` 下的数据台账配置工具模块，当前基于 `ledger.sql` 中的工程、项目、设备、监测点和台账树表结构，提供后端配置接口。

本次范围不包含：

- 前端真实页面代码
- 自动执行 SQL 初始化
- 自动数据库迁移
- 设备通信、WebSocket 或 Netty 链路改造

目录中的 `ledger.sql` 仅作为原始表结构脚本保留，当前模块不加载、不解析该脚本。

## 当前结构

```text
add-ledger/
├── ledger.sql
├── pom.xml
├── README.md
├── src/main/java/com/njcn/gather/tool/addledger/
│   ├── component/
│   ├── config/
│   ├── controller/
│   ├── mapper/
│   ├── pojo/
│   ├── service/
│   └── util/
└── src/main/resources/sql/add-ledger/
```

## 当前接口

完整调试说明见 [API_DEBUG.md](./API_DEBUG.md)。

- `GET /addLedger/tree`
  - 查询台账树，支持按节点名称关键字过滤。
- `GET /addLedger/detail`
  - 根据 `id` 和 `level` 查询工程、项目、设备或测点详情。
- `POST /addLedger/engineering/save`
  - 新增或保存工程，并同步 `cs_ledger` 工程节点。
- `POST /addLedger/project/save`
  - 新增或保存项目，并同步 `cs_ledger` 项目节点。
- `POST /addLedger/equipment/save`
  - 新增或保存设备，并同步 `cs_ledger` 设备节点。
- `POST /addLedger/line/save`
  - 新增或保存测点，并同步 `cs_ledger` 测点节点。
- `GET /addLedger/line/availableLineNos`
  - 查询设备下 `1-20` 中可用的线路号。
- `DELETE /addLedger/node`
  - 软删除指定节点，父节点会级联软删除下级业务数据和台账节点。

## 实现说明

- 台账层级固定为：工程 -> 项目 -> 设备 -> 监测点。
- 新增时绑定父级节点；编辑时只更新当前业务数据和台账节点名称，不搬迁节点。
- 保存业务表和 `cs_ledger` 在同一事务内完成。
- 设备保存时同步 `associated_engineering` 和 `associated_project`。
- 测点新增时生成 32 位 UUID 作为 `line_id`。
- 测点 `line_no` 后端限制为 `1-20`，且同设备下正常测点不可重复。
- 删除采用软删除：工程、项目、测点更新 `status=0`，设备更新 `run_status=0`，台账节点更新 `State=0`。

## 后续扩展约束

后续如果新增更多台账能力，应沿当前 `controller -> service -> mapper -> XML` 职责边界扩展，不回退为单一大类承载全部接口。