ETF罗盘

面向 A股、港股、美股与商品期货的研究/交易决策仪表盘：实时行情、滚动多空信号、ETF 轮动、宏观约束、历史验证与研究审计。前端 Astro，生产环境 Cloudflare Pages + Functions + D1。

在线访问：https://etf.peekabo.cc/

快速入口： A股罗盘 · 滚动罗盘 · 低筹码股 · 期货滚动 · 美股罗盘 · 期货罗盘 · 宏观数据 · 金银持仓

本项目提供研究与教育信息，不构成投资建议。影子模型仅用于研究和审计，不改变正式动作、权重、关键位或模拟执行规则。

• /a-compass/：A 股 ETF 罗盘与正式动作摘要（08:30 / 11:30 / 14:30 / 22:00 四窗）
• /a-momentum/：A 股 ETF 动量与全池
• /a-macro/：A 股中观与风险约束
• /us-compass/、/us-momentum/、/us-macro/：美股 ETF 对应页面

二级固定顺序：A股 → 期货 → 港股 → 美股

• /rolling/：A 股滚动多空能量传导
• /rolling/futures/：期货/现货滚动（当前白银现货 SI=F / hf_XAG）
• /rolling/hk/、/rolling/us/：港股 / 美股滚动
• /rolling/low-chip/：低筹码股内部模型观察列表（横条双行）
• /rolling/low-chip/tracking/：低筹码 10 日追踪（收盘历史 + 30 秒盘中批量行情、临时明细与实时统计）
• /rolling/insights/：滚动详细解读（盘后日更）

• /futures-compass/：期货看板与简报（akshare 数据源，显示名与数据源名可不同：铜/铝/猪肉 → 沪铜/沪铝/生猪）
• /futures-compass/jin10/：宏观数据（金十日历；原 /calendar/ 301 到此）
• /futures-compass/holdings/：金银 ETF 日频持仓（含 change=0 日）
• 同页库存/利率：/data/precious-inventory.json（SHFE / LBMA / CME / TIPS 实际利率 / 隐含租赁利率）
• 隐含租赁利率在线接口：GET /api/public/v1/implied-lease-rate（COMEX 期货 + 美债自算，edge 缓存 10 分钟；前端优先 API，失败回退静态 JSON）

• /login/：管理员、VIP账号与订阅密码统一登录

• /register/?code=...：限时邀请码自助注册永久VIP账号；邀请码仅存哈希，名额通过D1原子批处理控制

• /account/：会员身份、有效期、设备名额与密码管理

• /admin/：管理员授权账号管理

• /lab/：只读研究与影子模型

• /research-framework/：研究框架与证据层

• 实时在线人数：全站页头通过服务端签名匿名身份与 D1 心跳展示最近 2 分钟的活跃浏览器数；同源新身份限流抑制刷量。
• 多市场决策罗盘：A股 / 港股 / 美股 / 商品期货统一导航与状态呈现。
• 实时行情：Edge Quote（腾讯 → 新浪 → 雪球等降级），批量报价 + 短缓存。
• A 股筹码 V2：滚动卡片展示获利盘、90% 集中度、平均成本和同口径昨日变化；支持不复权 / QFQ / HFQ 与最近 90 日序列。
• 滚动多空信号：
  • TradingView Webhook → D1 日锁（first-write-wins）
  • 信号点股价服务端 1m close 入库，前端不扇出 kline
  • 能量矩阵列按 triggered_at 时间序排列；后出现的多方落在更早空方右侧
  • 多方/空方各最多展示最新 4 个正式窗口
  • 每行右侧提供 TradingView 技术分析；A股/美股/期货使用紧凑组件，港股显示 TradingView 4位代码及4小时/1天/1周抓取评级；港股交易时段每60秒刷新，休市与后台标签页暂停；窄屏整行展开，分页始终只加载当前 3 只
• 金银持仓：金十 ETF 报告代理，attr_id=1|2&all=1 保留 0 变动日；D1 缓存 ≤2 天热读
• 低筹码股：内部模型观察结果 + 日归档历史查询；追踪页保留 10 日研究窗口，交易时段叠加批量实时价格
• 交易时段控制：D1 多市场日历；休市停轮询、连续品种（金银油美元）24H 独立刷新
• 风险与研究隔离：正式动作、影子模型与历史审计边界清晰
• 数据契约与构建门禁：Schema、批次一致性、敏感字段与静态产物校验

Astro 静态页面 (dist/)
  ├─ Cloudflare Pages（主站 etf.peekabo.cc）
  ├─ Pages Functions
  │    quote / kline / market-calendar / presence
  │    rolling-signals（D1 日板 + LKG）
  │    jin10-calendar / jin10-mcp-calendar
  │    jin10-etf-reports
  │    TradingView webhook / auth / invite registration
  ├─ Cloudflare D1 (etf-compass-auth)
  │    rolling_signals · jin10_calendar_items · jin10_etf_holdings
  │    market_calendar · presence_sessions · auth/session · invite_codes
  ├─ Edge Quote：腾讯 → 新浪 → 雪球
  └─ JSON 契约：public/data + public/schemas + catalog

