# ana-data 目录导读

创建人员：Codex  
文件职责：说明 `project-info` 项目案例分析数据目录的定位、正式归档路径、现有行业数据容器、来源材料入口和工具目录边界。  
管理规范/模板：`../项目规范.md`；`../ana-doc/案例分析规范.md`；`../ana-doc/案例存储体系.md`；`../../common/ana-doc/案例存储体系创建指南.md`。  
引用文件：`../ana-doc/目录导读.md`；`../ana-doc/案例存储体系.md`；`../ana-doc/数据抓取脚本说明.md`；`tools/README.md`；`../项目配置清单.md`。  
记录方式：目录入口文档；本目录一级结构、正式归档口径、行业数据容器或来源材料入口发生新增、删除、改名或职责变化时同步更新。

## 1. 目录定位

`ana-data/` 是 `project-info` 案例分析体系的数据、资料、证据、图片、结果包和可重建中间产物存储区。

本目录不替代 `../ana-doc/` 的规范、设计、执行日志和审计入口。正式结论必须回写到对应案例文档或结果入口，并通过 manifest、证据映射或等价索引追溯到原始资料和处理过程。

## 2. 标准目录入口

| 目录 | 作用 | 使用边界 |
|---|---|---|
| `cases/` | 保存行业统一原始资料池、行业级通用处理产物，以及逐案例输出、引用清单和证据映射 | 正式资料和产物的主存储区；按行业、案例和 manifest 管理 |
| `result/` | 保存父体系结果入口、对外交付包、跨案例汇总结果和审计辅助输出 | 可以引用案例输出，但不能替代证据链 |
| `img/` | 保存图片、图册、研报截图、OCR 图片、标注图和图片 manifest | 被结论引用的图片必须登记来源和用途 |
| `tmp/` | 保存转换缓存、调试文件、临时草稿和其他可重建中间产物 | 不得作为正式证据、正式结果或审核入口 |
| `tools/` | 保存数据抓取、外部来源归档、MySQL 只读导出和市场反向补漏脚本 | 脚本产物不得留在本目录；具体用法见 `tools/README.md` |

标准研报行业数据根目录使用以下结构：

```text
cases/<行业案例>/
  raw/
  converted/
  extracted/
  supplement/
  evidence/
  manifest/
```

逐案例自定义产物使用以下结构：

```text
cases/<行业案例>/<case_id>/
  outputs/
  manifest/
  evidence/
```

父体系兼容入口使用以下结构：

```text
tmp/<行业案例>/<case_id>/<run_id>/
result/<行业案例>/<case_id>/
img/<行业案例>/<case_id>/
```

## 3. 当前案例数据容器

`cases/` 当前包含以下一级数据容器：

| 目录 | 当前用途 |
|---|---|
| `半导体案例/` | 半导体行业统一资料、处理产物和案例级结果容器 |
| `机器人案例/` | 机器人行业统一资料、处理产物和案例级结果容器 |
| `军工案例/` | 军工行业统一资料、处理产物和案例级结果容器 |
| `有色案例/` | 有色行业统一资料、处理产物和案例级结果容器 |
| `宏观地缘案例/` | 宏观地缘方向的补充资料容器 |
| `geo_jp_shock/` | 日本冲击相关专项数据、查询 manifest 和补充结果容器 |
| `股票估值/` | 跨行业股票估值任务输入、截图原件、来源登记、证据manifest和任务清单；正式结果位于`../result/股票估值/` |

行业容器的规范、设计、执行和审计入口位于 `../ana-doc/` 下对应行业案例目录或父级案例账本。新增行业或专项容器时，应同时确认文档入口、目录结构和 manifest 责任，不得只创建孤立数据目录。

## 4. 现有来源材料入口

本目录当前还保留以下按来源命名的材料目录：

| 目录 | 内容概况 |
|---|---|
| `news-大飞/` | 按来源收集的文本材料 |
| `news-大户/` | 按来源收集的直播转写、会议纪要及附件 |
| `news-滚雪球之路/` | 按来源收集的行业和市场文本材料 |
| `news-青枫浦上Q/` | B 站 UID `1420210197` 的正文、原图、视频转写和纪要归档；统一命名、迁移别名、Git 边界及半小时恢复规则见该目录 `目录导读.md` |
| `news-小郑/` | 按来源收集的直播转写、会议纪要及附件 |
| `news-熊猫财经/` | 按来源收集的文本和会议纪要 |
| `new-金融学长/` | 按月份整理的来源材料 |

这些目录记录的是当前实际存在的来源材料入口。材料尚未迁入 `cases/<行业案例>/raw/` 并完成 manifest 或等价索引登记前，只能视为待归档来源材料，不能直接作为正式证据、正式结果或审核入口。

如后续整理、迁移或重命名这些目录，应先保护原文件和来源信息，再更新引用、manifest、迁移记录和本导读；历史引用仍依赖旧路径时，应保留迁移说明或兼容入口。

## 5. 存放与追溯规则

1. 原始研报、公告、网页快照和外部资料原件先进入对应行业统一 `raw/`，保持不可覆盖、不可改写。
2. 转换文本、OCR、表格抽取和格式标准化结果进入行业级 `converted/`。
3. 通用事实抽取和指标候选进入 `extracted/`；外部补证和市场反向补漏材料进入 `supplement/`。
4. 通用证据事实和来源定位进入行业级 `evidence/`；具体案例的结论证据映射进入 `<case_id>/evidence/`。
5. 原始文件和正式产物必须进入 manifest 或等价数据库记录，至少能够追溯来源、相对路径、文件哈希、处理批次、生成时间和状态。
6. 路径默认使用相对项目根目录的写法，不在正式索引和文档中新增依赖个人机器的绝对路径。
7. `tmp/` 中只放可重建内容；需要交付或审核的产物必须迁入正式目录并补齐索引。
8. `tools/` 中只放可复用工具和工具说明；`__pycache__/` 等运行缓存不属于正式产物。
9. 研究资料、转写和纪要只代表来源内容；未经交叉验证、证据登记和审核，不直接转化为项目事实或投资结论。

## 6. 快速读取顺序

人或 AI 进入本目录工作时，建议依次读取：

1. `../ana-doc/目录导读.md`：确认案例体系、行业文档和审核入口。
2. `../ana-doc/案例存储体系.md`：确认当前存储结构、manifest 字段和正式产物口径。
3. 对应行业的案例分析设计、执行日志和审核记录：确认本次任务允许使用的数据范围。
4. 对应行业 `cases/<行业案例>/manifest/`：定位原始资料、批次、处理状态和产物路径。
5. 如需运行脚本，再读取 `../ana-doc/数据抓取脚本说明.md` 和 `tools/README.md`。