# 输入数据放置指导（v0.1 · 2026-09-17）

> 适用：把现场给的原始数据放进 `<安装目录>\data\raw\`。放完之后页面与重算链都读这里，
> **放错一层目录、名字写错，后面所有摄入都会读不到**（不会报错，只会"页面没数"）——所以先体检再放。
>
> 配套工具：
> * `python scripts/raw_data_check.py` —— **放置体检**（结构/命名/增量三清单/放置指导）；
> * `python scripts/place_raw_data.py --src <现场包目录>` —— 按映射表**自动落位**（落位前自动跑体检，冲突会拦下）；
> * `python scripts/scan_stations.py` —— 扫 `data/raw` 有哪些场站、各源类齐不齐。

---

## 1. 正确的位置长什么样

```
<安装目录>\data\raw\
├─ README_把原始数据放这里.txt          ← 说明文件可以留在这一层
├─ 如东\                                ← 场站目录（下一级目录名 = 场站；扫描按此辨识）
│   ├─ scada_10min\                     ← 平铺 <机组>.csv（WTG01.csv … WTG38.csv）
│   ├─ scada_1min\                      ← 平铺 <内部台号>.csv（01E.csv … 37B.csv）
│   ├─ 故障报警\                         ← 年度/季度 .xls + XML 报警导出
│   ├─ 风机故障记录\                      ← 年目录 + 月度汇总表(.xls/.xlsx) + .rar + 现场照片
│   ├─ 油样报告\                         ← **两级**：<台号>\<部件>\*.pdf
│   ├─ windcms\                         ← 振动线 CMS 原始导出：<包名>\measurement\<年>\<月>\<WTGxx>\*_decode.json
│   │   └─ 厂家报告\上海电气_月度\          ← 厂商月度振动评估报告（PDF 扫描件）
│   └─ m5_cms_tcm\                      ← 振动线 handoff 正本 + 厂家报告\
│       └─ 厂家报告\
└─ 西门子4.0技术资料\                     ← 与场站并列的**共享**技术资料（本体层 kb_ingest 读它）
```

**判断标准只有一条**：摄入脚本按"源类目录 → 再往下一层就是文件"读。多套一层包名目录
（`scada_10min\10分钟数据\WTG01.csv`）等于没放。

## 2. 每类源件的规则（体检器逐条查）

| 源类 | 允许的后缀 | 结构要求 | 体检器会报什么 |
|---|---|---|---|
| `scada_10min` | `.csv` | 平铺，**每台一个文件**，名字 = 场配置里的机组号（WTG01…） | 缺台（按台取数会空白）、文件名不是本场机组、多套一层 |
| `scada_1min` | `.csv` | 平铺，名字是**内部台号**（01E…37B） | 台数与场配置不符（1min 导出不用 WTG 名，故按台数判） |
| `故障报警` | `.xls` `.xlsx` `.xml` | 不许多套层 | 后缀不在约定内 |
| `风机故障记录` | `.xls` `.xlsx` `.rar` `.jpg` `.png` | 年目录 + 月度表 | 后缀不在约定内 |
| `油样报告` | `.pdf` | **两级** `<台号>/<部件>/*.pdf` | PDF 直接躺在源类根下（维护页按台/部件分组，会分不出来） |
| `windcms` | `.json` `.pdf` `.docx` | 含 `*_decode.json`（可套 `<包名>/measurement/…` 层） | 没有 `*_decode.json` ⇒ 振动侧无源可算 |
| `m5_cms_tcm` | `.json` `.docx` `.pdf` `.md` | handoff 正本（`handoff_vibration_v2.json` / `component_history.json`）+ `厂家报告/` | 缺正本时**由观澜自算件顶上**（`scripts/rudong_fusion_handoff.py` / `scripts/component_history_build.py`）；现场有正本则以正本为准 |

## 3. 增量放置（重点）

**"增量"= 只补新数据，不要重放全量。** 放置工具与体检器都按**同名同尺寸**判断：

| 情况 | 判定 | 处置 |
|---|---|---|
| 目标不存在 | **新增** | 拷进去 |
| 目标存在、大小相同 | **相同（跳过）** | 不重复拷（源件是只读输入，同尺寸视为同一份） |
| 目标存在、大小不同 | **冲突** | **必须人确认**：是"现场更正了数据"还是"这是另一批？" —— `place_raw_data.py` 默认**拒绝**落位，要覆盖需显式 `--force` |

```powershell
# 1) 先看会新增/跳过/冲突什么（不写盘）
python scripts\raw_data_check.py --src D:\现场增量包
# 2) 自动落位（落位前会再体检一次；有冲突会被拦下）
python scripts\place_raw_data.py --src D:\现场增量包
python scripts\place_raw_data.py --src D:\现场增量包 --force     # 确认要覆盖时才加
# 3) 落完再体检一次（含可读性抽样：CSV 编码/表头、TCM json 字段）
python scripts\raw_data_check.py --deep
```

**为什么不让它悄悄覆盖**：源件是**只读输入**，覆盖不可逆；而台账类产物（报警 39,211 / 工单 5,876 /
油样 404）是逐行对齐源件的，覆盖后若没重算，页面与源件就对不上了。

## 4. 放完之后做什么（体检器会按新增的源类给命令）

★ **不用自己记"放了什么"**（用户令 2026-09-19 增加自动扫描识别）：放完直接看扫描结论 ——

```
python scripts\raw_scan.py --check      # rc=0 无变化 · rc=4 有新数据(它会列出"该跑哪几步") · rc=5 还没基线
python scripts\rebuild_all.py --auto    # 先扫一遍再重算: 新数据落在被 --skip-* 跳过的族里时自动取消跳过
```

`--check` 的逐族口径是**指纹**（件数 / 体积 / 最新落盘时间 / 清单摘要；`--deep` 再叠内容哈希），
snapshot 落在 `outputs\<场>\_raw_scan.json`，重算链第 **①b** 步每次都会顺手更新它。
若想让服务自己盯着（每 N 分钟扫一次、可选自动重算）：`configs\serve.json` 的 `raw_watch`
（默认关：`{"enabled": false, "minutes": 30, "auto_rebuild": false}`）。

| 新增的源类 | 该跑的重算 | 预计 |
|---|---|---|
| `scada_10min` / `scada_1min` | `python scripts\rebuild_all.py` | 含 10 个构建器，约 15 分钟 |
| `故障报警` / `风机故障记录` / `油样报告` | `python scripts\rebuild_all.py --skip-scada` | 约 2 分钟 |
| `windcms` / `m5_cms_tcm` | 同上（重算链第 ④b 步自动摄入索引/谱 + 报告/在升闭环/三层基线） | 按数据量（153 GB 导出约 25 分钟索引+谱） |
| `scada_mdb`（现场年度归档库） | 同 `scada_10min`（CSV 缺失时取数层会回落到 MDB） | 同 ③/④/④c |
| 只放了文档/技术资料 | 无需重算（不影响页面数值），但 `西门子4.0技术资料` 变了要重跑 ⑦ 本体层 | — |

重算后核对锚点：报警 **39211** · 工单 **5876** · 油样 **404** · `temp_monthly` **19494** · 本体 **9702** 对象（审计 0 问题）；
页面看 `/detail/` 左栏「系统维护」两屏。若某页仍无数据，先看 `logs/ops/` 里最近一次动作的退出码。

## 5. 常见错误（都是体检器实测报过的）

| 现象 | 体检器的话 | 怎么修 |
|---|---|---|
| 把 csv 直接解到 `data/raw/` 根下 | `data/raw 顶层只放场站目录与说明文件; 源件要放进 <场站>/<源类>/` | 移进 `<场站>/scada_10min/` |
| 多套了一层包名 | `未约定的子目录 (约定: [...]) —— 常见成因: 解压时多套了一层包名` | 把文件上提一层（`place_raw_data.py` 的映射表已按现场包结构写好，直接用它可以避免） |
| 油样 PDF 平铺 | `N 个 PDF 直接躺在源类目录下 —— 约定是 <台号>/<部件>/*.pdf` | 按台号/部件建两级目录 |
| 1min 目录被判"缺 38 台"（旧版本） | 已修：1min 用内部台号，按台数判完整 | 若台数确实不足，补齐对应台号的 csv |
| 现场包被截断 | `不是合法 zip` | 重新拷贝现场包 |
| 整包 zip 丢进场站目录 | `压缩包直接放在场站目录下 —— 先解压再按源类落位` | 解压后再放（或直接 `place_raw_data.py --src`） |

## 6. 规则表与本次体检结论

<!-- RAWCHECK:BEGIN -->
### 体检结论（自动生成，勿手改）

· 源件目录 `data/raw/如东`：26,325 件 / 177.64 GB
  - `m5_cms_tcm/`：1 件 / 20.8 MB
  - `scada_10min/`：38 件 / 14722.7 MB
  - `scada_1min/`：38 件 / 13074.1 MB
  - `windcms/`：25,693 件 / 153751.0 MB
  - `故障报警/`：16 件 / 22.7 MB
  - `油样报告/`：404 件 / 168.1 MB
  - `风机故障记录/`：135 件 / 142.3 MB

· 结构与命名检查：**无不一致**（提示见下）
· `i` data/raw/如东/m5_cms_tcm：缺 handoff 正本 (handoff_vibration_v2.json / component_history.json) —— 融合面判级与 /cms/ 改用**观澜自算**件（`scripts/rudong_fusion_handoff.py` / `scripts/component_history_build.py`，链上 ④b/④d）；现场给了正本则正本优先
· `?` data/raw/如东：源件合计 177.6 GB —— 摄入与重算会很慢, 建议分批

**放置后该做什么**：
· 没有新增源件: 不必重算 (若刚换过数据, 用 scripts/rebuild_all.py --dry-run 看计划)

<!-- RAWCHECK:END -->

---

**退出码**（给脚本/CI 用）：`0` 合规（可能带提示）· `5` 结构或命名违例 · `6` 增量冲突（同名不同大小）·
`7` 缺源类或时间空洞 · `8` 仅有提示（体量/无消费者目录/散装件）。