fix(HEL-490): 真实装配接通中枢并收编估值晚间复核

把 query/行情钩子绑到内层 TushareClient，图表接受不完整日K窗口；收编现网 HEL-423 未提交的估值复核，避免换版丢掉。

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: multica-agent <github@multica.ai>

.env.example

@@ -5,6 +5,13 @@ APP_ENCRYPTION_KEY=
 # the system settings; all accounts use the same backend market snapshot.
 TUSHARE_TOKEN=your_tushare_token_here
 
+# Official xiaobai-datahub client. Read flags default on in config/datahub.config.json.
+# compose.yaml pins every DATAHUB_READ_* to 1 so leftover .env zeros cannot keep
+# official pages on the old APIs. Old website APIs are emergency fallback only.
+# DATAHUB_SHADOW_* can still override a single dataset.
+DATAHUB_BASE_URL=http://127.0.0.1:8766
+DATAHUB_TOKEN=
+
 # Optional iFinD HTTP credential. The backend exchanges it for a short-lived
 # access token and never exposes either token to browsers.
 IFIND_REFRESH_TOKEN=your_ifind_refresh_token_here

.gitignore

@@ -8,6 +8,9 @@ data/*.db
 data/*.db-shm
 data/*.db-wal
 data/backups/
+datahub-data/
+xiaobai-datahub/data/
+xiaobai-datahub/.venv/
 data/*.bak
 data/*.backup
 *.log

ARCHITECTURE.md

@@ -54,7 +54,9 @@ background scheduler
   feature repository mixins; do not add feature queries to it.
 - `backend/jobs/` owns job definitions, locks, retries, idempotency, and persisted run state.
   `backend/jobs/service.py` is the application-facing owner of scheduler start/stop, manual
-  refresh submission, and periodic refresh coordination.
+  refresh submission, and periodic refresh coordination. `backend/jobs/refresh.py` owns
+  whether a dashboard payload is a usable refresh result versus a failed job, and whether
+  after-hours official catch-up is due.
 - `backend/llm/` owns model selection, membership/quota checks, fallback, provider transport,
   streaming rules, and call audit. Feature agents only prepare messages and interpret
   feature-specific results.

DOCKER_DEPLOY.md

@@ -165,88 +165,58 @@ docker compose restart xiaobai-review
 docker compose down
 ```
 
-### 镜像构建的唯一安全入口（2026-08 HEL-235 起）
+### 服务器本地目录更新与构建（日常推荐）
 
-生产机 `192.168.200.11` 上的 `/opt/1panel/docker/compose/xiaobaifupan` 只是历史文件树：
+生产机 `192.168.200.11` 的 `/opt/1panel/docker/compose/xiaobaifupan` 自 2026-08-29（HEL-235B）
-不是 Git 仓库、内容停在旧提交、与线上镜像不一致，且其 `compose.yaml` 会把构建结果打进
+起已是受 Git 管理的工作目录，只跟踪 Gitea `main`（仓库
-`xiaobai-review:latest`。**禁止在该目录（或任何服务器工作树）里 `docker build` /
+`http://192.168.200.36:3200/leefer/xiaobai-review.git`）。由于目录顶层归 root，
-`docker compose build`**，否则会把已上线功能悄悄打回旧版。
+`.git` 存放在部署账号家目录（外部 Git 目录方案）：
-
-唯一安全构建方式是在有仓库检出、能免密 SSH 到部署机的机器上运行：
-
-```bash
-tools/build_image.sh <提交号> <镜像tag>
-# 示例：tools/build_image.sh cefc86917d89 verify-hel235-cefc869
-```
-
-该脚本的行为约束：
-
-- 先 `git fetch`，再把提交号解析为完整 SHA，解析失败立即中止，绝不使用本地脏状态或服务器旧目录；
-- 构建前读取当前线上容器镜像的 `org.opencontainers.image.revision`，用 Git 祖先关系确认候选提交包含线上全部历史；落后 `main`、旁支或错误提交会直接退出，并打印线上提交、候选提交、文件差异和将丢失的提交；
-- 镜像 tag 必须以 `-<提交短号7位>` 结尾（如 `hel234-cefc869`），禁止 `latest`、`rollback-*`；
-- 通过 `git archive <提交> | ssh 部署机 docker build -` 流式构建，服务器上不存在构建用工作树；
-- 构建后回读镜像 label 里的 `org.opencontainers.image.revision`，与预期提交不一致则删除镜像并中止；
-- 每次构建在部署机 `~/xiaobai-build/BUILD_LOG.tsv` 留痕，可追溯每个镜像的来源提交。
-
-构建只产出镜像，不启动、不替换任何容器；换版用新 tag 起新容器，回滚用既有镜像 tag 重跑。
-
-### 使用 Gitea 更新程序（旧方式，生产机禁用）
-
-代码仓库为：
 
 ```text
-http://192.168.200.36:3200/leefer/xiaobaifupan.git
+~/xiaobai-build/repos/xiaobai-review.git          Git 元数据（分支/历史/索引）
+/opt/1panel/docker/compose/xiaobaifupan           工作目录（程序文件本体）
+~/xiaobai-build/update-from-main.sh               一键更新+构建入口
+~/xiaobai-git                                    便捷查看（status/log/diff）
 ```
 
-首次在服务器部署代码时，可以直接克隆到目标目录：
+日常更新只需要在服务器上执行一条命令：
 
 ```bash
-sudo mkdir -p /opt/xiaobai-review
+~/xiaobai-build/update-from-main.sh            # 更新到 main 并构建 main-<短号> 镜像
-sudo chown "$USER":"$USER" /opt/xiaobai-review
+~/xiaobai-build/update-from-main.sh verify-tag main-a8732f5   # 部署前复核镜像与 main 一致
-git clone http://192.168.200.36:3200/leefer/xiaobaifupan.git /opt/xiaobai-review
-cd /opt/xiaobai-review
 ```
 
-私有仓库会提示输入 Gitea 用户名和密码或访问令牌。不要把密码写入仓库 URL、
+脚本在构建前强制完成五道校验，任一不符立即停止、不产出镜像：
-`compose.yaml` 或脚本。然后把原 `.env` 与 `data/` 放回该目录；这两项已被 Git
-忽略，后续拉取代码不会覆盖数据库与密钥。
 
-如需部署管理员私有问师，通过 NAS 文件管理器将本地
+1. `git fetch` 成功（连不上 Gitea 即停）；
-`data/private-mentor-skills/` 复制到服务器项目的同名 `data` 目录，并保持目录仅由
+2. 必须在 `main` 分支（智能体不得用功能分支直接当正式线）；
-部署账号和容器运行用户读取。该内容不会通过 Gitea 同步。
+3. 工作区无未提交改动、无多余文件；
+4. 只允许快进合并到 `origin/main`（分叉即停）；main 新增/删除顶层文件时会给出
+   需管理员执行的精确清单（目录顶层归 root）；
+5. 构建后回读镜像 `org.opencontainers.image.revision`，与 `main` 提交不一致则删除镜像。
 
-每次更新前先创建 SQLite 一致性备份，再拉取并重建容器（注意：`docker compose up -d --build`
+镜像 tag 固定为 `main-<提交短号7位>`（不带提交号的模糊 tag 一律禁止）；每次构建在
-从服务器本地工作树构建，仅适用于来源可信的全新环境；生产机 `192.168.200.11` 禁用，
+`~/xiaobai-build/BUILD_LOG.tsv` 留痕。构建只产出镜像，不启动、不替换容器；换版与
-请用 `tools/build_image.sh` 构建后换容器）：
+回滚步骤见 `~/xiaobai-build/README.md`。
 
-```bash
+`compose.yaml` 的镜像名与 revision 标签同样做了强校验：直接 `docker compose up -d --build`
-cd /opt/xiaobai-review
+会因缺少 `XIAOBAI_GIT_REV` / `XIAOBAI_GIT_SHORT` 变量而拒绝执行，避免再出现构建进
-docker compose exec -T xiaobai-review python -c "import sqlite3; s=sqlite3.connect('/app/data/review.db'); d=sqlite3.connect('/app/data/review-before-update.db'); s.backup(d); d.close(); s.close()"
+`latest` 的模糊版本。需要用 compose 时先 `export` 这两个变量（值以
-git pull --ff-only origin main
+`~/xiaobai-build/xiaobai-git rev-parse HEAD` 为准），或直接用上面的脚本。
-docker compose up -d --build
-docker compose ps
-curl --fail http://127.0.0.1:8765/api/health
-```
 
-`docker compose up -d --build` 会原地替换应用容器，不删除宿主机的 `data` 目录。
+### 智能体高级入口：Git 归档流式构建
-数据库迁移会在新容器启动时自动执行。若 `git pull --ff-only` 提示本地代码有修改，
-先用 `git status` 查明原因，不要用强制重置覆盖 `.env` 或 `data`。
 
-### 不使用 Git 时更新（生产机禁用）
+有仓库检出、能免密 SSH 到部署机的智能体可以用 `tools/build_image.sh <提交号> <镜像tag>`
+从任意明确提交流式构建（`git archive | ssh docker build`），tag 同样必须以
+`-<提交短号7位>` 结尾，构建后回读 revision 校验并留痕。用于在服务器不便拉取时的
+应急构建；日常正式线仍应走 `main`。
 
-`docker compose build` 会从服务器本地目录构建，来源提交不可追溯。生产机
+### 历史方式（已废弃）
-`192.168.200.11` 上禁止使用本节方式，一律改用上一节的 `tools/build_image.sh`。
 
-重新上传代码后执行：
+早期文档建议在服务器重新 `git clone` 一份或手工上传代码后 `docker compose up --build`。
-
+这两条路径已废弃：服务器上**只允许存在一个受管工作目录**（上述
-```bash
+`/opt/1panel/docker/compose/xiaobaifupan`），任何脱离 Git 校验的本地构建都会把
-docker compose down
+来源提交变成不可追溯状态，禁止使用。
-docker compose build --pull
-docker compose up -d
-```
-
-`docker compose down` 不会删除宿主机的 `data` 目录。不要使用带有手工删除
-`data` 目录的清理命令。
 
 ## 7. 备份与恢复
 

README.md

@@ -1,76 +1,138 @@
-# 小白复盘 Web
+# 小白复盘
 
-一个面向 A 股盘后复盘的本地 Web 工作台。后端使用 Python 访问 Tushare Pro，前端不依赖构建工具。
+面向 A 股盘后复盘的本地 Web 工作台。收盘后把涨停、炸板、连板梯队、板块轮动、集合竞价、龙虎榜等数据整理成可浏览的复盘界面；不接券商、不代为下单，也不提供个股推荐。
 
-本目录是经过保真迁移、结构治理和用户人工验收的唯一正式源码，不依赖父目录旧程序或失败版本。
+本目录是唯一正式源码。模块边界见 [ARCHITECTURE.md](ARCHITECTURE.md)，产品与维护文档见 [docs/README.md](docs/README.md)。
-目录职责见[ARCHITECTURE.md](ARCHITECTURE.md)，产品与维护文档见[docs/README.md](docs/README.md)。
 
-当前包含集合竞价、涨停池、炸板池、跌停板、昨日涨停、涨停表现、市场天梯、板块轮动、题材库、人气热榜、龙虎榜和个人复盘工作区。交易日快照与同步记录保存在本地 SQLite 数据库 `data/review.db`。
+## 主要功能
 
-集合竞价中心采用盘前生命周期：9:15 前显示预告，9:15–9:25 明确等待最终竞价，9:25–9:30 自动读取并重试最终竞价筛选，9:30 后停止更新并冻结为复盘归档。当前 Tushare 只提供 9:25 最终竞价快照，不将其表述为动态虚拟撮合行情。
+登录后左侧共 16 个页面，另有一个内嵌页「策略持续跟踪」。交易日快照保存在本地 SQLite 数据库 `data/review.db`。
 
-第三阶段加入了机构席位、席位别名、个股复权日 K、资金流、自选股、涨停原因修订、个股笔记、每日复盘和历史数据回补。
+- **情绪周期**：0–100 情绪温度与阶段判定（默认首页）
+- **涨停池 / 炸板池 / 跌停板 / 昨日涨停 / 涨停表现**：封板结构、炸板、跌停与昨日反馈
+- **市场天梯**：按连板高度排列的市场梯队
+- **板块轮动**：近若干交易日板块热力与成分下钻
+- **集合竞价**：盘前生命周期；9:30 后停止更新并冻结为复盘归档。当前数据源提供 9:25 最终竞价快照，不是动态虚拟撮合行情
+- **题材库 / 人气热榜 / 龙虎榜**：题材成分、双榜人气、席位与游资档案
+- **智能选股**（会员）：六阶段策略、精选策略库、自然语言编译为受控公式后的确定性筛选与滚动回测；候选需手动加入后才进入五交易日跟踪
+- **问师**（会员）：按选定的游资思维 Skill 单师对话；新增公开角色时在 `游资skills` 下增加含 `SKILL.md` 的目录，并在 `游资skills/mentor_catalog.json` 登记。管理员私有角色放在 `data/private-mentor-skills`（不进 Git / 镜像）
+- **问天**（会员）：观势 / 观气 / 观心。卦象、干支、节气与气机由本地程序确定性计算，大模型只负责文字解释。此前仅冻结过界面视觉方案，现已解冻；问天可纳入后续数据与功能迁移，本阶段不主动重做视觉。
+- **我的复盘**：手工交易日志、每日复盘、提醒中心与复盘助手；不接券商、不自动下单
 
-股票代码在桌面端悬停后会显示分时与日 K 快速预览，默认优先展示日 K；移动端点击代码后从底部打开预览面板。股票详情以及板块、题材、指数详情均可在日 K 与最新分时之间切换。日 K 复用个股详情缓存；分时优先使用 iFinD，东方财富仅作隔离的展示兜底，并使用短时内存缓存。图表数据不写入主行情、不参与情绪、选股或问天计算；不可用时明确显示“分时不可用”，不会用日 K 模拟分时走势。
+全局能力：日间 / 夜间主题、股票代码悬停预览日 K 与分时、`Ctrl + K` 全局搜索。图表数据不写入主行情，也不参与情绪、选股或问天计算。
 
-智能选股包含六阶段盘后候选、29 套精选策略、自定义公式 DSL、自然语言公式编译、候选排名和滚动回测。阶段与精选策略在当日行情更新后由后台确定性计算；自定义选股由用户手动执行，LLM 只负责编译自然语言条件，不参与候选筛选。竞价、估值、财务、资金、人气和席位等字段按已登记的数据可用性进入因子库，缺失时明确显示覆盖问题。
+## 技术栈
 
-候选只有经用户手动加入后才进入五交易日持续跟踪，展示 T+1 开盘/收盘、T+3、T+5、最大涨幅与最大回撤。提醒中心支持手工日期提醒，并在策略首日反馈和五日跟踪完成时生成账号私有的站内提醒。
+| 层面 | 说明 |
+| --- | --- |
+| 运行时 | Python 3.12；标准库 `ThreadingHTTPServer`，无独立 Web 框架 |
+| 依赖 | `requirements.txt` 仅含 `cryptography`；问天历法使用仓库内 `vendor/lunar_python` |
+| 数据库 | SQLite（WAL），默认文件 `data/review.db` |
+| 前端 | 原生 HTML / CSS / JavaScript，无打包、无构建步骤 |
+| 部署 | Docker / Docker Compose，或本机直接运行 `server.py` |
+| 安全 | 账号密码 scrypt 哈希；行情 Token 与模型密钥用 `APP_ENCRYPTION_KEY` 加密后存库 |
 
-问师模块会读取当前复盘、近十日市场情绪、涨跌停、昨日反馈、板块轮动、市场阶段、龙虎榜和指定个股数据，再按选中的游资思维 Skill 进行单师对话。对话记录按账号、老师和交易日期保存在服务端；主模型不可用时自动切换辅助模型。
+## 环境要求
 
-新增公开问师角色时，在 `游资skills` 下增加一个包含 `SKILL.md` 的独立目录，并在 `游资skills/mentor_catalog.json` 中登记素材等级与结构质检。管理员私有角色放在 `data/private-mentor-skills`，该目录不进入 Git 或 Docker 镜像，且只会出现在管理员的问师列表中。系统会从 Skill 的 frontmatter、一级标题、核心模型和引用语中自动生成角色信息，无需修改注册代码。
+- Python 3.12（与 `Dockerfile` 一致）
+- 本机启动：能执行 `python` / `pip`
+- Docker 部署：Docker Engine 24+，Compose v2（`docker compose`）
+- 行情：部署者自行申请并配置 Tushare Pro Token；部分分时优先使用同花顺 iFinD（可选）
+- 问师、问天解释、复盘助手、自然语言编译公式：需配置 OpenAI 兼容接口；未配置时市场数据页仍可用
 
-问天模块包含三个相互独立的部分：观势以市场数据生成三才六爻，用于观察“势”，行情缺失或自动取象明显偏差时可显式手动校准六爻，人工结果与自动来源严格区分；观气依据干支、精确节气、五运六气及客主加临关系观察“运”，行业五行仅作传统取象归类；观心先准备1秒，再完成5轮“吸3秒、顿2秒、呼4秒”，随后以六次三枚铜钱起卦、察念和解卦完成一次不输入问题的问心仪式。卦象、干支、节气与气机关系均由本地确定性程序计算，LLM只负责解释，不参与起卦或改动结果。
+## 安装与启动
 
-问天模块使用项目本地的 `lunar-python` 计算历法，并使用 `data/iching_zh.json` 中的固定六十四卦、卦辞和爻辞。第三方授权见 `THIRD_PARTY_NOTICES.md`。
+仓库根目录即为运行目录（`server.py`、`requirements.txt` 都在根目录）。
 
-“我的复盘”包含结构化手工交易日志，可记录方向、价格、数量、仓位、盈亏、逻辑、执行、情绪和标签，不接券商也不自动下单。顶部“复盘助手”以流式方式读取市场统计、策略跟踪、提醒、个人复盘和交易日志；对话按账号保存，只提供分析和条件化计划。
+```bash
-
-## 启动
-
-```powershell
-cd app
 python -m pip install -r requirements.txt
 python server.py
 ```
 
-浏览器打开 `http://127.0.0.1:8765`，首次使用先注册账号。首个账号自动成为管理员，后续账号默认为普通用户。主行情不再回退演示数据：盘前、非交易日或临时取数失败时沿用最近真实收盘快照；没有任何真实快照时提示等待管理员完成首次同步。
+默认监听 `127.0.0.1:8765`（仅本机可访问）。浏览器打开该地址，首次使用先注册账号；第一个账号自动成为管理员，之后注册的默认为普通用户。
 
-需要后台启动本地验收端口时，使用`tools/start_local.ps1`。该工具把日志、进程号和Python缓存
+主行情不再回退演示数据：盘前、非交易日或临时取数失败时沿用最近真实收盘快照；没有任何真实快照时，页面会提示等待管理员完成首次同步。
-统一写入`runtime/`，不在源码根目录产生运行文件：
+
+可选参数：
+
+```bash
+python server.py --host 127.0.0.1 --port 8765
+```
+
+Windows 下若需要后台启动，并把日志、进程号和 Python 缓存写入 `runtime/`（不在源码根目录产生运行文件）：
 
 ```powershell
-powershell -ExecutionPolicy Bypass -File tools/start_local.ps1 -Port 8797
+powershell -ExecutionPolicy Bypass -File tools/start_local.ps1
 ```
 
-局域网 Docker 部署使用 `Dockerfile` 与 `compose.yaml`，完整的迁移、持久化、
+该脚本默认端口为 `8797`。统一验收：
-防火墙、备份和恢复步骤见 [DOCKER_DEPLOY.md](DOCKER_DEPLOY.md)。
 
-账号密码使用 scrypt 哈希；公共 Tushare Token、平台模型密钥以及原始生辰资料均使用 `APP_ENCRYPTION_KEY` 加密后保存在 SQLite。公共数据和平台模型归系统所有，生辰资料仍按账号隔离。普通用户不配置 LLM，只有管理员授权的有效会员可以使用平台模型。请将 `.env` 与数据库一起备份，丢失加密密钥后无法恢复这些资料。
+```bash
+python tools/verify_baseline.py
+```
 
-## 系统与账号配置
+涉及运行时或前端时再加 `--e2e`（Playwright）。
 
-管理员通过页面右上角“系统管理”保存公共 Tushare Token、平台主/辅助模型、会员每日额度和后台刷新开关。所有用户读取同一份 SQLite 行情快照，不再分别配置行情 Token。已有个人凭据中的 Tushare Token 会在升级时迁移到系统配置并从个人凭据移除。
+## Docker 使用
+
+局域网或服务器部署使用仓库根目录的 `Dockerfile` 与 `compose.yaml`。容器监听 `8765`，默认以非 root 用户运行，并把宿主机 `./data` 挂到容器内 `/app/data`。
+
+1. 复制 `.env.example` 为 `.env`，填入 `APP_ENCRYPTION_KEY` 以及行情 / 模型等初始化配置。密钥不会返回到浏览器。
+2. `compose.yaml` 构建时要求带上当前 Git 提交号，避免打出无版本标签的镜像：
+
+```bash
+export XIAOBAI_GIT_REV="$(git rev-parse HEAD)"
+export XIAOBAI_GIT_SHORT="$(git rev-parse --short=7 HEAD)"
+docker compose build
+docker compose up -d
+```
+
+3. 检查健康接口：
+
+```bash
+docker compose ps
+curl http://127.0.0.1:8765/api/health
+```
+
+健康响应类似 `{"ok": true, "storage": "sqlite", "account_required": true}`。
+
+完整的迁移、持久化、防火墙、备份、恢复与正式线构建入口见 [DOCKER_DEPLOY.md](DOCKER_DEPLOY.md)。`.env` 必须与数据库成对备份；丢失 `APP_ENCRYPTION_KEY` 后无法恢复加密资料。
+
+## 目录与配置
 
 ```text
-TUSHARE_TOKEN=你的Token
+server.py            进程入口
+backend/            服务、路由、数据、任务、LLM
+frontend/            无构建前端（shared + pages）
+config/              页面 / API / 任务等注册表
+data/                SQLite 与私有数据（数据库文件不进 Git）
+runtime/             本地日志、PID、缓存（不进 Git）
+tools/               启动、验收与构建辅助脚本
+游资skills/          公开问师角色
+vendor/              本地第三方库（含 lunar-python）
+Dockerfile
+compose.yaml
+.env.example         环境变量模板（复制为 .env 后填写）
 ```
 
-`.env` 中的 Tushare 和平台 LLM 配置只用于初始化系统配置，密钥不会返回到浏览器。后台刷新只在交易时段更新 SQLite 快照，不会主动刷新或重绘用户页面；用户点击页面“刷新”时读取最新快照。管理员也可点“后台刷新”立即启动一次后台同步，当前页面仍保持不变。
+管理员通过页面右上角「系统管理」保存公共 Tushare Token、平台主/辅助模型、会员每日额度和后台刷新开关。所有用户读取同一份 SQLite 行情快照。`.env` 中的 Tushare 和平台 LLM 配置只用于初始化系统配置。
 
-普通用户在“账号设置”中维护个人资料、查看会员状态和修改密码，不配置个人 LLM。有效会员自动使用平台模型；管理员可在“系统管理”中手动开通、续期、停用会员。平台模型受管理员设置的每日调用次数限制，管理员账号始终可用。
+普通用户在「账号设置」中维护个人资料、查看会员状态和修改密码，不配置个人 LLM。有效会员使用平台模型；管理员可开通、续期、停用会员。平台模型受每日调用次数限制，管理员账号始终可用。
 
-Tushare 各接口有独立积分权限。程序优先使用 `limit_list_d` 获取涨跌停明细；该接口不可用时，会尝试通过日线和每日涨跌停价格推算。
+相关文档：
 
-## 隔离实时聚合验证
+- [ARCHITECTURE.md](ARCHITECTURE.md) — 模块边界
+- [docs/README.md](docs/README.md) — 交接手册入口
+- [DOCKER_DEPLOY.md](DOCKER_DEPLOY.md) — Docker 部署、备份与恢复
+- [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) — 第三方授权（含问天历法库）
+- [AGENTS.md](AGENTS.md) — 维护约束
 
-`backend/data/realtime.py`用于验证东方财富、同花顺和选股宝网页数据源。它不写入 SQLite 主行情快照，也不参与情绪评分或智能选股；当 Tushare 实时指数权限不可用时，观势会使用东方财富三大指数和板块外显，并继续使用 Tushare 的板块成分内核与个股数据。
+## 注意事项与免责声明
 
-登录后可调用：
+- 本项目是个人研究与复盘工具，全部数据、指标、候选与文字分析均不构成投资建议、证券推荐或买卖要约。
-
+- 不接券商、不代为下单。交易日志只做手工记录与统计，不代表实际成交。
-```text
+- 情绪温度、阶段判定、连板梯队、策略筛选等均为基于公开数据的统计与规则计算，不预测走势，不保证收益。
-GET /api/realtime-aggregate/health?sector=元器件
+- 「问天」属于传统文化视角的观察工具，不具备预测功能，不得作为投资依据。问天不是永久冻结区：此前只冻结过界面视觉方案，现已解冻，后续数据与功能迁移可以纳入。
-```
+- 行情来自第三方接口，可能延迟、缺失或口径调整；不可用时页面会明确提示，请以交易所与券商正式披露为准。
-
+- 不要把服务端口直接暴露到公网。不要把 Token、密码、密钥、数据库或 `.env` 提交进 Git。
-返回内容包括东方财富三大指数及板块快照、指数时间差、同花顺和选股宝可用性、每个来源的耗时与错误。盘中指数时间差不超过15秒，收盘后不超过120秒。`ready=true` 仅表示本次验证满足聚合层约束，不代表这些网页内部接口具有长期稳定性或商业使用授权。
+- 股市有风险，入市需谨慎。投资决策及其后果由使用者本人承担。

backend/bootstrap/runtime.py

@@ -1,11 +1,23 @@
 from __future__ import annotations
 
 import argparse
+import logging
 from http.server import ThreadingHTTPServer
 from typing import Any
 
 
+def configure_logging() -> None:
+    """让 INFO 级结构化日志（含 datahub 影子对比报告）落到容器日志。"""
+    if logging.getLogger().handlers:
+        return
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+
+
 def main(handler_class: type[Any] | None = None, service: Any | None = None) -> None:
+    configure_logging()
     if handler_class is None or service is None:
         from backend.application import RequestHandler, SERVICE
 

backend/bootstrap/settings.py

@@ -11,6 +11,8 @@ from backend.features.accounts.security import SecretVault
 def environment_credentials(environment: Mapping[str, str]) -> dict[str, str]:
     return {
         "tushare_token": str(environment.get("TUSHARE_TOKEN") or "").strip(),
+        "datahub_token": str(environment.get("DATAHUB_TOKEN") or "").strip(),
+        "datahub_base_url": str(environment.get("DATAHUB_BASE_URL") or "").strip(),
         "ifind_refresh_token": str(environment.get("IFIND_REFRESH_TOKEN") or "").strip(),
         "ifind_access_token": str(environment.get("IFIND_ACCESS_TOKEN") or "").strip(),
         "platform_llm_primary_api_key": str(

backend/data/datahub/__init__.py

@@ -0,0 +1,15 @@
+from backend.data.datahub.bridge import DatahubAwareTushareClient, DatahubBridge
+from backend.data.datahub.client import DatahubClient, DatahubResponse
+from backend.data.datahub.errors import DatahubError
+from backend.data.datahub.settings import DATASETS, DatahubSettings, DatasetFlags
+
+__all__ = [
+    "DATASETS",
+    "DatahubAwareTushareClient",
+    "DatahubBridge",
+    "DatahubClient",
+    "DatahubError",
+    "DatahubResponse",
+    "DatahubSettings",
+    "DatasetFlags",
+]

backend/data/datahub/bridge.py

@@ -0,0 +1,542 @@
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Any, Callable
+
+from backend.data.datahub.client import DatahubClient, DatahubResponse
+from backend.data.datahub.compare import compare_rows
+from backend.data.datahub.errors import DatahubError
+from backend.data.datahub.native import (
+    API_TO_DATASET,
+    filter_calendar_rows,
+    filter_stock_rows,
+    project_fields,
+    to_native_rows,
+    yyyymmdd,
+)
+from backend.data.datahub.redact import redact_text, redact_value
+from backend.data.datahub.route_state import LEDGER
+from backend.data.datahub.settings import DatahubSettings
+from backend.data.providers.tushare_client import TushareClient
+
+LOGGER = logging.getLogger("xiaobai.datahub")
+ShadowSink = Callable[[dict[str, Any]], None]
+
+
+def _usable_intraday_points(rows: list[Any]) -> list[dict[str, Any]]:
+    points: list[dict[str, Any]] = []
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        try:
+            close = float(row.get("close") or 0)
+        except (TypeError, ValueError):
+            close = 0.0
+        if close <= 0:
+            continue
+        point = dict(row)
+        if "average" not in point and point.get("avg_price") is not None:
+            point["average"] = point.get("avg_price")
+        points.append(point)
+    return points
+
+
+EMPTY_FAIL_DATASETS = {
+    "stocks", "daily", "index_daily", "valuation", "moneyflow", "auction",
+    "limit_events", "sector_daily",
+}
+
+
+def looks_like_heaven(module_name: str, filename: str = "") -> bool:
+    """问天调用栈识别（诊断用）。问天按数据集依赖接入，不再整栈强制旧链路。"""
+    path = filename.replace("\\", "/")
+    return module_name.startswith("backend.features.heaven") or "/features/heaven/" in path
+
+
+def caller_is_heaven(depth: int = 24) -> bool:
+    frame = sys._getframe(1)
+    for _ in range(depth):
+        frame = frame.f_back if frame is not None else None
+        if frame is None:
+            return False
+        name = str(frame.f_globals.get("__name__") or "")
+        filename = str(frame.f_code.co_filename or "")
+        if looks_like_heaven(name, filename):
+            return True
+    return False
+
+
+class DatahubBridge:
+    def __init__(
+        self,
+        settings: DatahubSettings,
+        client: DatahubClient,
+        shadow_sink: ShadowSink | None = None,
+        heaven_guard: Callable[[], bool] | None = None,
+    ) -> None:
+        self.settings = settings
+        self.client = client
+        self.shadow_sink = shadow_sink
+        self.heaven_guard = heaven_guard or caller_is_heaven
+
+    def dataset_status(self, trade_date: str) -> list[dict[str, Any]] | None:
+        flags = self.settings.flags("status")
+        if not flags.read and not flags.shadow:
+            return None
+        try:
+            response = self._require_fresh(self.client.dataset_status(yyyymmdd(trade_date)), "status")
+            rows = list(response.data or [])
+            if flags.shadow:
+                self._emit_shadow(compare_rows("status", [], rows, response.meta))
+            if flags.read:
+                return rows
+            return None
+        except Exception as exc:
+            self._log_failure("status", exc)
+            if flags.shadow:
+                self._emit_shadow(compare_rows("status", [], [], {}, self._error_text(exc)))
+            return None
+
+    def batches(self, trade_date: str, dataset: str = "") -> list[dict[str, Any]] | None:
+        flags = self.settings.flags("status")
+        if not flags.read:
+            return None
+        try:
+            response = self._require_fresh(
+                self.client.batches(yyyymmdd(trade_date), dataset),
+                "status",
+            )
+            return list(response.data or [])
+        except Exception as exc:
+            self._log_failure("status", exc)
+            return None
+
+    def try_intraday(self, code: str) -> dict[str, Any] | None:
+        flags = self.settings.flags("intraday")
+        if not flags.read:
+            return None
+        try:
+            response = self.client.intraday_points(code=code)
+            data = response.data
+            if not isinstance(data, dict):
+                raise DatahubError("EMPTY", "datahub intraday payload invalid")
+            points = _usable_intraday_points(data.get("points") or [])
+            if not points:
+                raise DatahubError("EMPTY", "datahub intraday empty")
+            if (response.meta or {}).get("stale"):
+                raise DatahubError("STALE", "datahub intraday stale")
+            self._record_route("intraday", "datahub", str((response.meta or {}).get("source") or "datahub"))
+            return {
+                "entity_type": str(data.get("entity_type") or "stock"),
+                "identifier": str(data.get("identifier") or code),
+                "name": str(data.get("name") or ""),
+                "code": str(data.get("code") or code),
+                "trade_date": str(data.get("trade_date") or points[-1].get("date") or ""),
+                "previous_close": float(data.get("previous_close") or 0),
+                "points": points,
+                "source": "datahub",
+            }
+        except Exception as exc:
+            self._log_failure("intraday", exc)
+            return None
+
+    def try_market_quotes(self, trade_date: str = "") -> list[dict[str, Any]] | None:
+        return self._try_quote_rows("quotes", {}, expected_date=trade_date, minimum=200)
+
+    def try_quotes(self, codes: list[str]) -> list[dict[str, Any]] | None:
+        cleaned = [str(item or "").strip() for item in codes if str(item or "").strip()]
+        if not cleaned:
+            return None
+        return self._try_quote_rows("quotes", {"codes": ",".join(cleaned[:60])}, minimum=1)
+
+    def try_index_quotes(self) -> list[dict[str, Any]] | None:
+        flags = self.settings.flags("index_quotes")
+        if not flags.read:
+            return None
+        try:
+            response = self.client.index_quotes()
+            rows = [dict(item) for item in (response.data or []) if isinstance(item, dict)]
+            if len(rows) < 3:
+                raise DatahubError("EMPTY", "datahub index quotes incomplete")
+            if (response.meta or {}).get("stale"):
+                raise DatahubError("STALE", "datahub index quotes stale")
+            self._record_route(
+                "index_quotes",
+                "datahub",
+                str((response.meta or {}).get("source") or "datahub"),
+            )
+            return rows
+        except Exception as exc:
+            self._log_failure("index_quotes", exc)
+            return None
+
+    def try_daily_chart(
+        self,
+        code: str,
+        end_date: str,
+        limit: int = 90,
+        dataset: str = "daily",
+    ) -> list[dict[str, Any]] | None:
+        flags = self.settings.flags(dataset)
+        if not flags.read:
+            return None
+        compact_end = yyyymmdd(end_date)
+        if not compact_end:
+            return None
+        try:
+            start = _shift_yyyymmdd(compact_end, -max(190, int(limit) * 3))
+            if dataset == "index_daily":
+                response = self._paginate(
+                    self.client.index_bars,
+                    {"code": code, "from": start, "to": compact_end},
+                )
+            else:
+                response = self._paginate(
+                    self.client.daily_bars,
+                    {"code": code, "from": start, "to": compact_end, "adjust": "none"},
+                )
+            # Charts can use a partial history window; do not discard usable bars
+            # just because the requested lookback is not fully covered.
+            self._validate_usable(
+                dataset,
+                list(response.data or []),
+                response,
+                require_complete=False,
+            )
+            rows = _chart_bars(list(response.data or []))
+            if not rows:
+                raise DatahubError("EMPTY", f"{dataset} chart empty")
+            self._record_route(dataset, "datahub", str((response.meta or {}).get("source") or "datahub"))
+            return rows[-max(20, min(180, int(limit))):]
+        except Exception as exc:
+            self._log_failure(dataset, exc)
+            return None
+
+    def record_legacy(self, dataset: str, source: str = "", error: str = "") -> None:
+        self._record_route(dataset, "legacy", source, error)
+
+    def route_snapshot(self) -> list[dict[str, Any]]:
+        return LEDGER.snapshot()
+
+    def _try_quote_rows(
+        self,
+        dataset: str,
+        params: dict[str, Any],
+        expected_date: str = "",
+        minimum: int = 1,
+    ) -> list[dict[str, Any]] | None:
+        flags = self.settings.flags(dataset)
+        if not flags.read:
+            return None
+        try:
+            response = self.client.quotes_latest(**params)
+            rows = [_native_quote(item) for item in (response.data or []) if isinstance(item, dict)]
+            rows = [item for item in rows if item]
+            want = yyyymmdd(expected_date)
+            if want:
+                dated = [item for item in rows if not item.get("quote_date") or item.get("quote_date") == want]
+                if dated:
+                    rows = dated
+            if len(rows) < minimum:
+                raise DatahubError("EMPTY", f"datahub {dataset} empty")
+            if (response.meta or {}).get("stale"):
+                raise DatahubError("STALE", f"datahub {dataset} stale")
+            self._record_route(dataset, "datahub", str((response.meta or {}).get("source") or "datahub"))
+            return rows
+        except Exception as exc:
+            self._log_failure(dataset, exc)
+            return None
+
+    def query(
+        self,
+        api_name: str,
+        params: dict[str, Any] | None,
+        fields: str,
+        legacy_query: Callable[..., list[dict[str, Any]]],
+    ) -> list[dict[str, Any]]:
+        dataset = API_TO_DATASET.get(api_name)
+        # 问天按实际数据依赖接入：已映射到 hub 的 API 跟随开关；未映射的继续旧链路。
+        if not dataset:
+            return legacy_query(api_name, params, fields)
+        flags = self.settings.flags(dataset)
+        if not flags.read and not flags.shadow:
+            return legacy_query(api_name, params, fields)
+
+        hub_rows: list[dict[str, Any]] | None = None
+        hub_meta: dict[str, Any] = {}
+        hub_error: str | None = None
+        hub_canonical: list[dict[str, Any]] = []
+        try:
+            response = self._fetch_dataset(dataset, params or {}, api_name=api_name)
+            hub_canonical = self._extract_rows(dataset, response, params or {})
+            hub_rows = to_native_rows(dataset, hub_canonical)
+            hub_meta = dict(response.meta)
+            self._validate_usable(dataset, hub_rows, response)
+        except Exception as exc:
+            hub_error = self._error_text(exc)
+            self._log_failure(dataset, exc)
+
+        if flags.shadow:
+            try:
+                legacy_rows = legacy_query(api_name, params, fields)
+            except Exception as exc:
+                if flags.read and hub_rows is not None and hub_error is None:
+                    self._emit_shadow(
+                        compare_rows(dataset, [], hub_canonical, hub_meta, self._error_text(exc), fields)
+                    )
+                    return project_fields(hub_rows, fields)
+                raise
+            self._emit_shadow(compare_rows(dataset, legacy_rows, hub_canonical, hub_meta, hub_error, fields))
+            if flags.read and hub_rows is not None and hub_error is None:
+                self._record_route(dataset, "datahub", str(hub_meta.get("source") or "datahub"))
+                return project_fields(hub_rows, fields)
+            if flags.read:
+                self._record_route(dataset, "legacy", "tushare", hub_error or "")
+            return legacy_rows
+
+        if flags.read and hub_rows is not None and hub_error is None:
+            self._record_route(dataset, "datahub", str(hub_meta.get("source") or "datahub"))
+            return project_fields(hub_rows, fields)
+        result = legacy_query(api_name, params, fields)
+        if flags.read:
+            self._record_route(dataset, "legacy", "tushare", hub_error or "")
+        return result
+
+    def _fetch_dataset(self, dataset: str, params: dict[str, Any], api_name: str = "") -> DatahubResponse:
+        date = yyyymmdd(params.get("trade_date") or params.get("date"))
+        start = yyyymmdd(params.get("start_date") or params.get("from") or date)
+        end = yyyymmdd(params.get("end_date") or params.get("to") or date)
+        code = str(params.get("ts_code") or params.get("code") or "").strip()
+        if dataset == "calendar":
+            if not start or not end:
+                raise DatahubError("INVALID_ARGUMENT", "calendar requires start_date and end_date")
+            return self.client.calendar(start, end)
+        if dataset == "stocks":
+            return self._paginate(self.client.stocks, {})
+        fetchers = {
+            "daily": self.client.daily_bars,
+            "index_daily": self.client.index_bars,
+            "valuation": self.client.valuation,
+            "moneyflow": self.client.moneyflow,
+            "auction": self.client.auction,
+            "limit_events": self.client.limit_events,
+            "popularity": self.client.popularity,
+            "dragon_tiger": self.client.dragon_tiger,
+            "sector_daily": self.client.sectors,
+        }
+        fetcher = fetchers[dataset]
+        query: dict[str, Any] = {}
+        if code:
+            query["code"] = code
+        if date and not (params.get("start_date") or params.get("end_date")):
+            query["date"] = date
+        else:
+            if start:
+                query["from"] = start
+            if end:
+                query["to"] = end
+        if dataset == "daily":
+            query["adjust"] = "none"
+        if dataset == "limit_events":
+            limit_type = str(params.get("limit_type") or "").strip().upper()
+            if limit_type:
+                query["limit_type"] = limit_type
+        if dataset == "popularity":
+            if api_name == "ths_hot":
+                query["source"] = "ths"
+            elif api_name == "dc_hot":
+                query["source"] = "dc"
+        if dataset == "sector_daily":
+            family = {
+                "ths_daily": "ths",
+                "dc_index": "dc",
+                "sw_daily": "sw",
+            }.get(api_name, "")
+            if family:
+                query["family"] = family
+        return self._paginate(fetcher, query)
+
+    def _paginate(self, fetcher: Callable[..., DatahubResponse], params: dict[str, Any]) -> DatahubResponse:
+        limit = self.settings.page_limit
+        offset = 0
+        rows: list[Any] = []
+        meta: dict[str, Any] = {}
+        schema_version = 1
+        while True:
+            page = fetcher(**{**params, "limit": limit, "offset": offset})
+            meta = dict(page.meta)
+            schema_version = page.schema_version
+            data = page.data or []
+            if not isinstance(data, list):
+                raise DatahubError("INTERNAL", "datahub returned a non-list payload")
+            rows.extend(data)
+            if len(data) < limit:
+                break
+            offset += limit
+            if offset > 200_000:
+                break
+        return DatahubResponse(data=rows, meta=meta, schema_version=schema_version)
+
+    def _extract_rows(
+        self,
+        dataset: str,
+        response: DatahubResponse,
+        params: dict[str, Any],
+    ) -> list[dict[str, Any]]:
+        rows = [dict(item) for item in (response.data or [])]
+        if dataset == "calendar":
+            return filter_calendar_rows(rows, params)
+        if dataset == "stocks":
+            return filter_stock_rows(rows, params)
+        return rows
+
+    def _validate_usable(
+        self,
+        dataset: str,
+        rows: list[dict[str, Any]],
+        response: DatahubResponse,
+        require_complete: bool = True,
+    ) -> None:
+        meta = response.meta or {}
+        stale_seconds = int(meta.get("staleness_seconds") or 0)
+        if meta.get("stale") or stale_seconds > self.settings.stale_seconds_max:
+            raise DatahubError("STALE", f"{dataset} data is stale")
+        if dataset in EMPTY_FAIL_DATASETS and not rows:
+            raise DatahubError("EMPTY", f"{dataset} returned no rows")
+        coverage = meta.get("coverage") if isinstance(meta.get("coverage"), dict) else {}
+        if require_complete and (meta.get("incomplete") is True or coverage.get("complete") is False):
+            missing = coverage.get("missing_count")
+            raise DatahubError("INCOMPLETE", f"{dataset} range is incomplete missing={missing}")
+
+    def _require_fresh(self, response: DatahubResponse, dataset: str) -> DatahubResponse:
+        self._validate_usable(dataset, list(response.data or []) if isinstance(response.data, list) else [], response)
+        return response
+
+    def _emit_shadow(self, report: dict[str, Any]) -> None:
+        safe = redact_value(report, secrets=self.settings.secrets())
+        LOGGER.info("datahub shadow %s", safe)
+        if self.shadow_sink is not None:
+            self.shadow_sink(report)
+
+    def _log_failure(self, dataset: str, exc: Exception) -> None:
+        error = redact_text(self._error_text(exc), self.settings.secrets())
+        LOGGER.warning("datahub fallback dataset=%s error=%s", dataset, error)
+        self._record_route(dataset, "legacy", "pending-legacy", error)
+
+    def _record_route(self, dataset: str, route: str, source: str = "", error: str = "") -> None:
+        LEDGER.record(dataset, route, source, redact_text(error, self.settings.secrets()))
+
+    def _error_text(self, exc: Exception) -> str:
+        if isinstance(exc, DatahubError):
+            text = f"{exc.code}: {exc.message}"
+        else:
+            text = str(exc)
+        return redact_text(text, self.settings.secrets())
+
+
+def _native_quote(row: dict[str, Any]) -> dict[str, Any] | None:
+    ts_code = str(row.get("ts_code") or "").strip()
+    close = _finite(row.get("close") if row.get("close") not in (None, "") else row.get("price"))
+    previous = _finite(
+        row.get("pre_close") if row.get("pre_close") not in (None, "") else row.get("previous_close")
+    )
+    if not ts_code or close <= 0 or previous <= 0:
+        return None
+    volume = _finite(row.get("vol") if row.get("vol") not in (None, "") else row.get("volume"))
+    return {
+        "ts_code": ts_code,
+        "name": str(row.get("name") or ts_code).strip(),
+        "pre_close": previous,
+        "open": _finite(row.get("open")),
+        "high": _finite(row.get("high")),
+        "low": _finite(row.get("low")),
+        "close": close,
+        "vol": volume,
+        "amount": _finite(row.get("amount")),
+        "num": 0,
+        "quote_date": yyyymmdd(row.get("quote_date") or row.get("trade_date")),
+        "source": str(row.get("source") or "datahub"),
+    }
+
+
+def _chart_bars(rows: list[Any]) -> list[dict[str, Any]]:
+    normalized: list[dict[str, Any]] = []
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        compact = yyyymmdd(row.get("trade_date"))
+        close = _finite(row.get("close"))
+        if len(compact) != 8 or close <= 0:
+            continue
+        volume = _finite(row.get("volume") if row.get("volume") not in (None, "") else row.get("vol"))
+        amount = _finite(row.get("amount"))
+        if volume and volume < close * 10 and amount > 1000:
+            volume = volume * 100
+        trade_date = f"{compact[:4]}-{compact[4:6]}-{compact[6:8]}"
+        previous = normalized[-1]["close"] if normalized else 0.0
+        normalized.append(
+            {
+                "trade_date": trade_date,
+                "open": _finite(row.get("open")),
+                "high": _finite(row.get("high")),
+                "low": _finite(row.get("low")),
+                "close": close,
+                "change": round((close / previous - 1) * 100, 4) if previous else _finite(row.get("pct_chg")),
+                "volume": volume,
+                "amount_billion": amount / 100_000_000,
+            }
+        )
+    return normalized
+
+
+def _shift_yyyymmdd(value: str, days: int) -> str:
+    from datetime import datetime, timedelta
+
+    stamp = datetime.strptime(value, "%Y%m%d")
+    return (stamp + timedelta(days=days)).strftime("%Y%m%d")
+
+
+def _finite(value: Any) -> float:
+    try:
+        return float(value or 0)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+class DatahubAwareTushareClient:
+    def __init__(self, legacy: TushareClient, bridge: DatahubBridge) -> None:
+        self._legacy = legacy
+        self._bridge = bridge
+        # Mixins run as methods on the inner instance (dashboard / indices /
+        # getattr). Bind hub hooks and query onto that instance so real
+        # assembly cannot skip 8766.
+        self._legacy_query = legacy.query
+        legacy.query = self.query
+        legacy.try_market_quotes = self.try_market_quotes
+        legacy.try_quotes = self.try_quotes
+        legacy.try_index_quotes = self.try_index_quotes
+        legacy.record_datahub_legacy = self.record_datahub_legacy
+
+    def query(
+        self,
+        api_name: str,
+        params: dict[str, Any] | None = None,
+        fields: str = "",
+    ) -> list[dict[str, Any]]:
+        return self._bridge.query(api_name, params, fields, self._legacy_query)
+
+    def try_market_quotes(self, trade_date: str = "") -> list[dict[str, Any]] | None:
+        return self._bridge.try_market_quotes(trade_date)
+
+    def try_quotes(self, codes: list[str]) -> list[dict[str, Any]] | None:
+        return self._bridge.try_quotes(codes)
+
+    def try_index_quotes(self) -> list[dict[str, Any]] | None:
+        return self._bridge.try_index_quotes()
+
+    def record_datahub_legacy(self, dataset: str, source: str = "", error: str = "") -> None:
+        self._bridge.record_legacy(dataset, source, error)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._legacy, name)

backend/data/datahub/client.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import json
+import logging
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from backend.data.datahub.errors import DatahubError
+from backend.data.datahub.redact import redact_text
+from backend.data.datahub.settings import DatahubSettings
+
+LOGGER = logging.getLogger("xiaobai.datahub")
+UrlOpen = Callable[..., Any]
+
+
+@dataclass(frozen=True)
+class DatahubResponse:
+    data: Any
+    meta: dict[str, Any] = field(default_factory=dict)
+    schema_version: int = 1
+    status: int = 200
+
+
+class DatahubClient:
+    def __init__(
+        self,
+        settings: DatahubSettings,
+        urlopen: UrlOpen = urllib.request.urlopen,
+    ) -> None:
+        self.settings = settings
+        self._urlopen = urlopen
+
+    def health(self) -> DatahubResponse:
+        return self.get("/v1/health")
+
+    def calendar(self, start: str, end: str) -> DatahubResponse:
+        return self.get("/v1/calendar", {"from": start, "to": end})
+
+    def stocks(self, updated_since: str = "", limit: int | None = None, offset: int = 0) -> DatahubResponse:
+        params: dict[str, Any] = {"offset": offset, "limit": limit or self.settings.page_limit}
+        if updated_since:
+            params["updated_since"] = updated_since
+        return self.get("/v1/stocks", params)
+
+    def daily_bars(self, **params: Any) -> DatahubResponse:
+        return self.get("/v1/bars/daily", params)
+
+    def index_bars(self, **params: Any) -> DatahubResponse:
+        return self.get("/v1/indexes/bars", params)
+
+    def valuation(self, **params: Any) -> DatahubResponse:
+        return self.get("/v1/valuation", params)
+
+    def moneyflow(self, **params: Any) -> DatahubResponse:
+        return self.get("/v1/moneyflow", params)
+
+    def auction(self, **params: Any) -> DatahubResponse:
+        return self.get("/v1/auction", params)
+
+    def limit_events(self, **params: Any) -> DatahubResponse:
+        return self.get("/v1/limit-events", params)
+
+    def popularity(self, **params: Any) -> DatahubResponse:
+        return self.get("/v1/popularity", params)
+
+    def dragon_tiger(self, **params: Any) -> DatahubResponse:
+        return self.get("/v1/dragon-tiger", params)
+
+    def sectors(self, **params: Any) -> DatahubResponse:
+        return self.get("/v1/sectors", params)
+
+    def quotes_latest(self, **params: Any) -> DatahubResponse:
+        return self.get("/v1/quotes/latest", params)
+
+    def index_quotes(self, **params: Any) -> DatahubResponse:
+        return self.get("/v1/indexes/quotes", params)
+
+    def intraday_points(self, **params: Any) -> DatahubResponse:
+        return self.get("/v1/intraday/points", params)
+
+    def dataset_status(self, date: str) -> DatahubResponse:
+        return self.get("/v1/datasets/status", {"date": date})
+
+    def batches(self, date: str, dataset: str = "") -> DatahubResponse:
+        params: dict[str, Any] = {"date": date}
+        if dataset:
+            params["dataset"] = dataset
+        return self.get("/v1/batches", params)
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> DatahubResponse:
+        if not self.settings.token:
+            raise DatahubError("NOT_CONFIGURED", "DATAHUB_TOKEN is not configured")
+        query = {
+            key: value
+            for key, value in (params or {}).items()
+            if value is not None and value != ""
+        }
+        url = self.settings.base_url + path
+        if query:
+            url = f"{url}?{urllib.parse.urlencode(query)}"
+        attempts = 1 + max(0, self.settings.retries)
+        last_error: DatahubError | None = None
+        for attempt in range(attempts):
+            try:
+                return self._request(url)
+            except DatahubError as exc:
+                last_error = exc
+                if exc.code not in {"TIMEOUT", "UNAVAILABLE"} or attempt + 1 >= attempts:
+                    raise
+                LOGGER.warning(
+                    "datahub retry %s/%s %s",
+                    attempt + 1,
+                    attempts,
+                    redact_text(str(exc), self.settings.secrets()),
+                )
+        raise last_error or DatahubError("INTERNAL", "datahub request failed")
+
+    def _request(self, url: str) -> DatahubResponse:
+        request = urllib.request.Request(
+            url,
+            headers={
+                "Accept": "application/json",
+                "X-Datahub-Token": self.settings.token,
+                "User-Agent": "XiaobaiReviewDatahub/1.0",
+            },
+            method="GET",
+        )
+        try:
+            with self._urlopen(request, timeout=self.settings.timeout_seconds) as response:
+                status = int(getattr(response, "status", 200) or 200)
+                raw = response.read().decode("utf-8")
+        except TimeoutError as exc:
+            raise DatahubError("TIMEOUT", "datahub request timed out") from exc
+        except urllib.error.HTTPError as exc:
+            body = _read_error_body(exc)
+            raise _http_error(exc.code, body, self.settings.secrets()) from exc
+        except urllib.error.URLError as exc:
+            reason = redact_text(str(getattr(exc, "reason", exc)), self.settings.secrets())
+            if "timed out" in reason.lower():
+                raise DatahubError("TIMEOUT", "datahub request timed out") from exc
+            raise DatahubError("UNAVAILABLE", f"datahub unavailable: {reason}") from exc
+        payload = _parse_json(raw, self.settings.secrets())
+        return _as_response(payload, status, self.settings.secrets())
+
+
+def _parse_json(raw: str, secrets: tuple[str, ...]) -> dict[str, Any]:
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise DatahubError("INTERNAL", "datahub returned invalid json") from exc
+    if not isinstance(payload, dict):
+        raise DatahubError("INTERNAL", "datahub returned a non-object payload")
+    return payload
+
+
+def _as_response(payload: dict[str, Any], status: int, secrets: tuple[str, ...]) -> DatahubResponse:
+    error = payload.get("error")
+    if isinstance(error, dict):
+        raise _mapped_error(str(error.get("code") or "INTERNAL"), str(error.get("message") or "datahub error"), status)
+    if status >= 400:
+        raise DatahubError("UNAVAILABLE", f"datahub http {status}", status)
+    return DatahubResponse(
+        data=payload.get("data"),
+        meta=dict(payload.get("meta") or {}),
+        schema_version=int(payload.get("schema_version") or 1),
+        status=status,
+    )
+
+
+def _http_error(status: int, payload: dict[str, Any], secrets: tuple[str, ...]) -> DatahubError:
+    error = payload.get("error") if isinstance(payload.get("error"), dict) else {}
+    code = str((error or {}).get("code") or "")
+    message = str((error or {}).get("message") or payload.get("message") or f"datahub http {status}")
+    message = redact_text(message, secrets)
+    if status == 401 or code == "UNAUTHORIZED":
+        return DatahubError("UNAUTHORIZED", message, status)
+    if status == 404 or code == "DATASET_NOT_PUBLISHED":
+        return DatahubError("DATASET_NOT_PUBLISHED", message, status)
+    if status == 400 or code == "INVALID_ARGUMENT":
+        return DatahubError("INVALID_ARGUMENT", message, status)
+    if status in {429, 503} or code in {"RATE_LIMITED", "SOURCE_UNAVAILABLE"}:
+        return DatahubError("UNAVAILABLE", message, status)
+    return DatahubError(code or "INTERNAL", message, status)
+
+
+def _mapped_error(code: str, message: str, status: int) -> DatahubError:
+    if code == "STALE_DATA":
+        return DatahubError("STALE", message, status)
+    if code in {"UNAUTHORIZED", "DATASET_NOT_PUBLISHED", "INVALID_ARGUMENT"}:
+        return DatahubError(code, message, status)
+    if code in {"RATE_LIMITED", "SOURCE_UNAVAILABLE"}:
+        return DatahubError("UNAVAILABLE", message, status)
+    return DatahubError(code or "INTERNAL", message, status)
+
+
+def _read_error_body(exc: urllib.error.HTTPError) -> dict[str, Any]:
+    try:
+        raw = exc.read().decode("utf-8")
+        payload = json.loads(raw)
+        return payload if isinstance(payload, dict) else {"message": raw}
+    except Exception:
+        return {"message": str(exc)}

backend/data/datahub/compare.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from typing import Any
+
+from backend.data.datahub.native import SCALE_FIELDS, row_key, to_canonical_row, yyyymmdd
+
+NUMERIC_TOLERANCE = 1e-4
+CANONICAL_ALIASES = {"volume": "vol"}
+
+
+def compare_rows(
+    dataset: str,
+    legacy_rows: list[dict[str, Any]],
+    hub_rows: list[dict[str, Any]] | None,
+    hub_meta: dict[str, Any] | None = None,
+    hub_error: str | None = None,
+    fields: str = "",
+) -> dict[str, Any]:
+    hub = hub_rows or []
+    requested = _requested_fields(fields)
+    legacy_map = {row_key(dataset, row): row for row in legacy_rows}
+    hub_map = {row_key(dataset, _align_hub_row(row)): row for row in hub}
+    missing_hub = sorted(key for key in legacy_map if key not in hub_map)
+    missing_legacy = sorted(key for key in hub_map if key not in legacy_map)
+    value_diffs: list[dict[str, Any]] = []
+    unit_conversion: list[dict[str, Any]] = []
+    matched = 0
+    for key, legacy in legacy_map.items():
+        hub_row = hub_map.get(key)
+        if hub_row is None:
+            continue
+        field_report = _compare_fields(dataset, legacy, hub_row, requested)
+        if field_report["unit_conversion"]:
+            unit_conversion.append({"key": list(key), "fields": field_report["unit_conversion"]})
+        if field_report["value_diff"]:
+            value_diffs.append({"key": list(key), "fields": field_report["value_diff"]})
+        if not field_report["unit_conversion"] and not field_report["value_diff"]:
+            matched += 1
+    stale_seconds = int((hub_meta or {}).get("staleness_seconds") or 0)
+    time_skew = bool((hub_meta or {}).get("stale")) or stale_seconds > 0
+    return {
+        "dataset": dataset,
+        "legacy_rows": len(legacy_rows),
+        "hub_rows": len(hub),
+        "matched": matched,
+        "missing_hub": [list(item) for item in missing_hub[:20]],
+        "missing_legacy": [list(item) for item in missing_legacy[:20]],
+        "missing_hub_count": len(missing_hub),
+        "missing_legacy_count": len(missing_legacy),
+        "value_diff_count": len(value_diffs),
+        "unit_conversion_count": len(unit_conversion),
+        "value_diffs": value_diffs[:20],
+        "unit_conversion": unit_conversion[:20],
+        "time_skew": time_skew,
+        "staleness_seconds": stale_seconds,
+        "published_at": (hub_meta or {}).get("published_at"),
+        "trade_date": yyyymmdd((hub_meta or {}).get("trade_date")),
+        "hub_error": hub_error,
+        "fields_compared": sorted(requested) if requested is not None else None,
+        "equal": (
+            not hub_error
+            and not missing_hub
+            and not missing_legacy
+            and not value_diffs
+            and not unit_conversion
+            and not time_skew
+        ),
+    }
+
+
+def _align_hub_row(row: dict[str, Any]) -> dict[str, Any]:
+    aligned = dict(row)
+    if "volume" in aligned and "vol" not in aligned:
+        aligned["vol"] = aligned.get("volume")
+    return aligned
+
+
+def _requested_fields(fields: str) -> list[str] | None:
+    """Fields the website actually asked for; None means "no projection"."""
+    keys = [item.strip() for item in str(fields or "").split(",") if item.strip()]
+    if not keys:
+        return None
+    seen: list[str] = []
+    for key in keys:
+        canonical = CANONICAL_ALIASES.get(key, key)
+        if canonical not in seen:
+            seen.append(canonical)
+    return seen
+
+
+def _compare_fields(
+    dataset: str,
+    legacy: dict[str, Any],
+    hub: dict[str, Any],
+    requested: list[str] | None = None,
+) -> dict[str, list[dict[str, Any]]]:
+    canonical_legacy = to_canonical_row(dataset, legacy)
+    hub_canonical = _hub_canonical(dataset, hub)
+    native_hub = _align_hub_row(hub)
+    value_diff: list[dict[str, Any]] = []
+    unit_conversion: list[dict[str, Any]] = []
+    keys = (set(canonical_legacy) | set(hub_canonical)) - {"batch_id", "updated_at", "volume"}
+    if requested is not None:
+        # Compare only what the website asked for. Extra hub columns are
+        # transport detail, not business differences; a requested field still
+        # alarms when it is missing or holds a different value.
+        keys = set(requested) - {"batch_id", "updated_at", "volume"}
+    scales = SCALE_FIELDS.get(dataset) or {}
+    for field in sorted(keys):
+        left = canonical_legacy.get(field)
+        right = hub_canonical.get(field)
+        if _same(left, right):
+            continue
+        native_left = legacy.get(field)
+        hub_raw = native_hub.get(field)
+        if field in scales and _near(_optional(native_left), _optional(hub_raw)):
+            unit_conversion.append(
+                {"field": field, "legacy": native_left, "hub": hub_raw, "reason": "unit_conversion"}
+            )
+            continue
+        value_diff.append({"field": field, "legacy": left, "hub": right, "reason": "value_diff"})
+    return {"value_diff": value_diff, "unit_conversion": unit_conversion}
+
+
+def _hub_canonical(dataset: str, row: dict[str, Any]) -> dict[str, Any]:
+    """Hub API rows are already canonical; only align field names."""
+    aligned = dict(row)
+    if "volume" in aligned and "vol" not in aligned:
+        aligned["vol"] = aligned.get("volume")
+    if dataset == "calendar":
+        is_open = aligned.get("is_open")
+        aligned["is_open"] = 1 if is_open in (True, 1, "1", "Y", "y") else 0
+        aligned["cal_date"] = yyyymmdd(aligned.get("cal_date"))
+        aligned["pretrade_date"] = yyyymmdd(aligned.get("pretrade_date")) or None
+        aligned["exchange"] = str(aligned.get("exchange") or "SSE")
+    return aligned
+
+
+def _same(left: Any, right: Any) -> bool:
+    if left in (None, "") and right in (None, ""):
+        return True
+    if isinstance(left, (int, float)) or isinstance(right, (int, float)):
+        return _near(_optional(left), _optional(right))
+    return str(left or "") == str(right or "")
+
+
+def _near(left: float | None, right: float | None) -> bool:
+    if left is None and right is None:
+        return True
+    if left is None or right is None:
+        return False
+    return abs(left - right) <= max(NUMERIC_TOLERANCE, abs(left) * 1e-9, abs(right) * 1e-9)
+
+
+def _optional(value: Any) -> float | None:
+    if value in (None, ""):
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None

backend/data/datahub/errors.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+
+class DatahubError(RuntimeError):
+    def __init__(self, code: str, message: str, status: int | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+
+    def __str__(self) -> str:
+        return f"{self.code}: {self.message}"

backend/data/datahub/native.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+from typing import Any
+
+from backend.data.numbers import finite_number
+
+
+AMOUNT_THOUSAND_YUAN = 1000.0
+AMOUNT_WAN_YUAN = 10000.0
+VOLUME_LOT = 100.0
+
+API_TO_DATASET = {
+    "trade_cal": "calendar",
+    "stock_basic": "stocks",
+    "daily": "daily",
+    "daily_basic": "valuation",
+    "index_daily": "index_daily",
+    "moneyflow": "moneyflow",
+    "stk_auction": "auction",
+    "limit_list_d": "limit_events",
+    "ths_hot": "popularity",
+    "dc_hot": "popularity",
+    "hm_detail": "dragon_tiger",
+    "ths_daily": "sector_daily",
+    "dc_index": "sector_daily",
+    "sw_daily": "sector_daily",
+}
+
+SCALE_FIELDS = {
+    "daily": {"vol": VOLUME_LOT, "amount": AMOUNT_THOUSAND_YUAN},
+    "index_daily": {"vol": VOLUME_LOT, "amount": AMOUNT_THOUSAND_YUAN},
+    "valuation": {"total_mv": AMOUNT_WAN_YUAN, "circ_mv": AMOUNT_WAN_YUAN},
+    "moneyflow": {
+        "buy_sm_amount": AMOUNT_WAN_YUAN,
+        "sell_sm_amount": AMOUNT_WAN_YUAN,
+        "buy_md_amount": AMOUNT_WAN_YUAN,
+        "sell_md_amount": AMOUNT_WAN_YUAN,
+        "buy_lg_amount": AMOUNT_WAN_YUAN,
+        "sell_lg_amount": AMOUNT_WAN_YUAN,
+        "buy_elg_amount": AMOUNT_WAN_YUAN,
+        "sell_elg_amount": AMOUNT_WAN_YUAN,
+        "net_mf_amount": AMOUNT_WAN_YUAN,
+    },
+    "auction": {"vol": VOLUME_LOT, "float_share": AMOUNT_WAN_YUAN},
+    "limit_events": {
+        "limit_amount": AMOUNT_WAN_YUAN,
+        "float_mv": AMOUNT_WAN_YUAN,
+        "total_mv": AMOUNT_WAN_YUAN,
+    },
+    "dragon_tiger": {
+        "buy_amount": AMOUNT_WAN_YUAN,
+        "sell_amount": AMOUNT_WAN_YUAN,
+        "net_amount": AMOUNT_WAN_YUAN,
+    },
+}
+
+
+def yyyymmdd(value: Any) -> str:
+    return str(value or "").replace("-", "")[:8]
+
+
+def to_native_rows(dataset: str, rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [to_native_row(dataset, row) for row in rows]
+
+
+def to_native_row(dataset: str, row: dict[str, Any]) -> dict[str, Any]:
+    if dataset == "calendar":
+        is_open = row.get("is_open")
+        return {
+            "exchange": str(row.get("exchange") or "SSE"),
+            "cal_date": yyyymmdd(row.get("cal_date")),
+            "is_open": 1 if is_open in (True, 1, "1", "Y", "y") else 0,
+            "pretrade_date": yyyymmdd(row.get("pretrade_date")) or None,
+        }
+    converted = dict(row)
+    converted.pop("batch_id", None)
+    if "volume" in converted and "vol" not in converted:
+        converted["vol"] = converted.pop("volume")
+    elif "volume" in converted:
+        converted.pop("volume", None)
+    scales = SCALE_FIELDS.get(dataset) or {}
+    for field, factor in scales.items():
+        if field in converted:
+            converted[field] = _unscale(converted.get(field), factor)
+    if dataset == "stocks":
+        converted.pop("updated_at", None)
+    if dataset == "popularity":
+        # keep hub source; callers filter ths/dc themselves when needed
+        if converted.get("ts_name") and not converted.get("name"):
+            converted["name"] = converted.get("ts_name")
+    if dataset == "dragon_tiger":
+        if converted.get("ts_name") and not converted.get("name"):
+            converted["name"] = converted.get("ts_name")
+    if dataset == "sector_daily":
+        if converted.get("pct_change") is not None and converted.get("pct_chg") is None:
+            converted["pct_chg"] = converted.get("pct_change")
+    return converted
+
+
+def to_canonical_row(dataset: str, row: dict[str, Any]) -> dict[str, Any]:
+    if dataset == "calendar":
+        is_open = row.get("is_open")
+        return {
+            "exchange": str(row.get("exchange") or "SSE"),
+            "cal_date": yyyymmdd(row.get("cal_date")),
+            "is_open": 1 if is_open in (True, 1, "1", "Y", "y") else 0,
+            "pretrade_date": yyyymmdd(row.get("pretrade_date")) or None,
+        }
+    converted = dict(row)
+    if "volume" in converted and "vol" not in converted:
+        converted["vol"] = converted.pop("volume")
+    scales = SCALE_FIELDS.get(dataset) or {}
+    for field, factor in scales.items():
+        if field in converted:
+            converted[field] = _scale(converted.get(field), factor)
+    return converted
+
+
+def row_key(dataset: str, row: dict[str, Any]) -> tuple[str, ...]:
+    if dataset == "calendar":
+        return (yyyymmdd(row.get("cal_date")),)
+    if dataset == "stocks":
+        return (str(row.get("ts_code") or "").upper(),)
+    if dataset == "status":
+        return (str(row.get("dataset") or ""), yyyymmdd(row.get("trade_date")))
+    if dataset == "limit_events":
+        return (
+            str(row.get("ts_code") or "").upper(),
+            yyyymmdd(row.get("trade_date")),
+            str(row.get("limit_type") or ""),
+        )
+    if dataset == "popularity":
+        return (
+            str(row.get("ts_code") or "").upper(),
+            yyyymmdd(row.get("trade_date")),
+            str(row.get("source") or ""),
+        )
+    if dataset == "dragon_tiger":
+        return (
+            str(row.get("ts_code") or "").upper(),
+            yyyymmdd(row.get("trade_date")),
+            str(row.get("hm_name") or ""),
+        )
+    if dataset == "sector_daily":
+        return (
+            str(row.get("ts_code") or "").upper(),
+            yyyymmdd(row.get("trade_date")),
+            str(row.get("family") or ""),
+        )
+    return (str(row.get("ts_code") or "").upper(), yyyymmdd(row.get("trade_date")))
+
+
+def project_fields(rows: list[dict[str, Any]], fields: str) -> list[dict[str, Any]]:
+    keys = [item.strip() for item in str(fields or "").split(",") if item.strip()]
+    if not keys:
+        return rows
+    return [{key: row.get(key) for key in keys} for row in rows]
+
+
+def filter_stock_rows(rows: list[dict[str, Any]], params: dict[str, Any] | None) -> list[dict[str, Any]]:
+    payload = params or {}
+    ts_code = str(payload.get("ts_code") or "").strip().upper()
+    status = str(payload.get("list_status") or "").strip()
+    name = str(payload.get("name") or "").strip()
+    filtered = rows
+    if ts_code:
+        filtered = [row for row in filtered if str(row.get("ts_code") or "").upper() == ts_code]
+    if status:
+        filtered = [row for row in filtered if str(row.get("list_status") or status) == status]
+    if name:
+        filtered = [row for row in filtered if name.casefold() in str(row.get("name") or "").casefold()]
+    return filtered
+
+
+def filter_calendar_rows(rows: list[dict[str, Any]], params: dict[str, Any] | None) -> list[dict[str, Any]]:
+    payload = params or {}
+    if payload.get("is_open") in (1, "1", True):
+        return [row for row in rows if int(row.get("is_open") or 0) == 1]
+    if payload.get("is_open") in (0, "0", False):
+        return [row for row in rows if int(row.get("is_open") or 0) == 0]
+    return rows
+
+
+def _scale(value: Any, factor: float) -> float | None:
+    number = _optional_number(value)
+    if number is None:
+        return None
+    return number * factor
+
+
+def _unscale(value: Any, factor: float) -> float | None:
+    number = _optional_number(value)
+    if number is None or factor == 0:
+        return None
+    return number / factor
+
+
+def _optional_number(value: Any) -> float | None:
+    if value in (None, ""):
+        return None
+    number = finite_number(value, default=float("nan"))
+    if number != number:
+        return None
+    return number

backend/data/datahub/redact.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+SECRET_HINTS = (
+    "token",
+    "password",
+    "secret",
+    "key",
+    "authorization",
+    "credential",
+    "cookie",
+)
+
+
+def redact_value(value: Any, key: str = "", secrets: tuple[str, ...] = ()) -> Any:
+    lowered = key.lower()
+    if any(part in lowered for part in SECRET_HINTS):
+        return "***"
+    if isinstance(value, dict):
+        return {
+            str(item_key): redact_value(item_value, str(item_key), secrets)
+            for item_key, item_value in value.items()
+        }
+    if isinstance(value, list):
+        return [redact_value(item, key, secrets) for item in value]
+    text = str(value) if value is not None and not isinstance(value, (int, float, bool)) else value
+    if isinstance(text, str):
+        return redact_text(text, secrets)
+    return value
+
+
+def redact_text(text: str, secrets: tuple[str, ...] = ()) -> str:
+    redacted = text
+    for secret in secrets:
+        if secret:
+            redacted = redacted.replace(secret, "***")
+    return redacted

backend/data/datahub/route_state.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from datetime import datetime
+from threading import Lock
+from typing import Any
+
+from backend.data.datahub.settings import DATASETS
+
+DATASET_LABELS = {
+    "calendar": "交易日历",
+    "stocks": "股票主档",
+    "daily": "个股日K",
+    "index_daily": "指数日K",
+    "valuation": "估值",
+    "moneyflow": "资金流",
+    "auction": "竞价",
+    "limit_events": "涨停池",
+    "popularity": "人气榜",
+    "dragon_tiger": "龙虎榜",
+    "sector_daily": "题材板块",
+    "quotes": "全市场实时行情",
+    "index_quotes": "指数实时行情",
+    "intraday": "分时",
+    "status": "数据集状态",
+}
+
+
+class DatahubRouteLedger:
+    def __init__(self) -> None:
+        self._lock = Lock()
+        self._rows: dict[str, dict[str, Any]] = {}
+
+    def record(self, dataset: str, route: str, source: str = "", error: str = "") -> None:
+        name = str(dataset or "").strip() or "unknown"
+        with self._lock:
+            self._rows[name] = {
+                "dataset": name,
+                "label": DATASET_LABELS.get(name, name),
+                "route": "legacy" if route == "legacy" else "datahub",
+                "source": str(source or "").strip(),
+                "error": str(error or "").strip(),
+                "at": datetime.now().astimezone().isoformat(timespec="seconds"),
+            }
+
+    def snapshot(self) -> list[dict[str, Any]]:
+        with self._lock:
+            rows = [dict(item) for item in self._rows.values()]
+        order = {name: index for index, name in enumerate(DATASETS)}
+        rows.sort(key=lambda item: (order.get(str(item.get("dataset")), 99), str(item.get("dataset"))))
+        return rows
+
+    def clear(self) -> None:
+        with self._lock:
+            self._rows.clear()
+
+
+LEDGER = DatahubRouteLedger()

backend/data/datahub/settings.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+from backend.bootstrap.config import APP_DIR
+
+
+DATASETS = (
+    "calendar",
+    "stocks",
+    "daily",
+    "index_daily",
+    "valuation",
+    "moneyflow",
+    "auction",
+    "limit_events",
+    "popularity",
+    "dragon_tiger",
+    "sector_daily",
+    "quotes",
+    "index_quotes",
+    "intraday",
+    "status",
+)
+
+ENV_DATASET = {
+    "calendar": "CALENDAR",
+    "stocks": "STOCKS",
+    "daily": "DAILY",
+    "index_daily": "INDEX_DAILY",
+    "valuation": "VALUATION",
+    "moneyflow": "MONEYFLOW",
+    "auction": "AUCTION",
+    "limit_events": "LIMIT_EVENTS",
+    "popularity": "POPULARITY",
+    "dragon_tiger": "DRAGON_TIGER",
+    "sector_daily": "SECTOR_DAILY",
+    "quotes": "QUOTES",
+    "index_quotes": "INDEX_QUOTES",
+    "intraday": "INTRADAY",
+    "status": "STATUS",
+}
+
+DEFAULT_CONFIG_PATH = APP_DIR / "config" / "datahub.config.json"
+
+
+def _truthy(value: Any) -> bool:
+    return str(value or "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _int(value: Any, default: int) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+@dataclass(frozen=True)
+class DatasetFlags:
+    name: str
+    read: bool = False
+    shadow: bool = False
+
+
+@dataclass(frozen=True)
+class DatahubSettings:
+    base_url: str
+    token: str
+    timeout_seconds: int = 8
+    retries: int = 1
+    page_limit: int = 5000
+    stale_seconds_max: int = 86400
+    datasets: dict[str, DatasetFlags] | None = None
+
+    def flags(self, dataset: str) -> DatasetFlags:
+        mapped = self.datasets or {}
+        return mapped.get(dataset) or DatasetFlags(dataset)
+
+    def any_enabled(self) -> bool:
+        return any(item.read or item.shadow for item in (self.datasets or {}).values())
+
+    def secrets(self) -> tuple[str, ...]:
+        return tuple(item for item in (self.token,) if item)
+
+    @classmethod
+    def load(
+        cls,
+        path: Path | None = None,
+        environ: Mapping[str, str] | None = None,
+        credentials: Mapping[str, object] | None = None,
+    ) -> "DatahubSettings":
+        config_path = path or DEFAULT_CONFIG_PATH
+        payload: dict[str, Any] = {}
+        if config_path.is_file():
+            payload = json.loads(config_path.read_text(encoding="utf-8"))
+        env = dict(os.environ if environ is None else environ)
+        creds = dict(credentials or {})
+        dataset_flags: dict[str, DatasetFlags] = {}
+        raw_datasets = payload.get("datasets") or {}
+        for name in DATASETS:
+            item = raw_datasets.get(name) or {}
+            env_key = ENV_DATASET[name]
+            read = _truthy(env.get(f"DATAHUB_READ_{env_key}")) if f"DATAHUB_READ_{env_key}" in env else bool(item.get("read"))
+            shadow = (
+                _truthy(env.get(f"DATAHUB_SHADOW_{env_key}"))
+                if f"DATAHUB_SHADOW_{env_key}" in env
+                else bool(item.get("shadow"))
+            )
+            dataset_flags[name] = DatasetFlags(name, read=read, shadow=shadow)
+        token = str(
+            env.get("DATAHUB_TOKEN")
+            or creds.get("datahub_token")
+            or payload.get("token")
+            or ""
+        ).strip()
+        base_url = str(
+            env.get("DATAHUB_BASE_URL")
+            or creds.get("datahub_base_url")
+            or payload.get("base_url")
+            or "http://127.0.0.1:8766"
+        ).strip().rstrip("/")
+        return cls(
+            base_url=base_url,
+            token=token,
+            timeout_seconds=_int(env.get("DATAHUB_TIMEOUT") or payload.get("timeout_seconds"), 8),
+            retries=max(0, _int(env.get("DATAHUB_RETRIES") or payload.get("retries"), 1)),
+            page_limit=max(1, _int(payload.get("page_limit"), 5000)),
+            stale_seconds_max=max(0, _int(payload.get("stale_seconds_max"), 86400)),
+            datasets=dataset_flags,
+        )

backend/data/gateway.py

@@ -3,8 +3,10 @@ from __future__ import annotations
 from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import datetime
+from typing import Any
 
 from backend.data.contracts import DataUsage
+from backend.data.datahub import DatahubAwareTushareClient, DatahubBridge, DatahubClient, DatahubSettings
 from backend.data.policy import DataSourcePolicy
 from backend.data.providers import IfindProvider, TushareProvider
 from backend.data.quality import DataQualityGate, QualityEvidence, QualityReport
@@ -22,6 +24,7 @@ class DataGateway:
     ifind_provider: IfindProvider
     chart_data: MarketChartClient
     realtime_observer: WebRealtimeAggregator
+    datahub: DatahubBridge
 
     @property
     def ifind(self) -> IfindHttpClient:
@@ -34,7 +37,40 @@ class DataGateway:
     ) -> TushareClient:
         if dataset_id:
             self.policy.assert_allowed(dataset_id, "tushare", usage)
-        return self.tushare_provider.client()
+        legacy = self.tushare_provider.client()
+        legacy.realtime_aggregator = self.realtime_observer
+        return DatahubAwareTushareClient(legacy, self.datahub)
+
+    def dataset_status(self, trade_date: str) -> list[dict[str, Any]] | None:
+        return self.datahub.dataset_status(trade_date)
+
+    def batches(self, trade_date: str, dataset: str = "") -> list[dict[str, Any]] | None:
+        return self.datahub.batches(trade_date, dataset)
+
+    def datahub_status(self) -> dict[str, Any]:
+        from backend.data.datahub.route_state import DATASET_LABELS, LEDGER
+        from backend.data.datahub.settings import DATASETS
+
+        settings = self.datahub.settings
+        flags = []
+        enabled = 0
+        for name in DATASETS:
+            read = bool(settings.flags(name).read)
+            if read:
+                enabled += 1
+            flags.append({"dataset": name, "label": DATASET_LABELS.get(name, name), "read": read})
+        routes = LEDGER.snapshot()
+        fallbacks = [item for item in routes if item.get("route") == "legacy"]
+        return {
+            "configured": bool(settings.token and settings.base_url),
+            "base_url": settings.base_url,
+            "enabled_reads": enabled,
+            "total_reads": len(DATASETS),
+            "flags": flags,
+            "routes": routes,
+            "fallback_count": len(fallbacks),
+            "fallback_labels": [str(item.get("label") or item.get("dataset")) for item in fallbacks],
+        }
 
     def assert_source(self, dataset_id: str, provider_id: str, usage: DataUsage) -> None:
         self.policy.assert_allowed(dataset_id, provider_id, usage)
@@ -64,6 +100,7 @@ class DataGateway:
 def build_data_gateway(
     credentials: dict[str, object],
     tushare_token_supplier: Callable[[], str] | None = None,
+    datahub_settings: DatahubSettings | None = None,
 ) -> DataGateway:
     ifind = IfindHttpClient(
         str(credentials.get("ifind_refresh_token") or ""),
@@ -73,11 +110,15 @@ def build_data_gateway(
         lambda: str(credentials.get("tushare_token") or "")
     )
     policy = DataSourcePolicy.load()
+    settings = datahub_settings or DatahubSettings.load(credentials=credentials)
+    datahub_client = DatahubClient(settings)
+    datahub = DatahubBridge(settings, datahub_client)
     return DataGateway(
         policy=policy,
         quality=DataQualityGate.load(policy),
         tushare_provider=TushareProvider(token_supplier),
         ifind_provider=IfindProvider(ifind),
-        chart_data=MarketChartClient(ifind, EastmoneyChartClient()),
+        chart_data=MarketChartClient(ifind, EastmoneyChartClient(), datahub),
         realtime_observer=WebRealtimeAggregator(),
+        datahub=datahub,
     )

backend/data/providers/tushare_daily.py

@@ -3,7 +3,11 @@ from __future__ import annotations
 from typing import Any
 
 from backend.data.numbers import finite_number as _number
-from backend.data.providers.tushare_helpers import _display_time, _prices_equal
+from backend.data.providers.tushare_helpers import (
+    _display_time,
+    _prices_equal,
+    calendar_is_open,
+)
 
 
 class DailyMarketMixin:
@@ -17,7 +21,11 @@ class DailyMarketMixin:
             trade_date = requested
         else:
             row = requested_rows[0]
-            trade_date = row["cal_date"] if row.get("is_open") == 1 else row.get("pretrade_date", requested)
+            trade_date = (
+                row["cal_date"]
+                if calendar_is_open(row.get("is_open"))
+                else row.get("pretrade_date", requested)
+            )
 
         resolved_rows = self.query(
             "trade_cal",

backend/data/providers/tushare_dashboard.py

@@ -16,6 +16,12 @@ from backend.data.providers.tushare_transport import TushareError
 
 
 class DashboardMixin:
+    def _now(self) -> datetime:
+        clock = getattr(self, "clock", None)
+        if callable(clock):
+            return clock()
+        return datetime.now().astimezone()
+
     def dashboard(self, requested_date: str) -> dict[str, Any]:
         trade_date, previous_trade_date = self.resolve_trade_context(requested_date)
         if self.should_use_realtime(requested_date, trade_date):
@@ -26,11 +32,12 @@ class DashboardMixin:
             )
 
         daily = self._load_daily(trade_date)
+        now = self._now()
         if (
             not daily
-            and requested_date == datetime.now().astimezone().strftime("%Y%m%d")
+            and requested_date == now.strftime("%Y%m%d")
             and trade_date == requested_date
-            and datetime.now().astimezone().time().replace(tzinfo=None) >= dt_time(9, 15)
+            and now.time().replace(tzinfo=None) >= dt_time(9, 15)
         ):
             return self._realtime_dashboard(
                 requested_date,
@@ -98,15 +105,14 @@ class DashboardMixin:
         }
         return apply_sentiment_to_dashboard(dashboard)
 
-    @staticmethod
+    def should_use_realtime(self, requested_date: str, trade_date: str) -> bool:
-    def should_use_realtime(requested_date: str, trade_date: str) -> bool:
+        """Use live quotes for today's open session until official daily settles."""
-        """Use rt_k for today's open market until end-of-day datasets settle."""
+        now = self._now()
-        now = datetime.now().astimezone()
         today = now.strftime("%Y%m%d")
         return (
             requested_date == today
             and trade_date == today
-            and dt_time(9, 15) <= now.time().replace(tzinfo=None) < dt_time(16, 30)
+            and dt_time(9, 15) <= now.time().replace(tzinfo=None) < dt_time(15, 5)
         )
 
     def _realtime_dashboard(
@@ -122,7 +128,7 @@ class DashboardMixin:
         )
         if not codes:
             raise TushareError("No active stock codes available for rt_k")
-        quotes = self.query("rt_k", {"ts_code": codes})
+        quotes, quote_source = self._load_realtime_quotes(codes, trade_date)
         if not quotes:
             raise TushareError(f"No realtime data returned for {trade_date}")
 
@@ -178,14 +184,35 @@ class DashboardMixin:
         )
         sectors = _build_sectors(limits)
         previous_sectors = _build_sectors(previous_limits)
-        now = datetime.now().astimezone()
+        now = self._now()
         market_status = _realtime_market_status(now.time().replace(tzinfo=None))
+        if quote_source == "datahub":
+            notice = (
+                "盘中行情由数据中枢统一提供；涨停原因、封板时间和开板次数以盘后榜单校正为准。"
+            )
+            source_name = "datahub"
+        elif quote_source == "eastmoney_clist":
+            notice = (
+                "盘中行情由东财免费实时快照计算；涨停原因、封板时间和开板次数以盘后榜单校正为准。"
+            )
+            source_name = "eastmoney"
+        elif quote_source == "tencent_qt":
+            notice = (
+                "盘中行情由腾讯免费实时行情计算；涨停原因、封板时间和开板次数以盘后榜单校正为准。"
+            )
+            source_name = "tencent"
+        else:
+            notice = (
+                "盘中行情由 Tushare rt_k 实时计算；涨停原因、封板时间和开板次数以盘后榜单校正为准。"
+            )
+            source_name = "tushare"
         dashboard = {
             "meta": {
                 "requested_date": _display_date(requested_date),
                 "trade_date": _display_date(trade_date),
                 "previous_trade_date": _display_date(previous_trade_date),
-                "source": "tushare",
+                "source": source_name,
+                "quote_source": quote_source,
                 "mode": "realtime",
                 "realtime": True,
                 "market_status": market_status,
@@ -193,7 +220,8 @@ class DashboardMixin:
                 "auto_refresh": False,
                 "quote_count": len(daily),
                 "updated_at": now.isoformat(timespec="seconds"),
-                "notice": "盘中行情由 Tushare rt_k 实时计算；涨停原因、封板时间和开板次数以盘后榜单校正为准。",
+                "notice": notice,
+                "indices": self._free_realtime_indices() if quote_source != "tushare_rt_k" else [],
             },
             "overview": _build_overview(daily, up_rows, down_rows, broken_rows),
             "limits": limits,
@@ -207,6 +235,89 @@ class DashboardMixin:
         }
         return apply_sentiment_to_dashboard(dashboard)
 
+    def _realtime_aggregator(self):
+        aggregator = getattr(self, "realtime_aggregator", None)
+        if aggregator is None:
+            raise TushareError("免费实时源未配置")
+        return aggregator
+
+    def _load_realtime_quotes(
+        self,
+        codes: str,
+        trade_date: str,
+    ) -> tuple[list[dict[str, Any]], str]:
+        hub = getattr(self, "try_market_quotes", None)
+        if callable(hub):
+            quotes = hub(trade_date)
+            if quotes:
+                return list(quotes), "datahub"
+        rt_error = ""
+        try:
+            quotes = self.query("rt_k", {"ts_code": codes})
+            if quotes:
+                self._mark_quote_legacy("tushare_rt_k", rt_error)
+                return list(quotes), "tushare_rt_k"
+            rt_error = f"No realtime data returned for {trade_date}"
+        except TushareError as exc:
+            rt_error = str(exc)
+        try:
+            quotes, quote_source = self._free_realtime_quotes(trade_date, codes)
+        except Exception as exc:
+            raise TushareError(
+                f"当天盘中实时行情不可用：rt_k={rt_error}；免费源={exc}"
+            ) from exc
+        if not quotes:
+            raise TushareError(
+                f"当天盘中实时行情不可用：rt_k={rt_error}；免费源=empty"
+            )
+        self._mark_quote_legacy(quote_source, rt_error)
+        return quotes, quote_source
+
+    def _mark_quote_legacy(self, source: str, error: str = "") -> None:
+        marker = getattr(self, "record_datahub_legacy", None)
+        if callable(marker):
+            marker("quotes", source, error)
+
+    def _free_realtime_quotes(
+        self,
+        trade_date: str,
+        codes: str = "",
+    ) -> tuple[list[dict[str, Any]], str]:
+        aggregator = self._realtime_aggregator()
+        last_error = ""
+        try:
+            quotes = aggregator.eastmoney_market_quotes(expected_date=trade_date)
+            if quotes:
+                return quotes, "eastmoney_clist"
+        except Exception as exc:
+            last_error = str(exc)
+        code_list = [item for item in str(codes or "").split(",") if item]
+        try:
+            quotes = aggregator.tencent_market_quotes(code_list, expected_date=trade_date)
+        except Exception as exc:
+            raise TushareError(
+                f"eastmoney={last_error or 'empty'}；tencent={exc}"
+            ) from exc
+        if not quotes:
+            raise TushareError(f"eastmoney={last_error or 'empty'}；tencent=empty")
+        return quotes, "tencent_qt"
+
+    def _free_realtime_indices(self) -> list[dict[str, Any]]:
+        hub = getattr(self, "try_index_quotes", None)
+        if callable(hub):
+            rows = hub()
+            converted = [item for item in (_hub_index_quote(row) for row in rows or []) if item]
+            if converted:
+                return converted
+        try:
+            rows = self._realtime_aggregator().eastmoney_indices()
+            marker = getattr(self, "record_datahub_legacy", None)
+            if callable(marker):
+                marker("index_quotes", "eastmoney_push2")
+            return rows
+        except Exception:
+            return []
+
     def _load_realtime_reference(
         self,
         trade_date: str,
@@ -234,7 +345,7 @@ class DashboardMixin:
             {"trade_date": previous_trade_date},
             "ts_code,trade_date,total_share,float_share,free_share,total_mv,circ_mv",
         )
-        if not basic_rows or not price_limits:
+        if not basic_rows:
             raise TushareError(f"Realtime reference data is incomplete for {trade_date}")
         result = {
             "basic_rows": basic_rows,
@@ -608,6 +719,31 @@ def _build_yesterday_performance(
     return result
 
 
+def _hub_index_quote(row: dict[str, Any]) -> dict[str, Any] | None:
+    ts_code = str(row.get("ts_code") or "")
+    code = str(row.get("code") or ts_code.split(".")[0])
+    close = _number(row.get("price") if row.get("price") not in (None, "") else row.get("close"))
+    previous = _number(
+        row.get("previous_close") if row.get("previous_close") not in (None, "") else row.get("pre_close")
+    )
+    if close <= 0 or previous <= 0:
+        return None
+    amount = _number(row.get("amount"))
+    amount_billion = _number(row.get("amount_billion"))
+    if not amount_billion and amount:
+        amount_billion = round(amount / 100_000_000, 2)
+    return {
+        "code": code,
+        "name": str(row.get("name") or code),
+        "price": close,
+        "change": _number(row.get("pct_chg") if row.get("pct_chg") not in (None, "") else row.get("change")),
+        "previous_close": previous,
+        "amount_billion": amount_billion,
+        "quote_time": str(row.get("quote_time") or ""),
+        "source": "datahub",
+    }
+
+
 def _build_limit_performance(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
     result = []
     for level in sorted({int(row.get("prior_streak") or 1) for row in rows}, reverse=True):

backend/data/providers/tushare_helpers.py

@@ -6,6 +6,17 @@ from typing import Any
 from backend.data.numbers import finite_number as _number
 
 
+def calendar_is_open(value: Any) -> bool:
+    if value in (True, 1, "1", "Y", "y"):
+        return True
+    if value in (False, 0, "0", "N", "n", None, ""):
+        return False
+    try:
+        return int(value) == 1
+    except (TypeError, ValueError):
+        return False
+
+
 def _text(value: Any) -> str:
     if isinstance(value, (list, tuple, set)):
         return "、".join(str(item).strip() for item in value if str(item).strip())

backend/data/providers/tushare_indices.py

@@ -59,6 +59,87 @@ class IndexMixin:
         }
 
     def realtime_market_indices(self, requested_date: str) -> dict[str, Any]:
+        hub = getattr(self, "try_index_quotes", None)
+        if callable(hub):
+            rows = hub()
+            if rows:
+                try:
+                    return self._hub_realtime_market_indices(requested_date, rows)
+                except TushareError:
+                    pass
+        try:
+            payload = self._tushare_realtime_market_indices(requested_date)
+            marker = getattr(self, "record_datahub_legacy", None)
+            if callable(marker):
+                marker("index_quotes", "tushare_rt_idx_k")
+            return payload
+        except TushareError:
+            payload = self._free_realtime_market_indices(requested_date)
+            marker = getattr(self, "record_datahub_legacy", None)
+            if callable(marker):
+                marker("index_quotes", str(payload.get("source") or "eastmoney_push2"))
+            return payload
+
+    def _hub_realtime_market_indices(
+        self,
+        requested_date: str,
+        rows: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        trade_date, _ = self.resolve_trade_context(requested_date)
+        index_names = {
+            "000001.SH": "上证指数",
+            "399001.SZ": "深证成指",
+            "399006.SZ": "创业板指",
+        }
+        by_code = {str(row.get("ts_code") or ""): row for row in rows}
+        by_symbol = {str(row.get("code") or ""): row for row in rows}
+        indices = []
+        for ts_code, name in index_names.items():
+            row = by_code.get(ts_code) or by_symbol.get(ts_code.split(".")[0])
+            if not row:
+                continue
+            close = _number(row.get("price") if row.get("price") not in (None, "") else row.get("close"))
+            previous_close = _number(
+                row.get("previous_close") if row.get("previous_close") not in (None, "") else row.get("pre_close")
+            )
+            if close <= 0 or previous_close <= 0:
+                continue
+            amount = _number(row.get("amount"))
+            amount_billion = _number(row.get("amount_billion"))
+            if not amount_billion and amount:
+                amount_billion = round(amount / 100_000_000, 2)
+            indices.append(
+                {
+                    "ts_code": ts_code,
+                    "name": str(row.get("name") or name).strip(),
+                    "trade_date": trade_date,
+                    "close": close,
+                    "pct_chg": round(
+                        _number(row.get("pct_chg")) or (close / previous_close - 1) * 100,
+                        3,
+                    ),
+                    "return_5d": 0,
+                    "amount_billion": amount_billion,
+                    "quote_time": str(row.get("quote_time") or ""),
+                    "source": "datahub",
+                }
+            )
+        if len(indices) != 3:
+            raise TushareError("Realtime index quotes are incomplete")
+        return {
+            "trade_date": trade_date,
+            "source": "datahub",
+            "realtime": True,
+            "precise": True,
+            "indices": indices,
+            "aggregate": {
+                "average_pct_chg": round(sum(item["pct_chg"] for item in indices) / len(indices), 3),
+                "average_return_5d": 0,
+                "average_return_20d": 0,
+            },
+        }
+
+    def _tushare_realtime_market_indices(self, requested_date: str) -> dict[str, Any]:
         trade_date, _ = self.resolve_trade_context(requested_date)
         index_names = {
             "000001.SH": "上证指数",
@@ -116,3 +197,52 @@ class IndexMixin:
                 "average_return_20d": 0,
             },
         }
+
+    def _free_realtime_market_indices(self, requested_date: str) -> dict[str, Any]:
+        trade_date, _ = self.resolve_trade_context(requested_date)
+        aggregator = getattr(self, "realtime_aggregator", None)
+        if aggregator is None:
+            raise TushareError("免费实时源未配置")
+        quotes = aggregator.eastmoney_indices()
+        index_names = {
+            "000001": ("000001.SH", "上证指数"),
+            "399001": ("399001.SZ", "深证成指"),
+            "399006": ("399006.SZ", "创业板指"),
+        }
+        indices = []
+        for quote in quotes:
+            mapped = index_names.get(str(quote.get("code") or ""))
+            if not mapped:
+                continue
+            ts_code, name = mapped
+            close = _number(quote.get("price"))
+            previous_close = _number(quote.get("previous_close"))
+            if close <= 0 or previous_close <= 0:
+                continue
+            indices.append(
+                {
+                    "ts_code": ts_code,
+                    "name": str(quote.get("name") or name).strip(),
+                    "trade_date": trade_date,
+                    "close": close,
+                    "pct_chg": round(_number(quote.get("change")) or (close / previous_close - 1) * 100, 3),
+                    "return_5d": 0,
+                    "amount_billion": round(_number(quote.get("amount_billion")), 2),
+                    "quote_time": quote.get("quote_time") or "",
+                    "source": quote.get("source") or "eastmoney_push2",
+                }
+            )
+        if len(indices) != 3:
+            raise TushareError("Realtime index quotes are incomplete")
+        return {
+            "trade_date": trade_date,
+            "source": "eastmoney_push2",
+            "realtime": True,
+            "precise": True,
+            "indices": indices,
+            "aggregate": {
+                "average_pct_chg": round(sum(item["pct_chg"] for item in indices) / len(indices), 3),
+                "average_return_5d": 0,
+                "average_return_20d": 0,
+            },
+        }

backend/data/realtime.py

@@ -19,8 +19,20 @@ class RealtimeAggregateError(RuntimeError):
 
 
 EASTMONEY_INDEX_URL = "https://push2.eastmoney.com/api/qt/ulist.np/get"
+EASTMONEY_STOCK_URL = "https://push2.eastmoney.com/api/qt/stock/get"
+EASTMONEY_STOCK_FIELDS = "f43,f44,f45,f46,f47,f48,f57,f58,f60,f86,f168"
 EASTMONEY_SECTOR_URL = "https://push2.eastmoney.com/api/qt/clist/get"
+EASTMONEY_A_SHARE_BOARDS = (
+    "m:0+t:6",
+    "m:0+t:80",
+    "m:1+t:2",
+    "m:1+t:23",
+    "m:0+t:81",
+)
+EASTMONEY_QUOTE_FIELDS = "f12,f13,f14,f2,f3,f4,f5,f6,f15,f16,f17,f18,f8,f124"
+EASTMONEY_MARKET_PAGE_SIZE = 100
 TENCENT_INDEX_URL = "https://qt.gtimg.cn/q=sh000001,sz399001,sz399006"
+TENCENT_QUOTE_URL = "https://qt.gtimg.cn/q="
 THS_LIMIT_URL = "https://data.10jqka.com.cn/dataapi/limit_up/limit_up_pool"
 XGB_POOL_URL = "https://flash-api.xuangubao.cn/api/pool/detail"
 BROWSER_USER_AGENT = (
@@ -134,6 +146,181 @@ class WebRealtimeAggregator:
             raise RealtimeAggregateError(f"Eastmoney returned {len(result)}/3 indices")
         return result
 
+    def eastmoney_market_quotes(self, expected_date: str = "") -> list[dict[str, Any]]:
+        """Full A-share snapshot via Eastmoney clist, used when Tushare rt_k is unavailable."""
+        now = time.time()
+        cache_key = "assembled:eastmoney_market"
+        with self._response_cache_lock:
+            cached = self._response_cache.get(cache_key)
+        cache_age = now - float((cached or {}).get("created_at") or 0)
+        if cached and cache_age <= min(20, self.response_cache_ttl_seconds):
+            quotes = list(cached.get("payload") or [])
+            return self._filter_quotes_by_date(quotes, expected_date)
+
+        rows: list[dict[str, Any]] = []
+        board_errors: list[str] = []
+        for board in EASTMONEY_A_SHARE_BOARDS:
+            try:
+                rows.extend(self._eastmoney_board_quotes(board))
+            except Exception as exc:
+                board_errors.append(f"{board}:{exc}")
+        quotes = []
+        seen: set[str] = set()
+        for row in rows:
+            quote = _normalize_eastmoney_quote(row)
+            ts_code = str((quote or {}).get("ts_code") or "")
+            if not quote or ts_code in seen:
+                continue
+            seen.add(ts_code)
+            quotes.append(quote)
+        if len(quotes) < 200:
+            detail = f"；{'; '.join(board_errors)}" if board_errors else ""
+            raise RealtimeAggregateError(
+                f"Eastmoney market snapshot too small: {len(quotes)}{detail}"
+            )
+        quotes = self._filter_quotes_by_date(quotes, expected_date)
+        with self._response_cache_lock:
+            self._response_cache[cache_key] = {"created_at": now, "payload": quotes}
+        return quotes
+
+    def _eastmoney_board_quotes(self, board: str) -> list[dict[str, Any]]:
+        first = self._eastmoney_market_page(board, 1)
+        data = first.get("data") or {}
+        rows = _diff_rows(data)
+        total = int(_number(data.get("total")))
+        page_count = 1
+        if total > 0:
+            page_count = max(1, (total + EASTMONEY_MARKET_PAGE_SIZE - 1) // EASTMONEY_MARKET_PAGE_SIZE)
+        for page in range(2, min(page_count, 40) + 1):
+            payload = self._eastmoney_market_page(board, page)
+            rows.extend(_diff_rows(payload.get("data") or {}))
+        return rows
+
+    def _eastmoney_market_page(self, board: str, page: int) -> dict[str, Any]:
+        return self._get_json(
+            EASTMONEY_SECTOR_URL,
+            {
+                "pn": str(page),
+                "pz": str(EASTMONEY_MARKET_PAGE_SIZE),
+                "po": "1",
+                "np": "1",
+                "fltt": "2",
+                "invt": "2",
+                "fid": "f12",
+                "fs": board,
+                "fields": EASTMONEY_QUOTE_FIELDS,
+            },
+            referer="https://quote.eastmoney.com/center/gridlist.html",
+        )
+
+    def _filter_quotes_by_date(
+        self,
+        quotes: list[dict[str, Any]],
+        expected_date: str,
+    ) -> list[dict[str, Any]]:
+        want = str(expected_date or "").replace("-", "")
+        if not want or not quotes:
+            return quotes
+        dated = [item for item in quotes if str(item.get("quote_date") or "") == want]
+        if dated and len(dated) >= max(100, int(len(quotes) * 0.2)):
+            return dated
+        if dated:
+            return dated
+        if all(not item.get("quote_date") for item in quotes):
+            return quotes
+        raise RealtimeAggregateError(f"Eastmoney quotes are not for {want}")
+
+    def tencent_market_quotes(
+        self,
+        codes: list[str],
+        expected_date: str = "",
+    ) -> list[dict[str, Any]]:
+        symbols: list[str] = []
+        seen: set[str] = set()
+        for raw in codes:
+            ts = str(raw or "").strip().upper()
+            if not ts:
+                continue
+            symbol = ts.split(".")[0]
+            if not symbol.isdigit() or len(symbol) != 6 or symbol in seen:
+                continue
+            seen.add(symbol)
+            if ts.endswith(".SH") or symbol.startswith(("5", "6", "9")):
+                symbols.append(f"sh{symbol}")
+            elif ts.endswith(".BJ") or symbol.startswith(("4", "8")):
+                symbols.append(f"bj{symbol}")
+            else:
+                symbols.append(f"sz{symbol}")
+        if not symbols:
+            raise RealtimeAggregateError("No stock codes available for Tencent quotes")
+
+        quotes: list[dict[str, Any]] = []
+        batch_size = 80
+
+        def load_batch(batch: list[str]) -> list[dict[str, Any]]:
+            raw, _cache_age = self._get_text(
+                f"{TENCENT_QUOTE_URL}{','.join(batch)}",
+                referer="https://gu.qq.com/",
+                encoding="gb18030",
+            )
+            return [
+                quote
+                for line in raw.splitlines()
+                if (quote := _parse_tencent_stock_quote(line))
+            ]
+
+        batches = [symbols[index:index + batch_size] for index in range(0, len(symbols), batch_size)]
+        errors: list[str] = []
+        with ThreadPoolExecutor(max_workers=4) as executor:
+            for result in executor.map(self._capture, [lambda batch=batch: load_batch(batch) for batch in batches]):
+                rows, status = result
+                if status.get("ok") and rows:
+                    quotes.extend(rows)
+                elif not status.get("ok"):
+                    errors.append(str(status.get("error") or "batch failed"))
+        if len(quotes) < 200:
+            detail = f"；{'; '.join(errors[:3])}" if errors else ""
+            raise RealtimeAggregateError(
+                f"Tencent market snapshot too small: {len(quotes)}{detail}"
+            )
+        return self._filter_quotes_by_date(quotes, expected_date)
+
+    def tencent_stock_quote(self, code: str, expected_date: str = "") -> dict[str, Any]:
+        symbol, _secid, ts_code = _a_share_identity(code)
+        raw, _cache_age = self._get_text(
+            f"{TENCENT_QUOTE_URL}{symbol}",
+            referer="https://gu.qq.com/",
+            encoding="gb18030",
+        )
+        quote = next(
+            (
+                item
+                for line in raw.splitlines()
+                if (item := _parse_tencent_stock_quote(line))
+            ),
+            None,
+        )
+        if not quote:
+            raise RealtimeAggregateError(f"Tencent stock quote unavailable for {ts_code}")
+        return _require_quote_date(quote, expected_date)
+
+    def eastmoney_stock_quote(self, code: str, expected_date: str = "") -> dict[str, Any]:
+        _symbol, secid, ts_code = _a_share_identity(code)
+        payload = self._get_json(
+            EASTMONEY_STOCK_URL,
+            {
+                "secid": secid,
+                "invt": "2",
+                "fltt": "2",
+                "fields": EASTMONEY_STOCK_FIELDS,
+            },
+            referer="https://quote.eastmoney.com/",
+        )
+        quote = _normalize_eastmoney_stock_quote(payload.get("data") or {}, ts_code)
+        if not quote:
+            raise RealtimeAggregateError(f"Eastmoney stock quote unavailable for {ts_code}")
+        return _require_quote_date(quote, expected_date)
+
     def tencent_indices(self) -> list[dict[str, Any]]:
         raw, cache_age = self._get_text(
             TENCENT_INDEX_URL,
@@ -397,6 +584,143 @@ class WebRealtimeAggregator:
         ) from last_error
 
 
+def _diff_rows(data: dict[str, Any]) -> list[dict[str, Any]]:
+    diff = data.get("diff") or []
+    if isinstance(diff, dict):
+        return [row for row in diff.values() if isinstance(row, dict)]
+    return [row for row in diff if isinstance(row, dict)]
+
+
+def _a_share_identity(code: str) -> tuple[str, str, str]:
+    raw = str(code or "").strip().upper()
+    symbol = raw.split(".")[0]
+    if not symbol.isdigit() or len(symbol) != 6:
+        raise RealtimeAggregateError("Invalid stock code")
+    if raw.endswith(".SH") or symbol.startswith(("5", "6", "9")):
+        return f"sh{symbol}", f"1.{symbol}", f"{symbol}.SH"
+    if raw.endswith(".BJ") or symbol.startswith(("4", "8")):
+        return f"bj{symbol}", f"0.{symbol}", f"{symbol}.BJ"
+    return f"sz{symbol}", f"0.{symbol}", f"{symbol}.SZ"
+
+
+def _require_quote_date(quote: dict[str, Any], expected_date: str) -> dict[str, Any]:
+    want = str(expected_date or "").replace("-", "")
+    got = str(quote.get("quote_date") or "")
+    if want and got != want:
+        raise RealtimeAggregateError(f"quote date {got or 'empty'} is not {want}")
+    return quote
+
+
+def _normalize_eastmoney_stock_quote(
+    row: dict[str, Any], ts_code: str
+) -> dict[str, Any] | None:
+    close = _number(row.get("f43"))
+    previous_close = _number(row.get("f60"))
+    if close <= 0 or previous_close <= 0:
+        return None
+    epoch = int(_number(row.get("f86")))
+    quote_date = ""
+    if epoch > 0:
+        quote_date = datetime.fromtimestamp(epoch).astimezone().strftime("%Y%m%d")
+    return {
+        "ts_code": ts_code,
+        "name": row.get("f58") or ts_code.split(".")[0],
+        "pre_close": previous_close,
+        "open": _number(row.get("f46")),
+        "high": _number(row.get("f44")),
+        "low": _number(row.get("f45")),
+        "close": close,
+        "vol": _number(row.get("f47")) * 100,
+        "amount": _number(row.get("f48")),
+        "num": 0,
+        "quote_date": quote_date,
+        "quote_time_epoch": epoch,
+        "turnover_rate": _number(row.get("f168")),
+        "source": "eastmoney_stock",
+    }
+
+
+def _parse_tencent_stock_quote(line: str) -> dict[str, Any] | None:
+    if '="' not in line:
+        return None
+    prefix, payload = line.split('="', 1)
+    fields = payload.rsplit('";', 1)[0].split("~")
+    if len(fields) < 38:
+        return None
+    symbol = fields[2]
+    if not symbol.isdigit() or len(symbol) != 6:
+        return None
+    close = _number(fields[3])
+    previous_close = _number(fields[4])
+    if close <= 0 or previous_close <= 0:
+        return None
+    marker = prefix.lower()
+    if "sh" in marker:
+        ts_code = f"{symbol}.SH"
+    elif "bj" in marker:
+        ts_code = f"{symbol}.BJ"
+    else:
+        ts_code = f"{symbol}.SZ"
+    try:
+        quote_time = datetime.strptime(fields[30], "%Y%m%d%H%M%S")
+        quote_date = quote_time.strftime("%Y%m%d")
+        epoch = int(quote_time.timestamp())
+    except ValueError:
+        quote_date = ""
+        epoch = 0
+    return {
+        "ts_code": ts_code,
+        "name": fields[1] or symbol,
+        "pre_close": previous_close,
+        "open": _number(fields[5]),
+        "high": _number(fields[33]),
+        "low": _number(fields[34]),
+        "close": close,
+        "vol": _number(fields[6]) * 100,
+        "amount": _number(fields[37]) * 10000,
+        "num": 0,
+        "quote_date": quote_date,
+        "quote_time_epoch": epoch,
+        "source": "tencent_qt",
+    }
+
+
+def _normalize_eastmoney_quote(row: dict[str, Any]) -> dict[str, Any] | None:
+    symbol = str(row.get("f12") or "").strip()
+    if not symbol.isdigit() or len(symbol) != 6:
+        return None
+    close = _number(row.get("f2"))
+    previous_close = _number(row.get("f18"))
+    if close <= 0 or previous_close <= 0:
+        return None
+    market = int(_number(row.get("f13")))
+    if market == 1 or symbol.startswith(("5", "6", "9")):
+        ts_code = f"{symbol}.SH"
+    elif symbol.startswith(("4", "8")):
+        ts_code = f"{symbol}.BJ"
+    else:
+        ts_code = f"{symbol}.SZ"
+    epoch = int(_number(row.get("f124")))
+    quote_date = ""
+    if epoch > 0:
+        quote_date = datetime.fromtimestamp(epoch).astimezone().strftime("%Y%m%d")
+    return {
+        "ts_code": ts_code,
+        "name": row.get("f14") or symbol,
+        "pre_close": previous_close,
+        "open": _number(row.get("f17")),
+        "high": _number(row.get("f15")),
+        "low": _number(row.get("f16")),
+        "close": close,
+        "vol": _number(row.get("f5")) * 100,
+        "amount": _number(row.get("f6")),
+        "num": 0,
+        "quote_date": quote_date,
+        "quote_time_epoch": epoch,
+        "source": "eastmoney_clist",
+    }
+
+
 def _normalize_sector(value: Any) -> str:
     text = str(value or "").strip().replace(" ", "")
     for suffix in ("板块", "概念", "行业", "Ⅱ", "Ⅲ", "(A股)", "（A股）"):

backend/features/market/charts.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import http.client
 import json
+import logging
 import re
 import time
 import urllib.error
@@ -15,12 +16,15 @@ from typing import Any, ClassVar
 from backend.bootstrap.config import tushare_code as _stock_market_code
 from backend.data.providers.ifind_client import IfindError, IfindHttpClient
 
+LOGGER = logging.getLogger("xiaobai.charts")
+
 
 class ChartDataError(RuntimeError):
     pass
 
 
 TRENDS_URL = "https://push2delay.eastmoney.com/api/qt/stock/trends2/get"
+HIS_TRENDS_URL = "https://push2his.eastmoney.com/api/qt/stock/trends2/get"
 BOARD_LIST_URL = "https://push2delay.eastmoney.com/api/qt/clist/get"
 BROWSER_USER_AGENT = (
     "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
@@ -37,14 +41,23 @@ INDEX_SECIDS = {
 class MarketChartClient:
     """Prefer iFinD for display charts and retain Eastmoney as a last resort."""
 
-    def __init__(self, ifind: IfindHttpClient, fallback: "EastmoneyChartClient") -> None:
+    def __init__(
+        self,
+        ifind: IfindHttpClient,
+        fallback: "EastmoneyChartClient",
+        datahub: Any = None,
+    ) -> None:
         self.ifind = ifind
         self.fallback = fallback
+        self.datahub = datahub
 
     def stock_intraday(self, code: str) -> dict[str, Any]:
         normalized = str(code or "").strip()
         if not re.fullmatch(r"\d{6}", normalized):
             raise ChartDataError("Invalid stock code")
+        hub_chart = self._datahub_intraday(normalized)
+        if hub_chart is not None:
+            return hub_chart
         ifind_code = _stock_market_code(normalized)
         try:
             return self._ifind_intraday(ifind_code, "stock", normalized)
@@ -55,12 +68,18 @@ class MarketChartClient:
         normalized = str(code or "").strip()
         if not re.fullmatch(r"\d{6}", normalized):
             raise ChartDataError("Invalid stock code")
+        hub_rows = self._datahub_daily(normalized, end_date, limit, "daily")
+        if hub_rows:
+            return hub_rows
         return self._ifind_daily(_stock_market_code(normalized), end_date, limit)
 
     def index_daily(self, identifier: str, end_date: str, limit: int = 90) -> list[dict[str, Any]]:
         normalized = str(identifier or "").strip().upper()
         if normalized not in INDEX_SECIDS:
             raise ChartDataError("Unsupported index")
+        hub_rows = self._datahub_daily(normalized, end_date, limit, "index_daily")
+        if hub_rows:
+            return hub_rows
         return self._ifind_daily(normalized, end_date, limit)
 
     def board_daily(self, identifier: str, end_date: str, limit: int = 90) -> list[dict[str, Any]]:
@@ -73,11 +92,135 @@ class MarketChartClient:
         normalized = str(identifier or "").strip().upper()
         if normalized not in INDEX_SECIDS:
             raise ChartDataError("Unsupported index")
+        hub_chart = self._datahub_intraday(normalized)
+        if hub_chart is not None:
+            return hub_chart
         try:
             return self._ifind_intraday(normalized, "index", normalized)
         except (IfindError, ChartDataError):
             return self.fallback.index_intraday(normalized)
 
+    def _datahub_intraday(self, code: str) -> dict[str, Any] | None:
+        if self.datahub is None:
+            return None
+        try:
+            chart = self.datahub.try_intraday(code)
+        except Exception as exc:
+            LOGGER.warning("datahub intraday unexpected error: %s", exc)
+            return None
+        if not chart:
+            return None
+        points = list(chart.get("points") or [])
+        if not points:
+            return None
+        return chart
+
+    def _datahub_daily(
+        self,
+        code: str,
+        end_date: str,
+        limit: int,
+        dataset: str,
+    ) -> list[dict[str, Any]] | None:
+        if self.datahub is None or not hasattr(self.datahub, "try_daily_chart"):
+            return None
+        try:
+            rows = self.datahub.try_daily_chart(code, end_date, limit, dataset)
+        except Exception as exc:
+            LOGGER.warning("datahub daily unexpected error: %s", exc)
+            rows = None
+        if not rows:
+            if hasattr(self.datahub, "record_legacy"):
+                self.datahub.record_legacy(dataset, "ifind")
+            return None
+        compact_end = str(end_date or "").replace("-", "")
+        market_now = datetime.now().astimezone()
+        today = market_now.strftime("%Y%m%d")
+        market_open = (
+            market_now.weekday() < 5
+            and market_now.time().replace(tzinfo=None) >= dt_time(9, 30)
+        )
+        if compact_end == today and market_open:
+            overlay = self._datahub_today_bar(code, dataset, rows)
+            if overlay:
+                if rows and rows[-1]["trade_date"] == overlay["trade_date"]:
+                    rows[-1] = overlay
+                else:
+                    rows.append(overlay)
+        return rows
+
+    def _datahub_today_bar(
+        self,
+        code: str,
+        dataset: str,
+        history: list[dict[str, Any]],
+    ) -> dict[str, Any] | None:
+        today_display = datetime.now().astimezone().date().isoformat()
+        previous = history[-1]["close"] if history and history[-1]["trade_date"] != today_display else (
+            history[-2]["close"] if len(history) >= 2 else 0.0
+        )
+        quote = None
+        if dataset == "index_daily" and hasattr(self.datahub, "try_index_quotes"):
+            quotes = self.datahub.try_index_quotes() or []
+            quote = next(
+                (
+                    item for item in quotes
+                    if str(item.get("ts_code") or "") == code or str(item.get("code") or "") == code.split(".")[0]
+                ),
+                None,
+            )
+        elif hasattr(self.datahub, "try_quotes"):
+            quotes = self.datahub.try_quotes([code]) or []
+            quote = quotes[0] if quotes else None
+        if quote:
+            close = _number(quote.get("close") if quote.get("close") not in (None, "") else quote.get("price"))
+            open_price = _number(quote.get("open"))
+            high = _number(quote.get("high"))
+            low = _number(quote.get("low"))
+            previous_close = _number(
+                quote.get("pre_close") if quote.get("pre_close") not in (None, "") else quote.get("previous_close")
+            ) or previous
+            volume = _number(quote.get("vol") if quote.get("vol") not in (None, "") else quote.get("volume"))
+            amount = _number(quote.get("amount"))
+            if close > 0 and open_price > 0:
+                return {
+                    "trade_date": today_display,
+                    "open": open_price,
+                    "high": high or close,
+                    "low": low or close,
+                    "close": close,
+                    "change": round((close / previous_close - 1) * 100, 4) if previous_close else 0.0,
+                    "volume": volume,
+                    "amount_billion": amount / 100_000_000,
+                    "realtime": True,
+                }
+        chart = self._datahub_intraday(code)
+        points = list((chart or {}).get("points") or [])
+        if not points:
+            return None
+        closes = [_number(point.get("close")) for point in points if _number(point.get("close")) > 0]
+        if not closes:
+            return None
+        opens = [_number(point.get("open")) for point in points if _number(point.get("open")) > 0]
+        highs = [_number(point.get("high")) for point in points if _number(point.get("high")) > 0]
+        lows = [_number(point.get("low")) for point in points if _number(point.get("low")) > 0]
+        volume = sum(_number(point.get("volume")) for point in points)
+        amount = sum(_number(point.get("amount")) for point in points)
+        previous_close = _number((chart or {}).get("previous_close")) or previous
+        close = closes[-1]
+        open_price = opens[0] if opens else closes[0]
+        return {
+            "trade_date": today_display,
+            "open": open_price,
+            "high": max(highs or closes),
+            "low": min(lows or closes),
+            "close": close,
+            "change": round((close / previous_close - 1) * 100, 4) if previous_close else 0.0,
+            "volume": volume,
+            "amount_billion": amount / 100_000_000,
+            "realtime": True,
+        }
+
     def board_intraday(self, identifier: str, name: str = "") -> dict[str, Any]:
         normalized = str(identifier or "").strip().upper()
         try:
@@ -305,21 +448,29 @@ class EastmoneyChartClient:
         if cached is not None:
             return cached
 
-        payload = self._request_json(
+        params = {
-            TRENDS_URL,
+            "secid": secid,
-            {
+            "fields1": "f1,f2,f3,f4,f5,f6,f7,f8,f9,f10,f11,f12,f13",
-                "secid": secid,
+            "fields2": "f51,f52,f53,f54,f55,f56,f57,f58",
-                "fields1": "f1,f2,f3,f4,f5,f6,f7,f8,f9,f10,f11,f12,f13",
+            "iscr": "0",
-                "fields2": "f51,f52,f53,f54,f55,f56,f57,f58",
+        }
-                "iscr": "0",
+        last_error: Exception | None = None
-                "ndays": "1",
+        data: dict[str, Any] = {}
-            },
+        points: list[dict[str, Any]] = []
-            "https://quote.eastmoney.com/",
+        for url, ndays in ((TRENDS_URL, "1"), (TRENDS_URL, "5"), (HIS_TRENDS_URL, "5")):
-        )
+            request_params = {**params, "ndays": ndays}
-        data = payload.get("data") or {}
+            try:
-        points = [point for raw in data.get("trends") or [] if (point := _parse_trend(raw))]
+                payload = self._request_json(url, request_params, "https://quote.eastmoney.com/")
+            except ChartDataError as exc:
+                last_error = exc
+                continue
+            data = payload.get("data") or {}
+            parsed = [point for raw in data.get("trends") or [] if (point := _parse_trend(raw))]
+            points = _latest_session(parsed)
+            if points:
+                break
         if not points:
-            raise ChartDataError("No intraday chart data returned")
+            raise ChartDataError("No intraday chart data returned") from last_error
 
         result = {
             "entity_type": entity_type,
@@ -433,6 +584,15 @@ class EastmoneyChartClient:
         raise ChartDataError("Intraday chart request failed") from last_error
 
 
+def _latest_session(points: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    if not points:
+        return []
+    latest = max(str(point.get("date") or "") for point in points)
+    if not latest:
+        return points
+    return [point for point in points if str(point.get("date") or "") == latest]
+
+
 def _parse_trend(raw: Any) -> dict[str, Any] | None:
     fields = str(raw or "").split(",")
     if len(fields) < 8 or " " not in fields[0]:

backend/features/market/service.py

@@ -15,6 +15,7 @@ from backend.bootstrap.config import (
 )
 from backend.data.providers.ifind_client import IfindError
 from backend.data.providers.tushare_client import TushareClient, TushareError
+from backend.data.realtime import RealtimeAggregateError
 from backend.features.market.backfill_history import (
     DEFAULT_RECENT_TRADING_DAYS,
     MAX_RANGE_TRADING_DAYS,
@@ -42,6 +43,7 @@ SEARCH_TYPE_LABELS = {
     "theme": "题材",
     "index": "指数",
 }
+TODAY_DAILY_UNAVAILABLE_NOTICE = "今日日K暂不可用，仍显示最近收盘K线。"
 THS_SEARCH_TYPES = {
     "I": ("sector", "行业板块"),
     "R": ("sector", "地域板块"),
@@ -63,11 +65,37 @@ class MarketServiceMixin:
         if gateway is not None:
             return gateway.tushare()
         # Compatibility for isolated legacy unit-test service stubs.
-        return TushareClient(self.token)
+        client = TushareClient(self.token)
+        aggregator = getattr(self, "realtime_aggregator", None)
+        if aggregator is not None:
+            client.realtime_aggregator = aggregator
+        return client
+
+    def _now(self) -> datetime:
+        clock = getattr(self, "clock", None)
+        if callable(clock):
+            return clock()
+        return datetime.now().astimezone()
+
+    def _is_requested_open_session(self, requested_date: str) -> bool:
+        now = self._now()
+        if requested_date != now.strftime("%Y%m%d"):
+            return False
+        if now.time().replace(tzinfo=None) < dt_time(9, 15):
+            return False
+        client = self._tushare_client() if self.configured else None
+        resolve = getattr(client, "resolve_trade_context", None) if client else None
+        if resolve is None:
+            return now.weekday() < 5
+        try:
+            trade_date, _ = resolve(requested_date)
+        except Exception:
+            return now.weekday() < 5
+        return str(trade_date or "") == requested_date
 
     def get_dashboard(self, trade_date: str, force: bool = False) -> dict[str, Any]:
         normalized_date = normalize_date(trade_date)
-        now = datetime.now().astimezone()
+        now = self._now()
         if (
             normalized_date == now.strftime("%Y%m%d")
             and now.time().replace(tzinfo=None) < datetime.strptime("09:15", "%H:%M").time()
@@ -79,6 +107,8 @@ class MarketServiceMixin:
         if not force:
             snapshot = self.database.get_snapshot(normalized_date)
             if snapshot and str((snapshot.get("meta") or {}).get("source") or "") != "demo":
+                if self._should_retry_incomplete_snapshot(snapshot, normalized_date):
+                    return self.sync_dashboard(normalized_date)
                 snapshot = copy.deepcopy(snapshot)
                 if normalized_date != now.strftime("%Y%m%d"):
                     snapshot.setdefault("meta", {}).update(
@@ -97,6 +127,8 @@ class MarketServiceMixin:
                 "dashboard_request_v1", normalized_date
             )
             if resolved and str((resolved.get("meta") or {}).get("source") or "") != "demo":
+                if self._should_retry_incomplete_snapshot(resolved, normalized_date):
+                    return self.sync_dashboard(normalized_date)
                 resolved = copy.deepcopy(resolved)
                 resolved.setdefault("meta", {})["requested_date"] = self._display_compact_date(
                     normalized_date
@@ -138,6 +170,71 @@ class MarketServiceMixin:
     def _display_compact_date(compact: str) -> str:
         return f"{compact[:4]}-{compact[4:6]}-{compact[6:8]}"
 
+    @staticmethod
+    def _chinese_month_day(value: str) -> str:
+        compact = str(value or "").replace("-", "").replace("/", "")
+        if len(compact) < 8 or not compact[:8].isdigit():
+            return "最近可用交易日"
+        return f"{int(compact[4:6])} 月 {int(compact[6:8])} 日"
+
+    @classmethod
+    def _preparing_display_notice(cls, actual_date: str, requested_date: str) -> str:
+        shown = cls._chinese_month_day(actual_date)
+        requested = str(requested_date or "").replace("-", "")
+        if requested == date.today().strftime("%Y%m%d"):
+            return f"今日数据正在准备，当前展示 {shown}"
+        return f"所选日期数据尚未到齐，当前展示 {shown}"
+
+    @staticmethod
+    def _snapshot_age_seconds(meta: dict[str, Any]) -> float:
+        raw = str(meta.get("updated_at") or "")
+        if not raw:
+            return 10**9
+        try:
+            updated_at = datetime.fromisoformat(raw)
+        except ValueError:
+            return 10**9
+        now = datetime.now().astimezone()
+        if updated_at.tzinfo is None:
+            updated_at = updated_at.replace(tzinfo=now.tzinfo)
+        return (now - updated_at.astimezone(now.tzinfo)).total_seconds()
+
+    def _should_retry_incomplete_snapshot(
+        self, snapshot: dict[str, Any], requested_date: str
+    ) -> bool:
+        if requested_date != self._now().strftime("%Y%m%d"):
+            return False
+        meta = snapshot.get("meta") or {}
+        actual = str(meta.get("trade_date") or "").replace("-", "")
+        stale_carry = bool(meta.get("carried_forward") or actual != requested_date)
+        if stale_carry and self._is_requested_open_session(requested_date):
+            return True
+        incomplete = meta.get("limit_data_source") == "derived" or stale_carry
+        return incomplete and self._snapshot_age_seconds(meta) >= 60
+
+    def _annotate_data_status(self, dashboard: dict[str, Any]) -> dict[str, Any]:
+        meta = dashboard.setdefault("meta", {})
+        notice = str(meta.get("notice") or "")
+        requested = str(meta.get("requested_date") or "").replace("-", "")
+        actual = str(meta.get("trade_date") or "").replace("-", "")
+        if meta.get("limit_data_source") == "derived" and not meta.get("carried_forward"):
+            meta["data_status"] = "partial"
+            meta["display_notice"] = notice or "部分正式数据尚未到齐，当前展示日线推算结果"
+        elif meta.get("carried_forward"):
+            if "非交易日" in notice or "盘前" in notice:
+                meta["data_status"] = "carried"
+                meta["display_notice"] = notice
+            else:
+                meta["data_status"] = "preparing"
+                meta["display_notice"] = self._preparing_display_notice(actual, requested)
+        elif meta.get("realtime"):
+            meta["data_status"] = "intraday"
+            meta.setdefault("display_notice", "")
+        else:
+            meta["data_status"] = "official"
+            meta.setdefault("display_notice", "")
+        return dashboard
+
     def _carry_dashboard(
         self, snapshot: dict[str, Any], requested_date: str, reason: str
     ) -> dict[str, Any]:
@@ -152,16 +249,16 @@ class MarketServiceMixin:
                 "notice": reason,
             }
         )
-        return carried
+        return self._annotate_data_status(carried)
 
     def _realtime_snapshot_due(
         self,
         normalized_date: str,
         snapshot: dict[str, Any],
     ) -> bool:
-        if not self.configured or normalized_date != date.today().strftime("%Y%m%d"):
+        if not self.configured or normalized_date != self._now().strftime("%Y%m%d"):
             return False
-        now = datetime.now().astimezone()
+        now = self._now()
         local_time = now.time().replace(tzinfo=None)
         realtime_start = datetime.strptime("09:15", "%H:%M").time()
         morning_end = datetime.strptime("11:35", "%H:%M").time()
@@ -197,19 +294,28 @@ class MarketServiceMixin:
                 if not self.configured:
                     raise TushareError("公共行情尚未配置")
                 dashboard = self._tushare_client().dashboard(normalized_date)
-
+                meta = dashboard.setdefault("meta", {})
-                if (dashboard.get("meta") or {}).get("limit_data_source") == "derived":
+                quote_source = str(meta.get("quote_source") or "")
-                    raise TushareError(
+                meta["source"] = source
-                        str((dashboard.get("meta") or {}).get("notice") or "官方涨跌停数据尚未返回")
+                if quote_source:
+                    meta["quote_source"] = quote_source
+                meta["requested_date"] = self._display_compact_date(normalized_date)
+                if meta.get("limit_data_source") == "derived":
+                    meta.setdefault(
+                        "notice",
+                        "涨跌停高级接口当日数据尚未更新，已使用日线数据推算。",
                     )
-
-                dashboard["meta"]["source"] = source
-                dashboard["meta"]["requested_date"] = self._display_compact_date(normalized_date)
                 dashboard = self._enrich_dashboard_sentiment(dashboard, normalized_date)
                 record_count = self._record_count(dashboard)
                 actual_date = normalize_date(
                     str(dashboard.get("meta", {}).get("trade_date") or normalized_date)
                 )
+                if actual_date != normalized_date and self._is_requested_open_session(
+                    normalized_date
+                ):
+                    raise TushareError(
+                        f"Intraday dashboard resolved {actual_date} instead of {normalized_date}"
+                    )
                 self.database.save_snapshot(actual_date, source, dashboard)
                 if actual_date != normalized_date:
                     dashboard.setdefault("meta", {}).update(
@@ -231,10 +337,37 @@ class MarketServiceMixin:
                 )
                 return self._apply_reason_overrides(self._with_storage(dashboard, cached=False))
             except TushareError as exc:
+                if self._is_requested_open_session(normalized_date):
+                    existing = self.database.get_snapshot(normalized_date)
+                    existing_date = str(
+                        ((existing or {}).get("meta") or {}).get("trade_date") or ""
+                    ).replace("-", "")
+                    if existing and existing_date == normalized_date:
+                        kept = copy.deepcopy(existing)
+                        kept.setdefault("meta", {}).update(
+                            {
+                                "requested_date": self._display_compact_date(normalized_date),
+                            }
+                        )
+                        self.database.finish_sync(
+                            sync_id,
+                            "fallback",
+                            self._record_count(kept),
+                            str(exc),
+                            "tushare",
+                        )
+                        return self._apply_reason_overrides(
+                            self._with_storage(kept, cached=True)
+                        )
+                    self.database.finish_sync(sync_id, "failed", message=str(exc))
+                    raise ValueError("当天盘中行情暂时不可用，请稍后重试。") from exc
                 fallback = self.database.get_latest_real_snapshot(normalized_date)
                 if fallback:
+                    actual = str((fallback.get("meta") or {}).get("trade_date") or "")
                     carried = self._carry_dashboard(
-                        fallback, normalized_date, f"最新行情暂不可用，沿用最近收盘快照：{exc}"
+                        fallback,
+                        normalized_date,
+                        self._preparing_display_notice(actual, normalized_date),
                     )
                     self.database.finish_sync(
                         sync_id, "fallback", self._record_count(carried), str(exc), "tushare"
@@ -683,26 +816,27 @@ class MarketServiceMixin:
                 "trade_date": f"{actual_date[:4]}-{actual_date[4:6]}-{actual_date[6:]}",
             }
         today = now.strftime("%Y%m%d")
+        latest_bar = (result.get("prices") or [{}])[-1] if result.get("prices") else {}
+        official_today = (
+            actual_date == today and not bool(latest_bar.get("realtime"))
+        )
+        after_close = now.time().replace(tzinfo=None) >= dt_time(15, 0)
         should_merge = (
             requested_date == today
             and actual_date <= today
             and now.weekday() < 5
             and now.time().replace(tzinfo=None) >= dt_time(9, 30)
+            and not (official_today and after_close)
         )
         if should_merge:
-            quote = self._ifind_realtime_stock_quote(code)
+            quote = self._resolve_today_daily_quote(code, today, result)
             if quote and self._valid_realtime_stock_quote(quote, today):
                 self._merge_realtime_stock_detail(result, quote, requested_date)
-            elif self.configured and actual_date < today:
+            elif actual_date < today:
-                client = self._tushare_client()
+                result["meta"] = {
-                try:
+                    **(result.get("meta") or {}),
-                    resolved_date, _ = client.resolve_trade_context(requested_date)
+                    "notice": TODAY_DAILY_UNAVAILABLE_NOTICE,
-                    if resolved_date == today:
+                }
-                        quote = client.realtime_stock_quote(tushare_code(code), requested_date)
-                        if self._valid_realtime_stock_quote(quote, today):
-                            self._merge_realtime_stock_detail(result, quote, requested_date)
-                except TushareError:
-                    pass
         return self._enrich_stock_detail(result)
 
     @staticmethod
@@ -817,6 +951,134 @@ class MarketServiceMixin:
             "quote_time": str(row.get("time") or ""),
         }
 
+    def _resolve_today_daily_quote(
+        self, code: str, today: str, payload: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        quote = self._ifind_realtime_stock_quote(code)
+        if quote and self._valid_realtime_stock_quote(quote, today):
+            return quote
+        if self.configured:
+            try:
+                client = self._tushare_client()
+                resolve = getattr(client, "resolve_trade_context", None)
+                resolved = today
+                if callable(resolve):
+                    resolved, _ = resolve(today)
+                if str(resolved or "") == today:
+                    quote = client.realtime_stock_quote(tushare_code(code), today)
+                    if self._valid_realtime_stock_quote(quote, today):
+                        return quote
+            except TushareError:
+                pass
+        quote = self._free_realtime_stock_quote(code, today)
+        if quote and self._valid_realtime_stock_quote(quote, today):
+            return quote
+        return self._intraday_realtime_stock_quote(code, today, payload)
+
+    def _free_realtime_stock_quote(self, code: str, today: str) -> dict[str, Any] | None:
+        aggregator = getattr(self, "realtime_aggregator", None)
+        if aggregator is None:
+            return None
+        ts_code = tushare_code(code)
+        for loader in (
+            getattr(aggregator, "tencent_stock_quote", None),
+            getattr(aggregator, "eastmoney_stock_quote", None),
+        ):
+            if not callable(loader):
+                continue
+            try:
+                row = loader(ts_code, expected_date=today)
+            except (RealtimeAggregateError, Exception):
+                continue
+            quote = self._quote_from_free_row(code, today, row)
+            if quote:
+                return quote
+        return None
+
+    def _quote_from_free_row(
+        self, code: str, today: str, row: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        price = float(row.get("close") or 0)
+        previous_close = float(row.get("pre_close") or 0)
+        if price <= 0 or previous_close <= 0:
+            return None
+        try:
+            name, sector = self._stock_identity(code, today)
+        except Exception:
+            name, sector = "--", "其他"
+        epoch = int(row.get("quote_time_epoch") or 0)
+        if epoch > 0:
+            quote_time = datetime.fromtimestamp(epoch).astimezone().isoformat(timespec="seconds")
+        else:
+            quote_date = str(row.get("quote_date") or today)
+            quote_time = f"{quote_date[:4]}-{quote_date[4:6]}-{quote_date[6:]}"
+        return {
+            "name": str(row.get("name") or name or "--"),
+            "sector": sector,
+            "price": price,
+            "open": float(row.get("open") or 0),
+            "high": float(row.get("high") or 0),
+            "low": float(row.get("low") or 0),
+            "change": round((price / previous_close - 1) * 100, 4),
+            "volume": float(row.get("vol") or 0),
+            "amount_billion": float(row.get("amount") or 0) / 100_000_000,
+            "turnover_rate": float(row.get("turnover_rate") or 0),
+            "quote_time": quote_time,
+        }
+
+    def _intraday_realtime_stock_quote(
+        self, code: str, today: str, payload: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        chart_data = getattr(self, "chart_data", None)
+        if chart_data is None:
+            return None
+        try:
+            chart = chart_data.stock_intraday(code)
+        except (AttributeError, ChartDataError, Exception):
+            return None
+        points = [
+            point
+            for point in list(chart.get("points") or [])
+            if str(point.get("date") or "").replace("-", "") == today
+        ]
+        if not points:
+            return None
+        opens = [float(point.get("open") or 0) for point in points if float(point.get("open") or 0) > 0]
+        highs = [float(point.get("high") or 0) for point in points if float(point.get("high") or 0) > 0]
+        lows = [float(point.get("low") or 0) for point in points if float(point.get("low") or 0) > 0]
+        closes = [float(point.get("close") or 0) for point in points if float(point.get("close") or 0) > 0]
+        if not opens or not highs or not lows or not closes:
+            return None
+        price = closes[-1]
+        previous_close = float(chart.get("previous_close") or 0)
+        if previous_close <= 0:
+            history = list(payload.get("prices") or [])
+            previous_close = float((history[-1] if history else {}).get("close") or 0)
+        if previous_close <= 0:
+            return None
+        volume = sum(float(point.get("volume") or 0) for point in points)
+        amount = sum(float(point.get("amount") or 0) for point in points)
+        if volume <= 0 and amount <= 0:
+            return None
+        try:
+            name, sector = self._stock_identity(code, today)
+        except Exception:
+            name, sector = "--", "其他"
+        return {
+            "name": name,
+            "sector": sector,
+            "price": price,
+            "open": opens[0],
+            "high": max(highs),
+            "low": min(lows),
+            "change": round((price / previous_close - 1) * 100, 4),
+            "volume": volume,
+            "volume_unit": "lots",
+            "amount_billion": amount / 100_000_000,
+            "turnover_rate": 0.0,
+            "quote_time": str(points[-1].get("date") or today),
+        }
+
     @staticmethod
     def _merge_realtime_stock_detail(
         payload: dict[str, Any], quote: dict[str, Any], trade_date: str
@@ -855,6 +1117,7 @@ class MarketServiceMixin:
             **(payload.get("meta") or {}),
             "trade_date": display_date,
             "realtime": True,
+            "notice": "",
             "updated_at": datetime.now().astimezone().isoformat(timespec="seconds"),
         }
 
@@ -1160,7 +1423,7 @@ class MarketServiceMixin:
             "storage": "sqlite",
             "cached": cached,
         }
-        return result
+        return self._annotate_data_status(result)
 
     @staticmethod
     def _record_count(dashboard: dict[str, Any]) -> int:

backend/features/system/service.py

@@ -130,6 +130,7 @@ class SystemServiceMixin:
                 ),
                 **self.database.status(),
                 "jobs": self.jobs.repository.recent(12),
+                "datahub": self._datahub_status(),
             },
             "llm": {
                 "primary_configured": self._profile_configured(platform["primary"]),
@@ -145,6 +146,22 @@ class SystemServiceMixin:
             },
         }
 
+    def _datahub_status(self) -> dict[str, Any]:
+        gateway = getattr(self, "data_gateway", None)
+        reporter = getattr(gateway, "datahub_status", None)
+        if callable(reporter):
+            return reporter()
+        return {
+            "configured": False,
+            "base_url": "",
+            "enabled_reads": 0,
+            "total_reads": 0,
+            "flags": [],
+            "routes": [],
+            "fallback_count": 0,
+            "fallback_labels": [],
+        }
+
     def save_system_settings(self, payload: dict[str, Any]) -> dict[str, Any]:
         current = dict(self._system_credentials)
         token = str(payload.get("tushare_token") or current.get("tushare_token") or "").strip()

backend/http/handler.py

@@ -109,7 +109,14 @@ class HttpTransportMixin:
             return {}
         if length <= 0 or length > 65536:
             raise ValueError("请求内容为空或过大。")
-        return json.loads(self.rfile.read(length).decode("utf-8"))
+        raw = self.rfile.read(length)
+        try:
+            payload = json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            raise ValueError("请求不是合法 JSON。") from None
+        if not isinstance(payload, dict):
+            raise ValueError("请求不是合法 JSON。")
+        return payload
 
     def serve_static(self, request_path: str) -> None:
         relative = unquote(request_path).lstrip("/") or "index.html"

backend/jobs/refresh.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from datetime import datetime, time as dt_time
+
+
+def dashboard_has_usable_data(dashboard: dict[str, object]) -> bool:
+    if not isinstance(dashboard, dict) or dashboard.get("status") == "failed":
+        return False
+    meta = dashboard.get("meta") or {}
+    overview = dashboard.get("overview") or {}
+    if isinstance(meta, dict) and (meta.get("trade_date") or meta.get("carried_forward")):
+        return True
+    return bool(isinstance(overview, dict) and overview)
+
+
+def verified_dashboard_result(dashboard: dict[str, object]) -> dict[str, object]:
+    """Manual refresh and automatic catch-up share this rule.
+
+    Derived limit lists or a previous usable snapshot are not whole-job failures.
+    Only a payload with no displayable market data is recorded as failed.
+    """
+    if dashboard_has_usable_data(dashboard):
+        return dashboard
+    meta = dashboard.get("meta") if isinstance(dashboard, dict) else None
+    notice = ""
+    if isinstance(meta, dict):
+        notice = str(meta.get("notice") or meta.get("display_notice") or "")
+    return {
+        "status": "failed",
+        "error": notice or "未获取到可用行情",
+    }
+
+
+def official_catchup_due(today: str, snapshot: dict[str, object]) -> bool:
+    now = datetime.now().astimezone().time().replace(tzinfo=None)
+    if not (dt_time(15, 5) <= now < dt_time(22, 0)):
+        return False
+    meta = snapshot.get("meta") if isinstance(snapshot.get("meta"), dict) else {}
+    actual = str(meta.get("trade_date") or "").replace("-", "")
+    if (
+        actual == today
+        and meta.get("limit_data_source") != "derived"
+        and not meta.get("carried_forward")
+        and not meta.get("realtime")
+        and meta.get("mode") != "realtime"
+    ):
+        return False
+    return True

backend/jobs/service.py

@@ -5,16 +5,7 @@ import time
 from datetime import date
 
 from backend.bootstrap.config import normalize_date
-
+from backend.jobs.refresh import official_catchup_due, verified_dashboard_result
-
-def _verified_dashboard_result(dashboard: dict[str, object]) -> dict[str, object]:
-    meta = dashboard.get("meta") or {}
-    if isinstance(meta, dict) and meta.get("carried_forward"):
-        return {
-            "status": "failed",
-            "error": str(meta.get("notice") or "未获取到所选日期的最新行情"),
-        }
-    return dashboard
 
 
 class JobServiceMixin:
@@ -36,7 +27,7 @@ class JobServiceMixin:
         started = self.jobs.submit(
             "market.refresh",
             key,
-            lambda: _verified_dashboard_result(self.sync_dashboard(normalized)),
+            lambda: verified_dashboard_result(self.sync_dashboard(normalized)),
             {"trade_date": normalized, "trigger": "administrator"},
         )
         return {"started": started, "job_key": key if started else ""}
@@ -54,7 +45,15 @@ class JobServiceMixin:
             self.jobs.submit(
                 "market.refresh",
                 f"realtime:{today}:{bucket}",
-                lambda: self.sync_dashboard(today),
+                lambda: verified_dashboard_result(self.sync_dashboard(today)),
                 {"trade_date": today, "trigger": "realtime-poll"},
             )
+        elif official_catchup_due(today, snapshot):
+            bucket = int(time.time() // 300)
+            self.jobs.submit(
+                "market.refresh",
+                f"catchup:{today}:{bucket}",
+                lambda: verified_dashboard_result(self.sync_dashboard(today)),
+                {"trade_date": today, "trigger": "official-catchup"},
+            )
         self._schedule_automatic_screeners(today, snapshot)

compose.datahub.yaml

@@ -0,0 +1,45 @@
+# Optional overlay. Does not replace the existing xiaobai-review service.
+# Start later (总工部署时) with:
+#   docker compose -f compose.yaml -f compose.datahub.yaml up -d
+#
+# Required .env keys: DATAHUB_ENCRYPTION_KEY, DATAHUB_TOKEN, DATAHUB_ADMIN_PASSWORD, TUSHARE_TOKEN
+
+services:
+  xiaobai-datahub:
+    build:
+      context: ./xiaobai-datahub
+      dockerfile: Dockerfile
+    image: xiaobai-datahub:local
+    container_name: xiaobai-datahub
+    ports:
+      - "0.0.0.0:8766:8766/tcp"
+    env_file:
+      - ./xiaobai-datahub/.env
+    environment:
+      DATAHUB_ENCRYPTION_KEY: "${DATAHUB_ENCRYPTION_KEY:?DATAHUB_ENCRYPTION_KEY must be set}"
+      DATAHUB_TOKEN: "${DATAHUB_TOKEN:?DATAHUB_TOKEN must be set}"
+      DATAHUB_ADMIN_PASSWORD: "${DATAHUB_ADMIN_PASSWORD:?DATAHUB_ADMIN_PASSWORD must be set}"
+      TUSHARE_TOKEN: "${TUSHARE_TOKEN:-}"
+      DATAHUB_DB_PATH: /app/data/datahub.db
+      DATAHUB_BACKUP_DIR: /app/data/backups
+      TZ: Asia/Shanghai
+      PYTHONUTF8: "1"
+    volumes:
+      - type: bind
+        source: ./datahub-data
+        target: /app/data
+    restart: unless-stopped
+    init: true
+    read_only: true
+    tmpfs:
+      - /tmp:size=64m,mode=1777
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    stop_grace_period: 30s
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"

compose.yaml

@@ -3,7 +3,9 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
-    image: xiaobai-review:latest
+      labels:
+        org.opencontainers.image.revision: "${XIAOBAI_GIT_REV:?必须先设置 XIAOBAI_GIT_REV=当前 main 完整提交号（或改用 tools/update_from_main.sh）}"
+    image: xiaobai-review:main-${XIAOBAI_GIT_SHORT:?必须先设置 XIAOBAI_GIT_SHORT=7位提交短号（或改用 tools/update_from_main.sh）}
     container_name: xiaobai-review
     ports:
       - "0.0.0.0:8765:8765/tcp"
@@ -11,6 +13,22 @@ services:
       - ./.env
     environment:
       APP_ENCRYPTION_KEY: "${APP_ENCRYPTION_KEY:?APP_ENCRYPTION_KEY must be set in .env}"
+      DATAHUB_BASE_URL: "${DATAHUB_BASE_URL:-http://192.168.200.11:8766}"
+      DATAHUB_READ_CALENDAR: "1"
+      DATAHUB_READ_STOCKS: "1"
+      DATAHUB_READ_DAILY: "1"
+      DATAHUB_READ_INDEX_DAILY: "1"
+      DATAHUB_READ_VALUATION: "1"
+      DATAHUB_READ_MONEYFLOW: "1"
+      DATAHUB_READ_AUCTION: "1"
+      DATAHUB_READ_LIMIT_EVENTS: "1"
+      DATAHUB_READ_POPULARITY: "1"
+      DATAHUB_READ_DRAGON_TIGER: "1"
+      DATAHUB_READ_SECTOR_DAILY: "1"
+      DATAHUB_READ_QUOTES: "1"
+      DATAHUB_READ_INDEX_QUOTES: "1"
+      DATAHUB_READ_INTRADAY: "1"
+      DATAHUB_READ_STATUS: "1"
       TZ: Asia/Shanghai
       PYTHONUTF8: "1"
     volumes:

config/README.md

@@ -12,6 +12,12 @@ These registries describe the approved product surface of the standalone applica
   providers, model entry points, CSS layers, and remaining code hotspots.
 - `data-fields.config.json`: canonical data products, provider eligibility, intended use, and
   known blocked datasets.
+- `datahub.config.json`: official read-only client for `xiaobai-datahub`. Each dataset has its
+  own `read` / `shadow` flag; official reads default on. `compose.yaml` pins every
+  `DATAHUB_READ_*` to `"1"` so a leftover `.env` `=0` cannot silently keep official
+  pages on the old APIs. Environment variables can still override a single
+  `DATAHUB_SHADOW_*` without a master switch. The old website APIs stay as
+  emergency fallback only.
 - `data-quality.config.json`: freshness, coverage, units, adjustment, point-in-time, and
   fail-closed rules for every canonical data product.
 - `jobs.config.json`: background schedules, dependencies, lock keys, retry policy, timeouts,

config/architecture-inventory.json

@@ -204,6 +204,11 @@
       "path": "backend/data/providers/tushare_client.py",
       "runtime_role": "stable client facade for primary deterministic market data"
     },
+    {
+      "provider": "datahub",
+      "path": "backend/data/datahub/client.py",
+      "runtime_role": "optional official EOD read path behind per-dataset flags"
+    },
     {
       "provider": "ifind",
       "path": "backend/data/providers/ifind_client.py",
@@ -217,12 +222,12 @@
     {
       "provider": "eastmoney",
       "path": "backend/data/realtime.py",
-      "runtime_role": "isolated realtime observation"
+      "runtime_role": "isolated realtime observation and intraday dashboard fallback"
     },
     {
       "provider": "tencent",
       "path": "backend/data/realtime.py",
-      "runtime_role": "index observation fallback"
+      "runtime_role": "index observation and intraday quote fallback"
     }
   ],
   "provider_domains": [
@@ -278,6 +283,18 @@
       "owner": "backend/data/providers/tushare.py",
       "compatibility_fallback": "backend/features/market/service.py"
     },
+    {
+      "client": "DatahubClient",
+      "owner": "backend/data/gateway.py"
+    },
+    {
+      "client": "DatahubBridge",
+      "owner": "backend/data/gateway.py"
+    },
+    {
+      "client": "DatahubAwareTushareClient",
+      "owner": "backend/data/gateway.py"
+    },
     {
       "client": "IfindHttpClient",
       "owner": "backend/data/gateway.py"
@@ -313,6 +330,7 @@
     "system_service": "backend/features/system/service.py",
     "account_bridge": "backend/features/accounts/application.py",
     "job_lifecycle": "backend/jobs/service.py",
+    "job_refresh_status": "backend/jobs/refresh.py",
     "feature_routes": "backend/features/*/routes.py"
   },
   "numeric_normalization": [
@@ -455,8 +473,8 @@
     },
     {
       "path": "frontend/shared/shell.css",
-      "bytes": 63659,
+      "bytes": 63733,
-      "lines": 3763
+      "lines": 3767
     },
     {
       "path": "backend/features/heaven/engine.py",
@@ -465,8 +483,8 @@
     },
     {
       "path": "frontend/index.html",
-      "bytes": 48254,
+      "bytes": 48447,
-      "lines": 664
+      "lines": 665
     },
     {
       "path": "backend/features/screener/catalog.py",
@@ -478,6 +496,11 @@
       "bytes": 35247,
       "lines": 2416
     },
+    {
+      "path": "backend/data/providers/tushare_dashboard.py",
+      "bytes": 33603,
+      "lines": 784
+    },
     {
       "path": "database.py",
       "bytes": 32073,
@@ -488,11 +511,6 @@
       "bytes": 31756,
       "lines": 562
     },
-    {
-      "path": "backend/data/providers/tushare_dashboard.py",
-      "bytes": 28234,
-      "lines": 648
-    },
     {
       "path": "backend/data/providers/tushare_industries.py",
       "bytes": 26540,
@@ -515,8 +533,8 @@
     },
     {
       "path": "frontend/pages/market/preview.js",
-      "bytes": 18178,
+      "bytes": 18339,
-      "lines": 446
+      "lines": 450
     },
     {
       "path": "backend/features/heaven/trend.py",
@@ -533,6 +551,16 @@
       "bytes": 15311,
       "lines": 387
     },
+    {
+      "path": "frontend/shared/admin.js",
+      "bytes": 15235,
+      "lines": 289
+    },
+    {
+      "path": "frontend/shared/dashboard.js",
+      "bytes": 15063,
+      "lines": 321
+    },
     {
       "path": "frontend/pages/pools/page.html",
       "bytes": 14942,
@@ -543,25 +571,20 @@
       "bytes": 14743,
       "lines": 342
     },
-    {
-      "path": "frontend/shared/admin.js",
-      "bytes": 14410,
-      "lines": 268
-    },
     {
       "path": "backend/features/heaven/market_context.py",
       "bytes": 13681,
       "lines": 338
     },
     {
-      "path": "frontend/shared/dashboard.js",
+      "path": "frontend/shared/session.js",
-      "bytes": 12894,
+      "bytes": 13219,
-      "lines": 274
+      "lines": 289
     },
     {
-      "path": "frontend/shared/session.js",
+      "path": "backend/features/system/service.py",
-      "bytes": 12848,
+      "bytes": 12937,
-      "lines": 283
+      "lines": 271
     },
     {
       "path": "backend/features/market/insights_auction_data.py",
@@ -569,9 +592,9 @@
       "lines": 318
     },
     {
-      "path": "backend/features/system/service.py",
+      "path": "backend/data/providers/tushare_indices.py",
-      "bytes": 12392,
+      "bytes": 10956,
-      "lines": 254
+      "lines": 248
     },
     {
       "path": "backend/features/market/insights_auction.py",
@@ -620,8 +643,8 @@
     },
     {
       "path": "backend/data/providers/tushare_daily.py",
-      "bytes": 6837,
+      "bytes": 6949,
-      "lines": 160
+      "lines": 168
     },
     {
       "path": "backend/application.py",
@@ -658,31 +681,26 @@
       "bytes": 6092,
       "lines": 138
     },
+    {
+      "path": "frontend/pages/market/stock-detail.js",
+      "bytes": 6041,
+      "lines": 134
+    },
     {
       "path": "frontend/pages/dragon-tiger/page.html",
       "bytes": 5754,
       "lines": 85
     },
     {
-      "path": "frontend/pages/market/stock-detail.js",
+      "path": "frontend/pages.config.js",
-      "bytes": 5690,
+      "bytes": 5385,
-      "lines": 124
+      "lines": 130
-    },
-    {
-      "path": "backend/data/providers/tushare_indices.py",
-      "bytes": 5451,
-      "lines": 118
     },
     {
       "path": "frontend/pages/market/search.js",
       "bytes": 5384,
       "lines": 131
     },
-    {
-      "path": "frontend/pages.config.js",
-      "bytes": 5380,
-      "lines": 130
-    },
     {
       "path": "frontend/pages/auction/page.html",
       "bytes": 5350,
@@ -769,14 +787,19 @@
       "lines": 63
     },
     {
-      "path": "backend/features/mentor/routes.py",
+      "path": "backend/data/providers/tushare_helpers.py",
-      "bytes": 2299,
+      "bytes": 2360,
-      "lines": 57
+      "lines": 75
     },
     {
       "path": "backend/jobs/service.py",
-      "bytes": 2219,
+      "bytes": 2337,
-      "lines": 60
+      "lines": 59
+    },
+    {
+      "path": "backend/features/mentor/routes.py",
+      "bytes": 2299,
+      "lines": 57
     },
     {
       "path": "backend/features/screener/regime.py",
@@ -793,11 +816,6 @@
       "bytes": 2165,
       "lines": 35
     },
-    {
-      "path": "backend/data/providers/tushare_helpers.py",
-      "bytes": 2083,
-      "lines": 64
-    },
     {
       "path": "frontend/pages/market/breadth.js",
       "bytes": 2071,
@@ -808,6 +826,11 @@
       "bytes": 1919,
       "lines": 45
     },
+    {
+      "path": "backend/jobs/refresh.py",
+      "bytes": 1808,
+      "lines": 48
+    },
     {
       "path": "backend/features/system/routes.py",
       "bytes": 1791,

config/data-fields.config.json

@@ -2,6 +2,7 @@
   "schema_version": 1,
   "providers": {
     "tushare": {"class": "licensed", "calculation_allowed": true},
+    "datahub": {"class": "licensed", "calculation_allowed": true},
     "ifind": {"class": "licensed", "calculation_allowed": true},
     "eastmoney": {"class": "public_web", "calculation_allowed": false},
     "tencent": {"class": "public_web", "calculation_allowed": false},

config/datahub.config.json

@@ -0,0 +1,25 @@
+{
+  "schema_version": 1,
+  "base_url": "http://127.0.0.1:8766",
+  "timeout_seconds": 8,
+  "retries": 1,
+  "page_limit": 5000,
+  "stale_seconds_max": 86400,
+  "datasets": {
+    "calendar": { "read": true, "shadow": false },
+    "stocks": { "read": true, "shadow": false },
+    "daily": { "read": true, "shadow": false },
+    "index_daily": { "read": true, "shadow": false },
+    "valuation": { "read": true, "shadow": false },
+    "moneyflow": { "read": true, "shadow": false },
+    "auction": { "read": true, "shadow": false },
+    "limit_events": { "read": true, "shadow": false },
+    "popularity": { "read": true, "shadow": false },
+    "dragon_tiger": { "read": true, "shadow": false },
+    "sector_daily": { "read": true, "shadow": false },
+    "quotes": { "read": true, "shadow": false },
+    "index_quotes": { "read": true, "shadow": false },
+    "intraday": { "read": true, "shadow": false },
+    "status": { "read": true, "shadow": false }
+  }
+}

docs/README.md

@@ -32,4 +32,4 @@
 
 - 旧文档不能删：被替代的旧文档开头要加一行「⚠️ 本文档已过时，仅留档备查，请勿删除」，再写新版。
 - 用中文大白话写，专业词要带通俗解释，让不懂代码的人也能看懂。
-- 「问天」板块是冻结区，任何改动都不许碰；写文档时别误导后来人去改它。
+- 「问天」不是永久冻结区：此前只冻结过界面视觉方案，现已解冻。问天可纳入后续数据与功能迁移，不要再写成“永远不碰”。

docs/governance/architecture-inventory.json

@@ -213,12 +213,12 @@
     {
       "provider": "eastmoney",
       "path": "realtime_aggregator.py",
-      "runtime_role": "isolated realtime observation"
+      "runtime_role": "isolated realtime observation and intraday dashboard fallback"
     },
     {
       "provider": "tencent",
       "path": "realtime_aggregator.py",
-      "runtime_role": "index observation fallback"
+      "runtime_role": "index observation and intraday quote fallback"
     }
   ],
   "llm_entrypoints": [

docs/任务清单.md

@@ -7,6 +7,7 @@
 | 任务 | 说明 | 状态 |
 |---|---|---|
 | 全站视觉统一改造收尾 | 主线。17 个阶段已完成，正在最终验收、代码合并 | 收尾中 |
+| 行情刷新误报与旧数据提示 | HEL-412：高级接口未到齐不再记整次失败；今日正式数据晚到时提示当前展示日期 | 施工中 |
 | 手机端独立重新设计 | 先出视觉/交互规范和技术架构方案，等老板确认后再施工 | 方案送审中 |
 
 ## 已做完

docs/项目需求.md

@@ -29,11 +29,11 @@
 - **智能工具类（3 个）**：智能选股、问师、问天。
 - **个人类（1 个）**：我的复盘。
 
-其中「问天」是冻结区（见下面的硬规矩）。
+其中「问天」此前只在全站视觉改造阶段冻结过界面方案，现已解冻；问天可以纳入后续数据与功能迁移，但不等于本阶段要重做视觉。
 
 ## 几条硬规矩（不能破坏的边界）
 
-- 「问天」板块是**冻结区**，任何改动都不许碰它。
+- 「问天」板块**不是永久冻结区**：此前冻结的是界面视觉方案，现已解冻。问天现有功能与界面不要破坏；后续数据与功能迁移可以纳入，不主动重做视觉。
 - **不用假数据冒充真行情**；数据缺失就明说“没有/不可用”，不能编。
 - **每个用户自己的数据互相隔离**（自选、复盘、对话、问天历史等），看不到别人的。
 - **计算由程序确定性完成**（情绪周期、智能选股、问天排盘等），AI 大模型（LLM，就是会聊天的那个 AI）只负责解释或编译自然语言条件，不能改计算结果。

frontend/index.html

@@ -611,6 +611,7 @@
         <label class="form-field"><span>iFinD Refresh Token</span><input id="systemIfindTokenInput" type="password" autocomplete="off" maxlength="2048" placeholder="留空保留现有 Token"></label>
         <label class="switch-control"><input id="systemBackgroundRefresh" type="checkbox"><span>启用交易时段后台刷新</span></label>
         <p class="form-hint">所有用户读取同一份后台快照，页面不会随后台任务自动重绘。</p>
+        <div id="datahubRouteStatus" class="admin-refresh-status" data-tone="idle" role="status" aria-live="polite"><i data-lucide="database"></i><span>数据中枢线路待检查</span></div>
         <div id="adminRefreshStatus" class="admin-refresh-status" data-tone="idle" role="status" aria-live="polite"><i data-lucide="circle-dot"></i><span>尚未手动刷新</span></div>
         <div class="dialog-actions admin-inline-actions"><button id="adminRefreshButton" class="button" type="button"><i data-lucide="refresh-cw"></i>立即后台刷新</button><button class="button primary" type="submit">保存行情配置</button></div>
       </form>

frontend/login/index.html

@@ -19,9 +19,9 @@
       document.documentElement.style.colorScheme = theme;
     })();
   </script>
-  <link rel="stylesheet" href="/shared/tokens.css?v=20260829-hel240">
+  <link rel="stylesheet" href="/shared/tokens.css?v=20260829-hel251">
   <link rel="stylesheet" href="/shared/base.css?v=20260806-1">
-  <link rel="stylesheet" href="/shared/auth.css?v=20260829-hel240b">
+  <link rel="stylesheet" href="/shared/auth.css?v=20260829-hel251">
   <link rel="stylesheet" href="/shared/components/controls.css?v=20260820-2">
 </head>
 <body class="login-portal">
@@ -33,6 +33,73 @@
         <p class="login-brand-subtitle">A股个人复盘工作台</p>
       </div>
     </div>
+    <div class="login-mascots" id="loginMascots" aria-hidden="true" data-mood="idle">
+      <div class="login-mascots-stage">
+        <div class="login-mascot is-red">
+          <div class="login-mascot-breathe">
+            <div class="login-mascot-lean">
+              <svg class="login-mascot-figure" viewBox="0 0 96 210" focusable="false">
+                <ellipse class="login-mascot-shadow" cx="48" cy="200" rx="26" ry="5.5"></ellipse>
+                <line class="login-mascot-wick" x1="48" y1="10" x2="48" y2="50"></line>
+                <rect class="login-mascot-body" x="16" y="50" width="64" height="126" rx="14"></rect>
+                <line class="login-mascot-wick" x1="48" y1="176" x2="48" y2="190"></line>
+                <g class="login-mascot-face">
+                  <circle class="login-mascot-eye" cx="36" cy="94" r="10"></circle>
+                  <circle class="login-mascot-eye" cx="60" cy="94" r="10"></circle>
+                  <circle class="login-mascot-pupil" cx="36" cy="94" r="4.2"></circle>
+                  <circle class="login-mascot-pupil" cx="60" cy="94" r="4.2"></circle>
+                  <rect class="login-mascot-lid" x="24" y="82" width="48" height="24" rx="10"></rect>
+                  <path class="login-mascot-happy" d="M28 96 Q36 88 44 96"></path>
+                  <path class="login-mascot-happy" d="M52 96 Q60 88 68 96"></path>
+                  <circle class="login-mascot-sad" cx="36" cy="96" r="2.2"></circle>
+                  <circle class="login-mascot-sad" cx="60" cy="96" r="2.2"></circle>
+                </g>
+                <ellipse class="login-mascot-arm is-left" cx="16" cy="128" rx="8" ry="5.5"></ellipse>
+                <ellipse class="login-mascot-arm is-right" cx="80" cy="128" rx="8" ry="5.5"></ellipse>
+                <ellipse class="login-mascot-hand is-left" cx="16" cy="128" rx="9" ry="7"></ellipse>
+                <ellipse class="login-mascot-hand is-right" cx="80" cy="128" rx="9" ry="7"></ellipse>
+              </svg>
+            </div>
+          </div>
+        </div>
+        <div class="login-mascot is-green">
+          <div class="login-mascot-breathe">
+            <div class="login-mascot-lean">
+              <div class="login-mascot-figure">
+                <svg class="login-mascot-front" viewBox="0 0 84 175" focusable="false">
+                  <ellipse class="login-mascot-shadow" cx="42" cy="166" rx="22" ry="4.5"></ellipse>
+                  <line class="login-mascot-wick" x1="42" y1="8" x2="42" y2="42"></line>
+                  <rect class="login-mascot-body" x="15" y="42" width="54" height="104" rx="12"></rect>
+                  <line class="login-mascot-wick" x1="42" y1="146" x2="42" y2="158"></line>
+                  <g class="login-mascot-face">
+                    <circle class="login-mascot-eye" cx="32" cy="76" r="8.5"></circle>
+                    <circle class="login-mascot-eye" cx="52" cy="76" r="8.5"></circle>
+                    <circle class="login-mascot-pupil" cx="32" cy="76" r="3.6"></circle>
+                    <circle class="login-mascot-pupil" cx="52" cy="76" r="3.6"></circle>
+                    <rect class="login-mascot-lid" x="22" y="66" width="40" height="20" rx="8"></rect>
+                    <path class="login-mascot-happy" d="M25 78 Q32 71 39 78"></path>
+                    <path class="login-mascot-happy" d="M45 78 Q52 71 59 78"></path>
+                    <circle class="login-mascot-sad" cx="32" cy="78" r="1.9"></circle>
+                    <circle class="login-mascot-sad" cx="52" cy="78" r="1.9"></circle>
+                  </g>
+                  <ellipse class="login-mascot-arm is-left" cx="15" cy="108" rx="7" ry="4.5"></ellipse>
+                  <ellipse class="login-mascot-arm is-right" cx="69" cy="108" rx="7" ry="4.5"></ellipse>
+                </svg>
+                <svg class="login-mascot-back" viewBox="0 0 84 175" focusable="false">
+                  <ellipse class="login-mascot-shadow" cx="42" cy="166" rx="22" ry="4.5"></ellipse>
+                  <line class="login-mascot-wick" x1="42" y1="8" x2="42" y2="42"></line>
+                  <rect class="login-mascot-body" x="15" y="42" width="54" height="104" rx="12"></rect>
+                  <line class="login-mascot-wick" x1="42" y1="146" x2="42" y2="158"></line>
+                  <rect class="login-mascot-slit" x="40.5" y="58" width="3" height="72" rx="1.5"></rect>
+                  <ellipse class="login-mascot-arm is-left" cx="15" cy="108" rx="7" ry="4.5"></ellipse>
+                  <ellipse class="login-mascot-arm is-right" cx="69" cy="108" rx="7" ry="4.5"></ellipse>
+                </svg>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
     <div class="login-brand-copy">
       <p class="login-brand-kicker">收盘之后 · 复盘开始</p>
       <h1 class="login-brand-title">看懂情绪周期，把复盘变成下一次的先手。</h1>
@@ -90,6 +157,6 @@
     <section class="login-card" id="loginCard" aria-live="polite"></section>
   </main>
   <script src="/shared/api.js?v=20260803-2"></script>
-  <script src="/login/page.js?v=20260829-hel240"></script>
+  <script src="/login/page.js?v=20260829-hel251"></script>
 </body>
 </html>

frontend/login/page.js

@@ -15,6 +15,7 @@
     error: "",
     username: "",
     password: "",
+    passwordVisible: false,
   };
 
   function escapeHtml(value) {
@@ -77,9 +78,22 @@
     return chips.join("");
   }
 
+  function returnPath() {
+    const raw = new URLSearchParams(global.location.search).get("next") || "";
+    if (!raw) return "/";
+    try {
+      const url = new URL(raw, global.location.origin);
+      if (url.origin !== global.location.origin) return "/";
+      const path = url.pathname || "/";
+      if (path === "/login" || path.startsWith("/login/")) return "/";
+      return `${path}${url.search}${url.hash}` || "/";
+    } catch (_error) {
+      return "/";
+    }
+  }
+
   function enterApp() {
-    const next = new URLSearchParams(global.location.search).get("next");
+    global.location.replace(returnPath());
-    global.location.replace(next && next.startsWith("/") ? next : "/");
   }
 
   function formMarkup(options) {
@@ -89,6 +103,8 @@
     const lead = options.lead;
     const hint = options.hint;
     const invalid = state.error ? " is-invalid" : "";
+    const passwordType = state.passwordVisible ? "text" : "password";
+    const passwordToggle = state.passwordVisible ? "隐藏" : "显示";
     return [
       options.back
         ? '<button class="login-back" type="button" data-login-action="picker">返回账号列表</button>'
@@ -101,7 +117,7 @@
       "</div>",
       '<form class="login-form" id="loginForm">',
       `<label class="form-field"><span>账号名</span><input id="loginUsername" type="text" minlength="3" maxlength="30" autocomplete="username" placeholder="请输入账号名" value="${escapeHtml(state.username)}" required></label>`,
-      `<label class="form-field"><span>密码</span><input id="loginPassword" class="${invalid.trim()}" type="password" minlength="8" maxlength="128" autocomplete="${registering ? "new-password" : "current-password"}" placeholder="请输入密码" value="${escapeHtml(state.password)}" required></label>`,
+      `<label class="form-field"><span>密码</span><span class="login-password-wrap"><input id="loginPassword" class="${invalid.trim()}" type="${passwordType}" minlength="8" maxlength="128" autocomplete="${registering ? "new-password" : "current-password"}" placeholder="请输入密码" value="${escapeHtml(state.password)}" required><button class="login-password-toggle" type="button" data-login-action="toggle-password" aria-pressed="${state.passwordVisible ? "true" : "false"}" aria-label="${state.passwordVisible ? "隐藏密码" : "显示密码"}">${passwordToggle}</button></span></label>`,
       `<label class="form-field" id="loginConfirmField"${registering ? "" : " hidden"}><span>确认密码</span><input id="loginPasswordConfirm" type="password" minlength="8" maxlength="128" autocomplete="new-password"${registering ? " required" : ""}></label>`,
       state.error ? `<p class="login-error">${escapeHtml(state.error)}</p>` : '<p class="login-error" hidden></p>',
       `<button class="button primary login-submit" type="submit"${state.loading ? " disabled" : ""}>`,
@@ -120,7 +136,7 @@
       "login-account-row",
       current ? "is-current" : "",
       confirming ? "is-confirming" : "",
-      !managing && !current ? "is-switchable" : "",
+      !managing ? "is-switchable" : "",
     ].filter(Boolean).join(" ");
     if (managing && confirming) {
       return [
@@ -138,11 +154,12 @@
     const action = managing
       ? `<button class="login-account-remove" type="button" data-confirm-id="${account.user_id}" aria-label="移除 ${escapeHtml(account.username)}"><svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M6 2h4l.5 1H14v1H2V3h3.5L6 2zm1 4v6H6V6h1zm3 0v6H9V6h1zM3.5 5H13l-.7 8.2A1.5 1.5 0 0 1 10.81 14H5.19a1.5 1.5 0 0 1-1.49-1.8L3.5 5z"></path></svg></button>`
       : current
-        ? '<span class="login-account-check" aria-hidden="true">✓</span>'
+        ? '<span class="login-account-action"><span class="login-account-check" aria-hidden="true">✓</span>继续使用</span>'
         : "";
     const switchAttr = !managing && !current ? ` data-switch-id="${account.user_id}"` : "";
+    const resumeAttr = !managing && current ? ` data-resume-id="${account.user_id}"` : "";
     return [
-      `<div class="${classes}" data-user-id="${account.user_id}"${switchAttr}>`,
+      `<div class="${classes}" data-user-id="${account.user_id}"${switchAttr}${resumeAttr}>`,
       `<span class="login-avatar tone-${tone}" aria-hidden="true">${glyph}</span>`,
       '<div class="login-account-meta">',
       '<div class="login-account-name">',
@@ -160,6 +177,9 @@
     const count = state.accounts.length;
     const managing = state.view === "manage";
     return [
+      managing
+        ? ""
+        : '<button class="login-back" type="button" data-login-action="resume">返回复盘</button>',
       `<h2 class="login-card-title">${managing ? "管理账号记录" : "选择账号"}</h2>`,
       `<p class="login-card-lead">${managing
         ? "移除只删除这台电脑上的登录记录，不会注销账号"
@@ -197,6 +217,7 @@
       card.innerHTML = pickerMarkup();
     }
     bindCard();
+    if (mascots) mascots.sync();
   }
 
   function bindCard() {
@@ -210,6 +231,14 @@
     card.querySelectorAll("[data-login-action]").forEach((button) => {
       button.addEventListener("click", () => {
         const action = button.dataset.loginAction;
+        if (action === "toggle-password") {
+          togglePasswordVisible();
+          return;
+        }
+        if (action === "resume") {
+          resumeCurrentAccount();
+          return;
+        }
         if (action === "picker") {
           state.view = state.accounts.length ? "picker" : "first";
           state.confirmingId = null;
@@ -228,6 +257,9 @@
     card.querySelectorAll("[data-switch-id]").forEach((button) => {
       button.addEventListener("click", () => switchAccount(Number(button.dataset.switchId)));
     });
+    card.querySelectorAll("[data-resume-id]").forEach((button) => {
+      button.addEventListener("click", () => resumeCurrentAccount());
+    });
     card.querySelectorAll("[data-confirm-id]").forEach((button) => {
       button.addEventListener("click", (event) => {
         event.stopPropagation();
@@ -269,11 +301,13 @@
     render();
     try {
       await api.request(`/api/auth/${state.mode}`, "POST", { username, password });
+      await celebrateLogin();
       enterApp();
     } catch (error) {
       state.loading = false;
       setError(error.message || "账号操作失败");
       render();
+      mascots.fail();
     }
   }
 
@@ -291,6 +325,27 @@
     }
   }
 
+  async function resumeCurrentAccount() {
+    state.loading = true;
+    setError("");
+    render();
+    try {
+      const session = await api.request("/api/auth/me");
+      const sessionUserId = session.user?.id;
+      const matches = Boolean(session.authenticated) && (
+        !state.currentUserId || Number(sessionUserId) === Number(state.currentUserId)
+      );
+      if (!matches) {
+        throw new Error("当前会话已失效，请重新登录");
+      }
+      enterApp();
+    } catch (error) {
+      state.loading = false;
+      setError(error.message || "当前会话已失效，请重新登录");
+      render();
+    }
+  }
+
   async function forgetAccount(userId) {
     try {
       await api.request("/api/auth/forget", "POST", { user_id: userId });
@@ -305,6 +360,241 @@
     }
   }
 
+  function togglePasswordVisible() {
+    state.passwordVisible = !state.passwordVisible;
+    const input = document.querySelector("#loginPassword");
+    const button = document.querySelector(".login-password-toggle");
+    if (input) {
+      input.type = state.passwordVisible ? "text" : "password";
+      input.focus();
+    }
+    if (button) {
+      button.textContent = state.passwordVisible ? "隐藏" : "显示";
+      button.setAttribute("aria-pressed", state.passwordVisible ? "true" : "false");
+      button.setAttribute("aria-label", state.passwordVisible ? "隐藏密码" : "显示密码");
+    }
+    mascots.sync();
+  }
+
+  function reducedMotion() {
+    return Boolean(global.matchMedia && global.matchMedia("(prefers-reduced-motion: reduce)").matches);
+  }
+
+  function finePointer() {
+    return Boolean(global.matchMedia && global.matchMedia("(pointer: fine)").matches);
+  }
+
+  function wait(ms) {
+    return new Promise((resolve) => global.setTimeout(resolve, ms));
+  }
+
+  async function celebrateLogin() {
+    mascots.succeed();
+    if (!reducedMotion()) await wait(720);
+  }
+
+  const mascots = (() => {
+    const root = document.querySelector("#loginMascots");
+    const red = root && root.querySelector(".login-mascot.is-red");
+    const green = root && root.querySelector(".login-mascot.is-green");
+    const motion = {
+      pupilX: 0,
+      pupilY: 0,
+      targetX: 0,
+      targetY: 0,
+      leanRed: 0,
+      leanGreen: 0,
+      targetLeanRed: 0,
+      targetLeanGreen: 0,
+    };
+    let mood = "idle";
+    let locked = "";
+    let blinkTimer = 0;
+    let failTimer = 0;
+    let raf = 0;
+
+    function setVars() {
+      if (!red || !green) return;
+      const pupilX = `${motion.pupilX.toFixed(2)}px`;
+      const pupilY = `${motion.pupilY.toFixed(2)}px`;
+      red.style.setProperty("--pupil-x", pupilX);
+      red.style.setProperty("--pupil-y", pupilY);
+      green.style.setProperty("--pupil-x", pupilX);
+      green.style.setProperty("--pupil-y", pupilY);
+      red.style.setProperty("--lean", `${motion.leanRed.toFixed(2)}deg`);
+      green.style.setProperty("--lean", `${motion.leanGreen.toFixed(2)}deg`);
+    }
+
+    function poseFor(next) {
+      if (next === "account" || next === "busy") {
+        motion.targetX = 3.2;
+        motion.targetY = 0.8;
+        motion.targetLeanRed = 7;
+        motion.targetLeanGreen = 5.6;
+        return;
+      }
+      if (next === "password") {
+        motion.targetX = 0;
+        motion.targetY = 0;
+        motion.targetLeanRed = 0;
+        motion.targetLeanGreen = 0;
+        return;
+      }
+      if (next === "fail") {
+        motion.targetX = 0;
+        motion.targetY = 2.8;
+        motion.targetLeanRed = 8;
+        motion.targetLeanGreen = 8;
+        return;
+      }
+      if (next === "success") {
+        motion.targetX = 0;
+        motion.targetY = 0;
+        motion.targetLeanRed = 0;
+        motion.targetLeanGreen = 0;
+        return;
+      }
+      if (!finePointer()) {
+        motion.targetX = 2.4;
+        motion.targetY = 0.4;
+        motion.targetLeanRed = 4;
+        motion.targetLeanGreen = 3.2;
+        return;
+      }
+      motion.targetLeanRed = 0;
+      motion.targetLeanGreen = 0;
+    }
+
+    function applyMood(next) {
+      if (!root) return;
+      const changed = next !== mood;
+      if (changed) {
+        mood = next;
+        root.dataset.mood = next;
+        poseFor(next);
+      } else if (next !== "idle") {
+        poseFor(next);
+      }
+      if (reducedMotion()) {
+        motion.pupilX = motion.targetX;
+        motion.pupilY = motion.targetY;
+        motion.leanRed = motion.targetLeanRed;
+        motion.leanGreen = motion.targetLeanGreen;
+        setVars();
+      }
+    }
+
+    function focusedControl() {
+      const active = document.activeElement;
+      if (!active || !card.contains(active)) return "";
+      if (active.classList.contains("login-password-toggle")) return "loginPassword";
+      return active.id || "";
+    }
+
+    function desiredMood() {
+      if (locked === "success") return "success";
+      if (state.loading) return "busy";
+      const focused = focusedControl();
+      if (focused === "loginPassword" || focused === "loginPasswordConfirm") return "password";
+      if (focused === "loginUsername") return "account";
+      if (locked === "fail") return "fail";
+      return "idle";
+    }
+
+    function sync() {
+      applyMood(desiredMood());
+    }
+
+    function succeed() {
+      locked = "success";
+      applyMood("success");
+    }
+
+    function fail() {
+      locked = "fail";
+      applyMood("fail");
+      global.clearTimeout(failTimer);
+      failTimer = global.setTimeout(() => {
+        if (locked === "fail") locked = "";
+        sync();
+      }, 900);
+    }
+
+    function blink() {
+      if (!root || reducedMotion()) return;
+      if (mood !== "idle" && mood !== "account" && mood !== "busy") return;
+      root.classList.remove("is-blinking");
+      void root.offsetWidth;
+      root.classList.add("is-blinking");
+      global.setTimeout(() => root.classList.remove("is-blinking"), 160);
+    }
+
+    function scheduleBlink() {
+      global.clearTimeout(blinkTimer);
+      if (reducedMotion()) return;
+      const waitMs = 4000 + Math.random() * 2000;
+      blinkTimer = global.setTimeout(() => {
+        blink();
+        scheduleBlink();
+      }, waitMs);
+    }
+
+    function onMouseMove(event) {
+      if (reducedMotion() || !finePointer()) return;
+      if (desiredMood() !== "idle") return;
+      const rect = root.getBoundingClientRect();
+      const cx = rect.left + rect.width * 0.42;
+      const cy = rect.top + rect.height * 0.42;
+      const dx = event.clientX - cx;
+      const dy = event.clientY - cy;
+      const dist = Math.hypot(dx, dy) || 1;
+      const cap = 3.5;
+      motion.targetX = (dx / dist) * Math.min(cap, Math.abs(dx) / 90);
+      motion.targetY = (dy / dist) * Math.min(cap, Math.abs(dy) / 90);
+      const tilt = Math.max(-5, Math.min(5, (dx / Math.max(global.innerWidth, 1)) * 10));
+      motion.targetLeanRed = tilt;
+      motion.targetLeanGreen = tilt * 0.8;
+    }
+
+    function tick() {
+      if (!root) return;
+      if (!reducedMotion()) {
+        motion.pupilX += (motion.targetX - motion.pupilX) * 0.18;
+        motion.pupilY += (motion.targetY - motion.pupilY) * 0.18;
+        motion.leanRed += (motion.targetLeanRed - motion.leanRed) * 0.18;
+        motion.leanGreen += (motion.targetLeanGreen - motion.leanGreen) * 0.18;
+        setVars();
+      } else {
+        motion.pupilX = motion.targetX;
+        motion.pupilY = motion.targetY;
+        motion.leanRed = motion.targetLeanRed;
+        motion.leanGreen = motion.targetLeanGreen;
+        setVars();
+      }
+      raf = global.requestAnimationFrame(tick);
+    }
+
+    function onFocusChange() {
+      global.requestAnimationFrame(sync);
+    }
+
+    if (root) {
+      document.addEventListener("focusin", onFocusChange);
+      document.addEventListener("focusout", onFocusChange);
+      global.addEventListener("mousemove", onMouseMove, { passive: true });
+      if (!reducedMotion()) {
+        raf = global.requestAnimationFrame(tick);
+        scheduleBlink();
+      } else {
+        poseFor("idle");
+        setVars();
+      }
+      sync();
+    }
+
+    return { sync, succeed, fail };
+  })();
+
   themeButton.addEventListener("click", () => {
     applyTheme(document.documentElement.dataset.theme === "dark" ? "light" : "dark", true);
   });

frontend/m/js/pages.js

@@ -770,11 +770,33 @@
     scroll.classList.add("m-motion-fade-in");
   }
 
+  function dashboardFreshnessNotice() {
+    const meta = (state.dashboard && state.dashboard.meta) || {};
+    if (meta.display_notice) return String(meta.display_notice);
+    const requested = String(meta.requested_date || "").replace(/-/g, "");
+    const actual = String(meta.trade_date || "").replace(/-/g, "");
+    const compact = actual;
+    const shown = /^\d{8}$/.test(compact)
+      ? (Number(compact.slice(4, 6)) + " 月 " + Number(compact.slice(6, 8)) + " 日")
+      : "";
+    if (meta.data_status === "preparing" || (meta.carried_forward && actual && requested && actual !== requested)) {
+      return shown ? ("今日数据正在准备，当前展示 " + shown) : "今日数据正在准备，当前展示最近可用数据";
+    }
+    if (meta.data_status === "partial" || meta.limit_data_source === "derived") {
+      return meta.notice || "部分正式数据尚未到齐，当前展示日线推算结果";
+    }
+    return "";
+  }
+
   function renderTopArea(key) {
     const page = document.querySelector(".m-page");
     if (!page) return;
     let top = page.querySelector(".m-top");
     let html = buildStrip();
+    const freshness = dashboardFreshnessNotice();
+    if (freshness) {
+      html = '<div class="m-phase-notice"><strong>' + escapeHtml(freshness) + "</strong></div>" + html;
+    }
     if (key === "market/performance") html += performanceConclusion();
     if (!top) {
       top = document.createElement("div");
@@ -5197,6 +5219,15 @@
     return '<span class="m-sys-dot' + (ok ? " m-sys-dot--ok" : "") + '"></span>';
   }
 
+  function datahubStatusText(hub) {
+    const enabled = number(hub.enabled_reads);
+    const total = number(hub.total_reads) || enabled;
+    const fallbacks = hub.fallback_labels || [];
+    if (fallbacks.length) return " 备用 " + fallbacks.join("、");
+    if (hub.configured) return " 主线路 " + enabled + "/" + total;
+    return " 未配置";
+  }
+
   function renderSystemAdmin(key) {
     if (key === "system/members") {
       renderSystemMembers();
@@ -5215,6 +5246,7 @@
       '<div class="m-sys-status-item"><span>iFinD</span><span>' + statusDot(ifind.configured) + (ifind.configured ? " 已配置" : " 未配置") + "</span></div>" +
       '<div class="m-sys-status-item"><span>行情快照</span><strong>' + number(data.snapshot_dates) + " 个交易日</strong></div>" +
       '<div class="m-sys-status-item"><span>后台刷新</span><span>' + statusDot(data.background_refresh_enabled) + (data.background_refresh_enabled ? " 已启用" : " 已暂停") + "</span></div>" +
+      '<div class="m-sys-status-item"><span>数据中枢</span><span>' + statusDot(Boolean((data.datahub || {}).configured) && !((data.datahub || {}).fallback_count)) + datahubStatusText(data.datahub || {}) + "</span></div>" +
       "</div></div>" +
       '<div class="m-card m-sys-section"><strong>数据源密钥</strong>' +
       formFieldHtml("Tushare Token", '<input id="m-sys-token" type="password" autocomplete="off" minlength="20" placeholder="留空则保留现有 Token">', false) +

frontend/pages.config.js

@@ -95,7 +95,7 @@
     "/shared/table.js?v=20260803-1",
     "/shared/theme.js?v=20260803-1",
     "/shared/dashboard.js?v=20260820-1",
-    "/shared/session.js?v=20260803-1",
+    "/shared/session.js?v=20260829-hel243",
     "/shared/admin.js?v=20260803-1",
     "/app.js?v=20260803-2",
   ];

frontend/pages/market/preview.js

@@ -367,7 +367,11 @@ function selectStockPreviewChart(chart) {
     }
   } else if ((payload.prices || []).length) {
     setText("stockPreviewDate", payload.meta?.trade_date || "最新行情");
-    setText("stockPreviewSource", `日 K 行情 · ${payload.prices.length} 个交易日`);
+    const notice = String(payload.meta?.notice || "").trim();
+    setText(
+      "stockPreviewSource",
+      notice ? `日 K 行情 · ${payload.prices.length} 个交易日 · ${notice}` : `日 K 行情 · ${payload.prices.length} 个交易日`,
+    );
     drawDailyPreviewChart(payload.prices);
   } else {
     setText("stockPreviewDate", payload.meta?.trade_date || "最新行情");

frontend/pages/market/stock-detail.js

@@ -52,7 +52,11 @@ async function openStock(code, fallback = null) {
     renderStockNotes(payload.notes || []);
     updateWatchButton();
     if (state.stockDetailChartMode === "daily") {
-      setText("chartSource", `日 K 行情 · ${payload.prices.length} 个交易日`);
+      const notice = String(payload.meta?.notice || "").trim();
+      setText(
+        "chartSource",
+        notice ? `日 K 行情 · ${payload.prices.length} 个交易日 · ${notice}` : `日 K 行情 · ${payload.prices.length} 个交易日`,
+      );
       requestAnimationFrame(() => drawPriceChart(payload.prices || []));
     }
   } catch (error) {
@@ -69,7 +73,13 @@ async function selectStockDetailChart(mode) {
   syncDetailChartButtons("stock", selected);
   if (selected === "daily") {
     const prices = state.stockDetail?.prices || [];
-    setText("chartSource", prices.length ? `日 K 行情 · ${prices.length} 个交易日` : "正在加载行情");
+    const notice = String(state.stockDetail?.meta?.notice || "").trim();
+    setText(
+      "chartSource",
+      prices.length
+        ? (notice ? `日 K 行情 · ${prices.length} 个交易日 · ${notice}` : `日 K 行情 · ${prices.length} 个交易日`)
+        : "正在加载行情",
+    );
     if (prices.length) requestAnimationFrame(() => drawPriceChart(prices));
     else clearPriceChart("正在加载日 K 数据");
     return;

frontend/shared/admin.js

@@ -44,6 +44,7 @@ async function openAdminSettings(refreshOnly = false) {
     status.textContent = `Tushare ${data.configured ? "已配置" : "未配置"} · iFinD ${ifind.configured ? "已配置" : "未配置"} · ${number(data.snapshot_dates)} 个交易日`;
     status.classList.toggle("connected", Boolean(data.configured));
     setText("systemDataStatus", data.background_refresh_enabled ? "后台刷新已启用" : "后台刷新已暂停");
+    renderDatahubRouteStatus(data.datahub || {});
     document.querySelector("#systemTokenInput").value = "";
     document.querySelector("#systemIfindTokenInput").value = "";
     document.querySelector("#systemBackgroundRefresh").checked = Boolean(data.background_refresh_enabled);
@@ -55,6 +56,26 @@ async function openAdminSettings(refreshOnly = false) {
   }
 }
 
+function renderDatahubRouteStatus(hub) {
+  const box = document.querySelector("#datahubRouteStatus");
+  if (!box) return;
+  const label = box.querySelector("span");
+  const enabled = number(hub.enabled_reads);
+  const total = number(hub.total_reads) || enabled;
+  const fallbacks = hub.fallback_labels || [];
+  if (fallbacks.length) {
+    box.dataset.tone = "warning";
+    if (label) label.textContent = `数据中枢主线路 ${enabled}/${total} · 备用 ${fallbacks.length} 类：${fallbacks.join("、")}`;
+    return;
+  }
+  box.dataset.tone = hub.configured ? "success" : "idle";
+  if (label) {
+    label.textContent = hub.configured
+      ? `数据中枢主线路 ${enabled}/${total}，当前无备用`
+      : "数据中枢尚未配置，网站仍走原接口";
+  }
+}
+
 function selectAdminPanel(panel) {
   const selected = ["market", "models", "members"].includes(panel) ? panel : "market";
   document.querySelector("#adminSectionSelect").value = selected;

frontend/shared/auth.css

@@ -1827,16 +1827,351 @@ body.login-portal {
   opacity: 0.72;
 }
 
-.login-brand-copy {
+.login-mascots {
   display: flex;
 
   flex: 1 1 auto;
 
+  align-items: center;
+
+  min-height: 0;
+
+  pointer-events: none;
+}
+
+.login-mascots-stage {
+  display: flex;
+
+  align-items: flex-end;
+
+  padding-left: calc(var(--login-mascot-height) * 82 / 210);
+
+  gap: calc(var(--login-mascot-height) * 10 / 210);
+}
+
+.login-mascot {
+  position: relative;
+
+  flex: 0 0 auto;
+
+  overflow: visible;
+
+  --pupil-x: 0px;
+
+  --pupil-y: 0px;
+
+  --lean: 0deg;
+}
+
+.login-mascot.is-red {
+  width: calc(var(--login-mascot-height) * 96 / 210);
+
+  height: var(--login-mascot-height);
+}
+
+.login-mascot.is-green {
+  width: calc(var(--login-mascot-height) * 84 / 210);
+
+  height: calc(var(--login-mascot-height) * 175 / 210);
+
+  perspective: 420px;
+}
+
+.login-mascot-breathe {
+  width: 100%;
+
+  height: 100%;
+
+  transform-origin: 50% 100%;
+}
+
+.login-mascots[data-mood="idle"] .login-mascot-breathe {
+  animation: login-mascot-breathe 3.6s ease-in-out infinite;
+}
+
+.login-mascot-lean {
+  width: 100%;
+
+  height: 100%;
+
+  transform: rotate(var(--lean));
+
+  transform-origin: 50% 88%;
+}
+
+.login-mascot.is-red .login-mascot-figure {
+  display: block;
+
+  width: 100%;
+
+  height: 100%;
+}
+
+.login-mascot.is-green .login-mascot-figure {
+  position: relative;
+
+  width: 100%;
+
+  height: 100%;
+
+  transform-style: preserve-3d;
+
+  transition: transform 280ms ease-in-out;
+}
+
+.login-mascot-front {
+  display: block;
+
+  width: 100%;
+
+  height: 100%;
+
+  backface-visibility: hidden;
+}
+
+.login-mascot-back {
+  position: absolute;
+
+  inset: 0;
+
+  display: block;
+
+  width: 100%;
+
+  height: 100%;
+
+  backface-visibility: hidden;
+
+  transform: rotateY(180deg);
+}
+
+.login-mascots[data-mood="password"] .login-mascot.is-green .login-mascot-figure {
+  transform: rotateY(180deg);
+}
+
+.login-mascot-body {
+  fill: var(--login-mascot-red);
+}
+
+.login-mascot.is-green .login-mascot-body {
+  fill: var(--login-mascot-green);
+}
+
+.login-mascot-wick {
+  stroke: var(--login-mascot-red);
+
+  stroke-width: 4;
+
+  stroke-linecap: round;
+}
+
+.login-mascot.is-green .login-mascot-wick {
+  stroke: var(--login-mascot-green);
+
+  stroke-width: 3.5;
+}
+
+.login-mascot-eye {
+  fill: var(--login-mascot-eye);
+}
+
+.login-mascot-pupil {
+  fill: var(--login-mascot-pupil);
+
+  transform: translate(var(--pupil-x), var(--pupil-y));
+
+  transform-box: fill-box;
+
+  transform-origin: center;
+}
+
+.login-mascot-lid {
+  fill: var(--login-mascot-red);
+
+  transform: scaleY(0);
+
+  transform-box: fill-box;
+
+  transform-origin: center;
+}
+
+.login-mascot.is-green .login-mascot-lid {
+  fill: var(--login-mascot-green);
+}
+
+.login-mascots.is-blinking .login-mascot-lid {
+  animation: login-mascot-blink 140ms ease-out;
+}
+
+.login-mascot-happy {
+  fill: none;
+
+  stroke: var(--login-mascot-pupil);
+
+  stroke-width: 2.4;
+
+  stroke-linecap: round;
+
+  opacity: 0;
+}
+
+.login-mascot-sad {
+  fill: var(--login-mascot-pupil);
+
+  opacity: 0;
+}
+
+.login-mascot-arm {
+  fill: var(--login-mascot-red);
+
+  transform-box: fill-box;
+
+  transform-origin: center;
+
+  transition: transform 250ms cubic-bezier(0.2, 0.9, 0.25, 1.2);
+}
+
+.login-mascot.is-green .login-mascot-arm {
+  fill: var(--login-mascot-green);
+}
+
+.login-mascot-hand {
+  fill: var(--login-mascot-red-shade);
+
+  opacity: 0;
+
+  transform-box: fill-box;
+
+  transform-origin: center;
+
+  transition: transform 250ms cubic-bezier(0.2, 0.9, 0.25, 1.2), opacity 180ms ease-out;
+}
+
+.login-mascots[data-mood="password"] .login-mascot.is-red .login-mascot-hand {
+  opacity: 1;
+}
+
+.login-mascots[data-mood="password"] .login-mascot.is-red .login-mascot-hand.is-left {
+  transform: translate(20px, -34px) scale(1.2);
+}
+
+.login-mascots[data-mood="password"] .login-mascot.is-red .login-mascot-hand.is-right {
+  transform: translate(-20px, -34px) scale(1.2);
+}
+
+.login-mascots[data-mood="password"] .login-mascot.is-red .login-mascot-arm.is-left {
+  transform: translate(10px, -18px) rotate(-18deg);
+}
+
+.login-mascots[data-mood="password"] .login-mascot.is-red .login-mascot-arm.is-right {
+  transform: translate(-10px, -18px) rotate(18deg);
+}
+
+.login-mascots[data-mood="password"] .login-mascot.is-red .login-mascot-pupil,
+.login-mascots[data-mood="password"] .login-mascot.is-red .login-mascot-eye {
+  opacity: 0;
+}
+
+.login-mascot-slit {
+  fill: var(--login-mascot-green-shade);
+}
+
+.login-mascot-shadow {
+  fill: rgba(6, 10, 24, 0.28);
+}
+
+.login-mascots[data-mood="success"] .login-mascot-pupil,
+.login-mascots[data-mood="success"] .login-mascot-lid,
+.login-mascots[data-mood="fail"] .login-mascot-pupil {
+  opacity: 0;
+}
+
+.login-mascots[data-mood="success"] .login-mascot-happy,
+.login-mascots[data-mood="fail"] .login-mascot-sad {
+  opacity: 1;
+}
+
+.login-mascots[data-mood="success"] .login-mascot.is-red .login-mascot-arm.is-left {
+  transform: translate(-2px, -36px) rotate(-48deg);
+}
+
+.login-mascots[data-mood="success"] .login-mascot.is-red .login-mascot-arm.is-right {
+  transform: translate(2px, -36px) rotate(48deg);
+}
+
+.login-mascots[data-mood="success"] .login-mascot.is-red {
+  animation: login-mascot-hop-red 450ms ease-in-out;
+}
+
+.login-mascots[data-mood="success"] .login-mascot.is-green {
+  animation: login-mascot-hop-green 450ms ease-in-out 80ms;
+}
+
+.login-mascots[data-mood="fail"] .login-mascot-arm {
+  transform: translateY(6px);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .login-mascots[data-mood="idle"] .login-mascot-breathe,
+  .login-mascots.is-blinking .login-mascot-lid,
+  .login-mascots[data-mood="success"] .login-mascot.is-red,
+  .login-mascots[data-mood="success"] .login-mascot.is-green {
+    animation: none;
+  }
+
+  .login-mascot.is-green .login-mascot-figure,
+  .login-mascot-hand,
+  .login-mascot-arm {
+    transition: none;
+  }
+}
+
+.login-password-wrap {
+  position: relative;
+
+  display: block;
+}
+
+.login-portal .login-password-wrap input {
+  padding-right: 48px;
+}
+
+.login-password-toggle {
+  position: absolute;
+
+  top: 50%;
+
+  right: 8px;
+
+  z-index: 1;
+
+  min-height: 24px;
+
+  padding: 0;
+
+  border: 0;
+
+  background: transparent;
+
+  color: var(--text-secondary);
+
+  font-size: var(--font-size-caption);
+
+  transform: translateY(-50%);
+
+  cursor: pointer;
+}
+
+.login-brand-copy {
+  display: flex;
+
+  flex: 0 0 auto;
+
   flex-direction: column;
 
   justify-content: flex-end;
 
-  padding: 24px 0 20px;
+  padding: 0 0 20px;
 }
 
 .login-brand-kicker {
@@ -2119,6 +2454,50 @@ body.login-portal {
   }
 }
 
+@keyframes login-mascot-breathe {
+  0%,
+  100% {
+    transform: scaleY(1);
+  }
+
+  50% {
+    transform: scaleY(1.015);
+  }
+}
+
+@keyframes login-mascot-blink {
+  0%,
+  100% {
+    transform: scaleY(0);
+  }
+
+  50% {
+    transform: scaleY(1);
+  }
+}
+
+@keyframes login-mascot-hop-red {
+  0%,
+  100% {
+    transform: translateY(0);
+  }
+
+  42% {
+    transform: translateY(-13px);
+  }
+}
+
+@keyframes login-mascot-hop-green {
+  0%,
+  100% {
+    transform: translateY(0);
+  }
+
+  42% {
+    transform: translateY(-11px);
+  }
+}
+
 .login-error {
   margin: 0;
 
@@ -2389,6 +2768,18 @@ body.login-portal {
   font-size: 16px;
 }
 
+.login-account-action {
+  display: grid;
+
+  justify-items: end;
+
+  gap: 2px;
+
+  color: var(--action);
+
+  font-size: var(--font-size-caption);
+}
+
 .login-account-remove {
   display: grid;
 
@@ -2454,7 +2845,8 @@ body.login-portal {
 
   .login-brand-copy,
   .login-brand-market,
-  .login-brand-disclaimer {
+  .login-brand-disclaimer,
+  .login-mascots {
     display: none;
   }
 

frontend/shared/dashboard.js

@@ -66,11 +66,18 @@ async function startAdminRefresh() {
     const requestedCompact = requestedDate.replaceAll("-", "");
     const actualCompact = actualDate.replaceAll("-", "");
     const updated = formatTimestamp(meta.updated_at);
-    if (actualCompact !== requestedCompact || meta.carried_forward) {
+    const freshness = dashboardFreshnessMessage(meta);
-      const reason = meta.notice ? `；${meta.notice}` : "";
+    if (meta.realtime && actualCompact === requestedCompact && !meta.carried_forward) {
-      setAdminRefreshStatus("warning", `刷新已完成，但没有获取到 ${requestedDate} 的最新行情；当前仍是 ${actualDate || "未知日期"}${reason}`, "triangle-alert");
+      setAdminRefreshStatus("success", `刷新成功：已获取 ${actualDate} 的盘中行情，更新时间 ${updated}`, "circle-check");
-      showToast("刷新完成，但未获取到所选日期的最新行情");
+      showToast(`刷新成功：已获取 ${actualDate} 的盘中行情`);
-    } else if (meta.notice) {
+      return;
+    }
+    if (freshness || actualCompact !== requestedCompact || meta.carried_forward || meta.limit_data_source === "derived") {
+      setAdminRefreshStatus("warning", freshness || `部分正式数据尚未到齐，当前展示 ${actualDate || "最近可用数据"}`, "triangle-alert");
+      setStatus(freshness || "部分正式数据尚未到齐，当前展示最近可用数据");
+      return;
+    }
+    if (meta.notice) {
       setAdminRefreshStatus("warning", `已刷新到 ${actualDate}（${updated}），但数据源提示：${meta.notice}`, "triangle-alert");
       showToast(`已刷新到 ${actualDate}，请留意数据源提示`);
     } else {
@@ -105,6 +112,37 @@ async function waitForAdminRefresh(jobKey) {
   throw new Error("刷新等待超时，请稍后重试");
 }
 
+let dashboardCatchupTimer = 0;
+
+function chineseMonthDay(value) {
+  const compact = String(value || "").replaceAll("-", "").replaceAll("/", "");
+  if (!/^\d{8}/.test(compact)) return "";
+  return `${Number(compact.slice(4, 6))} 月 ${Number(compact.slice(6, 8))} 日`;
+}
+
+function dashboardFreshnessMessage(meta = {}) {
+  if (meta.display_notice) return String(meta.display_notice);
+  const requested = String(meta.requested_date || "").replaceAll("-", "");
+  const actual = String(meta.trade_date || "").replaceAll("-", "");
+  const shown = chineseMonthDay(actual);
+  if (meta.data_status === "preparing" || (meta.carried_forward && actual && requested && actual !== requested)) {
+    return shown ? `今日数据正在准备，当前展示 ${shown}` : "今日数据正在准备，当前展示最近可用数据";
+  }
+  if (meta.data_status === "partial" || meta.limit_data_source === "derived") {
+    return meta.notice || "部分正式数据尚未到齐，当前展示日线推算结果";
+  }
+  return "";
+}
+
+function scheduleDashboardCatchup(meta = {}) {
+  window.clearTimeout(dashboardCatchupTimer);
+  const status = String(meta.data_status || "");
+  if (status !== "preparing" && status !== "partial") return;
+  dashboardCatchupTimer = window.setTimeout(() => {
+    loadDashboard(false, true, false);
+  }, 60000);
+}
+
 function applyDashboard(payload, background = false) {
   state.dashboard = payload;
   const selectedDate = payload.meta.requested_date || payload.meta.trade_date;
@@ -112,7 +150,11 @@ function applyDashboard(payload, background = false) {
   document.querySelector("#qiObservationDate").value = selectedDate;
   document.querySelector("#journalDate").value = selectedDate;
   renderDashboard();
-  setStatus(`${dashboardSourceLabel(payload.meta)} · 数据已更新`);
+  const freshness = dashboardFreshnessMessage(payload.meta || {});
+  setStatus(freshness || `${dashboardSourceLabel(payload.meta)} · 数据已更新`);
+  const updatedAt = document.querySelector("#updatedAt");
+  if (updatedAt) updatedAt.dataset.tone = freshness ? "warning" : "ok";
+  scheduleDashboardCatchup(payload.meta || {});
   if (!background) {
     if (state.activeView === "dragonView") loadDragonTiger();
     if (state.activeView === "screenerView") loadScreenerSetup();
@@ -180,7 +222,12 @@ function renderDashboard() {
     }
   }
   updateSentimentGauge(overview.sentiment_score);
-  setText("updatedAt", `${dashboardSourceLabel(meta)} · 更新 ${formatTimestamp(meta.updated_at)}`);
+  const freshness = dashboardFreshnessMessage(meta);
+  setText("updatedAt", freshness
+    ? freshness
+    : `${dashboardSourceLabel(meta)} · 更新 ${formatTimestamp(meta.updated_at)}`);
+  const updatedAt = document.querySelector("#updatedAt");
+  if (updatedAt) updatedAt.dataset.tone = freshness ? "warning" : "ok";
 
   renderLimitTable();
   renderLadderMini(ladders || []);

frontend/shared/session.js

@@ -196,7 +196,13 @@ async function changeAccountPassword(event) {
 
 async function switchAccount() {
   toggleAccountDropdown(false);
-  window.location.assign("/login/");
+  const params = new URLSearchParams();
+  const next = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+  if (next.startsWith("/") && !next.startsWith("//") && next !== "/login" && !next.startsWith("/login/") && !next.startsWith("/login?")) {
+    params.set("next", next);
+  }
+  const query = params.toString();
+  window.location.assign("/login/" + (query ? `?${query}` : ""));
 }
 
 

frontend/shared/shell.css

@@ -921,6 +921,10 @@ body.sidebar-collapsed .app-main {
   text-align: right;
 }
 
+.status-bar #updatedAt[data-tone="warning"] {
+  color: var(--warning);
+}
+
 .status-bar .risk-note {
   display: block;
 

frontend/shared/tokens.css

@@ -165,6 +165,13 @@
   --login-candle-up: #e07078;
   --login-candle-down: #3db88a;
   --login-trend-line: rgba(244, 247, 255, 0.88);
+  --login-mascot-red: #e8605a;
+  --login-mascot-red-shade: #c74a45;
+  --login-mascot-green: #46be93;
+  --login-mascot-green-shade: #37997a;
+  --login-mascot-eye: #f7f9fc;
+  --login-mascot-pupil: #1a2440;
+  --login-mascot-height: clamp(150px, 15vw, 260px);
 
   --font-size-aux: 11.5px;
   --font-size-caption: 12.5px;

tests/e2e/login-portal.spec.js

@@ -81,14 +81,58 @@ async function mockLoginPortal(page, options = {}) {
       return;
     }
     if (url.pathname === "/api/auth/me") {
+      const current = accounts.find((item) => Number(item.user_id) === Number(currentUserId)) || null;
+      const authenticated = Boolean(current) && !options.sessionExpired;
       await route.fulfill({
         status: 200,
         contentType: "application/json",
         body: JSON.stringify({
           ok: true,
-          authenticated: Boolean(currentUserId),
+          authenticated,
           csrf_token: "portal-csrf",
-          user: accounts.find((item) => Number(item.user_id) === Number(currentUserId)) || null,
+          user: authenticated ? {
+            id: current.user_id,
+            username: current.username,
+            role: current.role,
+            membership: current.membership,
+          } : null,
+        }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/dashboard") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          ok: true,
+          meta: {
+            trade_date: "2026-07-22",
+            requested_date: "2026-07-22",
+            source: "tushare",
+            realtime: false,
+            cached: true,
+            market_status: "closed",
+            updated_at: "2026-07-22T15:00:00+08:00",
+          },
+          overview: {
+            up_count: 2100,
+            down_count: 2800,
+            limit_up_count: 42,
+            limit_down_count: 8,
+            broken_count: 17,
+            seal_rate: 71.2,
+            amount_billion: 12600,
+            sentiment_score: 48,
+          },
+          limits: [],
+          broken: [],
+          down_limits: [],
+          yesterday_limits: [],
+          limit_performance: [],
+          ladders: [],
+          sectors: [],
+          sector_rotation: [],
         }),
       });
       return;
@@ -185,12 +229,26 @@ async function assertConfirmedSkeleton(page, { width, height }) {
   expect(title.y).toBeLessThan(height * 0.72);
   expect(stats.y).toBeGreaterThan(height * 0.55);
   expect(chart.height).toBeGreaterThan(80);
+  await expect(page.locator("#loginMascots")).toBeVisible();
   expect(card.width).toBeGreaterThan(380);
   expect(card.width).toBeLessThan(450);
   if (width === 1440) {
     expect(brand.width).toBeGreaterThan(470);
     expect(brand.width).toBeLessThan(520);
     expect(brand.height).toBe(height);
+    const mascots = await page.locator("#loginMascots").boundingBox();
+    const kicker = await page.locator(".login-brand-kicker").boundingBox();
+    expect(mascots).toBeTruthy();
+    expect(kicker).toBeTruthy();
+    expect(mascots.y).toBeGreaterThan(header.y + header.height - 4);
+    expect(mascots.y + mascots.height).toBeLessThan(kicker.y + 8);
+    const gapTop = header.y + header.height;
+    const gapBottom = kicker.y;
+    const mid = (gapTop + gapBottom) / 2;
+    const mascotMid = mascots.y + mascots.height / 2;
+    expect(Math.abs(mascotMid - mid)).toBeLessThan(48);
+    expect(title.y).toBeGreaterThan(470);
+    expect(title.y).toBeLessThan(580);
   } else if (width === 1920) {
     expect(brand.width).toBeGreaterThan(540);
     expect(brand.width).toBeLessThan(580);
@@ -289,3 +347,210 @@ test("loading button appears on the confirmed first-login skeleton", async ({ pa
   await page.screenshot({ path: path.join(SHOT_DIR, "loading-dark-1440.png"), fullPage: true });
   await submit;
 });
+
+async function openPicker(page, options = {}) {
+  const accounts = options.accounts || SAVED_ACCOUNTS.map((item) => ({ ...item }));
+  const currentUserId = options.currentUserId ?? 1;
+  const next = options.next || "/index.html?view=sentimentCycleView";
+  await page.unroute("**/api/**").catch(() => {});
+  await mockLoginPortal(page, {
+    accounts,
+    currentUserId,
+    sessionExpired: options.sessionExpired,
+    switchFails: options.switchFails,
+  });
+  await page.goto(`/login/?next=${encodeURIComponent(next)}`);
+  await expect(page.locator(".login-card-title")).toHaveText("选择账号");
+}
+
+test("clicking the current account from two workspace pages returns without switching", async ({ page }) => {
+  const views = ["sentimentCycleView", "ladderView"];
+  for (const viewId of views) {
+    const next = `/index.html?view=${viewId}`;
+    const switchCalls = [];
+    const onRequest = (request) => {
+      if (request.url().includes("/api/auth/switch") && request.method() === "POST") {
+        switchCalls.push(request);
+      }
+    };
+    page.on("request", onRequest);
+    await openPicker(page, { next });
+    await expect(page.locator('[data-resume-id="1"]')).toContainText("继续使用");
+    await expect(page.locator('[data-resume-id="1"]')).toContainText("当前");
+    await page.locator('[data-resume-id="1"]').click();
+    await expect(page).toHaveURL(new RegExp(`[?&]view=${viewId}\\b`));
+    expect(switchCalls).toEqual([]);
+    page.off("request", onRequest);
+  }
+});
+
+test("a lone current account can return from the picker instead of dead-ending", async ({ page }) => {
+  await openPicker(page, {
+    accounts: [SAVED_ACCOUNTS[0]],
+    currentUserId: 1,
+    next: "/index.html?view=reviewWorkspaceView",
+  });
+  await expect(page.locator(".login-account-row")).toHaveCount(1);
+  await expect(page.locator('[data-switch-id]')).toHaveCount(0);
+  await page.locator('[data-resume-id="1"]').click();
+  await expect(page).toHaveURL(/view=reviewWorkspaceView/);
+});
+
+test("the return control also restores the originating workspace page", async ({ page }) => {
+  await openPicker(page, { next: "/index.html?view=ladderView" });
+  await page.locator('[data-login-action="resume"]').click();
+  await expect(page).toHaveURL(/view=ladderView/);
+});
+
+test("refreshing the picker still returns to the originating page", async ({ page }) => {
+  await openPicker(page, { next: "/index.html?view=sentimentCycleView" });
+  await page.reload();
+  await expect(page.locator(".login-card-title")).toHaveText("选择账号");
+  await page.locator('[data-resume-id="1"]').click();
+  await expect(page).toHaveURL(/view=sentimentCycleView/);
+});
+
+test("an expired current session asks for login instead of pretending to return", async ({ page }) => {
+  await openPicker(page, {
+    next: "/index.html?view=sentimentCycleView",
+    sessionExpired: true,
+  });
+  await page.locator('[data-resume-id="1"]').click();
+  await expect(page.locator(".login-error")).toHaveText("当前会话已失效，请重新登录");
+  await expect(page).toHaveURL(/\/login\/?/);
+});
+
+test("other saved accounts still switch while the current row only resumes", async ({ page }) => {
+  await openPicker(page, { next: "/index.html?view=auctionView" });
+  const switched = page.waitForRequest((request) => (
+    request.url().includes("/api/auth/switch") && request.method() === "POST"
+  ));
+  await page.locator('[data-switch-id="2"]').click();
+  const request = await switched;
+  expect(JSON.parse(request.postData() || "{}")).toEqual({ user_id: 2 });
+});
+
+test("workspace switch-account menu carries the current page back to the picker", async ({ page }) => {
+  await mockLoginPortal(page, {
+    accounts: SAVED_ACCOUNTS.map((item) => ({ ...item })),
+    currentUserId: 1,
+  });
+  await page.goto("/index.html?view=sentimentCycleView");
+  await expect(page.locator("#accountButton")).toBeVisible();
+  await page.locator("#accountButton").click();
+  await page.locator("#switchAccountMenuButton").click();
+  await expect(page).toHaveURL(/\/login\/\?next=/);
+  await expect(page.locator(".login-card-title")).toHaveText("选择账号");
+  await page.locator('[data-resume-id="1"]').click();
+  await expect(page).toHaveURL(/view=sentimentCycleView/);
+});
+
+test("workspace switch-account from a second page also returns to that page", async ({ page }) => {
+  await mockLoginPortal(page, {
+    accounts: SAVED_ACCOUNTS.map((item) => ({ ...item })),
+    currentUserId: 1,
+  });
+  await page.goto("/index.html?view=ladderView");
+  await expect(page.locator("#accountButton")).toBeVisible();
+  await page.locator("#accountButton").click();
+  await page.locator("#switchAccountMenuButton").click();
+  await expect(page.locator(".login-card-title")).toHaveText("选择账号");
+  await page.locator('[data-resume-id="1"]').click();
+  await expect(page).toHaveURL(/view=ladderView/);
+});
+
+test("desktop mascots react to account focus, password, toggle, loading, success and failure", async ({ page }) => {
+  await openPortal(page, { theme: "light", width: 1440, height: 900, accounts: [] });
+  const mascots = page.locator("#loginMascots");
+  await expect(mascots).toHaveAttribute("data-mood", "idle");
+  await page.locator("#loginUsername").focus();
+  await expect(mascots).toHaveAttribute("data-mood", "account");
+  await page.locator("#loginPassword").focus();
+  await expect(mascots).toHaveAttribute("data-mood", "password");
+  await expect.poll(async () => (
+    page.locator(".login-mascot.is-red .login-mascot-hand.is-left").evaluate((node) => getComputedStyle(node).opacity)
+  )).toBe("1");
+  await page.locator(".login-password-toggle").click();
+  await expect(page.locator("#loginPassword")).toHaveAttribute("type", "text");
+  await expect(mascots).toHaveAttribute("data-mood", "password");
+  await page.locator(".login-password-toggle").click();
+  await expect(page.locator("#loginPassword")).toHaveAttribute("type", "password");
+  await expect(mascots).toHaveAttribute("data-mood", "password");
+  await page.screenshot({ path: path.join(SHOT_DIR, "mascots-password-light-1440.png"), fullPage: true });
+});
+
+test("login loading and failure drive short mascot feedback", async ({ page }) => {
+  await openPortal(page, {
+    theme: "dark",
+    width: 1440,
+    height: 900,
+    accounts: [],
+    loginFails: true,
+    loginDelay: 800,
+  });
+  await page.locator("#loginUsername").fill("baiqizhi");
+  await page.locator("#loginPassword").fill("wrong-password");
+  const submit = page.locator(".login-submit").click();
+  await expect(page.locator("#loginMascots")).toHaveAttribute("data-mood", "busy");
+  await expect(page.locator(".login-error")).toContainText("账号名或密码不正确");
+  await expect(page.locator("#loginMascots")).toHaveAttribute("data-mood", "fail");
+  await page.screenshot({ path: path.join(SHOT_DIR, "mascots-fail-dark-1440.png"), fullPage: true });
+  await submit;
+});
+
+test("login success plays a hop before leaving the portal", async ({ page }) => {
+  await openPortal(page, { theme: "light", width: 1440, height: 900, accounts: [] });
+  await page.evaluate(() => {
+    window.location.replace = () => {};
+  });
+  await page.locator("#loginUsername").fill("baiqizhi");
+  await page.locator("#loginPassword").fill("password12");
+  const submit = page.locator(".login-submit").click();
+  await expect(page.locator("#loginMascots")).toHaveAttribute("data-mood", /busy|success/);
+  await expect(page.locator("#loginMascots")).toHaveAttribute("data-mood", "success", { timeout: 4000 });
+  await page.screenshot({ path: path.join(SHOT_DIR, "mascots-success-light-1440.png"), fullPage: true });
+  await submit;
+});
+
+test("reduced motion keeps static mascots without mouse tracking", async ({ page }) => {
+  await page.emulateMedia({ reducedMotion: "reduce" });
+  await openPortal(page, { theme: "dark", width: 1440, height: 900, accounts: [] });
+  const mascots = page.locator("#loginMascots");
+  await expect(mascots).toBeVisible();
+  await expect(mascots).toHaveAttribute("data-mood", "idle");
+  const before = await mascots.evaluate((node) => getComputedStyle(node.querySelector(".login-mascot.is-red")).getPropertyValue("--pupil-x"));
+  await page.mouse.move(1200, 120);
+  await page.waitForTimeout(120);
+  const after = await mascots.evaluate((node) => getComputedStyle(node.querySelector(".login-mascot.is-red")).getPropertyValue("--pupil-x"));
+  expect(after).toBe(before);
+  await page.locator("#loginPassword").focus();
+  await expect(mascots).toHaveAttribute("data-mood", "password");
+  await page.screenshot({ path: path.join(SHOT_DIR, "mascots-reduced-dark-1440.png"), fullPage: true });
+});
+
+test("mouse follow updates mascot pupils on a fine pointer", async ({ page }) => {
+  await openPortal(page, { theme: "light", width: 1440, height: 900, accounts: [] });
+  const mascots = page.locator("#loginMascots");
+  await page.mouse.move(80, 160);
+  await page.waitForTimeout(180);
+  const left = await mascots.evaluate((node) => getComputedStyle(node.querySelector(".login-mascot.is-red")).getPropertyValue("--pupil-x"));
+  await page.mouse.move(1280, 200);
+  await page.waitForTimeout(180);
+  const right = await mascots.evaluate((node) => getComputedStyle(node.querySelector(".login-mascot.is-red")).getPropertyValue("--pupil-x"));
+  expect(Number.parseFloat(right)).toBeGreaterThan(Number.parseFloat(left));
+});
+
+test("narrow screens hide mascots without moving the login card", async ({ page }) => {
+  await openPortal(page, { theme: "light", width: 800, height: 900, accounts: [] });
+  await expect(page.locator("#loginMascots")).toBeHidden();
+  await expect(page.locator(".login-card-title")).toHaveText("欢迎回来");
+  await expect(page.locator(".login-brand-title")).toBeHidden();
+});
+
+test("theme toggle keeps mascots in the brand gap", async ({ page }) => {
+  await openPortal(page, { theme: "light", width: 1440, height: 900, accounts: [] });
+  await page.locator("#loginThemeToggle").click();
+  await expect(page.locator("html")).toHaveAttribute("data-theme", "dark");
+  await assertConfirmedSkeleton(page, { width: 1440, height: 900 });
+  await page.screenshot({ path: path.join(SHOT_DIR, "mascots-idle-dark-1440.png"), fullPage: true });
+});

tests/test_admin_refresh_status.py

@@ -1,23 +1,452 @@
 from __future__ import annotations
 
+import copy
+import threading
 import unittest
+from datetime import date, datetime, timedelta, timezone, time as dt_time
+from unittest.mock import patch
+from pathlib import Path
 
-from backend.jobs.service import _verified_dashboard_result
+from backend.features.market.service import MarketServiceMixin
+from backend.jobs.refresh import (
+    dashboard_has_usable_data,
+    official_catchup_due,
+    verified_dashboard_result,
+)
+from backend.data.providers.tushare_transport import TushareError
 
 
 class AdminRefreshStatusTests(unittest.TestCase):
-    def test_carried_snapshot_is_reported_as_failed_job(self):
+    def test_carried_snapshot_is_usable_not_failed_job(self):
-        result = _verified_dashboard_result(
+        result = verified_dashboard_result(
-            {"meta": {"carried_forward": True, "notice": "官方涨跌停数据尚未返回"}}
+            {
+                "meta": {
+                    "trade_date": "2026-09-01",
+                    "requested_date": "2026-09-02",
+                    "carried_forward": True,
+                    "notice": "今日数据正在准备，当前展示 9 月 1 日",
+                    "data_status": "preparing",
+                },
+                "overview": {"limit_up_count": 12},
+            }
         )
 
-        self.assertEqual(result["status"], "failed")
+        self.assertNotEqual(result.get("status"), "failed")
-        self.assertEqual(result["error"], "官方涨跌停数据尚未返回")
+        self.assertEqual(result["meta"]["data_status"], "preparing")
+        self.assertTrue(dashboard_has_usable_data(result))
+
+    def test_derived_limit_snapshot_is_usable_not_failed_job(self):
+        dashboard = {
+            "meta": {
+                "trade_date": "2026-09-02",
+                "limit_data_source": "derived",
+                "notice": "涨跌停高级接口当日数据尚未更新，已使用日线数据推算。",
+                "data_status": "partial",
+            },
+            "overview": {"limit_up_count": 8},
+        }
+
+        self.assertIs(verified_dashboard_result(dashboard), dashboard)
 
     def test_current_snapshot_is_reported_as_successful_job(self):
         dashboard = {"meta": {"trade_date": "2026-08-28", "carried_forward": False}}
 
-        self.assertIs(_verified_dashboard_result(dashboard), dashboard)
+        self.assertIs(verified_dashboard_result(dashboard), dashboard)
+
+    def test_empty_payload_is_still_failed(self):
+        result = verified_dashboard_result({"meta": {}, "overview": {}})
+        self.assertEqual(result["status"], "failed")
+
+
+class FakeSyncDatabase:
+    def __init__(self, latest=None):
+        self.latest = latest
+        self.saved = []
+        self.finished = []
+
+    def start_sync(self, *_args, **_kwargs):
+        return 1
+
+    def save_snapshot(self, trade_date, source, payload):
+        self.saved.append((trade_date, source, copy.deepcopy(payload)))
+
+    def save_data_snapshot(self, *_args, **_kwargs):
+        return None
+
+    def finish_sync(self, *args, **kwargs):
+        self.finished.append((args, kwargs))
+
+    def get_latest_real_snapshot(self, *_args, **_kwargs):
+        return copy.deepcopy(self.latest)
+
+    def get_snapshot(self, *_args, **_kwargs):
+        return None
+
+    def get_data_snapshot(self, *_args, **_kwargs):
+        return None
+
+    def reason_overrides(self, *_args, **_kwargs):
+        return {}
+
+
+class FakeDerivedClient:
+    def dashboard(self, trade_date: str):
+        return {
+            "meta": {
+                "trade_date": f"{trade_date[:4]}-{trade_date[4:6]}-{trade_date[6:8]}",
+                "limit_data_source": "derived",
+                "notice": "涨跌停高级接口当日数据尚未更新，已使用日线数据推算。",
+                "updated_at": datetime.now().astimezone().isoformat(timespec="seconds"),
+            },
+            "overview": {"limit_up_count": 3},
+            "limits": [{"code": "000001"}],
+            "broken": [],
+            "down_limits": [],
+            "yesterday_limits": [],
+        }
+
+
+SHANGHAI = timezone(timedelta(hours=8))
+TRADE_DAY = date(2026, 9, 8)
+
+
+def at_clock(hour: int, minute: int, day: date = TRADE_DAY) -> datetime:
+    return datetime(day.year, day.month, day.day, hour, minute, tzinfo=SHANGHAI)
+
+
+class FakeMissingDailyClient:
+    def __init__(self, open_today: bool = True):
+        self.open_today = open_today
+
+    def dashboard(self, trade_date: str):
+        raise TushareError(f"No daily data returned for {trade_date}")
+
+    def resolve_trade_context(self, requested: str):
+        if self.open_today:
+            return requested, "20260907"
+        return "20260907", "20260904"
+
+
+class FakeRealtimeTodayClient:
+    def dashboard(self, trade_date: str):
+        return {
+            "meta": {
+                "trade_date": f"{trade_date[:4]}-{trade_date[4:6]}-{trade_date[6:8]}",
+                "requested_date": f"{trade_date[:4]}-{trade_date[4:6]}-{trade_date[6:8]}",
+                "realtime": True,
+                "mode": "realtime",
+                "market_status": "trading",
+                "notice": "盘中行情由 Tushare rt_k 实时计算；涨停原因、封板时间和开板次数以盘后榜单校正为准。",
+                "updated_at": datetime.now().astimezone().isoformat(timespec="seconds"),
+            },
+            "overview": {"limit_up_count": 15},
+            "limits": [{"code": "000001"}],
+            "broken": [],
+            "down_limits": [],
+            "yesterday_limits": [],
+        }
+
+    def resolve_trade_context(self, requested: str):
+        return requested, "20260907"
+
+
+class FakeFreeRealtimeTodayClient:
+    def dashboard(self, trade_date: str):
+        return {
+            "meta": {
+                "trade_date": f"{trade_date[:4]}-{trade_date[4:6]}-{trade_date[6:8]}",
+                "requested_date": f"{trade_date[:4]}-{trade_date[4:6]}-{trade_date[6:8]}",
+                "realtime": True,
+                "mode": "realtime",
+                "quote_source": "eastmoney_clist",
+                "source": "eastmoney",
+                "market_status": "trading",
+                "notice": "盘中行情由东财免费实时快照计算；涨停原因、封板时间和开板次数以盘后榜单校正为准。",
+                "updated_at": datetime.now().astimezone().isoformat(timespec="seconds"),
+                "indices": [{"code": "000001", "price": 3800.1, "change": 0.5}],
+            },
+            "overview": {"limit_up_count": 18, "up_count": 2100, "amount_billion": 12345.6},
+            "limits": [{"code": "000001"}],
+            "broken": [],
+            "down_limits": [],
+            "yesterday_limits": [],
+        }
+
+    def resolve_trade_context(self, requested: str):
+        return requested, "20260907"
+
+
+class SyncHarness(MarketServiceMixin):
+    def __init__(self, client, latest=None, clock=None):
+        self.configured = True
+        self.sync_lock = threading.Lock()
+        self.database = FakeSyncDatabase(latest)
+        self._client = client
+        self.current_user_id = 1
+        self.clock = clock
+
+    def _tushare_client(self):
+        return self._client
+
+    def _enrich_dashboard_sentiment(self, dashboard, _trade_date):
+        return dashboard
+
+    def _apply_reason_overrides(self, dashboard):
+        return dashboard
+
+
+class DashboardFreshnessTests(unittest.TestCase):
+    def test_derived_limits_are_kept_as_partial_success(self):
+        today = date.today().strftime("%Y%m%d")
+        harness = SyncHarness(FakeDerivedClient())
+        payload = harness.sync_dashboard(today)
+        meta = payload["meta"]
+
+        self.assertEqual(meta["limit_data_source"], "derived")
+        self.assertEqual(meta["data_status"], "partial")
+        self.assertFalse(meta.get("carried_forward"))
+        self.assertIn("日线数据推算", meta["display_notice"])
+        self.assertEqual(harness.database.finished[0][0][1], "success")
+        self.assertEqual(verified_dashboard_result(payload), payload)
+
+    def test_intraday_refresh_keeps_today_and_does_not_fall_back_to_yesterday(self):
+        today = TRADE_DAY.strftime("%Y%m%d")
+        latest = {
+            "meta": {"trade_date": "2026-09-07", "source": "tushare"},
+            "overview": {"limit_up_count": 20},
+        }
+        harness = SyncHarness(
+            FakeRealtimeTodayClient(),
+            latest,
+            clock=lambda: at_clock(10, 5),
+        )
+        payload = harness.sync_dashboard(today)
+        meta = payload["meta"]
+
+        self.assertFalse(meta.get("carried_forward"))
+        self.assertTrue(meta["realtime"])
+        self.assertEqual(meta["data_status"], "intraday")
+        self.assertEqual(str(meta["trade_date"]).replace("-", ""), today)
+        self.assertNotIn("今日数据正在准备", meta.get("display_notice") or "")
+        self.assertEqual(harness.database.saved[0][0], today)
+
+    def test_intraday_free_source_keeps_today_and_indices(self):
+        today = TRADE_DAY.strftime("%Y%m%d")
+        latest = {
+            "meta": {"trade_date": "2026-09-07", "source": "tushare"},
+            "overview": {"limit_up_count": 20},
+        }
+        harness = SyncHarness(
+            FakeFreeRealtimeTodayClient(),
+            latest,
+            clock=lambda: at_clock(10, 5),
+        )
+        payload = harness.sync_dashboard(today)
+        meta = payload["meta"]
+        self.assertFalse(meta.get("carried_forward"))
+        self.assertTrue(meta["realtime"])
+        self.assertEqual(meta["data_status"], "intraday")
+        self.assertEqual(str(meta["trade_date"]).replace("-", ""), today)
+        self.assertEqual(meta["quote_source"], "eastmoney_clist")
+        self.assertEqual(payload["overview"]["amount_billion"], 12345.6)
+        self.assertEqual(meta["indices"][0]["price"], 3800.1)
+        self.assertEqual(harness.database.saved[0][0], today)
+
+    def test_intraday_missing_quotes_do_not_carry_yesterday(self):
+        today = TRADE_DAY.strftime("%Y%m%d")
+        latest = {
+            "meta": {"trade_date": "2026-09-07", "source": "tushare"},
+            "overview": {"limit_up_count": 20},
+        }
+        harness = SyncHarness(
+            FakeMissingDailyClient(),
+            latest,
+            clock=lambda: at_clock(10, 5),
+        )
+        with self.assertRaises(ValueError) as ctx:
+            harness.sync_dashboard(today)
+        self.assertIn("当天盘中行情", str(ctx.exception))
+        self.assertFalse(harness.database.saved)
+
+    def test_intraday_keeps_existing_today_snapshot_when_refresh_fails(self):
+        today = TRADE_DAY.strftime("%Y%m%d")
+        existing = {
+            "meta": {
+                "trade_date": "2026-09-08",
+                "realtime": True,
+                "mode": "realtime",
+                "source": "tushare",
+            },
+            "overview": {"limit_up_count": 11},
+            "limits": [{"code": "600000"}],
+            "broken": [],
+            "down_limits": [],
+            "yesterday_limits": [],
+        }
+        harness = SyncHarness(
+            FakeMissingDailyClient(),
+            clock=lambda: at_clock(10, 5),
+        )
+        harness.database.get_snapshot = lambda *_args, **_kwargs: copy.deepcopy(existing)
+        payload = harness.sync_dashboard(today)
+        meta = payload["meta"]
+        self.assertEqual(str(meta["trade_date"]).replace("-", ""), today)
+        self.assertTrue(meta["realtime"])
+        self.assertEqual(meta["data_status"], "intraday")
+        self.assertFalse(meta.get("carried_forward"))
+
+    def test_lunch_and_after_hours_keep_today_until_official_arrives(self):
+        today = TRADE_DAY.strftime("%Y%m%d")
+        for clock in (lambda: at_clock(12, 0), lambda: at_clock(16, 10)):
+            harness = SyncHarness(
+                FakeRealtimeTodayClient(),
+                clock=clock,
+            )
+            payload = harness.sync_dashboard(today)
+            self.assertEqual(str(payload["meta"]["trade_date"]).replace("-", ""), today)
+            self.assertFalse(payload["meta"].get("carried_forward"))
+
+    def test_preopen_and_weekend_still_carry_last_session(self):
+        latest = {
+            "meta": {"trade_date": "2026-09-07", "source": "tushare"},
+            "overview": {"limit_up_count": 20},
+        }
+        preopen = SyncHarness(
+            FakeMissingDailyClient(),
+            latest,
+            clock=lambda: at_clock(8, 30),
+        )
+        preopen_payload = preopen.sync_dashboard(TRADE_DAY.strftime("%Y%m%d"))
+        self.assertTrue(preopen_payload["meta"]["carried_forward"])
+        self.assertEqual(preopen_payload["meta"]["data_status"], "preparing")
+        self.assertIn("今日数据正在准备，当前展示", preopen_payload["meta"]["display_notice"])
+
+        weekend = SyncHarness(
+            FakeMissingDailyClient(open_today=False),
+            latest,
+            clock=lambda: at_clock(10, 5, date(2026, 9, 5)),
+        )
+        weekend_payload = weekend.sync_dashboard("20260905")
+        self.assertTrue(weekend_payload["meta"]["carried_forward"])
+
+    def test_history_date_still_uses_official_or_preparing_notice(self):
+        latest = {
+            "meta": {"trade_date": "2026-09-01", "source": "tushare"},
+            "overview": {"limit_up_count": 8},
+        }
+        harness = SyncHarness(
+            FakeMissingDailyClient(),
+            latest,
+            clock=lambda: at_clock(10, 5),
+        )
+        payload = harness.sync_dashboard("20260902")
+        self.assertTrue(payload["meta"]["carried_forward"])
+        self.assertIn("所选日期数据尚未到齐", payload["meta"]["display_notice"])
+
+    def test_carried_today_snapshot_is_retried_immediately_in_session(self):
+        today = TRADE_DAY.strftime("%Y%m%d")
+        snapshot = {
+            "meta": {
+                "source": "tushare",
+                "trade_date": "2026-09-07",
+                "carried_forward": True,
+                "requested_date": "2026-09-08",
+                "updated_at": at_clock(10, 0).isoformat(),
+            },
+            "overview": {"limit_up_count": 1},
+        }
+        harness = SyncHarness(
+            FakeRealtimeTodayClient(),
+            clock=lambda: at_clock(10, 5),
+        )
+        harness.database.get_snapshot = lambda *_args, **_kwargs: copy.deepcopy(snapshot)
+        payload = harness.get_dashboard(today)
+        self.assertEqual(str(payload["meta"]["trade_date"]).replace("-", ""), today)
+        self.assertEqual(payload["meta"]["data_status"], "intraday")
+        self.assertTrue(harness.database.saved)
+
+    def test_weekend_carry_is_not_labeled_as_preparing(self):
+        snapshot = {
+            "meta": {"trade_date": "2026-07-24", "source": "tushare", "updated_at": "2026-07-24T15:00:00+08:00"},
+            "overview": {"limit_up_count": 1},
+        }
+        harness = SyncHarness(FakeMissingDailyClient())
+        carried = harness._carry_dashboard(snapshot, "20260725", "非交易日沿用最近交易日收盘行情")
+        self.assertEqual(carried["meta"]["data_status"], "carried")
+        self.assertIn("非交易日", carried["meta"]["display_notice"])
+
+    def test_stale_derived_snapshot_is_retried(self):
+        today = date.today().strftime("%Y%m%d")
+        old = datetime.now(timezone.utc) - timedelta(minutes=5)
+        snapshot = {
+            "meta": {
+                "source": "tushare",
+                "trade_date": f"{today[:4]}-{today[4:6]}-{today[6:8]}",
+                "limit_data_source": "derived",
+                "updated_at": old.isoformat(),
+            },
+            "overview": {"limit_up_count": 1},
+        }
+        harness = SyncHarness(FakeDerivedClient())
+        harness.database.get_snapshot = lambda *_args, **_kwargs: copy.deepcopy(snapshot)
+        payload = harness.get_dashboard(today)
+        self.assertEqual(payload["meta"]["data_status"], "partial")
+        self.assertTrue(harness.database.saved)
+
+    def test_official_catchup_skips_complete_today_snapshot(self):
+        today = date.today().strftime("%Y%m%d")
+        iso = f"{today[:4]}-{today[4:6]}-{today[6:8]}"
+        due = official_catchup_due(
+            today,
+            {"meta": {"trade_date": iso, "limit_data_source": "official"}},
+        )
+        derived_due = official_catchup_due(
+            today,
+            {"meta": {"trade_date": iso, "limit_data_source": "derived"}},
+        )
+        now = datetime.now().astimezone().time().replace(tzinfo=None)
+        if dt_time(15, 5) <= now < dt_time(22, 0):
+            self.assertFalse(due)
+            self.assertTrue(derived_due)
+        else:
+            self.assertFalse(due)
+            self.assertFalse(derived_due)
+
+    def test_official_catchup_is_due_for_intraday_snapshot_after_close(self):
+        today = TRADE_DAY.strftime("%Y%m%d")
+        snapshot = {
+            "meta": {
+                "trade_date": "2026-09-08",
+                "realtime": True,
+                "mode": "realtime",
+            }
+        }
+        with patch("backend.jobs.refresh.datetime") as mocked:
+            mocked.now.return_value = at_clock(16, 10)
+            mocked.strptime = datetime.strptime
+            self.assertTrue(official_catchup_due(today, snapshot))
+            official = {
+                "meta": {
+                    "trade_date": "2026-09-08",
+                    "limit_data_source": "official",
+                    "realtime": False,
+                }
+            }
+            self.assertFalse(official_catchup_due(today, official))
+
+
+class FrontendRefreshCopyTests(unittest.TestCase):
+    def test_dashboard_script_distinguishes_partial_from_failure(self):
+        script = (Path(__file__).resolve().parents[1] / "frontend" / "shared" / "dashboard.js").read_text(encoding="utf-8")
+        self.assertIn("今日数据正在准备，当前展示", script)
+        self.assertIn("部分正式数据尚未到齐", script)
+        self.assertIn("盘中行情", script)
+        self.assertIn("meta.realtime && actualCompact === requestedCompact", script)
+        self.assertIn('job.status === "failed"', script)
+        failed_block = script.split("if (job.status === \"failed\")", 1)[1].split("const query", 1)[0]
+        self.assertIn("后台刷新失败", failed_block)
+        success_block = script.split("const freshness = dashboardFreshnessMessage(meta);", 1)[1]
+        self.assertNotIn("后台刷新失败", success_block.split("} else {", 1)[0])
 
 
 if __name__ == "__main__":

tests/test_bootstrap_runtime.py

@@ -0,0 +1,34 @@
+import logging
+import unittest
+
+from backend.bootstrap.runtime import configure_logging
+
+
+class ConfigureLoggingTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self._saved_handlers = logging.getLogger().handlers[:]
+        self._saved_level = logging.getLogger().level
+        logging.getLogger().handlers.clear()
+
+    def tearDown(self) -> None:
+        logging.getLogger().handlers[:] = self._saved_handlers
+        logging.getLogger().setLevel(self._saved_level)
+
+    def test_configures_root_logger_at_info(self) -> None:
+        configure_logging()
+        root = logging.getLogger()
+        self.assertTrue(root.handlers)
+        self.assertEqual(root.level, logging.INFO)
+        with self.assertLogs("xiaobai.datahub", level="INFO") as captured:
+            logging.getLogger("xiaobai.datahub").info("datahub shadow %s", {"dataset": "daily"})
+        self.assertIn("datahub shadow", captured.output[0])
+
+    def test_keeps_existing_configuration(self) -> None:
+        handler = logging.NullHandler()
+        logging.getLogger().addHandler(handler)
+        configure_logging()
+        self.assertEqual(logging.getLogger().handlers, [handler])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_chart_data_provider.py

@@ -2,7 +2,8 @@ from __future__ import annotations
 
 import unittest
 
-from backend.features.market.charts import ChartDataError, EastmoneyChartClient
+from backend.data.providers.ifind_client import IfindHttpClient
+from backend.features.market.charts import ChartDataError, EastmoneyChartClient, HIS_TRENDS_URL, MarketChartClient, TRENDS_URL
 from server import DashboardService
 
 
@@ -72,6 +73,171 @@ class ChartDataProviderTests(unittest.TestCase):
             self.client.stock_intraday("abc")
 
 
+class LookbackChartClient(EastmoneyChartClient):
+    def __init__(self) -> None:
+        super().__init__(cache_ttl_seconds=20)
+        self.requests: list[tuple[str, dict[str, str]]] = []
+
+    def _request_json(self, url, params, referer):
+        self.requests.append((url, params))
+        if url == TRENDS_URL and params.get("ndays") == "1":
+            return {"data": {"code": "601318", "name": "中国平安", "preClose": 56.0, "trends": []}}
+        if url == TRENDS_URL and params.get("ndays") == "5":
+            return {"data": {"code": "601318", "name": "中国平安", "preClose": 56.0, "trends": []}}
+        if url == HIS_TRENDS_URL:
+            return {
+                "data": {
+                    "code": "601318",
+                    "name": "中国平安",
+                    "preClose": 55.8,
+                    "trends": [
+                        "2026-09-07 09:30,55.80,55.90,56.00,55.70,100,5580.00,55.900",
+                        "2026-09-07 15:00,56.10,56.20,56.30,56.00,200,11240.00,56.150",
+                        "2026-09-08 09:30,0,0,0,0,0,0.00,0",
+                    ],
+                }
+            }
+        raise ChartDataError("unexpected url")
+
+
+class ChartLookbackTests(unittest.TestCase):
+    def setUp(self) -> None:
+        EastmoneyChartClient._cache.clear()
+        self.client = LookbackChartClient()
+
+    def test_empty_today_falls_back_to_latest_available_session(self):
+        payload = self.client.stock_intraday("601318")
+        urls = [url for url, _ in self.client.requests]
+        self.assertEqual(urls[0], TRENDS_URL)
+        self.assertEqual(self.client.requests[0][1]["ndays"], "1")
+        self.assertEqual(urls[1], TRENDS_URL)
+        self.assertEqual(self.client.requests[1][1]["ndays"], "5")
+        self.assertEqual(urls[2], HIS_TRENDS_URL)
+        self.assertEqual(payload["trade_date"], "2026-09-07")
+        self.assertEqual([point["time"] for point in payload["points"]], ["09:30", "15:00"])
+        self.assertEqual(payload["points"][0]["close"], 55.9)
+
+    def test_delay_multiday_can_recover_without_his(self):
+        class DelayFive(EastmoneyChartClient):
+            def __init__(self):
+                super().__init__(cache_ttl_seconds=20)
+                self.requests = []
+
+            def _request_json(self, url, params, referer):
+                self.requests.append((url, params))
+                if params.get("ndays") == "1":
+                    return {"data": {"code": "000001", "name": "平安银行", "preClose": 11.7, "trends": []}}
+                return {
+                    "data": {
+                        "code": "000001",
+                        "name": "平安银行",
+                        "preClose": 11.5,
+                        "trends": [
+                            "2026-09-07 09:30,11.50,11.60,11.70,11.40,100,1160.00,11.600",
+                            "2026-09-07 15:00,11.70,11.80,11.90,11.60,200,2360.00,11.750",
+                        ],
+                    }
+                }
+
+        EastmoneyChartClient._cache.clear()
+        client = DelayFive()
+        payload = client.stock_intraday("000001")
+        self.assertEqual(payload["trade_date"], "2026-09-07")
+        self.assertEqual(len(payload["points"]), 2)
+        self.assertEqual([url for url, _ in client.requests], [TRENDS_URL, TRENDS_URL])
+
+    def test_sh_sz_cyb_codes_use_correct_secid(self):
+        for code, secid in (("601318", "1.601318"), ("000001", "0.000001"), ("300750", "0.300750")):
+            EastmoneyChartClient._cache.clear()
+            client = LookbackChartClient()
+            client.stock_intraday(code)
+            self.assertEqual(client.requests[0][1]["secid"], secid)
+
+
+class FakeHub:
+    def __init__(self, chart=None, error=None, daily=None):
+        self.chart = chart
+        self.error = error
+        self.daily = daily
+        self.calls: list[str] = []
+        self.legacy: list[str] = []
+
+    def try_intraday(self, code):
+        self.calls.append(code)
+        if self.error:
+            raise self.error
+        return self.chart
+
+    def try_daily_chart(self, code, end_date, limit=90, dataset="daily"):
+        self.calls.append(f"{dataset}:{code}")
+        if self.error:
+            raise self.error
+        return self.daily
+
+    def record_legacy(self, dataset, source="", error=""):
+        self.legacy.append(dataset)
+
+
+class DatahubChartFallbackTests(unittest.TestCase):
+    def setUp(self) -> None:
+        EastmoneyChartClient._cache.clear()
+
+    def test_datahub_success_skips_old_channel(self):
+        hub = FakeHub(
+            {
+                "entity_type": "stock",
+                "identifier": "601318",
+                "name": "中国平安",
+                "code": "601318",
+                "trade_date": "2026-09-08",
+                "previous_close": 56.36,
+                "points": [{"date": "2026-09-08", "time": "09:30", "close": 56.5, "average": 56.4}],
+                "source": "datahub",
+            }
+        )
+        fallback = LookbackChartClient()
+        client = MarketChartClient(IfindHttpClient(), fallback, hub)
+        payload = client.stock_intraday("601318")
+        self.assertEqual(payload["source"], "datahub")
+        self.assertEqual(hub.calls, ["601318"])
+        self.assertEqual(fallback.requests, [])
+
+    def test_datahub_timeout_or_empty_falls_back_to_eastmoney(self):
+        fallback = LookbackChartClient()
+        for hub in (
+            FakeHub(chart=None),
+            FakeHub(error=RuntimeError("timeout")),
+            FakeHub(error=RuntimeError("datahub exploded")),
+            FakeHub(chart={"points": []}),
+        ):
+            EastmoneyChartClient._cache.clear()
+            fallback.requests.clear()
+            client = MarketChartClient(IfindHttpClient(), fallback, hub)
+            payload = client.stock_intraday("000001")
+            self.assertEqual(payload["trade_date"], "2026-09-07")
+            self.assertGreaterEqual(len(payload["points"]), 1)
+            self.assertTrue(fallback.requests)
+
+    def test_datahub_daily_skips_ifind(self):
+        hub = FakeHub(
+            daily=[
+                {
+                    "trade_date": "2026-09-07",
+                    "open": 10.0,
+                    "high": 10.4,
+                    "low": 9.9,
+                    "close": 10.2,
+                    "volume": 1000,
+                    "amount_billion": 0.02,
+                }
+            ]
+        )
+        client = MarketChartClient(IfindHttpClient(), LookbackChartClient(), hub)
+        rows = client.stock_daily("600000", "20260907")
+        self.assertEqual(rows[-1]["trade_date"], "2026-09-07")
+        self.assertIn("daily:600000", hub.calls)
+
+
 class ChartServiceStub:
     @staticmethod
     def _payload(code: str, name: str):

tests/test_data_gateway.py

@@ -67,6 +67,9 @@ class DataGatewayTests(unittest.TestCase):
             "TushareClient": {"backend/features/market/service.py"},
             "TushareProvider": {"backend/data/gateway.py"},
             "WebRealtimeAggregator": {"backend/data/gateway.py"},
+            "DatahubClient": {"backend/data/gateway.py"},
+            "DatahubAwareTushareClient": {"backend/data/gateway.py"},
+            "DatahubBridge": {"backend/data/gateway.py"},
         }
         found = {name: set() for name in owners}
         for path in (root / "backend").rglob("*.py"):

tests/test_datahub_bridge.py

@@ -0,0 +1,620 @@
+from __future__ import annotations
+
+import ast
+import json
+import unittest
+from pathlib import Path
+from typing import Any
+
+from backend.data import build_data_gateway
+from backend.data.datahub.bridge import DatahubAwareTushareClient, DatahubBridge, looks_like_heaven
+from backend.data.datahub.client import DatahubClient, DatahubResponse
+from backend.data.datahub.compare import compare_rows
+from backend.data.datahub.errors import DatahubError
+from backend.data.datahub.native import to_canonical_row, to_native_row
+from backend.data.datahub.route_state import LEDGER
+from backend.data.datahub.settings import DATASETS, DatahubSettings, DatasetFlags
+
+ROOT = Path(__file__).resolve().parents[1]
+TOKEN = "super-secret-datahub-token"
+
+LEGACY_DAILY = {
+    "ts_code": "600000.SH",
+    "trade_date": "20240902",
+    "open": 10.11,
+    "high": 10.25,
+    "low": 10.01,
+    "close": 10.20,
+    "pct_chg": 1.2345,
+    "vol": 1000.0,
+    "amount": 2000.0,
+}
+HUB_DAILY = {
+    "ts_code": "600000.SH",
+    "trade_date": "20240902",
+    "open": 10.11,
+    "high": 10.25,
+    "low": 10.01,
+    "close": 10.20,
+    "pct_chg": 1.2345,
+    "volume": 100000.0,
+    "amount": 2000000.0,
+}
+
+
+class FakeLegacy:
+    def __init__(self, rows: list[dict[str, Any]] | Exception | None = None) -> None:
+        self.token = "legacy-token"
+        self.timeout = 30
+        self.rows = [] if rows is None else rows
+        self.calls: list[tuple[str, dict[str, Any] | None, str]] = []
+
+    def query(self, api_name: str, params: dict[str, Any] | None = None, fields: str = "") -> list[dict[str, Any]]:
+        self.calls.append((api_name, params, fields))
+        if isinstance(self.rows, Exception):
+            raise self.rows
+        return [dict(row) for row in self.rows]
+
+
+class FakeClient(DatahubClient):
+    def __init__(self, error: DatahubError | None = None, response: DatahubResponse | None = None) -> None:
+        super().__init__(DatahubSettings(base_url="http://127.0.0.1:9", token=TOKEN))
+        self.error = error
+        self.response = response or DatahubResponse(
+            data=[dict(HUB_DAILY)],
+            meta={"tier": "official", "trade_date": "20240902", "stale": False, "staleness_seconds": 0},
+        )
+        self.paths: list[str] = []
+        self.calls: list[tuple[str, dict[str, Any]]] = []
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> DatahubResponse:
+        self.paths.append(path)
+        self.calls.append((path, {key: value for key, value in (params or {}).items()}))
+        if TOKEN in json.dumps(params or {}) or TOKEN in path:
+            raise AssertionError("token leaked into url")
+        if self.error:
+            raise self.error
+        return self.response
+
+
+def flags(**enabled: tuple[bool, bool]) -> DatahubSettings:
+    datasets = {name: DatasetFlags(name) for name in DATASETS}
+    for name, pair in enabled.items():
+        datasets[name] = DatasetFlags(name, read=pair[0], shadow=pair[1])
+    return DatahubSettings(base_url="http://127.0.0.1:9", token=TOKEN, datasets=datasets)
+
+
+class DatahubBridgeTests(unittest.TestCase):
+    def setUp(self) -> None:
+        LEDGER.clear()
+
+    def test_default_config_enables_official_reads(self) -> None:
+        settings = DatahubSettings.load(environ={}, credentials={})
+        self.assertTrue(settings.any_enabled())
+        self.assertTrue(all(settings.flags(name).read and not settings.flags(name).shadow for name in DATASETS))
+        client = FakeClient()
+        legacy = FakeLegacy([LEGACY_DAILY])
+        wrapped = DatahubAwareTushareClient(legacy, DatahubBridge(settings, client))
+        rows = wrapped.query("daily", {"trade_date": "20240902"}, "ts_code,close,vol,amount")
+        self.assertEqual(rows[0]["amount"], 2000.0)
+        self.assertEqual(client.paths, ["/v1/bars/daily"])
+        self.assertEqual(legacy.calls, [])
+        self.assertEqual(LEDGER.snapshot()[0]["route"], "datahub")
+
+    def test_each_dataset_has_independent_read_flag(self) -> None:
+        settings = flags(daily=(True, False), auction=(False, False))
+        self.assertTrue(settings.flags("daily").read)
+        self.assertFalse(settings.flags("auction").read)
+        self.assertFalse(any(settings.flags(name).read for name in DATASETS if name != "daily"))
+        source = (ROOT / "config" / "datahub.config.json").read_text(encoding="utf-8")
+        self.assertNotIn("master", source)
+        self.assertNotIn("DATAHUB_READ_ALL", source)
+        compose = (ROOT / "compose.yaml").read_text(encoding="utf-8")
+        for env_key in (
+            "CALENDAR", "STOCKS", "DAILY", "INDEX_DAILY", "VALUATION", "MONEYFLOW",
+            "AUCTION", "LIMIT_EVENTS", "POPULARITY", "DRAGON_TIGER", "SECTOR_DAILY",
+            "QUOTES", "INDEX_QUOTES", "INTRADAY", "STATUS",
+        ):
+            self.assertIn(f'DATAHUB_READ_{env_key}: "1"', compose)
+
+    def test_read_flag_replaces_only_that_dataset_and_converts_units(self) -> None:
+        shadows: list[dict[str, Any]] = []
+        client = FakeClient()
+        legacy = FakeLegacy([LEGACY_DAILY])
+        wrapped = DatahubAwareTushareClient(
+            legacy,
+            DatahubBridge(flags(daily=(True, False)), client, shadow_sink=shadows.append),
+        )
+        rows = wrapped.query("daily", {"trade_date": "20240902"}, "ts_code,vol,amount")
+        self.assertEqual(rows[0]["vol"], 1000.0)
+        self.assertEqual(rows[0]["amount"], 2000.0)
+        self.assertEqual(legacy.calls, [])
+        self.assertEqual(client.paths, ["/v1/bars/daily"])
+        calendar_legacy = FakeLegacy([{"cal_date": "20240902", "is_open": 1}])
+        calendar_client = FakeClient(error=DatahubError("INTERNAL", "nope"))
+        calendar_wrapped = DatahubAwareTushareClient(
+            calendar_legacy,
+            DatahubBridge(flags(daily=(True, False)), calendar_client),
+        )
+        calendar = calendar_wrapped.query("trade_cal", {"start_date": "20240902", "end_date": "20240902"}, "")
+        self.assertEqual(calendar[0]["is_open"], 1)
+        self.assertEqual(calendar_client.paths, [])
+
+    def test_fallback_on_down_401_timeout_empty_unpublished_stale_and_incomplete(self) -> None:
+        cases = [
+            DatahubError("UNAVAILABLE", "down"),
+            DatahubError("UNAUTHORIZED", "401"),
+            DatahubError("TIMEOUT", "late"),
+            DatahubError("EMPTY", "no rows"),
+            DatahubError("DATASET_NOT_PUBLISHED", "not ready"),
+            DatahubError("STALE", "old"),
+            DatahubError("INCOMPLETE", "truncated"),
+        ]
+        for error in cases:
+            with self.subTest(error=error.code):
+                if error.code == "EMPTY":
+                    client = FakeClient(response=DatahubResponse(data=[], meta={"stale": False, "staleness_seconds": 0}))
+                elif error.code == "STALE":
+                    client = FakeClient(response=DatahubResponse(
+                        data=[dict(HUB_DAILY)],
+                        meta={"stale": True, "staleness_seconds": 999999},
+                    ))
+                elif error.code == "INCOMPLETE":
+                    client = FakeClient(response=DatahubResponse(
+                        data=[dict(HUB_DAILY)],
+                        meta={
+                            "stale": False,
+                            "staleness_seconds": 0,
+                            "incomplete": True,
+                            "coverage": {"complete": False, "missing_count": 80},
+                        },
+                    ))
+                else:
+                    client = FakeClient(error=error)
+                legacy = FakeLegacy([LEGACY_DAILY])
+                wrapped = DatahubAwareTushareClient(legacy, DatahubBridge(flags(daily=(True, False)), client))
+                rows = wrapped.query("daily", {"trade_date": "20240902"}, "ts_code,amount")
+                self.assertEqual(rows[0]["amount"], 2000.0)
+                self.assertEqual(len(legacy.calls), 1)
+
+    def test_shadow_compares_without_replacing_and_survives_hub_failure(self) -> None:
+        reports: list[dict[str, Any]] = []
+        client = FakeClient()
+        legacy = FakeLegacy([LEGACY_DAILY])
+        wrapped = DatahubAwareTushareClient(
+            legacy,
+            DatahubBridge(flags(daily=(False, True)), client, shadow_sink=reports.append),
+        )
+        rows = wrapped.query("daily", {"trade_date": "20240902"}, "ts_code,amount,vol")
+        self.assertEqual(rows[0]["amount"], 2000.0)
+        self.assertEqual(len(legacy.calls), 1)
+        self.assertEqual(reports[0]["equal"], True)
+        self.assertEqual(reports[0]["matched"], 1)
+
+        failed = FakeClient(error=DatahubError("UNAVAILABLE", TOKEN))
+        fail_reports: list[dict[str, Any]] = []
+        fail_legacy = FakeLegacy([LEGACY_DAILY])
+        fail_wrapped = DatahubAwareTushareClient(
+            fail_legacy,
+            DatahubBridge(flags(daily=(False, True)), failed, shadow_sink=fail_reports.append),
+        )
+        again = fail_wrapped.query("daily", {"trade_date": "20240902"}, "amount")
+        self.assertEqual(again[0]["amount"], 2000.0)
+        self.assertTrue(fail_reports[0]["hub_error"])
+        self.assertNotIn(TOKEN, json.dumps(fail_reports[0]))
+
+    def test_compare_classifies_unit_conversion_missing_row_and_value_diff(self) -> None:
+        equal = compare_rows("daily", [LEGACY_DAILY], [HUB_DAILY], {"stale": False, "staleness_seconds": 0})
+        self.assertTrue(equal["equal"])
+        unit = compare_rows("daily", [LEGACY_DAILY], [{**HUB_DAILY, "amount": 2000.0, "volume": 1000.0}])
+        self.assertGreater(unit["unit_conversion_count"], 0)
+        missing = compare_rows("daily", [LEGACY_DAILY], [])
+        self.assertEqual(missing["missing_hub_count"], 1)
+        value = compare_rows("daily", [LEGACY_DAILY], [{**HUB_DAILY, "close": 99.0}])
+        self.assertEqual(value["value_diff_count"], 1)
+        skew = compare_rows("daily", [LEGACY_DAILY], [HUB_DAILY], {"stale": False, "staleness_seconds": 12})
+        self.assertTrue(skew["time_skew"])
+
+    def test_shadow_extra_hub_columns_are_not_false_diffs_when_projected(self) -> None:
+        hub_full = {**HUB_DAILY, "adj_factor": 1.1}
+        legacy_close_only = {k: LEGACY_DAILY[k] for k in ("ts_code", "trade_date", "close")}
+        report = compare_rows(
+            "daily", [legacy_close_only], [hub_full],
+            {"stale": False, "staleness_seconds": 0},
+            fields="ts_code,trade_date,close",
+        )
+        self.assertTrue(report["equal"])
+        self.assertEqual(report["value_diff_count"], 0)
+        self.assertEqual(report["fields_compared"], ["close", "trade_date", "ts_code"])
+        # without projection the same pair shows the historic false diff
+        unprojected = compare_rows("daily", [legacy_close_only], [hub_full])
+        self.assertFalse(unprojected["equal"])
+
+        legacy_stocks = {"ts_code": "600000.SH", "name": "浦发银行"}
+        hub_stocks = {
+            "ts_code": "600000.SH", "symbol": "600000", "name": "浦发银行", "area": "上海",
+            "industry": "银行", "market": "主板", "list_status": "L", "list_date": "19991110",
+        }
+        stocks = compare_rows("stocks", [legacy_stocks], [hub_stocks], {}, fields="ts_code,name")
+        self.assertTrue(stocks["equal"])
+
+        legacy_cal = {"cal_date": "20240902", "is_open": 1}
+        hub_cal = {
+            "cal_date": "20240902", "is_open": True,
+            "pretrade_date": "20240830", "prev_open": "20240830",
+        }
+        calendar = compare_rows(
+            "calendar", [legacy_cal], [hub_cal], {}, fields="cal_date,is_open"
+        )
+        self.assertTrue(calendar["equal"])
+
+    def test_shadow_projection_still_alarms_on_requested_field_problems(self) -> None:
+        hub_missing_field = {k: v for k, v in HUB_DAILY.items() if k != "close"}
+        legacy_close_only = {k: LEGACY_DAILY[k] for k in ("ts_code", "trade_date", "close")}
+        lost = compare_rows(
+            "daily", [legacy_close_only], [hub_missing_field], fields="ts_code,trade_date,close"
+        )
+        self.assertFalse(lost["equal"])
+        self.assertEqual(lost["value_diff_count"], 1)
+
+        changed = compare_rows(
+            "daily", [legacy_close_only], [{**HUB_DAILY, "close": 99.0}],
+            fields="ts_code,trade_date,close",
+        )
+        self.assertFalse(changed["equal"])
+        self.assertEqual(changed["value_diff_count"], 1)
+        self.assertEqual(changed["value_diffs"][0]["fields"][0]["field"], "close")
+
+        gone = compare_rows("daily", [LEGACY_DAILY], [], fields="ts_code,trade_date,close")
+        self.assertEqual(gone["missing_hub_count"], 1)
+        self.assertFalse(gone["equal"])
+
+        unit = compare_rows(
+            "daily", [LEGACY_DAILY], [{**HUB_DAILY, "amount": 2000.0, "volume": 1000.0}],
+            fields="ts_code,trade_date,vol,amount",
+        )
+        self.assertGreater(unit["unit_conversion_count"], 0)
+        self.assertFalse(unit["equal"])
+
+    def test_bridge_shadow_report_uses_website_request_fields(self) -> None:
+        hub_full = {**HUB_DAILY, "adj_factor": 1.1}
+        legacy_close_only = {k: LEGACY_DAILY[k] for k in ("ts_code", "trade_date", "close", "vol", "amount")}
+        reports: list[dict[str, Any]] = []
+        client = FakeClient(
+            response=DatahubResponse(
+                data=[hub_full],
+                meta={"tier": "official", "trade_date": "20240902", "stale": False, "staleness_seconds": 0},
+            )
+        )
+        wrapped = DatahubAwareTushareClient(
+            FakeLegacy([legacy_close_only]),
+            DatahubBridge(flags(daily=(False, True)), client, shadow_sink=reports.append),
+        )
+        rows = wrapped.query("daily", {"trade_date": "20240902"}, "ts_code,trade_date,close,vol,amount")
+        self.assertEqual(rows[0]["close"], 10.20)
+        self.assertEqual(rows[0]["vol"], 1000.0)
+        self.assertTrue(reports[0]["equal"])
+        self.assertEqual(reports[0]["matched"], 1)
+
+    def test_native_roundtrip_matches_known_scales(self) -> None:
+        native = to_native_row("daily", HUB_DAILY)
+        self.assertEqual(native["vol"], 1000.0)
+        self.assertEqual(native["amount"], 2000.0)
+        canonical = to_canonical_row("daily", native)
+        self.assertEqual(canonical["vol"], 100000.0)
+        self.assertEqual(canonical["amount"], 2000000.0)
+
+    def test_heaven_can_use_hub_when_dataset_flag_is_on(self) -> None:
+        """问天按数据依赖接入：已映射 API 跟随开关，不再整栈强制旧链路。"""
+        self.assertTrue(looks_like_heaven("backend.features.heaven.market_context", "backend/features/heaven/market_context.py"))
+        self.assertFalse(looks_like_heaven("backend.features.market.service", "backend/features/market/service.py"))
+        client = FakeClient()
+        legacy = FakeLegacy([LEGACY_DAILY])
+        wrapped = DatahubAwareTushareClient(
+            legacy,
+            DatahubBridge(flags(daily=(True, False)), client, heaven_guard=lambda: True),
+        )
+        rows = wrapped.query("daily", {"trade_date": "20240902"}, "amount")
+        self.assertEqual(rows[0]["amount"], 2000.0)
+        self.assertEqual(client.paths, ["/v1/bars/daily"])
+        self.assertEqual(legacy.calls, [])
+
+    def test_status_flag_does_not_run_when_off_and_falls_back_when_on(self) -> None:
+        off = DatahubBridge(flags(), FakeClient(error=DatahubError("UNAVAILABLE", "down")))
+        self.assertIsNone(off.dataset_status("20240902"))
+        reports: list[dict[str, Any]] = []
+        failed = DatahubBridge(
+            flags(status=(True, True)),
+            FakeClient(error=DatahubError("UNAUTHORIZED", "nope")),
+            shadow_sink=reports.append,
+        )
+        self.assertIsNone(failed.dataset_status("20240902"))
+        self.assertTrue(reports[0]["hub_error"])
+        ok = DatahubBridge(
+            flags(status=(True, False)),
+            FakeClient(response=DatahubResponse(data=[{"dataset": "daily", "state": "published"}], meta={"stale": False, "staleness_seconds": 0})),
+        )
+        self.assertEqual(ok.dataset_status("20240902")[0]["state"], "published")
+
+    def test_default_gateway_wraps_tushare_without_calling_datahub(self) -> None:
+        gateway = build_data_gateway({}, datahub_settings=flags())
+        client = gateway.tushare()
+        self.assertIsInstance(client, DatahubAwareTushareClient)
+        self.assertFalse(gateway.datahub.settings.any_enabled())
+
+    def test_stock_detail_range_query_is_not_silently_accepted_when_incomplete(self) -> None:
+        source = (ROOT / "backend" / "data" / "providers" / "tushare_stocks.py").read_text(encoding="utf-8")
+        self.assertIn('"daily"', source)
+        self.assertIn("start_date", source)
+        self.assertIn("end_date", source)
+        client = FakeClient(
+            response=DatahubResponse(
+                data=[dict(HUB_DAILY)],
+                meta={"stale": False, "staleness_seconds": 0, "incomplete": True, "coverage": {"complete": False, "missing_count": 89}},
+            )
+        )
+        legacy = FakeLegacy([LEGACY_DAILY])
+        wrapped = DatahubAwareTushareClient(legacy, DatahubBridge(flags(daily=(True, False)), client))
+        rows = wrapped.query(
+            "daily",
+            {"ts_code": "600000.SH", "start_date": "20240301", "end_date": "20240902"},
+            "ts_code,amount",
+        )
+        self.assertEqual(rows[0]["amount"], 2000.0)
+        self.assertEqual(len(legacy.calls), 1)
+
+    def test_try_intraday_respects_switch_and_falls_back_on_bad_payload(self) -> None:
+        closed = DatahubBridge(flags(), FakeClient(error=DatahubError("INTERNAL", "should not run")))
+        self.assertIsNone(closed.try_intraday("601318"))
+
+        empty = DatahubBridge(
+            flags(intraday=(True, False)),
+            FakeClient(response=DatahubResponse(data={"points": []}, meta={"stale": False})),
+        )
+        self.assertIsNone(empty.try_intraday("601318"))
+
+        stale = DatahubBridge(
+            flags(intraday=(True, False)),
+            FakeClient(response=DatahubResponse(
+                data={
+                    "entity_type": "stock",
+                    "code": "601318",
+                    "trade_date": "2026-09-07",
+                    "previous_close": 55.8,
+                    "points": [{"date": "2026-09-07", "time": "09:30", "close": 55.9, "avg_price": 55.85}],
+                },
+                meta={"stale": True},
+            )),
+        )
+        self.assertIsNone(stale.try_intraday("601318"))
+
+        ok = DatahubBridge(
+            flags(intraday=(True, False)),
+            FakeClient(response=DatahubResponse(
+                data={
+                    "entity_type": "stock",
+                    "identifier": "601318",
+                    "name": "中国平安",
+                    "code": "601318",
+                    "trade_date": "2026-09-08",
+                    "previous_close": 56.36,
+                    "points": [
+                        {"date": "2026-09-08", "time": "09:30", "close": 0},
+                        {"date": "2026-09-08", "time": "09:31", "close": 56.5, "avg_price": 56.4},
+                    ],
+                },
+                meta={"stale": False},
+            )),
+        )
+        chart = ok.try_intraday("601318")
+        self.assertEqual(chart["source"], "datahub")
+        self.assertEqual(len(chart["points"]), 1)
+        self.assertEqual(chart["points"][0]["average"], 56.4)
+        self.assertEqual(ok.client.paths, ["/v1/intraday/points"])
+        self.assertEqual(ok.client.calls, [("/v1/intraday/points", {"code": "601318"})])
+        self.assertNotIn("date", ok.client.calls[0][1])
+
+        timeout = DatahubBridge(
+            flags(intraday=(True, False)),
+            FakeClient(error=DatahubError("TIMEOUT", "datahub request timed out")),
+        )
+        self.assertIsNone(timeout.try_intraday("601318"))
+        broken = DatahubBridge(
+            flags(intraday=(True, False)),
+            FakeClient(error=DatahubError("INTERNAL", "datahub exploded")),
+        )
+        self.assertIsNone(broken.try_intraday("601318"))
+        self.assertTrue(DatahubSettings.load(environ={}, credentials={}).flags("intraday").read)
+
+    def test_try_market_quotes_and_visible_fallback(self) -> None:
+        quotes = [
+            {
+                "ts_code": f"{600000 + index:06d}.SH",
+                "name": f"股票{index}",
+                "close": 10.2,
+                "pre_close": 10.0,
+                "open": 10.1,
+                "high": 10.3,
+                "low": 9.9,
+                "vol": 1000,
+                "amount": 2000000,
+                "quote_date": "20240902",
+            }
+            for index in range(220)
+        ]
+        ok = DatahubBridge(
+            flags(quotes=(True, False)),
+            FakeClient(
+                response=DatahubResponse(
+                    data=quotes,
+                    meta={"stale": False, "staleness_seconds": 0, "source": "eastmoney:clist"},
+                )
+            ),
+        )
+        rows = ok.try_market_quotes("20240902")
+        self.assertEqual(len(rows), 220)
+        self.assertEqual(rows[0]["pre_close"], 10.0)
+        self.assertEqual(ok.client.paths, ["/v1/quotes/latest"])
+        self.assertEqual(LEDGER.snapshot()[0]["route"], "datahub")
+
+        failed = DatahubBridge(
+            flags(quotes=(True, False)),
+            FakeClient(error=DatahubError("UNAVAILABLE", "down")),
+        )
+        self.assertIsNone(failed.try_market_quotes("20240902"))
+        failed.record_legacy("quotes", "tencent_qt", "down")
+        snap = next(item for item in LEDGER.snapshot() if item["dataset"] == "quotes")
+        self.assertEqual(snap["route"], "legacy")
+        self.assertEqual(snap["source"], "tencent_qt")
+        self.assertIn("备用", "备用")
+
+        gateway = build_data_gateway({}, datahub_settings=flags(quotes=(True, False)))
+        status = gateway.datahub_status()
+        self.assertEqual(status["enabled_reads"], 1)
+        self.assertEqual(status["total_reads"], len(DATASETS))
+        self.assertGreaterEqual(status["fallback_count"], 1)
+
+    def test_try_daily_chart_converts_hub_bars(self) -> None:
+        rows = [
+            {
+                "ts_code": "600000.SH",
+                "trade_date": "20240901",
+                "open": 10.0,
+                "high": 10.4,
+                "low": 9.9,
+                "close": 10.2,
+                "volume": 100000,
+                "amount": 2000000,
+            },
+            {
+                "ts_code": "600000.SH",
+                "trade_date": "20240902",
+                "open": 10.2,
+                "high": 10.5,
+                "low": 10.1,
+                "close": 10.4,
+                "volume": 120000,
+                "amount": 2400000,
+            },
+        ]
+        hub = DatahubBridge(
+            flags(daily=(True, False)),
+            FakeClient(
+                response=DatahubResponse(
+                    data=rows,
+                    meta={"stale": False, "staleness_seconds": 0, "source": "tushare:daily"},
+                )
+            ),
+        )
+        chart = hub.try_daily_chart("600000.SH", "20240902", 90, "daily")
+        self.assertEqual(chart[-1]["trade_date"], "2024-09-02")
+        self.assertEqual(chart[-1]["close"], 10.4)
+        self.assertAlmostEqual(chart[-1]["amount_billion"], 0.024)
+
+    def test_try_daily_chart_keeps_usable_bars_when_coverage_incomplete(self) -> None:
+        rows = [
+            {
+                "ts_code": "000001.SZ",
+                "trade_date": "20240901",
+                "open": 10.0,
+                "high": 10.4,
+                "low": 9.9,
+                "close": 10.2,
+                "volume": 100000,
+                "amount": 2000000,
+            },
+            {
+                "ts_code": "000001.SZ",
+                "trade_date": "20240902",
+                "open": 10.2,
+                "high": 10.5,
+                "low": 10.1,
+                "close": 10.4,
+                "volume": 120000,
+                "amount": 2400000,
+            },
+        ]
+        hub = DatahubBridge(
+            flags(daily=(True, False)),
+            FakeClient(
+                response=DatahubResponse(
+                    data=rows,
+                    meta={
+                        "stale": False,
+                        "staleness_seconds": 0,
+                        "incomplete": True,
+                        "coverage": {"complete": False, "missing_count": 127},
+                        "source": "tushare:daily",
+                    },
+                )
+            ),
+        )
+        chart = hub.try_daily_chart("000001.SZ", "20240902", 90, "daily")
+        self.assertIsNotNone(chart)
+        self.assertEqual(chart[-1]["trade_date"], "2024-09-02")
+        self.assertEqual(chart[-1]["close"], 10.4)
+
+    def test_gateway_tushare_assembly_binds_hooks_on_inner_client(self) -> None:
+        quotes = [
+            {
+                "ts_code": f"{index:06d}.SZ",
+                "name": f"S{index}",
+                "pre_close": 10.0,
+                "open": 10.0,
+                "high": 10.5,
+                "low": 9.8,
+                "close": 10.2,
+                "vol": 100.0,
+                "amount": 1000.0,
+                "quote_date": "20240902",
+            }
+            for index in range(1, 221)
+        ]
+        hub_client = FakeClient(
+            response=DatahubResponse(
+                data=quotes,
+                meta={"stale": False, "staleness_seconds": 0, "source": "eastmoney_clist"},
+            )
+        )
+        gateway = build_data_gateway(
+            {"tushare_token": "tok"},
+            datahub_settings=flags(quotes=(True, False), daily=(True, False)),
+        )
+        gateway.datahub.client = hub_client
+        wrapped = gateway.tushare()
+        inner = wrapped._legacy
+        self.assertTrue(callable(getattr(inner, "try_market_quotes", None)))
+        self.assertTrue(callable(getattr(inner, "try_index_quotes", None)))
+        self.assertTrue(callable(getattr(inner, "record_datahub_legacy", None)))
+        self.assertIs(inner.query.__self__, wrapped)
+        self.assertEqual(inner.query.__func__, wrapped.query.__func__)
+        self.assertFalse(hasattr(type(inner), "try_market_quotes"))
+        rows = inner.try_market_quotes("20240902")
+        self.assertGreaterEqual(len(rows or []), 200)
+        self.assertIn("/v1/quotes/latest", hub_client.paths)
+        hub_client.response = DatahubResponse(
+            data=[dict(HUB_DAILY)],
+            meta={"stale": False, "staleness_seconds": 0, "source": "tushare:daily"},
+        )
+        daily = inner.query("daily", {"trade_date": "20240902"}, "ts_code,amount")
+        self.assertEqual(daily[0]["amount"], 2000.0)
+        self.assertIn("/v1/bars/daily", hub_client.paths)
+
+    def test_features_do_not_import_datahub_client(self) -> None:
+        violations = []
+        for path in (ROOT / "backend" / "features").rglob("*.py"):
+            tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+            for node in ast.walk(tree):
+                names = []
+                if isinstance(node, ast.Import):
+                    names = [alias.name for alias in node.names]
+                elif isinstance(node, ast.ImportFrom) and node.module:
+                    names = [node.module]
+                for name in names:
+                    if "datahub" in name.split("."):
+                        violations.append(f"{path.relative_to(ROOT)} -> {name}")
+        self.assertEqual(violations, [])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_datahub_client.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import io
+import json
+import logging
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from backend.data.datahub.client import DatahubClient
+from backend.data.datahub.errors import DatahubError
+from backend.data.datahub.redact import redact_text
+from backend.data.datahub.settings import DatahubSettings
+
+
+TOKEN = "super-secret-datahub-token"
+
+
+class FakeHubState:
+    def __init__(self) -> None:
+        self.mode = "ok"
+        self.hits = 0
+        self.paths: list[str] = []
+
+
+STATE = FakeHubState()
+
+
+class FakeHubHandler(BaseHTTPRequestHandler):
+    def log_message(self, format: str, *args: object) -> None:
+        return
+
+    def do_GET(self) -> None:  # noqa: N802
+        STATE.hits += 1
+        parsed = urlparse(self.path)
+        STATE.paths.append(parsed.path)
+        token = self.headers.get("X-Datahub-Token", "")
+        if STATE.mode == "timeout":
+            raise TimeoutError("simulated timeout")
+        if token != TOKEN:
+            self._json(401, {"error": {"code": "UNAUTHORIZED", "message": "missing or invalid X-Datahub-Token"}})
+            return
+        if STATE.mode == "unpublished":
+            self._json(404, {"error": {"code": "DATASET_NOT_PUBLISHED", "message": "daily 19990101 尚未发布", "expected_at": "15:05+08:00"}})
+            return
+        if STATE.mode == "empty":
+            self._json(200, {"schema_version": 1, "data": [], "meta": {"tier": "official", "stale": False, "staleness_seconds": 0}})
+            return
+        if STATE.mode == "stale":
+            self._json(200, {"schema_version": 1, "data": [{"ts_code": "600000.SH", "trade_date": "20240902", "close": 10.2, "volume": 100000, "amount": 2000000}], "meta": {"tier": "official", "stale": True, "staleness_seconds": 999999}})
+            return
+        if STATE.mode == "invalid":
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.end_headers()
+            self.wfile.write(b"not-json")
+            return
+        if parsed.path == "/v1/health":
+            self._json(200, {"schema_version": 1, "data": {"status": "ok"}, "meta": {"tier": "official", "source": "datahub", "stale": False, "staleness_seconds": 0}})
+            return
+        if parsed.path == "/v1/calendar":
+            self._json(200, {"schema_version": 1, "data": [{"cal_date": "20240902", "is_open": True, "pretrade_date": "20240830"}], "meta": {"tier": "official", "trade_date": "20240902", "stale": False, "staleness_seconds": 0}})
+            return
+        if parsed.path == "/v1/bars/daily":
+            query = {key: values[-1] for key, values in parse_qs(parsed.query).items()}
+            self._json(200, {
+                "schema_version": 1,
+                "data": [{
+                    "ts_code": "600000.SH",
+                    "trade_date": query.get("date") or "20240902",
+                    "open": 10.11, "high": 10.25, "low": 10.01, "close": 10.20,
+                    "pct_chg": 1.2345, "volume": 100000.0, "amount": 2000000.0, "adj_factor": 1.1,
+                }],
+                "meta": {"tier": "official", "trade_date": "20240902", "stale": False, "staleness_seconds": 0, "source": "tushare:daily"},
+            })
+            return
+        if parsed.path == "/v1/datasets/status":
+            self._json(200, {"schema_version": 1, "data": [{"dataset": "daily", "state": "published", "trade_date": "20240902"}], "meta": {"tier": "official", "stale": False, "staleness_seconds": 0}})
+            return
+        self._json(400, {"error": {"code": "INVALID_ARGUMENT", "message": f"unknown endpoint: {parsed.path}"}})
+
+    def _json(self, status: int, payload: dict) -> None:
+        body = json.dumps(payload).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+
+class DatahubClientTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), FakeHubHandler)
+        cls.thread = threading.Thread(target=cls.server.serve_forever, daemon=True)
+        cls.thread.start()
+        cls.base = f"http://127.0.0.1:{cls.server.server_address[1]}"
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cls.server.shutdown()
+        cls.server.server_close()
+
+    def setUp(self) -> None:
+        STATE.mode = "ok"
+        STATE.hits = 0
+        STATE.paths = []
+        self.client = DatahubClient(DatahubSettings(base_url=self.base, token=TOKEN, retries=1, timeout_seconds=2))
+
+    def test_health_envelope(self) -> None:
+        response = self.client.health()
+        self.assertEqual(response.schema_version, 1)
+        self.assertEqual(response.data["status"], "ok")
+        self.assertIn("stale", response.meta)
+
+    def test_missing_and_bad_token_401(self) -> None:
+        missing = DatahubClient(DatahubSettings(base_url=self.base, token=""))
+        with self.assertRaises(DatahubError) as raised:
+            missing.health()
+        self.assertEqual(raised.exception.code, "NOT_CONFIGURED")
+        bad = DatahubClient(DatahubSettings(base_url=self.base, token="wrong"))
+        with self.assertRaises(DatahubError) as raised:
+            bad.health()
+        self.assertEqual(raised.exception.code, "UNAUTHORIZED")
+        self.assertNotIn(TOKEN, str(raised.exception))
+
+    def test_unpublished_and_empty_and_stale_codes(self) -> None:
+        STATE.mode = "unpublished"
+        with self.assertRaises(DatahubError) as raised:
+            self.client.daily_bars(date="19990101")
+        self.assertEqual(raised.exception.code, "DATASET_NOT_PUBLISHED")
+        STATE.mode = "empty"
+        response = self.client.daily_bars(date="20240902")
+        self.assertEqual(response.data, [])
+        STATE.mode = "stale"
+        stale = self.client.daily_bars(date="20240902")
+        self.assertTrue(stale.meta["stale"])
+
+    def test_invalid_json_maps_to_internal(self) -> None:
+        STATE.mode = "invalid"
+        with self.assertRaises(DatahubError) as raised:
+            self.client.health()
+        self.assertEqual(raised.exception.code, "INTERNAL")
+
+    def test_timeout_maps_and_retries(self) -> None:
+        hits = {"n": 0}
+
+        def boom(_request, timeout=None):
+            hits["n"] += 1
+            raise TimeoutError("late")
+
+        client = DatahubClient(
+            DatahubSettings(base_url=self.base, token=TOKEN, retries=1, timeout_seconds=1),
+            urlopen=boom,
+        )
+        with self.assertRaises(DatahubError) as raised:
+            client.health()
+        self.assertEqual(raised.exception.code, "TIMEOUT")
+        self.assertEqual(hits["n"], 2)
+
+    def test_token_never_appears_in_error_text_or_logs(self) -> None:
+        stream = io.StringIO()
+        logger = logging.getLogger("xiaobai.datahub")
+        handler = logging.StreamHandler(stream)
+        logger.addHandler(handler)
+        logger.setLevel(logging.DEBUG)
+        try:
+            with self.assertRaises(DatahubError):
+                DatahubClient(DatahubSettings(base_url=self.base, token="wrong")).health()
+            blob = stream.getvalue() + redact_text("header " + TOKEN, (TOKEN,))
+            self.assertNotIn(TOKEN, blob)
+            self.assertIn("***", redact_text(TOKEN, (TOKEN,)))
+        finally:
+            logger.removeHandler(handler)
+
+    def test_calendar_and_status_contract(self) -> None:
+        calendar = self.client.calendar("20240901", "20240902")
+        self.assertEqual(calendar.data[0]["cal_date"], "20240902")
+        status = self.client.dataset_status("20240902")
+        self.assertEqual(status.data[0]["dataset"], "daily")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_heaven_realtime.py

@@ -3,9 +3,10 @@ from __future__ import annotations
 import http.client
 import json
 import unittest
+from datetime import datetime
 from unittest.mock import MagicMock, patch
 
-from backend.data.realtime import WebRealtimeAggregator
+from backend.data.realtime import RealtimeAggregateError, WebRealtimeAggregator
 from backend.features.heaven.engine import _market_line_scores, build_manual_market_hexagram
 from server import DashboardService
 from backend.data.providers.tushare_client import (
@@ -377,6 +378,87 @@ class RealtimeAggregatorTests(unittest.TestCase):
         self.assertEqual(rows[0]["quote_time"][:10], "2026-07-20")
         self.assertAlmostEqual(rows[0]["amount_billion"], 12946.52)
 
+    @patch.object(WebRealtimeAggregator, "_get_json")
+    def test_eastmoney_market_quotes_normalize_and_keep_expected_date(self, get_json: MagicMock):
+        epoch = datetime(2026, 7, 20, 10, 5).timestamp()
+        rows = []
+        for index in range(200):
+            sz = index < 100
+            rows.append(
+                {
+                    "f12": f"{index:06d}" if sz else f"{600000 + index - 100:06d}",
+                    "f13": 0 if sz else 1,
+                    "f14": f"股票{index}",
+                    "f2": 11.2,
+                    "f3": 2.0,
+                    "f5": 10,
+                    "f6": 50000000,
+                    "f15": 11.3,
+                    "f16": 11.0,
+                    "f17": 11.1,
+                    "f18": 11.0,
+                    "f124": epoch,
+                }
+            )
+        def fake_get_json(_url, params, referer=""):
+            page = int(params.get("pn") or 1)
+            start = (page - 1) * 100
+            return {"rc": 0, "data": {"total": 200, "diff": rows[start:start + 100]}}
+
+        get_json.side_effect = fake_get_json
+        aggregator = WebRealtimeAggregator()
+        aggregator._response_cache.clear()
+        quotes = aggregator.eastmoney_market_quotes("20260720")
+        self.assertEqual(len(quotes), 200)
+        self.assertEqual(quotes[0]["ts_code"], "000000.SZ")
+        self.assertTrue(quotes[100]["ts_code"].endswith(".SH"))
+        self.assertEqual(quotes[0]["vol"], 1000)
+        self.assertEqual(quotes[0]["quote_date"], "20260720")
+
+    @patch.object(WebRealtimeAggregator, "_get_text")
+    def test_tencent_stock_quote_keeps_expected_date(self, get_text: MagicMock):
+        fields = [""] * 38
+        fields[1] = "浦发银行"
+        fields[2] = "600000"
+        fields[3] = "11.20"
+        fields[4] = "11.00"
+        fields[5] = "11.10"
+        fields[6] = "1234"
+        fields[30] = "20260720103000"
+        fields[33] = "11.30"
+        fields[34] = "11.00"
+        fields[37] = "1380"
+        get_text.return_value = (f'v_sh600000="{"~".join(fields)}";', 0)
+
+        quote = WebRealtimeAggregator().tencent_stock_quote("600000", "20260720")
+
+        self.assertEqual(quote["ts_code"], "600000.SH")
+        self.assertEqual(quote["quote_date"], "20260720")
+        self.assertEqual(quote["vol"], 123400)
+        self.assertAlmostEqual(quote["amount"], 13_800_000)
+
+    @patch.object(WebRealtimeAggregator, "_get_json")
+    def test_eastmoney_stock_quote_rejects_stale_date(self, get_json: MagicMock):
+        epoch = datetime(2026, 7, 19, 15, 0).timestamp()
+        get_json.return_value = {
+            "rc": 0,
+            "data": {
+                "f43": 11.2,
+                "f44": 11.3,
+                "f45": 11.0,
+                "f46": 11.1,
+                "f47": 10,
+                "f48": 50000000,
+                "f57": "300750",
+                "f58": "宁德时代",
+                "f60": 11.0,
+                "f86": epoch,
+            },
+        }
+
+        with self.assertRaises(RealtimeAggregateError):
+            WebRealtimeAggregator().eastmoney_stock_quote("300750.SZ", "20260720")
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_http_dispatch.py

@@ -138,7 +138,7 @@ class HttpDispatchContractTests(unittest.TestCase):
             self.assertTrue(claimed.isdisjoint(methods))
             claimed.update(methods)
             self.assertLessEqual(len(path.read_text(encoding="utf-8").splitlines()), line_limit)
-        self.assertEqual(len(claimed), 27)
+        self.assertEqual(len(claimed), 28)
 
 
 if __name__ == "__main__":

tests/test_login_portal.py

@@ -44,11 +44,47 @@ class LoginPortalContractTests(unittest.TestCase):
         self.assertIn("padding-bottom: 0;", AUTH)
         self.assertNotIn("padding: 0 0 var(--statusbar-height);", AUTH)
 
+    def test_confirmed_mascots_fill_the_brand_gap(self) -> None:
+        for needle in (
+            'id="loginMascots"',
+            'aria-hidden="true"',
+            'class="login-mascot is-red"',
+            'class="login-mascot is-green"',
+            'class="login-mascot-back"',
+            'class="login-mascot-slit"',
+        ):
+            self.assertIn(needle, LOGIN)
+        for needle in (
+            "--login-mascot-red: #e8605a;",
+            "--login-mascot-green: #46be93;",
+            "--login-mascot-height: clamp(150px, 15vw, 260px);",
+        ):
+            self.assertIn(needle, TOKENS)
+        self.assertIn("flex: 1 1 auto;", AUTH)
+        self.assertIn(".login-mascots {", AUTH)
+        self.assertIn("prefers-reduced-motion: reduce", AUTH)
+        self.assertIn('next === "password"', LOGIN_JS)
+        self.assertIn("toggle-password", LOGIN_JS)
+        self.assertIn("celebrateLogin", LOGIN_JS)
+
     def test_portal_keeps_account_switch_and_theme_hooks(self) -> None:
         self.assertIn("data-switch-id", LOGIN_JS)
+        self.assertIn("data-resume-id", LOGIN_JS)
         self.assertIn('data-login-action="manage"', LOGIN_JS)
         self.assertIn('data-login-action="add"', LOGIN_JS)
+        self.assertIn('data-login-action="resume"', LOGIN_JS)
+        self.assertIn("继续使用", LOGIN_JS)
+        self.assertIn("返回复盘", LOGIN_JS)
+        self.assertIn("/api/auth/me", LOGIN_JS)
         self.assertIn("xiaobaiTheme", LOGIN_JS)
         self.assertNotIn("内网个人版", LOGIN)
         self.assertNotIn("192.168.200.11", LOGIN)
         self.assertNotIn("/api/heaven", LOGIN_JS)
+
+    def test_current_account_row_stays_clickable_without_reswitching(self) -> None:
+        self.assertIn("resumeCurrentAccount", LOGIN_JS)
+        self.assertIn("当前会话已失效，请重新登录", LOGIN_JS)
+        self.assertNotIn("!managing && !current ? \"is-switchable\"", LOGIN_JS)
+        session = (ROOT / "frontend" / "shared" / "session.js").read_text(encoding="utf-8")
+        self.assertIn('params.set("next", next)', session)
+        self.assertIn(".login-account-action", AUTH)

tests/test_realtime_dashboard.py

@@ -1,8 +1,16 @@
 from __future__ import annotations
 
 import unittest
+from datetime import datetime, timedelta, timezone
 
 from backend.data.providers.tushare_client import TushareClient
+from backend.data.providers.tushare_helpers import calendar_is_open
+from backend.data.providers.tushare_transport import TushareError
+from backend.data.realtime import (
+    RealtimeAggregateError,
+    _normalize_eastmoney_quote,
+    _parse_tencent_stock_quote,
+)
 
 
 class FakeRealtimeClient(TushareClient):
@@ -81,6 +89,65 @@ class FakeRealtimeClient(TushareClient):
         raise AssertionError(f"Unexpected API call: {api_name} {params}")
 
 
+FREE_QUOTES = [
+    {
+        "ts_code": "000001.SZ", "name": "甲", "pre_close": 10.0,
+        "open": 10.1, "high": 11.0, "low": 10.0, "close": 11.0,
+        "vol": 1000, "amount": 100000000, "num": 10,
+        "quote_date": "20260720",
+    },
+    {
+        "ts_code": "000002.SZ", "name": "乙", "pre_close": 20.0,
+        "open": 19.5, "high": 20.0, "low": 18.0, "close": 18.0,
+        "vol": 2000, "amount": 200000000, "num": 20,
+        "quote_date": "20260720",
+    },
+    {
+        "ts_code": "000003.SZ", "name": "丙", "pre_close": 30.0,
+        "open": 31.0, "high": 33.0, "low": 30.0, "close": 32.0,
+        "vol": 3000, "amount": 300000000, "num": 30,
+        "quote_date": "20260720",
+    },
+]
+
+
+class FakeFreeAggregator:
+    def __init__(self, quotes=None, fail=False):
+        self.quotes = list(quotes if quotes is not None else FREE_QUOTES)
+        self.fail = fail
+        self.calls = 0
+
+    def eastmoney_market_quotes(self, expected_date=""):
+        self.calls += 1
+        if self.fail:
+            raise RealtimeAggregateError("eastmoney down")
+        if expected_date and self.quotes:
+            dated = [
+                row for row in self.quotes
+                if str(row.get("quote_date") or "") == str(expected_date).replace("-", "")
+            ]
+            if dated:
+                return dated
+        return list(self.quotes)
+
+    def tencent_market_quotes(self, codes, expected_date=""):
+        return self.eastmoney_market_quotes(expected_date)
+
+    def eastmoney_indices(self):
+        return [
+            {
+                "code": "000001",
+                "name": "上证指数",
+                "price": 3800.12,
+                "change": 0.85,
+                "previous_close": 3768.0,
+                "amount_billion": 4200.5,
+                "quote_time": "2026-07-20T10:05:00+08:00",
+                "source": "eastmoney_push2",
+            }
+        ]
+
+
 class RealtimeDashboardTests(unittest.TestCase):
     def setUp(self):
         TushareClient._realtime_reference_cache.clear()
@@ -130,6 +197,272 @@ class RealtimeDashboardTests(unittest.TestCase):
         self.assertEqual(dashboard["meta"]["limit_data_source"], "derived")
         self.assertIn("日线数据推算", dashboard["meta"]["notice"])
 
+    def test_calendar_open_flag_accepts_string_and_bool(self):
+        self.assertTrue(calendar_is_open(1))
+        self.assertTrue(calendar_is_open("1"))
+        self.assertTrue(calendar_is_open(True))
+        self.assertFalse(calendar_is_open(0))
+        self.assertFalse(calendar_is_open("0"))
+        self.assertFalse(calendar_is_open(False))
+
+        original_query = self.client.query
+
+        def query(api_name, params=None, fields=""):
+            if api_name == "trade_cal":
+                return [
+                    {
+                        "cal_date": params.get("start_date"),
+                        "is_open": "1",
+                        "pretrade_date": "20260907",
+                    }
+                ]
+            return original_query(api_name, params, fields)
+
+        self.client.query = query
+        trade_date, previous = self.client.resolve_trade_context("20260908")
+        self.assertEqual(trade_date, "20260908")
+        self.assertEqual(previous, "20260907")
+
+    def test_session_clock_uses_realtime_until_official_window(self):
+        today = "20260908"
+        self.client.clock = lambda: datetime(
+            2026, 9, 8, 10, 5, tzinfo=timezone(timedelta(hours=8))
+        )
+        self.assertTrue(self.client.should_use_realtime(today, today))
+        self.client.clock = lambda: datetime(
+            2026, 9, 8, 16, 10, tzinfo=timezone(timedelta(hours=8))
+        )
+        self.assertFalse(self.client.should_use_realtime(today, today))
+
+    def test_realtime_dashboard_survives_missing_limit_table(self):
+        original_query = self.client.query
+
+        def query(api_name, params=None, fields=""):
+            if api_name == "stk_limit":
+                return []
+            return original_query(api_name, params, fields)
+
+        self.client.query = query
+        TushareClient._realtime_reference_cache.clear()
+        dashboard = self.client._realtime_dashboard("20260720", "20260720", "20260717")
+        self.assertTrue(dashboard["meta"]["realtime"])
+        self.assertEqual(dashboard["meta"]["quote_count"], 3)
+        self.assertEqual(dashboard["overview"]["limit_up_count"], 0)
+
+    def test_rt_k_permission_error_falls_back_to_free_quotes(self):
+        original_query = self.client.query
+
+        def query(api_name, params=None, fields=""):
+            if api_name == "rt_k":
+                raise TushareError("没有接口访问权限")
+            return original_query(api_name, params, fields)
+
+        self.client.query = query
+        self.client.realtime_aggregator = FakeFreeAggregator()
+        TushareClient._realtime_reference_cache.clear()
+        dashboard = self.client._realtime_dashboard("20260720", "20260720", "20260717")
+
+        self.assertTrue(dashboard["meta"]["realtime"])
+        self.assertEqual(dashboard["meta"]["quote_source"], "eastmoney_clist")
+        self.assertEqual(dashboard["meta"]["trade_date"], "2026-07-20")
+        self.assertEqual(dashboard["meta"]["quote_count"], 3)
+        self.assertEqual(dashboard["overview"]["limit_up_count"], 1)
+        self.assertEqual(dashboard["overview"]["limit_down_count"], 1)
+        self.assertEqual(dashboard["overview"]["amount_billion"], 6.0)
+        self.assertIn("东财免费实时", dashboard["meta"]["notice"])
+        self.assertEqual(dashboard["meta"]["indices"][0]["price"], 3800.12)
+
+    def test_rt_k_empty_result_falls_back_to_free_quotes(self):
+        original_query = self.client.query
+
+        def query(api_name, params=None, fields=""):
+            if api_name == "rt_k":
+                return []
+            return original_query(api_name, params, fields)
+
+        self.client.query = query
+        self.client.realtime_aggregator = FakeFreeAggregator()
+        TushareClient._realtime_reference_cache.clear()
+        dashboard = self.client._realtime_dashboard("20260720", "20260720", "20260717")
+        self.assertEqual(dashboard["meta"]["quote_source"], "eastmoney_clist")
+        self.assertEqual(str(dashboard["meta"]["trade_date"]).replace("-", ""), "20260720")
+
+    def test_rt_k_and_free_source_failure_keeps_today_error(self):
+        original_query = self.client.query
+
+        def query(api_name, params=None, fields=""):
+            if api_name == "rt_k":
+                raise TushareError("没有接口访问权限")
+            return original_query(api_name, params, fields)
+
+        self.client.query = query
+        self.client.realtime_aggregator = FakeFreeAggregator(fail=True)
+        TushareClient._realtime_reference_cache.clear()
+        with self.assertRaises(TushareError) as ctx:
+            self.client._realtime_dashboard("20260720", "20260720", "20260717")
+        self.assertIn("当天盘中实时行情不可用", str(ctx.exception))
+        self.assertIn("没有接口访问权限", str(ctx.exception))
+
+    def test_rt_k_and_eastmoney_failure_falls_back_to_tencent(self):
+        original_query = self.client.query
+
+        def query(api_name, params=None, fields=""):
+            if api_name == "rt_k":
+                raise TushareError("没有接口访问权限")
+            return original_query(api_name, params, fields)
+
+        class TencentOnlyAggregator(FakeFreeAggregator):
+            def eastmoney_market_quotes(self, expected_date=""):
+                raise RealtimeAggregateError("eastmoney blocked")
+
+            def tencent_market_quotes(self, codes, expected_date=""):
+                return list(FREE_QUOTES)
+
+        self.client.query = query
+        self.client.realtime_aggregator = TencentOnlyAggregator()
+        TushareClient._realtime_reference_cache.clear()
+        dashboard = self.client._realtime_dashboard("20260720", "20260720", "20260717")
+        self.assertEqual(dashboard["meta"]["quote_source"], "tencent_qt")
+        self.assertEqual(str(dashboard["meta"]["trade_date"]).replace("-", ""), "20260720")
+        self.assertIn("腾讯免费实时", dashboard["meta"]["notice"])
+        self.assertEqual(dashboard["overview"]["amount_billion"], 6.0)
+
+    def test_normalize_eastmoney_quote_maps_units_and_exchange(self):
+        quote = _normalize_eastmoney_quote(
+            {
+                "f12": "600000",
+                "f13": 1,
+                "f14": "浦发银行",
+                "f2": 10.5,
+                "f5": 12.0,
+                "f6": 200000000,
+                "f15": 10.8,
+                "f16": 10.2,
+                "f17": 10.3,
+                "f18": 10.0,
+                "f124": 1752986700,
+            }
+        )
+        self.assertEqual(quote["ts_code"], "600000.SH")
+        self.assertEqual(quote["vol"], 1200)
+        self.assertEqual(quote["close"], 10.5)
+        self.assertEqual(quote["pre_close"], 10.0)
+        self.assertEqual(quote["source"], "eastmoney_clist")
+
+    def test_parse_tencent_stock_quote_keeps_today_and_units(self):
+        line = (
+            'v_sz000001="51~平安银行~000001~11.73~11.70~11.66~346232~0~0~0~0~0~0~0~0~0~0~0~0~0~0~0~0~0~0~0~0~0~0~'
+            '~20260720100500~0.03~0.26~11.79~11.65~11.73/346232/406045563~346232~40605~0.18~5.24~~11.79~11.65~1.20~'
+            '2276.29~2276.31~0.49~12.87~10.53~0.95~-3076~11.73~4.43~5.34~~~0.18~40604.5563~0.0000~0~";'
+        )
+        quote = _parse_tencent_stock_quote(line)
+        self.assertEqual(quote["ts_code"], "000001.SZ")
+        self.assertEqual(quote["quote_date"], "20260720")
+        self.assertEqual(quote["close"], 11.73)
+        self.assertEqual(quote["pre_close"], 11.70)
+        self.assertEqual(quote["vol"], 34623200)
+        self.assertEqual(quote["amount"], 406050000)
+        self.assertEqual(quote["source"], "tencent_qt")
+
+    def test_datahub_market_quotes_used_before_legacy(self):
+        calls = []
+
+        def try_market_quotes(trade_date):
+            calls.append(trade_date)
+            return list(FREE_QUOTES)
+
+        self.client.try_market_quotes = try_market_quotes
+        self.client.realtime_aggregator = FakeFreeAggregator(fail=True)
+        TushareClient._realtime_reference_cache.clear()
+        dashboard = self.client._realtime_dashboard("20260720", "20260720", "20260717")
+        self.assertEqual(calls, ["20260720"])
+        self.assertEqual(dashboard["meta"]["quote_source"], "datahub")
+        self.assertEqual(dashboard["meta"]["source"], "datahub")
+        self.assertEqual(dashboard["meta"]["quote_count"], 3)
+        self.assertIn("数据中枢", dashboard["meta"]["notice"])
+
+    def test_gateway_dashboard_uses_bound_market_quotes(self) -> None:
+        from backend.data import build_data_gateway
+        from backend.data.datahub.client import DatahubResponse
+        from backend.data.datahub.settings import DATASETS, DatahubSettings, DatasetFlags
+        from backend.data.gateway import DataGateway
+        from backend.data.providers.tushare import TushareProvider
+
+        quotes = [
+            {
+                "ts_code": item["ts_code"],
+                "name": item["name"],
+                "pre_close": item["pre_close"],
+                "open": item["open"],
+                "high": item["high"],
+                "low": item["low"],
+                "close": item["close"],
+                "vol": item["vol"],
+                "amount": item["amount"],
+                "quote_date": "20260720",
+            }
+            for item in FREE_QUOTES
+        ]
+        extras = [
+            {
+                "ts_code": f"{index:06d}.SZ",
+                "name": f"X{index}",
+                "pre_close": 10.0,
+                "open": 10.0,
+                "high": 10.2,
+                "low": 9.8,
+                "close": 10.1,
+                "vol": 100.0,
+                "amount": 1000.0,
+                "quote_date": "20260720",
+            }
+            for index in range(10, 230)
+        ]
+
+        class QuoteHub:
+            def __init__(self):
+                self.calls = []
+
+            def quotes_latest(self, **params):
+                return self.get("/v1/quotes/latest", params)
+
+            def get(self, path, params=None):
+                self.calls.append(path)
+                if path == "/v1/quotes/latest":
+                    return DatahubResponse(
+                        data=quotes + extras,
+                        meta={"stale": False, "staleness_seconds": 0, "source": "eastmoney_clist"},
+                    )
+                raise AssertionError(path)
+
+        datasets = {name: DatasetFlags(name) for name in DATASETS}
+        datasets["quotes"] = DatasetFlags("quotes", read=True, shadow=False)
+        settings = DatahubSettings(base_url="http://127.0.0.1:9", token="tok", datasets=datasets)
+        base = build_data_gateway({"tushare_token": "tok"}, datahub_settings=settings)
+        gateway = DataGateway(
+            policy=base.policy,
+            quality=base.quality,
+            tushare_provider=TushareProvider(
+                lambda: "tok",
+                client_factory=lambda token: FakeRealtimeClient(token),
+            ),
+            ifind_provider=base.ifind_provider,
+            chart_data=base.chart_data,
+            realtime_observer=base.realtime_observer,
+            datahub=base.datahub,
+        )
+        gateway.datahub.client = QuoteHub()
+        wrapped = gateway.tushare()
+        inner = wrapped._legacy
+        inner.clock = lambda: datetime(2026, 7, 20, 10, 30, tzinfo=timezone(timedelta(hours=8)))
+        inner.realtime_aggregator = FakeFreeAggregator(fail=True)
+        TushareClient._realtime_reference_cache.clear()
+        dashboard = wrapped.dashboard("20260720")
+        self.assertEqual(dashboard["meta"]["quote_source"], "datahub")
+        self.assertIn("/v1/quotes/latest", gateway.datahub.client.calls)
+        self.assertTrue(callable(getattr(inner, "try_market_quotes", None)))
+        self.assertFalse(hasattr(type(inner), "try_market_quotes"))
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_stock_detail_realtime.py

@@ -5,6 +5,10 @@ import unittest
 from datetime import datetime, timedelta
 from unittest.mock import patch
 
+from backend.data.providers.tushare_client import TushareError
+from backend.data.realtime import RealtimeAggregateError
+from backend.features.market.charts import ChartDataError
+from backend.features.market.service import TODAY_DAILY_UNAVAILABLE_NOTICE
 from server import DashboardService
 
 
@@ -17,6 +21,10 @@ class DetailDatabaseStub:
     def list_notes(user_id, code=""):
         return []
 
+    @staticmethod
+    def get_snapshot(trade_date):
+        return {}
+
 
 class RealtimeClientStub:
     quote_calls = 0
@@ -61,6 +69,122 @@ class FixedPreopenDatetime(datetime):
         return cls.fixed_now
 
 
+class FixedLunchDatetime(datetime):
+    fixed_now = datetime(2026, 7, 31, 11, 45).astimezone()
+
+    @classmethod
+    def now(cls, tz=None):
+        return cls.fixed_now
+
+
+class FixedAfterCloseDatetime(datetime):
+    fixed_now = datetime(2026, 7, 31, 15, 30).astimezone()
+
+    @classmethod
+    def now(cls, tz=None):
+        return cls.fixed_now
+
+
+class DeniedRealtimeClientStub:
+    quote_calls = 0
+
+    def __init__(self, token):
+        self.token = token
+
+    @staticmethod
+    def resolve_trade_context(requested_date):
+        return requested_date, requested_date
+
+    @classmethod
+    def realtime_stock_quote(cls, ts_code, reference_date=""):
+        cls.quote_calls += 1
+        raise TushareError("没有接口访问权限")
+
+
+class FreeQuoteAggregator:
+    def __init__(self, quote=None, fail=False):
+        self.quote = quote
+        self.fail = fail
+        self.tencent_calls = 0
+        self.eastmoney_calls = 0
+
+    def tencent_stock_quote(self, code, expected_date=""):
+        self.tencent_calls += 1
+        if self.fail:
+            raise RealtimeAggregateError("tencent down")
+        if self.quote and self.quote.get("source") == "eastmoney_stock":
+            raise RealtimeAggregateError("tencent empty")
+        if self.quote:
+            return self.quote
+        raise RealtimeAggregateError("tencent empty")
+
+    def eastmoney_stock_quote(self, code, expected_date=""):
+        self.eastmoney_calls += 1
+        if self.fail:
+            raise RealtimeAggregateError("eastmoney down")
+        if self.quote and self.quote.get("source") == "eastmoney_stock":
+            return self.quote
+        raise RealtimeAggregateError("eastmoney empty")
+
+
+class IntradayChartStub:
+    def __init__(self, points, previous_close=10.0, trade_date="2026-07-31"):
+        self.points = points
+        self.previous_close = previous_close
+        self.trade_date = trade_date
+
+    def stock_daily(self, code, end_date, limit=90):
+        raise ChartDataError("iFinD daily unavailable")
+
+    def stock_intraday(self, code):
+        return {
+            "trade_date": self.trade_date,
+            "previous_close": self.previous_close,
+            "points": self.points,
+        }
+
+
+def _history_payload(code="002141"):
+    yesterday = (FixedMarketDatetime.fixed_now - timedelta(days=1)).strftime("%Y-%m-%d")
+    return {
+        "meta": {"trade_date": yesterday, "source": "tushare"},
+        "stock": {"code": code, "name": "旧名称", "price": 10, "change": 7.1},
+        "prices": [
+            {
+                "trade_date": yesterday,
+                "open": 9.5,
+                "high": 10.1,
+                "low": 9.4,
+                "close": 10,
+                "change": 7.1,
+                "volume": 100,
+                "amount_billion": 1.1,
+            }
+        ],
+        "moneyflow": {},
+    }
+
+
+def _free_quote(source="tencent_qt", **overrides):
+    quote = {
+        "ts_code": "002141.SZ",
+        "name": "贤程科技",
+        "pre_close": 10.0,
+        "open": 10.2,
+        "high": 10.8,
+        "low": 10.1,
+        "close": 10.6,
+        "vol": 250000,
+        "amount": 26_500_000,
+        "quote_date": "20260731",
+        "quote_time_epoch": int(datetime(2026, 7, 31, 10, 31).timestamp()),
+        "source": source,
+        "turnover_rate": 2.5,
+    }
+    quote.update(overrides)
+    return quote
+
+
 class StockDetailRealtimeTests(unittest.TestCase):
     def setUp(self):
         self.service = DashboardService.__new__(DashboardService)
@@ -68,7 +192,11 @@ class StockDetailRealtimeTests(unittest.TestCase):
         self.service.database = DetailDatabaseStub()
         self.service._request_context = threading.local()
         self.service._request_context.user_id = 1
+        self.service.ifind = None
+        self.service.realtime_aggregator = None
+        self.service.chart_data = None
         RealtimeClientStub.quote_calls = 0
+        DeniedRealtimeClientStub.quote_calls = 0
 
     def test_today_detail_merges_rt_quote_without_mutating_daily_cache(self):
         today = FixedMarketDatetime.fixed_now.strftime("%Y%m%d")
@@ -162,6 +290,183 @@ class StockDetailRealtimeTests(unittest.TestCase):
         self.assertEqual(result["stock"]["change"], 1.2)
         self.assertEqual(RealtimeClientStub.quote_calls, 0)
 
+    def test_today_detail_falls_back_to_tencent_quote_when_rt_k_denied(self):
+        today = FixedMarketDatetime.fixed_now.strftime("%Y%m%d")
+        aggregator = FreeQuoteAggregator(_free_quote())
+        self.service.realtime_aggregator = aggregator
+        DeniedRealtimeClientStub.quote_calls = 0
+
+        with patch("backend.features.market.service.datetime", FixedMarketDatetime), patch(
+            "backend.features.market.service.TushareClient", DeniedRealtimeClientStub
+        ):
+            result = self.service._prepare_stock_detail(_history_payload(), "002141", today)
+
+        bar = result["prices"][-1]
+        self.assertEqual(bar["trade_date"], "2026-07-31")
+        self.assertTrue(bar["realtime"])
+        self.assertEqual(bar["open"], 10.2)
+        self.assertEqual(bar["high"], 10.8)
+        self.assertEqual(bar["low"], 10.1)
+        self.assertEqual(bar["close"], 10.6)
+        self.assertAlmostEqual(bar["change"], 6.0, places=4)
+        self.assertEqual(bar["volume"], 2500)
+        self.assertAlmostEqual(bar["amount_billion"], 0.265)
+        self.assertEqual(len(result["prices"]), 2)
+        self.assertEqual(result["meta"]["notice"], "")
+        self.assertEqual(aggregator.tencent_calls, 1)
+        self.assertEqual(DeniedRealtimeClientStub.quote_calls, 1)
+
+    def test_today_detail_falls_back_to_eastmoney_then_intraday(self):
+        today = FixedMarketDatetime.fixed_now.strftime("%Y%m%d")
+        aggregator = FreeQuoteAggregator(
+            _free_quote("eastmoney_stock", ts_code="600000.SH", name="浦发银行"),
+        )
+        self.service.realtime_aggregator = aggregator
+        DeniedRealtimeClientStub.quote_calls = 0
+
+        with patch("backend.features.market.service.datetime", FixedMarketDatetime), patch(
+            "backend.features.market.service.TushareClient", DeniedRealtimeClientStub
+        ):
+            result = self.service._prepare_stock_detail(_history_payload("600000"), "600000", today)
+
+        self.assertEqual(result["prices"][-1]["trade_date"], "2026-07-31")
+        self.assertEqual(result["prices"][-1]["close"], 10.6)
+        self.assertEqual(aggregator.tencent_calls, 1)
+        self.assertEqual(aggregator.eastmoney_calls, 1)
+
+        aggregator = FreeQuoteAggregator(fail=True)
+        self.service.realtime_aggregator = aggregator
+        self.service.chart_data = IntradayChartStub(
+            [
+                {
+                    "date": "2026-07-31",
+                    "time": "09:30",
+                    "open": 10.1,
+                    "high": 10.2,
+                    "low": 10.0,
+                    "close": 10.15,
+                    "volume": 120,
+                    "amount": 121800,
+                },
+                {
+                    "date": "2026-07-31",
+                    "time": "10:05",
+                    "open": 10.15,
+                    "high": 10.5,
+                    "low": 9.9,
+                    "close": 10.4,
+                    "volume": 80,
+                    "amount": 83200,
+                },
+            ]
+        )
+        with patch("backend.features.market.service.datetime", FixedMarketDatetime), patch(
+            "backend.features.market.service.TushareClient", DeniedRealtimeClientStub
+        ):
+            result = self.service._prepare_stock_detail(_history_payload("300750"), "300750", today)
+
+        bar = result["prices"][-1]
+        self.assertEqual(bar["trade_date"], "2026-07-31")
+        self.assertEqual(bar["open"], 10.1)
+        self.assertEqual(bar["high"], 10.5)
+        self.assertEqual(bar["low"], 9.9)
+        self.assertEqual(bar["close"], 10.4)
+        self.assertAlmostEqual(bar["change"], 4.0, places=4)
+        self.assertEqual(bar["volume"], 200)
+        self.assertTrue(bar["realtime"])
+
+    def test_today_detail_keeps_history_when_free_sources_fail(self):
+        today = FixedMarketDatetime.fixed_now.strftime("%Y%m%d")
+        self.service.realtime_aggregator = FreeQuoteAggregator(fail=True)
+        self.service.chart_data = IntradayChartStub([], trade_date="2026-07-30")
+        DeniedRealtimeClientStub.quote_calls = 0
+
+        with patch("backend.features.market.service.datetime", FixedMarketDatetime), patch(
+            "backend.features.market.service.TushareClient", DeniedRealtimeClientStub
+        ):
+            result = self.service._prepare_stock_detail(_history_payload(), "002141", today)
+
+        self.assertEqual(result["prices"][-1]["trade_date"], "2026-07-30")
+        self.assertFalse(result["meta"].get("realtime", False))
+        self.assertEqual(result["meta"]["notice"], TODAY_DAILY_UNAVAILABLE_NOTICE)
+        self.assertEqual(len(result["prices"]), 1)
+
+    def test_lunch_keeps_morning_realtime_bar(self):
+        today = FixedLunchDatetime.fixed_now.strftime("%Y%m%d")
+        self.service.realtime_aggregator = FreeQuoteAggregator(
+            _free_quote(quote_time_epoch=int(datetime(2026, 7, 31, 11, 30).timestamp()))
+        )
+        DeniedRealtimeClientStub.quote_calls = 0
+        with patch("backend.features.market.service.datetime", FixedLunchDatetime), patch(
+            "backend.features.market.service.TushareClient", DeniedRealtimeClientStub
+        ):
+            result = self.service._prepare_stock_detail(_history_payload(), "002141", today)
+
+        self.assertEqual(result["prices"][-1]["trade_date"], "2026-07-31")
+        self.assertTrue(result["meta"]["realtime"])
+
+    def test_after_close_keeps_forming_bar_until_official_ready(self):
+        today = FixedAfterCloseDatetime.fixed_now.strftime("%Y%m%d")
+        self.service.realtime_aggregator = FreeQuoteAggregator(_free_quote())
+        DeniedRealtimeClientStub.quote_calls = 0
+        with patch("backend.features.market.service.datetime", FixedAfterCloseDatetime), patch(
+            "backend.features.market.service.TushareClient", DeniedRealtimeClientStub
+        ):
+            forming = self.service._prepare_stock_detail(_history_payload(), "002141", today)
+        self.assertEqual(forming["prices"][-1]["trade_date"], "2026-07-31")
+        self.assertTrue(forming["prices"][-1]["realtime"])
+
+        official = _history_payload()
+        official["prices"].append(
+            {
+                "trade_date": "2026-07-31",
+                "open": 10.15,
+                "high": 10.9,
+                "low": 10.05,
+                "close": 10.7,
+                "change": 7.0,
+                "volume": 1800,
+                "amount_billion": 0.3,
+            }
+        )
+        RealtimeClientStub.quote_calls = 0
+        with patch("backend.features.market.service.datetime", FixedAfterCloseDatetime), patch(
+            "backend.features.market.service.TushareClient", RealtimeClientStub
+        ):
+            replaced = self.service._prepare_stock_detail(official, "002141", today)
+
+        self.assertEqual(replaced["prices"][-1]["close"], 10.7)
+        self.assertFalse(replaced["prices"][-1].get("realtime", False))
+        self.assertEqual(len(replaced["prices"]), 2)
+        self.assertEqual(RealtimeClientStub.quote_calls, 0)
+
+    def test_same_date_bar_is_replaced_not_duplicated(self):
+        today = FixedMarketDatetime.fixed_now.strftime("%Y%m%d")
+        payload = _history_payload()
+        payload["prices"].append(
+            {
+                "trade_date": "2026-07-31",
+                "open": 10.0,
+                "high": 10.1,
+                "low": 9.9,
+                "close": 10.05,
+                "change": 0.5,
+                "volume": 10,
+                "amount_billion": 0.01,
+                "realtime": True,
+            }
+        )
+        self.service.realtime_aggregator = FreeQuoteAggregator(_free_quote())
+        DeniedRealtimeClientStub.quote_calls = 0
+        with patch("backend.features.market.service.datetime", FixedMarketDatetime), patch(
+            "backend.features.market.service.TushareClient", DeniedRealtimeClientStub
+        ):
+            result = self.service._prepare_stock_detail(payload, "002141", today)
+
+        self.assertEqual(len(result["prices"]), 2)
+        self.assertEqual(result["prices"][-1]["close"], 10.6)
+        self.assertEqual(result["prices"][-1]["trade_date"], "2026-07-31")
+
 
 if __name__ == "__main__":
     unittest.main()

tools/README.md

@@ -20,12 +20,18 @@ registry, and verification tools.
 - `python tools/backfill_recent_snapshots.py --account <admin> [--lookback 60] [--dry-run]`:
   auditable recent trading-day dashboard snapshot backfill. See
   `docs/maintenance/行情历史补档.md`.
-- `bash tools/build_image.sh <commit> <tag>`: the only sanctioned way to build the
+- `tools/update_from_main.sh` (deployed to the server as
-  production Docker image. Streams `git archive <commit>` to the deploy host over SSH
+  `~/xiaobai-build/update-from-main.sh`): the server-side update-and-build entry for
-  (default `moxiaobai@192.168.200.11`), refuses tags that do not end with the commit
+  the managed local worktree at `/opt/1panel/docker/compose/xiaobaifupan`. Fetches
+  Gitea `main`, enforces branch/clean/fast-forward checks, builds a
+  `main-<shortsha>` tagged image with the revision label, and verifies the label
+  after the build. `tools/xiaobai-git` is the matching git wrapper for that
+  worktree (`status`/`log`/`diff`).
+- `bash tools/build_image.sh <commit> <tag>`: agent-grade entry that streams
+  `git archive <commit>` to the deploy host over SSH (default
+  `moxiaobai@192.168.200.11`), refuses tags that do not end with the commit
   short SHA, verifies the revision label after the build, and appends a record to
-  `~/xiaobai-build/BUILD_LOG.tsv` on the host. Building from any server-side working
+  `~/xiaobai-build/BUILD_LOG.tsv` on the host. Before building, it runs
-  tree is forbidden; see `DOCKER_DEPLOY.md`. Before building, it runs
   `tools/check_deploy_baseline.sh` so the candidate commit must contain the currently
   running container's Git revision as an ancestor.
 - `bash tools/check_deploy_baseline.sh <commit> [--live-revision <sha>]`: deployment

tools/build_architecture_inventory.py

@@ -97,6 +97,7 @@ def code_hotspots() -> list[dict[str, Any]]:
         "backend/features/system/service.py",
         "backend/features/accounts/application.py",
         "backend/jobs/service.py",
+        "backend/jobs/refresh.py",
         "database.py",
         "backend/features/screener/engine.py",
         "backend/features/screener/catalog.py",
@@ -217,10 +218,11 @@ def build() -> dict[str, Any]:
         ),
         "external_data_adapters": [
             {"provider": "tushare", "path": "backend/data/providers/tushare_client.py", "runtime_role": "stable client facade for primary deterministic market data"},
+            {"provider": "datahub", "path": "backend/data/datahub/client.py", "runtime_role": "optional official EOD read path behind per-dataset flags"},
             {"provider": "ifind", "path": "backend/data/providers/ifind_client.py", "runtime_role": "realtime, charts, snapshots, enrichment"},
             {"provider": "eastmoney", "path": "backend/features/market/charts.py", "runtime_role": "display chart fallback"},
-            {"provider": "eastmoney", "path": "backend/data/realtime.py", "runtime_role": "isolated realtime observation"},
+            {"provider": "eastmoney", "path": "backend/data/realtime.py", "runtime_role": "isolated realtime observation and intraday dashboard fallback"},
-            {"provider": "tencent", "path": "backend/data/realtime.py", "runtime_role": "index observation fallback"},
+            {"provider": "tencent", "path": "backend/data/realtime.py", "runtime_role": "index observation and intraday quote fallback"},
         ],
         "provider_domains": [
             {"provider": "tushare", "path": "backend/data/providers/tushare_transport.py", "responsibility": "HTTP transport and provider errors"},
@@ -235,6 +237,9 @@ def build() -> dict[str, Any]:
         ],
         "provider_construction": [
             {"client": "TushareClient", "owner": "backend/data/providers/tushare.py", "compatibility_fallback": "backend/features/market/service.py"},
+            {"client": "DatahubClient", "owner": "backend/data/gateway.py"},
+            {"client": "DatahubBridge", "owner": "backend/data/gateway.py"},
+            {"client": "DatahubAwareTushareClient", "owner": "backend/data/gateway.py"},
             {"client": "IfindHttpClient", "owner": "backend/data/gateway.py"},
             {"client": "MarketChartClient", "owner": "backend/data/gateway.py"},
             {"client": "WebRealtimeAggregator", "owner": "backend/data/gateway.py"},
@@ -261,6 +266,7 @@ def build() -> dict[str, Any]:
             "system_service": "backend/features/system/service.py",
             "account_bridge": "backend/features/accounts/application.py",
             "job_lifecycle": "backend/jobs/service.py",
+            "job_refresh_status": "backend/jobs/refresh.py",
             "feature_routes": "backend/features/*/routes.py",
         },
         "numeric_normalization": [

tools/update_from_main.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# 小白复盘服务器本地目录安全更新/构建入口（HEL-235B 固化）
+# 作用：把 /opt/1panel/docker/compose/xiaobaifupan 的 Git 工作目录安全快进到 Gitea main，
+#       校验“本地 HEAD = origin/main = 镜像 revision”后，从本地目录构建带提交号的镜像。
+# 禁止：不从 main 构建；不使用不带提交短号的 tag；本地有改动/落后/分叉时一律停止。
+# 说明：目录顶层归 root，本脚本用“截断写入”绕开 git 对顶层文件 unlink+重建的权限要求；
+#       但 main 新增/删除顶层文件时无法自动处理，会列出需管理员执行的精确清单。
+set -euo pipefail
+
+GIT_DIR_PATH="$HOME/xiaobai-build/repos/xiaobai-review.git"
+WORK_TREE="/opt/1panel/docker/compose/xiaobaifupan"
+IMAGE_REPO="xiaobai-review"
+LOG_FILE="$HOME/xiaobai-build/BUILD_LOG.tsv"
+MODE="${1:-build}"
+
+g() { git --git-dir="$GIT_DIR_PATH" --work-tree="$WORK_TREE" "$@"; }
+
+refuse() { printf '拒绝：%s\n' "$*" >&2; exit 1; }
+
+[ "$MODE" = "build" ] || [ "$MODE" = "verify-tag" ] || refuse "未知子命令「${MODE}」（可用：build / verify-tag <tag>）"
+[ -d "$GIT_DIR_PATH" ] || refuse "Git 目录不存在：$GIT_DIR_PATH"
+
+echo "==> 拉取 Gitea origin/main"
+g fetch --quiet origin main || refuse "无法连接 Gitea 拉取 origin/main"
+
+echo "==> 检查分支与工作区"
+BRANCH="$(g symbolic-ref --short HEAD 2>/dev/null || true)"
+[ "$BRANCH" = "main" ] || refuse "当前不在 main 分支（${BRANCH:-detached}），停止"
+DIRTY="$(g status --porcelain)"
+[ -z "$DIRTY" ] || refuse "本地目录有未提交改动或多余文件，先处理再构建：
+$DIRTY"
+
+LOCAL_HEAD="$(g rev-parse HEAD)"
+REMOTE_HEAD="$(g rev-parse origin/main)"
+if [ "$LOCAL_HEAD" != "$REMOTE_HEAD" ]; then
+  g merge-base --is-ancestor "$LOCAL_HEAD" "$REMOTE_HEAD" \
+    || refuse "本地 main 与 origin/main 历史分叉，停止（未改写工作目录）"
+  CHANGES="$(g diff --no-renames --name-status HEAD origin/main)"
+  TOP_AD="$(printf '%s\n' "$CHANGES" | grep -E "^[AD][[:space:]]+[^/]+$" || true)"
+  [ -z "$TOP_AD" ] || refuse "main 相比本地新增/删除了顶层文件，目录顶层归 root，需管理员执行：
+$TOP_AD"
+  echo "==> 同步 origin/main 文件（顶层文件保留原 inode，避免目录权限限制）"
+  while IFS=$'\t' read -r status path; do
+    [ -n "$path" ] || continue
+    case "$status" in
+      D)
+        case "$path" in
+          */*) rm -f -- "$WORK_TREE/$path" ;;
+          *) refuse "main 删除了顶层文件 $path，需管理员处理" ;;
+        esac
+        ;;
+      A|M)
+        MODE_BITS="$(g ls-tree origin/main -- "$path" | awk '{print $1}')"
+        case "$MODE_BITS" in
+          100644|100755) ;;
+          *) refuse "文件 ${path} 的 Git 类型 ${MODE_BITS} 不支持自动同步，需管理员处理" ;;
+        esac
+        mkdir -p -- "$(dirname "$WORK_TREE/$path")"
+        g show "origin/main:$path" > "$WORK_TREE/$path"
+        [ "$MODE_BITS" = "100755" ] && chmod 755 "$WORK_TREE/$path" || chmod 644 "$WORK_TREE/$path"
+        ;;
+      *) refuse "遇到未支持的 Git 变更类型 ${status}：${path}" ;;
+    esac
+  done <<< "$CHANGES"
+  g read-tree origin/main
+  g update-ref refs/heads/main "$REMOTE_HEAD" "$LOCAL_HEAD"
+  DIRTY="$(g status --porcelain)"
+  [ -z "$DIRTY" ] || refuse "快进后工作区仍不一致，停止：
+$DIRTY"
+  LOCAL_HEAD="$(g rev-parse HEAD)"
+fi
+[ "$LOCAL_HEAD" = "$REMOTE_HEAD" ] || refuse "本地 HEAD 与 origin/main 不一致，停止"
+SHORT="${LOCAL_HEAD:0:7}"
+echo "==> 校验通过：本地 HEAD = origin/main = ${LOCAL_HEAD}（${SHORT}）"
+
+if [ "$MODE" = "verify-tag" ]; then
+  TAG="${2:?用法: update-from-main.sh verify-tag <tag>}"
+  [ "$TAG" = "main-${SHORT}" ] \
+    || refuse "镜像标签必须是当前 main 对应的 main-${SHORT}，收到：${TAG}"
+  LABEL="$(docker image inspect "${IMAGE_REPO}:${TAG}" \
+    --format '{{index .Config.Labels "org.opencontainers.image.revision"}}' 2>/dev/null)" \
+    || refuse "镜像 ${IMAGE_REPO}:${TAG} 不存在"
+  [ "$LABEL" = "$LOCAL_HEAD" ] || refuse "镜像 revision（${LABEL}）与当前 main（${LOCAL_HEAD}）不一致，禁止部署"
+  echo "==> 通过：${IMAGE_REPO}:${TAG} 的 revision 与 main 一致，可以部署"
+  exit 0
+fi
+
+TAG="main-${SHORT}"
+echo "==> 从本地目录构建 ${IMAGE_REPO}:${TAG}"
+docker build --rm -t "${IMAGE_REPO}:${TAG}" \
+  --label "org.opencontainers.image.revision=${LOCAL_HEAD}" \
+  --label "org.opencontainers.image.created=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  "$WORK_TREE" 2>&1 | tail -5
+
+echo "==> 回读校验镜像 revision"
+GOT="$(docker image inspect "${IMAGE_REPO}:${TAG}" \
+  --format '{{index .Config.Labels "org.opencontainers.image.revision"}}')"
+if [ "$GOT" != "$LOCAL_HEAD" ]; then
+  docker rmi "${IMAGE_REPO}:${TAG}" >/dev/null 2>&1 || true
+  refuse "镜像 revision（${GOT}）与 main（${LOCAL_HEAD}）不一致，已删除镜像"
+fi
+IMAGE_ID="$(docker image inspect "${IMAGE_REPO}:${TAG}" --format '{{.Id}}' | cut -c8-19)"
+mkdir -p "$(dirname "$LOG_FILE")"
+printf '%s\t%s\t%s\t%s\tlocal-worktree\n' \
+  "$(date '+%F %T')" "${IMAGE_REPO}:${TAG}" "${LOCAL_HEAD}" "${IMAGE_ID}" >> "$LOG_FILE"
+
+cat <<EOF
+==> 完成：${IMAGE_REPO}:${TAG}（revision=${LOCAL_HEAD}）
+    部署需人工确认，参考 ~/xiaobai-build/README.md 的换版与回滚步骤。
+EOF

tools/xiaobai-git

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# 查看服务器本地目录 Git 状态的便捷入口：xiaobai-git status / log / diff 等
+exec git \
+  --git-dir="$HOME/xiaobai-build/repos/xiaobai-review.git" \
+  --work-tree="/opt/1panel/docker/compose/xiaobaifupan" \
+  "$@"

xiaobai-datahub/.dockerignore

@@ -0,0 +1,10 @@
+.git
+.gitignore
+.env
+.env.*
+!.env.example
+__pycache__/
+*.py[cod]
+*.log
+data/
+tests/

xiaobai-datahub/.env.example

@@ -0,0 +1,13 @@
+# Fernet key. Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+DATAHUB_ENCRYPTION_KEY=
+
+# Consumer API token for /v1 (32+ random bytes, shown once). Never log this value.
+DATAHUB_TOKEN=
+
+# Initial admin password for /admin. Forced change on first login.
+DATAHUB_ADMIN_PASSWORD=
+
+# Tushare Pro token. Stored encrypted after first launch; never returned by API or admin pages.
+TUSHARE_TOKEN=
+
+TZ=Asia/Shanghai

xiaobai-datahub/Dockerfile

@@ -0,0 +1,36 @@
+FROM python:3.12-slim-bookworm
+
+ARG APP_UID=10002
+ARG APP_GID=10002
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONUTF8=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    TZ=Asia/Shanghai
+
+WORKDIR /app
+
+RUN apt-get update \
+    && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+        ca-certificates \
+        tzdata \
+    && groupadd --gid "${APP_GID}" datahub \
+    && useradd --uid "${APP_UID}" --gid "${APP_GID}" --create-home --shell /usr/sbin/nologin datahub \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt ./
+RUN python -m pip install --no-cache-dir -r requirements.txt
+
+COPY --chown=datahub:datahub . .
+RUN mkdir -p /app/data /app/data/backups && chown -R datahub:datahub /app/data
+
+USER datahub
+
+EXPOSE 8766
+STOPSIGNAL SIGINT
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+    CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8766/livez', timeout=4).read()"]
+
+CMD ["python", "-u", "server.py", "--host", "0.0.0.0", "--port", "8766"]

xiaobai-datahub/README.md

@@ -0,0 +1,152 @@
+# xiaobai-datahub
+
+独立行情数据中枢（HEL-382 / P0）。与 `xiaobai-review` 同仓库、不同容器、不共享数据库文件。
+本阶段不部署现网；只提供可本地运行、可自测的底座和盘后正式数据链路。
+
+## 做什么
+
+- SQLite WAL `datahub.db`，容器名 `xiaobai-datahub`，端口 `8766`
+- Tushare 盘后正式数据：交易日历、股票主档、daily、daily_basic、adj_factor、index_daily、moneyflow、stk_auction、limit_list_d、ths_hot/dc_hot、hm_detail、ths_daily/dc_index/sw_daily
+- 盘中观察（provisional）：东财/腾讯指数报价、个股最新价、全市场快照、分时点（`/v1/quotes/latest` 不传 codes 即全市场，`/v1/indexes/quotes` `/v1/intraday/points`）；永不写入 eod_* 正式表
+- 暂存 → 校验 → 整批原子发布 → 可回滚
+- `/v1` 稳定接口（`X-Datahub-Token`）
+- `/admin/` 最小管理后台（总览 / 数据源 / 调度 / 发布 / 数据集 / 审计）
+- 同花顺/选股宝/AKShare/iFinD 适配器位仍预留；东财/腾讯已接入盘中观察
+
+## 单位口径（相对现站）
+
+现站 `xiaobai-review` 按 Tushare 原始单位入库、展示时再换算。中枢在归一化层一次换算：
+
+| 字段 | Tushare / 现站 | 中枢 canonical |
+|---|---|---|
+| `daily.amount` / `index_daily.amount` | 千元 | 元（×1000） |
+| `daily.vol` / `index_daily.vol` | 手 | 股（×100） |
+| `moneyflow.*_amount` | 万元 | 元（×1e4） |
+| `daily_basic.total_mv` / `circ_mv` | 万元 | 元（×1e4） |
+| `stk_auction.amount` | 元 | 元 |
+
+差异为口径升级，golden 测试按上表对照，不为 0 的字段都有说明。
+
+## 本地启动（不走 Docker）
+
+```bash
+cd xiaobai-datahub
+python -m venv .venv && .venv/bin/pip install -r requirements.txt
+cp .env.example .env
+# 填入 DATAHUB_ENCRYPTION_KEY / DATAHUB_TOKEN / DATAHUB_ADMIN_PASSWORD / TUSHARE_TOKEN
+# 生成 Fernet 密钥：
+# python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+.venv/bin/python server.py --host 127.0.0.1 --port 8766
+```
+
+- 管理后台：http://127.0.0.1:8766/admin/
+- 存活检查：http://127.0.0.1:8766/livez （无需 token）
+- `/v1/*` 必须带请求头 `X-Datahub-Token`
+
+## Docker（独立 compose，不改现网 review 服务）
+
+```bash
+cd xiaobai-datahub
+cp .env.example .env   # 填密钥
+mkdir -p data
+docker compose build
+docker compose up -d
+```
+
+仓库根目录另有 `compose.datahub.yaml`，供总工以后与现有 `compose.yaml` 叠加部署，本卡不执行现网 `up`。
+
+## 自测
+
+```bash
+cd xiaobai-datahub
+python -m unittest discover -s tests -v
+```
+
+不调用真实 Tushare；用内存/临时库和假适配器。
+
+## 历史回补
+
+交易日历默认从 `20160101` 拉到今天后 30 天；盘前 `precheck` 与手动回补都走同一 UPSERT，可重复执行。
+
+网站实际使用的指数（上证、深成、创业板、沪深300）按交易日增量发布，默认覆盖 260 个交易日（大于现有 90 天窗口，并覆盖智能选股基准回看）。已发布日期默认跳过。
+
+```bash
+cd xiaobai-datahub
+python -m datahub history-backfill
+# 可选：--calendar-start 20160101 --index-days 260 --force
+```
+
+管理后台也可手动跑 `history_backfill` 任务，或 `POST /admin/api/backfill` 且 `dataset=history`、确认词 `history:full`。
+
+区间接口在 `meta.coverage` / `meta.incomplete` 标明覆盖是否完整；网站只读接入把不完整区间视为不可用并回旧链路。个股日 K 的 90 天区间查询依赖已核实，本阶段不回补全市场历史。
+
+## 估值字段级质量门
+
+`hub-quality.config.json` 的 `field_gates` 按数据集配置关键字段：非空率下限（支持按字段覆盖，如 `dv_ttm` 合法高空值）、非有限值比例上限、以及相对上一已发布批次的非空率塌陷保护。字段大面积为空的批次会被拒绝发布、保留上一份正常正式数据，失败原因逐字段写入 `batches.error` / `quality_json`。被拒后数据集仍视为缺失，盘后自动重试（HEL-435 机制）会继续尝试直到成功或截止。配置对任意数据集生效，不写死单日或单字段。
+
+## 整批原子发布（release group）
+
+盘后发布/重发（eod_a、eod_retry、`eod-refresh`、跨数据集重发）不再逐数据集各自切换，而是走整批原子可见机制：
+
+- 一致性边界：日 K、估值、资金流、竞价同属 A 组整批；指数日 K 为 B 组；当日股票主档快照随 A 组一同切换（主档 `stock_master` 的 UPSERT 与快照发布同一事务，不会出现主档先行/滞后）。
+- 流程：组内全部成员先在暂存表完成拉取、字段质量门、覆盖检查和跨数据集交叉校验（`cross_gates` 配置 ts_code 覆盖重叠率下限），全部达标后才在**一个 SQLite 事务**里复制正式表并翻转全部 `publications` 指针。
+- 任一成员失败（拉取失败、质量门拒绝、交叉校验不过、切换事务中断）→ 整批不切换，对外继续提供上一份完整正式版本，失败原因写入 `batches.error` 与 `audit_log`（`action=release-group`），等待晚间自动重试。
+- 读取侧任何时刻只会看到"旧完整版本"或"新完整版本"：发布指针在单事务内统一翻转，容器重启/事务中断自动回滚，不暴露字段残缺或跨数据集混合版本。
+- 幂等：仅当一致性边界内全部成员都已发布时才整组跳过；边界内任有缺失则整组重暂存后统一切换，避免旧批次与新批次混在同一次重发中。重复执行、并发重试不会在完整边界已就绪时生成重复批次（调度器另有 EOD 互斥锁）。
+
+## 股票主档每日刷新与发布
+
+交易日 20:00 与 23:10（`stocks_refresh_times` 可配）自动刷新股票主档并发布版本化快照（`eod_stocks` + `publications.dataset='stocks'`），覆盖当日新上市、证券简称变化和上市首日 N/C 前缀摘除；无变化则跳过，重复执行幂等。`/v1/stocks` 从最新已发布快照提供数据并带 `batch_id` / `published_at`；`/v1/datasets/status` 同步展示 stocks 状态。
+
+```bash
+cd xiaobai-datahub
+python -m datahub stocks-refresh            # 手动触发；--force 无变化也重发
+```
+
+## 资金流历史回补
+
+网站会沿真实调用链查最近若干交易日的 moneyflow（个股详情任意日期点查 + 智能选股最近 5 个交易日），默认回补最近 60 个交易日（`moneyflow_history_trading_days` 可配，已发布日期自动跳过）。点查未覆盖的历史日期返回 `DATASET_NOT_PUBLISHED` 并附 `available_from` / `available_to`（低于下界时 `reason=history_not_backfilled`），网站据此明确回退旧链路，不会静默拿到半截数据。
+
+```bash
+cd xiaobai-datahub
+python -m datahub moneyflow-backfill        # --trading-days 60 --end-date --force 可选
+```
+
+## 盘后补跑与强制重发
+
+```bash
+cd xiaobai-datahub
+python -m datahub eod-refresh --trade-date 20260904                  # 补不完整的 A/B 边界
+python -m datahub eod-refresh --trade-date 20260904 --force --dataset valuation
+# --force 按一致性边界整组重发：valuation/daily/moneyflow/auction/stocks → A 组；
+# index_daily → B 组。不可再单独切换某一个正式数据集。
+```
+
+管理后台「补数」对盘后正式数据集同样走 `force_republish_boundary`，不会绕过 A/B 整批边界。
+
+## 估值发布后复核与自动追补
+
+Tushare `daily_basic` 会在盘后继续改当日字段。HEL-423 在 2026-09-07 观察到：中枢 17:10 发布 `003021.SZ turnover_rate=1.3565`，21:05 上游/旧链路已是 `1.3572`；其余 7 类观察对象当日一致。日 K、资金流、竞价、指数没有同类晚间修订证据，股票主档已有 20:00/23:10 刷新，因此默认只复核估值，不盲目全量重拉。
+
+窗口（可配）：交易日 **20:00–23:20**，每 30 分钟一次轻量比对（对齐网站 21:00 / 23:30 观察）。只拉取 `daily_basic`，按网站真实请求字段精确比较，无误差豁免。
+
+- 无变化：不产生新批次，状态「已追平」。
+- 发现修订：重新走字段质量门、覆盖检查和 A 组整批原子发布；读者全程只能看到上一完整版本或新完整版本。
+- 上游空 / 接口失败 / 不完整 / 质量门拒绝：保留上一完整版本，状态「复核失败」。
+- 23:20 截止后停止当晚复核；下一自然日盘前对上一交易日再做一次安全追赶。
+- 与 `eod_a` / `eod_retry` 共用互斥锁；容器重启会在窗口内立即补一次。
+
+## 备份
+
+每日 00:40 任务把 `datahub.db` 备份到 `data/backups/`（保留 14 份）。也可手动：
+
+```bash
+python -c "from pathlib import Path; from datahub.db import HubDB; HubDB(Path('data/datahub.db')).backup_to(Path('data/backups/manual.db'))"
+```
+
+## 安全
+
+- 密钥只以 `configured / 末4位 / 更新时间` 出现在后台，不进日志、不进 `/v1`
+- HTTP 解析失败只记录“请求不是合法 JSON”，不把请求正文、密码或 Token 写入容器日志
+- 回滚、补数需重新输入密码 + 确认词
+- 容器非 root（uid 10002）、read_only、cap_drop ALL

xiaobai-datahub/admin/app.js

@@ -0,0 +1,299 @@
+const state = { csrf: "", page: "overview" };
+
+function $(id) { return document.getElementById(id); }
+
+async function api(path, options = {}) {
+  const headers = Object.assign({ "Content-Type": "application/json" }, options.headers || {});
+  if (state.csrf && (options.method || "GET") !== "GET") headers["X-CSRF-Token"] = state.csrf;
+  const res = await fetch(path, Object.assign({}, options, { headers, credentials: "same-origin" }));
+  const body = await res.json();
+  if (!res.ok) {
+    const msg = (body.error && body.error.message) || body.error || res.statusText;
+    throw new Error(msg);
+  }
+  return body;
+}
+
+function show(id) {
+  ["login-view", "change-view", "shell"].forEach((key) => { $(key).hidden = key !== id; });
+}
+
+function esc(value) {
+  return String(value ?? "").replace(/[&<>"]/g, (ch) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[ch]));
+}
+
+function table(headers, rows) {
+  const thead = headers.map((h) => `<th>${esc(h)}</th>`).join("");
+  const body = rows.length
+    ? rows.map((cols) => `<tr>${cols.map((c) => `<td>${c}</td>`).join("")}</tr>`).join("")
+    : `<tr><td colspan="${headers.length}">暂无数据</td></tr>`;
+  return `<table><thead><tr>${thead}</tr></thead><tbody>${body}</tbody></table>`;
+}
+
+async function boot() {
+  try {
+    const session = await api("/admin/api/session");
+    state.csrf = session.csrf;
+    $("who").textContent = session.username;
+    if (session.must_change) { show("change-view"); return; }
+    show("shell");
+    await render();
+  } catch {
+    show("login-view");
+  }
+}
+
+$("login-form").addEventListener("submit", async (event) => {
+  event.preventDefault();
+  const form = new FormData(event.target);
+  $("login-error").hidden = true;
+  try {
+    const result = await api("/admin/api/login", {
+      method: "POST",
+      body: JSON.stringify({ username: form.get("username"), password: form.get("password") }),
+    });
+    state.csrf = result.csrf;
+    if (result.must_change) show("change-view");
+    else { show("shell"); await render(); }
+  } catch (err) {
+    $("login-error").hidden = false;
+    $("login-error").textContent = err.message;
+  }
+});
+
+$("change-form").addEventListener("submit", async (event) => {
+  event.preventDefault();
+  const form = new FormData(event.target);
+  try {
+    await api("/admin/api/change-password", {
+      method: "POST",
+      body: JSON.stringify({ current: form.get("current"), new_password: form.get("new_password") }),
+    });
+    show("shell");
+    await render();
+  } catch (err) {
+    $("change-error").hidden = false;
+    $("change-error").textContent = err.message;
+  }
+});
+
+$("logout-btn").addEventListener("click", async () => {
+  await api("/admin/api/logout", { method: "POST", body: "{}" });
+  show("login-view");
+});
+
+$("theme-btn").addEventListener("click", () => {
+  const root = document.documentElement;
+  const next = root.getAttribute("data-theme") === "night" ? "" : "night";
+  if (next) root.setAttribute("data-theme", next);
+  else root.removeAttribute("data-theme");
+  $("theme-btn").textContent = next ? "日间" : "夜间";
+});
+
+document.querySelectorAll("nav button").forEach((btn) => {
+  btn.addEventListener("click", () => {
+    document.querySelectorAll("nav button").forEach((item) => item.classList.remove("active"));
+    btn.classList.add("active");
+    state.page = btn.dataset.page;
+    render();
+  });
+});
+
+async function render() {
+  const page = $("page");
+  if (state.page === "overview") {
+    const data = await api("/admin/api/overview");
+    $("phase").textContent = data.session_phase;
+    const eod = data.eod_status || {};
+    const rev = data.revision_status || {};
+    const eodLabels = {
+      pending_first_attempt: "等待首次尝试",
+      waiting_upstream: "等待上游",
+      done: "已成功",
+      cutoff_failed: "已截止失败",
+      closed_day: "休市",
+    };
+    const revLabels = {
+      waiting_review: "等待复核",
+      review_failed: "复核失败",
+      aligned: "已追平",
+      cutoff: "已截止",
+      pending_publish: "待发布",
+      closed_day: "休市",
+    };
+    const eodExtra = [];
+    if (eod.state === "waiting_upstream") {
+      eodExtra.push(`已试 ${eod.attempts} 次`);
+      if (eod.next_retry_at) eodExtra.push(`下次重试 ${esc(String(eod.next_retry_at).replace("T", " ").slice(11, 16))}`);
+      if (eod.missing_datasets && eod.missing_datasets.length) eodExtra.push(`缺 ${esc(eod.missing_datasets.join(","))}`);
+    }
+    if (eod.state === "cutoff_failed" && eod.missing_datasets) {
+      eodExtra.push(`缺 ${esc(eod.missing_datasets.join(","))}`);
+    }
+    const revExtra = [];
+    if (rev.detail) revExtra.push(esc(String(rev.detail)));
+    if (rev.window) revExtra.push(esc(String(rev.window)));
+    page.innerHTML = `
+      <div class="cards">
+        <div class="card"><div class="muted">交易日</div><strong>${esc(data.trade_date)}</strong></div>
+        <div class="card"><div class="muted">阶段</div><strong>${esc(data.session_phase)}</strong></div>
+        <div class="card"><div class="muted">今日发布</div><strong>${data.publications.length}</strong></div>
+        <div class="card"><div class="muted">盘后补跑</div><strong>${esc(eodLabels[eod.state] || eod.state || "-")}</strong><div class="muted">${eodExtra.join(" · ")}</div></div>
+        <div class="card"><div class="muted">估值复核</div><strong>${esc(revLabels[rev.state] || rev.state || "-")}</strong><div class="muted">${revExtra.join(" · ")}</div></div>
+        <div class="card"><div class="muted">异常批次</div><strong class="${data.anomalies.length ? "fail" : "ok"}">${data.anomalies.length}</strong></div>
+      </div>
+      <h2>最近调用</h2>
+      ${table(["时间", "源", "端点", "结果", "耗时"], data.recent_calls.map((row) => [
+        esc(row.created_at), esc(row.provider), esc(row.endpoint),
+        row.ok ? '<span class="ok">成功</span>' : `<span class="fail">${esc(row.error)}</span>`,
+        `${row.latency_ms ?? "-"} ms`,
+      ]))}
+    `;
+    return;
+  }
+  if (state.page === "sources") {
+    const data = await api("/admin/api/sources");
+    page.innerHTML = `<h2>数据源</h2>` + table(
+      ["源", "角色", "状态", "凭据", "操作"],
+      data.items.map((item) => {
+        const cred = item.credential || {};
+        const credText = cred.configured ? `已配置 · ${esc(cred.last4 || "****")}` : "未配置";
+        return [
+          esc(item.provider),
+          esc(item.role),
+          esc((item.health && (item.health.state || item.health.status)) || "-"),
+          credText,
+          `<button data-probe="${esc(item.provider)}">探测一次</button>`,
+        ];
+      }),
+    );
+    page.querySelectorAll("[data-probe]").forEach((btn) => {
+      btn.addEventListener("click", async () => {
+        const result = await api(`/admin/api/sources/${btn.dataset.probe}/probe`, { method: "POST", body: "{}" });
+        alert(JSON.stringify(result));
+        render();
+      });
+    });
+    return;
+  }
+  if (state.page === "jobs") {
+    const data = await api("/admin/api/jobs");
+    page.innerHTML = `
+      <h2>调度任务</h2>
+      ${table(["任务", "时刻", "操作"], data.jobs.map((job) => [
+        `${esc(job.id)} · ${esc(job.title)}`, esc(job.at),
+        `<button data-run="${esc(job.id)}">手动触发</button>`,
+      ]))}
+      <h3>最近运行</h3>
+      ${table(["ID", "任务", "状态", "开始", "结束", "错误"], data.runs.map((row) => [
+        row.id, esc(row.job_id), esc(row.state), esc(row.started_at), esc(row.finished_at), esc(row.error),
+      ]))}
+    `;
+    page.querySelectorAll("[data-run]").forEach((btn) => {
+      btn.addEventListener("click", async () => {
+        const date = prompt("交易日 YYYYMMDD（可留空=今天）", "") || "";
+        await api(`/admin/api/jobs/${btn.dataset.run}/run`, { method: "POST", body: JSON.stringify({ trade_date: date }) });
+        render();
+      });
+    });
+    return;
+  }
+  if (state.page === "release") {
+    const date = new Date().toISOString().slice(0, 10).replace(/-/g, "");
+    const data = await api(`/admin/api/batches?date=${date}`);
+    page.innerHTML = `
+      <h2>盘后发布 ${esc(data.trade_date)}</h2>
+      <div class="toolbar">
+        <label>日期 <input id="rel-date" value="${esc(data.trade_date)}" /></label>
+        <button type="button" id="rel-load">查看</button>
+        <button type="button" id="rel-backfill">补数</button>
+      </div>
+      <h3>当前映射</h3>
+      ${table(["数据集", "活跃批次", "上一批次", "状态", "发布时间", "操作"], data.publications.map((row) => [
+        esc(row.dataset), esc(row.active_batch), esc(row.prev_batch), esc(row.state), esc(row.published_at),
+        row.prev_batch ? `<button class="danger" data-rollback="${esc(row.dataset)}">回滚</button>` : "-",
+      ]))}
+      <h3>批次</h3>
+      ${table(["batch_id", "数据集", "状态", "行数", "错误"], data.batches.map((row) => [
+        esc(row.batch_id), esc(row.dataset), esc(row.state), row.rows_out ?? "", esc(row.error),
+      ]))}
+    `;
+    $bindRelease(page);
+    return;
+  }
+  if (state.page === "datasets") {
+    const data = await api("/admin/api/datasets?date=");
+    page.innerHTML = `
+      <h2>数据集 / 质量 ${esc(data.trade_date)}</h2>
+      ${table(["数据集", "批次", "状态", "发布时间"], data.publications.map((row) => [
+        esc(row.dataset), esc(row.active_batch), esc(row.state), esc(row.published_at),
+      ]))}
+      <h3>源间差异</h3>
+      ${table(["指标", "左", "右", "偏差", "样本"], data.diff_reports.map((row) => [
+        esc(row.metric), esc(row.left_value), esc(row.right_value), esc(row.deviation), row.sample_count ?? "",
+      ]))}
+    `;
+    return;
+  }
+  if (state.page === "audit") {
+    const data = await api("/admin/api/audit");
+    page.innerHTML = `<h2>审计</h2>` + table(
+      ["时间", "操作者", "动作", "对象", "详情"],
+      data.items.map((row) => [esc(row.created_at), esc(row.actor), esc(row.action), esc(row.target), esc(row.detail)]),
+    );
+  }
+}
+
+function $bindRelease(page) {
+  page.querySelector("#rel-load").addEventListener("click", async () => {
+    const date = page.querySelector("#rel-date").value;
+    const data = await api(`/admin/api/batches?date=${encodeURIComponent(date)}`);
+    state.page = "release";
+    // re-render with fetched date by writing location hash
+    history.replaceState(null, "", `#release-${date}`);
+    $("page").innerHTML = renderRelease(data);
+    $bindRelease($("page"));
+  });
+  page.querySelector("#rel-backfill").addEventListener("click", () => dangerous("backfill"));
+  page.querySelectorAll("[data-rollback]").forEach((btn) => {
+    btn.addEventListener("click", () => dangerous("rollback", btn.dataset.rollback));
+  });
+}
+
+function renderRelease(data) {
+  return `
+    <h2>盘后发布 ${esc(data.trade_date)}</h2>
+    <div class="toolbar">
+      <label>日期 <input id="rel-date" value="${esc(data.trade_date)}" /></label>
+      <button type="button" id="rel-load">查看</button>
+      <button type="button" id="rel-backfill">补数</button>
+    </div>
+    <h3>当前映射</h3>
+    ${table(["数据集", "活跃批次", "上一批次", "状态", "发布时间", "操作"], data.publications.map((row) => [
+      esc(row.dataset), esc(row.active_batch), esc(row.prev_batch), esc(row.state), esc(row.published_at),
+      row.prev_batch ? `<button class="danger" data-rollback="${esc(row.dataset)}">回滚</button>` : "-",
+    ]))}
+    <h3>批次</h3>
+    ${table(["batch_id", "数据集", "状态", "行数", "错误"], data.batches.map((row) => [
+      esc(row.batch_id), esc(row.dataset), esc(row.state), row.rows_out ?? "", esc(row.error),
+    ]))}
+  `;
+}
+
+async function dangerous(kind, dataset) {
+  const date = ($("rel-date") && $("rel-date").value) || "";
+  const ds = dataset || prompt("数据集（daily/valuation/moneyflow/auction/stocks→A组整批；index_daily→B组；或 reference）", "daily");
+  if (!ds) return;
+  const password = prompt("二次确认：输入管理密码");
+  if (!password) return;
+  const confirmWord = `${ds}:${date}`;
+  const typed = prompt(`请输入确认词：${confirmWord}`);
+  const path = kind === "rollback" ? "/admin/api/rollback" : "/admin/api/backfill";
+  await api(path, {
+    method: "POST",
+    body: JSON.stringify({ dataset: ds, trade_date: date, password, confirm: typed }),
+  });
+  render();
+}
+
+boot();

xiaobai-datahub/admin/index.html

@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>xiaobai-datahub 管理后台</title>
+  <link rel="stylesheet" href="/admin/styles.css" />
+</head>
+<body>
+  <div id="app">
+    <section id="login-view" class="panel auth-panel">
+      <h1>数据中枢</h1>
+      <p class="muted">内网管理后台，用于查看源状态、调度和盘后发布批次。</p>
+      <form id="login-form">
+        <label>账号 <input name="username" value="hub_admin" autocomplete="username" /></label>
+        <label>密码 <input name="password" type="password" autocomplete="current-password" /></label>
+        <button type="submit">登录</button>
+        <p id="login-error" class="error" hidden></p>
+      </form>
+    </section>
+
+    <section id="change-view" class="panel auth-panel" hidden>
+      <h1>修改初始密码</h1>
+      <form id="change-form">
+        <label>当前密码 <input name="current" type="password" /></label>
+        <label>新密码（至少 8 位） <input name="new_password" type="password" /></label>
+        <button type="submit">保存并继续</button>
+        <p id="change-error" class="error" hidden></p>
+      </form>
+    </section>
+
+    <section id="shell" hidden>
+      <header class="top">
+        <strong>xiaobai-datahub</strong>
+        <span id="phase" class="pill"></span>
+        <span id="who" class="muted"></span>
+        <button type="button" id="theme-btn" class="ghost">夜间</button>
+        <button type="button" id="logout-btn" class="ghost">退出</button>
+      </header>
+      <nav>
+        <button data-page="overview" class="active">总览</button>
+        <button data-page="sources">数据源</button>
+        <button data-page="jobs">调度任务</button>
+        <button data-page="release">盘后发布</button>
+        <button data-page="datasets">数据集</button>
+        <button data-page="audit">审计</button>
+      </nav>
+      <main id="page"></main>
+    </section>
+  </div>
+  <script src="/admin/app.js"></script>
+</body>
+</html>

xiaobai-datahub/admin/styles.css

@@ -0,0 +1,51 @@
+:root {
+  color-scheme: light;
+  --bg: #f4f5f7;
+  --surface: #ffffff;
+  --text: #1f2329;
+  --muted: #646a73;
+  --line: #dee0e3;
+  --action: #3370ff;
+  --danger: #e04536;
+  --ok: #16a34a;
+  --warn: #b45309;
+  --radius: 8px;
+  --pad: 16px;
+  font-family: "Segoe UI", "PingFang SC", "Noto Sans SC", sans-serif;
+}
+:root[data-theme="night"] {
+  color-scheme: dark;
+  --bg: #111318;
+  --surface: #1b1e24;
+  --text: #e8eaed;
+  --muted: #9aa0a6;
+  --line: #2a2f38;
+  --action: #5b8cff;
+}
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--text); }
+.panel, header.top, nav, main { background: var(--surface); }
+.auth-panel { max-width: 420px; margin: 12vh auto; padding: 28px; border-radius: var(--radius); border: 1px solid var(--line); }
+label { display: block; margin: 12px 0; }
+input, select { width: 100%; padding: 8px 10px; border: 1px solid var(--line); border-radius: 4px; background: var(--bg); color: var(--text); }
+button { background: var(--action); color: #fff; border: 0; border-radius: 4px; padding: 8px 14px; cursor: pointer; }
+button.ghost { background: transparent; color: var(--text); border: 1px solid var(--line); }
+button.danger { background: var(--danger); }
+.muted { color: var(--muted); }
+.error { color: var(--danger); }
+.top { display: flex; gap: 12px; align-items: center; padding: 10px var(--pad); border-bottom: 1px solid var(--line); }
+nav { display: flex; gap: 4px; padding: 8px var(--pad); border-bottom: 1px solid var(--line); }
+nav button { background: transparent; color: var(--muted); }
+nav button.active { color: var(--action); background: transparent; font-weight: 600; }
+main { padding: var(--pad); min-height: calc(100vh - 96px); }
+.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 12px; margin-bottom: 16px; }
+.card { border: 1px solid var(--line); border-radius: var(--radius); padding: 12px; }
+table { width: 100%; border-collapse: collapse; font-size: 13px; }
+th, td { text-align: left; padding: 8px; border-bottom: 1px solid var(--line); vertical-align: top; }
+.pill { font-size: 12px; padding: 2px 8px; border-radius: 999px; border: 1px solid var(--line); }
+.ok { color: var(--ok); }
+.warn { color: var(--warn); }
+.fail { color: var(--danger); }
+.toolbar { display: flex; gap: 8px; flex-wrap: wrap; margin: 12px 0; align-items: end; }
+.toolbar label { margin: 0; }
+dialog { border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); color: var(--text); padding: 20px; }

xiaobai-datahub/compose.yaml

@@ -0,0 +1,39 @@
+services:
+  xiaobai-datahub:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: xiaobai-datahub:local
+    container_name: xiaobai-datahub
+    ports:
+      - "0.0.0.0:8766:8766/tcp"
+    env_file:
+      - ./.env
+    environment:
+      DATAHUB_ENCRYPTION_KEY: "${DATAHUB_ENCRYPTION_KEY:?DATAHUB_ENCRYPTION_KEY must be set}"
+      DATAHUB_TOKEN: "${DATAHUB_TOKEN:?DATAHUB_TOKEN must be set}"
+      DATAHUB_ADMIN_PASSWORD: "${DATAHUB_ADMIN_PASSWORD:?DATAHUB_ADMIN_PASSWORD must be set}"
+      TUSHARE_TOKEN: "${TUSHARE_TOKEN:-}"
+      DATAHUB_DB_PATH: /app/data/datahub.db
+      DATAHUB_BACKUP_DIR: /app/data/backups
+      TZ: Asia/Shanghai
+      PYTHONUTF8: "1"
+    volumes:
+      - type: bind
+        source: ./data
+        target: /app/data
+    restart: unless-stopped
+    init: true
+    read_only: true
+    tmpfs:
+      - /tmp:size=64m,mode=1777
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    stop_grace_period: 30s
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"

xiaobai-datahub/config/hub-quality.config.json

@@ -0,0 +1,62 @@
+{
+  "daily_row_ratio": 0.98,
+  "null_rate_max": 0.01,
+  "cross_check_price_deviation": 0.03,
+  "cross_check_outlier_ratio": 0.05,
+  "index_price_deviation": 0.005,
+  "max_publish_attempts": 5,
+  "staging_retain_days": 14,
+  "job_run_retain_days": 90,
+  "backup_retain": 14,
+  "publication_generations": 3,
+  "tushare_rate_per_minute": 300,
+  "list_limit_default": 5000,
+  "list_limit_max": 5000,
+  "calendar_start": "20160101",
+  "index_history_trading_days": 260,
+  "eod_retry_start": "15:15",
+  "eod_retry_interval_minutes": 30,
+  "eod_retry_cutoff": "23:30",
+  "revision_review_datasets": ["valuation"],
+  "revision_review_start": "20:00",
+  "revision_review_interval_minutes": 30,
+  "revision_review_cutoff": "23:20",
+  "moneyflow_history_trading_days": 60,
+  "stocks_refresh_times": [
+    "20:00",
+    "23:10"
+  ],
+  "cross_gates": [
+    {
+      "left": "daily",
+      "right": "valuation",
+      "min_key_overlap": 0.98
+    },
+    {
+      "left": "daily",
+      "right": "moneyflow",
+      "min_key_overlap": 0.98
+    }
+  ],
+  "field_gates": {
+    "valuation": {
+      "fields": [
+        "turnover_rate",
+        "volume_ratio",
+        "total_mv",
+        "circ_mv",
+        "pe_ttm",
+        "pb",
+        "ps_ttm",
+        "dv_ttm"
+      ],
+      "min_nonnull_rate": 0.9,
+      "min_nonnull_rate_by_field": {
+        "pe_ttm": 0.5,
+        "dv_ttm": 0.3
+      },
+      "max_nonnull_drop_vs_prev": 0.15,
+      "max_nonfinite_rate": 0.01
+    }
+  }
+}

xiaobai-datahub/datahub/__init__.py

@@ -0,0 +1,4 @@
+"""xiaobai-datahub: independent market-data service for xiaobai-review."""
+
+__version__ = "0.1.0"
+SCHEMA_VERSION = 1

xiaobai-datahub/datahub/__main__.py

@@ -0,0 +1,4 @@
+from datahub.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

xiaobai-datahub/datahub/adapters/__init__.py

@@ -0,0 +1,15 @@
+from datahub.adapters.akshare import ADAPTER as akshare
+from datahub.adapters.eastmoney import EastmoneyAdapter
+from datahub.adapters.ifind import ADAPTER as ifind
+from datahub.adapters.tencent import TencentAdapter
+from datahub.adapters.ths import ADAPTER as ths
+from datahub.adapters.xgb import ADAPTER as xgb
+
+RESERVED = {
+    "eastmoney": EastmoneyAdapter(),
+    "tencent": TencentAdapter(),
+    "ths": ths,
+    "xgb": xgb,
+    "akshare": akshare,
+    "ifind": ifind,
+}

xiaobai-datahub/datahub/adapters/akshare.py

@@ -0,0 +1,3 @@
+from datahub.adapters.base import ReservedAdapter
+
+ADAPTER = ReservedAdapter("akshare")

xiaobai-datahub/datahub/adapters/base.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class AdapterError(RuntimeError):
+    pass
+
+
+class MarketAdapter(ABC):
+    """Uniform adapter: probe / fetch / normalize. Realtime adapters may be stubs in P0."""
+
+    name: str = "base"
+
+    @abstractmethod
+    def probe(self) -> dict[str, Any]:
+        """Liveness check. Must not leak credentials."""
+
+    @abstractmethod
+    def fetch(self, dataset: str, params: dict[str, Any]) -> list[dict[str, Any]]:
+        """Return provider-native rows (pre-canonical)."""
+
+    @abstractmethod
+    def normalize(self, dataset: str, rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Map provider-native rows onto hub canonical fields."""
+
+
+class ReservedAdapter(MarketAdapter):
+    """Placeholder for a later free/licensed source. Does not pull data in P0."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    def probe(self) -> dict[str, Any]:
+        return {
+            "provider": self.name,
+            "configured": False,
+            "state": "reserved",
+            "message": "适配器位已预留，本阶段不接入",
+        }
+
+    def fetch(self, dataset: str, params: dict[str, Any]) -> list[dict[str, Any]]:
+        raise AdapterError(f"{self.name} 适配器本阶段未接入")
+
+    def normalize(self, dataset: str, rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        return []

xiaobai-datahub/datahub/adapters/eastmoney.py

@@ -0,0 +1,382 @@
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime
+from typing import Any
+
+from datahub.adapters.base import AdapterError, MarketAdapter
+from datahub.numbers import finite_number, round4
+
+EASTMONEY_INDEX_URL = "https://push2.eastmoney.com/api/qt/ulist.np/get"
+EASTMONEY_CLIST_URL = "https://push2.eastmoney.com/api/qt/clist/get"
+EASTMONEY_A_SHARE_BOARDS = (
+    "m:0+t:6",
+    "m:0+t:80",
+    "m:1+t:2",
+    "m:1+t:23",
+    "m:0+t:81",
+)
+EASTMONEY_QUOTE_FIELDS = "f12,f13,f14,f2,f3,f4,f5,f6,f15,f16,f17,f18,f8,f124"
+EASTMONEY_MARKET_PAGE_SIZE = 100
+TRENDS_URL = "https://push2delay.eastmoney.com/api/qt/stock/trends2/get"
+HIS_TRENDS_URL = "https://push2his.eastmoney.com/api/qt/stock/trends2/get"
+BROWSER_UA = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36"
+)
+INDEX_SECIDS = {
+    "000001.SH": "1.000001",
+    "399001.SZ": "0.399001",
+    "399006.SZ": "0.399006",
+}
+
+
+class EastmoneyAdapter(MarketAdapter):
+    name = "eastmoney"
+
+    def __init__(self, timeout: int = 8) -> None:
+        self.timeout = timeout
+
+    def probe(self) -> dict[str, Any]:
+        started = time.perf_counter()
+        try:
+            rows = self.fetch_indices()
+            state = "ok" if len(rows) == 3 else "empty"
+        except AdapterError as exc:
+            return {
+                "provider": self.name,
+                "configured": True,
+                "state": "error",
+                "message": str(exc),
+                "latency_ms": round((time.perf_counter() - started) * 1000),
+            }
+        return {
+            "provider": self.name,
+            "configured": True,
+            "state": state,
+            "latency_ms": round((time.perf_counter() - started) * 1000),
+        }
+
+    def fetch(self, dataset: str, params: dict[str, Any]) -> list[dict[str, Any]]:
+        if dataset in {"indexes_quotes", "index_quotes"}:
+            return self.fetch_indices()
+        if dataset in {"quotes", "quotes_latest"}:
+            codes = params.get("codes") or []
+            if isinstance(codes, str):
+                codes = [item.strip() for item in codes.split(",") if item.strip()]
+            if codes:
+                return self.fetch_quotes(list(codes))
+            return self.fetch_market_quotes()
+        if dataset in {"quotes_market", "market_quotes"}:
+            return self.fetch_market_quotes()
+        raise AdapterError(f"{self.name} unsupported dataset: {dataset}")
+
+    def normalize(self, dataset: str, rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        return list(rows)
+
+    def fetch_indices(self) -> list[dict[str, Any]]:
+        payload = self._get_json(
+            EASTMONEY_INDEX_URL,
+            {
+                "secids": "1.000001,0.399001,0.399006",
+                "fltt": "2",
+                "invt": "2",
+                "fields": "f12,f14,f2,f3,f4,f15,f16,f17,f18,f6,f124",
+            },
+            referer="https://quote.eastmoney.com/",
+        )
+        rows = list((payload.get("data") or {}).get("diff") or [])
+        result = []
+        for row in rows:
+            code = str(row.get("f12") or "")
+            if code not in {"000001", "399001", "399006"}:
+                continue
+            epoch = int(finite_number(row.get("f124")) or 0)
+            ts_code = f"{code}.SH" if code.startswith("0") and code == "000001" else f"{code}.SZ"
+            if code == "000001":
+                ts_code = "000001.SH"
+            result.append(
+                {
+                    "ts_code": ts_code,
+                    "code": code,
+                    "name": row.get("f14") or code,
+                    "price": round4(finite_number(row.get("f2"))),
+                    "pct_chg": round4(finite_number(row.get("f3"))),
+                    "change_amount": round4(finite_number(row.get("f4"))),
+                    "open": round4(finite_number(row.get("f17"))),
+                    "high": round4(finite_number(row.get("f15"))),
+                    "low": round4(finite_number(row.get("f16"))),
+                    "previous_close": round4(finite_number(row.get("f18"))),
+                    "amount": round4(finite_number(row.get("f6"))),
+                    "quote_time_epoch": epoch,
+                    "quote_time": (
+                        datetime.fromtimestamp(epoch).astimezone().isoformat(timespec="seconds")
+                        if epoch
+                        else ""
+                    ),
+                    "source": "eastmoney_push2",
+                }
+            )
+        if len(result) != 3:
+            raise AdapterError(f"Eastmoney returned {len(result)}/3 indices")
+        return result
+
+    def fetch_quotes(self, codes: list[str]) -> list[dict[str, Any]]:
+        # Eastmoney clist does not accept arbitrary code lists well; use ulist.np for batches.
+        secids = []
+        for code in codes:
+            ts = str(code or "").upper()
+            symbol = ts.split(".")[0]
+            if ts.endswith(".SH") or symbol.startswith(("5", "6", "9")):
+                secids.append(f"1.{symbol}")
+            else:
+                secids.append(f"0.{symbol}")
+        if not secids:
+            return []
+        payload = self._get_json(
+            EASTMONEY_INDEX_URL,
+            {
+                "secids": ",".join(secids[:60]),
+                "fltt": "2",
+                "invt": "2",
+                "fields": "f12,f14,f2,f3,f4,f15,f16,f17,f18,f5,f6,f8,f124",
+            },
+            referer="https://quote.eastmoney.com/",
+        )
+        rows = list((payload.get("data") or {}).get("diff") or [])
+        result = []
+        for row in rows:
+            symbol = str(row.get("f12") or "")
+            if not symbol:
+                continue
+            ts_code = f"{symbol}.SH" if symbol.startswith(("5", "6", "9")) else f"{symbol}.SZ"
+            epoch = int(finite_number(row.get("f124")) or 0)
+            result.append(
+                {
+                    "ts_code": ts_code,
+                    "name": row.get("f14") or symbol,
+                    "price": round4(finite_number(row.get("f2"))),
+                    "pct_chg": round4(finite_number(row.get("f3"))),
+                    "change_amount": round4(finite_number(row.get("f4"))),
+                    "open": round4(finite_number(row.get("f17"))),
+                    "high": round4(finite_number(row.get("f15"))),
+                    "low": round4(finite_number(row.get("f16"))),
+                    "previous_close": round4(finite_number(row.get("f18"))),
+                    "volume": round4(finite_number(row.get("f5"))),
+                    "amount": round4(finite_number(row.get("f6"))),
+                    "turnover_rate": round4(finite_number(row.get("f8"))),
+                    "quote_time_epoch": epoch,
+                    "quote_time": (
+                        datetime.fromtimestamp(epoch).astimezone().isoformat(timespec="seconds")
+                        if epoch
+                        else ""
+                    ),
+                    "source": "eastmoney_push2",
+                }
+            )
+        return result
+
+    def fetch_market_quotes(self) -> list[dict[str, Any]]:
+        rows: list[dict[str, Any]] = []
+        board_errors: list[str] = []
+        for board in EASTMONEY_A_SHARE_BOARDS:
+            try:
+                rows.extend(self._board_quotes(board))
+            except Exception as exc:
+                board_errors.append(f"{board}:{exc}")
+        quotes: list[dict[str, Any]] = []
+        seen: set[str] = set()
+        for row in rows:
+            quote = _normalize_market_quote(row)
+            ts_code = str((quote or {}).get("ts_code") or "")
+            if not quote or ts_code in seen:
+                continue
+            seen.add(ts_code)
+            quotes.append(quote)
+        if len(quotes) < 200:
+            detail = f"；{'; '.join(board_errors)}" if board_errors else ""
+            raise AdapterError(f"Eastmoney market snapshot too small: {len(quotes)}{detail}")
+        return quotes
+
+    def _board_quotes(self, board: str) -> list[dict[str, Any]]:
+        first = self._market_page(board, 1)
+        data = first.get("data") or {}
+        rows = list(data.get("diff") or [])
+        total = int(finite_number(data.get("total")) or 0)
+        page_count = 1
+        if total > 0:
+            page_count = max(1, (total + EASTMONEY_MARKET_PAGE_SIZE - 1) // EASTMONEY_MARKET_PAGE_SIZE)
+        for page in range(2, min(page_count, 40) + 1):
+            payload = self._market_page(board, page)
+            rows.extend(list((payload.get("data") or {}).get("diff") or []))
+        return rows
+
+    def _market_page(self, board: str, page: int) -> dict[str, Any]:
+        return self._get_json(
+            EASTMONEY_CLIST_URL,
+            {
+                "pn": str(page),
+                "pz": str(EASTMONEY_MARKET_PAGE_SIZE),
+                "po": "1",
+                "np": "1",
+                "fltt": "2",
+                "invt": "2",
+                "fid": "f12",
+                "fs": board,
+                "fields": EASTMONEY_QUOTE_FIELDS,
+            },
+            referer="https://quote.eastmoney.com/center/gridlist.html",
+        )
+
+    def fetch_intraday(self, ts_code: str, date: str = "") -> dict[str, Any]:
+        code = str(ts_code or "").upper()
+        if code in INDEX_SECIDS:
+            secid = INDEX_SECIDS[code]
+            entity = "index"
+            identifier = code
+        else:
+            symbol = code.split(".")[0]
+            market = "1" if symbol.startswith(("5", "6", "9")) else "0"
+            secid = f"{market}.{symbol}"
+            entity = "stock"
+            identifier = symbol
+        params = {
+            "secid": secid,
+            "fields1": "f1,f2,f3,f4,f5,f6,f7,f8,f9,f10,f11,f12,f13",
+            "fields2": "f51,f52,f53,f54,f55,f56,f57,f58",
+            "iscr": "0",
+        }
+        data: dict[str, Any] = {}
+        points: list[dict[str, Any]] = []
+        last_error: Exception | None = None
+        for url, ndays in ((TRENDS_URL, "1"), (TRENDS_URL, "5"), (HIS_TRENDS_URL, "5")):
+            try:
+                payload = self._get_json(
+                    url,
+                    {**params, "ndays": ndays},
+                    referer="https://quote.eastmoney.com/",
+                )
+            except AdapterError as exc:
+                last_error = exc
+                continue
+            data = payload.get("data") or {}
+            parsed = [point for raw in data.get("trends") or [] if (point := _parse_trend(raw))]
+            points = _preferred_session(parsed, date)
+            if points:
+                break
+        if not points:
+            raise AdapterError("No intraday chart data returned") from last_error
+        return {
+            "entity_type": entity,
+            "identifier": identifier,
+            "ts_code": code if "." in code else f"{identifier}.{'SH' if identifier.startswith(('5','6','9')) else 'SZ'}",
+            "name": str(data.get("name") or ""),
+            "code": str(data.get("code") or identifier),
+            "trade_date": points[-1]["date"],
+            "previous_close": round4(finite_number(data.get("preClose"))),
+            "points": points,
+            "source": "eastmoney_trends2",
+        }
+
+    def _get_json(self, url: str, params: dict[str, str], referer: str) -> dict[str, Any]:
+        request_url = f"{url}?{urllib.parse.urlencode(params)}"
+        request = urllib.request.Request(
+            request_url,
+            headers={
+                "Accept": "application/json,text/plain,*/*",
+                "User-Agent": BROWSER_UA,
+                "Referer": referer,
+            },
+            method="GET",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except Exception as exc:
+            raise AdapterError(f"eastmoney request failed: {exc}") from exc
+
+
+def _preferred_session(points: list[dict[str, Any]], preferred_date: str = "") -> list[dict[str, Any]]:
+    if not points:
+        return []
+    want = ""
+    digits = str(preferred_date or "").replace("-", "")[:8]
+    if len(digits) == 8 and digits.isdigit():
+        want = f"{digits[:4]}-{digits[4:6]}-{digits[6:8]}"
+    if want:
+        matched = [point for point in points if str(point.get("date") or "") == want]
+        if matched:
+            return matched
+    latest = max(str(point.get("date") or "") for point in points)
+    if not latest:
+        return points
+    return [point for point in points if str(point.get("date") or "") == latest]
+
+
+def _normalize_market_quote(row: dict[str, Any]) -> dict[str, Any] | None:
+    symbol = str(row.get("f12") or "").strip()
+    if not symbol.isdigit() or len(symbol) != 6:
+        return None
+    close = round4(finite_number(row.get("f2")))
+    previous_close = round4(finite_number(row.get("f18")))
+    if close <= 0 or previous_close <= 0:
+        return None
+    market = int(finite_number(row.get("f13")) or 0)
+    if market == 1 or symbol.startswith(("5", "6", "9")):
+        ts_code = f"{symbol}.SH"
+    elif symbol.startswith(("4", "8")):
+        ts_code = f"{symbol}.BJ"
+    else:
+        ts_code = f"{symbol}.SZ"
+    epoch = int(finite_number(row.get("f124")) or 0)
+    quote_date = ""
+    if epoch > 0:
+        quote_date = datetime.fromtimestamp(epoch).astimezone().strftime("%Y%m%d")
+    return {
+        "ts_code": ts_code,
+        "name": row.get("f14") or symbol,
+        "pre_close": previous_close,
+        "previous_close": previous_close,
+        "open": round4(finite_number(row.get("f17"))),
+        "high": round4(finite_number(row.get("f15"))),
+        "low": round4(finite_number(row.get("f16"))),
+        "close": close,
+        "price": close,
+        "pct_chg": round4(finite_number(row.get("f3"))),
+        "vol": round4(finite_number(row.get("f5")) * 100),
+        "volume": round4(finite_number(row.get("f5")) * 100),
+        "amount": round4(finite_number(row.get("f6"))),
+        "quote_date": quote_date,
+        "quote_time_epoch": epoch,
+        "source": "eastmoney_clist",
+    }
+
+
+def _parse_trend(raw: Any) -> dict[str, Any] | None:
+    text = str(raw or "")
+    parts = text.split(",")
+    if len(parts) < 8:
+        return None
+    stamp = parts[0]
+    try:
+        when = datetime.strptime(stamp, "%Y-%m-%d %H:%M")
+    except ValueError:
+        return None
+    close = round4(finite_number(parts[2]))
+    if close <= 0:
+        return None
+    return {
+        "time": when.strftime("%H:%M"),
+        "date": when.strftime("%Y-%m-%d"),
+        "open": round4(finite_number(parts[1])),
+        "close": close,
+        "high": round4(finite_number(parts[3])),
+        "low": round4(finite_number(parts[4])),
+        "avg_price": round4(finite_number(parts[7] if len(parts) > 7 else parts[2])),
+        "volume": round4(finite_number(parts[5])),
+        "amount": round4(finite_number(parts[6])),
+    }

xiaobai-datahub/datahub/adapters/ifind.py

@@ -0,0 +1,3 @@
+from datahub.adapters.base import ReservedAdapter
+
+ADAPTER = ReservedAdapter("ifind")

xiaobai-datahub/datahub/adapters/tencent.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import time
+import urllib.error
+import urllib.request
+from datetime import datetime
+from typing import Any
+
+from datahub.adapters.base import AdapterError, MarketAdapter
+from datahub.numbers import finite_number, round4
+
+TENCENT_INDEX_URL = "https://qt.gtimg.cn/q=sh000001,sz399001,sz399006"
+BROWSER_UA = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36"
+)
+
+
+class TencentAdapter(MarketAdapter):
+    name = "tencent"
+
+    def __init__(self, timeout: int = 8) -> None:
+        self.timeout = timeout
+
+    def probe(self) -> dict[str, Any]:
+        started = time.perf_counter()
+        try:
+            rows = self.fetch_indices()
+            state = "ok" if len(rows) == 3 else "empty"
+        except AdapterError as exc:
+            return {
+                "provider": self.name,
+                "configured": True,
+                "state": "error",
+                "message": str(exc),
+                "latency_ms": round((time.perf_counter() - started) * 1000),
+            }
+        return {
+            "provider": self.name,
+            "configured": True,
+            "state": state,
+            "latency_ms": round((time.perf_counter() - started) * 1000),
+        }
+
+    def fetch(self, dataset: str, params: dict[str, Any]) -> list[dict[str, Any]]:
+        if dataset in {"indexes_quotes", "index_quotes"}:
+            return self.fetch_indices()
+        raise AdapterError(f"{self.name} unsupported dataset: {dataset}")
+
+    def normalize(self, dataset: str, rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        return list(rows)
+
+    def fetch_indices(self) -> list[dict[str, Any]]:
+        request = urllib.request.Request(
+            TENCENT_INDEX_URL,
+            headers={"User-Agent": BROWSER_UA, "Referer": "https://gu.qq.com/"},
+            method="GET",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                raw = response.read().decode("gb18030", errors="ignore")
+        except Exception as exc:
+            raise AdapterError(f"tencent request failed: {exc}") from exc
+        result = []
+        for line in raw.splitlines():
+            if '="' not in line:
+                continue
+            fields = line.split('="', 1)[1].rsplit('";', 1)[0].split("~")
+            if len(fields) < 38:
+                continue
+            code = fields[2]
+            if code not in {"000001", "399001", "399006"}:
+                continue
+            try:
+                quote_time = datetime.strptime(fields[30], "%Y%m%d%H%M%S").astimezone()
+            except ValueError as exc:
+                raise AdapterError(f"Tencent invalid quote time for {code}") from exc
+            ts_code = "000001.SH" if code == "000001" else f"{code}.SZ"
+            result.append(
+                {
+                    "ts_code": ts_code,
+                    "code": code,
+                    "name": fields[1] or code,
+                    "price": round4(finite_number(fields[3])),
+                    "pct_chg": round4(finite_number(fields[32])),
+                    "change_amount": round4(finite_number(fields[31])),
+                    "open": round4(finite_number(fields[5])),
+                    "high": round4(finite_number(fields[33])),
+                    "low": round4(finite_number(fields[34])),
+                    "previous_close": round4(finite_number(fields[4])),
+                    "amount": round4(finite_number(fields[37]) * 10000),
+                    "quote_time_epoch": int(quote_time.timestamp()),
+                    "quote_time": quote_time.isoformat(timespec="seconds"),
+                    "source": "tencent_qt",
+                }
+            )
+        if len(result) != 3:
+            raise AdapterError(f"Tencent returned {len(result)}/3 indices")
+        return result

xiaobai-datahub/datahub/adapters/ths.py

@@ -0,0 +1,3 @@
+from datahub.adapters.base import ReservedAdapter
+
+ADAPTER = ReservedAdapter("ths")

xiaobai-datahub/datahub/adapters/tushare.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Callable
+
+from datahub.adapters.base import AdapterError, MarketAdapter
+from datahub.normalize import (
+    normalize_auction,
+    normalize_calendar,
+    normalize_daily,
+    normalize_dragon_tiger,
+    normalize_index_daily,
+    normalize_limit_event,
+    normalize_moneyflow,
+    normalize_popularity,
+    normalize_sector_daily,
+    normalize_stock,
+    normalize_valuation,
+)
+
+TUSHARE_URL = "http://api.tushare.pro"
+
+TUSHARE_FIELDS = {
+    "trade_cal": "exchange,cal_date,is_open,pretrade_date",
+    "stock_basic": "ts_code,symbol,name,area,industry,market,list_status,list_date",
+    "daily": "ts_code,trade_date,open,high,low,close,pct_chg,vol,amount",
+    "daily_basic": "ts_code,trade_date,turnover_rate,volume_ratio,total_mv,circ_mv,pe_ttm,pb,ps_ttm,dv_ttm",
+    "adj_factor": "ts_code,trade_date,adj_factor",
+    "index_daily": "ts_code,trade_date,open,high,low,close,pct_chg,vol,amount",
+    "moneyflow": (
+        "ts_code,trade_date,buy_sm_amount,sell_sm_amount,buy_md_amount,sell_md_amount,"
+        "buy_lg_amount,sell_lg_amount,buy_elg_amount,sell_elg_amount,net_mf_amount"
+    ),
+    "stk_auction": "ts_code,trade_date,vol,price,amount,pre_close,turnover_rate,volume_ratio,float_share",
+    "limit_list_d": (
+        "trade_date,ts_code,industry,name,close,pct_chg,amount,limit_amount,"
+        "float_mv,total_mv,turnover_ratio,fd_amount,first_time,last_time,"
+        "open_times,up_stat,limit_times,limit_type"
+    ),
+    "ths_hot": "ts_code,ts_name,hot,rank,pct_change,current_price,concept,data_type,trade_date",
+    "dc_hot": "ts_code,ts_name,rank,pct_change,current_price,hot,concept,data_type,trade_date",
+    "hm_detail": "trade_date,ts_code,ts_name,buy_amount,sell_amount,net_amount,hm_name,hm_orgs,tag",
+    "hm_list": "name,desc,orgs",
+    "top_list": "trade_date,ts_code,name,pct_change,reason",
+    "top_inst": "trade_date,ts_code,exalter,buy,buy_rate,sell,sell_rate,net_buy,side,reason",
+    "ths_index": "ts_code,name,count,exchange,list_date,type",
+    "ths_daily": "ts_code,trade_date,open,high,low,close,pre_close,pct_change,vol,turnover_rate",
+    "dc_index": "ts_code,trade_date,name,open,high,low,close,pre_close,pct_change,vol,amount,turnover_rate",
+    "sw_daily": "ts_code,trade_date,name,open,high,low,close,pct_change,vol,amount",
+}
+
+DATASET_API = {
+    "calendar": "trade_cal",
+    "stocks": "stock_basic",
+    "daily": "daily",
+    "valuation": "daily_basic",
+    "adj_factor": "adj_factor",
+    "index_daily": "index_daily",
+    "moneyflow": "moneyflow",
+    "auction": "stk_auction",
+    "limit_events": "limit_list_d",
+    "popularity": "ths_hot",
+    "dragon_tiger": "hm_detail",
+    "sector_daily": "ths_daily",
+}
+
+WEBSITE_INDEX_CODES = ("000001.SH", "399001.SZ", "399006.SZ", "000300.SH")
+DEFAULT_INDEX_CODES = WEBSITE_INDEX_CODES
+LIMIT_TYPES = ("U", "D", "Z")
+
+
+class TushareAdapter(MarketAdapter):
+    name = "tushare"
+
+    def __init__(
+        self,
+        token: str,
+        timeout: int = 30,
+        transport: Callable[[str, dict[str, Any], str], list[dict[str, Any]]] | None = None,
+    ) -> None:
+        self.token = token
+        self.timeout = timeout
+        self._transport = transport
+
+    def probe(self) -> dict[str, Any]:
+        if not self.token:
+            return {"provider": self.name, "configured": False, "state": "unconfigured"}
+        started = time.perf_counter()
+        try:
+            rows = self.fetch("calendar", {"exchange": "SSE", "start_date": "20200102", "end_date": "20200102"})
+        except AdapterError as exc:
+            return {
+                "provider": self.name,
+                "configured": True,
+                "state": "error",
+                "message": str(exc),
+                "latency_ms": round((time.perf_counter() - started) * 1000),
+            }
+        return {
+            "provider": self.name,
+            "configured": True,
+            "state": "ok" if rows else "empty",
+            "latency_ms": round((time.perf_counter() - started) * 1000),
+        }
+
+    def fetch(self, dataset: str, params: dict[str, Any]) -> list[dict[str, Any]]:
+        if dataset == "limit_events":
+            return self.fetch_limit_events(str(params.get("trade_date") or ""))
+        if dataset == "popularity":
+            return self.fetch_popularity(str(params.get("trade_date") or ""))
+        if dataset == "dragon_tiger":
+            return self.fetch_dragon_tiger(str(params.get("trade_date") or ""))
+        if dataset == "sector_daily":
+            return self.fetch_sector_daily(str(params.get("trade_date") or ""))
+        api_name = DATASET_API.get(dataset, dataset)
+        fields = TUSHARE_FIELDS.get(api_name, "")
+        query_params = dict(params)
+        if api_name == "stock_basic" and "list_status" not in query_params:
+            query_params["list_status"] = "L"
+        if api_name == "trade_cal" and "exchange" not in query_params:
+            query_params["exchange"] = "SSE"
+        if api_name == "index_daily" and "ts_code" not in query_params:
+            query_params.setdefault("ts_code", DEFAULT_INDEX_CODES[0])
+        return self._query(api_name, query_params, fields)
+
+    def fetch_limit_events(self, trade_date: str) -> list[dict[str, Any]]:
+        rows: list[dict[str, Any]] = []
+        for limit_type in LIMIT_TYPES:
+            part = self._query(
+                "limit_list_d",
+                {"trade_date": trade_date, "limit_type": limit_type},
+                TUSHARE_FIELDS["limit_list_d"],
+            )
+            for row in part:
+                row = dict(row)
+                row.setdefault("limit_type", limit_type)
+                rows.append(row)
+        return rows
+
+    def fetch_popularity(self, trade_date: str) -> list[dict[str, Any]]:
+        rows: list[dict[str, Any]] = []
+        for api_name, source in (("ths_hot", "ths"), ("dc_hot", "dc")):
+            for row in self._query(api_name, {"trade_date": trade_date}, TUSHARE_FIELDS[api_name]):
+                item = dict(row)
+                item["source"] = source
+                item.setdefault("trade_date", trade_date)
+                rows.append(item)
+        return rows
+
+    def fetch_dragon_tiger(self, trade_date: str) -> list[dict[str, Any]]:
+        details = self._query("hm_detail", {"trade_date": trade_date}, TUSHARE_FIELDS["hm_detail"])
+        top_rows = self._query("top_list", {"trade_date": trade_date}, TUSHARE_FIELDS["top_list"])
+        context = {
+            str(row.get("ts_code") or ""): row
+            for row in top_rows
+            if str(row.get("ts_code") or "")
+        }
+        rows: list[dict[str, Any]] = []
+        for row in details:
+            item = dict(row)
+            stock = context.get(str(item.get("ts_code") or ""), {})
+            if item.get("pct_change") is None and stock.get("pct_change") is not None:
+                item["pct_change"] = stock.get("pct_change")
+            if not item.get("reason") and stock.get("reason"):
+                item["reason"] = stock.get("reason")
+            if not item.get("ts_name") and stock.get("name"):
+                item["ts_name"] = stock.get("name")
+            rows.append(item)
+        return rows
+
+    def fetch_sector_daily(self, trade_date: str) -> list[dict[str, Any]]:
+        rows: list[dict[str, Any]] = []
+        for api_name, family in (("ths_daily", "ths"), ("dc_index", "dc"), ("sw_daily", "sw")):
+            try:
+                part = self._query(api_name, {"trade_date": trade_date}, TUSHARE_FIELDS[api_name])
+            except AdapterError:
+                part = []
+            for row in part:
+                item = dict(row)
+                item["family"] = family
+                rows.append(item)
+        return rows
+
+    def fetch_index_daily(self, trade_date: str, codes: tuple[str, ...] = DEFAULT_INDEX_CODES) -> list[dict[str, Any]]:
+        rows: list[dict[str, Any]] = []
+        for ts_code in codes:
+            rows.extend(self.fetch("index_daily", {"ts_code": ts_code, "trade_date": trade_date}))
+        return rows
+
+    def normalize(self, dataset: str, rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        if dataset in {"limit_events", "limit_list_d"}:
+            return [normalize_limit_event(row) for row in rows]
+        if dataset == "popularity":
+            return [normalize_popularity(row, source=str(row.get("source") or "")) for row in rows]
+        if dataset == "dragon_tiger":
+            return [normalize_dragon_tiger(row) for row in rows]
+        if dataset == "sector_daily":
+            return [
+                normalize_sector_daily(row, family=str(row.get("family") or "ths"))
+                for row in rows
+            ]
+        mapping = {
+            "calendar": normalize_calendar,
+            "trade_cal": normalize_calendar,
+            "stocks": normalize_stock,
+            "stock_basic": normalize_stock,
+            "daily": normalize_daily,
+            "valuation": normalize_valuation,
+            "daily_basic": normalize_valuation,
+            "moneyflow": normalize_moneyflow,
+            "auction": normalize_auction,
+            "stk_auction": normalize_auction,
+            "index_daily": normalize_index_daily,
+        }
+        fn = mapping.get(dataset)
+        if fn is None:
+            if dataset == "adj_factor":
+                return [
+                    {
+                        "ts_code": str(row.get("ts_code") or "").upper(),
+                        "trade_date": str(row.get("trade_date") or ""),
+                        "adj_factor": row.get("adj_factor"),
+                    }
+                    for row in rows
+                ]
+            raise AdapterError(f"unsupported dataset: {dataset}")
+        return [fn(row) for row in rows]
+
+    def _query(self, api_name: str, params: dict[str, Any], fields: str) -> list[dict[str, Any]]:
+        if self._transport is not None:
+            return self._transport(api_name, params, fields)
+        if not self.token:
+            raise AdapterError("Tushare token 未配置")
+        payload = json.dumps(
+            {"api_name": api_name, "token": self.token, "params": params, "fields": fields}
+        ).encode("utf-8")
+        request = urllib.request.Request(
+            TUSHARE_URL,
+            data=payload,
+            headers={"Content-Type": "application/json", "User-Agent": "XiaobaiDatahub/0.1"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                result = json.loads(response.read().decode("utf-8"))
+        except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
+            raise AdapterError(f"Tushare 请求失败: {exc}") from exc
+        if result.get("code") not in (0, "0", None):
+            raise AdapterError(str(result.get("msg") or f"Tushare error {result.get('code')}"))
+        data = result.get("data") or {}
+        items = data.get("items") or []
+        fields_list = data.get("fields") or (fields.split(",") if fields else [])
+        return [dict(zip(fields_list, item)) for item in items]

xiaobai-datahub/datahub/adapters/xgb.py

@@ -0,0 +1,3 @@
+from datahub.adapters.base import ReservedAdapter
+
+ADAPTER = ReservedAdapter("xgb")

xiaobai-datahub/datahub/admin_api.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from datahub.adapters import RESERVED
+from datahub.auth import AuthService
+from datahub.db import HubDB
+from datahub.pipeline import OFFICIAL_DATASETS, STOCKS_DATASET, Pipeline
+from datahub.scheduler import Scheduler
+from datahub.serving import ApiError
+from datahub.timeutil import isoformat, now_shanghai, session_phase, yyyymmdd
+
+
+class AdminAPI:
+    def __init__(self, db: HubDB, pipeline: Pipeline, scheduler: Scheduler, auth: AuthService) -> None:
+        self.db = db
+        self.pipeline = pipeline
+        self.scheduler = scheduler
+        self.auth = auth
+
+    def overview(self) -> dict[str, Any]:
+        today = yyyymmdd(now_shanghai())
+        cal = self.db.fetchone(
+            "SELECT is_open FROM trade_calendar WHERE exchange = 'SSE' AND cal_date = ?",
+            (today,),
+        )
+        is_open = bool(cal and int(cal["is_open"]) == 1)
+        pubs = self.db.fetchall("SELECT * FROM publications WHERE trade_date = ?", (today,))
+        failed = self.db.fetchall(
+            "SELECT * FROM batches WHERE trade_date = ? AND state IN ('failed','staged')",
+            (today,),
+        )
+        calls = self.db.fetchall(
+            "SELECT * FROM src_calls ORDER BY id DESC LIMIT 20",
+        )
+        return {
+            "trade_date": today,
+            "session_phase": session_phase(now_shanghai(), is_open),
+            "is_open_day": is_open,
+            "eod_status": self.scheduler.eod_status(today),
+            "revision_status": self.scheduler.revision_status(today),
+            "publications": pubs,
+            "anomalies": failed,
+            "recent_calls": _public_calls(calls),
+            "source_count": len(self.db.fetchall("SELECT provider FROM src_health")),
+        }
+
+    def sources(self) -> dict[str, Any]:
+        health = {f"{row['provider']}:{row['endpoint_class']}": row for row in self.db.fetchall("SELECT * FROM src_health")}
+        items = [
+            {
+                "provider": "tushare",
+                "role": "official",
+                "health": health.get("tushare:pro") or {"state": "unknown"},
+                "credential": self.auth.credential_status("tushare_token") or {"configured": bool(self.pipeline.adapter.token)},
+            }
+        ]
+        for name, adapter in RESERVED.items():
+            items.append(
+                {
+                    "provider": name,
+                    "role": "reserved",
+                    "health": adapter.probe(),
+                    "credential": {"configured": False, "last4": "", "updated_at": ""},
+                }
+            )
+        # Prefer encrypted last4 if stored
+        cred = self.auth.credential_status("tushare_token")
+        if cred.get("configured"):
+            items[0]["credential"] = cred
+        elif self.pipeline.adapter.token:
+            from datahub.crypto import mask_secret
+
+            items[0]["credential"] = {"configured": True, "last4": mask_secret(self.pipeline.adapter.token), "updated_at": ""}
+        return {"items": items}
+
+    def probe(self, provider: str) -> dict[str, Any]:
+        if provider == "tushare":
+            return self.pipeline.adapter.probe()
+        adapter = RESERVED.get(provider)
+        if adapter is None:
+            raise ApiError("INVALID_ARGUMENT", f"unknown provider: {provider}")
+        return adapter.probe()
+
+    def jobs(self) -> dict[str, Any]:
+        runs = self.db.fetchall("SELECT * FROM job_runs ORDER BY id DESC LIMIT 100")
+        stocks_times = "/".join(self.pipeline.settings.stocks_refresh_times) or "20:00"
+        return {
+            "jobs": [
+                {"id": "precheck", "at": "08:45", "title": "盘前预检"},
+                {"id": "eod_a", "at": "15:05", "title": "盘后批 A daily/valuation/moneyflow/auction"},
+                {"id": "eod_b", "at": "15:10", "title": "盘后批 B index_daily"},
+                {"id": "eod_retry", "at": "15:15-23:30", "title": "盘后未出数自动重试（每 30 分钟，成功即停）"},
+                {"id": "eod_revise", "at": "20:00-23:20", "title": "估值发布后复核（轻量比对，有修订才整组原子追补）"},
+                {"id": "stocks_refresh", "at": stocks_times, "title": "股票主档刷新与正式发布（新上市/更名，无变化跳过）"},
+                {"id": "history_backfill", "at": "manual", "title": "回补历史日历与指数日 K"},
+                {"id": "cleanup", "at": "00:30", "title": "清理 staging / 日志"},
+                {"id": "backup", "at": "00:40", "title": "SQLite 备份"},
+            ],
+            "runs": runs,
+        }
+
+    def run_job(self, job_id: str, trade_date: str) -> dict[str, Any]:
+        return self.scheduler.run_job(job_id, yyyymmdd(trade_date or now_shanghai()))
+
+    def batches(self, date: str, dataset: str = "") -> dict[str, Any]:
+        trade_date = yyyymmdd(date or now_shanghai())
+        if dataset:
+            rows = self.db.fetchall(
+                "SELECT * FROM batches WHERE trade_date = ? AND dataset = ? ORDER BY started_at",
+                (trade_date, dataset),
+            )
+        else:
+            rows = self.db.fetchall(
+                "SELECT * FROM batches WHERE trade_date = ? ORDER BY started_at",
+                (trade_date,),
+            )
+        pubs = self.db.fetchall("SELECT * FROM publications WHERE trade_date = ?", (trade_date,))
+        return {"trade_date": trade_date, "batches": rows, "publications": pubs}
+
+    def datasets(self, date: str) -> dict[str, Any]:
+        trade_date = yyyymmdd(date or now_shanghai())
+        pubs = self.db.fetchall("SELECT * FROM publications WHERE trade_date = ?", (trade_date,))
+        diffs = self.db.fetchall(
+            "SELECT * FROM diff_reports WHERE trade_date = ? ORDER BY id",
+            (trade_date,),
+        )
+        return {"trade_date": trade_date, "publications": pubs, "diff_reports": diffs}
+
+    def audit(self) -> dict[str, Any]:
+        return {"items": self.db.fetchall("SELECT * FROM audit_log ORDER BY id DESC LIMIT 200")}
+
+    def rollback(self, dataset: str, trade_date: str, password: str, confirm: str, actor: str) -> dict[str, Any]:
+        self._dangerous(password, confirm, f"{dataset}:{trade_date}")
+        result = self.pipeline.rollback(dataset, trade_date, actor=actor)
+        return result
+
+    def backfill(self, dataset: str, trade_date: str, password: str, confirm: str, actor: str) -> dict[str, Any]:
+        day = yyyymmdd(trade_date or now_shanghai())
+        if dataset == "history":
+            self._dangerous(password, confirm, "history:full")
+            result = self.pipeline.backfill_history(day)
+        else:
+            self._dangerous(password, confirm, f"{dataset}:{day}")
+            if dataset == "reference":
+                result = self.pipeline.ingest_reference(day)
+            elif dataset in OFFICIAL_DATASETS or dataset == STOCKS_DATASET:
+                # Manual same-day republish must rebuild the full A/B boundary.
+                # Gate failures and mid-switch exceptions both surface as
+                # FAILED_PRECONDITION so the admin API never leaks raw
+                # transaction errors to the client.
+                try:
+                    result = self.pipeline.force_republish_boundary(dataset, day)
+                    failures = self.pipeline.eod_failures(result)
+                    if failures:
+                        raise ApiError("FAILED_PRECONDITION", "; ".join(failures))
+                except ApiError:
+                    raise
+                except Exception as exc:
+                    raise ApiError("FAILED_PRECONDITION", str(exc)) from exc
+            else:
+                raise ApiError("INVALID_ARGUMENT", f"unsupported backfill dataset: {dataset}")
+        self.pipeline.audit(actor, "backfill", f"{dataset}:{day}", json.dumps({"ok": True}))
+        return result
+
+    def _dangerous(self, password: str, confirm: str, expected: str) -> None:
+        if not self.auth.confirm_password(password):
+            raise ApiError("UNAUTHORIZED", "二次确认密码错误")
+        if confirm.strip() != expected:
+            raise ApiError("INVALID_ARGUMENT", f"确认词必须为 {expected}")
+
+
+def _public_calls(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    out = []
+    for row in rows:
+        out.append(
+            {
+                "id": row["id"],
+                "provider": row["provider"],
+                "endpoint": row["endpoint"],
+                "ok": bool(row["ok"]),
+                "latency_ms": row["latency_ms"],
+                "error": row["error"],
+                "created_at": row["created_at"],
+            }
+        )
+    return out

xiaobai-datahub/datahub/auth.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import os
+import secrets
+from datetime import timedelta
+from typing import Any
+
+from datahub.crypto import SecretVault, mask_secret
+from datahub.db import HubDB
+from datahub.timeutil import isoformat, now_shanghai
+
+PBKDF2_ROUNDS = 200_000
+SESSION_HOURS = 12
+LOGIN_FAIL_LIMIT = 5
+LOCK_MINUTES = 10
+
+
+def hash_password(password: str, salt: bytes | None = None) -> tuple[str, str]:
+    raw_salt = salt or os.urandom(16)
+    digest = hashlib.pbkdf2_hmac("sha256", password.encode("utf-8"), raw_salt, PBKDF2_ROUNDS, dklen=32)
+    return (
+        base64.urlsafe_b64encode(raw_salt).decode("ascii"),
+        base64.urlsafe_b64encode(digest).decode("ascii"),
+    )
+
+
+def verify_password(password: str, salt_text: str, expected_hash: str) -> bool:
+    try:
+        salt = base64.urlsafe_b64decode(salt_text.encode("ascii"))
+        _, actual = hash_password(password, salt)
+    except (ValueError, TypeError):
+        return False
+    return hmac.compare_digest(actual, expected_hash)
+
+
+def token_hash(token: str) -> str:
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+class AuthService:
+    def __init__(self, db: HubDB, vault: SecretVault, api_token: str, admin_password: str) -> None:
+        self.db = db
+        self.vault = vault
+        self._bootstrap(api_token, admin_password)
+
+    def _bootstrap(self, api_token: str, admin_password: str) -> None:
+        if api_token:
+            existing = self.db.fetchone("SELECT token_hash FROM api_tokens WHERE name = ?", ("review",))
+            hashed = token_hash(api_token)
+            last4 = mask_secret(api_token)
+            if existing is None:
+                self.db.execute(
+                    "INSERT INTO api_tokens(token_hash, name, last4, created_at) VALUES (?,?,?,?)",
+                    (hashed, "review", last4, isoformat()),
+                )
+            elif existing["token_hash"] != hashed:
+                self.db.execute(
+                    "UPDATE api_tokens SET token_hash = ?, last4 = ? WHERE name = ?",
+                    (hashed, last4, "review"),
+                )
+        admin = self.db.fetchone("SELECT id FROM hub_admin WHERE username = ?", ("hub_admin",))
+        if admin is None and admin_password:
+            salt, hashed = hash_password(admin_password)
+            now = isoformat()
+            self.db.execute(
+                """
+                INSERT INTO hub_admin(username, password_salt, password_hash, password_must_change, created_at, updated_at)
+                VALUES (?, ?, ?, 1, ?, ?)
+                """,
+                ("hub_admin", salt, hashed, now, now),
+            )
+
+    def check_api_token(self, supplied: str) -> bool:
+        if not supplied:
+            return False
+        row = self.db.fetchone(
+            "SELECT token_hash FROM api_tokens WHERE token_hash = ? AND revoked_at IS NULL",
+            (token_hash(supplied),),
+        )
+        return row is not None
+
+    def login(self, username: str, password: str) -> dict[str, Any]:
+        user = self.db.fetchone("SELECT * FROM hub_admin WHERE username = ?", (username,))
+        if not user:
+            raise PermissionError("账号或密码错误")
+        now = now_shanghai()
+        locked_until = user.get("locked_until")
+        if locked_until:
+            try:
+                from datetime import datetime
+
+                if datetime.fromisoformat(str(locked_until)) > now:
+                    raise PermissionError("账号已锁定，请稍后再试")
+            except ValueError:
+                pass
+        if not verify_password(password, str(user["password_salt"]), str(user["password_hash"])):
+            fails = int(user["failed_attempts"] or 0) + 1
+            lock = isoformat(now + timedelta(minutes=LOCK_MINUTES)) if fails >= LOGIN_FAIL_LIMIT else None
+            self.db.execute(
+                "UPDATE hub_admin SET failed_attempts = ?, locked_until = ? WHERE id = ?",
+                (fails, lock, user["id"]),
+            )
+            raise PermissionError("账号或密码错误")
+        self.db.execute(
+            "UPDATE hub_admin SET failed_attempts = 0, locked_until = NULL WHERE id = ?",
+            (user["id"],),
+        )
+        session = secrets.token_urlsafe(32)
+        csrf = secrets.token_urlsafe(24)
+        expires = isoformat(now + timedelta(hours=SESSION_HOURS))
+        self.db.execute(
+            "INSERT INTO hub_sessions(token_hash, csrf_token, expires_at, created_at) VALUES (?,?,?,?)",
+            (token_hash(session), csrf, expires, isoformat(now)),
+        )
+        return {
+            "session": session,
+            "csrf": csrf,
+            "must_change": bool(user["password_must_change"]),
+            "expires_at": expires,
+        }
+
+    def session_user(self, raw_token: str) -> dict[str, Any] | None:
+        if not raw_token:
+            return None
+        row = self.db.fetchone(
+            "SELECT * FROM hub_sessions WHERE token_hash = ?",
+            (token_hash(raw_token),),
+        )
+        if not row:
+            return None
+        if str(row["expires_at"]) < isoformat():
+            self.db.execute("DELETE FROM hub_sessions WHERE token_hash = ?", (row["token_hash"],))
+            return None
+        admin = self.db.fetchone("SELECT username, password_must_change FROM hub_admin WHERE username = ?", ("hub_admin",))
+        return {
+            "username": (admin or {}).get("username") or "hub_admin",
+            "csrf_token": row["csrf_token"],
+            "must_change": bool((admin or {}).get("password_must_change")),
+            "token_hash": row["token_hash"],
+        }
+
+    def logout(self, raw_token: str) -> None:
+        if raw_token:
+            self.db.execute("DELETE FROM hub_sessions WHERE token_hash = ?", (token_hash(raw_token),))
+
+    def change_password(self, current: str, new_password: str) -> None:
+        if len(new_password) < 8:
+            raise ValueError("新密码至少 8 位")
+        user = self.db.fetchone("SELECT * FROM hub_admin WHERE username = ?", ("hub_admin",))
+        if not user or not verify_password(current, str(user["password_salt"]), str(user["password_hash"])):
+            raise PermissionError("当前密码错误")
+        salt, hashed = hash_password(new_password)
+        self.db.execute(
+            "UPDATE hub_admin SET password_salt=?, password_hash=?, password_must_change=0, updated_at=? WHERE id=?",
+            (salt, hashed, isoformat(), user["id"]),
+        )
+
+    def confirm_password(self, password: str) -> bool:
+        user = self.db.fetchone("SELECT * FROM hub_admin WHERE username = ?", ("hub_admin",))
+        if not user:
+            return False
+        return verify_password(password, str(user["password_salt"]), str(user["password_hash"]))
+
+    def credential_status(self, name: str) -> dict[str, Any]:
+        row = self.db.fetchone("SELECT last4, updated_at FROM credentials WHERE name = ?", (name,))
+        if not row:
+            return {"configured": False, "last4": "", "updated_at": ""}
+        return {"configured": True, "last4": row["last4"], "updated_at": row["updated_at"]}
+
+    def store_credential(self, name: str, secret: str) -> None:
+        payload = self.vault.encrypt_json({name: secret})
+        self.db.execute(
+            """
+            INSERT INTO credentials(name, encrypted_payload, last4, updated_at)
+            VALUES (?, ?, ?, ?)
+            ON CONFLICT(name) DO UPDATE SET
+              encrypted_payload=excluded.encrypted_payload, last4=excluded.last4, updated_at=excluded.updated_at
+            """,
+            (name, payload, mask_secret(secret), isoformat()),
+        )
+
+    def load_credential(self, name: str) -> str:
+        row = self.db.fetchone("SELECT encrypted_payload FROM credentials WHERE name = ?", (name,))
+        if not row:
+            return ""
+        data = self.vault.decrypt_json(str(row["encrypted_payload"]))
+        return str(data.get(name) or "")

xiaobai-datahub/datahub/cli.py

@@ -0,0 +1,112 @@
+"""Command-line entry for one-shot datahub operations."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from datahub.hub import build_hub
+from datahub.pipeline import EOD_A_DATASETS, OFFICIAL_DATASETS, STOCKS_DATASET
+from datahub.settings import load_settings
+from datahub.timeutil import yyyymmdd
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="xiaobai-datahub CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+    history = sub.add_parser("history-backfill", help="回补 2016 年起交易日历和网站所用指数日 K")
+    history.add_argument("--calendar-start", default=None, help="日历起点，默认配置 calendar_start")
+    history.add_argument("--index-days", type=int, default=None, help="指数回补交易日数量，默认 260")
+    history.add_argument("--force", action="store_true", help="覆盖已发布的指数日期")
+    refresh = sub.add_parser("eod-refresh", help="对指定交易日补跑盘后正式数据（跳过已完整发布的一致性边界，仍走质量门禁）")
+    refresh.add_argument("--trade-date", default=None, help="交易日 YYYYMMDD，默认今天")
+    refresh.add_argument(
+        "--force", action="store_true",
+        help="强制重发 --dataset 所属的完整一致性边界（A 组或 B 组），生成新批次并保留上一批次可回滚",
+    )
+    refresh.add_argument(
+        "--dataset", default=None,
+        help="配合 --force：指定边界内任一成员（如 valuation→整组 A；index_daily→整组 B）",
+    )
+    stocks_refresh = sub.add_parser("stocks-refresh", help="刷新股票主档并发布正式快照（幂等：无变化则跳过）")
+    stocks_refresh.add_argument("--trade-date", default=None, help="交易日 YYYYMMDD，默认今天")
+    stocks_refresh.add_argument("--force", action="store_true", help="即使快照无变化也重新发布")
+    moneyflow_backfill = sub.add_parser(
+        "moneyflow-backfill", help="回补资金流历史（默认覆盖网站所需的最近 N 个交易日，跳过已发布日期）",
+    )
+    moneyflow_backfill.add_argument("--end-date", default=None, help="截止交易日 YYYYMMDD，默认今天")
+    moneyflow_backfill.add_argument("--trading-days", type=int, default=None, help="回补交易日数量，默认配置 moneyflow_history_trading_days")
+    moneyflow_backfill.add_argument("--force", action="store_true", help="覆盖已发布的资金流日期")
+    args = parser.parse_args(argv)
+
+    settings = load_settings()
+    hub = build_hub(settings)
+    if args.command == "history-backfill":
+        result = hub.pipeline.backfill_history(
+            calendar_start=args.calendar_start,
+            index_days=args.index_days,
+            force=args.force,
+        )
+        json.dump(result, sys.stdout, ensure_ascii=False, indent=2, default=str)
+        sys.stdout.write("\n")
+        return 0 if result.get("ok") else 1
+    if args.command == "eod-refresh":
+        day = yyyymmdd(args.trade_date) if args.trade_date else yyyymmdd()
+        if args.force:
+            allowed = set(OFFICIAL_DATASETS) | {STOCKS_DATASET}
+            if not args.dataset:
+                parser.error("--force requires --dataset (e.g. --dataset valuation)")
+            if args.dataset not in allowed:
+                parser.error(f"unknown dataset: {args.dataset}")
+            result = hub.pipeline.force_republish_boundary(args.dataset, day)
+            boundary = "A" if args.dataset in EOD_A_DATASETS or args.dataset == STOCKS_DATASET else "B"
+        else:
+            result = hub.pipeline.run_eod_missing(day)
+            boundary = None
+        hub.pipeline.audit("cli", "eod-refresh", f"eod:{day}", json.dumps(
+            {"force": bool(args.force), "dataset": args.dataset, "boundary": boundary,
+             **{name: item.get("state") for name, item in result.items() if isinstance(item, dict)}},
+            ensure_ascii=False,
+        ))
+        if args.force:
+            failures = hub.pipeline.eod_failures(result)
+            payload = {"trade_date": day, "boundary": boundary, "datasets": result}
+            json.dump(payload, sys.stdout, ensure_ascii=False, indent=2, default=str)
+            sys.stdout.write("\n")
+            return 0 if not failures else 1
+        missing = hub.pipeline.missing_official_datasets(day)
+        payload = {"trade_date": day, "datasets": result, "missing_after": missing}
+        json.dump(payload, sys.stdout, ensure_ascii=False, indent=2, default=str)
+        sys.stdout.write("\n")
+        return 0 if not missing else 1
+    if args.command == "stocks-refresh":
+        day = yyyymmdd(args.trade_date) if args.trade_date else yyyymmdd()
+        result = hub.pipeline.refresh_stocks(day, force=args.force)
+        hub.pipeline.audit("cli", "stocks-refresh", f"stocks:{day}", json.dumps(
+            {"force": bool(args.force), "state": result.get("state"), "batch_id": result.get("batch_id")},
+            ensure_ascii=False,
+        ))
+        json.dump(result, sys.stdout, ensure_ascii=False, indent=2, default=str)
+        sys.stdout.write("\n")
+        return 0 if result.get("state") != "failed" else 1
+    if args.command == "moneyflow-backfill":
+        result = hub.pipeline.backfill_moneyflow_history(
+            end_date=args.end_date,
+            trading_days=args.trading_days,
+            force=args.force,
+        )
+        hub.pipeline.audit("cli", "moneyflow-backfill", f"moneyflow:{result.get('end')}", json.dumps(
+            {"published": len(result.get("published") or []), "skipped": len(result.get("skipped") or []),
+             "failed": len(result.get("failed") or [])},
+            ensure_ascii=False,
+        ))
+        json.dump(result, sys.stdout, ensure_ascii=False, indent=2, default=str)
+        sys.stdout.write("\n")
+        return 0 if result.get("ok") else 1
+    parser.error(f"unknown command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

xiaobai-datahub/datahub/codes.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from datahub.db import HubDB
+
+
+def resolve_code(db: HubDB, raw: str) -> str | None:
+    text = str(raw or "").strip().upper()
+    if not text:
+        return None
+    if "." in text:
+        row = db.fetchone("SELECT ts_code FROM stock_master WHERE ts_code = ?", (text,))
+        if row:
+            return row["ts_code"]
+        # indices are not always in stock_master
+        return text
+    matches = db.fetchall(
+        "SELECT ts_code FROM stock_master WHERE symbol = ? OR ts_code LIKE ?",
+        (text, f"{text}.%"),
+    )
+    if len(matches) == 1:
+        return matches[0]["ts_code"]
+    if len(matches) > 1:
+        return None
+    # unique exchange guess for 6-digit codes
+    suffix = "SH" if text.startswith("6") or text.startswith("9") else "SZ" if text.startswith(("0", "3")) else "BJ"
+    return f"{text}.{suffix}"

xiaobai-datahub/datahub/coverage.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from datahub.db import HubDB
+from datahub.timeutil import iter_yyyymmdd, yyyymmdd
+
+MISSING_SAMPLE_LIMIT = 10
+
+
+def coverage_payload(
+    *,
+    kind: str,
+    start: str,
+    end: str,
+    expected: Iterable[str],
+    available: Iterable[str],
+    extra: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    start = yyyymmdd(start)
+    end = yyyymmdd(end)
+    expected_list = sorted({yyyymmdd(item) for item in expected if item})
+    available_set = {yyyymmdd(item) for item in available if item}
+    missing = [item for item in expected_list if item not in available_set]
+    payload: dict[str, Any] = {
+        "kind": kind,
+        "complete": not missing,
+        "requested_from": start,
+        "requested_to": end,
+        "available_from": min(available_set) if available_set else None,
+        "available_to": max(available_set) if available_set else None,
+        "expected_count": len(expected_list),
+        "available_count": len(available_set),
+        "missing_count": len(missing),
+        "missing_sample": missing[:MISSING_SAMPLE_LIMIT],
+    }
+    if extra:
+        payload.update(extra)
+    return payload
+
+
+def calendar_coverage(db: HubDB, start: str, end: str, exchange: str = "SSE") -> dict[str, Any]:
+    start = yyyymmdd(start)
+    end = yyyymmdd(end)
+    expected = list(iter_yyyymmdd(start, end))
+    rows = db.fetchall(
+        "SELECT cal_date FROM trade_calendar WHERE exchange = ? AND cal_date >= ? AND cal_date <= ?",
+        (exchange, start, end),
+    )
+    return coverage_payload(
+        kind="calendar",
+        start=start,
+        end=end,
+        expected=expected,
+        available=(row["cal_date"] for row in rows),
+        extra={"exchange": exchange},
+    )
+
+
+def published_range_coverage(
+    db: HubDB,
+    dataset: str,
+    start: str,
+    end: str,
+    ts_code: str = "",
+    table: str = "",
+) -> dict[str, Any]:
+    start = yyyymmdd(start)
+    end = yyyymmdd(end)
+    calendar = calendar_coverage(db, start, end)
+    open_rows = db.fetchall(
+        """
+        SELECT cal_date FROM trade_calendar
+        WHERE exchange = 'SSE' AND is_open = 1 AND cal_date >= ? AND cal_date <= ?
+        ORDER BY cal_date
+        """,
+        (start, end),
+    )
+    expected_open = [row["cal_date"] for row in open_rows]
+    pubs = db.fetchall(
+        """
+        SELECT trade_date, active_batch FROM publications
+        WHERE dataset = ? AND trade_date >= ? AND trade_date <= ?
+        ORDER BY trade_date
+        """,
+        (dataset, start, end),
+    )
+    published_dates = [row["trade_date"] for row in pubs]
+    available = list(published_dates)
+    extra: dict[str, Any] = {
+        "dataset": dataset,
+        "calendar_complete": calendar["complete"],
+        "calendar_missing_count": calendar["missing_count"],
+    }
+    if ts_code and table and pubs:
+        present_code: list[str] = []
+        for pub in pubs:
+            hit = db.fetchone(
+                f"SELECT 1 AS ok FROM {table} WHERE trade_date = ? AND batch_id = ? AND ts_code = ? LIMIT 1",
+                (pub["trade_date"], pub["active_batch"], ts_code),
+            )
+            if hit:
+                present_code.append(pub["trade_date"])
+        available = present_code
+        extra["code"] = ts_code
+    payload = coverage_payload(
+        kind="published_range",
+        start=start,
+        end=end,
+        expected=expected_open,
+        available=available,
+        extra=extra,
+    )
+    if not calendar["complete"]:
+        payload["complete"] = False
+        payload["calendar_missing_sample"] = calendar["missing_sample"]
+    return payload
+
+
+def point_coverage(trade_date: str, dataset: str = "") -> dict[str, Any]:
+    day = yyyymmdd(trade_date)
+    payload = coverage_payload(
+        kind="point",
+        start=day,
+        end=day,
+        expected=[day],
+        available=[day],
+        extra={"dataset": dataset} if dataset else None,
+    )
+    return payload

xiaobai-datahub/datahub/crypto.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from cryptography.fernet import Fernet, InvalidToken
+
+
+class SecretVault:
+    def __init__(self, key: str) -> None:
+        try:
+            self._fernet = Fernet(key.encode("ascii"))
+        except (ValueError, TypeError) as exc:
+            raise ValueError("DATAHUB_ENCRYPTION_KEY 格式无效。") from exc
+
+    @staticmethod
+    def generate_key() -> str:
+        return Fernet.generate_key().decode("ascii")
+
+    def encrypt_json(self, payload: dict[str, Any]) -> str:
+        raw = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+        return self._fernet.encrypt(raw).decode("ascii")
+
+    def decrypt_json(self, token: str) -> dict[str, Any]:
+        if not token:
+            return {}
+        try:
+            payload = json.loads(self._fernet.decrypt(token.encode("ascii")).decode("utf-8"))
+        except (InvalidToken, UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise ValueError("凭据无法解密，请检查 DATAHUB_ENCRYPTION_KEY。") from exc
+        if not isinstance(payload, dict):
+            raise ValueError("凭据格式无效。")
+        return payload
+
+
+def mask_secret(value: str, last_n: int = 4) -> str:
+    text = str(value or "")
+    if not text:
+        return ""
+    if len(text) <= last_n:
+        return "*" * len(text)
+    return ("*" * max(4, len(text) - last_n)) + text[-last_n:]

xiaobai-datahub/datahub/datasets_ext.py

@@ -0,0 +1,180 @@
+"""Extended EOD datasets beyond the first-batch A/B release groups.
+
+These publish independently (soft): a failure here must not block daily/valuation
+release. Scheduler runs them after the core EOD window.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Independent soft datasets (not part of A/B atomic groups).
+EXTENDED_SOFT_DATASETS = {
+    "limit_events",
+    "popularity",
+    "dragon_tiger",
+    "sector_daily",
+}
+
+EXTENDED_SCHEMA = """
+CREATE TABLE IF NOT EXISTS eod_limit_events (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL, limit_type TEXT NOT NULL,
+  name TEXT, industry TEXT, close REAL, pct_chg REAL, amount REAL,
+  limit_amount REAL, float_mv REAL, total_mv REAL, turnover_ratio REAL,
+  fd_amount REAL, first_time TEXT, last_time TEXT,
+  open_times INTEGER, up_stat TEXT, limit_times INTEGER,
+  batch_id TEXT NOT NULL,
+  PRIMARY KEY (ts_code, trade_date, limit_type, batch_id)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS staging_limit_events (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL, limit_type TEXT NOT NULL, batch_id TEXT NOT NULL,
+  name TEXT, industry TEXT, close REAL, pct_chg REAL, amount REAL,
+  limit_amount REAL, float_mv REAL, total_mv REAL, turnover_ratio REAL,
+  fd_amount REAL, first_time TEXT, last_time TEXT,
+  open_times INTEGER, up_stat TEXT, limit_times INTEGER,
+  PRIMARY KEY (batch_id, ts_code, trade_date, limit_type)
+);
+
+CREATE TABLE IF NOT EXISTS eod_popularity (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL, source TEXT NOT NULL,
+  ts_name TEXT, rank INTEGER, pct_change REAL, current_price REAL,
+  hot REAL, concept TEXT, data_type TEXT,
+  batch_id TEXT NOT NULL,
+  PRIMARY KEY (ts_code, trade_date, source, batch_id)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS staging_popularity (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL, source TEXT NOT NULL, batch_id TEXT NOT NULL,
+  ts_name TEXT, rank INTEGER, pct_change REAL, current_price REAL,
+  hot REAL, concept TEXT, data_type TEXT,
+  PRIMARY KEY (batch_id, ts_code, trade_date, source)
+);
+
+CREATE TABLE IF NOT EXISTS eod_dragon_tiger (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL, hm_name TEXT NOT NULL,
+  ts_name TEXT, buy_amount REAL, sell_amount REAL, net_amount REAL,
+  hm_orgs TEXT, tag TEXT, pct_change REAL, reason TEXT,
+  batch_id TEXT NOT NULL,
+  PRIMARY KEY (ts_code, trade_date, hm_name, batch_id)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS staging_dragon_tiger (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL, hm_name TEXT NOT NULL, batch_id TEXT NOT NULL,
+  ts_name TEXT, buy_amount REAL, sell_amount REAL, net_amount REAL,
+  hm_orgs TEXT, tag TEXT, pct_change REAL, reason TEXT,
+  PRIMARY KEY (batch_id, ts_code, trade_date, hm_name)
+);
+
+CREATE TABLE IF NOT EXISTS eod_sector_daily (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL, family TEXT NOT NULL,
+  name TEXT, open REAL, high REAL, low REAL, close REAL, pre_close REAL,
+  pct_change REAL, vol REAL, turnover_rate REAL, amount REAL,
+  batch_id TEXT NOT NULL,
+  PRIMARY KEY (ts_code, trade_date, family, batch_id)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS staging_sector_daily (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL, family TEXT NOT NULL, batch_id TEXT NOT NULL,
+  name TEXT, open REAL, high REAL, low REAL, close REAL, pre_close REAL,
+  pct_change REAL, vol REAL, turnover_rate REAL, amount REAL,
+  PRIMARY KEY (batch_id, ts_code, trade_date, family)
+);
+
+CREATE TABLE IF NOT EXISTS sector_master (
+  ts_code TEXT PRIMARY KEY,
+  name TEXT,
+  family TEXT NOT NULL,
+  exchange TEXT,
+  list_date TEXT,
+  member_count INTEGER,
+  type TEXT,
+  updated_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_eod_limit_date ON eod_limit_events(trade_date, batch_id);
+CREATE INDEX IF NOT EXISTS idx_eod_pop_date ON eod_popularity(trade_date, batch_id);
+CREATE INDEX IF NOT EXISTS idx_eod_lhb_date ON eod_dragon_tiger(trade_date, batch_id);
+CREATE INDEX IF NOT EXISTS idx_eod_sector_date ON eod_sector_daily(trade_date, family, batch_id);
+"""
+
+EXTENDED_DATASET_TABLES = {
+    "limit_events": ("eod_limit_events", "staging_limit_events"),
+    "popularity": ("eod_popularity", "staging_popularity"),
+    "dragon_tiger": ("eod_dragon_tiger", "staging_dragon_tiger"),
+    "sector_daily": ("eod_sector_daily", "staging_sector_daily"),
+}
+
+EXTENDED_STAGING_INSERT: dict[str, tuple[str, Any]] = {
+    "limit_events": (
+        "INSERT INTO staging_limit_events("
+        "ts_code,trade_date,limit_type,batch_id,name,industry,close,pct_chg,amount,"
+        "limit_amount,float_mv,total_mv,turnover_ratio,fd_amount,first_time,last_time,"
+        "open_times,up_stat,limit_times) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+        lambda r, b: (
+            r["ts_code"], r["trade_date"], r["limit_type"], b,
+            r.get("name"), r.get("industry"), r.get("close"), r.get("pct_chg"), r.get("amount"),
+            r.get("limit_amount"), r.get("float_mv"), r.get("total_mv"), r.get("turnover_ratio"),
+            r.get("fd_amount"), r.get("first_time"), r.get("last_time"),
+            r.get("open_times"), r.get("up_stat"), r.get("limit_times"),
+        ),
+    ),
+    "popularity": (
+        "INSERT INTO staging_popularity("
+        "ts_code,trade_date,source,batch_id,ts_name,rank,pct_change,current_price,hot,concept,data_type) "
+        "VALUES (?,?,?,?,?,?,?,?,?,?,?)",
+        lambda r, b: (
+            r["ts_code"], r["trade_date"], r["source"], b,
+            r.get("ts_name"), r.get("rank"), r.get("pct_change"), r.get("current_price"),
+            r.get("hot"), r.get("concept"), r.get("data_type"),
+        ),
+    ),
+    "dragon_tiger": (
+        "INSERT INTO staging_dragon_tiger("
+        "ts_code,trade_date,hm_name,batch_id,ts_name,buy_amount,sell_amount,net_amount,"
+        "hm_orgs,tag,pct_change,reason) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)",
+        lambda r, b: (
+            r["ts_code"], r["trade_date"], r["hm_name"], b,
+            r.get("ts_name"), r.get("buy_amount"), r.get("sell_amount"), r.get("net_amount"),
+            r.get("hm_orgs"), r.get("tag"), r.get("pct_change"), r.get("reason"),
+        ),
+    ),
+    "sector_daily": (
+        "INSERT INTO staging_sector_daily("
+        "ts_code,trade_date,family,batch_id,name,open,high,low,close,pre_close,"
+        "pct_change,vol,turnover_rate,amount) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+        lambda r, b: (
+            r["ts_code"], r["trade_date"], r["family"], b,
+            r.get("name"), r.get("open"), r.get("high"), r.get("low"), r.get("close"),
+            r.get("pre_close"), r.get("pct_change"), r.get("vol"), r.get("turnover_rate"),
+            r.get("amount"),
+        ),
+    ),
+}
+
+EXTENDED_EOD_COPY = {
+    "limit_events": (
+        "INSERT OR REPLACE INTO eod_limit_events "
+        "SELECT ts_code,trade_date,limit_type,name,industry,close,pct_chg,amount,"
+        "limit_amount,float_mv,total_mv,turnover_ratio,fd_amount,first_time,last_time,"
+        "open_times,up_stat,limit_times,batch_id "
+        "FROM staging_limit_events WHERE batch_id = ?"
+    ),
+    "popularity": (
+        "INSERT OR REPLACE INTO eod_popularity "
+        "SELECT ts_code,trade_date,source,ts_name,rank,pct_change,current_price,hot,concept,data_type,batch_id "
+        "FROM staging_popularity WHERE batch_id = ?"
+    ),
+    "dragon_tiger": (
+        "INSERT OR REPLACE INTO eod_dragon_tiger "
+        "SELECT ts_code,trade_date,hm_name,ts_name,buy_amount,sell_amount,net_amount,"
+        "hm_orgs,tag,pct_change,reason,batch_id "
+        "FROM staging_dragon_tiger WHERE batch_id = ?"
+    ),
+    "sector_daily": (
+        "INSERT OR REPLACE INTO eod_sector_daily "
+        "SELECT ts_code,trade_date,family,name,open,high,low,close,pre_close,"
+        "pct_change,vol,turnover_rate,amount,batch_id "
+        "FROM staging_sector_daily WHERE batch_id = ?"
+    ),
+}

xiaobai-datahub/datahub/db.py

@@ -0,0 +1,384 @@
+from __future__ import annotations
+
+import sqlite3
+import threading
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from datahub.datasets_ext import EXTENDED_DATASET_TABLES, EXTENDED_SCHEMA
+from datahub.timeutil import isoformat
+
+_BASE_SCHEMA = """
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  version INTEGER PRIMARY KEY,
+  applied_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS credentials (
+  name TEXT PRIMARY KEY,
+  encrypted_payload TEXT NOT NULL,
+  last4 TEXT,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS hub_admin (
+  id INTEGER PRIMARY KEY,
+  username TEXT NOT NULL UNIQUE,
+  password_salt TEXT NOT NULL,
+  password_hash TEXT NOT NULL,
+  password_must_change INTEGER NOT NULL DEFAULT 1,
+  failed_attempts INTEGER NOT NULL DEFAULT 0,
+  locked_until TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS hub_sessions (
+  token_hash TEXT PRIMARY KEY,
+  csrf_token TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS api_tokens (
+  token_hash TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  last4 TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  revoked_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS trade_calendar (
+  exchange TEXT NOT NULL,
+  cal_date TEXT NOT NULL,
+  is_open INTEGER NOT NULL,
+  pretrade_date TEXT,
+  fetched_at TEXT NOT NULL,
+  PRIMARY KEY (exchange, cal_date)
+);
+
+CREATE TABLE IF NOT EXISTS stock_master (
+  ts_code TEXT PRIMARY KEY,
+  symbol TEXT,
+  name TEXT,
+  area TEXT,
+  industry TEXT,
+  market TEXT,
+  list_status TEXT,
+  list_date TEXT,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS eod_bars (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL,
+  open REAL, high REAL, low REAL, close REAL, pct_chg REAL,
+  volume REAL, amount REAL, adj_factor REAL,
+  batch_id TEXT NOT NULL,
+  PRIMARY KEY (ts_code, trade_date, batch_id)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS eod_valuation (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL,
+  turnover_rate REAL, volume_ratio REAL,
+  total_mv REAL, circ_mv REAL,
+  pe_ttm REAL, pb REAL, ps_ttm REAL, dv_ttm REAL,
+  batch_id TEXT NOT NULL,
+  PRIMARY KEY (ts_code, trade_date, batch_id)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS eod_moneyflow (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL,
+  buy_sm_amount REAL, sell_sm_amount REAL,
+  buy_md_amount REAL, sell_md_amount REAL,
+  buy_lg_amount REAL, sell_lg_amount REAL,
+  buy_elg_amount REAL, sell_elg_amount REAL,
+  net_mf_amount REAL,
+  batch_id TEXT NOT NULL,
+  PRIMARY KEY (ts_code, trade_date, batch_id)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS eod_auction (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL,
+  volume REAL, price REAL, amount REAL, pre_close REAL,
+  turnover_rate REAL, volume_ratio REAL, float_share REAL,
+  batch_id TEXT NOT NULL,
+  PRIMARY KEY (ts_code, trade_date, batch_id)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS eod_index_bars (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL,
+  open REAL, high REAL, low REAL, close REAL, pct_chg REAL,
+  volume REAL, amount REAL,
+  batch_id TEXT NOT NULL,
+  PRIMARY KEY (ts_code, trade_date, batch_id)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS eod_stocks (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL,
+  symbol TEXT, name TEXT, area TEXT, industry TEXT, market TEXT,
+  list_status TEXT, list_date TEXT,
+  batch_id TEXT NOT NULL,
+  PRIMARY KEY (ts_code, trade_date, batch_id)
+) WITHOUT ROWID;
+
+CREATE TABLE IF NOT EXISTS staging_stocks (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL, batch_id TEXT NOT NULL,
+  symbol TEXT, name TEXT, area TEXT, industry TEXT, market TEXT,
+  list_status TEXT, list_date TEXT,
+  PRIMARY KEY (batch_id, ts_code, trade_date)
+);
+
+CREATE TABLE IF NOT EXISTS staging_bars (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL, batch_id TEXT NOT NULL,
+  open REAL, high REAL, low REAL, close REAL, pct_chg REAL,
+  volume REAL, amount REAL, adj_factor REAL,
+  PRIMARY KEY (batch_id, ts_code, trade_date)
+);
+
+CREATE TABLE IF NOT EXISTS staging_valuation (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL, batch_id TEXT NOT NULL,
+  turnover_rate REAL, volume_ratio REAL,
+  total_mv REAL, circ_mv REAL, pe_ttm REAL, pb REAL, ps_ttm REAL, dv_ttm REAL,
+  PRIMARY KEY (batch_id, ts_code, trade_date)
+);
+
+CREATE TABLE IF NOT EXISTS staging_moneyflow (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL, batch_id TEXT NOT NULL,
+  buy_sm_amount REAL, sell_sm_amount REAL, buy_md_amount REAL, sell_md_amount REAL,
+  buy_lg_amount REAL, sell_lg_amount REAL, buy_elg_amount REAL, sell_elg_amount REAL,
+  net_mf_amount REAL,
+  PRIMARY KEY (batch_id, ts_code, trade_date)
+);
+
+CREATE TABLE IF NOT EXISTS staging_auction (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL, batch_id TEXT NOT NULL,
+  volume REAL, price REAL, amount REAL, pre_close REAL,
+  turnover_rate REAL, volume_ratio REAL, float_share REAL,
+  PRIMARY KEY (batch_id, ts_code, trade_date)
+);
+
+CREATE TABLE IF NOT EXISTS staging_index_bars (
+  ts_code TEXT NOT NULL, trade_date TEXT NOT NULL, batch_id TEXT NOT NULL,
+  open REAL, high REAL, low REAL, close REAL, pct_chg REAL,
+  volume REAL, amount REAL,
+  PRIMARY KEY (batch_id, ts_code, trade_date)
+);
+
+CREATE TABLE IF NOT EXISTS publications (
+  dataset TEXT NOT NULL, trade_date TEXT NOT NULL,
+  active_batch TEXT NOT NULL, prev_batch TEXT,
+  state TEXT NOT NULL,
+  published_at TEXT NOT NULL,
+  PRIMARY KEY (dataset, trade_date)
+);
+
+CREATE TABLE IF NOT EXISTS publication_history (
+  dataset TEXT NOT NULL, trade_date TEXT NOT NULL,
+  batch_id TEXT NOT NULL, published_at TEXT NOT NULL,
+  generation INTEGER NOT NULL,
+  PRIMARY KEY (dataset, trade_date, batch_id)
+);
+
+CREATE TABLE IF NOT EXISTS batches (
+  batch_id TEXT PRIMARY KEY,
+  dataset TEXT NOT NULL,
+  trade_date TEXT NOT NULL,
+  state TEXT NOT NULL,
+  attempt INTEGER DEFAULT 0,
+  rows_in INTEGER,
+  rows_out INTEGER,
+  quality_json TEXT,
+  started_at TEXT,
+  finished_at TEXT,
+  error TEXT
+);
+
+CREATE TABLE IF NOT EXISTS src_health (
+  provider TEXT NOT NULL, endpoint_class TEXT NOT NULL,
+  state TEXT NOT NULL,
+  last_ok_at TEXT, last_error TEXT,
+  consec_failures INTEGER DEFAULT 0,
+  opened_at TEXT,
+  cooldown_until TEXT,
+  PRIMARY KEY (provider, endpoint_class)
+);
+
+CREATE TABLE IF NOT EXISTS src_calls (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  provider TEXT NOT NULL,
+  endpoint TEXT NOT NULL,
+  ok INTEGER NOT NULL,
+  latency_ms INTEGER,
+  error TEXT,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS job_runs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  job_id TEXT NOT NULL,
+  state TEXT NOT NULL,
+  started_at TEXT,
+  finished_at TEXT,
+  rows_in INTEGER,
+  rows_out INTEGER,
+  error TEXT,
+  attempt INTEGER DEFAULT 1,
+  detail TEXT
+);
+
+CREATE TABLE IF NOT EXISTS eod_progress (
+  trade_date TEXT PRIMARY KEY,
+  state TEXT NOT NULL,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  last_attempt_at TEXT,
+  next_retry_at TEXT,
+  finished_at TEXT,
+  detail TEXT,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS revision_progress (
+  trade_date TEXT PRIMARY KEY,
+  state TEXT NOT NULL,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  last_attempt_at TEXT,
+  next_retry_at TEXT,
+  finished_at TEXT,
+  catchup_done INTEGER NOT NULL DEFAULT 0,
+  last_diff TEXT,
+  detail TEXT,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS audit_log (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  actor TEXT NOT NULL,
+  action TEXT NOT NULL,
+  target TEXT,
+  detail TEXT,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS rt_cache (
+  cache_key TEXT PRIMARY KEY,
+  payload TEXT NOT NULL,
+  source TEXT NOT NULL,
+  stored_at TEXT NOT NULL,
+  expires_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS last_known_good (
+  cache_key TEXT PRIMARY KEY,
+  payload TEXT NOT NULL,
+  source TEXT NOT NULL,
+  stored_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS diff_reports (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  trade_date TEXT NOT NULL,
+  metric TEXT NOT NULL,
+  left_source TEXT,
+  right_source TEXT,
+  left_value REAL,
+  right_value REAL,
+  deviation REAL,
+  sample_count INTEGER,
+  created_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_batches_date ON batches(trade_date, dataset);
+CREATE INDEX IF NOT EXISTS idx_job_runs_job ON job_runs(job_id, started_at);
+CREATE INDEX IF NOT EXISTS idx_src_calls_created ON src_calls(created_at);
+CREATE INDEX IF NOT EXISTS idx_eod_bars_date ON eod_bars(trade_date, batch_id);
+CREATE INDEX IF NOT EXISTS idx_calendar_open ON trade_calendar(is_open, cal_date);
+"""
+
+SCHEMA = _BASE_SCHEMA + EXTENDED_SCHEMA
+
+DATASET_TABLES = {
+    "daily": ("eod_bars", "staging_bars"),
+    "valuation": ("eod_valuation", "staging_valuation"),
+    "moneyflow": ("eod_moneyflow", "staging_moneyflow"),
+    "auction": ("eod_auction", "staging_auction"),
+    "index_daily": ("eod_index_bars", "staging_index_bars"),
+    "stocks": ("eod_stocks", "staging_stocks"),
+    **EXTENDED_DATASET_TABLES,
+}
+
+
+class ManagedConnection(sqlite3.Connection):
+    def __exit__(self, exc_type, exc_value, traceback):
+        try:
+            return super().__exit__(exc_type, exc_value, traceback)
+        finally:
+            self.close()
+
+
+class HubDB:
+    def __init__(self, path: Path, timeout_seconds: float = 20) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.timeout_seconds = timeout_seconds
+        self._write_lock = threading.RLock()
+        self.initialize()
+
+    def connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(
+            self.path,
+            timeout=self.timeout_seconds,
+            factory=ManagedConnection,
+        )
+        connection.row_factory = sqlite3.Row
+        connection.execute("PRAGMA journal_mode=WAL")
+        connection.execute("PRAGMA foreign_keys=ON")
+        connection.execute("PRAGMA busy_timeout=20000")
+        connection.execute("PRAGMA synchronous=NORMAL")
+        return connection
+
+    def initialize(self) -> None:
+        with self.connect() as connection:
+            connection.executescript(SCHEMA)
+            row = connection.execute(
+                "SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 1"
+            ).fetchone()
+            if row is None:
+                connection.execute(
+                    "INSERT INTO schema_migrations(version, applied_at) VALUES (1, ?)",
+                    (isoformat(),),
+                )
+
+    @contextmanager
+    def write(self) -> Iterator[sqlite3.Connection]:
+        with self._write_lock:
+            with self.connect() as connection:
+                yield connection
+
+    def fetchall(self, sql: str, params: tuple[Any, ...] = ()) -> list[dict[str, Any]]:
+        with self.connect() as connection:
+            rows = connection.execute(sql, params).fetchall()
+        return [dict(row) for row in rows]
+
+    def fetchone(self, sql: str, params: tuple[Any, ...] = ()) -> dict[str, Any] | None:
+        with self.connect() as connection:
+            row = connection.execute(sql, params).fetchone()
+        return dict(row) if row else None
+
+    def execute(self, sql: str, params: tuple[Any, ...] = ()) -> None:
+        with self.write() as connection:
+            connection.execute(sql, params)
+
+    def executemany(self, sql: str, rows: list[tuple[Any, ...]]) -> None:
+        with self.write() as connection:
+            connection.executemany(sql, rows)
+
+    def backup_to(self, dest: Path) -> None:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        with self.connect() as source, sqlite3.connect(dest) as target:
+            source.backup(target)
+
+    def vacuum(self) -> None:
+        with self.connect() as connection:
+            connection.execute("VACUUM")

xiaobai-datahub/datahub/governance/__init__.py

@@ -0,0 +1,13 @@
+from datahub.governance.circuit import CircuitBreaker, CircuitState
+from datahub.governance.lkg import LastKnownGood
+from datahub.governance.ratelimit import TokenBucket
+from datahub.governance.retry import RetryError, retry_call
+
+__all__ = [
+    "CircuitBreaker",
+    "CircuitState",
+    "LastKnownGood",
+    "RetryError",
+    "TokenBucket",
+    "retry_call",
+]

xiaobai-datahub/datahub/governance/circuit.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass
+
+
+@dataclass
+class CircuitState:
+    state: str = "closed"  # closed | open | half_open
+    consec_failures: int = 0
+    opened_at: float | None = None
+    cooldown_until: float = 0.0
+    last_error: str = ""
+    last_ok_at: float | None = None
+
+
+class CircuitBreaker:
+    """Sliding-window breaker: 5 consecutive failures or >50% of 60s window → open."""
+
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        window_seconds: float = 60.0,
+        open_seconds: float = 120.0,
+        max_open_seconds: float = 600.0,
+        clock=time.monotonic,
+    ) -> None:
+        self.failure_threshold = failure_threshold
+        self.window_seconds = window_seconds
+        self.open_seconds = open_seconds
+        self.max_open_seconds = max_open_seconds
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._events: deque[tuple[float, bool]] = deque()
+        self.status = CircuitState()
+        self._open_stretch = open_seconds
+
+    def allow(self) -> bool:
+        with self._lock:
+            self._refresh_locked()
+            if self.status.state == "open":
+                return False
+            if self.status.state == "half_open":
+                # single probe in flight: caller must record success/failure
+                return True
+            return True
+
+    def record_success(self) -> CircuitState:
+        with self._lock:
+            now = self._clock()
+            self._events.append((now, True))
+            self.status.last_ok_at = now
+            self.status.consec_failures = 0
+            self.status.last_error = ""
+            self._open_stretch = self.open_seconds
+            self.status.state = "closed"
+            self.status.opened_at = None
+            self.status.cooldown_until = 0.0
+            return self._copy()
+
+    def record_failure(self, error: str = "") -> CircuitState:
+        with self._lock:
+            now = self._clock()
+            self._events.append((now, False))
+            self.status.consec_failures += 1
+            self.status.last_error = error
+            self._prune_locked(now)
+            failures = sum(1 for _, ok in self._events if not ok)
+            total = len(self._events)
+            rate = (failures / total) if total else 0.0
+            trip = self.status.consec_failures >= self.failure_threshold or (
+                total >= self.failure_threshold and rate > 0.5
+            )
+            if trip:
+                self.status.state = "open"
+                self.status.opened_at = now
+                self.status.cooldown_until = now + self._open_stretch
+                self._open_stretch = min(self.max_open_seconds, self._open_stretch * 2)
+            return self._copy()
+
+    def snapshot(self) -> CircuitState:
+        with self._lock:
+            self._refresh_locked()
+            return self._copy()
+
+    def _refresh_locked(self) -> None:
+        now = self._clock()
+        self._prune_locked(now)
+        if self.status.state == "open" and now >= self.status.cooldown_until:
+            self.status.state = "half_open"
+
+    def _prune_locked(self, now: float) -> None:
+        cutoff = now - self.window_seconds
+        while self._events and self._events[0][0] < cutoff:
+            self._events.popleft()
+
+    def _copy(self) -> CircuitState:
+        return CircuitState(
+            state=self.status.state,
+            consec_failures=self.status.consec_failures,
+            opened_at=self.status.opened_at,
+            cooldown_until=self.status.cooldown_until,
+            last_error=self.status.last_error,
+            last_ok_at=self.status.last_ok_at,
+        )

xiaobai-datahub/datahub/governance/lkg.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from datahub.db import HubDB
+from datahub.timeutil import isoformat, now_shanghai
+
+
+class LastKnownGood:
+    def __init__(self, db: HubDB) -> None:
+        self.db = db
+
+    def store(self, cache_key: str, payload: Any, source: str) -> None:
+        self.db.execute(
+            """
+            INSERT INTO last_known_good(cache_key, payload, source, stored_at)
+            VALUES (?, ?, ?, ?)
+            ON CONFLICT(cache_key) DO UPDATE SET
+              payload=excluded.payload, source=excluded.source, stored_at=excluded.stored_at
+            """,
+            (cache_key, json.dumps(payload, ensure_ascii=False), source, isoformat()),
+        )
+
+    def load(self, cache_key: str) -> dict[str, Any] | None:
+        row = self.db.fetchone("SELECT * FROM last_known_good WHERE cache_key = ?", (cache_key,))
+        if not row:
+            return None
+        return {
+            "payload": json.loads(row["payload"]),
+            "source": row["source"],
+            "stored_at": row["stored_at"],
+        }
+
+    def put_rt(self, cache_key: str, payload: Any, source: str, ttl_seconds: int) -> None:
+        now = now_shanghai()
+        expires = isoformat(now.replace(microsecond=0))
+        # expires_at stored as iso; compute by adding ttl via timestamp
+        from datetime import timedelta
+
+        self.db.execute(
+            """
+            INSERT INTO rt_cache(cache_key, payload, source, stored_at, expires_at)
+            VALUES (?, ?, ?, ?, ?)
+            ON CONFLICT(cache_key) DO UPDATE SET
+              payload=excluded.payload, source=excluded.source,
+              stored_at=excluded.stored_at, expires_at=excluded.expires_at
+            """,
+            (
+                cache_key,
+                json.dumps(payload, ensure_ascii=False),
+                source,
+                isoformat(now),
+                isoformat(now + timedelta(seconds=ttl_seconds)),
+            ),
+        )
+        self.store(cache_key, payload, source)
+
+    def get_rt(self, cache_key: str, max_stale_seconds: int | None = None) -> dict[str, Any] | None:
+        row = self.db.fetchone("SELECT * FROM rt_cache WHERE cache_key = ?", (cache_key,))
+        if not row:
+            lkg = self.load(cache_key)
+            if not lkg:
+                return None
+            return {**lkg, "stale": True}
+        stored_at = row["stored_at"]
+        expired = row["expires_at"] < isoformat()
+        result = {
+            "payload": json.loads(row["payload"]),
+            "source": row["source"],
+            "stored_at": stored_at,
+            "stale": expired,
+        }
+        if expired and max_stale_seconds is not None:
+            from datetime import datetime
+
+            try:
+                stored = datetime.fromisoformat(stored_at)
+                age = (now_shanghai() - stored).total_seconds()
+            except ValueError:
+                age = max_stale_seconds + 1
+            if age > max_stale_seconds:
+                return None
+        return result

xiaobai-datahub/datahub/governance/ratelimit.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import threading
+import time
+
+
+class TokenBucket:
+    def __init__(self, rate_per_minute: float, capacity: float | None = None, clock=time.monotonic) -> None:
+        self.rate_per_second = max(0.001, rate_per_minute / 60.0)
+        self.capacity = float(capacity if capacity is not None else rate_per_minute)
+        self._tokens = self.capacity
+        self._updated = clock()
+        self._clock = clock
+        self._lock = threading.Lock()
+
+    def acquire(self, tokens: float = 1.0, block: bool = True) -> bool:
+        while True:
+            with self._lock:
+                now = self._clock()
+                elapsed = max(0.0, now - self._updated)
+                self._tokens = min(self.capacity, self._tokens + elapsed * self.rate_per_second)
+                self._updated = now
+                if self._tokens >= tokens:
+                    self._tokens -= tokens
+                    return True
+                wait = (tokens - self._tokens) / self.rate_per_second
+            if not block:
+                return False
+            time.sleep(min(wait, 0.05))
+
+    @property
+    def remaining(self) -> float:
+        with self._lock:
+            now = self._clock()
+            elapsed = max(0.0, now - self._updated)
+            return min(self.capacity, self._tokens + elapsed * self.rate_per_second)

xiaobai-datahub/datahub/governance/retry.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+class RetryError(RuntimeError):
+    def __init__(self, message: str, attempts: int, last_error: BaseException | None = None) -> None:
+        super().__init__(message)
+        self.attempts = attempts
+        self.last_error = last_error
+
+
+def retry_call(
+    fn: Callable[[], T],
+    attempts: int = 5,
+    base_delay: float = 0.2,
+    max_delay: float = 8.0,
+    sleeper: Callable[[float], None] = time.sleep,
+    retry_on: tuple[type[BaseException], ...] = (Exception,),
+) -> T:
+    last: BaseException | None = None
+    for attempt in range(1, max(1, attempts) + 1):
+        try:
+            return fn()
+        except retry_on as exc:
+            last = exc
+            if attempt >= attempts:
+                break
+            delay = min(max_delay, base_delay * (2 ** (attempt - 1)))
+            sleeper(delay)
+    raise RetryError(f"retry exhausted after {attempts} attempts: {last}", attempts, last)