智能投研 REST 服务 · 已上线

离线可测、依赖注入的 Python 投研服务。每层都能注入假实现（FakeProvider / StubLLMClient），故沙箱无网络、无密钥也能跑全部 648 测试。改代码务必守以下不变量：

• 数字来自工具，叙事由 LLM。系统提示锁死「不复述或改动数字、不给买卖指令」，有测试守「LLM 改不动数字」。
• 凭证只在 provider / 网关层。agent 与 tools 层永远看不到 API key。
• 缺数显式标注不编。取不到就优雅降级、在 source_notes 里说明，绝不填占位数字。
• 依赖注入 + 离线可测。新增能力必须能注入假实现、进 648 测试。
• 强制免责声明。每份报告尾部固定声明；免费数据源受其 ToS 约束，商业化前须授权。

浏览器(oaf.world) ──HTTPS + CORS──▶ api.oaf.world
                                      │  阿里云海外 ECS(Alibaba Cloud Linux 3) · Docker
   ┌──────────────────────────────────┴─────────────────────────────┐
   │ Caddy 容器 (80/443, 自动 Let's Encrypt 证书, 反向代理)        │
   │        └──▶ api 容器 (仅内网 expose 8000 · FastAPI/uvicorn)      │
   └──────────────────────────────────────────────────────────────────┘
        api ──▶ 数据源(yfinance · edgartools · baostock)
        api ──▶ LLM 网关(AsiaInfo AIGW ──▶ Claude Opus 4.8)

公网只暴露 Caddy；api 只在 compose 内网。当前线上：开放 API（无 Bearer）+ CORS 收窄到 https://oaf.world + 每 IP 限流兜底。部署包在 deploy/（compose · Caddyfile · .env 不入库 · aliyun-ecs.md）。

⚠️ 海外 ECS 上 A 股财报/报价主源用 baostock：tushare 财务接口需 2000 积分、akshare 抓的境内站从海外 IP 不可达，唯 baostock 免费且海外可达。营收/净利/毛利/经营现金流/总股本可取（够 DCF），总资产/权益 baostock 只给比率故留空；字段口径见 baostock_provider.py。

⚠️ 港股（yfinance）已知口径注脚：报价为 HKD、财报为 RMB（公司以人民币披露），DCF 用 RMB 营收对比 HKD 现价约 8% 汇率偏差；财报固定取最近一期年报，period 标签与实际财年可能差一年。均为不阻塞的可选增强。

⚠️ edgartools 跨版本 API 漂移大：升级后先跑 deploy/aliyun-ecs.md 的 /research 冒烟；字段映射在 edgartools_provider.py::_default_loader。

都在 deploy/.env（不入库）。下表为线上关键项：

客户端对 Opus 4.8 / Sonnet 5 / Fable 5 自动不传 temperature（这些模型拒绝采样参数）。直连 Anthropic 则用 ANTHROPIC_API_KEY + IR_LLM_MODEL=anthropic/claude-haiku-4-5，网关项留空。

# 更新代码重部署
git -C ~/InvesResearch pull origin main
docker compose -f docker-compose.prod.yml up -d --build

# 日志 / 健康 / 指标 / 冒烟
docker compose -f docker-compose.prod.yml logs -f api
curl https://api.oaf.world/health
curl -s https://api.oaf.world/metrics | grep -v '^#'      # ir_http_requests_total 等
curl -s "https://api.oaf.world/quote?uid=US:AAPL"

• 证书：Caddy 自动续期，存 caddy_data 命名卷 —— 重建别删卷。
• 限流：超额返回 429 + Retry-After；/health·/metrics 豁免；IP 取 X-Forwarded-For 首段。
• 成本护栏：Opus 4.8 叙事约 700 字/次，/research·/dcf·/compare 已限 10/min/IP；想更省把 IR_LLM_MODEL 降到 Haiku 4.5。
• /metrics 访问控制：设 IR_METRICS_TOKEN 后 /metrics 要求 ?token=（否则 401）；Prometheus 抓取用 params: {token: [...]}。留空则公开（向后兼容）。
• 健康告警：scripts/healthcheck.py 挂 cron 探 /health，状态翻转（挂/恢复）才推飞书（不刷屏）。仅需标准库；配 IR_ALERT_FEISHU_WEBHOOK 启用。
  * * * * * IR_HEALTH_URL=https://api.oaf.world/health IR_ALERT_FEISHU_WEBHOOK=… python3 ~/InvesResearch/web-backend/scripts/healthcheck.py
• 每日研报：scripts/daily_digest.py 挂 cron 每日调一次，读 IR_DIGEST_UIDS → 复用 /compare（估值 + LLM 研判）→ 推飞书。后端仍无状态（清单来自配置、调度靠 cron、复用已部署服务，不加 DB/端点）。
  0 9 * * * IR_DIGEST_UIDS=SH:600519,HK:00700,US:NVDA IR_DIGEST_FEISHU_WEBHOOK=… python3 ~/InvesResearch/web-backend/scripts/daily_digest.py