# 数据直查层（`data_*` 数据库 / 缓存 / 上游）

直接读数据库、缓存或上游平台，跳过 Service 层。**全部只读**。仅当 `service_*` 工具无法满足（自定义 filter、聚合统计、上游原始数据）时使用。

## MongoDB

| 工具 | 参数 | 说明 |
|------|------|------|
| `data_mongo_find` | `collection`(必填)、`filter`(JSON)、`fields`(字段投影数组)、`limit`(默认10,最大100)、`skip`、`sort`(JSON) | 查询集合文档 |
| `data_mongo_count` | `collection`(必填)、`filter`(JSON,可空) | 统计符合条件的文档数 |
| `data_mongo_export` | `collection`(必填)、`filter`(JSON)、`fields`(数组)、`sort`(JSON)、`max_docs` | 全量导出到 NDJSON 文件，游标流式、内存常数级；仅回 localPath+count+summary |
| `data_mongo_aggregate` | `collection`(必填)、`pipeline`(JSON数组字符串,必填)、`max_docs` | **聚合管道**：在数据库侧完成过滤+关联(JOIN)+分组统计，结果流式落盘 |

**collection 白名单**（仅以下集合可查；`$lookup`/`$graphLookup`/`$unionWith` 引用的集合也必须在此列表内）：
`SiteInfoManageData`、`SiteInfoManageRecord`、`SimCardManage`、`SimCardMonthlyData`、`BatchDownloadConfig`、`SiteAnalysisConfig`、`StatisticsShutdown`、`StatisticsAlarm`、`SiteMonitorConfig`、`AutoUpdateConfigOption`、`AutoUpdateConfig`

> 注意：`UserInfo`（内部用户身份数据）与 `AiChatSessions`（历史对话自由文本）已从白名单**移除**，不可直查，也不可作为 `$lookup`/`$unionWith` 的目标。

find/export 示例：
```json
{ "collection": "SiteInfoManageData", "filter": "{\"sn\": \"xxx\"}", "limit": 10, "sort": "{\"createdAt\": -1}" }
```

用法提示：
- `filter` / `sort` / `pipeline` 都是 JSON **字符串**（如 `"{\"sn\":\"xxx\"}"`）。
- 分页用 `skip` + `limit`；大数据量导出用 `data_mongo_export`（不受 100 条上限）。
- 优先用对应的 `service_*` 工具；直查仅用于灵活筛选/聚合/关联。
- **所有 `data_mongo_*` 返回都无条件落盘**：仅返回 `localPath` + `summary`，需用文件读取工具按 `localPath` 读取完整数据。

### data_mongo_aggregate（聚合 / 跨集合 JOIN）

在**数据库侧**一次性完成"过滤 + 关联(JOIN) + 分组统计"，避免多次取数与 Agent 侧拼接，是大数据量关联任务的首选。

**允许的只读阶段**：`$match`、`$project`、`$addFields`/`$set`、`$unset`、`$group`、`$sort`、`$limit`、`$skip`、`$count`、`$unwind`、`$lookup`、`$graphLookup`、`$unionWith`、`$facet`、`$bucket`/`$bucketAuto`、`$sortByCount`、`$replaceRoot`/`$replaceWith`、`$sample`、`$redact`、`$setWindowFields`。

**禁止的阶段**（会被拒绝）：`$out`、`$merge`（写集合）、`$function`、`$accumulator`、`$where`（执行 JS）。

**安全约束**：
- `collection` 及 `$lookup`/`$graphLookup`/`$unionWith` 引用的集合都必须在白名单内（含嵌套 pipeline，递归校验）。
- 每个阶段必须恰好一个顶层操作符。
- 结果超过 `max_docs`（默认 50000）会被截断。

#### 字段字典（写 pipeline 必读）

**`SiteInfoManageData`（站点信息，`_id` = 站点 SN）关键字段**：
- `_id`（站点 SN，20位）、`iccId`（SIM 卡 ICCID，20位；**前 19 位 = GICCID**）
- `province`（州/省，如 `"Puerto Rico"`）、`city`、`country`（`"United States"`）、`countryId`、`provinceId`
- `activeStatus`(1=已激活)、`status`(在线状态)、`runStatus`、`connType`、`signal`、`batterySoc`
- `installerName`、`version`、`realSysHdVersion`、`site`(站点编码)、`siteId`
- 敏感字段（会被脱敏）：`address`/`deviceAddress`、`longitude`/`latitude`、`contactNumber`、`userName`/`firstName`/`lastName`、`account`、`mac`/`deviceIp`/`imei`

**`SimCardManage`（SIM 卡，`_id` = GICCID 19位）关键字段**：
- `_id`（GICCID，19位）、`status`（UNKNOWN/NOT_ACTIVATED/ACTIVATED/DEACTIVATED/RETIRED）、`platform`（SmartHub/Acceleronix）
- `allDataUsage`（累计用量字节）、`month`（yyyy-MM）、`expirationTime`、`updateTime`
- 敏感字段（会被脱敏）：`imei`、`imsi`、`msisdn`

