Skip to content

明确 Fins company identity 与 SEC CIK 字段职责 #145

Description

@noho

背景

Issue #139 / PR #144 完成了 CN/HK 财报下载闭环,并让 CN/HK 与 upload 链路更多使用 ticker_to_company_id() 生成 ticker-based company identity,例如:

  • 600519 -> 600519_SSE
  • 0700 -> 0700_HKEX
  • AAPL -> AAPL_US

但 SEC 既有下载链路长期把 SEC CIK 作为 company_id 写入 company/source meta,例如 AAPL -> 3201930000320193。这与 upload 链路中 ticker_to_company_id() 的行为存在语义分裂。

当前现象

  • SEC upload / 通用 upload company meta:使用 ticker_to_company_id(normalize_ticker(ticker)),例如 AAPL_US
  • SEC download company meta:仍使用 CIK 作为 company_id
  • SEC download filing source meta:仍使用 CIK 作为 company_id
  • CN/HK download:使用 ticker-based company identity。

风险

同一个 US ticker 在 upload 和 download 两条路径下可能写出不同 company_id,未来如果按 company identity 做检索、去重、权限、审计或跨市场主体折叠,可能出现不一致。

为什么本次不直接修

SEC 历史数据和既有语义已经把 company_id 与 CIK 深度绑定。贸然把 SEC download 改成 ticker-based company_id 会引入 schema/migration 风险,也可能破坏依赖 CIK 的现有逻辑。

因此本 issue 先作为 identity model 设计追踪,不作为 #139 的阻塞补丁处理。

建议设计方向

需要单独明确以下字段职责:

  • company_id:是否应表示 Dayu 内部统一公司主体 ID。
  • source_company_id:是否应表示主源侧公司 ID,例如 SEC CIK、CNINFO orgId、HKEX stockId。
  • cik / cik10:SEC 专属溯源字段,应从统一 identity 中拆出。
  • ticker_to_company_id():是否只是临时 fallback identity,还是稳定内部 company ID 真源。

验收建议

  • SEC upload 与 SEC download 对同一 ticker 的 identity 语义一致,或文档明确说明二者不同字段的职责。
  • source meta 中 SEC CIK 有独立字段承载,不依赖 company_id 的隐含语义。
  • 如涉及已落盘 meta 语义变更,必须提供 workspace_migrations,并通过 dayu-cli init 进入旧工作区升级流程。
  • README 同步说明 identity 字段职责。

Refs #139
Follow-up to #144

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions