# Premium Cabin Collector — 参考手册

与 [`SKILL.md`](../SKILL.md) 配合使用：主文件写门禁、进度与阶段总览；本文件写**输出目录规范**、**各 Phase 命令**、**验收与复盘**。

---

## 路径与依赖

- **技能根目录**：`SKILL.md` 所在目录（含 [`scripts/`](../scripts/)）。
- 命令中的 `--output` 可为绝对路径或相对于**当前工作目录**的路径。
- Python 依赖：`pip install requests beautifulsoup4`
- 使用 **Claude Code** 时：默认危险权限、`settings.local.json` 白名单（含 `Bash(*)`）及「Shell expansion」类弹窗处理，见 [`SKILL.md`](../SKILL.md) 中「Claude Code：默认危险权限」。

---

## 输出约定

### 最深层目录（定义）

- **单类型机型**（seatmap 仅 **1** 个类型）：**机型根目录**即为最深层；其下直接放 `机型详情.md` 与 `images/`。
- **多类型机型**（seatmap 显示 **N** 个类型，N>1）：**每个类型对应一个版本子目录**（如 `V.1`…`V.N` 或与页面一致的 `ULR` 等），**该子目录内部**为最深层；每个最深层内须有 `机型详情.md` 与 `images/`（六项子目录见下）。
- 机型根级可额外保留汇总的 `机型详情.md`、`完整内容整理.md`、`版本索引.md`、根级 `images/`（与历史数据一致时保留）；**不得**用根级 `images/` 替代某个类型最深层下的完整结构。

### 强制目录结构（每个最深层）

每个最深层须包含：

- 该层根：`机型详情.md`（**强制**；单类型机型在机型根目录，多类型机型在每个 `V.x` 子目录内）
- `images/`，且其下**必须存在**下列 **6 个子目录**（名称固定；`1`～`5` 为对 `0-原始数据` 的语义整理归类，不删改原始层）。同级可保留 `classification-report*.md` 等辅助文件，但六项子目录**缺一不可**：

| 子目录 | 用途 |
|--------|------|
| `0-原始数据` | 首次抓取原文、原图；**只追加、不删除** |
| `1-座椅布局` | 座位图、舱位平面等（从原始数据整理归类） |
| `2-座椅图片` | 座椅实物照片等 |
| `3-机上餐食` | 餐食、菜单相关 |
| `4-娱乐设备` | IFE、端口、Wi‑Fi 等 |
| `5-其他信息` | 外观、logo、杂项等 |

### 重要规则（强制）

| 规则 | 说明 |
|------|------|
| **单类型机型** | 机型根目录即为最深层，必须在根目录创建 `机型详情.md` |
| **多类型机型** | 每个类型对应一个 `V.x` 子目录，每个 `V.x` 内必须有 `机型详情.md` + 完整 `images/` |
| **禁止根级 images** | 多类型机型的机型根级**不得**保留 `images/` 目录（数据应完整存在于各 `V.x/images/` 内） |
| **seatmap 哈希验证** | `0-原始数据` 与 `1-座椅布局` 中的 seatmap 文件必须与 seatmaps.com 上各版本的 hash ID 一致（32 位 hex） |

### 目录结构示例（单版本）

```text
机型名称/
├── 机型详情.md
└── images/
    ├── 0-原始数据/
    ├── 1-座椅布局/
    ├── 2-座椅图片/
    ├── 3-机上餐食/
    ├── 4-娱乐设备/
    └── 5-其他信息/
```

### 多类型 / 多版本机型结构示例

- **类型数校验**：seatmap 上该机型的 **「类型」数量 = N** 时，机型目录下必须有 **N 个**最深层类型子目录（示例为 `V.1`…`V.N`）；并建议根级维护 `版本索引.md`，列出类型与目录对应关系。
- 每个 `V.x` 内均为 **`机型详情.md` + `images/`（六项子目录齐全）**。

```text
Airbus A380/
├── 机型详情.md
├── 版本索引.md
├── 完整内容整理.md
├── V.1/
│   ├── 机型详情.md
│   └── images/
│       ├── 0-原始数据/
│       ├── 1-座椅布局/
│       ├── 2-座椅图片/
│       ├── 3-机上餐食/
│       ├── 4-娱乐设备/
│       └── 5-其他信息/
├── V.2/
│   └── …
└── …（直至 V.N，N = seatmap 类型数）
```

---

## 主流程命令参考

以下均假设当前工作目录为输出父目录（例如用户项目根）。将 `SKILL_ROOT` 设为真源目录，例如：

```bash
SKILL_ROOT="${SKILL_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
```

### Phase 1 — 确认范围

明确：航司名称、单机型或全航司、输出目录（如 `FlightData/` 或绝对路径）。

### Phase 2 — 获取机型列表

航司列表入口：`https://seatmaps.com/zh-CN/airlines/`
输出：`[Progress] Found aircraft count: X`（或等价说明）。

### Phase 3 — 抓取机型数据

在技能 [`scripts/`](../scripts/) 目录下执行（**注意使用 ASCII 连字符 `--`**）：

```bash
python "$SKILL_ROOT/scripts/scrape_seatmaps.py" --airline "航空公司中英文名称" --output FlightData/
```

