# 可复用接口与命令

本项目是独立研究模块，位于现有 `fashion-workbench` 下。采集、分析、存储与展示分离，不依赖小红书个人登录态、付费API或私有凭据。

## 快捷命令

PowerShell 工作目录：`D:\codex\fashion-workbench\runway-research`。

```powershell
# 发现更新、续传图片、重建报告；不重新做已完成视觉分析
.\update.ps1

# 仅重建本地数据和报告，不联网
.\update.ps1 -Offline

# 仅打开已有图册，双击index.html也可以
.\view.ps1
```

采集脚本各有 `--help`。巴黎支持 `--metadata-only`、`--download-only`、`--offline`、`--delay 0.8`；米兰支持 `--refresh`、`--metadata-only` 和品牌选择。新增年份需要新增来源配置并核实页面，不仅替换字符串中的年份。

统一更新入口为米兰启用 `--cnmi-all`，同时保留重点品牌官网来源。单独续传已发现的全部米兰公开图册，可运行 `python scripts/collect_milan.py --brands none --cnmi-all`；增加 `--refresh --metadata-only` 可只刷新目录和图片清单。纽约／伦敦新增品牌仍需先核验本季官方入口并补充 Provider，当前三品牌采集器不代表已实现两城全品牌采集。

## 本地HTTP接口 v1

运行 `scripts/serve.py --port 8765` 后访问 `http://127.0.0.1:8765`。仅监听本机；没有公网部署。

| 路径 | 返回 |
|---|---|
| `GET /api/v1/summary` | 更新时间、建档／下载／分析统计 |
| `GET /api/v1/shows` | 场次与素材覆盖 |
| `GET /api/v1/looks` | 图片资产及其分析 |
| `GET /api/v1/looks/{id}` | 一个稳定ID对应的全部原图与分析字段 |
| `GET /api/v1/sources` | 来源账本 |

列表支持 `offset`（默认0）、`limit`（默认100，最大1000）和 `brand`、`city`、`season`、`show_id`、`analysis_status` 精确筛选；`q` 对记录做不区分大小写搜索。Look列表中的city由所属show补入。返回 `total`、`offset`、`limit`、`items`、`generated_at`。非法分页返回400，未知ID返回404，目录尚未构建返回503。

例如：`/api/v1/looks?brand=Prada&analysis_status=reviewed&limit=20`。本接口只读，不允许网页触发采集或写入任意路径。

## Provider协议与事实接口

每个provider输出 `data/{provider}.json`，顶层为 `sources`、`shows`、`looks`。不让报告依赖网站特定字段。观察到的网站接口见对应脚本，使用方法和缓存记录存于 `raw/{provider}/`。

巴黎来源：FHCM `/en/paris-fashion-week/collections`、`/en/paris-fashion-week/calendar` 与实际发现的 `/en/collection/…` 页面。图册通过HTML解析，不构造不存在的原图尺寸URL。

米兰来源：CNMI `https://milanofashionweek.cameramoda.it/en/calendar`、页面公开使用的 `/api/fetchCalendarList`、实际关联的 `/en/brand/{event_id}`，以及品牌官方本季页面。具体参数与响应以本地采集器和原始快照为准，不假定长期稳定。

纽约／伦敦：官方日程及已验证品牌系列页，见 `data/season_registry.json` 与 `scripts/collect_other.py`。官网设计师主页可能是旧季图库，必须核验图像所属系列。

## 数据对象

`shows`：稳定ID、品牌、SS27、城市、场次日期、来源、抓取状态、公开图片期望数、下载数和复核数。`expected_looks` 是来源图册公开数量字段，可能含末尾谢幕；不能直接视为服装款数。

`looks`：稳定ID、show_id、品牌、城市、图册序号、可核实Look号、原图URL、本地路径、SHA-256、分析状态。`model_name=null` 表示未由官方文字确认。`analysis_status=pending` 不是无价值数据，而是原始图片可查但结论尚未填写。

`analysis`：复核日期、方式、范围分类、哈希、风格／颜色／廓形、可见证据、单品数组、面料候选、两条业务建议和风险。规范见 `data/analysis.schema.json`。

## 持久化与消费

- `data/catalog.json`：完整规范化交换数据。
- `data/catalog.js`：离线浏览用打包数据，不是上游事实源。
- `data/runway.sqlite3`：关系数据库。示例SQL：`SELECT brand, COUNT(*) FROM shows GROUP BY brand;`；逐款材料在 `materials` 表，材料候选不能当真实成分。
- `snapshots/`：更新前快照；`data/update_history.json`：执行结果。
- `raw/`：来源证据和HTTP缓存；`assets/`：原图。

默认更新复用图片文件和已审核分析。图片哈希不匹配将使分析过期。报告构建不发外部请求。只有图片已实际复核时才更新分析文件，避免每次重复模型处理。

## 官方细节与工作队列

`collect_details.py` 从已观察到的官方媒体清单下载细节图，默认只补已分析女装对应细节，`--all` 可补齐全部已发现细节，`--metadata-only` 只更新清单；固定串行与缓存复用。

`build_work_queue.py` 输出 `data/work_queue.json` 和 `docs/NEXT_RUN.md`，按品牌优先级列出缺图、已保存待分析、混秀范围待核和缺图册场次。`verify_assets.py` 校验可解码图像、哈希、关系、标注框及PDF可检索中文，并写入 `data/quality_check.json`。


## 材料频率统计接口

GET /api/v1/material-statistics 返回规范化材料方向、服装单品／图像／品牌分母、去重后的出现次数与比例、城市分布和证据等级。离线文件为 data/material_statistics.json，含分子对应的图像与单品 ID；分类规则在 data/material_taxonomy.json。

每次 build_reports.py 会调用 material_statistics.py 根据当前已复核女装重算，排除明确配饰和 alternatives；新候选名称进入待归并项，不能默认当成已有面料。标签多选比例可能超过100%，不要当纤维含量或全季份额。

export_pdfs.py --only fabric_report 可只重导面料报告。输出入口以 data/pdf_exports.json 为准；旧PDF被阅读器占用时保留原文件并另存更新版。

Chloé 补充采集器使用同一个巴黎 show_id，区分 FHCM 日程／官方视频与 Vogue 公开供图。其预系列不与10月秀场混合。