A股成交额集中度历史分位（AkShare）

Purpose

只使用 AkShare 获取数据，计算沪深京 A 股成交额前 1%/3%/5% 占比和历史分位。执行前阅读 references/methodology.md。

Data Sources

• 交易日历：tool_trade_date_hist_sina
• 当前沪深京证券池：stock_info_sh_name_code、stock_info_sz_name_code、stock_info_bj_name_code
• 沪深退市证券池：stock_info_sh_delist、stock_info_sz_delist
• 默认历史成交额：stock_zh_a_hist，不复权
• 可选 AkShare 历史接口：stock_zh_a_hist_tx 或 stock_zh_a_daily
• 收盘后全市场增量快照：stock_zh_a_spot

不得用 Tushare、Wind、iFinD、聚宽或外部行情文件填充失败证券或缺失日期。AkShare 底层公开提供方必须在输出中保留，不得只写“AkShare”而隐藏实际接口。

Workflow

1. 预检

• 确认 python3、akshare、pandas 可导入并记录版本。图表由标准库生成 SVG，不依赖 Matplotlib。
• 不主动升级依赖。只有用户明确要求时才升级。
• 先运行确定性测试：

python3 scripts/a_share_turnover_concentration_akshare.py self-test

• 首次建库前对少量股票做接口冒烟测试；默认东财接口失败时，先报告错误，再选择同一 AkShare 内的腾讯或新浪接口，不静默混源：

python3 scripts/a_share_turnover_concentration_akshare.py smoke \
  --provider em \
  --symbols 000001,600000 \
  --start-date 20260101 \
  --end-date 20260131

2. 首次历史建库

默认从 2015-01-01 回溯。AkShare 没有“单次返回某历史日全市场个股成交额”的接口，因此首次运行需要逐证券抓取并写入可续跑 SQLite 缓存；这一步可能较慢。

python3 scripts/a_share_turnover_concentration_akshare.py backfill \
  --start-date 20150101 \
  --provider em \
  --cache-dir /absolute/output/cache \
  --output-dir /absolute/output/report

• em：默认，使用 stock_zh_a_hist；通常每只证券一次区间请求。
• tx：使用 stock_zh_a_hist_tx；长历史按年份请求，首次全市场回溯更重。
• sina：使用 stock_zh_a_daily；脚本强制单线程和节流，避免高频访问。
• 缓存会按每只证券已成功请求的区间寻找前段、内部和尾部缺口；单独存在一条最新快照不会跳过更早历史。
• 若探测阶段大比例失败，熔断并停止，不把部分结果包装成全市场历史。

3. 每日收盘后更新

python3 scripts/a_share_turnover_concentration_akshare.py update \
  --cache-dir /absolute/output/cache \
  --output-dir /absolute/output/report

• 交易日 09:15 至 16:10 默认拒绝写入，避免把盘中成交额当完整日。
• 使用 stock_zh_a_spot 一次获取收盘快照，并用 stock_zh_a_hist_tx 的 000001 成交额和日期作锚点。
• 锚点失败必须写入组件状态，并把当日降为 DEGRADED、返回非零退出码；显式使用 --strict-anchor 时立即停止，不生成降级结果。
• --allow-intraday 只用于诊断；对应日期强制标记 FAIL，不得进入历史分位。

4. 仅从缓存重算

python3 scripts/a_share_turnover_concentration_akshare.py report \
  --cache-dir /absolute/output/cache \
  --output-dir /absolute/output/report

默认要求至少 252 个 PASS 交易日才发布历史分位。除非用户明确接受降级，不使用 --include-degraded。

Fixed Metrics

N[t] = 当日成交额 > 0 的沪深京 A 股数量
k_p[t] = ceil(N[t] × p), p ∈ {1%, 3%, 5%}
集中度_p[t] = 成交额最大的 k_p[t] 只股票成交额之和 / 当日全市场股票成交额
历史分位_p[t] = 历史合格样本中 集中度_p <= 当日集中度_p 的比例

成交额使用原始日成交额，不需要价格复权。禁止把“成交股数前 1%”与“成交额前 1%”混写。

China-Specific Considerations

• 纳入上交所主板、科创板、深交所主板/创业板和北交所 A 股；排除 B 股、ETF、基金、债券和成交额为 0 的证券。
• 沪深历史证券池合并当前上市与已退市证券；任一沪深退市池接口失败时，历史建库必须停止，不能在生存者偏差下发布分位。
• 北交所 2025-10-09 起存量股票全面切换 920 代码；脚本检查 920 代码能否衔接切换前历史。
• AkShare 当前没有独立北交所退市证券池接口，因此北交所退市历史可能遗漏，必须固定披露。
• 股票数量变化由百分比和向上取整处理；不得固定用“前 50 只”冒充前 1%。

Quality Checks

交付前确认：

• [ ] 数据源只使用 AkShare，且每个组件记录接口、状态、行数和错误。
• [ ] 最新日期是已完成交易日；盘中快照未进入历史分位。
• [ ] 证券池包含沪深京，并合并沪深退市证券。
• [ ] 每日按正成交额股票数动态计算 ceil(N×1%/3%/5%)。
• [ ] 全市场分母与排名分子来自同一日期、同一截面。
• [ ] 默认只用 PASS 日期计算历史分位，合格样本不少于 252 日。
• [ ] 空接口响应未计为成功抓取覆盖；盘中 FAIL 和锚点 DEGRADED 在缓存重算后仍保持。
• [ ] 抓取失败、日度覆盖、北交所退市缺口和底层提供方均已披露。
• [ ] 高集中只解释为流动性聚集，不给出确定涨跌或自动交易结论。

Outputs

• a_share_turnover_concentration_YYYYMMDD.md
• a_share_turnover_concentration_YYYYMMDD.json
• a_share_turnover_concentration_history_YYYYMMDD.csv
• a_share_turnover_concentration_top_YYYYMMDD.csv
• a_share_turnover_concentration_YYYYMMDD.svg
• cache/a_share_turnover_concentration.sqlite3