# Public API changelog

## Unreleased

- `/v1/catalog/snapshot` 新增可选的 PostgreSQL runtime 可见性策略：空策略保持全量；
  配置 `batx-production.catalog.dataset_visibility` 后，仅公开 `enabled=true` 的
  dataset，并裁剪无数据集 category 与未映射 relation。默认接口行为保持兼容。

- **Breaking:** feed.batx.ai 定位为纯 WebSocket 订阅转发，不再承载任何
  `/api/workspace/*` 行情与基本面 REST 拉取端点（`quotes`、`klines_meta`、`ohlcv`、
  `ohlcv_batch`、`fundamentals`、`company_profile`、`market_cap`、`financial_catalog`、
  `financial_records/*`、`infoway_financials`、`refinitiv_financials` 已全部下线，
  请求返回 404）。历史数据请使用 BATX NAS/SQL 产品；WebSocket 订阅
  （`/ws`、`/api/cell/v2/ws`、`batx-market-feed/v1`）与 `/api/cell/v2/*` 查询面保持不变。
  SQL Catalog `/v1/catalog/*` 由 datagateway 提供，BATX 不再通过 Python Feed 访问目录。
- 新增并固化 SQL Catalog 的 `/v1/catalog/sources` 和 `/v1/catalog/search`，与
  `/snapshot`、`/categories`、`/describe`、`/health` 共用一个有界目录 generation。
- Kline WebSocket 订阅不再回填历史：`/ws` kline 订阅不再预载最近 K 线，
  `/api/cell/v2/ws` kline 订阅的 `snapshot` 参数仍被接受但固定返回空 `rows` 的
  snapshot 帧（帧结构不变）。K 线自订阅起由实时成交增量生成；历史读取请使用
  NAS/SQL 产品。

- 加法式提供需现有 Feed API key 的 `GET /v1/symbols?profile=batx-symbol-catalog/v1`：
  从当前 Feed Universe 输出 revision-bound BATX canonical 标的目录，包含既有 Binance
  crypto 与指数 alias、名称/关键词/时区等已核验 enrichment。响应不使用 Workspace
  envelope；默认 `/v1/symbols` 的 provider-level 分页、字段和 limit 契约保持不变。

- 修复报价已有历史记录时跳过最新日线核验，造成实时价搭配旧昨收/错误涨幅的问题；
  无法核验源数据时沿用单标的 `MARKET_DATA_UNAVAILABLE`，请求字段、认证及既有 key
  权限保持不变。日桶在交易所收盘后可参与报价计算，不改变 OHLCV 的 `forming`。

- 新增美股电话会议数据集 `alt.events.us_earnings_calls` 与
  `alt.events.us_earnings_call_transcripts`（事件 + 句级转录，经 `call_id` 关联），
  可通过 WS `dataset` channel 订阅版本推送、`/api/cell/v2/llm|analytics/query` SQL
  查询与 DuckDB 直读 Parquet 访问；schema 与三通道用法见新公开文档
  [earnings-calls.md](earnings-calls.md)。当前源 rights 为 internal-research。
- 新浪 7x24 快讯的 `news.articles.url` 现在使用上游逐条文章链接（`docurl` / `ext.docurl`）；无文章链接时为空，不再返回栏目首页作为来源。

- 修复 `POST /api/workspace/quotes` 首次查询冷标的时，日 K 已成功回填却可能返回
  `NO_DATA` 的问题；报价现在会在同一次请求中使用已返回的完成日 K，接口字段、鉴权及
  单标的错误格式保持不变。
- 修复 Cell source 模式下全新 Feed runtime 的批量行情投影：已连接 Cell 的已知 symbol
  不再因 Feed 本地 reference/cache 为空而被 `/api/workspace/quotes` 误报为 `NOT_FOUND`；
  quotes 从 owning Cell 最近日线计算昨收，`klines_meta` 从 owning Cell 持久化 coverage
  返回周期与范围，并让 Infoway crypto meta/Kline 保持既有 `Asia/Shanghai` 时区约定。
  请求、响应字段、认证、既有 API key 和错误格式保持不变。
- **Breaking:** Feed OHLCV 的 `d` 统一为 provider 原始 epoch-ms；Kline WebSocket 同样发送
  `d`、`ts` 和 `trading_day`。旧 `time` / `trading_date` 字段继续作为兼容别名保留。
- Dataset discovery 与 typed/LLM query 加法式提供 `bjt06-cn-market.bars`，包含大陆侧
  A 股 `1d`、`1h`、`5m` K 线 Published 版本；时间仍为 epoch milliseconds 并附
  `Asia/Shanghai`，既有 Feed API key 默认可读，现有行情接口与 Infoway source 不变。

- **Breaking:** Workspace OHLCV 切换到 `raw-source-d-v1`：`rows[].d` 由 legacy 日期字符串
  改为 provider 原始 epoch-ms 整数；`rows[].ts` 改为交易所当地墙上时间的无时区轴游标，
  日线取 `trading_day` 的 UTC 零点；全市场必发 `trading_day`，并显式返回 IANA
  `timezone`。旧 `time` / `trading_date` 字段保留，分别与 `d` / `trading_day`
  同源派生；crypto 固定按 `Asia/Shanghai`。
- `raw-source-d-v1` 的日线分页/增量/日期窗口会在 provider 原始轴扩大读取范围后，按
  规范化的当地 `ts/trading_day` 严格过滤，并优先采用上游显式交易日，避免 UTC 日期
  错位导致接缝漏行或越界。

