feat(HEL-402): 接通网站首批只读 datahub 并建立双路对比

默认全部读取/影子开关关闭，网站继续走旧 Tushare 链路；开启单项时只替换该类原料并在失败时回旧，问天保持旧路径。

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

.dockerignore

@@ -9,6 +9,7 @@ __pycache__/
 *.log
 runtime/
 data/cache/
+data/backups/
 data/private-mentor-skills/
 data/*.db
 data/*.db-shm

.env.example

@@ -5,6 +5,11 @@ APP_ENCRYPTION_KEY=
 # the system settings; all accounts use the same backend market snapshot.
 TUSHARE_TOKEN=your_tushare_token_here
 
+# Optional xiaobai-datahub client. All DATAHUB_READ_* / DATAHUB_SHADOW_* flags
+# default off in config/datahub.config.json, so the website keeps using Tushare.
+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

DOCKER_DEPLOY.md

@@ -165,58 +165,58 @@ docker compose restart xiaobai-review
 docker compose down
 ```
 
-### 使用 Gitea 更新程序（推荐）
+### 服务器本地目录更新与构建（日常推荐）
 
-代码仓库为：
+生产机 `192.168.200.11` 的 `/opt/1panel/docker/compose/xiaobaifupan` 自 2026-08-29（HEL-235B）
+起已是受 Git 管理的工作目录，只跟踪 Gitea `main`（仓库
+`http://192.168.200.36:3200/leefer/xiaobai-review.git`）。由于目录顶层归 root，
+`.git` 存放在部署账号家目录（外部 Git 目录方案）：
 
 ```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 一致性备份，再拉取并重建容器：
+镜像 tag 固定为 `main-<提交短号7位>`（不带提交号的模糊 tag 一律禁止）；每次构建在
+`~/xiaobai-build/BUILD_LOG.tsv` 留痕。构建只产出镜像，不启动、不替换容器；换版与
+回滚步骤见 `~/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`。
 
-重新上传代码后执行：
+### 历史方式（已废弃）
 
-```bash
+早期文档建议在服务器重新 `git clone` 一份或手工上传代码后 `docker compose up --build`。
-docker compose down
+这两条路径已废弃：服务器上**只允许存在一个受管工作目录**（上述
-docker compose build --pull
+`/opt/1panel/docker/compose/xiaobaifupan`），任何脱离 Git 校验的本地构建都会把
-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/config.py

@@ -18,6 +18,8 @@ TOKEN_PATTERN = re.compile(r"^[A-Za-z0-9_-]{20,128}$")
 USERNAME_PATTERN = re.compile(r"^[A-Za-z0-9_\-\u4e00-\u9fff]{3,30}$")
 SESSION_COOKIE = "xiaobai_session"
 SESSION_MAX_AGE = 30 * 24 * 60 * 60
+DEVICE_COOKIE = "xiaobai_device"
+DEVICE_MAX_AGE = 180 * 24 * 60 * 60
 
 
 def load_local_env() -> None:

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,249 @@
+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.settings import DatahubSettings
+from backend.data.providers.tushare_client import TushareClient
+
+LOGGER = logging.getLogger("xiaobai.datahub")
+ShadowSink = Callable[[dict[str, Any]], None]
+EMPTY_FAIL_DATASETS = {"stocks", "daily", "index_daily", "valuation", "moneyflow", "auction"}
+
+
+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 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)
+        if not dataset or self.heaven_guard():
+            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 {})
+            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)))
+                    return project_fields(hub_rows, fields)
+                raise
+            self._emit_shadow(compare_rows(dataset, legacy_rows, hub_canonical, hub_meta, hub_error))
+            if flags.read and hub_rows is not None and hub_error is None:
+                return project_fields(hub_rows, fields)
+            return legacy_rows
+
+        if flags.read and hub_rows is not None and hub_error is None:
+            return project_fields(hub_rows, fields)
+        return legacy_query(api_name, params, fields)
+
+    def _fetch_dataset(self, dataset: str, params: dict[str, Any]) -> 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,
+        }
+        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"
+        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) -> 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")
+
+    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:
+        LOGGER.warning(
+            "datahub fallback dataset=%s error=%s",
+            dataset,
+            redact_text(self._error_text(exc), 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())
+
+
+class DatahubAwareTushareClient:
+    def __init__(self, legacy: TushareClient, bridge: DatahubBridge) -> None:
+        self._legacy = legacy
+        self._bridge = bridge
+
+    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 __getattr__(self, name: str) -> Any:
+        return getattr(self._legacy, name)

backend/data/datahub/client.py

@@ -0,0 +1,184 @@
+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 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,134 @@
+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
+
+
+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,
+) -> dict[str, Any]:
+    hub = hub_rows or []
+    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)
+        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,
+        "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 _compare_fields(dataset: str, legacy: dict[str, Any], hub: dict[str, Any]) -> 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"}
+    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,153 @@
+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",
+}
+
+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},
+}
+
+
+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)
+    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")))
+    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/settings.py

@@ -0,0 +1,120 @@
+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",
+    "status",
+)
+
+ENV_DATASET = {
+    "calendar": "CALENDAR",
+    "stocks": "STOCKS",
+    "daily": "DAILY",
+    "index_daily": "INDEX_DAILY",
+    "valuation": "VALUATION",
+    "moneyflow": "MONEYFLOW",
+    "auction": "AUCTION",
+    "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,13 @@ class DataGateway:
     ) -> TushareClient:
         if dataset_id:
             self.policy.assert_allowed(dataset_id, "tushare", usage)
-        return self.tushare_provider.client()
+        return DatahubAwareTushareClient(self.tushare_provider.client(), 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 assert_source(self, dataset_id: str, provider_id: str, usage: DataUsage) -> None:
         self.policy.assert_allowed(dataset_id, provider_id, usage)
@@ -64,6 +73,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,6 +83,8 @@ 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)
     return DataGateway(
         policy=policy,
         quality=DataQualityGate.load(policy),
@@ -80,4 +92,5 @@ def build_data_gateway(
         ifind_provider=IfindProvider(ifind),
         chart_data=MarketChartClient(ifind, EastmoneyChartClient()),
         realtime_observer=WebRealtimeAggregator(),
+        datahub=DatahubBridge(settings, datahub_client),
     )

backend/data/providers/tushare_dashboard.py

@@ -41,13 +41,16 @@ class DashboardMixin:
             raise TushareError(f"No daily data returned for {trade_date}")
 
         notices: list[str] = []
+        limit_data_source = "official"
         try:
             limit_rows = self._load_limit_lists(trade_date)
             previous_limit_rows = self._load_limit_type(previous_trade_date, "U")
             if not limit_rows:
+                limit_data_source = "derived"
                 notices.append("涨跌停高级接口当日数据尚未更新，已使用日线数据推算。")
                 limit_rows = self._derive_limits(trade_date, daily)
         except TushareError as exc:
+            limit_data_source = "derived"
             notices.append(f"涨跌停高级接口不可用，已使用日线数据推算：{exc}")
             limit_rows = self._derive_limits(trade_date, daily)
             previous_daily = self._load_daily(previous_trade_date)
@@ -79,6 +82,7 @@ class DashboardMixin:
                 "trade_date": _display_date(trade_date),
                 "previous_trade_date": _display_date(previous_trade_date),
                 "source": "tushare",
+                "limit_data_source": limit_data_source,
                 "updated_at": datetime.now().astimezone().isoformat(timespec="seconds"),
                 "notice": "；".join(notices),
             },

backend/database/migrations/__init__.py

@@ -2,6 +2,7 @@ from .m0001_adopt_legacy import MIGRATION as M0001_ADOPT_LEGACY
 from .m0002_job_runs import MIGRATION as M0002_JOB_RUNS
 from .m0003_llm_audit import MIGRATION as M0003_LLM_AUDIT
 from .m0004_mentor_notes import MIGRATION as M0004_MENTOR_NOTES
+from .m0005_account_switch_grants import MIGRATION as M0005_ACCOUNT_SWITCH_GRANTS
 from .runner import Migration, MigrationError, MigrationRunner
 
 MIGRATIONS = (
@@ -9,6 +10,7 @@ MIGRATIONS = (
     M0002_JOB_RUNS,
     M0003_LLM_AUDIT,
     M0004_MENTOR_NOTES,
+    M0005_ACCOUNT_SWITCH_GRANTS,
 )
 
 __all__ = ["MIGRATIONS", "Migration", "MigrationError", "MigrationRunner"]

backend/database/migrations/m0005_account_switch_grants.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import sqlite3
+
+from backend.database.migrations.runner import Migration
+
+
+def create_account_switch_grants(connection: sqlite3.Connection) -> None:
+    connection.execute(
+        """
+        CREATE TABLE IF NOT EXISTS account_switch_grants (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            device_hash TEXT NOT NULL,
+            user_id INTEGER NOT NULL,
+            granted_at TEXT NOT NULL,
+            last_used_at TEXT NOT NULL,
+            expires_at TEXT NOT NULL,
+            UNIQUE (device_hash, user_id),
+            FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+        )
+        """
+    )
+    connection.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_account_switch_grants_device
+        ON account_switch_grants(device_hash, last_used_at DESC)
+        """
+    )
+    connection.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_account_switch_grants_expiry
+        ON account_switch_grants(expires_at)
+        """
+    )
+
+
+MIGRATION = Migration(
+    version="0005",
+    name="create_account_switch_grants",
+    action=create_account_switch_grants,
+    signature="account-switch-grants:v1:device,user,granted,used,expires,unique",
+)

backend/features/accounts/application.py

@@ -28,11 +28,11 @@ class AccountApplicationMixin:
     def update_membership(self, payload: dict[str, Any]) -> None:
         self.accounts.update_membership(payload)
 
-    def register_account(self, username: str, password: str) -> dict[str, Any]:
+    def register_account(self, username: str, password: str, device_hash: str = "") -> dict[str, Any]:
-        return self.accounts.register(username, password)
+        return self.accounts.register(username, password, device_hash)
 
-    def login_account(self, username: str, password: str) -> dict[str, Any]:
+    def login_account(self, username: str, password: str, device_hash: str = "") -> dict[str, Any]:
-        return self.accounts.login(username, password)
+        return self.accounts.login(username, password, device_hash)
 
     def change_password(self, current_password: str, new_password: str) -> None:
         self.accounts.change_password(current_password, new_password)

backend/features/accounts/http.py

@@ -1,49 +1,108 @@
 from __future__ import annotations
 
 import json
+import secrets
 from http import HTTPStatus
 
+from backend.features.accounts.security import token_hash
+
 
 class AccountHttpMixin:
+    def _device_hash(self) -> str:
+        raw = self.device_token()
+        return token_hash(raw) if raw else ""
+
+    def _ensure_device_token(self) -> str:
+        return self.device_token() or secrets.token_urlsafe(32)
+
+    def _auth_success_headers(self, session_token: str, device_raw: str) -> list[tuple[str, str]]:
+        return [
+            ("Set-Cookie", self.session_cookie(session_token)),
+            ("Set-Cookie", self.device_cookie(device_raw)),
+        ]
+
+    def _send_authenticated_session(self, result: dict, status: HTTPStatus, device_raw: str) -> None:
+        self.send_json(
+            {
+                "ok": True,
+                "authenticated": True,
+                "user": result["user"],
+                "csrf_token": result["csrf_token"],
+            },
+            status,
+            self._auth_success_headers(result["session_token"], device_raw),
+        )
+
     def auth_register(self) -> None:
         try:
             body = self.read_json_body()
+            device_raw = self._ensure_device_token()
             result = self.application_service.register_account(
                 str(body.get("username") or ""),
                 str(body.get("password") or ""),
+                token_hash(device_raw),
             )
-            self.send_json(
+            self._send_authenticated_session(result, HTTPStatus.CREATED, device_raw)
-                {
-                    "ok": True,
-                    "authenticated": True,
-                    "user": result["user"],
-                    "csrf_token": result["csrf_token"],
-                },
-                HTTPStatus.CREATED,
-                {"Set-Cookie": self.session_cookie(result["session_token"])},
-            )
         except (ValueError, json.JSONDecodeError) as exc:
             self.send_json({"error": str(exc)}, HTTPStatus.BAD_REQUEST)
 
     def auth_login(self) -> None:
         try:
             body = self.read_json_body()
+            device_raw = self._ensure_device_token()
             result = self.application_service.login_account(
                 str(body.get("username") or ""),
                 str(body.get("password") or ""),
+                token_hash(device_raw),
             )
-            self.send_json(
+            self._send_authenticated_session(result, HTTPStatus.OK, device_raw)
-                {
-                    "ok": True,
-                    "authenticated": True,
-                    "user": result["user"],
-                    "csrf_token": result["csrf_token"],
-                },
-                headers={"Set-Cookie": self.session_cookie(result["session_token"])},
-            )
         except (ValueError, json.JSONDecodeError) as exc:
             self.send_json({"error": str(exc)}, HTTPStatus.UNAUTHORIZED)
 
+    def auth_accounts(self) -> None:
+        current_user_id = None
+        if self.require_auth(send_error=False):
+            current_user_id = int(self.auth_user["id"])
+        payload = self.application_service.accounts.list_device_accounts(
+            self._device_hash(),
+            current_user_id,
+        )
+        self.send_json({"ok": True, **payload})
+
+    def auth_switch(self) -> None:
+        try:
+            body = self.read_json_body()
+            try:
+                user_id = int(body.get("user_id"))
+            except (TypeError, ValueError):
+                user_id = 0
+            device_raw = self.device_token()
+            result = self.application_service.accounts.switch_account(
+                token_hash(device_raw) if device_raw else "",
+                user_id,
+            )
+            self._send_authenticated_session(
+                result,
+                HTTPStatus.OK,
+                device_raw or self._ensure_device_token(),
+            )
+        except PermissionError as exc:
+            self.send_json({"error": str(exc)}, HTTPStatus.UNAUTHORIZED)
+        except (ValueError, json.JSONDecodeError) as exc:
+            self.send_json({"error": str(exc)}, HTTPStatus.BAD_REQUEST)
+
+    def auth_forget(self) -> None:
+        try:
+            body = self.read_json_body()
+            try:
+                user_id = int(body.get("user_id"))
+            except (TypeError, ValueError):
+                user_id = 0
+            self.application_service.accounts.forget_account(self._device_hash(), user_id)
+        except (ValueError, json.JSONDecodeError):
+            pass
+        self.send_json({"ok": True})
+
     def auth_me(self) -> None:
         service = self.application_service
         if not self.require_auth(send_error=False):
@@ -55,6 +114,15 @@ class AccountHttpMixin:
                 }
             )
             return
+        headers = None
+        if not self.device_token():
+            device_raw = secrets.token_urlsafe(32)
+            service.accounts.remember_account(
+                token_hash(device_raw),
+                int(self.auth_user["id"]),
+                fresh=True,
+            )
+            headers = [("Set-Cookie", self.device_cookie(device_raw))]
         self.send_json(
             {
                 "ok": True,
@@ -66,15 +134,19 @@ class AccountHttpMixin:
                     "membership": service.membership(),
                 },
                 "csrf_token": str(self.auth_user["csrf_token"]),
-            }
+            },
+            headers=headers,
         )
 
     def auth_logout(self) -> None:
         raw_token = self.session_token()
+        user_id = int(getattr(self, "auth_user", {}).get("id") or 0)
         if raw_token:
-            from backend.features.accounts.security import token_hash
-
             self.application_service.database.delete_session(token_hash(raw_token))
+        self.application_service.accounts.revoke_current_device_grant(
+            self._device_hash(),
+            user_id,
+        )
         self.send_json(
             {"ok": True},
             headers={"Set-Cookie": self.session_cookie("", clear=True)},

backend/features/accounts/repository.py

@@ -234,3 +234,96 @@ class AccountRepositoryMixin:
                 (user_id,),
             )
             return cursor.rowcount > 0
+
+    def cleanup_expired_switch_grants(self, now: str) -> int:
+        with self.connect() as connection:
+            cursor = connection.execute(
+                "DELETE FROM account_switch_grants WHERE expires_at <= ?",
+                (now,),
+            )
+        return int(cursor.rowcount)
+
+    def list_switch_grants(self, device_hash: str, now: str) -> list[dict[str, Any]]:
+        with self.connect() as connection:
+            rows = connection.execute(
+                """
+                SELECT u.id, u.username, u.role, u.llm_mode, u.membership_status,
+                       u.membership_plan, u.membership_starts_at, u.membership_expires_at,
+                       u.created_at, g.last_used_at, g.granted_at, g.expires_at
+                FROM account_switch_grants AS g
+                JOIN users AS u ON u.id = g.user_id
+                WHERE g.device_hash = ? AND g.expires_at > ?
+                ORDER BY g.last_used_at DESC, g.id DESC
+                """,
+                (device_hash, now),
+            ).fetchall()
+        return [dict(row) for row in rows]
+
+    def get_switch_grant(self, device_hash: str, user_id: int) -> dict[str, Any] | None:
+        with self.connect() as connection:
+            row = connection.execute(
+                """
+                SELECT device_hash, user_id, granted_at, last_used_at, expires_at
+                FROM account_switch_grants
+                WHERE device_hash = ? AND user_id = ?
+                """,
+                (device_hash, user_id),
+            ).fetchone()
+        return dict(row) if row else None
+
+    def upsert_switch_grant(
+        self,
+        device_hash: str,
+        user_id: int,
+        granted_at: str,
+        last_used_at: str,
+        expires_at: str,
+    ) -> None:
+        with self.connect() as connection:
+            connection.execute(
+                """
+                INSERT INTO account_switch_grants
+                    (device_hash, user_id, granted_at, last_used_at, expires_at)
+                VALUES (?, ?, ?, ?, ?)
+                ON CONFLICT(device_hash, user_id) DO UPDATE SET
+                    granted_at = excluded.granted_at,
+                    last_used_at = excluded.last_used_at,
+                    expires_at = excluded.expires_at
+                """,
+                (device_hash, user_id, granted_at, last_used_at, expires_at),
+            )
+
+    def prune_switch_grants(self, device_hash: str, keep: int) -> int:
+        with self.connect() as connection:
+            rows = connection.execute(
+                """
+                SELECT id FROM account_switch_grants
+                WHERE device_hash = ?
+                ORDER BY last_used_at DESC, id DESC
+                """,
+                (device_hash,),
+            ).fetchall()
+            extra = [int(row["id"]) for row in rows[keep:]]
+            if not extra:
+                return 0
+            connection.execute(
+                f"DELETE FROM account_switch_grants WHERE id IN ({','.join('?' * len(extra))})",
+                extra,
+            )
+        return len(extra)
+
+    def delete_switch_grant(self, device_hash: str, user_id: int) -> bool:
+        with self.connect() as connection:
+            cursor = connection.execute(
+                "DELETE FROM account_switch_grants WHERE device_hash = ? AND user_id = ?",
+                (device_hash, user_id),
+            )
+        return cursor.rowcount > 0
+
+    def delete_switch_grants_for_user(self, user_id: int) -> int:
+        with self.connect() as connection:
+            cursor = connection.execute(
+                "DELETE FROM account_switch_grants WHERE user_id = ?",
+                (user_id,),
+            )
+        return int(cursor.rowcount)

backend/features/accounts/routes.py

@@ -6,6 +6,9 @@ class AccountRoutesMixin:
         if parsed.path == "/api/auth/me":
             self.auth_me()
             return True
+        if parsed.path == "/api/auth/accounts":
+            self.auth_accounts()
+            return True
         return False
 
     def _handle_accounts_get(self, parsed) -> bool:

backend/features/accounts/service.py

@@ -77,15 +77,22 @@ class AccountService:
         access = self.access_supplier() or self.database.user_access(self.current_user_id) or {}
         return self.membership_for_access(access)
 
-    def register(self, username: str, password: str) -> dict[str, Any]:
+    GRANT_SLIDE_DAYS = 30
+    GRANT_HARD_DAYS = 180
+    MAX_GRANTS_PER_DEVICE = 5
+    SWITCH_REAUTH_MESSAGE = "该账号需重新验证"
+
+    def register(self, username: str, password: str, device_hash: str = "") -> dict[str, Any]:
         username = username.strip()
         self.validate_input(username, password)
         with self.auth_lock:
             salt, password_digest = hash_password(password)
             user = self.database.create_user(username, salt, password_digest)
-        return self.create_session(user)
+        result = self.create_session(user)
+        self.remember_account(device_hash, int(user["id"]), fresh=True)
+        return result
 
-    def login(self, username: str, password: str) -> dict[str, Any]:
+    def login(self, username: str, password: str, device_hash: str = "") -> dict[str, Any]:
         username = username.strip()
         if not username or not password:
             raise ValueError("账号名和密码不能为空。")
@@ -96,7 +103,9 @@ class AccountService:
             str(user.get("password_hash") or ""),
         ):
             raise ValueError("账号名或密码不正确。")
-        return self.create_session(user)
+        result = self.create_session(user)
+        self.remember_account(device_hash, int(user["id"]), fresh=True)
+        return result
 
     def change_password(self, current_password: str, new_password: str) -> None:
         current_password = str(current_password or "")
@@ -112,6 +121,86 @@ class AccountService:
         salt, digest = hash_password(new_password)
         if not self.database.update_user_password(self.current_user_id, salt, digest):
             raise ValueError("账号不存在。")
+        self.database.delete_switch_grants_for_user(self.current_user_id)
+
+    @staticmethod
+    def _utc_now() -> datetime:
+        return datetime.now(timezone.utc)
+
+    @classmethod
+    def _iso(cls, value: datetime) -> str:
+        return value.isoformat(timespec="seconds")
+
+    def remember_account(self, device_hash: str, user_id: int, *, fresh: bool = False) -> None:
+        if not device_hash or user_id <= 0:
+            return
+        now = self._utc_now()
+        now_text = self._iso(now)
+        self.database.cleanup_expired_switch_grants(now_text)
+        existing = None if fresh else self.database.get_switch_grant(device_hash, user_id)
+        granted_at = parse_iso_datetime(existing["granted_at"]) if existing else now
+        if granted_at is None:
+            granted_at = now
+        expires = min(
+            now + timedelta(days=self.GRANT_SLIDE_DAYS),
+            granted_at + timedelta(days=self.GRANT_HARD_DAYS),
+        )
+        if not existing:
+            self.database.prune_switch_grants(device_hash, self.MAX_GRANTS_PER_DEVICE - 1)
+        self.database.upsert_switch_grant(
+            device_hash,
+            user_id,
+            self._iso(granted_at),
+            now_text,
+            self._iso(expires),
+        )
+
+    def list_device_accounts(
+        self, device_hash: str, current_user_id: int | None = None
+    ) -> dict[str, Any]:
+        if not device_hash:
+            return {"accounts": [], "current_user_id": current_user_id}
+        now_text = self._iso(self._utc_now())
+        self.database.cleanup_expired_switch_grants(now_text)
+        accounts = []
+        for row in self.database.list_switch_grants(device_hash, now_text):
+            accounts.append(
+                {
+                    "user_id": int(row["id"]),
+                    "username": str(row["username"]),
+                    "role": str(row.get("role") or "user"),
+                    "membership": self.membership_for_access(row),
+                    "last_used_at": str(row.get("last_used_at") or ""),
+                }
+            )
+        return {"accounts": accounts, "current_user_id": current_user_id}
+
+    def switch_account(self, device_hash: str, user_id: int) -> dict[str, Any]:
+        if not device_hash or user_id <= 0:
+            raise PermissionError(self.SWITCH_REAUTH_MESSAGE)
+        now = self._utc_now()
+        now_text = self._iso(now)
+        self.database.cleanup_expired_switch_grants(now_text)
+        grant = self.database.get_switch_grant(device_hash, user_id)
+        expires = parse_iso_datetime(grant.get("expires_at")) if grant else None
+        if not grant or not expires or expires <= now:
+            if grant:
+                self.database.delete_switch_grant(device_hash, user_id)
+            raise PermissionError(self.SWITCH_REAUTH_MESSAGE)
+        user = self.database.user_access(user_id)
+        if not user:
+            raise PermissionError(self.SWITCH_REAUTH_MESSAGE)
+        result = self.create_session(user)
+        self.remember_account(device_hash, user_id)
+        return result
+
+    def forget_account(self, device_hash: str, user_id: int) -> None:
+        if device_hash and user_id > 0:
+            self.database.delete_switch_grant(device_hash, user_id)
+
+    def revoke_current_device_grant(self, device_hash: str, user_id: int) -> None:
+        if device_hash and user_id > 0:
+            self.database.delete_switch_grant(device_hash, user_id)
 
     def create_session(self, user: dict[str, Any]) -> dict[str, Any]:
         session_token = secrets.token_urlsafe(32)

backend/features/market/service.py

@@ -198,6 +198,11 @@ class MarketServiceMixin:
                     raise TushareError("公共行情尚未配置")
                 dashboard = self._tushare_client().dashboard(normalized_date)
 
+                if (dashboard.get("meta") or {}).get("limit_data_source") == "derived":
+                    raise TushareError(
+                        str((dashboard.get("meta") or {}).get("notice") or "官方涨跌停数据尚未返回")
+                    )
+
                 dashboard["meta"]["source"] = source
                 dashboard["meta"]["requested_date"] = self._display_compact_date(normalized_date)
                 dashboard = self._enrich_dashboard_sentiment(dashboard, normalized_date)
@@ -1163,4 +1168,3 @@ class MarketServiceMixin:
             len(dashboard.get(key) or [])
             for key in ("limits", "broken", "down_limits", "yesterday_limits")
         )
-

backend/features/system/http.py

@@ -26,13 +26,15 @@ class SystemHttpMixin:
     def start_background_refresh(self) -> None:
         try:
             body = self.read_json_body(allow_empty=True)
-            started = self.application_service.request_background_sync(
+            refresh = self.application_service.request_background_sync(
                 str(body.get("trade_date") or date.today().isoformat())
             )
+            started = bool(refresh.get("started"))
             self.send_json(
                 {
                     "ok": True,
                     "started": started,
+                    "job_key": str(refresh.get("job_key") or ""),
                     "message": "后台刷新已开始" if started else "已有后台刷新任务正在运行",
                 },
                 HTTPStatus.ACCEPTED,

backend/http/dispatch.py

@@ -7,6 +7,8 @@ from urllib.parse import urlparse
 PUBLIC_POST_HANDLERS = {
     "/api/auth/register": "auth_register",
     "/api/auth/login": "auth_login",
+    "/api/auth/switch": "auth_switch",
+    "/api/auth/forget": "auth_forget",
 }
 
 AUTHENTICATED_POST_HANDLERS = {

backend/http/handler.py

@@ -9,7 +9,13 @@ from http.cookies import SimpleCookie
 from typing import Any
 from urllib.parse import unquote
 
-from backend.bootstrap.config import SESSION_COOKIE, SESSION_MAX_AGE, STATIC_DIR
+from backend.bootstrap.config import (
+    DEVICE_COOKIE,
+    DEVICE_MAX_AGE,
+    SESSION_COOKIE,
+    SESSION_MAX_AGE,
+    STATIC_DIR,
+)
 from backend.features.accounts.security import token_hash
 from backend.http.context import correlation_id
 from backend.http.errors import normalize_error_payload
@@ -21,15 +27,21 @@ class HttpTransportMixin:
     application_service: Any
     route_registry: Any
 
-    def session_token(self) -> str:
+    def cookie_value(self, name: str) -> str:
         cookie = SimpleCookie()
         try:
             cookie.load(self.headers.get("Cookie", ""))
         except Exception:
             return ""
-        morsel = cookie.get(SESSION_COOKIE)
+        morsel = cookie.get(name)
         return morsel.value if morsel else ""
 
+    def session_token(self) -> str:
+        return self.cookie_value(SESSION_COOKIE)
+
+    def device_token(self) -> str:
+        return self.cookie_value(DEVICE_COOKIE)
+
     def require_auth(self, send_error: bool = True) -> bool:
         raw_token = self.session_token()
         service = self.application_service
@@ -79,15 +91,18 @@ class HttpTransportMixin:
             return self.require_member()
         return True
 
-    def session_cookie(self, value: str, clear: bool = False) -> str:
+    def _cookie_header(self, name: str, value: str, max_age: int) -> str:
-        max_age = 0 if clear else SESSION_MAX_AGE
+        cookie = f"{name}={value}; Path=/; HttpOnly; SameSite=Lax; Max-Age={max_age}"
-        cookie = (
-            f"{SESSION_COOKIE}={value}; Path=/; HttpOnly; SameSite=Lax; Max-Age={max_age}"
-        )
         if self.headers.get("X-Forwarded-Proto", "").lower() == "https":
             cookie += "; Secure"
         return cookie
 
+    def session_cookie(self, value: str, clear: bool = False) -> str:
+        return self._cookie_header(SESSION_COOKIE, value, 0 if clear else SESSION_MAX_AGE)
+
+    def device_cookie(self, value: str, clear: bool = False) -> str:
+        return self._cookie_header(DEVICE_COOKIE, value, 0 if clear else DEVICE_MAX_AGE)
+
     def read_json_body(self, allow_empty: bool = False) -> dict[str, Any]:
         length = int(self.headers.get("Content-Length", "0"))
         if length == 0 and allow_empty:
@@ -132,7 +147,7 @@ class HttpTransportMixin:
         self,
         payload: dict[str, Any],
         status: HTTPStatus = HTTPStatus.OK,
-        headers: dict[str, str] | None = None,
+        headers: dict[str, str] | list[tuple[str, str]] | tuple[tuple[str, str], ...] | None = None,
     ) -> None:
         request_id = getattr(self, "_correlation_id", "")
         if not request_id:
@@ -145,7 +160,8 @@ class HttpTransportMixin:
         self.send_header("Content-Length", str(len(content)))
         self.send_header("Cache-Control", "no-store")
         self.send_header("X-Request-ID", request_id)
-        for name, value in (headers or {}).items():
+        header_items = headers.items() if isinstance(headers, dict) else (headers or ())
+        for name, value in header_items:
             self.send_header(name, value)
         self.end_headers()
         self.wfile.write(content)

backend/jobs/service.py

@@ -7,6 +7,16 @@ from datetime import date
 from backend.bootstrap.config import normalize_date
 
 
+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:
     def start_background_jobs(self) -> threading.Thread:
         return self.jobs.start_scheduler(
@@ -20,15 +30,16 @@ class JobServiceMixin:
         workers_stopped = self.jobs.wait_for_idle(timeout_seconds)
         return scheduler_stopped and workers_stopped
 
-    def request_background_sync(self, trade_date: str) -> bool:
+    def request_background_sync(self, trade_date: str) -> dict[str, object]:
         normalized = normalize_date(trade_date)
         key = f"manual:{normalized}:{time.time_ns()}"
-        return self.jobs.submit(
+        started = self.jobs.submit(
             "market.refresh",
             key,
-            lambda: 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 ""}
 
     def _background_refresh_tick(self) -> None:
         if not (

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"

config/README.md

@@ -12,6 +12,9 @@ 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`: optional read-only client for `xiaobai-datahub`. Each dataset has its
+  own `read` / `shadow` flag, all default off. Environment variables `DATAHUB_READ_*` and
+  `DATAHUB_SHADOW_*` can override a single dataset without a master switch.
 - `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/api.config.json

@@ -128,6 +128,20 @@
       "feature": "auction",
       "access": "authenticated"
     },
+    {
+      "method": "GET",
+      "path": "/api/auth/accounts",
+      "match": "exact",
+      "feature": "auth",
+      "access": "public"
+    },
+    {
+      "method": "POST",
+      "path": "/api/auth/forget",
+      "match": "exact",
+      "feature": "auth",
+      "access": "public"
+    },
     {
       "method": "POST",
       "path": "/api/auth/login",
@@ -156,6 +170,13 @@
       "feature": "auth",
       "access": "public"
     },
+    {
+      "method": "POST",
+      "path": "/api/auth/switch",
+      "match": "exact",
+      "feature": "auth",
+      "access": "public"
+    },
     {
       "method": "POST",
       "path": "/api/backfill",

config/architecture-inventory.json

@@ -10,10 +10,10 @@
   },
   "counts": {
     "primary_pages": 16,
-    "api_exact_paths": 53,
+    "api_exact_paths": 56,
     "api_prefixes": 0,
     "api_patterns": 11,
-    "database_tables": 36,
+    "database_tables": 37,
     "frontend_page_fragments": 12
   },
   "pages": [
@@ -96,10 +96,13 @@
       "/api/assistant/chat",
       "/api/assistant/messages",
       "/api/auction",
+      "/api/auth/accounts",
+      "/api/auth/forget",
       "/api/auth/login",
       "/api/auth/logout",
       "/api/auth/me",
       "/api/auth/register",
+      "/api/auth/switch",
       "/api/backfill",
       "/api/chart/intraday",
       "/api/dashboard",
@@ -189,6 +192,7 @@
     "assistant_messages",
     "heaven_readings",
     "job_runs",
+    "account_switch_grants",
     "schema_migrations"
   ],
   "background_job_methods": [
@@ -200,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",
@@ -274,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"
@@ -370,11 +391,11 @@
     }
   ],
   "css_layers": [
-    "/shared/tokens.css?v=20260820-3",
+    "/shared/tokens.css?v=20260829-hel240",
     "/shared/base.css?v=20260806-1",
-    "/shared/shell.css?v=20260827-hel183",
+    "/shared/shell.css?v=20260829-hel237",
-    "/shared/auth.css?v=20260820-5",
+    "/shared/auth.css?v=20260829-hel240b",
-    "/shared/components/controls.css?v=20260827-hel183",
+    "/shared/components/controls.css?v=20260829-hel237",
     "/shared/components/navigation.css?v=20260820-1",
     "/shared/components/cards.css?v=20260820-1",
     "/shared/components/tables.css?v=20260820-1",
@@ -461,8 +482,8 @@
     },
     {
       "path": "frontend/index.html",
-      "bytes": 47891,
+      "bytes": 48254,
-      "lines": 661
+      "lines": 664
     },
     {
       "path": "backend/features/screener/catalog.py",
@@ -486,8 +507,8 @@
     },
     {
       "path": "backend/data/providers/tushare_dashboard.py",
-      "bytes": 28051,
+      "bytes": 28234,
-      "lines": 644
+      "lines": 648
     },
     {
       "path": "backend/data/providers/tushare_industries.py",
@@ -551,8 +572,13 @@
     },
     {
       "path": "frontend/shared/session.js",
-      "bytes": 13176,
+      "bytes": 13219,
-      "lines": 293
+      "lines": 289
+    },
+    {
+      "path": "frontend/shared/dashboard.js",
+      "bytes": 12894,
+      "lines": 274
     },
     {
       "path": "backend/features/market/insights_auction_data.py",
@@ -574,11 +600,6 @@
       "bytes": 10539,
       "lines": 244
     },
-    {
-      "path": "frontend/shared/dashboard.js",
-      "bytes": 9993,
-      "lines": 220
-    },
     {
       "path": "backend/data/providers/tushare_sectors.py",
       "bytes": 9876,
@@ -669,16 +690,16 @@
       "bytes": 5451,
       "lines": 118
     },
+    {
+      "path": "frontend/pages.config.js",
+      "bytes": 5385,
+      "lines": 130
+    },
     {
       "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,
@@ -716,8 +737,8 @@
     },
     {
       "path": "backend/http/dispatch.py",
-      "bytes": 4118,
+      "bytes": 4196,
-      "lines": 115
+      "lines": 117
     },
     {
       "path": "frontend/shared/table.js",
@@ -734,16 +755,16 @@
       "bytes": 3369,
       "lines": 81
     },
+    {
+      "path": "frontend/app.js",
+      "bytes": 3337,
+      "lines": 95
+    },
     {
       "path": "frontend/pages/themes/page.html",
       "bytes": 3316,
       "lines": 55
     },
-    {
-      "path": "frontend/app.js",
-      "bytes": 3201,
-      "lines": 93
-    },
     {
       "path": "backend/features/market/insights_context.py",
       "bytes": 3175,
@@ -761,7 +782,7 @@
     },
     {
       "path": "backend/features/accounts/application.py",
-      "bytes": 2442,
+      "bytes": 2514,
       "lines": 63
     },
     {
@@ -769,6 +790,11 @@
       "bytes": 2299,
       "lines": 57
     },
+    {
+      "path": "backend/jobs/service.py",
+      "bytes": 2219,
+      "lines": 60
+    },
     {
       "path": "backend/features/screener/regime.py",
       "bytes": 2202,
@@ -804,11 +830,6 @@
       "bytes": 1791,
       "lines": 46
     },
-    {
-      "path": "backend/jobs/service.py",
-      "bytes": 1746,
-      "lines": 49
-    },
     {
       "path": "backend/features/alerts/routes.py",
       "bytes": 1687,
@@ -849,6 +870,11 @@
       "bytes": 1143,
       "lines": 19
     },
+    {
+      "path": "backend/features/accounts/routes.py",
+      "bytes": 908,
+      "lines": 25
+    },
     {
       "path": "backend/features/popularity/routes.py",
       "bytes": 822,
@@ -859,11 +885,6 @@
       "bytes": 817,
       "lines": 23
     },
-    {
-      "path": "backend/features/accounts/routes.py",
-      "bytes": 803,
-      "lines": 22
-    },
     {
       "path": "backend/features/sentiment/routes.py",
       "bytes": 724,

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,18 @@
+{
+  "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": false, "shadow": false },
+    "stocks": { "read": false, "shadow": false },
+    "daily": { "read": false, "shadow": false },
+    "index_daily": { "read": false, "shadow": false },
+    "valuation": { "read": false, "shadow": false },
+    "moneyflow": { "read": false, "shadow": false },
+    "auction": { "read": false, "shadow": false },
+    "status": { "read": false, "shadow": false }
+  }
+}

frontend/app.js

@@ -25,8 +25,10 @@ async function initialize() {
   try {
     const session = await apiRequest("/api/auth/me");
     if (!session.authenticated) {
-      if (session.registration_required) selectAuthMode("register");
+      const params = new URLSearchParams();
-      showAuthGate();
+      if (session.registration_required) params.set("mode", "register");
+      const query = params.toString();
+      window.location.replace("/login/" + (query ? `?${query}` : ""));
       return;
     }
     await applyAuthenticatedSession(session);

frontend/index.html

@@ -24,7 +24,9 @@
     (() => {
       let theme = "light";
       try {
-        theme = localStorage.getItem("xiaobaiTheme") === "dark" ? "dark" : "light";
+        const stored = localStorage.getItem("xiaobaiTheme");
+        if (stored === "dark" || stored === "light") theme = stored;
+        else if (window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches) theme = "dark";
       } catch (_error) {
         theme = "light";
       }
@@ -32,11 +34,11 @@
       document.documentElement.style.colorScheme = theme;
     })();
   </script>
-  <link rel="stylesheet" href="/shared/tokens.css?v=20260820-3">
+  <link rel="stylesheet" href="/shared/tokens.css?v=20260829-hel240">
   <link rel="stylesheet" href="/shared/base.css?v=20260806-1">
-  <link rel="stylesheet" href="/shared/shell.css?v=20260827-hel183">
+  <link rel="stylesheet" href="/shared/shell.css?v=20260829-hel237">
-  <link rel="stylesheet" href="/shared/auth.css?v=20260820-5">
+  <link rel="stylesheet" href="/shared/auth.css?v=20260829-hel240b">
-  <link rel="stylesheet" href="/shared/components/controls.css?v=20260827-hel183">
+  <link rel="stylesheet" href="/shared/components/controls.css?v=20260829-hel237">
   <link rel="stylesheet" href="/shared/components/navigation.css?v=20260820-1">
   <link rel="stylesheet" href="/shared/components/cards.css?v=20260820-1">
   <link rel="stylesheet" href="/shared/components/tables.css?v=20260820-1">
@@ -57,7 +59,7 @@
   <link rel="stylesheet" href="/pages/review/foundation.css?v=20260820-4">
 </head>
 <body>
-  <section id="authGate" class="auth-gate" aria-label="账号登录">
+  <section id="authGate" class="auth-gate" aria-label="账号登录" hidden>
     <div class="auth-shell">
       <div class="auth-brand">
         <div class="brand-mark" aria-hidden="true"><span class="brand-glyph">复</span></div>
@@ -609,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="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>
       <section class="settings-section">

frontend/login/index.html

@@ -0,0 +1,162 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="color-scheme" content="light dark">
+  <title>登录 · 小白复盘</title>
+  <script>
+    (() => {
+      let theme = "light";
+      try {
+        const stored = localStorage.getItem("xiaobaiTheme");
+        if (stored === "dark" || stored === "light") theme = stored;
+        else if (window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches) theme = "dark";
+      } catch (_error) {
+        theme = "light";
+      }
+      document.documentElement.dataset.theme = theme;
+      document.documentElement.style.colorScheme = theme;
+    })();
+  </script>
+  <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-hel251">
+  <link rel="stylesheet" href="/shared/components/controls.css?v=20260820-2">
+</head>
+<body class="login-portal">
+  <aside class="login-brand" aria-hidden="true">
+    <div class="login-brand-header">
+      <div class="login-brand-mark"><span class="login-brand-glyph">复</span></div>
+      <div class="login-brand-identity">
+        <p class="login-brand-name">小白复盘</p>
+        <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>
+      <p class="login-brand-lead">情绪周期、涨停梯队、主题轮动、竞价、龙虎榜、人气榜、交易复盘，集中在一个安静的复盘空间。</p>
+    </div>
+    <div class="login-brand-market">
+      <svg class="login-brand-chart" viewBox="0 0 480 168" focusable="false">
+        <defs>
+          <linearGradient id="loginChartFade" x1="0" x2="0" y1="0" y2="1">
+            <stop offset="0%" stop-color="#d7e4ff" stop-opacity="0.18"></stop>
+            <stop offset="100%" stop-color="#d7e4ff" stop-opacity="0"></stop>
+          </linearGradient>
+        </defs>
+        <path class="login-chart-area" d="M8 118 C 52 108, 78 96, 112 102 S 168 128, 204 112 S 268 78, 312 86 S 372 118, 428 92 L 472 84 L 472 168 L 8 168 Z"></path>
+        <g class="login-candles">
+          <g class="is-up" transform="translate(36 0)"><line x1="8" y1="58" x2="8" y2="128"></line><rect x="2" y="72" width="12" height="40"></rect></g>
+          <g class="is-down" transform="translate(68 0)"><line x1="8" y1="64" x2="8" y2="132"></line><rect x="2" y="86" width="12" height="28"></rect></g>
+          <g class="is-up" transform="translate(100 0)"><line x1="8" y1="48" x2="8" y2="118"></line><rect x="2" y="60" width="12" height="44"></rect></g>
+          <g class="is-down" transform="translate(132 0)"><line x1="8" y1="70" x2="8" y2="136"></line><rect x="2" y="92" width="12" height="26"></rect></g>
+          <g class="is-up" transform="translate(164 0)"><line x1="8" y1="42" x2="8" y2="110"></line><rect x="2" y="54" width="12" height="38"></rect></g>
+          <g class="is-up" transform="translate(196 0)"><line x1="8" y1="36" x2="8" y2="98"></line><rect x="2" y="48" width="12" height="32"></rect></g>
+          <g class="is-down" transform="translate(228 0)"><line x1="8" y1="58" x2="8" y2="128"></line><rect x="2" y="78" width="12" height="36"></rect></g>
+          <g class="is-up" transform="translate(260 0)"><line x1="8" y1="40" x2="8" y2="104"></line><rect x="2" y="52" width="12" height="36"></rect></g>
+          <g class="is-down" transform="translate(292 0)"><line x1="8" y1="66" x2="8" y2="134"></line><rect x="2" y="88" width="12" height="30"></rect></g>
+          <g class="is-up" transform="translate(324 0)"><line x1="8" y1="44" x2="8" y2="112"></line><rect x="2" y="58" width="12" height="40"></rect></g>
+          <g class="is-down" transform="translate(356 0)"><line x1="8" y1="72" x2="8" y2="138"></line><rect x="2" y="96" width="12" height="24"></rect></g>
+          <g class="is-up" transform="translate(388 0)"><line x1="8" y1="38" x2="8" y2="108"></line><rect x="2" y="50" width="12" height="42"></rect></g>
+          <g class="is-up" transform="translate(420 0)"><line x1="8" y1="32" x2="8" y2="96"></line><rect x="2" y="44" width="12" height="34"></rect></g>
+        </g>
+        <path class="login-chart-line" d="M8 118 C 52 108, 78 96, 112 102 S 168 128, 204 112 S 268 78, 312 86 S 372 118, 428 92 L 472 84"></path>
+      </svg>
+      <dl class="login-brand-stats">
+        <div class="login-stat">
+          <dt>市场情绪</dt>
+          <dd>72 <span class="login-stat-tag">高热</span></dd>
+        </div>
+        <div class="login-stat">
+          <dt>涨停</dt>
+          <dd>63</dd>
+        </div>
+        <div class="login-stat">
+          <dt>跌停</dt>
+          <dd>4</dd>
+        </div>
+        <div class="login-stat login-stat-wide">
+          <dt>两市成交</dt>
+          <dd>1.02万亿</dd>
+        </div>
+      </dl>
+    </div>
+    <p class="login-brand-disclaimer">股市有风险，投资需谨慎 · 本工具仅供个人复盘学习使用</p>
+  </aside>
+  <main class="login-stage">
+    <button id="loginThemeToggle" class="login-theme-toggle" type="button">🌙 夜间</button>
+    <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-hel251"></script>
+</body>
+</html>

frontend/login/page.js

@@ -0,0 +1,610 @@
+(function bootLoginPortal(global) {
+  "use strict";
+
+  const THEME_KEY = "xiaobaiTheme";
+  const api = global.XiaobaiAPI;
+  const card = document.querySelector("#loginCard");
+  const themeButton = document.querySelector("#loginThemeToggle");
+  const state = {
+    view: "first",
+    mode: "login",
+    accounts: [],
+    currentUserId: null,
+    loading: false,
+    confirmingId: null,
+    error: "",
+    username: "",
+    password: "",
+    passwordVisible: false,
+  };
+
+  function escapeHtml(value) {
+    return String(value ?? "").replace(/[&<>"']/g, (ch) => (
+      { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[ch]
+    ));
+  }
+
+  function preferredTheme() {
+    try {
+      const stored = global.localStorage.getItem(THEME_KEY);
+      if (stored === "dark" || stored === "light") return stored;
+    } catch (_error) {
+      // Fall through to the system preference.
+    }
+    return global.matchMedia && global.matchMedia("(prefers-color-scheme: dark)").matches
+      ? "dark"
+      : "light";
+  }
+
+  function applyTheme(theme, persist) {
+    const normalized = theme === "dark" ? "dark" : "light";
+    document.documentElement.dataset.theme = normalized;
+    document.documentElement.style.colorScheme = normalized;
+    themeButton.textContent = normalized === "dark" ? "☀ 日间" : "🌙 夜间";
+    themeButton.setAttribute("aria-label", normalized === "dark" ? "切换到日间模式" : "切换到夜间模式");
+    if (persist) {
+      try {
+        global.localStorage.setItem(THEME_KEY, normalized);
+      } catch (_error) {
+        // Theme still applies for the current page when storage is unavailable.
+      }
+    }
+  }
+
+  function setError(message) {
+    state.error = message || "";
+  }
+
+  function formatLastUsed(value) {
+    if (!value) return "";
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) return "";
+    const now = new Date();
+    const hh = String(parsed.getHours()).padStart(2, "0");
+    const mm = String(parsed.getMinutes()).padStart(2, "0");
+    if (parsed.toDateString() === now.toDateString()) return `今天 ${hh}:${mm}`;
+    const yesterday = new Date(now);
+    yesterday.setDate(now.getDate() - 1);
+    if (parsed.toDateString() === yesterday.toDateString()) return `昨天 ${hh}:${mm}`;
+    return `${parsed.getMonth() + 1}月${parsed.getDate()}日`;
+  }
+
+  function chipsFor(account, current) {
+    const chips = [];
+    if (current) chips.push('<span class="login-chip login-chip-current">当前</span>');
+    if (account.role === "admin") chips.push('<span class="login-chip">管理员</span>');
+    if (account.membership?.subscribed) chips.push('<span class="login-chip login-chip-member">会员</span>');
+    else if (account.role !== "admin") chips.push('<span class="login-chip">普通用户</span>');
+    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() {
+    global.location.replace(returnPath());
+  }
+
+  function formMarkup(options) {
+    const registering = state.mode === "register";
+    const submitLabel = options.submitLabel
+      || (state.loading ? "正在登录..." : registering ? "注册并进入" : options.add ? "添加并进入" : "登录");
+    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>'
+        : "",
+      `<h2 class="login-card-title">${escapeHtml(options.title)}</h2>`,
+      `<p class="login-card-lead">${escapeHtml(lead)}</p>`,
+      '<div class="login-tabs" role="tablist">',
+      `<button class="login-tab${state.mode === "login" ? " is-active" : ""}" type="button" data-auth-mode="login">登录</button>`,
+      `<button class="login-tab${state.mode === "register" ? " is-active" : ""}" type="button" data-auth-mode="register">注册</button>`,
+      "</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><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" : ""}>`,
+      state.loading ? '<span class="login-spinner" aria-hidden="true"></span>' : "",
+      `<span>${escapeHtml(submitLabel)}</span></button>`,
+      "</form>",
+      `<p class="login-hint">${escapeHtml(hint)}</p>`,
+    ].join("");
+  }
+
+  function accountRow(account) {
+    const current = Number(account.user_id) === Number(state.currentUserId);
+    const confirming = Number(state.confirmingId) === Number(account.user_id);
+    const managing = state.view === "manage";
+    const classes = [
+      "login-account-row",
+      current ? "is-current" : "",
+      confirming ? "is-confirming" : "",
+      !managing ? "is-switchable" : "",
+    ].filter(Boolean).join(" ");
+    if (managing && confirming) {
+      return [
+        `<div class="${classes}" data-user-id="${account.user_id}">`,
+        `<p class="login-confirm-copy">移除「${escapeHtml(account.username)}」的本机记录？</p>`,
+        '<div class="login-confirm-actions">',
+        `<button class="button danger-button" type="button" data-forget-id="${account.user_id}">移除</button>`,
+        '<button class="button" type="button" data-login-action="cancel-forget">取消</button>',
+        "</div></div>",
+      ].join("");
+    }
+    const glyph = escapeHtml(String(account.username || "账").slice(0, 1));
+    const tone = Number(account.user_id || 0) % 4;
+    const used = formatLastUsed(account.last_used_at);
+    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-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}${resumeAttr}>`,
+      `<span class="login-avatar tone-${tone}" aria-hidden="true">${glyph}</span>`,
+      '<div class="login-account-meta">',
+      '<div class="login-account-name">',
+      `<strong>${escapeHtml(account.username)}</strong>`,
+      chipsFor(account, current),
+      "</div>",
+      used ? `<span class="login-account-used">上次登录 ${escapeHtml(used)}</span>` : "",
+      "</div>",
+      action,
+      "</div>",
+    ].join("");
+  }
+
+  function pickerMarkup() {
+    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
+        ? "移除只删除这台电脑上的登录记录，不会注销账号"
+        : `这台电脑已记录 ${count} 个账号，点选即可进入，无需再次输入密码。`}</p>`,
+      managing
+        ? '<div class="login-manage-toolbar"><p class="login-manage-hint">点击右侧图标移除对应记录</p><button class="login-manage-done" type="button" data-login-action="picker">完成</button></div>'
+        : "",
+      `<div class="login-account-list">${state.accounts.map(accountRow).join("")}</div>`,
+      managing
+        ? ""
+        : '<button class="login-add" type="button" data-login-action="add">＋ 添加账号</button>',
+      managing
+        ? ""
+        : '<button class="login-manage" type="button" data-login-action="manage">管理已记录的账号</button>',
+      state.error ? `<p class="login-error">${escapeHtml(state.error)}</p>` : "",
+      managing
+        ? '<p class="login-privacy"><span class="login-lock" aria-hidden="true">🔒</span>移除后再次登录该账号需重新输入密码</p>'
+        : '<p class="login-privacy"><span class="login-lock" aria-hidden="true">🔒</span>账号记录仅保存在这台电脑的浏览器中</p>',
+    ].join("");
+  }
+
+  function render() {
+    card.classList.toggle("is-loading", state.loading);
+    if (state.view === "first" || state.view === "add") {
+      card.innerHTML = formMarkup({
+        title: state.view === "add" ? "添加账号" : "欢迎回来",
+        lead: state.view === "add" ? "登录另一个账号，添加后可随时一键切换" : "登录后进入你的复盘空间",
+        hint: state.view === "add"
+          ? "添加后账号会保存在这台电脑，方便随时切换。"
+          : "密码连续输错 5 次将锁定 10 分钟。还没有账号？切换到「注册」创建。",
+        add: state.view === "add",
+        back: state.view === "add",
+      });
+    } else {
+      card.innerHTML = pickerMarkup();
+    }
+    bindCard();
+    if (mascots) mascots.sync();
+  }
+
+  function bindCard() {
+    card.querySelectorAll("[data-auth-mode]").forEach((button) => {
+      button.addEventListener("click", () => {
+        state.mode = button.dataset.authMode === "register" ? "register" : "login";
+        setError("");
+        render();
+      });
+    });
+    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;
+        } else if (action === "add") {
+          state.view = "add";
+          state.mode = "login";
+        } else if (action === "manage") {
+          state.view = "manage";
+        } else if (action === "cancel-forget") {
+          state.confirmingId = null;
+        }
+        setError("");
+        render();
+      });
+    });
+    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();
+        state.confirmingId = Number(button.dataset.confirmId);
+        render();
+      });
+    });
+    card.querySelectorAll("[data-forget-id]").forEach((button) => {
+      button.addEventListener("click", () => forgetAccount(Number(button.dataset.forgetId)));
+    });
+    const form = card.querySelector("#loginForm");
+    if (form) form.addEventListener("submit", submitCredentials);
+  }
+
+  async function loadAccounts() {
+    const payload = await api.request("/api/auth/accounts");
+    state.accounts = payload.accounts || [];
+    state.currentUserId = payload.current_user_id ?? null;
+    const params = new URLSearchParams(global.location.search);
+    if (params.get("mode") === "register") state.mode = "register";
+    if (params.get("notice")) setError(params.get("notice"));
+    if (state.accounts.length) state.view = "picker";
+    else state.view = "first";
+  }
+
+  async function submitCredentials(event) {
+    event.preventDefault();
+    const username = document.querySelector("#loginUsername").value.trim();
+    const password = document.querySelector("#loginPassword").value;
+    state.username = username;
+    state.password = password;
+    if (state.mode === "register" && password !== document.querySelector("#loginPasswordConfirm").value) {
+      setError("两次输入的密码不一致。");
+      render();
+      return;
+    }
+    state.loading = true;
+    setError("");
+    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();
+    }
+  }
+
+  async function switchAccount(userId) {
+    state.loading = true;
+    setError("");
+    render();
+    try {
+      await api.request("/api/auth/switch", "POST", { user_id: userId });
+      enterApp();
+    } catch (error) {
+      state.loading = false;
+      setError(error.message || "该账号需重新验证");
+      render();
+    }
+  }
+
+  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 });
+      state.accounts = state.accounts.filter((item) => Number(item.user_id) !== Number(userId));
+      state.confirmingId = null;
+      if (!state.accounts.length) state.view = "first";
+      setError("");
+      render();
+    } catch (error) {
+      setError(error.message || "移除失败");
+      render();
+    }
+  }
+
+  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);
+  });
+  applyTheme(preferredTheme(), false);
+
+  loadAccounts()
+    .then(render)
+    .catch((error) => {
+      setError(error.message || "无法连接本地服务");
+      state.view = "first";
+      render();
+    });
+})(window);

frontend/m/css/features.css

@@ -3174,3 +3174,458 @@
   border-top: 1px solid var(--border);
   transform: translateY(calc(-1 * var(--m-keyboard-inset, 0px)));
 }
+
+.m-sys-lead {
+  margin: 8px 0 12px;
+  font-size: var(--font-size-label);
+  color: var(--text-secondary);
+  line-height: 1.5;
+}
+
+.m-sys-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 8px;
+  margin: 0 0 12px;
+}
+
+.m-sys-grid div {
+  padding: 12px;
+  border-radius: 8px;
+  background: var(--surface-muted);
+}
+
+.m-sys-grid span {
+  display: block;
+  font-size: var(--font-size-label);
+  color: var(--text-tertiary);
+}
+
+.m-sys-grid strong {
+  display: block;
+  margin-top: 4px;
+  font-size: var(--font-size-body);
+  color: var(--text-primary);
+}
+
+.m-sys-home {
+  padding: 0 0 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.m-sys-body {
+  padding: 12px 12px 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.m-sys-home .m-card,
+.m-sys-body .m-card {
+  margin-left: 0;
+  margin-right: 0;
+}
+
+.m-sys-profile-card {
+  display: flex;
+  gap: 12px;
+  align-items: flex-start;
+  padding: 14px;
+}
+
+.m-sys-avatar {
+  flex: 0 0 auto;
+  width: 48px;
+  height: 48px;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--action-soft);
+  color: var(--action);
+  font-size: var(--font-size-page-title);
+  font-weight: 600;
+}
+
+.m-sys-profile-card strong {
+  display: block;
+  font-size: var(--font-size-card-title);
+  color: var(--text-primary);
+}
+
+.m-sys-profile-meta {
+  margin: 4px 0 8px;
+  font-size: var(--font-size-caption);
+  color: var(--text-secondary);
+}
+
+.m-sys-badges {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
+.m-sys-badge {
+  display: inline-flex;
+  align-items: center;
+  height: 22px;
+  padding: 0 8px;
+  border-radius: 999px;
+  font-size: var(--font-size-aux);
+  font-weight: 600;
+  background: var(--surface-muted);
+  color: var(--text-secondary);
+}
+
+.m-sys-badge--admin {
+  background: var(--action-soft);
+  color: var(--action);
+}
+
+.m-sys-badge--ok {
+  background: var(--market-down-soft);
+  color: var(--market-down);
+}
+
+.m-sys-group-title {
+  margin: 4px 0 0;
+  font-size: var(--font-size-caption);
+  font-weight: 600;
+  color: var(--text-tertiary);
+}
+
+.m-sys-list {
+  padding: 0;
+  overflow: hidden;
+}
+
+.m-sys-row {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px 12px;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  text-align: left;
+  cursor: pointer;
+  -webkit-tap-highlight-color: transparent;
+}
+
+.m-sys-row + .m-sys-row {
+  border-top: 1px solid var(--border);
+}
+
+.m-sys-row:active {
+  background: var(--surface-hover);
+}
+
+.m-sys-row-icon {
+  flex: 0 0 auto;
+  width: 36px;
+  height: 36px;
+  border-radius: 10px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--action-soft);
+  color: var(--action);
+}
+
+.m-sys-row--danger .m-sys-row-icon {
+  background: var(--market-up-soft);
+  color: var(--market-up);
+}
+
+.m-sys-row-body {
+  flex: 1;
+  min-width: 0;
+}
+
+.m-sys-row-body strong {
+  display: block;
+  font-size: var(--font-size-body);
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+.m-sys-row-body small {
+  display: block;
+  margin-top: 2px;
+  font-size: var(--font-size-caption);
+  color: var(--text-secondary);
+}
+
+.m-sys-row-chevron {
+  flex: 0 0 auto;
+  color: var(--text-tertiary);
+}
+
+.m-sys-foot {
+  margin: 8px 0 0;
+  text-align: center;
+  font-size: var(--font-size-caption);
+  color: var(--text-tertiary);
+}
+
+.m-sys-notice {
+  padding: 12px;
+  border-radius: 12px;
+  background: var(--surface-muted);
+}
+
+.m-sys-notice p {
+  margin: 0;
+  font-size: var(--font-size-label);
+  color: var(--text-secondary);
+  line-height: 1.55;
+}
+
+.m-sys-notice .m-sys-badges {
+  margin-top: 8px;
+}
+
+.m-sys-section {
+  padding: 12px;
+}
+
+.m-sys-section > strong,
+.m-sys-section-title {
+  display: block;
+  margin-bottom: 10px;
+  font-size: var(--font-size-card-title);
+  color: var(--text-primary);
+}
+
+.m-sys-hint {
+  margin: 8px 0 0;
+  font-size: var(--font-size-caption);
+  color: var(--text-tertiary);
+  line-height: 1.45;
+}
+
+.m-sys-status-list {
+  display: grid;
+  gap: 8px;
+}
+
+.m-sys-status-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  font-size: var(--font-size-body);
+  color: var(--text-primary);
+}
+
+.m-sys-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--text-tertiary);
+}
+
+.m-sys-dot--ok {
+  background: var(--market-down);
+}
+
+.m-sys-switch-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.m-sys-switch-row strong {
+  display: block;
+  font-size: var(--font-size-body);
+  margin-bottom: 0;
+}
+
+.m-btn-outline,
+.m-btn-outline-danger {
+  width: 100%;
+  height: 44px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  border-radius: 8px;
+  background: var(--surface);
+  font-size: var(--font-size-body);
+  font-weight: 600;
+  cursor: pointer;
+  -webkit-tap-highlight-color: transparent;
+}
+
+.m-btn-outline {
+  border: 1px solid var(--action);
+  color: var(--action);
+}
+
+.m-btn-outline:active {
+  background: var(--action-soft);
+}
+
+.m-btn-outline-danger {
+  border: 1px solid var(--market-up);
+  color: var(--market-up);
+}
+
+.m-btn-outline-danger:active {
+  background: var(--market-up-soft);
+}
+
+.m-btn-outline:disabled,
+.m-btn-outline-danger:disabled {
+  opacity: 0.45;
+  cursor: default;
+  pointer-events: none;
+}
+
+.m-sys-model-card .m-sys-badges,
+.m-sys-user-row .m-sys-badges {
+  margin-top: 6px;
+}
+
+.m-sys-model-card {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 8px;
+  width: 100%;
+  padding: 12px;
+  border: 0;
+  background: transparent;
+  text-align: left;
+  cursor: pointer;
+}
+
+.m-sys-model-card + .m-sys-model-card {
+  border-top: 1px solid var(--border);
+}
+
+.m-sys-model-card:active {
+  background: var(--surface-hover);
+}
+
+.m-sys-user-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 12px;
+}
+
+.m-sys-user-row + .m-sys-user-row {
+  border-top: 1px solid var(--border);
+}
+
+.m-sys-user-row .m-btn-outline {
+  width: auto;
+  height: 32px;
+  padding: 0 12px;
+  flex: 0 0 auto;
+}
+
+.m-sys-pair {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 8px;
+}
+
+.m-sheet-root.is-dialog .m-sheet {
+  display: none;
+}
+
+.m-dialog {
+  position: absolute;
+  left: 50%;
+  top: 42%;
+  width: calc(100% - 48px);
+  max-width: 320px;
+  transform: translate(-50%, -46%) scale(0.96);
+  border-radius: 12px;
+  background: var(--surface);
+  box-shadow: var(--elevation-float);
+  padding: 18px 16px 14px;
+  z-index: 3;
+  opacity: 0;
+  transition: opacity var(--motion-enter) var(--ease-enter),
+              transform var(--motion-enter) var(--ease-enter);
+}
+
+.m-sheet-root.is-open .m-dialog {
+  opacity: 1;
+  transform: translate(-50%, -50%) scale(1);
+}
+
+.m-dialog h2 {
+  margin: 0 0 8px;
+  font-size: var(--font-size-card-title);
+  color: var(--text-primary);
+  text-align: center;
+}
+
+.m-dialog p {
+  margin: 0 0 16px;
+  font-size: var(--font-size-label);
+  color: var(--text-secondary);
+  line-height: 1.5;
+  text-align: center;
+}
+
+.m-dialog-actions {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 8px;
+}
+
+.m-dialog-actions .m-btn-outline,
+.m-dialog-actions .m-btn-outline-danger,
+.m-dialog-actions .m-btn-primary {
+  height: 40px;
+}
+
+.m-sys-sheet-actions {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 8px;
+  margin-top: 12px;
+}
+
+.m-sys-test-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin: 8px 0 12px;
+}
+
+.m-sys-test-row .m-btn-outline {
+  width: auto;
+  flex: 0 0 auto;
+  height: 36px;
+  padding: 0 12px;
+}
+
+.m-sys-test-row [data-model-test-status] {
+  flex: 1;
+  font-size: var(--font-size-caption);
+  color: var(--text-secondary);
+}
+
+.m-sys-hero {
+  padding: 14px;
+}
+
+.m-sys-hero strong {
+  display: block;
+  font-size: var(--font-size-page-title);
+  margin-bottom: 6px;
+}
+
+.m-page[data-page^="system/"] .m-card {
+  margin-bottom: 0;
+}

frontend/m/css/shell.css

@@ -246,6 +246,29 @@ body {
   padding-top: 8px;
 }
 
+.m-auth-accounts {
+  display: grid;
+  gap: 8px;
+  margin-bottom: 16px;
+}
+
+.m-auth-account {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  min-height: 48px;
+  padding: 0 14px;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  background: var(--surface);
+  color: var(--text-primary);
+}
+
+.m-auth-account span {
+  color: var(--action);
+  font-size: var(--font-size-label);
+}
+
 .m-auth-brand {
   text-align: center;
   margin: 24px 0 20px;
@@ -313,7 +336,8 @@ body {
   color: var(--text-secondary);
 }
 
-.m-form-field input {
+.m-form-field input,
+.m-form-field select {
   height: 44px;
   padding: 0 12px;
   border: 1px solid var(--border-strong);
@@ -323,11 +347,20 @@ body {
   font-size: 14px;
 }
 
-.m-form-field input:focus {
+.m-form-field input:focus,
+.m-form-field select:focus {
   outline: none;
   border-color: var(--action);
 }
 
+.m-form-field input[type="checkbox"] {
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  border: none;
+  background: transparent;
+}
+
 .m-auth-error {
   margin: 0 0 12px;
   padding: 10px 12px;

frontend/m/index.html

@@ -15,7 +15,9 @@
       (() => {
         let theme = "light";
         try {
-          theme = localStorage.getItem("xiaobaiTheme") === "dark" ? "dark" : "light";
+          const stored = localStorage.getItem("xiaobaiTheme");
+          if (stored === "dark" || stored === "light") theme = stored;
+          else if (window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches) theme = "dark";
         } catch (_error) {
           theme = "light";
         }

frontend/m/js/boot.js

@@ -5,10 +5,15 @@
 
   function readTheme() {
     try {
-      return global.localStorage.getItem(THEME_KEY) === "dark" ? "dark" : "light";
+      const stored = global.localStorage.getItem(THEME_KEY);
+      if (stored === "dark" || stored === "light") return stored;
     } catch (_error) {
       return "light";
     }
+    if (global.matchMedia && global.matchMedia("(prefers-color-scheme: dark)").matches) {
+      return "dark";
+    }
+    return "light";
   }
 
   function applyTheme(theme) {

frontend/m/js/router.js

@@ -187,9 +187,9 @@
     const dark = document.getElementById("m-app").dataset.theme === "dark";
     const toggle = document.querySelector("[data-theme-toggle]");
     if (toggle) toggle.setAttribute("aria-checked", dark ? "true" : "false");
-    const rowIcon = document.querySelector(".m-theme-row-icon");
+    const rowIcon = document.querySelector(".m-theme-row-icon, [data-theme-row-icon]");
     if (rowIcon) rowIcon.innerHTML = icon(dark ? "moon" : "sun");
-    const rowBodySmall = document.querySelector(".m-theme-row-body small");
+    const rowBodySmall = document.querySelector(".m-theme-row-body small, [data-theme-row-label]");
     if (rowBodySmall) rowBodySmall.textContent = dark ? "当前：夜间模式" : "当前：日间模式";
   }
 
@@ -206,6 +206,10 @@
       replace(DEFAULT_HASH);
       return;
     }
+    if (key === "system" && global.MobilePages && typeof global.MobilePages.renderSystemHome === "function") {
+      global.MobilePages.renderSystemHome();
+      return;
+    }
     const items = visibleHubItems(hub);
     updateHeader({ title: hub.title, back: false });
     const section = key === "system" ? themeToggleSection() : "";
@@ -250,6 +254,7 @@
       '<h2>小白复盘</h2>',
       '<p>登录后进入你的复盘空间</p>',
       "</div>",
+      '<div class="m-auth-accounts" id="m-auth-accounts" hidden></div>',
       '<div class="m-auth-tabs">',
       '<button class="m-auth-tab active" type="button" data-auth-mode="login">登录</button>',
       '<button class="m-auth-tab" type="button" data-auth-mode="register">注册</button>',
@@ -265,6 +270,7 @@
     ].join("");
     authMode = "login";
     bindAuth();
+    loadMobileAccounts();
   }
 
   function setAuthMode(mode) {
@@ -287,6 +293,34 @@
     document.getElementById("m-auth-form").addEventListener("submit", submitAuth);
   }
 
+  async function loadMobileAccounts() {
+    const host = document.getElementById("m-auth-accounts");
+    if (!host || !global.MobileSession.listAccounts) return;
+    try {
+      const payload = await global.MobileSession.listAccounts();
+      const accounts = payload.accounts || [];
+      if (!accounts.length) return;
+      host.hidden = false;
+      host.innerHTML = accounts.map(function (account) {
+        return '<button class="m-auth-account" type="button" data-switch-id="' + account.user_id + '">' +
+          '<strong>' + escapeHtml(account.username) + '</strong>' +
+          '<span>直接进入</span></button>';
+      }).join("");
+      host.querySelectorAll("[data-switch-id]").forEach(function (button) {
+        button.addEventListener("click", async function () {
+          try {
+            await global.MobileSession.switchAccount(Number(button.dataset.switchId));
+            replace(DEFAULT_HASH);
+          } catch (error) {
+            showAuthError(document.getElementById("m-auth-error"), error.message || "该账号需重新验证");
+          }
+        });
+      });
+    } catch (_error) {
+      host.hidden = true;
+    }
+  }
+
   function showAuthError(element, message) {
     element.textContent = message;
     element.classList.remove("m-motion-fade-in");

frontend/m/js/session.js

@@ -47,5 +47,30 @@
     return Boolean(state.user && state.user.role === "admin");
   }
 
-  global.MobileSession = { state: state, me: me, login: login, register: register, logout: logout, isAdmin: isAdmin };
+  async function listAccounts() {
+    return global.MobileAPI.request("/api/auth/accounts");
+  }
+
+  async function switchAccount(userId) {
+    const payload = await global.MobileAPI.request("/api/auth/switch", "POST", {
+      user_id: userId
+    });
+    return applySession(payload);
+  }
+
+  async function forgetAccount(userId) {
+    await global.MobileAPI.request("/api/auth/forget", "POST", { user_id: userId });
+  }
+
+  global.MobileSession = {
+    state: state,
+    me: me,
+    login: login,
+    register: register,
+    logout: logout,
+    listAccounts: listAccounts,
+    switchAccount: switchAccount,
+    forgetAccount: forgetAccount,
+    isAdmin: isAdmin
+  };
 })(window);

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/sentiment/foundation.css

@@ -1011,9 +1011,9 @@
 
   border-radius: 6px;
 
-  background: var(--r2-ink);
+  background: var(--sentiment-tooltip-bg);
 
-  color: var(--text-inverse);
+  color: var(--sentiment-tooltip-fg);
 
   font-size: 11px;
 
@@ -1021,6 +1021,8 @@
 }
 
 .sentiment-chart-tooltip b {
+  color: inherit;
+
   font-weight: 700;
 }
 
@@ -1568,10 +1570,6 @@
   #sentimentCycleView .sentiment-component-item {
     padding: 4px 0px;
   }
-
-  #sentimentCycleView .sentiment-component-item small {
-    display: none;
-  }
 }
 
 @media (min-width: 768px) {
@@ -1764,3 +1762,72 @@
     grid-template-columns: repeat(2, minmax(0, 1fr));
   }
 }
+
+@media (min-width: 1024px) {
+  #sentimentCycleView .redesigned-emotion-grid {
+    align-items: stretch;
+
+    height: var(--sentiment-analysis-height);
+
+    max-height: var(--sentiment-analysis-height);
+
+    overflow: hidden;
+  }
+
+  .redesigned-sentiment-view .sentiment-analysis-main,
+  .redesigned-sentiment-view .sentiment-analysis-rail {
+    align-self: stretch;
+
+    height: 100%;
+
+    min-height: 0px;
+  }
+
+  .redesigned-sentiment-view .sentiment-trend-panel {
+    display: flex;
+
+    flex: 1 1 auto;
+
+    flex-direction: column;
+
+    min-height: 0px;
+  }
+
+  .redesigned-sentiment-view .sentiment-chart-shell {
+    flex: 1 1 auto;
+
+    height: auto;
+
+    min-height: 0px;
+  }
+
+  .redesigned-sentiment-view .sentiment-chart-shell canvas {
+    height: 100%;
+  }
+
+  .redesigned-sentiment-view .sentiment-cycle-summary {
+    flex: 0 0 auto;
+  }
+
+  .redesigned-sentiment-view .sentiment-components-panel {
+    display: flex;
+
+    flex: 1 1 auto;
+
+    flex-direction: column;
+
+    min-height: 0px;
+  }
+
+  .redesigned-sentiment-view .sentiment-component-list {
+    display: flex;
+
+    flex: 1 1 auto;
+
+    flex-direction: column;
+
+    justify-content: space-evenly;
+
+    min-height: 0px;
+  }
+}

frontend/pages/sentiment/page.js

@@ -1,10 +1,39 @@
 let sentimentChartAnimationFrame = null;
+let sentimentChartResizeObserver = null;
+let sentimentChartLastSize = "";
 
 window.XiaobaiPageModules.register("sentiment", ["sentimentCycleView"], {
   bind: bindSentimentEvents,
   enter: ["loadSentiment"],
 });
 
+function sentimentChartSizeKey(target) {
+  if (!target) return "";
+  const rect = target.getBoundingClientRect();
+  return `${Math.round(rect.width)}x${Math.round(rect.height)}x${window.devicePixelRatio || 1}`;
+}
+
+function observeSentimentTrendChart() {
+  const shell = document.querySelector("#sentimentCycleView .sentiment-chart-shell");
+  if (!shell) return;
+  if (!sentimentChartResizeObserver) {
+    sentimentChartResizeObserver = new ResizeObserver(() => {
+      if (sentimentChartAnimationFrame) return;
+      if (state.activeView !== "sentimentCycleView") return;
+      const rows = state.sentimentHistory?.rows;
+      if (!rows?.length) return;
+      const current = document.querySelector("#sentimentCycleView .sentiment-chart-shell");
+      const nextKey = sentimentChartSizeKey(current);
+      if (!nextKey || nextKey === sentimentChartLastSize) return;
+      drawSentimentTrendChart(rows, 1);
+    });
+  } else {
+    sentimentChartResizeObserver.disconnect();
+  }
+  sentimentChartLastSize = sentimentChartSizeKey(shell);
+  sentimentChartResizeObserver.observe(shell);
+}
+
 async function loadSentimentHistory(force = false) {
   if (!state.dashboard || state.sentimentLoading) return;
   const key = `${elements.tradeDate.value}:${state.sentimentRange}`;
@@ -126,6 +155,7 @@ function animateSentimentTrendChart(rows) {
   if (sentimentChartAnimationFrame) cancelAnimationFrame(sentimentChartAnimationFrame);
   if (!motionEnabled()) {
     drawSentimentTrendChart(rows, 1);
+    observeSentimentTrendChart();
     return;
   }
   const startedAt = performance.now();
@@ -135,7 +165,10 @@ function animateSentimentTrendChart(rows) {
     const progress = 1 - (1 - rawProgress) ** 3;
     drawSentimentTrendChart(rows, progress);
     if (rawProgress < 1) sentimentChartAnimationFrame = requestAnimationFrame(frame);
-    else sentimentChartAnimationFrame = null;
+    else {
+      sentimentChartAnimationFrame = null;
+      observeSentimentTrendChart();
+    }
   };
   sentimentChartAnimationFrame = requestAnimationFrame(frame);
 }
@@ -144,9 +177,9 @@ function drawSentimentTrendChart(rows, progress = 1) {
   const canvas = document.querySelector("#sentimentTrendChart");
   if (!canvas || !rows.length || state.activeView !== "sentimentCycleView") return;
   const rect = canvas.getBoundingClientRect();
-  if (!rect.width) return;
+  if (rect.width < 8 || rect.height < 8) return;
-  const width = Math.max(320, rect.width);
+  const width = rect.width;
-  const height = Math.max(220, rect.height);
+  const height = rect.height;
   const ratio = window.devicePixelRatio || 1;
   canvas.width = Math.round(width * ratio);
   canvas.height = Math.round(height * ratio);
@@ -258,6 +291,7 @@ function drawSentimentTrendChart(rows, progress = 1) {
     const dateText = displayCompactDate(row.trade_date).slice(5);
     context.fillText(dateText, x(index), height - padding.bottom + 10);
   });
+  sentimentChartLastSize = sentimentChartSizeKey(canvas.closest(".sentiment-chart-shell"));
 }
 
 function bindSentimentChartTooltip(rows) {

frontend/shared/dashboard.js

@@ -40,17 +40,71 @@ async function loadDashboard(force = false, background = false, showOverlay = tr
 async function startAdminRefresh() {
   const buttons = [document.querySelector("#syncButton"), document.querySelector("#adminRefreshButton")].filter(Boolean);
   buttons.forEach((button) => { button.disabled = true; });
+  const requestedDate = elements.tradeDate.value;
+  setAdminRefreshStatus("running", `正在刷新 ${requestedDate} 的行情，请稍候…`, "loader-circle");
   try {
-    const payload = await apiRequest("/api/admin/refresh", "POST", { trade_date: elements.tradeDate.value });
+    const payload = await apiRequest("/api/admin/refresh", "POST", { trade_date: requestedDate });
-    showToast(payload.message || "后台刷新已提交");
+    if (!payload.started || !payload.job_key) {
-    setStatus("后台刷新运行中，当前页面保持不变");
+      setAdminRefreshStatus("warning", "已有刷新任务正在运行，请稍后再试。", "clock-3");
+      showToast(payload.message || "已有后台刷新任务正在运行");
+      return;
+    }
+    setStatus(`正在刷新 ${requestedDate} 的行情`);
+    const job = await waitForAdminRefresh(payload.job_key);
+    if (job.status === "failed") {
+      const reason = job.message || job.error_code || "数据源未返回结果";
+      setAdminRefreshStatus("failure", `刷新失败：${reason}`, "circle-x");
+      setStatus("后台刷新失败");
+      showToast("后台刷新失败");
+      return;
+    }
+    const query = new URLSearchParams({ trade_date: requestedDate });
+    const dashboard = await apiRequest(`/api/dashboard?${query}`);
+    applyDashboard(dashboard);
+    const meta = dashboard.meta || {};
+    const actualDate = String(meta.trade_date || "").slice(0, 10);
+    const requestedCompact = requestedDate.replaceAll("-", "");
+    const actualCompact = actualDate.replaceAll("-", "");
+    const updated = formatTimestamp(meta.updated_at);
+    if (actualCompact !== requestedCompact || meta.carried_forward) {
+      const reason = meta.notice ? `；${meta.notice}` : "";
+      setAdminRefreshStatus("warning", `刷新已完成，但没有获取到 ${requestedDate} 的最新行情；当前仍是 ${actualDate || "未知日期"}${reason}`, "triangle-alert");
+      showToast("刷新完成，但未获取到所选日期的最新行情");
+    } else if (meta.notice) {
+      setAdminRefreshStatus("warning", `已刷新到 ${actualDate}（${updated}），但数据源提示：${meta.notice}`, "triangle-alert");
+      showToast(`已刷新到 ${actualDate}，请留意数据源提示`);
+    } else {
+      setAdminRefreshStatus("success", `刷新成功：已获取 ${actualDate} 的最新行情，更新时间 ${updated}`, "circle-check");
+      showToast(`刷新成功：已获取 ${actualDate} 的最新行情`);
+    }
   } catch (error) {
-    showToast(error.message || "后台刷新启动失败");
+    const message = error.message || "后台刷新失败";
+    setAdminRefreshStatus("failure", `刷新失败：${message}`, "circle-x");
+    setStatus("后台刷新失败");
+    showToast(message);
   } finally {
     buttons.forEach((button) => { button.disabled = false; });
   }
 }
 
+function setAdminRefreshStatus(tone, message, icon = "circle-dot") {
+  const status = document.querySelector("#adminRefreshStatus");
+  if (!status) return;
+  status.dataset.tone = tone;
+  status.innerHTML = `<i data-lucide="${icon}"></i><span>${escapeHtml(message)}</span>`;
+  refreshIcons();
+}
+
+async function waitForAdminRefresh(jobKey) {
+  for (let attempt = 0; attempt < 120; attempt += 1) {
+    const payload = await apiRequest("/api/admin/settings");
+    const job = (payload.data?.jobs || []).find((item) => item.idempotency_key === jobKey);
+    if (job && ["success", "failed"].includes(job.status)) return job;
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+  }
+  throw new Error("刷新等待超时，请稍后重试");
+}
+
 function applyDashboard(payload, background = false) {
   state.dashboard = payload;
   const selectedDate = payload.meta.requested_date || payload.meta.trade_date;

frontend/shared/session.js

@@ -53,12 +53,10 @@ async function applyAuthenticatedSession(session) {
 function showAuthGate(message = "") {
   state.user = null;
   state.csrfToken = "";
-  const gate = document.querySelector("#authGate");
+  const params = new URLSearchParams();
-  gate.hidden = false;
+  if (message) params.set("notice", message);
-  const errorElement = document.querySelector("#authError");
+  const query = params.toString();
-  errorElement.textContent = message;
+  window.location.replace("/login/" + (query ? `?${query}` : ""));
-  errorElement.hidden = !message;
-  document.querySelector("#authUsername").focus();
 }
 
 async function logoutAccount() {
@@ -197,16 +195,14 @@ async function changeAccountPassword(event) {
 }
 
 async function switchAccount() {
-  const button = document.querySelector("#switchAccountMenuButton");
-  button.disabled = true;
   toggleAccountDropdown(false);
-  try {
+  const params = new URLSearchParams();
-    await apiRequest("/api/auth/logout", "POST", {});
+  const next = `${window.location.pathname}${window.location.search}${window.location.hash}`;
-    window.location.reload();
+  if (next.startsWith("/") && !next.startsWith("//") && next !== "/login" && !next.startsWith("/login/") && !next.startsWith("/login?")) {
-  } catch (error) {
+    params.set("next", next);
-    showToast(error.message || "切换账号失败");
-    button.disabled = false;
   }
+  const query = params.toString();
+  window.location.assign("/login/" + (query ? `?${query}` : ""));
 }
 
 

frontend/shared/tokens.css

@@ -146,6 +146,32 @@
   --shadow-float: var(--elevation-float);
   --duration-fast: 150ms;
   --duration-normal: 220ms;
+  --login-brand-gradient: linear-gradient(165deg, #0c1e4a, #16307c, #2153cc);
+  --login-brand-share: 34%;
+  --login-brand-min: 420px;
+  --login-brand-cap: 560px;
+  --login-brand-wide-share: 29.2%;
+  --login-brand-pad: 36px 40px 24px;
+  --login-brand-mark-size: 44px;
+  --login-brand-name-size: 16px;
+  --login-hero-size: 28px;
+  --login-card-width: 408px;
+  --login-card-pad: 32px;
+  --login-card-title-size: 22px;
+  --login-account-row-min: 72px;
+  --login-account-avatar: 40px;
+  --login-submit-height: 40px;
+  --login-stat-chip-bg: rgba(8, 12, 24, 0.48);
+  --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;
@@ -210,6 +236,9 @@
   --pool-table-max-height: calc(var(--content-height) - var(--topbar-height) - var(--page-pad-y) - var(--page-pad-y) - var(--card-gap));
   --sentiment-history-max-height: 510px;
   --sentiment-history-min-height: 220px;
+  --sentiment-analysis-height: 600px;
+  --sentiment-tooltip-bg: var(--text-primary);
+  --sentiment-tooltip-fg: var(--text-inverse);
   --primary-share: 1.45fr;
   --secondary-share: .75fr;
   --mobile-nav-height: 64px;
@@ -505,10 +534,17 @@
   --chart-repair: #e2ad58;
   --chart-ma-10: #d39a45;
   --chart-ma-20: #9aa5af;
+  --sentiment-tooltip-bg: #26293e;
+  --sentiment-tooltip-fg: #e8eaed;
   --on-action: #101418;
   --warning-line: #6d5a38;
   --warning-line-strong: #66502d;
   --control-shadow: 0 1px 3px rgba(0, 0, 0, .3);
+  --login-brand-gradient: linear-gradient(165deg, #080c18, #0e1730, #14224a);
+  --login-stat-chip-bg: rgba(6, 8, 16, 0.58);
+  --login-candle-up: #f06d73;
+  --login-candle-down: #43bc8a;
+  --login-trend-line: rgba(232, 236, 244, 0.9);
   --dialog-backdrop: var(--backdrop);
   --ladder-level-1: #2d2426;
   --ladder-level-2: #2b2822;

tests/e2e/app-shell.spec.js

@@ -47,6 +47,72 @@ function session(role = "admin", subscribed = true) {
   };
 }
 
+function sentimentHistoryPayload(days = 20) {
+  const phases = ["冰点", "修复", "发酵", "高潮", "分化", "退潮"];
+  const rows = Array.from({ length: days }, (_, index) => {
+    const score = 28 + ((index * 7) % 55);
+    return {
+      trade_date: `2026-08-${String(index + 1).padStart(2, "0")}`,
+      score,
+      label: "情绪观察",
+      phase: phases[index % phases.length],
+      direction: index % 2 ? "升温" : "降温",
+      day_change: index % 2 ? 3.2 : -2.1,
+      seal_rate: 71.5,
+      limit_up_count: 40 + index,
+      first_board_count: 18,
+      second_board_count: 8,
+      three_plus_count: 4,
+      max_height: 5,
+      broken_count: 12,
+      limit_down_count: 3,
+      previous_limit_count: 38,
+      previous_positive_count: 22,
+      previous_positive_rate: 57.9,
+      average_previous_change: 1.2,
+      normalization: "固定锚点",
+      components: {
+        breadth: { label: "市场宽度", score: 55.8, weight: 20, summary: "红盘家数回升" },
+        limit: { label: "涨停连板", score: 79.6, weight: 25, summary: "连板生态改善" },
+        profit: { label: "赚钱效应", score: 67.0, weight: 30, summary: "昨日反馈尚可" },
+        ladder: { label: "涨幅结构", score: 81.5, weight: 15, summary: "高度仍在扩张" },
+        amount: { label: "成交活跃度", score: 46.1, weight: 10, summary: "量能略低于均值" },
+      },
+    };
+  });
+  return { available_days: days, rows };
+}
+
+async function renderSentimentFixture(page, days = 20) {
+  await page.evaluate((payload) => {
+    state.sentimentHistory = payload;
+    renderSentimentHistory();
+  }, sentimentHistoryPayload(days));
+  await page.locator('[data-view="sentimentCycleView"]').first().click();
+  await page.waitForTimeout(900);
+}
+
+function readSentimentLayout() {
+  const analysis = document.querySelector(".redesigned-emotion-grid").getBoundingClientRect();
+  const trend = document.querySelector(".sentiment-trend-panel").getBoundingClientRect();
+  const summary = document.querySelector(".sentiment-cycle-summary").getBoundingClientRect();
+  const components = document.querySelector(".sentiment-components-panel").getBoundingClientRect();
+  const chart = document.querySelector(".sentiment-chart-shell").getBoundingClientRect();
+  const detail = document.querySelector(".sentiment-detail-toolbar").getBoundingClientRect();
+  const table = document.querySelector(".sentiment-history-frame").getBoundingClientRect();
+  const small = document.querySelector(".sentiment-component-item small");
+  return {
+    topDelta: Math.abs(trend.top - summary.top),
+    bottomDelta: Math.abs(trend.bottom - components.bottom),
+    analysisHeight: analysis.height,
+    chartHeight: chart.height,
+    detailAfterAnalysis: detail.top > Math.max(trend.bottom, components.bottom) - 0.5,
+    tableVisible: table.top < window.innerHeight && table.bottom > detail.bottom,
+    smallVisible: small ? getComputedStyle(small).display !== "none" : false,
+    overflowX: document.documentElement.scrollWidth > document.documentElement.clientWidth + 1,
+  };
+}
+
 function waitForApplicationRuntime(page) {
   return expect(page.locator("body")).toHaveAttribute("data-runtime-ready", "true");
 }
@@ -721,6 +787,7 @@ test("collapsed overview and sentiment layout keep a single current reading", as
   await expect(page.locator(".sentiment-stage-guide, [data-sentiment-stage]")).toHaveCount(0);
   await expect(page.locator("#sentimentPhaseAdvice")).toHaveText("情绪指标继续走弱。");
   const alignment = await page.evaluate(() => {
+    const analysis = document.querySelector(".redesigned-emotion-grid").getBoundingClientRect();
     const components = document.querySelector(".sentiment-components-panel").getBoundingClientRect();
     const trend = document.querySelector(".sentiment-trend-panel").getBoundingClientRect();
     const summary = document.querySelector(".sentiment-cycle-summary").getBoundingClientRect();
@@ -732,6 +799,8 @@ test("collapsed overview and sentiment layout keep a single current reading", as
     const statusStyle = getComputedStyle(document.querySelector(".sentiment-block .sentiment-text"));
     return {
       columnsAligned: Math.abs(trend.top - summary.top) < 1,
+      bottomsAligned: Math.abs(trend.bottom - components.bottom) < 1,
+      analysisHeight: analysis.height,
       railAligned: Math.abs(summary.x - components.x) < 1 && Math.abs(summary.width - components.width) < 1 && components.top > summary.bottom,
       detailAfterAnalysis: detail.top > Math.max(trend.bottom, components.bottom),
       chartHeight: chart.height,
@@ -743,6 +812,8 @@ test("collapsed overview and sentiment layout keep a single current reading", as
     };
   });
   expect(alignment.columnsAligned).toBe(true);
+  expect(alignment.bottomsAligned).toBe(true);
+  expect(Math.abs(alignment.analysisHeight - 600)).toBeLessThanOrEqual(1);
   expect(alignment.railAligned).toBe(true);
   expect(alignment.detailAfterAnalysis).toBe(true);
   expect(alignment.chartHeight).toBeGreaterThanOrEqual(340);
@@ -780,6 +851,68 @@ test("collapsed overview and sentiment layout keep a single current reading", as
   }
 });
 
+test("sentiment cycle keeps 600px equal-height layout across zoom viewports", async ({ page }, testInfo) => {
+  const shotDir = testInfo.outputPath("hel-221-shots");
+  await mockApplication(page, session("user", true));
+  const viewports = [
+    { name: "zoom-100", width: 2560, height: 1440 },
+    { name: "zoom-110", width: 2327, height: 1309 },
+    { name: "zoom-125", width: 2048, height: 1152 },
+  ];
+
+  for (const viewport of viewports) {
+    await page.setViewportSize({ width: viewport.width, height: viewport.height });
+    await page.goto("/index.html");
+    await renderSentimentFixture(page, 20);
+    const layout = await page.evaluate(readSentimentLayout);
+    expect(layout.topDelta, viewport.name).toBeLessThanOrEqual(1);
+    expect(layout.bottomDelta, viewport.name).toBeLessThanOrEqual(1);
+    expect(Math.abs(layout.analysisHeight - 600), viewport.name).toBeLessThanOrEqual(1);
+    expect(layout.chartHeight, viewport.name).toBeGreaterThanOrEqual(450);
+    expect(layout.detailAfterAnalysis, viewport.name).toBe(true);
+    expect(layout.tableVisible, viewport.name).toBe(true);
+    expect(layout.smallVisible, viewport.name).toBe(true);
+    expect(layout.overflowX, viewport.name).toBe(false);
+    await page.screenshot({
+      path: `${shotDir}/day-${viewport.name}.png`,
+      fullPage: true,
+    });
+  }
+
+  await page.setViewportSize({ width: 2560, height: 1440 });
+  await page.locator("#themeToggle").click();
+  await expect(page.locator("html")).toHaveAttribute("data-theme", "dark");
+  await page.waitForTimeout(200);
+  const nightLayout = await page.evaluate(readSentimentLayout);
+  expect(nightLayout.topDelta).toBeLessThanOrEqual(1);
+  expect(nightLayout.bottomDelta).toBeLessThanOrEqual(1);
+  expect(Math.abs(nightLayout.analysisHeight - 600)).toBeLessThanOrEqual(1);
+  await page.locator("#sentimentTrendChart").hover({ position: { x: 280, y: 120 } });
+  const tooltip = page.locator("#sentimentChartTooltip");
+  await expect(tooltip).toBeVisible();
+  await expect(tooltip).toContainText("温度");
+  const tooltipStyle = await tooltip.evaluate((node) => {
+    const style = getComputedStyle(node);
+    const bold = getComputedStyle(node.querySelector("b") || node);
+    return { background: style.backgroundColor, color: style.color, bold: bold.color };
+  });
+  expect(tooltipStyle.background).toBe("rgb(38, 41, 62)");
+  expect(tooltipStyle.color).toBe("rgb(232, 234, 237)");
+  expect(tooltipStyle.bold).toBe("rgb(232, 234, 237)");
+  await page.screenshot({ path: `${shotDir}/night-zoom-100.png`, fullPage: true });
+
+  await page.locator("#themeToggle").click();
+  await expect(page.locator("html")).toHaveAttribute("data-theme", "light");
+  await page.locator("#sentimentTrendChart").hover({ position: { x: 280, y: 120 } });
+  await expect(tooltip).toBeVisible();
+  const lightTooltip = await tooltip.evaluate((node) => {
+    const style = getComputedStyle(node);
+    return { background: style.backgroundColor, color: style.color };
+  });
+  expect(lightTooltip.background).toBe("rgb(31, 35, 41)");
+  expect(lightTooltip.color).toBe("rgb(255, 255, 255)");
+});
+
 test("limit-up pool separates stock identity and restores the reason column", async ({ page }) => {
   await mockApplication(page, session("user", true));
   await page.goto("/index.html");

tests/e2e/login-portal.spec.js

@@ -0,0 +1,556 @@
+const { test, expect } = require("@playwright/test");
+const fs = require("fs");
+const path = require("path");
+
+const SHOT_DIR = path.resolve(__dirname, "../../../verify-shots");
+fs.mkdirSync(SHOT_DIR, { recursive: true });
+
+function loginPayload(user) {
+  return {
+    ok: true,
+    authenticated: true,
+    csrf_token: "portal-csrf",
+    user,
+  };
+}
+
+async function mockLoginPortal(page, options = {}) {
+  const accounts = options.accounts || [];
+  let currentUserId = options.currentUserId ?? null;
+  await page.route("**/api/**", async (route) => {
+    const url = new URL(route.request().url());
+    const method = route.request().method();
+    if (url.pathname === "/api/auth/accounts") {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ ok: true, accounts, current_user_id: currentUserId }),
+      });
+      return;
+    }
+    if (url.pathname === "/api/auth/switch" && method === "POST") {
+      const body = route.request().postDataJSON() || {};
+      const account = accounts.find((item) => Number(item.user_id) === Number(body.user_id));
+      if (!account || options.switchFails) {
+        await route.fulfill({
+          status: 401,
+          contentType: "application/json",
+          body: JSON.stringify({ error: "该账号需重新验证" }),
+        });
+        return;
+      }
+      currentUserId = account.user_id;
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify(loginPayload(account)),
+      });
+      return;
+    }
+    if (url.pathname === "/api/auth/forget" && method === "POST") {
+      const body = route.request().postDataJSON() || {};
+      const index = accounts.findIndex((item) => Number(item.user_id) === Number(body.user_id));
+      if (index >= 0) accounts.splice(index, 1);
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ ok: true }),
+      });
+      return;
+    }
+    if ((url.pathname === "/api/auth/login" || url.pathname === "/api/auth/register") && method === "POST") {
+      if (options.loginDelay) await new Promise((resolve) => setTimeout(resolve, options.loginDelay));
+      if (options.loginFails) {
+        await route.fulfill({
+          status: 401,
+          contentType: "application/json",
+          body: JSON.stringify({ error: "账号名或密码不正确，请重新输入。" }),
+        });
+        return;
+      }
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify(loginPayload({
+          id: 9,
+          username: "new_user",
+          role: "user",
+          membership: { active: false, subscribed: false, is_admin: false },
+        })),
+      });
+      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,
+          csrf_token: "portal-csrf",
+          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;
+    }
+    await route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify({ ok: true }),
+    });
+  });
+}
+
+const SAVED_ACCOUNTS = [
+  {
+    user_id: 1,
+    username: "alpha_user",
+    role: "admin",
+    membership: { active: true, subscribed: true, is_admin: true },
+    last_used_at: "2026-08-29T01:00:00+00:00",
+  },
+  {
+    user_id: 2,
+    username: "beta_user",
+    role: "user",
+    membership: { active: false, subscribed: false, is_admin: false },
+    last_used_at: "2026-08-28T01:00:00+00:00",
+  },
+];
+
+test("first-time login portal asks for a password and hides environment copy", async ({ page }) => {
+  await mockLoginPortal(page, { accounts: [] });
+  await page.goto("/login/");
+  await expect(page.locator(".login-card-title")).toHaveText("欢迎回来");
+  await expect(page.locator("#loginUsername")).toBeVisible();
+  await expect(page.locator(".login-submit")).toHaveText("登录");
+  await expect(page.locator("body")).not.toContainText("内网个人版");
+  await expect(page.locator("body")).not.toContainText("192.168.200.11");
+});
+
+test("saved accounts can switch directly and show a re-auth message on failure", async ({ page }) => {
+  await mockLoginPortal(page, { accounts: SAVED_ACCOUNTS.map((item) => ({ ...item })) });
+  await page.goto("/login/");
+  await expect(page.locator(".login-card-title")).toHaveText("选择账号");
+  await expect(page.locator(".login-account-row")).toHaveCount(2);
+  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("failed account switch stays on the portal with the original copy", async ({ page }) => {
+  await mockLoginPortal(page, {
+    accounts: SAVED_ACCOUNTS.map((item) => ({ ...item })),
+    switchFails: true,
+  });
+  await page.goto("/login/");
+  await page.locator('[data-switch-id="2"]').click();
+  await expect(page.locator(".login-error")).toHaveText("该账号需重新验证");
+  await expect(page).toHaveURL(/\/login\/?/);
+});
+
+test("managing accounts removes a local record after inline confirmation", async ({ page }) => {
+  await mockLoginPortal(page, { accounts: SAVED_ACCOUNTS.map((item) => ({ ...item })) });
+  await page.goto("/login/");
+  await page.locator('[data-login-action="manage"]').click();
+  await expect(page.locator(".login-card-title")).toHaveText("管理账号记录");
+  await page.locator('[data-confirm-id="2"]').click();
+  await expect(page.locator(".login-confirm-copy")).toContainText("beta_user");
+  await page.locator('[data-forget-id="2"]').click();
+  await expect(page.locator(".login-account-row")).toHaveCount(1);
+  await expect(page.locator(".login-account-row")).toContainText("alpha_user");
+});
+
+async function assertConfirmedSkeleton(page, { width, height }) {
+  await expect(page.locator(".login-brand-title")).toHaveText("看懂情绪周期，把复盘变成下一次的先手。");
+  await expect(page.locator(".login-brand-header")).toBeVisible();
+  await expect(page.locator(".login-brand-chart")).toBeVisible();
+  await expect(page.locator(".login-brand-stats")).toBeVisible();
+  await expect(page.locator(".login-brand-kicker")).toHaveText("收盘之后 · 复盘开始");
+  const brand = await page.locator(".login-brand").boundingBox();
+  const header = await page.locator(".login-brand-header").boundingBox();
+  const mark = await page.locator(".login-brand-mark").boundingBox();
+  const name = await page.locator(".login-brand-name").boundingBox();
+  const title = await page.locator(".login-brand-title").boundingBox();
+  const stats = await page.locator(".login-brand-stats").boundingBox();
+  const chart = await page.locator(".login-brand-chart").boundingBox();
+  const card = await page.locator(".login-card").boundingBox();
+  expect(brand).toBeTruthy();
+  expect(header.y - brand.y).toBeLessThan(48);
+  expect(Math.abs(mark.y - name.y)).toBeLessThan(16);
+  expect(title.y).toBeGreaterThan(height * 0.28);
+  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);
+  } else {
+    expect(brand.width).toBeGreaterThan(560);
+  }
+}
+
+async function openPortal(page, { theme, width, height, accounts, currentUserId, loginFails, loginDelay }) {
+  await page.addInitScript((nextTheme) => {
+    localStorage.setItem("xiaobaiTheme", nextTheme);
+  }, theme);
+  await page.setViewportSize({ width, height });
+  await mockLoginPortal(page, { accounts, currentUserId, loginFails, loginDelay });
+  await page.goto("/login/");
+}
+
+for (const theme of ["light", "dark"]) {
+  for (const [width, height] of [[1440, 900], [1920, 1080]]) {
+    test(`confirmed skeleton ${theme} ${width}x${height}`, async ({ page }) => {
+      await openPortal(page, { theme, width, height, accounts: [] });
+      await assertConfirmedSkeleton(page, { width, height });
+      await expect(page.locator("#loginThemeToggle")).toHaveText(theme === "dark" ? "☀ 日间" : "🌙 夜间");
+      await page.screenshot({ path: path.join(SHOT_DIR, `first-${theme}-${width}.png`), fullPage: true });
+    });
+  }
+}
+
+test("ultrawide keeps the left brand from collapsing into a strip", async ({ page }) => {
+  await openPortal(page, { theme: "dark", width: 2560, height: 1080, accounts: [] });
+  await assertConfirmedSkeleton(page, { width: 2560, height: 1080 });
+});
+
+test("picker add remove error and loading share the same desktop skeleton", async ({ page }) => {
+  const accounts = SAVED_ACCOUNTS.map((item) => ({ ...item }));
+  await openPortal(page, {
+    theme: "dark",
+    width: 1440,
+    height: 900,
+    accounts,
+    currentUserId: 1,
+  });
+  await assertConfirmedSkeleton(page, { width: 1440, height: 900 });
+  await expect(page.locator(".login-card-title")).toHaveText("选择账号");
+  await expect(page.locator(".login-avatar")).toHaveCount(2);
+  await expect(page.locator(".login-add")).toBeVisible();
+  await page.screenshot({ path: path.join(SHOT_DIR, "picker-dark-1440.png"), fullPage: true });
+
+  await page.locator('[data-login-action="add"]').click();
+  await expect(page.locator(".login-card-title")).toHaveText("添加账号");
+  await assertConfirmedSkeleton(page, { width: 1440, height: 900 });
+  await page.screenshot({ path: path.join(SHOT_DIR, "add-dark-1440.png"), fullPage: true });
+
+  await page.locator('[data-login-action="picker"]').click();
+  await page.locator('[data-login-action="manage"]').click();
+  await expect(page.locator(".login-card-title")).toHaveText("管理账号记录");
+  await page.locator('[data-confirm-id="2"]').click();
+  await expect(page.locator(".login-confirm-copy")).toContainText("beta_user");
+  await page.screenshot({ path: path.join(SHOT_DIR, "remove-dark-1440.png"), fullPage: true });
+});
+
+test("login failure and loading keep the confirmed first-login skeleton", async ({ page }) => {
+  await openPortal(page, {
+    theme: "light",
+    width: 1440,
+    height: 900,
+    accounts: [],
+    loginFails: true,
+  });
+  await page.locator("#loginUsername").fill("baiqizhi");
+  await page.locator("#loginPassword").fill("wrong-password");
+  await page.locator(".login-submit").click();
+  await expect(page.locator(".login-error")).toContainText("账号名或密码不正确");
+  await expect(page.locator("#loginPassword")).toHaveClass(/is-invalid/);
+  await assertConfirmedSkeleton(page, { width: 1440, height: 900 });
+  await page.screenshot({ path: path.join(SHOT_DIR, "error-light-1440.png"), fullPage: true });
+});
+
+test("loading button appears on the confirmed first-login skeleton", async ({ page }) => {
+  await openPortal(page, {
+    theme: "dark",
+    width: 1440,
+    height: 900,
+    accounts: [],
+    loginDelay: 2500,
+  });
+  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(".login-submit")).toContainText("正在登录...");
+  await expect(page.locator(".login-spinner")).toBeVisible();
+  await assertConfirmedSkeleton(page, { width: 1440, height: 900 });
+  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/e2e/mobile-app.spec.js

@@ -1,7 +1,7 @@
 const { test, expect } = require("@playwright/test");
 
-// 手机端（/m/）全页面回归：P5 收官打磨。
+// 手机端（/m/）全页面回归：P5 收官打磨 + HEL-233 系统管理恢复。
-// 覆盖：登录、四个入口图标页、行情 12 页、工具 3 页、复盘 5 页、复盘助手，
+// 覆盖：登录、四个入口图标页、行情 12 页、工具 3 页、复盘 5 页、复盘助手、系统管理 5 页，
 // 以及日夜两套渲染、空态、错误态、横屏健壮性、深底深字对比度抽查。
 
 const EMPTY_DASHBOARD = {
@@ -138,6 +138,36 @@ async function mockMobileApi(page, options = {}) {
       payload = { items: [] };
     } else if (path === "/api/search") {
       payload = { groups: { stocks: [{ id: "002141", code: "002141", name: "贤丰控股", type: "stock", industry: "电子元件" }], sectors: [], themes: [], indices: [] } };
+    } else if (path === "/api/auth/accounts") {
+      payload = {
+        accounts: [{ user_id: auth.user.id, username: auth.user.username, role: auth.user.role, last_used_at: "2026-07-22T09:12:00+08:00" }],
+        current_user_id: auth.user.id,
+      };
+    } else if (path === "/api/account/status") {
+      payload = {
+        birth_profile_configured: true,
+        birth_profile: { birth_datetime: "1990-01-15T08:30", gender: "male" },
+        llm_access: {
+          daily_limit: 50,
+          used_today: 3,
+          remaining_calls: 47,
+          membership: {
+            active: true,
+            subscribed: true,
+            is_admin: auth.user.role === "admin",
+            remaining_days: 20,
+            expires_at: "2026-09-18",
+            plan: "会员",
+          },
+        },
+      };
+    } else if (path === "/api/admin/settings") {
+      payload = {
+        data: { configured: true, snapshot_dates: 12, background_refresh_enabled: true, ifind: { configured: false } },
+        llm: { models: [{ id: "model-1", name: "主模型", base_url: "https://api.openai.com/v1", model: "gpt-4.1", configured: true }], primary_model_id: "model-1", fallback_model_id: "" },
+        membership: { member_daily_limit: 50 },
+        users: [{ id: 2, username: "normal_user", role: "user", membership_subscribed: true, membership_status: "active", membership_expires_at: "2026-09-18", used_today: 3 }],
+      };
     } else if (/^\/api\/stock\/\d+\/preview$/.test(path)) {
       payload = {
         meta: { trade_date: "2026-07-22", intraday_status: "available" },
@@ -230,6 +260,16 @@ const REVIEW_PAGES = [
   ["review/alerts", "提醒中心"],
 ];
 
+const SYSTEM_PAGES = [
+  ["system/profile", "账号资料"],
+  ["system/password", "修改密码"],
+  ["system/membership", "会员状态"],
+  ["system/admin", "系统设置"],
+  ["system/members", "会员管理"],
+];
+
+const PLACEHOLDER_COPY = "该功能页将在后续批次实现";
+
 test("mobile login renders before authentication", async ({ page }) => {
   await page.setViewportSize({ width: 390, height: 844 });
   await page.route("**/api/**", async (route) => {
@@ -249,12 +289,16 @@ test("mobile login renders before authentication", async ({ page }) => {
 test("four hub pages render their icon grids", async ({ page }) => {
   await mockMobileApi(page);
   await openMobile(page);
-  for (const hub of ["market", "tools", "review", "system"]) {
+  for (const hub of ["market", "tools", "review"]) {
     await page.evaluate((h) => { window.MobileRouter.navigate("#/hub/" + h); }, hub);
     await expect(page.locator(".m-hub-grid")).toBeVisible();
     await expect(page.locator(".m-hub-grid .m-grid-item").first()).toBeVisible();
     expect(await measureOverflow(page)).toBeLessThanOrEqual(1);
   }
+  await page.evaluate(() => { window.MobileRouter.navigate("#/hub/system"); });
+  await expect(page.locator("[data-system-page='home']")).toBeVisible();
+  await expect(page.locator(".m-sys-row").first()).toBeVisible();
+  expect(await measureOverflow(page)).toBeLessThanOrEqual(1);
 });
 
 for (const theme of ["day", "night"]) {
@@ -296,6 +340,112 @@ test("review five pages render watchlist, trades, daily, notes and alerts", asyn
   }
 });
 
+test("system management pages render real content instead of placeholders", async ({ page }) => {
+  await mockMobileApi(page);
+  await openMobile(page);
+  for (const [key, label] of SYSTEM_PAGES) {
+    await navigateToFeature(page, key);
+    await expect(page.locator("#m-title")).toHaveText(label);
+    await expect(page.locator(".m-placeholder")).toHaveCount(0);
+    await expect(page.locator("#m-view")).not.toContainText(PLACEHOLDER_COPY);
+    await expect(page.locator("[data-system-page], [data-system-admin-panel]").first()).toBeVisible();
+    expect(await measureOverflow(page)).toBeLessThanOrEqual(1);
+  }
+  await navigateToFeature(page, "system/profile");
+  await expect(page.locator("#m-sys-birth-date")).toBeVisible();
+  await expect(page.locator("[data-system-save-birth]")).toBeVisible();
+  await navigateToFeature(page, "system/password");
+  await expect(page.locator("#m-sys-password-current")).toBeVisible();
+  await navigateToFeature(page, "system/membership");
+  await expect(page.locator(".m-sys-grid")).toBeVisible();
+  await navigateToFeature(page, "system/admin");
+  await expect(page.locator("#m-sys-token")).toBeVisible();
+  await navigateToFeature(page, "system/members");
+  await expect(page.locator("#m-sys-member-limit")).toBeVisible();
+});
+
+test("system home groups entries and keeps admin-only items gated", async ({ page }) => {
+  await mockMobileApi(page);
+  await openMobile(page);
+  await page.evaluate(() => { window.MobileRouter.navigate("#/hub/system"); });
+  await expect(page.locator("[data-system-page='home']")).toBeVisible();
+  await expect(page.locator("#m-view")).toContainText("账号");
+  await expect(page.locator("#m-view")).toContainText("偏好");
+  await expect(page.locator("#m-view")).toContainText("管理员专区");
+  await expect(page.locator("[data-theme-toggle]")).toBeVisible();
+  await expect(page.locator("[data-system-switch]")).toBeVisible();
+  expect(await measureOverflow(page)).toBeLessThanOrEqual(1);
+});
+
+test("system settings tabs, model editor, delete confirm and theme toggle work", async ({ page }) => {
+  await mockMobileApi(page);
+  await openMobile(page);
+  await navigateToFeature(page, "system/admin");
+  await expect(page.locator("[data-system-admin-panel='market']")).toBeVisible();
+  await page.locator("[data-system-admin-tab='models']").click();
+  await expect(page.locator("[data-system-admin-panel='models']")).toBeVisible();
+  await page.locator("[data-system-edit-model]").first().click();
+  await expect(page.locator(".m-sheet-root.is-open")).toBeVisible();
+  await expect(page.locator(".m-sheet-head h2")).toHaveText("编辑模型");
+  await page.locator("[data-sheet-close]").click();
+  await page.locator("[data-system-admin-tab='market']").click();
+  await expect(page.locator("#m-sys-token")).toBeVisible();
+
+  await navigateToFeature(page, "system/profile");
+  await page.locator("[data-system-delete-birth]").click();
+  await expect(page.locator(".m-dialog")).toBeVisible();
+  await expect(page.locator(".m-dialog")).toContainText("删除命理资料");
+  await page.locator("[data-sheet-close]").click();
+
+  await page.evaluate(() => { window.MobileRouter.navigate("#/hub/system"); });
+  await expect(page.locator("[data-theme-toggle]")).toBeVisible();
+  const before = await page.locator("#m-app").getAttribute("data-theme");
+  await page.locator("[data-theme-toggle]").click();
+  await expect.poll(async () => page.locator("#m-app").getAttribute("data-theme")).not.toBe(before);
+
+  await navigateToFeature(page, "system/members");
+  await page.locator("[data-system-open-member]").click();
+  await expect(page.locator(".m-sheet-root.is-open")).toBeVisible();
+  await expect(page.locator(".m-sheet-head h2")).toContainText("管理会员");
+});
+
+test("password mismatch shows inline error instead of a silent submit", async ({ page }) => {
+  await mockMobileApi(page);
+  await openMobile(page);
+  await navigateToFeature(page, "system/password");
+  await page.locator("#m-sys-password-current").fill("OldPass12");
+  await page.locator("#m-sys-password-new").fill("NewPass123");
+  await page.locator("#m-sys-password-confirm").fill("OtherPass123");
+  await page.locator("[data-system-save-password]").click();
+  await expect(page.locator("[data-field-error='confirm']")).toBeVisible();
+  await expect(page.locator("[data-field-error='confirm']")).toContainText("两次输入的密码不一致");
+});
+
+test("empty birth profile save shows a validation toast", async ({ page }) => {
+  await mockMobileApi(page);
+  await openMobile(page);
+  await navigateToFeature(page, "system/profile");
+  await expect(page.locator("[data-system-save-birth]")).toBeVisible();
+  await page.locator("#m-sys-birth-date").fill("");
+  await page.locator("#m-sys-birth-time").fill("");
+  await page.locator("[data-system-save-birth]").click();
+  await expect(page.locator("#m-toast.is-visible")).toBeVisible();
+  await expect(page.locator("#m-toast")).toContainText("请填写完整出生日期和时间");
+});
+
+test("non-admin cannot open system admin pages as placeholders", async ({ page }) => {
+  await mockMobileApi(page, { auth: authSession("user", true) });
+  await openMobile(page);
+  await page.evaluate(() => { window.MobileRouter.navigate("#/hub/system"); });
+  await expect(page.locator("[data-system-page='home']")).toBeVisible();
+  await expect(page.locator('[data-route="#/feature/system/admin"]')).toHaveCount(0);
+  await expect(page.locator('[data-route="#/feature/system/members"]')).toHaveCount(0);
+  await expect(page.locator("[data-system-switch]")).toBeVisible();
+  await navigateToFeature(page, "system/admin");
+  await expect(page.locator("#m-view")).not.toContainText(PLACEHOLDER_COPY);
+  await expect(page.locator("[data-system-page='forbidden']")).toBeVisible();
+});
+
 test("assistant chat renders with presets and input", async ({ page }) => {
   await mockMobileApi(page);
   await openMobile(page);

tests/test_account_switch_grants.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import threading
+import unittest
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from backend.features.accounts.security import SecretVault, token_hash
+from backend.features.accounts.service import AccountService
+from database import ReviewDatabase
+
+
+class AccountSwitchGrantTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temp = TemporaryDirectory()
+        self.database = ReviewDatabase(Path(self.temp.name) / "review.db")
+        self.bound_user_id = 0
+        self.service = AccountService(
+            database=self.database,
+            vault=SecretVault(SecretVault.generate_key()),
+            current_user_supplier=lambda: self.bound_user_id,
+            access_supplier=lambda: self.database.user_access(self.bound_user_id) or {},
+            bind_user=self._bind,
+            personal_field_builder=lambda *args, **kwargs: {},
+            auth_lock=threading.Lock(),
+        )
+        self.device_a = token_hash("device-a-token")
+        self.device_b = token_hash("device-b-token")
+
+    def tearDown(self) -> None:
+        self.temp.cleanup()
+
+    def _bind(self, user_id: int) -> None:
+        self.bound_user_id = int(user_id)
+
+    def _register(self, username: str, device_hash: str = "") -> dict:
+        return self.service.register(username, "Password123", device_hash or self.device_a)
+
+    def test_login_records_accounts_for_the_current_device_only(self) -> None:
+        first = self._register("alpha_user")
+        second = self._register("beta_user")
+        self.service.login("alpha_user", "Password123", self.device_b)
+
+        listed = self.service.list_device_accounts(self.device_a)
+        names = [item["username"] for item in listed["accounts"]]
+        self.assertEqual(names, ["beta_user", "alpha_user"])
+        self.assertEqual(
+            self.service.list_device_accounts(self.device_b)["accounts"][0]["username"],
+            "alpha_user",
+        )
+        self.assertEqual(self.service.list_device_accounts("")["accounts"], [])
+        self.assertEqual(first["user"]["username"], "alpha_user")
+        self.assertEqual(second["user"]["username"], "beta_user")
+
+    def test_switch_uses_device_grant_and_keeps_the_original_authorization(self) -> None:
+        first = self._register("alpha_user")
+        self._register("beta_user")
+        switched = self.service.switch_account(self.device_a, int(first["user"]["id"]))
+        self.assertEqual(switched["user"]["username"], "alpha_user")
+        remaining = {
+            item["username"]
+            for item in self.service.list_device_accounts(self.device_a)["accounts"]
+        }
+        self.assertEqual(remaining, {"alpha_user", "beta_user"})
+
+    def test_switch_without_a_valid_grant_requires_reauthentication(self) -> None:
+        user = self._register("alpha_user")
+        with self.assertRaisesRegex(PermissionError, "该账号需重新验证"):
+            self.service.switch_account(self.device_b, int(user["user"]["id"]))
+        with self.assertRaisesRegex(PermissionError, "该账号需重新验证"):
+            self.service.switch_account("", int(user["user"]["id"]))
+
+    def test_forget_only_removes_the_current_device_grant(self) -> None:
+        user = self._register("alpha_user")
+        self.service.login("alpha_user", "Password123", self.device_b)
+        self.service.forget_account(self.device_a, int(user["user"]["id"]))
+        self.service.forget_account(self.device_a, int(user["user"]["id"]))
+        self.assertEqual(self.service.list_device_accounts(self.device_a)["accounts"], [])
+        self.assertEqual(
+            self.service.list_device_accounts(self.device_b)["accounts"][0]["username"],
+            "alpha_user",
+        )
+
+    def test_logout_revokes_only_the_current_account_on_this_device(self) -> None:
+        first = self._register("alpha_user")
+        second = self._register("beta_user")
+        self.service.revoke_current_device_grant(self.device_a, int(second["user"]["id"]))
+        names = {
+            item["username"]
+            for item in self.service.list_device_accounts(self.device_a)["accounts"]
+        }
+        self.assertEqual(names, {"alpha_user"})
+        switched = self.service.switch_account(self.device_a, int(first["user"]["id"]))
+        self.assertEqual(switched["user"]["id"], first["user"]["id"])
+
+    def test_password_change_revokes_grants_on_every_device(self) -> None:
+        user = self._register("alpha_user")
+        self.service.login("alpha_user", "Password123", self.device_b)
+        self._bind(int(user["user"]["id"]))
+        self.service.change_password("Password123", "Password456")
+        self.assertEqual(self.service.list_device_accounts(self.device_a)["accounts"], [])
+        self.assertEqual(self.service.list_device_accounts(self.device_b)["accounts"], [])
+        with self.assertRaisesRegex(PermissionError, "该账号需重新验证"):
+            self.service.switch_account(self.device_a, int(user["user"]["id"]))
+
+    def test_device_keeps_at_most_five_accounts(self) -> None:
+        usernames = [f"user_{index}" for index in range(6)]
+        ids = [self._register(name)["user"]["id"] for name in usernames]
+        listed = self.service.list_device_accounts(self.device_a)["accounts"]
+        self.assertEqual(len(listed), 5)
+        kept = {item["user_id"] for item in listed}
+        self.assertNotIn(ids[0], kept)
+        self.assertTrue(set(ids[1:]).issubset(kept))
+
+    def test_expired_grants_are_removed_lazily(self) -> None:
+        user = self._register("alpha_user")
+        past = (datetime.now(timezone.utc) - timedelta(days=1)).isoformat(timespec="seconds")
+        self.database.upsert_switch_grant(
+            self.device_a,
+            int(user["user"]["id"]),
+            past,
+            past,
+            past,
+        )
+        self.assertEqual(self.service.list_device_accounts(self.device_a)["accounts"], [])
+        with self.assertRaisesRegex(PermissionError, "该账号需重新验证"):
+            self.service.switch_account(self.device_a, int(user["user"]["id"]))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_admin_refresh_status.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import unittest
+
+from backend.jobs.service import _verified_dashboard_result
+
+
+class AdminRefreshStatusTests(unittest.TestCase):
+    def test_carried_snapshot_is_reported_as_failed_job(self):
+        result = _verified_dashboard_result(
+            {"meta": {"carried_forward": True, "notice": "官方涨跌停数据尚未返回"}}
+        )
+
+        self.assertEqual(result["status"], "failed")
+        self.assertEqual(result["error"], "官方涨跌停数据尚未返回")
+
+    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)
+
+
+if __name__ == "__main__":
+    unittest.main()

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_database_migrations.py

@@ -25,6 +25,7 @@ class DatabaseMigrationTests(unittest.TestCase):
                         ("0002", "create_job_runs"),
                         ("0003", "extend_llm_audit"),
                         ("0004", "add_mentor_note"),
+                        ("0005", "create_account_switch_grants"),
                     ],
                 )
                 columns = {
@@ -39,7 +40,7 @@ class DatabaseMigrationTests(unittest.TestCase):
                 count = connection.execute(
                     "SELECT COUNT(*) AS count FROM schema_migrations"
                 ).fetchone()["count"]
-            self.assertEqual(count, 4)
+            self.assertEqual(count, 5)
 
     def test_database_with_recorded_0004_and_note_column_starts_without_reapply(
         self,
@@ -60,7 +61,7 @@ class DatabaseMigrationTests(unittest.TestCase):
                 count = connection.execute(
                     "SELECT COUNT(*) AS count FROM schema_migrations"
                 ).fetchone()["count"]
-            self.assertEqual(count, 4)
+            self.assertEqual(count, 5)
 
     def test_old_database_without_0004_upgrades_and_adds_note_column(self) -> None:
         with tempfile.TemporaryDirectory() as root:
@@ -87,7 +88,7 @@ class DatabaseMigrationTests(unittest.TestCase):
                         "PRAGMA table_info(mentor_preferences)"
                     )
                 ]
-            self.assertEqual(versions, {"0001", "0002", "0003", "0004"})
+            self.assertEqual(versions, {"0001", "0002", "0003", "0004", "0005"})
             self.assertIn("note", note_rows)
 
     def test_database_with_unknown_migration_is_rejected(self) -> None:

tests/test_datahub_bridge.py

@@ -0,0 +1,254 @@
+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.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] = []
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> DatahubResponse:
+        self.paths.append(path)
+        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 test_default_config_keeps_legacy_and_does_not_call_datahub(self) -> None:
+        settings = DatahubSettings.load(environ={}, credentials={})
+        self.assertFalse(settings.any_enabled())
+        self.assertTrue(all(not settings.flags(name).read and not settings.flags(name).shadow for name in DATASETS))
+        client = FakeClient(error=DatahubError("INTERNAL", "should not be called"))
+        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, [])
+        self.assertEqual(len(legacy.calls), 1)
+
+    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)
+
+    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_and_stale(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"),
+        ]
+        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},
+                    ))
+                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_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_keeps_legacy_even_when_read_flag_is_on(self) -> None:
+        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, [])
+
+    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_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_deploy_baseline.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import os
+import stat
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+CHECK = ROOT / "tools" / "check_deploy_baseline.sh"
+BUILD = ROOT / "tools" / "build_image.sh"
+
+
+def run_check(repo: Path, candidate: str, live: str) -> subprocess.CompletedProcess[str]:
+    env = os.environ.copy()
+    env["GIT_DIR"] = str(repo / ".git")
+    env["GIT_WORK_TREE"] = str(repo)
+    return subprocess.run(
+        ["bash", str(CHECK), candidate, "--live-revision", live],
+        cwd=repo,
+        capture_output=True,
+        text=True,
+        env=env,
+        check=False,
+    )
+
+
+def git(repo: Path, *args: str) -> str:
+    result = subprocess.run(
+        ["git", *args],
+        cwd=repo,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout.strip()
+
+
+class DeployBaselineGateTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.tmpdir = tempfile.TemporaryDirectory()
+        cls.repo = Path(cls.tmpdir.name) / "repo"
+        cls.repo.mkdir()
+        git(cls.repo, "init")
+        git(cls.repo, "config", "user.email", "gate@example.com")
+        git(cls.repo, "config", "user.name", "Gate")
+        (cls.repo / "README").write_text("base\n", encoding="utf-8")
+        git(cls.repo, "add", "README")
+        git(cls.repo, "commit", "-m", "base")
+        cls.base = git(cls.repo, "rev-parse", "HEAD")
+
+        (cls.repo / "online.txt").write_text("live\n", encoding="utf-8")
+        git(cls.repo, "add", "online.txt")
+        git(cls.repo, "commit", "-m", "online")
+        cls.live = git(cls.repo, "rev-parse", "HEAD")
+
+        git(cls.repo, "checkout", "-b", "successor")
+        (cls.repo / "next.txt").write_text("next\n", encoding="utf-8")
+        git(cls.repo, "add", "next.txt")
+        git(cls.repo, "commit", "-m", "successor of live")
+        cls.successor = git(cls.repo, "rev-parse", "HEAD")
+
+        git(cls.repo, "checkout", "-B", "lagging-main", cls.base)
+        (cls.repo / "stale.txt").write_text("stale main\n", encoding="utf-8")
+        git(cls.repo, "add", "stale.txt")
+        git(cls.repo, "commit", "-m", "lagging main")
+        cls.lagging = git(cls.repo, "rev-parse", "HEAD")
+
+        git(cls.repo, "checkout", "-B", "side", cls.base)
+        (cls.repo / "side.txt").write_text("side branch\n", encoding="utf-8")
+        git(cls.repo, "add", "side.txt")
+        git(cls.repo, "commit", "-m", "unrelated side branch")
+        cls.side = git(cls.repo, "rev-parse", "HEAD")
+
+        git(cls.repo, "checkout", "-B", "successor", cls.successor)
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cls.tmpdir.cleanup()
+
+    def test_check_script_is_executable(self) -> None:
+        self.assertTrue(CHECK.exists())
+        self.assertTrue(stat.S_IXUSR & CHECK.stat().st_mode)
+
+    def test_successor_of_live_passes(self) -> None:
+        result = run_check(self.repo, self.successor, self.live)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn(self.live, result.stdout)
+        self.assertIn(self.successor, result.stdout)
+        self.assertIn("next.txt", result.stdout)
+        self.assertIn("祖先关系通过", result.stdout)
+
+    def test_lagging_main_is_blocked(self) -> None:
+        result = run_check(self.repo, self.lagging, self.live)
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("拒绝", result.stderr)
+
+    def test_side_branch_is_blocked(self) -> None:
+        result = run_check(self.repo, self.side, self.live)
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("拒绝", result.stderr)
+
+    def test_unknown_commit_is_blocked(self) -> None:
+        result = run_check(self.repo, "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef", self.live)
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("无法解析", result.stderr)
+
+    def test_build_image_calls_the_gate_and_rejects_latest(self) -> None:
+        source = BUILD.read_text(encoding="utf-8")
+        self.assertIn("check_deploy_baseline.sh", source)
+        self.assertIn("禁止构建 latest", source)
+        self.assertIn("org.opencontainers.image.revision", source)
+        gate = CHECK.read_text(encoding="utf-8")
+        self.assertIn("org.opencontainers.image.revision", gate)
+        self.assertIn("merge-base --is-ancestor", gate)
+        self.assertIn("候选将丢失的提交", gate)
+        self.assertIn("禁止人工填写", gate)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_frontend_contract.py

@@ -344,6 +344,22 @@ class FrontendContractTests(unittest.TestCase):
         self.assertIn("max-height: var(--sentiment-history-max-height);", self.sentiment_styles)
         self.assertIn("overflow: auto;", self.sentiment_styles)
 
+    def test_sentiment_equal_height_and_tooltip_tokens(self):
+        self.assertIn("--sentiment-analysis-height: 600px;", self.tokens)
+        self.assertIn("--sentiment-tooltip-bg: var(--text-primary);", self.tokens)
+        self.assertIn("--sentiment-tooltip-fg: var(--text-inverse);", self.tokens)
+        self.assertIn("--sentiment-tooltip-bg: #26293e;", self.tokens)
+        self.assertIn("--sentiment-tooltip-fg: #e8eaed;", self.tokens)
+        self.assertIn("height: var(--sentiment-analysis-height);", self.sentiment_styles)
+        self.assertIn("max-height: var(--sentiment-analysis-height);", self.sentiment_styles)
+        self.assertIn("justify-content: space-evenly;", self.sentiment_styles)
+        self.assertIn("background: var(--sentiment-tooltip-bg);", self.sentiment_styles)
+        self.assertIn("color: var(--sentiment-tooltip-fg);", self.sentiment_styles)
+        self.assertIn("new ResizeObserver", self.script)
+        self.assertIn("#sentimentCycleView .redesigned-emotion-grid {", self.sentiment_styles)
+        self.assertNotIn("height: 100vh", self.sentiment_styles)
+        self.assertNotIn("min-height: 100%", self.sentiment_styles)
+
     def test_mentor_final_visual_fix_contract(self):
         shell_styles = (STATIC_DIR / "shared" / "shell.css").read_text(encoding="utf-8")
         mentor_html = (STATIC_DIR / "pages" / "mentor" / "page.html").read_text(encoding="utf-8")

tests/test_governance_registries.py

@@ -65,8 +65,11 @@ class GovernanceRegistryTests(unittest.TestCase):
             public,
             {
                 ("GET", "/api/health"),
+                ("GET", "/api/auth/accounts"),
                 ("POST", "/api/auth/login"),
                 ("POST", "/api/auth/register"),
+                ("POST", "/api/auth/switch"),
+                ("POST", "/api/auth/forget"),
             },
         )
 

tests/test_login_portal.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+LOGIN = (ROOT / "frontend" / "login" / "index.html").read_text(encoding="utf-8")
+LOGIN_JS = (ROOT / "frontend" / "login" / "page.js").read_text(encoding="utf-8")
+AUTH = (ROOT / "frontend" / "shared" / "auth.css").read_text(encoding="utf-8")
+TOKENS = (ROOT / "frontend" / "shared" / "tokens.css").read_text(encoding="utf-8")
+
+
+class LoginPortalContractTests(unittest.TestCase):
+    def test_confirmed_brand_skeleton_is_in_markup(self) -> None:
+        for needle in (
+            'class="login-brand-header"',
+            'class="login-brand-name"',
+            "A股个人复盘工作台",
+            'class="login-brand-kicker"',
+            "看懂情绪周期，把复盘变成下一次的先手。",
+            'class="login-brand-chart"',
+            'class="login-brand-stats"',
+            "股市有风险，投资需谨慎",
+            'id="loginThemeToggle"',
+            'id="loginCard"',
+        ):
+            self.assertIn(needle, LOGIN)
+
+    def test_login_tokens_own_the_confirmed_layout_metrics(self) -> None:
+        for needle in (
+            "--login-brand-share: 34%;",
+            "--login-brand-cap: 560px;",
+            "--login-brand-wide-share: 29.2%;",
+            "--login-card-width: 408px;",
+            "--login-hero-size: 28px;",
+            "--login-account-row-min: 72px;",
+        ):
+            self.assertIn(needle, TOKENS)
+        self.assertIn("width: var(--login-brand-share);", AUTH)
+        self.assertIn("width: var(--login-card-width);", AUTH)
+        self.assertIn("justify-content: flex-end;", AUTH)
+        self.assertIn("body.login-portal {", AUTH)
+        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_mobile_system_pages.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import re
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+NAV = ROOT / "frontend/m/config/nav.config.js"
+PAGES = ROOT / "frontend/m/js/pages.js"
+ROUTER = ROOT / "frontend/m/js/router.js"
+
+
+class MobileSystemPagesRegressionTests(unittest.TestCase):
+    """Prevent mobile system-management entries from falling back to placeholders."""
+
+    def test_nav_system_entries_are_registered_as_real_pages(self) -> None:
+        nav = NAV.read_text(encoding="utf-8")
+        pages = PAGES.read_text(encoding="utf-8")
+        keys = re.findall(r'key:\s*"(system/[^"]+)"', nav)
+        self.assertEqual(
+            keys,
+            [
+                "system/profile",
+                "system/password",
+                "system/membership",
+                "system/admin",
+                "system/members",
+            ],
+        )
+        for key in keys:
+            self.assertIn(f'"{key}": setupSystemPage', pages)
+            self.assertIn(f'"{key}": loadSystem', pages)
+
+    def test_placeholder_copy_is_only_a_router_fallback(self) -> None:
+        router = ROUTER.read_text(encoding="utf-8")
+        pages = PAGES.read_text(encoding="utf-8")
+        self.assertIn("该功能页将在后续批次实现", router)
+        self.assertNotIn("该功能页将在后续批次实现", pages)
+        self.assertIn("function setupSystemPage", pages)
+        self.assertIn("function loadSystem", pages)
+
+    def test_system_pages_render_real_controls_not_stubs(self) -> None:
+        pages = PAGES.read_text(encoding="utf-8")
+        for marker in (
+            'data-system-page="home"',
+            'data-system-page="profile"',
+            'data-system-page="password"',
+            'data-system-page="membership"',
+            'data-system-page="members"',
+            'data-system-page="forbidden"',
+            'data-system-admin-panel="market"',
+            "m-sys-birth-date",
+            "m-sys-password-current",
+            "m-sys-token",
+            "m-sys-member-limit",
+            "data-system-switch",
+            "data-system-edit-model",
+            "data-system-open-member",
+            "管理员专区",
+            "保存密钥",
+            "保存分工",
+            'location.assign("/login/")',
+        ):
+            self.assertIn(marker, pages)
+
+    def test_system_boolean_attrs_do_not_have_stray_quotes(self) -> None:
+        pages = PAGES.read_text(encoding="utf-8")
+        stray = re.findall(r'data-system-[a-z-]*"(?=[>\s])', pages)
+        self.assertEqual(
+            stray,
+            [],
+            "boolean data-system attributes must not have a trailing quote before > or space",
+        )
+        for name in (
+            "data-system-save-birth",
+            "data-system-save-password",
+            "data-system-add-model",
+            "data-system-save-models",
+            "data-system-save-market",
+            "data-system-refresh",
+            "data-system-toggle-refresh",
+            "data-system-save-model",
+        ):
+            self.assertIn(name, pages)
+            self.assertNotIn(name + '">', pages)

tests/test_realtime_dashboard.py

@@ -111,6 +111,25 @@ class RealtimeDashboardTests(unittest.TestCase):
         self.assertEqual(quote["amount_billion"], 3.0)
         self.assertAlmostEqual(quote["turnover_rate"], 0.01)
 
+    def test_close_dashboard_marks_official_limit_data(self):
+        dashboard = self.client.dashboard("20260720")
+
+        self.assertEqual(dashboard["meta"]["limit_data_source"], "official")
+
+    def test_close_dashboard_marks_derived_limit_data_as_incomplete(self):
+        original_query = self.client.query
+
+        def query(api_name, params=None, fields=""):
+            if api_name == "limit_list_d":
+                return []
+            return original_query(api_name, params, fields)
+
+        self.client.query = query
+        dashboard = self.client.dashboard("20260720")
+
+        self.assertEqual(dashboard["meta"]["limit_data_source"], "derived")
+        self.assertIn("日线数据推算", dashboard["meta"]["notice"])
+
 
 if __name__ == "__main__":
     unittest.main()

tools/README.md

@@ -20,6 +20,25 @@ 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`.
+- `tools/update_from_main.sh` (deployed to the server as
+  `~/xiaobai-build/update-from-main.sh`): the server-side update-and-build entry for
+  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. 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
+  ancestor gate. Reads the live `org.opencontainers.image.revision` from the running
+  `xiaobai-review` container (or `--live-revision` in tests), prints the live SHA,
+  candidate SHA, file diff, and commits the candidate would drop, then exits if the
+  live revision is not an ancestor of the candidate.
 
 `verify_baseline.py` does not inspect a parent checkout or skip tests according to files outside
 this application. Historical comparison scripts were retired after final standalone acceptance;

tools/build_api_registry.py

@@ -50,7 +50,13 @@ def _owner(path: str) -> str:
 
 
 def _role(method: str, path: str) -> str:
-    if path == "/api/health" or path in {"/api/auth/register", "/api/auth/login"}:
+    if path == "/api/health" or path in {
+        "/api/auth/register",
+        "/api/auth/login",
+        "/api/auth/accounts",
+        "/api/auth/switch",
+        "/api/auth/forget",
+    }:
         return "public"
     from api_access import required_role
 

tools/build_architecture_inventory.py

@@ -217,6 +217,7 @@ 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"},
@@ -235,6 +236,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"},

tools/build_image.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# 小白复盘唯一安全构建入口（HEL-235 固化）
+# 方式：从明确 Git 提交 git archive 流式传输到部署机 docker build，不使用任何服务器工作树。
+# 铁律：禁止在服务器目录（如 /opt/1panel/docker/compose/xiaobaifupan）里 docker build；
+#       禁止构建 latest 等不带提交短号的 tag；严禁向 192.168.200.36 构建或部署。
+set -euo pipefail
+
+HOST_DEFAULT="moxiaobai@192.168.200.11"
+REPO_NAME="xiaobai-review"
+
+usage() {
+  cat <<'EOF'
+用法: tools/build_image.sh <commit> <tag>
+  <commit>  提交号（完整或前缀），必须能被 origin 解析；构建前会自动 fetch
+  <tag>     镜像 tag，必须以 -<提交短号7位> 结尾，锁定镜像来源；禁止 latest、rollback-*
+示例: tools/build_image.sh cefc86917d89 verify-hel235-cefc869
+说明: 仅构建镜像，不启动、不替换任何容器；换版与回滚另行人工执行。
+EOF
+  exit 2
+}
+
+[ $# -eq 2 ] || usage
+COMMIT="$1"
+TAG="$2"
+HOST="${XB_BUILD_HOST:-$HOST_DEFAULT}"
+
+case "$HOST" in
+  *192.168.200.36*)
+    echo "拒绝：192.168.200.36 已永久废弃，严禁在其上构建或部署。" >&2
+    exit 1
+    ;;
+esac
+
+cd "$(git rev-parse --show-toplevel)"
+
+echo "==> 同步远端引用"
+git fetch origin --prune --quiet
+
+FULL_SHA="$(git rev-parse --verify --quiet "${COMMIT}^{commit}" || true)"
+if [ -z "$FULL_SHA" ]; then
+  echo "拒绝：提交 ${COMMIT} 无法解析。构建源必须锁定到已推送 origin 的明确提交。" >&2
+  exit 1
+fi
+SHORT="${FULL_SHA:0:7}"
+SUBJECT="$(git log -1 --format=%s "$FULL_SHA")"
+
+case "$TAG" in
+  latest)
+    echo "拒绝：禁止构建 latest，模糊 tag 无法追溯来源提交。" >&2
+    exit 1
+    ;;
+  rollback-*)
+    echo "拒绝：rollback-* 是部署时对既有镜像的人工 docker tag，不允许用来构建。" >&2
+    exit 1
+    ;;
+esac
+if [[ "$TAG" != *-"$SHORT" ]]; then
+  echo "拒绝：tag「${TAG}」必须以 -${SHORT} 结尾，保证镜像 tag 与来源提交一一对应。" >&2
+  exit 1
+fi
+
+echo "==> 部署基线门禁（线上提交必须是候选祖先）"
+bash "$(git rev-parse --show-toplevel)/tools/check_deploy_baseline.sh" "$FULL_SHA"
+
+echo "==> 构建计划"
+echo "    提交: ${FULL_SHA}  ${SUBJECT}"
+echo "    镜像: ${REPO_NAME}:${TAG}  @ ${HOST}"
+echo "    方式: git archive 流式构建（不读取服务器上任何代码目录）"
+
+echo "==> 流式构建开始"
+git archive --format=tar "$FULL_SHA" \
+  | ssh -o BatchMode=yes "$HOST" docker build --rm \
+      -t "${REPO_NAME}:${TAG}" \
+      --label "org.opencontainers.image.revision=${FULL_SHA}" \
+      --label "org.opencontainers.image.created=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+      --label "org.opencontainers.image.source=git-archive-stream" \
+      -
+
+echo "==> 回读校验镜像内记录的提交号"
+GOT="$(ssh -o BatchMode=yes "$HOST" "docker image inspect ${REPO_NAME}:${TAG} --format '{{index .Config.Labels \"org.opencontainers.image.revision\"}}'" 2>/dev/null || true)"
+if [ "$GOT" != "$FULL_SHA" ]; then
+  echo "校验失败：镜像 revision='${GOT:-<空>}'，期望 ${FULL_SHA}。删除不可信镜像，中止。" >&2
+  ssh -o BatchMode=yes "$HOST" docker rmi "${REPO_NAME}:${TAG}" >/dev/null 2>&1 || true
+  exit 1
+fi
+
+IMAGE_ID="$(ssh -o BatchMode=yes "$HOST" "docker image inspect ${REPO_NAME}:${TAG} --format '{{.Id}}'")"
+SHORT_ID="${IMAGE_ID##*:}"
+
+ssh -o BatchMode=yes "$HOST" \
+  "mkdir -p ~/xiaobai-build && printf '%s\t%s\t%s\t%s\tgit-archive-stream\n' \"\$(date '+%F %T')\" ${REPO_NAME}:${TAG} ${FULL_SHA} ${SHORT_ID} >> ~/xiaobai-build/BUILD_LOG.tsv"
+
+echo "==> 完成"
+echo "    ${REPO_NAME}:${TAG}  (${SHORT_ID})"
+echo "    来源提交 ${FULL_SHA} 已写入镜像 label 与 ~/xiaobai-build/BUILD_LOG.tsv"

tools/check_deploy_baseline.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# 部署基线门禁（HEL-238）：候选提交必须包含当前线上提交的全部历史。
+# 线上提交号从运行中的容器镜像 label 读取，禁止人工填写“看起来正确”的基线。
+set -euo pipefail
+
+HOST_DEFAULT="moxiaobai@192.168.200.11"
+CONTAINER_DEFAULT="xiaobai-review"
+
+usage() {
+  cat <<'EOF'
+用法: tools/check_deploy_baseline.sh <candidate_commit> [--live-revision <sha>]
+  <candidate_commit>     准备构建/部署的提交（完整或前缀）
+  --live-revision <sha>  仅测试用：直接指定线上提交，跳过 SSH 读取
+环境变量:
+  XB_BUILD_HOST          部署机 SSH（默认 moxiaobai@192.168.200.11）
+  XB_LIVE_CONTAINER      运行中容器名（默认 xiaobai-review）
+  XB_LIVE_REVISION       若已设置则视为线上提交，不再 SSH
+EOF
+  exit 2
+}
+
+[ $# -ge 1 ] || usage
+CANDIDATE="$1"
+shift
+LIVE_OVERRIDE=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --live-revision)
+      [ $# -ge 2 ] || usage
+      LIVE_OVERRIDE="$2"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      ;;
+    *)
+      echo "拒绝：未知参数 $1" >&2
+      usage
+      ;;
+  esac
+done
+
+HOST="${XB_BUILD_HOST:-$HOST_DEFAULT}"
+CONTAINER="${XB_LIVE_CONTAINER:-$CONTAINER_DEFAULT}"
+
+case "$HOST" in
+  *192.168.200.36*)
+    echo "拒绝：192.168.200.36 已永久废弃，严禁在其上构建或部署。" >&2
+    exit 1
+    ;;
+esac
+
+cd "$(git rev-parse --show-toplevel)"
+
+read_live_revision() {
+  if [ -n "${LIVE_OVERRIDE}" ]; then
+    printf '%s\n' "${LIVE_OVERRIDE}"
+    return
+  fi
+  if [ -n "${XB_LIVE_REVISION:-}" ]; then
+    printf '%s\n' "${XB_LIVE_REVISION}"
+    return
+  fi
+  ssh -o BatchMode=yes "$HOST" bash -s -- "$CONTAINER" <<'REMOTE'
+set -euo pipefail
+container="$1"
+revision="$(docker inspect --format '{{index .Config.Labels "org.opencontainers.image.revision"}}' "$container" 2>/dev/null || true)"
+if [ -z "$revision" ] || [ "$revision" = "<no value>" ]; then
+  image="$(docker inspect --format '{{.Image}}' "$container" 2>/dev/null || true)"
+  if [ -n "$image" ]; then
+    revision="$(docker inspect --format '{{index .Config.Labels "org.opencontainers.image.revision"}}' "$image" 2>/dev/null || true)"
+  fi
+fi
+if [ -z "$revision" ] || [ "$revision" = "<no value>" ]; then
+  echo "拒绝：无法从线上容器 ${container} 读取 org.opencontainers.image.revision。" >&2
+  exit 1
+fi
+printf '%s\n' "$revision"
+REMOTE
+}
+
+LIVE_RAW="$(read_live_revision)"
+LIVE_RAW="$(printf '%s' "$LIVE_RAW" | tr -d '[:space:]')"
+if [ -z "$LIVE_RAW" ]; then
+  echo "拒绝：线上提交号为空，禁止继续构建或部署。" >&2
+  exit 1
+fi
+
+CANDIDATE_SHA="$(git rev-parse --verify --quiet "${CANDIDATE}^{commit}" || true)"
+if [ -z "$CANDIDATE_SHA" ]; then
+  echo "拒绝：候选提交 ${CANDIDATE} 无法解析。" >&2
+  exit 1
+fi
+
+LIVE_SHA="$(git rev-parse --verify --quiet "${LIVE_RAW}^{commit}" || true)"
+if [ -z "$LIVE_SHA" ]; then
+  echo "拒绝：线上提交 ${LIVE_RAW} 在本地仓库无法解析；请先 git fetch，禁止手工填写替代基线。" >&2
+  exit 1
+fi
+
+echo "==> 部署基线对照"
+echo "    线上提交: ${LIVE_SHA}"
+echo "    候选提交: ${CANDIDATE_SHA}"
+
+echo "==> 候选相对线上的文件差异"
+DIFF_FILES="$(git diff --name-only "$LIVE_SHA" "$CANDIDATE_SHA" || true)"
+if [ -z "$DIFF_FILES" ]; then
+  echo "    （无文件差异）"
+else
+  printf '%s\n' "$DIFF_FILES" | sed 's/^/    /'
+fi
+
+echo "==> 候选将丢失的提交（线上有、候选没有）"
+LOST="$(git log --oneline "$CANDIDATE_SHA".."$LIVE_SHA" || true)"
+if [ -z "$LOST" ]; then
+  echo "    （无）"
+else
+  printf '%s\n' "$LOST" | sed 's/^/    /'
+fi
+
+if ! git merge-base --is-ancestor "$LIVE_SHA" "$CANDIDATE_SHA"; then
+  echo "拒绝：候选提交不是当前线上提交的后继，部署会丢失线上已有提交。禁止构建或部署。" >&2
+  exit 1
+fi
+
+echo "==> 祖先关系通过：线上 ${LIVE_SHA:0:7} 是候选 ${CANDIDATE_SHA:0:7} 的祖先"

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,78 @@
+# 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
+- 暂存 → 校验 → 整批原子发布 → 可回滚
+- `/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；用内存/临时库和假适配器。
+
+## 备份
+
+每日 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`
+- 回滚、补数需重新输入密码 + 确认词
+- 容器非 root（uid 10002）、read_only、cap_drop ALL

xiaobai-datahub/admin/app.js

@@ -0,0 +1,268 @@
+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;
+    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 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 / index_daily / 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,15 @@
+{
+  "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
+}

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/adapters/__init__.py

@@ -0,0 +1,15 @@
+from datahub.adapters.akshare import ADAPTER as akshare
+from datahub.adapters.eastmoney import ADAPTER as eastmoney
+from datahub.adapters.ifind import ADAPTER as ifind
+from datahub.adapters.tencent import ADAPTER as tencent
+from datahub.adapters.ths import ADAPTER as ths
+from datahub.adapters.xgb import ADAPTER as xgb
+
+RESERVED = {
+    "eastmoney": eastmoney,
+    "tencent": tencent,
+    "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,3 @@
+from datahub.adapters.base import ReservedAdapter
+
+ADAPTER = ReservedAdapter("eastmoney")

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,3 @@
+from datahub.adapters.base import ReservedAdapter
+
+ADAPTER = ReservedAdapter("tencent")

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,154 @@
+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_index_daily,
+    normalize_moneyflow,
+    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",
+}
+
+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",
+}
+
+DEFAULT_INDEX_CODES = ("000001.SH", "399001.SZ", "399006.SZ", "000300.SH")
+
+
+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]]:
+        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:
+            # Caller typically loops codes; a missing code would pull nothing useful.
+            query_params.setdefault("ts_code", DEFAULT_INDEX_CODES[0])
+        return self._query(api_name, query_params, fields)
+
+    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]]:
+        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 request failed: {exc}") from exc
+        if result.get("code") != 0:
+            raise AdapterError(result.get("msg") or "Tushare returned an unknown error")
+        data = result.get("data") or {}
+        columns = data.get("fields") or []
+        return [dict(zip(columns, item)) for item in data.get("items") or []]

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,162 @@
+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 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,
+            "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")
+        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": "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]:
+        self._dangerous(password, confirm, f"{dataset}:{trade_date}")
+        if dataset == "reference":
+            result = self.pipeline.ingest_reference(trade_date)
+        else:
+            result = self.pipeline.run_dataset(dataset, trade_date)
+        self.pipeline.audit(actor, "backfill", f"{dataset}:{trade_date}", 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/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/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/db.py

@@ -0,0 +1,340 @@
+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.timeutil import isoformat
+
+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 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 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);
+"""
+
+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"),
+}
+
+
+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")