数据抓取脚本说明

创建人员：Codex
文件职责：说明 project-info/ana-data/tools 中数据抓取、外部来源归档和本地 MySQL 只读导出脚本的使用口径。
管理规范/模板：案例分析规范.md；案例存储体系.md；案例审核规范.md；研报体系导读.md。
引用文件：案例分析规范.md；案例存储体系.md；案例审核规范.md；研报体系/研报分析架构.md。
记录方式：工具使用说明；新增、下线或改变抓数脚本时同步更新。

1. 定位

ana-data/tools/ 是研报案例体系的工具脚本入口，不是新的数据目录，也不是正式证据库。脚本用于帮助案例分析员完成外部资料抓取、本地数据库只读导出和市场反向补漏初筛。

正式数据仍按 案例存储体系.md 落点：

1. 原始研报、公告、网页保存件和外部资料原件进入 ana-data/cases/<行业案例>/raw/ 或 supplement/。
2. 外部补充来源、网页快照、市场显影初筛和查询导出进入 ana-data/cases/<行业案例>/supplement/。
3. 证据链、范围闸门、结论证据映射进入 evidence/。
4. 来源、参数、hash、SQL、脚本输出清单进入 manifest/。
5. 临时调试文件进入 ana-data/tmp/<行业案例>/<case_id>/<run_id>/，不得作为正式证据入口。

2. 使用前提

案例分析员使用这些脚本前必须满足：

1. 父级 案例总纲.md 已登记真实案例。
2. 行业 案例分析设计.md 已写清 case_id、batch_id、run_id、输入范围、输出物、存储路径和验收方式。
3. 需要网上补充、外部信息、新闻公告、事件链、市场显影或暗线判断时，必须使用 darkline 技能和信息拓扑方法。
4. 设计审核未通过前，只能做资料盘点或 dry-run，不得把脚本产物作为正式结论依据。
5. 使用脚本后必须在行业 案例执行日志.md 记录脚本名、参数摘要、输出路径、manifest 路径、异常和自检结论。

3. 脚本清单

4. 外部网页和文件抓取

适用场景：

1. 抓取交易所、政府、行业协会、公司官网、投资者关系、公开报告页面。
2. 保存外部网页快照，作为缺口补证或 source gap audit 输入。
3. 抓取明确 URL 的 PDF、CSV、JSON 或文本资料。

示例：

python ana-data/tools/collect_web_sources.py `
  --industry-case 有色案例 `
  --case-id ANA-YS-INDUSTRY-001 `
  --batch-id BATCH-003 `
  --run-id RUN-ANA-YS-INDUSTRY-001-BATCH-003 `
  --url "https://www.lme.com/market-data/reports-and-data/lme-official-prices" `
  --target supplement

使用要求：

1. URL 必须是显式给出的公开来源，不使用脚本绕过登录、付费墙、验证码或反爬限制。
2. 抓取网页用于补资料或市场显影时，设计和日志里必须说明已使用 darkline 方法。
3. 输出文件和文本快照只作为来源材料；进入结论前还必须抽取证据、标记时间戳和来源置信度。
4. 抓取失败也会进入 manifest，分析员应在执行日志说明是否重试、换源或保留缺口状态。

5. 本地 MySQL 只读导出

适用场景：

1. 从本地 tianxia 数据库导出 A 股 K 线、公司画像、行业概念、市场广度或其他已纳入全局公共表的数据。
2. 为公司池、市场反向补漏、涨停/强势股扫描、公司列表补证生成 CSV。
3. 将 SQL、输出 CSV 和执行记录纳入 manifest，方便审核员复核。

环境变量：

$env:TIANXIA_MYSQL_PASSWORD='本机 MySQL 密码'

示例：

python ana-data/tools/export_mysql_query.py `
  --industry-case 有色案例 `
  --case-id ANA-YS-INDUSTRY-001 `
  --batch-id BATCH-003 `
  --run-id RUN-ANA-YS-INDUSTRY-001-BATCH-003 `
  --artifact-name ys_company_profile_candidates `
  --sql "SELECT snapshot_date, symbol, stock_name, industry_l1, industry_l2, concepts_raw FROM a_share_profile_snapshot WHERE industry_l1 LIKE '%有色%' LIMIT 200"