- 加法式新增 BATX canonical market protocol v1：认证服务可用精确 typed body 换取短期、
  单次、audience/opaque-subject 绑定的 ticket，并连接 `/api/cell/v2/market/ws` 使用
  canonical subscribe、ACK 与 frame 一致的服务端 provider mapping、mapping 隔离的
  sequence/history epoch、snapshot、ordered event/status、gap 和 replay。空、畸形及其他
  legacy body 仍被忽略并返回原 ticket 结构；既有 `/ws`
  和 `/api/cell/v2/ws` 契约不变。
- 新增需现有 Feed API key 的 `GET /api/data-health`，按逻辑数据分区返回连接状态、Dataset
  coverage、range、持久化待完成/累计完成进度、pull source 状态和 Published projection
  进度；所有 instant 使用 epoch milliseconds，并提供 RFC 3339 与 IANA timezone。
  未连接或状态 RPC 不可用时未知持久化计数为 `null`。既有 `/healthz`、`/api/status`
  和 API key 行为不变。
- `news.articles` 历史覆盖现可纳入既有五源快讯档案；公开 news query、Dataset query 与
  range discovery 可访问回填后的更早数据，现有请求和响应契约不变。
- Dataset discovery 与 LLM/typed query 加法式提供 `social.posts` 和
  `fund.valuation`；`news.articles` 增加交易所披露与监管公告 provider。所有时间仍为
  epoch milliseconds 并附 IANA timezone，既有 API key 默认可读，现有接口与字段不变。
- 新增 `POST /api/cell/v2/news/query`，按 epoch-ms 半开时间窗和可选 instrument
  过滤、以 cursor 分页读取 `news.articles`；响应提供 RFC 3339 instant、IANA timezone、
  gap/partial 状态和 trace ID。东方财富、同花顺、富途、新浪、金十的规范化快讯也可通过
  现有 `/api/cell/v2/ws` news channel 实时订阅，并通过 LLM query 固定版本批量读取；
  所有已签发 API key 默认可用。
- Cell V2 WebSocket 加法式新增 `dataset` channel，可按 `datasets` 过滤 immutable
  Dataset 新版本通知；通知仅携带 discovery 元数据，不推送整批行。现有 API key
  默认可用，Kline、market、news frame 和订阅行为保持不变。
- Feed discovery 与 LLM/typed query 现已提供 `market.prices`、`market.flows`、
  `market.options.chain`、`macro.series`、`fund.quarterly`、`fund.ownership`、
  `alt.events.foodborne_outbreaks` 七个 batch Dataset；所有既有 API key 默认可读。
  仅有内部研究授权或尚无实际 publisher 的类别不会出现在公开 discovery。
- Cell V2 Dataset discovery 不再广告已被 Source current-only retention 删除的旧版本；
  endpoint、字段和 current 查询方式不变，手工保留的 Published 版本继续正常发现。
- Workspace OHLCV 不再因 Source Cell 正常重启而等待全量标的目录刷新；Feed 可依据 Cell
  声明的市场范围立即恢复请求路由，降低目录同步期间的 502 和 readiness 中断。接口、
  参数、响应字段、鉴权及缓存语义保持不变。
- Workspace OHLCV 最近窗现在直接返回 Infoway 请求周期的原生 K 线，不再用更细周期
  或实时报价重算 OHLCV；既有 endpoint、参数、响应字段、鉴权和历史游标保持兼容。
- Workspace OHLCV 的 Cell 本地缓存查询/回填不再等待后台 Published Dataset 版本构建，
  减少高并发首次 K 线请求的额外延迟；响应字段、缓存语义和鉴权保持不变。
- BATX 批量报价的 `name` 现在在实时 metadata 与 reference catalog 之间全局按
  `display_chinese_name → display_name → name` 选择，避免 provider 英文原始名
  覆盖已校验中文名；`/api/universe` 的三个名称字段仍保持原有独立语义。
- Cell V2 typed analytics 的 Dataset binding 加法式支持可选 `scan.filters`。当前字符串
  `eq` 可让 Cell 在执行 SQL 前安全缩小 immutable Published Parquet 文件集合；响应
  `stats` 新增准备耗时和索引选取统计。未声明 `scan`、索引不可用或 footer 证据不足时
  保持完整扫描，既有请求和查询结果不变。
- Cell V2 在 Cell/Feed 重连和大量 Published version 场景下改进目录恢复与请求调度，
  避免历史目录同步或慢 history RPC 阻塞实时订阅、LLM catalog、heartbeat 和
  readiness，并修正订阅确认与可用状态同时到达时的状态顺序；公开 discovery 返回
  Cell 当前仍保留的全部版本，既有字段、认证和版本固定查询语义不变。
- LLM query 的 `data_version` / `data_versions` 现在接受文档中的 `current` 别名；执行时
  固定为 Cell 本地当前 Published version，响应返回实际版本，查询过程不拉取远程数据。
- BATX Workspace 现在接受 `BTC_USDT_BINANCE` 等
  `<BASE>_<QUOTE>_BINANCE` crypto symbol，并通过 reference catalog 映射到现有
  Infoway crypto canonical；OHLCV、K 线元数据和批量报价无需调用方改名。
- 新增 `GET /api/workspace/company_profile`，返回完整 provider 公司资料，并提供
  可空的顶层 `logo_url` / `icon_url`。
- `GET /api/workspace/financial_records/company` 支持读取完整公司资料原始记录。
- `/api/workspace/fundamentals`、`/api/workspace/infoway_financials` 和
  `/api/workspace/refinitiv_financials` 加法式增加可空的 `logo_url` / `icon_url`。
- Cell V2 公开 REST 与 WebSocket 统一使用 `/api/cell/v2/` 前缀。
- Swagger、OpenAPI、Postman 和 Markdown 公开文档只展示外部接口契约；旧文档 URL
  保持可访问。

以上新增能力默认对所有现有 Feed API key 开放，不需要换 key 或 opt in。既有接口、
字段、认证、错误格式和状态码不变。