use_cninfo: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

这个 repo 是什么

cninfo-cli — 一个按需召唤型的 A 股公告抓取工具:CLI + Python 包,顺带给 Claude Code 提供一个 skill 入口。从巨潮资讯网(cninfo.com.cn)拉公告 PDF + PyMuPDF 提取的 md 全文,落本地缓存,二次访问秒级。

不是后台调度系统,不是数据池,不做增量同步 — 全是一次性命令,跑完即停。

常用命令

# 开发环境
uv venv --python 3.10
uv pip install -e ".[dev]"

# 跑测试(离线,32 个)
uv run pytest                       # 全跑
uv run pytest tests/test_api.py     # 单文件
uv run pytest -k "cache_hit"        # 按名字过滤

# Lint
uv run ruff check src tests
uv run ruff check --fix src tests   # 自动修

# 真机 smoke test(联网)
CNINFO_ALLOW_NETWORK=1 cninfo fetch-report 600519 --year 2024 --kind annual

# 重生成 fixture PDF(几乎不用)
python tests/fixtures/_make_pdf.py

架构关键点

单向依赖(从底到顶):

api.py        ← 纯函数,cninfo HTTP 客户端 + 时区/标题清洗
parser.py     ← PyMuPDF 包装
cache.py      ← ~/.cache/cninfo/ 三件套读写 + orgid_map
orgid.py      ← secCode→orgId(走 cninfo topSearch),用 cache.py 持久化
classify.py   ← argus_legal 薄包装(动态 import,缺失时抛 ClassifierUnavailable)
fetcher.py    ← 把上面拼起来:fetch_announcement / iter_* / find_periodic_report
cli.py        ← argparse,6 个子命令

测试隔离:conftest.py autouse fixture 默认禁用真实网络(requests.{get,post} 抛错),要联网测时设 CNINFO_ALLOW_NETWORK=1 或在测试里 mock。

缓存命中策略:pdf + md + meta 三件齐全才算命中;任一缺失走未命中路径。--force 跳过命中检查。

接口约束(继承自 cninfo,不要尝试"修复")

详见 docs/gotchas.md 14 条。最关键的 4 条:

1. pageSize 服务端硬限 30 — 必须翻页(api.py:query_all 已处理)
2. stock 必须 <6位>,<orgId> — 仅传 6 位返 0 条;本仓库通过 topSearch 拉 orgId(orgid.py),首次发现的 orgId 也会顺带缓存进 orgid_map.json
3. announcementTime 是 UTC epoch ms — 必须按北京时区转(api.py:epoch_ms_to_ann_date),否则跨日公告 ann_date 差一天
4. 同一公告可能有 2 条记录 — announcementId 不同 PDF 内容相同;is_periodic_report_body 已排除摘要/审计/内控,但全市场场景下用户需自行去重

改动指引

修接口参数 / 加 category / 加新场景:

• 改 api.py(常量 / 函数)→ 同步更新 docs/api_reference.md 那张表
• 加 fixture(tests/fixtures/) → 加单测

新增 CLI 子命令:

• cli.py 的 build_parser() 加子 parser,cmd_xxx 写动作,默认 JSON 优先 + 表格可选
• 一定要在 tests/test_cli.py 加一个走 main([...]) 的覆盖(可只看返回码 / stderr)