使用要求：

1. 只允许 SELECT、WITH、SHOW、DESCRIBE、DESC、EXPLAIN 类只读语句。
2. 禁止 INSERT、UPDATE、DELETE、CREATE、DROP、ALTER、LOAD、REPLACE、TRUNCATE、GRANT 等写入或管理语句。
3. 不得在命令行、SQL 文件、说明文档或输出 manifest 中写数据库密码。
4. SQL 文件会进入行业 manifest/，输出 CSV 进入指定 supplement/、evidence/ 或 manifest/。

6. 市场反向补漏扫描

适用场景：

1. 准备输出行业视图、市场视图、公司视图前，检查近 3 个月是否存在研报样本遗漏的强显影公司。
2. 用本地 a_share_profile_snapshot 和 a_share_daily_price 初筛公司池和行情表现。
3. 给后续人工或 AI 的 scope 闸门、公司核心业务重归因和补资料队列提供输入。

示例：

python ana-data/tools/market_gap_scan_mysql.py `
  --industry-case 有色案例 `
  --case-id ANA-YS-INDUSTRY-001 `
  --batch-id BATCH-003 `
  --run-id RUN-ANA-YS-INDUSTRY-001-BATCH-003 `
  --start-date 2026-03-26 `
  --end-date 2026-06-26 `
  --keyword 有色 `
  --keyword 铜 `
  --keyword 铝 `
  --keyword 锂 `
  --keyword 稀土 `
  --keyword 黄金 `
  --keyword 小金属

输出口径：

1. market_manifestation_gap_audit_*.csv：强显影候选、涨幅、强势日、放量指标和待 review 状态。
2. market_manifestation_gap_summary_*.json：扫描窗口、关键词、参数和结果摘要。
3. market_manifestation_gap_manifest_*.csv：SQL、输出路径、row_count 和审核状态。

使用要求：

1. 扫描结果只表示市场显影和资料缺口，不是投资建议。
2. 每个候选公司必须再按行业方案做核心业务重归因，标记 CORE_INDUSTRY、ADJACENT_DOWNSTREAM 或 FALSE_THEME_OR_NOISE。
3. CORE_INDUSTRY 才能进入补资料队列；ADJACENT_DOWNSTREAM 单独 review；FALSE_THEME_OR_NOISE 只保留审计记录。
4. 需要解释异常行情、新闻公告、事件链或暗线时，必须继续使用 darkline 方法。

7. 设计和日志写法

行业 案例分析设计.md 至少写清：

1. 是否需要抓取外部资料、MySQL 导出或市场反向补漏。
2. 使用哪些脚本、输入范围、关键词、日期窗口、SQL 来源和输出路径。
3. 脚本产物如何进入 supplement/、evidence/、manifest/ 和后续证据数据卡。
4. 审核员如何复核脚本参数、SQL、输出 row_count、hash、manifest 和结论边界。

行业 案例执行日志.md 至少记录：

1. 脚本名和执行时间。
2. case_id、batch_id、run_id。
3. 参数摘要，不记录密码。
4. 输出文件路径和 manifest 路径。
5. 成功、失败、重试、缺口保留或降级状态。

8. 审核口径

审核员检查脚本产物时，至少确认：

1. 脚本使用已经在设计中声明，或执行日志解释了必要偏离。
2. 输出没有留在 ana-data/tools/ 或私人工作区。
3. SQL 是只读语句，且没有泄露密码、token、cookie 或私有凭据。
4. 输出 CSV、网页快照、SQL、summary 和 manifest 能互相反查。
5. 市场反向补漏结果没有直接写成投资结论。
6. 需要 darkline 的场景已经按 darkline 方法留痕。

9. 禁止事项

1. 不得把 ana-data/tools/ 当成结果目录或证据库。
2. 不得让脚本绕过设计审核、执行日志、manifest 和执行审核。
3. 不得抓取需要登录、付费、验证码或明确禁止自动访问的来源。
4. 不得把数据库密码、token、cookie 或授权信息写入脚本参数、SQL 文件、manifest 或输出文档。
5. 不得执行写库 SQL 或修改全局公共表。
6. 不得把市场显影扫描结果直接当作行业覆盖完整、公司推荐或买卖建议。