生产以 wrangler pages deploy dist 为准；git push 只更新 GitHub。

TradingView POST /api/v1/tradingview
  → 解析 trigger 分钟价（payload 或 Edge kline?at=）
  → D1 INSERT OR IGNORE
       PK (trade_date, symbol, cycle_code, signal)
  → 当日同节点只锁首次；可选 WxPusher / Telegram

GET /api/public/v1/rolling-signals?symbol=  （单标） / ?symbols=a,b,c  （批量 boards[]）
  → 静态 LKG + 当日 D1 合并
  → storage=d1 表示走了日板

前端：public/js/a-rolling-app.js + ARollingEnergyMatrix.astro
正式多方窗：2h…8h（观察 1.75h/105m）
正式空方窗：15m…240m（观察 10m；240m 展示「停止验证 240m」）

• 页面：/futures-compass/holdings/
• API：GET /api/public/v1/jin10-etf-reports?attr_id=1|2&limit=15
  • attr_id=1 黄金 ETF，attr_id=2 白银 ETF
  • 日频默认；unit=week 为周聚合
  • 上游日频必须带 all=1，否则 change=0 日被过滤
• 缓存：D1 jin10_etf_holdings 优先（行数够且最新 ≤2 天）；否则拉上游并 waitUntil 落库
• 浏览器：public/js/jin10-holdings-app.js（打开即拉，无独立 cron）

• 页面：/futures-compass/jin10/（/calendar/ → 301）
• 直连：GET /api/public/v1/jin10-calendar?date=YYYY-MM-DD
• MCP：GET /api/public/v1/jin10-mcp-calendar（当前自然周 + affect_txt）
• 独立可复用代理：brucelau1987cn/jin10-mcp-proxy

• Edge API：GET /api/public/v1/quote?symbols=600021.SH,hf_XAG,SI=F
• 响应：{ status: "ok", source, count, quotes: { [code]: { price, change_percent, ... } } }
• 客户端适配：src/lib/normalizeQuotePayload.mjs + /js/normalize-quote-payload.js（window.EtfQuote）

python3 scripts/a_share_fundamental_shadow.py --workers 4        # 只读探针/本地审计
python3 scripts/a_share_fundamental_shadow.py --workers 4 --write # 64/64门禁通过后写D1

• 数据源：BaoStock 未复权日线估值字段 + 季报已披露 totalShare；total_mv=close×total_share。
• 覆盖契约：expected/succeeded/empty/failed/coverage/publishable；任何 empty/failed 返回 STAGING BLOCKER，D1保持不变。
• 运行边界：最多4个独立进程；每进程独立持久BaoStock会话，会话失效仅做一次有界重登录。
• 时间边界：首个可靠股本披露日前 total_share/total_mv=null；增量收益率必须携带前一交易日K线。
• 影子观察：第1—9个交易日 IMMATURE，第10—19日 ACCUMULATING，第20日起 OBSERVED；全程 audit_only，正式权重、信号和动作保持不变。