单机型 URL：

```bash
python "$SKILL_ROOT/scripts/scrape_seatmaps.py" "https://seatmaps.com/zh-CN/..." --output FlightData/
```

可选：`--limit N`、`--dry-run`。航司名称映射与更多示例见 `scrape_seatmaps.py` 文件头注释。

**可选一键子流程**：在 `SKILL_ROOT` 下 `node scripts/batch-process.js --airline "航司名" --output FlightData/`（以脚本实现为准）；若与手工阶段冲突，以用户要求的阶段为准。

**餐食与官网回退（强制，与 [`SKILL.md`](../SKILL.md) 一致）**：

- 先完成 seatmaps 侧该机型的正文与图片抓取。
- 若判定 seatmaps **无餐食 / 菜单 / 餐饮**相关内容或素材，**必须**继续访问**当前航司官方网站**（餐饮、机上体验、媒体库等合理入口）尝试补抓；补抓内容写入**对应最深层**的 `images/0-原始数据/`（只追加），并在文档中标注来源为官网。
- 仅当官网经合理尝试仍不可得时，在 `机型详情.md` 或验收说明中记录「已尝试 seatmaps + 官网」。

### Phase 4 — 原始归档

确保首次抓取的文本与图片已进入**各最深层**的 `images/0-原始数据/`（只追加）。多类型机型须按类型分别归档到对应 `V.x/images/0-原始数据/`，不得混在同一类型目录内。

### Phase 5 — 语义分类

```bash
cd "$SKILL_ROOT/scripts"
node classify-images-v2.js --airline "航司名"
# 或
node classify-images-v2.js --base-dir "/path/to/FlightData/航司目录"
```

若需与其它版本脚本（如 `classify-images-v3.js`）对齐，以仓库内脚本说明为准。

### Phase 6 — 去重

```bash
cd "$SKILL_ROOT/scripts"
node dedup-images.js --airline "航司名"
# 或
node dedup-images.js --base-dir "/path/to/FlightData/航司目录"
```

### Phase 7 — 多类型 / 多版本检测

- 以 seatmap **页面标明的「类型」数量 N** 为准：目录中必须存在 **N 个**类型子目录，与页面一一对应；**禁止**少建、合并或仅用根级 `images/` 代替。
- 每个类型子目录内必须有 `机型详情.md` 与完整的 `images/` **六项子目录**（见上文「强制目录结构」）。
- 若历史数据命名与 `V.1`…`V.N` 不一致，迁移时保持**数量与语义**与 seatmap 类型一致，并更新 `版本索引.md`。
- 复杂迁移可使用仓库内 `organize-a330-versions*.js` 等脚本作为参考或基础。

### Phase 8 — 文档生成

生成或更新：航司级 `README.md`、各机型（及各最深层）`机型详情.md`、多类型机型的 `版本索引.md`、必要时 `完整内容整理.md`。餐食若来自官网补抓，须在相应文档或元数据中注明来源。

### Phase 9 — 清理中间文件

删除或移走：`classification-report*.md`、其它临时文件（以不删 `0-原始数据` 内容为前提）。

---

## 完成检查

输出：`[Progress] Running final validation…`

核对：

- 航司/机型侧 `README.md`、`机型详情.md` 是否存在且可读；多类型机型须有 `版本索引.md`（或与用户历史命名等价的索引文档）
- **每个最深层**的 `images/` 下是否存在 `0-原始数据`～`5-其他信息` 六个子目录（名称完全一致、无遗漏）；若存在 `classification-report*.md` 等辅助文件，不与上述六项冲突即可
- **类型数**：seatmap 显示的「类型」数量是否与机型下类型子目录数量一致，且每个类型目录内结构完整
- **餐食**：若 `3-机上餐食` 在 seatmaps 侧为空，是否已按规则尝试航司官网补抓；若仍无，是否有书面说明「已尝试双源」
- 无多余重复图片/重复正文（在允许的归档规则内）

最后：`[Progress] Task finished successfully`

---

## 自我学习机制（任务后复盘）

每轮任务结束后简要复盘并**写入可查找的笔记**（例如用户约定的工作区 `memory/YYYY-MM-DD.md` 或本仓库旁的采集备注），避免仅在对话中"说过就算"。

### 必查项

- 是否漏做多类型（类型数与 `V.x` 数量不一致）或错误合并
- 每个最深层 `images/` 六项子目录是否齐全；`0-原始数据` 是否被误删或覆盖
- seatmaps 无餐食时是否执行过官网回退；`3-机上餐食` 长期为空时原因是否可追溯
- 是否重复下载或可合并的重复资源
- 正文与图片是否漏抓、误分入 `1`～`5` 目录
- 临时文件是否已清理

### 新案例沉淀

遇到新航司或新页面结构时记录：航司、机型、是否多版本、页面特殊点、分类异常与**正确处理步骤**。

### 错误沉淀

对漏版本、漏图、重复数据、分类错误记录：**原因 + 修复方式 + 如何预防**。

### 批量回顾

每完成一个航司的批量采集：对照清单看结构是否统一、机型与版本是否齐全。

**目标**：同一套 skill 越用越稳定、越用越完整，形成长期可复用的航司机型数据库。