**`SimCardMonthlyData`（SIM 月用量）**：`simId`(GICCID)、`month`、`allDataUsage`、`dailyUsage`。

#### JOIN 关系图谱（跨集合关联键）

- **站点 ↔ SIM**：`SiteInfoManageData.iccId` 取**前 19 位** = `SimCardManage._id`（GICCID）。
  在 pipeline 中先用 `$addFields` 计算 `giccid = $substrBytes(iccId, 0, 19)`，再 `$lookup` 关联。
- **SIM ↔ 月用量**：`SimCardManage._id` = `SimCardMonthlyData.simId`。

#### 配方：波多黎各站点关联 SIM 信息（一步完成）

```json
[
  { "$match": { "province": "Puerto Rico" } },
  { "$addFields": { "giccid": { "$substrBytes": ["$iccId", 0, 19] } } },
  { "$lookup": {
      "from": "SimCardManage",
      "localField": "giccid",
      "foreignField": "_id",
      "as": "sim"
  }},
  { "$project": {
      "sn": "$_id", "city": 1, "giccid": 1,
      "simStatus": { "$arrayElemAt": ["$sim.status", 0] },
      "simPlatform": { "$arrayElemAt": ["$sim.platform", 0] },
      "dataUsage": { "$arrayElemAt": ["$sim.allDataUsage", 0] }
  }}
]
```
调用（pipeline 作为 JSON 字符串传入）：
```json
{ "collection": "SiteInfoManageData", "pipeline": "[{\"$match\":{\"province\":\"Puerto Rico\"}}, ...]" }
```

#### 配方：按州统计站点数与激活率

```json
[
  { "$group": {
      "_id": "$province",
      "total": { "$sum": 1 },
      "active": { "$sum": { "$cond": [{ "$eq": ["$activeStatus", 1] }, 1, 0] } }
  }},
  { "$sort": { "total": -1 } }
]
```

#### 约束与反模式

- **不要**用 `$project`/`$group` 把敏感字段（`contactNumber`/`imei`/`longitude` 等）**重命名**成新字段名或拼接进字符串——脱敏按字段名匹配，改名可能绕过脱敏，导致隐私外泄。保留敏感字段原名或直接不输出。
- `$lookup` 关联大集合时注意被关联集合的关联字段应有索引（`SimCardManage._id`、`SimCardMonthlyData.simId` 已有）。
- 只需计数/分组时优先 `$group`，不要把明细 `$push` 出来再在 Agent 侧数。
- 需要把结果交给用户或后续脚本时，按 `localPath` 读取 NDJSON 文件处理。


## Redis

| 工具 | 参数 | 说明 |
|------|------|------|
| `data_redis_get` | `key`、`type`(string默认/hash/list/set) | 读取 key 的值（仅支持 string 和 hash） |
| `data_redis_exists` | `key` | 检查 key 是否存在并返回 TTL |

## PostgreSQL（告警快照）

| 工具 | 参数 | 说明 |
|------|------|------|
| `data_pgsql_query_snapshot_data` | `sn`、`date` | 按 SN 和日期查告警快照数据 |
| `data_pgsql_query_snapshot_file_record` | `file_name` | 查告警快照文件的解析记录 |

## EMS 参数字典

| 工具 | 参数 | 说明 |
|------|------|------|
| `data_emspara_pid_info` | `id`(PID ID 数字字符串) | 通过 PID ID 查宏名和描述 |
| `data_emspara_vid_info` | `id`(VID ID 数字字符串) | 通过 VID ID 查宏名和描述 |

用于把 EMS 日志/参数中的数字 PID/VID 翻译成可读含义。

## SIM 上游平台

优先用 `service_sim_*`（见主 SKILL.md 第 4 节）；需上游原始数据时用：

**Acceleronix**
| 工具 | 参数 | 说明 |
|------|------|------|
| `data_sim_acceleronix_card_info` | `iccid` | 单张 SIM 详情 |
| `data_sim_acceleronix_card_list` | `page`、`size` | SIM 卡列表 |
| `data_sim_acceleronix_batch_data_info` | `iccid_list`(逗号分隔)、`month`(YYYYMM) | 批量用量信息 |
| `data_sim_acceleronix_data_pool_list` | `page`、`size` | 流量池列表 |
| `data_sim_acceleronix_data_pool_sim_info` | `data_pool_id`、`page`、`size` | 流量池中的 SIM 详情 |

**SmartHub**
| 工具 | 参数 | 说明 |
|------|------|------|
| `data_sim_smarthub_card_info` | `giccid` | 单张 SIM 详细信息 |
| `data_sim_smarthub_batch_info` | `page`、`size` | 批量 SIM 信息 |

注意：Acceleronix 用 `iccid`，SmartHub 用 `giccid`；月份参数 Acceleronix 批量用量为 `YYYYMM`。