• GET /api/public/v1/market-data/bars、/ths/*、/subscription/status、/jin10-indicator-history 已下线（410 Gone）
• 数据源：A股日/周/月优先 Pages BaoStock；adjustment=none 时 BaoStock 故障可回退 Yahoo；全球及分钟周期使用 Yahoo Finance；source=tradingview 当前明确返回 503 UNAVAILABLE，等待 Cloudflare 边缘 WebSocket 独立探针通过后再接入。
• 周期支持 period=1m|5m|15m|30m|1h|day|week|month。BaoStock 支持 adjustment=none|qfq|hfq；Yahoo 仅支持 adjustment=none。返回统一 items[{timestamp,open,high,low,close,volume}]。
• source=auto|baostock|yahoo|tradingview 可用于确定性诊断；失败返回 503、code=UNAVAILABLE，不静默估算。
• 可见性轮询：/js/etf-live-poll.js（window.EtfLivePoll）
• 源仓：brucelau1987cn/edge-quote-api
  • npm run sync:quote / npm run sync:adapter
• 部署/缓存探针：docs/deploy-cache-probe-contract.md

• Pages 主接口：GET https://etf.peekabo.cc/api/public/v1/chip?symbol=600021&adjust=qfq&limit=90
• Worker 容灾接口：GET https://edge-quote-api.brucelau1987.workers.dev/api/public/v1/chip?symbol=600021&adjust=qfq&limit=90
• 两个入口由 edge-quote-api 的 src/index.js 与 src/chip.js 生成，响应契约保持同构。
• 返回 series、latest、previous、profit_ratio_change_pp，页面“较昨日获利盘”直接使用同算法相邻交易日结果。
• limit 只控制 series 长度；limit=1 仍会返回昨日点和变化值。
• 更新公开滚动数据：python3 scripts/update_a_rolling_chip.py。脚本过滤港股、美股等未支持市场，保留成功标的并在 failures 中记录失败代码。

# 1. 在 edge-quote-api 完成修改和测试
npm test

# 2. 在本仓同步 Pages 路由
npm run sync:quote

# 3. 验证生成模块与 Cloudflare Functions 构建
node --test tests/pages_chip_import.test.mjs
npx wrangler pages functions build functions --outdir /tmp/etf-pages-functions-build

# 4. 刷新滚动筹码数据并构建
python3 scripts/update_a_rolling_chip.py
npm run build

• functions/api/public/v1/quote.js、chip.js、_chip.js、_baostock.js 是同步产物；行情和筹码逻辑统一在 edge-quote-api 修改，再执行 npm run sync:quote。
• 同步脚本需要同时替换 ./chip.js 的 import 与 re-export。遗漏 re-export 会造成 Pages Functions 循环导入并阻断部署。
• 同步后必须保留 SI=F / GC=F / CL=F 别名，并与 kline.js 保持一致。
• 腾讯主源的历史换手率采用当前流通股本近似；腾讯失败后 Cloudflare 直接连接 BaoStock TCP，并使用 BaoStock 每日真实换手率。生产无需本地代理。
• refresh=1 绕过已完成缓存且响应 no-store，相同并发刷新仍会合并在途计算。
• Worker 与 Pages 分别部署。发布后应使用相同 symbol、adjust、limit、refresh 请求比较两个入口。
• Cloudflare Global API Key、API Token、账户邮箱等凭据只存本机凭据文件或 CI Secret，禁止写入仓库、日志和公开 JSON。

多 publisher 共享 worktree：外脏路径会硬拦（korea-tech-factor-shadow.json / us-selector-shadow.json 豁免）。夜间 base_commit 漂移需重跑 prepare。

要求 Node.js 22.12+ 与 Python 3.12（3.11 亦可）。包管理 npm（package-lock.json）。

npm ci
python3 -m pip install -r requirements-ci.txt
npm run dev

npm run test
npm run build
npm run audit
git diff --check

npm run build 门禁顺序：

1. 启动 build Python / 期货快照新鲜度
2. 跨文件批次一致性（A 股 + 美股）
3. 生成浏览器精简看板与公开目录
4. Schema / 目录 / 字段安全
5. Astro 静态构建 + JS 版本注入

页面-only 改动（.astro / CSS / JS，数据 JSON 未变）可：

rm -rf dist && npx astro build
node scripts/inject_public_js_version.mjs dist

# 1) 构建
npm run build   # 或页面-only: npx astro build + inject

# 2) 凭证
set -a; . ~/.hermes/credentials/cloudflare-pages.env; set +a

# 3) 部署（shadow 脏树需 --commit-dirty=true）
npx wrangler pages deploy dist --project-name etf-rotation-blog --commit-dirty=true

# 4) 探针
npm run verify:pages

或：

npm run release:pages
npm run release:dual    # Pages + edge Worker

凭证（本机，不入库）：

• Pages：~/.hermes/credentials/cloudflare-pages.env
• D1/Workers 全局：~/.hermes/credentials/cloudflare-global.env

public/data/          公开 JSON 快照与目录
public/js/            浏览器脚本（行情适配 / 轮询 / 滚动 / 持仓 / 罗盘）
public/schemas/       JSON Schema
functions/            Pages Functions
  api/public/v1/      quote · kline · rolling-signals · jin10-*
  _lib/               D1 helpers
migrations/           D1 迁移（auth / calendar / rolling / jin10 holdings）
scripts/              数据生成、门禁、发布器、Pages 探针
src/pages/            路由
  rolling/            滚动子页（futures / hk / us / low-chip / insights）
  futures-compass/    期货罗盘 / 宏观数据 / 金银持仓
src/components/       布局与看板组件（能量矩阵、摘要条等）
src/content/blog/     A 股日更与研究文章
tests/                Python + Node 回归
docs/                 契约与运维文档

• 正式输出、影子研究、历史记录、运行快照角色分离。
• null / 缺数 不等于零；未知必须披露。
• 页面数据先生成、再编目、再校验；失败时构建关闭。
• 公开契约不发布凭据、私有路径或内部实现细节。

• docs/data-contracts.md — 公开数据契约
• docs/deploy-cache-probe-contract.md — 部署与缓存探针
• docs/investment-research-layer.md — 研究层与写入边界
• docs/nightly-github-trigger.md — 夜间 GH 触发