企业官网建设流程全解析

PRISM-INSIGHT 是一套 AI 驱动的韩美双市场股票分析与自动交易系统，本文解析它的核心工程设计：韩国市场由 KIS（韩国投资证券）Open API 统一供数，美国市场则以兼容 yfinance 调用语义的 KIS 海外行情适配器为核心，两个市场共用同一套MarketDataSource协议与SourceChain适配器链，让"换供应商"退化为"加一个类"这么简单。

一、为什么双市场需要统一数据层 🎯

一套系统同时跑韩国与美股，两边的"取数需求"并不相同：

• 韩国：机构/外国人/个人三类投资者的资金流（수급）只有交易所或券商渠道才发布，第三方爬虫拿不到；
• 美国：团队长期习惯 yfinance 的history()/download()调用方式与列结构；
• 共用的能力：日线 OHLCV、指数历史、基本面、新闻标题等。

PRISM-INSIGHT 的解法是：按"报告真正要什么"定义端口（protocol），而不是按某一家供应商的 API 形状来定义。每个供应商写一个 Adapter 即可，新增券商只需"写一个类"，而不是去改遍所有调用点。

统一契约定义在 cores/market_data/source.py 中。

二、韩国市场：KIS 单一数据源适配器

韩国侧的适配器是 cores/market_data/kis_source.py 中的KisSource，它有几个值得学习的工程细节：

1. 分窗回溯，而不是信任单次调用

KIS 日线接口单次返回行数有上限——请求一整年会静默截断。因此KisSource把时间范围拆成窗口、从新到旧逐页回溯（最多_MAX_WINDOWS = 40个窗口），直到覆盖起始日期为止，避免"图表悄悄少画了半年"。

2. 限流重试与指数代码纠偏

• 命中限流码EGW00201时按 0.5s / 1.0s 阶梯退避重试（配额按秒重置，短等待即可恢复）；
• KRX 与 KIS 的指数代码会静默冲突（两边都用1001，但指向不同指数），源码中内置了1001→0001（KOSPI）、2001→1001（KOSDAQ）的映射，避免"拿到一个看起来合理、其实是另一个指数的数字"。

3. 复用交易客户端，而非自行鉴权

KIS 每个 app key 只发一个 token，且鉴权状态是全局的。KisSource直接借用已认证的DomesticStockTrading(auto_trading=False)客户端，避免第二条鉴权路径与实盘交易循环互相抢占 token——它只取数，不下单。

4. KIS-only：退役供应商无法复活

韩国市场已迁移到 KIS 单一供应商（背景见 docs/KIS_ONLY_MIGRATION_20260911.md）。cores/market_data/init.py 中default_chain()只构建KisSource：即使残留的PRISM_MARKET_DATA_SOURCES环境变量写着旧供应商，也只会被忽略并记录警告，从机制上杜绝"旧配置偷偷复活"。

5. 远程部署形态：SSH 隧道只读代理

当行情服务需要跑在与交易主机不同的机器上时，cores/market_data/remote_source.py 中的RemoteKisSource通过本地回环 + SSH 隧道访问远端/market-data端点，带 API Key 鉴权、2MB 载荷上限与 1200 行结果限制——KIS 仍是唯一数据提供方，本地不持有额外凭据。

三、美国市场：以 yfinance 语义接入 KIS 海外行情

美国侧的核心是 prism_core/us_market_data.py，它解决了一个现实问题：yfinance 抓取 Yahoo 数据没有许可证，不能支撑商业化服务。方案是改从 KIS 海外行情取价，同时对外保持 yfinance 的调用习惯：

• history()是 yfinanceTicker(symbol).history(...)的 drop-in 替代：相同的列（Open/High/Low/Close/Volume）、相同的auto_adjust语义、America/New_York午夜索引、end排他；
• INDEX_CODES把 yfinance 指数代码映射到 KIS（^GSPC→SPX、^VIX→VIX、^TNX→Y0202），没有对应代码的指数（如^RUT）直接报"不可用"，绝不拿相近指数顶替；
• yfinance_basis()用 KIS 的原始价（MODP=0）与复权价（MODP=1）还原出 yfinance 的口径：split 已调整、股息未调整，并输出 yfinance 约定的Stock Splits列——2026-10-23 与 yfinance 1.4.1 实测对齐；
• 缺失保持缺失：空字段是 NaN 而不是 0，请求失败抛出UsMarketDataUnavailable，而不是返回空表。

供应商同样由环境变量编排

PRISM_US_MARKET_DATA_SOURCES决定美国侧的适配器顺序，默认kis，例如kis,yfinance表示 KIS 优先、yfinance 兜底（yfinance 仅限 opt-in，无许可）。注册表_SOURCES里只有两行映射：接入新供应商 = 写一个带daily_history和current_quote的类 + 在_SOURCES里加一个条目，调用方零改动。

已收盘会话的数据还会写入保守缓存 prism_core/us_daily_cache.py：缓存条目携带完整的价格口径元数据（provider、auto_adjust、interval、币种），并且"新鲜的实时响应永远优先于缓存"。

四、统一契约：MarketDataSource 与 SourceChain

SourceChain是整套设计的灵魂，规则很简洁：

1. 按顺序逐个询问每个 source；
2. 抛出Unsupported（"该供应商天生没有此能力"）→ 跳过，不记错误日志；
3. 抛出Unavailable（限流、超时、鉴权失败、空结果）→ 跳过并记 warning；
4. 任何一个 source 成功即返回，若是非首选 source 还额外打一条[FALLBACK]日志；
5. 全部失败才抛出携带每次尝试原因的Unavailable。

关键设计决策是禁止用"返回空表"来表达能力缺失——注释里写得很直白：正是"空表"曾让一次两小时的数据源故障看起来像"这些股票就是没有数据"。

五、关键文件索引

六、总结 ✅

PRISM-INSIGHT 的数据层给出了一个可复用的范式：协议按需求定义、供应商按适配器接入、失败语义显式区分（Unsupported vs Unavailable）、退役供应商在机制上不可复活。韩国侧 KIS 独占、美国侧 KIS 主供 + yfinance 语义兼容，两个市场共用同一条SourceChain逻辑——这就是"双市场统一工程设计"的全部含义：不是把两个市场的数据硬凑到一起，而是让同一套契约同时容纳它们。