fix(HEL-164): 排除构建中的数据库备份

Co-authored-by: multica-agent <github@multica.ai>
fix(HEL-164): 拒绝缓存不完整涨停快照
2026-08-28 11:32:21 +00:00 · 2026-08-28 09:44:51 +00:00 · 2026-08-28 09:29:06 +00:00 · 2026-08-28 09:05:42 +00:00 · 2026-08-28 08:09:49 +00:00 · 2026-08-28 08:09:28 +00:00
33 changed files with 1670 additions and 335 deletions
@@ -9,6 +9,7 @@ __pycache__/
 *.log
 runtime/
 data/cache/
+data/backups/
 data/private-mentor-skills/
 data/*.db
 data/*.db-shm
@@ -14,13 +14,29 @@
    v
 xiaobai-review 容器 :8765
    |-- /app              只读应用代码
+    |   `-- backend/features/heaven/assets/heaven_knowledge.json
+    |                     镜像内 seed（不受 data 挂载遮盖）
    `-- /app/data         宿主机 ./data 持久化挂载
+        |-- review.db
+        |-- iching_zh.json
+        `-- heaven_knowledge.json   优先读取；缺失时回退到上方 seed
 ```

 账号、加密后的公共数据 Token、平台模型 API Key、生辰资料、行情快照和复盘数据均在
 `data/review.db`。解密密钥来自 `.env` 中的 `APP_ENCRYPTION_KEY`。数据库与
 密钥必须成对备份，任意一个丢失都无法恢复账号内的加密资料。

+问天静态知识文件：
+
+- `data/iching_zh.json`、`data/heaven_knowledge.json` 纳入 Git 与镜像构建；
+  `.dockerignore` 不排除这两个文件（只排除 `data/*.db`、`data/cache/` 等运行时产物）。
+- Compose 把宿主机 `./data` 整目录挂到 `/app/data`，会遮盖镜像里同路径文件。
+  因此宿主机 `data/` 应保留上述两个 JSON；若只缺 `heaven_knowledge.json`，
+  服务会回退读取镜像内
+  `backend/features/heaven/assets/heaven_knowledge.json`，解势仍可用。
+- 持久化位置：正式环境以宿主机项目目录下的 `./data/heaven_knowledge.json` 为准；
+  补文件后无需改代码，重启容器即可加载。
+
 管理员私有的问师 Skill 保存在宿主机 `data/private-mentor-skills/`。该目录随 `data`
 挂载进入容器，但被 Git 与 Docker 构建上下文排除，不会进入 Gitea 或镜像。私有 Skill
 只对管理员账号返回和开放调用，也会随本指南的 `data` 备份一起保存。
@@ -23,7 +23,10 @@ COPY requirements.txt ./
 RUN python -m pip install --no-cache-dir -r requirements.txt

 COPY --chown=xiaobai:xiaobai . .
-RUN mkdir -p /app/data && chown -R xiaobai:xiaobai /app/data
+RUN mkdir -p /app/data && chown -R xiaobai:xiaobai /app/data \
+    && test -f /app/data/heaven_knowledge.json \
+    && test -f /app/data/iching_zh.json \
+    && test -f /app/backend/features/heaven/assets/heaven_knowledge.json

 USER xiaobai

@@ -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),
            },
@@ -0,0 +1,117 @@
+{
+  "version": "2026.08.05-5",
+  "sources": {
+    "zhouyi": {
+      "title": "周易经文与十翼",
+      "scope": "卦辞、爻辞、彖传、象传",
+      "kind": "public_domain_primary",
+      "note": "观势与观心只引用本项目已校录的卦爻原文，不把现代网络释文当作原典。"
+    },
+    "jingfang": {
+      "title": "京氏易传",
+      "scope": "八宫与纳甲体系来源",
+      "kind": "public_domain_traditional",
+      "note": "确定性程序采用京房纳甲、八宫世应的通行排法。"
+    },
+    "huozhulin": {
+      "title": "火珠林",
+      "scope": "纳甲筮法、六亲与日月关系",
+      "kind": "public_domain_traditional",
+      "note": "用于观心规则脉络，不直接复制后世简化断语。"
+    },
+    "zengshan": {
+      "title": "增删卜易",
+      "scope": "用神、世应、动变、日月旺衰",
+      "kind": "public_domain_traditional",
+      "note": "只采用可明确编码且有一致输入条件的规则；争议规则单独标记。"
+    },
+    "neijing": {
+      "title": "黄帝内经·素问运气七篇",
+      "scope": "五运、司天在泉、主客气与运气关系",
+      "kind": "public_domain_primary",
+      "note": "观气将原典关系转成当日自我观察语言，不宣称对股价存在因果作用。"
+    }
+  },
+  "trend": {
+    "method": "本卦说明当下结构，实际动爻说明变化关节，之卦说明所趋结构；多动爻全部保留，不以固定口诀删去用户实际得到的爻。",
+    "rules": {
+      "stable": "无动爻时以本卦整体、上下卦关系和大象为主，说明结构的延续条件，不把静止等同于永远不变。",
+      "single": "一爻动时以该爻的时位、爻辞和象辞为变化核心，并用之卦检查变化后的结构。",
+      "multiple": "多爻动时逐一保留相关爻义，先找共同方向与冲突，再结合之卦给出有条件的倾向；不得用固定套话把不同动爻压成同一结论。"
+    }
+  },
+  "fortune": {
+    "principle": "先立中运与司天在泉的年纲，再察当前客气加临主气，最后以日辰说明当日触发；不使用产品权重推导传统结论。",
+    "movement": {
+      "太过": "太过表示该运之气偏于有余，解释时同时观察其本气表现与对所胜、所生关系的牵动，不直接等同于吉或凶。",
+      "不及": "不及表示该运之气偏于不足，解释时同时观察其所不胜来乘与所生受累的可能，不直接等同于弱势结论。"
+    },
+    "qi": {
+      "厥阴风木": "厥阴取风木之动，侧重疏泄、升发、变化与不定；偏盛时可表现为动摇、急变或升散不收。",
+      "少阴君火": "少阴取君火之明与热，侧重显化、温煦和内在驱动；偏盛时容易躁热，受制时则显而不畅。",
+      "太阴湿土": "太阴取湿土之濡与承载，侧重黏滞、蓄积和转化；偏盛时容易困重迟缓，得化时则能承接。",
+      "少阳相火": "少阳取相火之行与枢转，侧重外达、加速和往来；偏盛时容易浮越躁动，受阻时表现为枢机不利。",
+      "阳明燥金": "阳明取燥金之收与清肃，侧重收敛、裁决和边界；偏盛时容易干急严峻，得润时则清明有序。",
+      "太阳寒水": "太阳取寒水之藏与凝，侧重潜藏、收引和下行；偏盛时容易凝滞退缩，得温时则蓄势有根。"
+    },
+    "relations": {
+      "same": "客主同气表示同类气相并，重点看是否相得而彰，还是同气偏盛而亢；不能机械判为有利。",
+      "guest_generates_host": "客生主表示来气生助时令本气，气机较易衔接；仍需观察生助是否过度及年纲是否承接。",
+      "host_generates_guest": "主生客表示时令本气向来气流转，有相生也有外泄；不能只取相生而忽略主气受耗。",
+      "guest_controls_host": "客克主表示来气制约主气，传统称客胜为从；重点解释外来变化居上及原有节律受制。",
+      "host_controls_guest": "主克客表示主气制约来气，传统称主胜为逆；重点解释时令与来气相持而不把相克直接断凶。"
+    },
+    "day_trigger": "日辰只说明当日关系如何被触发，不与中运、司天在泉或主客气并列重复计权。",
+    "industry_boundary": "五行对应行业只作传统取象：可以说明本次已经出现的五行之气对相应行业形成的象征性关注、节奏或约束，但不得读取或猜测行业实时行情，不得预测涨跌，也不得把取象写成投资推荐。",
+    "personal_boundary": "personal.natal_day_master才是用户本命日主；today_relative_to_natal_day_master中的pillars是当日历法，stem_relations只是当日年、月、日三柱天干相对本命日主的确定性关系标签。只能使用本次检索到的关系释义，不得自行重算十神、扩展五行生克、使用藏干、库气或支的燥湿属性，也不得把当日日柱称为用户命局，或由这些字段推断命局中某一十神偏重、身强身弱或喜用神。",
+    "personal_relations": {
+      "比肩": "比肩作为当日天干关系标签，只提示用户可能更在意自主判断、同类比较或坚持原有立场；不能据此判断命局强弱或现实事件。",
+      "劫财": "劫财作为当日天干关系标签，只提示用户留意精力、注意力或可支配资源在同类事项间的分流与竞争感；不等同于破财或他人争夺。",
+      "食神": "食神作为当日天干关系标签，只提示用户留意表达、输出、舒缓与完成感；不等同于收益或确定的轻松结果。",
+      "伤官": "伤官作为当日天干关系标签，只提示用户留意质疑规则、急于表达或追求自主空间的倾向；不等同于冲突或违规。",
+      "偏财": "偏财作为当日天干关系标签，只提示用户留意机会分配、灵活取舍与非固定资源的吸引力；不等同于意外获利。",
+      "正财": "正财作为当日天干关系标签，只提示用户更关注可核对的结果、资源边界和务实落地；不等同于必得收益或现金变化。",
+      "七杀": "七杀作为当日天干关系标签，只提示用户留意紧迫感、外部压力和快速决断冲动；不等同于危险必然发生。",
+      "正官": "正官作为当日天干关系标签，只提示用户更在意规则、责任、秩序和可交付标准；不等同于结果必然受控。",
+      "偏印": "偏印作为当日天干关系标签，只提示用户留意内省、非惯常信息和反复推敲的倾向；不等同于退缩、失眠或方向错误。",
+      "正印": "正印作为当日天干关系标签，只提示用户更在意依据、支持、学习和安全边界；不等同于必然获得帮助。"
+    }
+  },
+  "heart": {
+    "presets": {
+      "trade": "关于我心中的这笔交易，此刻最需要看清的机会、阻碍与风险是什么？",
+      "mind": "此刻影响我交易判断的情绪、执念或盲点是什么？",
+      "unthemed": "不设具体问题，只观此刻一念。"
+    },
+    "focus": {
+      "trade": "以世爻、应爻、妻财爻及实际动变为主要检索对象，同时检查兄弟、官鬼和子孙的生克，不把任何单一六亲固定判吉凶。",
+      "mind": "以世爻和实际动爻为主，观察官鬼所示压力、子孙所示舒解及内外生克；不把心境问题强行翻译成价格方向。",
+      "unthemed": "不强选事项用神，以本卦、世爻、实际动爻和之卦作一般观照，不猜测用户没有提出的问题。",
+      "custom": "先依据用户明确写出的股票交易问题选择相关六亲；无法明确归类时退回世爻、动爻和卦变的一般解释，不擅自补全问题。"
+    },
+    "evidence_order": [
+      "用户问题与预设来源",
+      "本卦及卦宫",
+      "世应与所问相关六亲",
+      "月建日辰、旬空及冲合生克",
+      "实际动爻与变爻",
+      "之卦与整体卦义",
+      "六神辅助象义"
+    ],
+    "limits": "六神只作辅助象义；空亡、月破、日冲、合冲刑害均需结合用神、世应和动变，不得单项宣布结果。",
+    "semantics": {
+      "self_response": "世爻表示求测者当前立场与承受状态，应爻表示所问事项的外部一端或对照面。应爻不是固定的合作方、庄家或资金方；只有用户问题明确给出该角色时，才可作对应解释。",
+      "calendar": "月建与日辰用于判断爻在起卦时刻的承受、生扶和制约。旬空表示该爻所象征的条件当下可能未落实、难发挥或有名无实，但不能单凭旬空判失败，也不能用填实日期预测何时涨跌或行动。月破、日冲、六合、六冲、六害和相刑同样必须与世应、相关六亲及动变合看。",
+      "movement": "动爻说明关系正在变化；变爻说明变化后的承接方向。回头生、回头克和原变爻生克只描述力量关系，不自动对应现实中的借贷、融资、合作或某个具体人物。进神退神只说明同类地支变化的进退趋势，不直接宣布价格方向。",
+      "six_spirits": "六神只补充表达色彩，不单独定成败。青龙不必然有利，白虎不必然紧急或凶险，朱雀不必然等同口舌，玄武不必然等同欺骗，勾陈与螣蛇也不得脱离爻位、六亲和动变独断。",
+      "timing_boundary": "观心不作应期预测。可以说明某项条件在起卦时刻尚未落实或受制，但不得给出未来若干日、某干支日、出空或填实后必然发生什么。",
+      "relatives": {
+        "兄弟": "兄弟是与卦宫五行同类的关系。在股票交易问题中可作为竞争、同类力量或资源分流的候选象义，但不直接等同合作方、亏损或他人拿走资金。",
+        "子孙": "子孙是卦宫所生的关系，可作为舒缓、产出、执行后的释放或对压力的制衡候选象义，但不直接等同收益、资金提供方或确定的利好。",
+        "妻财": "妻财是卦宫所克的关系，在股票交易问题中可作为价值、收益预期、持仓利益或可支配资源的候选象义，但不直接等同现金、融资、自有资金或必得之财。",
+        "官鬼": "官鬼是克制卦宫的关系，可作为压力、风险、规则约束或担忧的候选象义，但不直接等同借贷、坏消息、疾病或必然损失。",
+        "父母": "父母是生助卦宫的关系，可作为信息、依据、计划、规则、凭据或保护条件的候选象义，但不直接等同政策、合同或某一条消息。"
+      }
+    }
+  }
+}
@@ -3,15 +3,24 @@ from __future__ import annotations
 import json
 from http import HTTPStatus

+from backend.features.heaven.knowledge import HeavenKnowledgeError
+

 class HeavenHttpMixin:
+    def _send_heaven_client_error(self, exc: Exception) -> None:
+        payload: dict = {"error": str(exc)}
+        code = getattr(exc, "error_code", None)
+        if code:
+            payload["code"] = str(code)
+        self.send_json(payload, HTTPStatus.BAD_REQUEST)
+
    def heaven_hexagram(self) -> None:
        try:
            body = self.read_json_body()
            result = self.application_service.heaven_hexagram(body.get("lines"))
            self.send_json({"ok": True, "hexagram": result})
        except (ValueError, json.JSONDecodeError) as exc:
-            self.send_json({"error": str(exc)}, HTTPStatus.BAD_REQUEST)
+            self._send_heaven_client_error(exc)

    def heaven_personal(self) -> None:
        try:
@@ -19,12 +28,12 @@ class HeavenHttpMixin:
            result = self.application_service.heaven_personal(body)
            self.send_json({"ok": True, "personal": result})
        except (ValueError, json.JSONDecodeError) as exc:
-            self.send_json({"error": str(exc)}, HTTPStatus.BAD_REQUEST)
+            self._send_heaven_client_error(exc)

    def heaven_interpret(self) -> None:
        try:
            body = self.read_json_body()
            result = self.application_service.heaven_interpret(body)
            self.send_json({"ok": True, **result})
-        except (ValueError, json.JSONDecodeError) as exc:
-            self.send_json({"error": str(exc)}, HTTPStatus.BAD_REQUEST)
+        except (HeavenKnowledgeError, ValueError, json.JSONDecodeError) as exc:
+            self._send_heaven_client_error(exc)
@@ -2,12 +2,23 @@ from __future__ import annotations

 import json
 from functools import lru_cache
+from pathlib import Path
 from typing import Any

 from backend.bootstrap.config import APP_DIR


 KNOWLEDGE_FILE = APP_DIR / "data" / "heaven_knowledge.json"
+# Baked into the image outside the ./data bind mount so volume overlay cannot hide it.
+KNOWLEDGE_SEED_FILE = Path(__file__).resolve().parent / "assets" / "heaven_knowledge.json"
+
+
+class HeavenKnowledgeError(ValueError):
+    """Structured knowledge-file failure surfaced to HTTP as Chinese API errors."""
+
+    def __init__(self, message: str, *, code: str) -> None:
+        super().__init__(message)
+        self.error_code = code


 def prepare_heaven_context(mode: str, calculation: dict[str, Any]) -> dict[str, Any]:
@@ -379,9 +390,49 @@ def _line_record(line: dict[str, Any]) -> dict[str, Any]:
    }


+def resolve_heaven_knowledge_path() -> Path:
+    """Prefer the persisted data-dir file; fall back to the image-baked seed."""
+    if KNOWLEDGE_FILE.is_file():
+        return KNOWLEDGE_FILE
+    if KNOWLEDGE_SEED_FILE.is_file():
+        return KNOWLEDGE_SEED_FILE
+    raise HeavenKnowledgeError(
+        "问天知识文件缺失：未找到 heaven_knowledge.json。"
+        "请确认宿主机 data 目录或镜像内 seed 文件完整。",
+        code="heaven_knowledge_missing",
+    )
+
+
@lru_cache(maxsize=1)
 def _knowledge_catalog() -> dict[str, Any]:
-    payload = json.loads(KNOWLEDGE_FILE.read_text(encoding="utf-8"))
+    path = resolve_heaven_knowledge_path()
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise HeavenKnowledgeError(
+            f"问天知识文件无法读取（{path.name}）：{exc.strerror or exc}",
+            code="heaven_knowledge_missing",
+        ) from exc
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise HeavenKnowledgeError(
+            f"问天知识文件 JSON 损坏（{path.name}），无法解析："
+            f"第 {exc.lineno} 行附近。",
+            code="heaven_knowledge_invalid",
+        ) from exc
+    if not isinstance(payload, dict):
+        raise HeavenKnowledgeError(
+            f"问天知识文件格式不正确（{path.name}）：根节点必须是对象。",
+            code="heaven_knowledge_invalid",
+        )
    if not payload.get("version") or not isinstance(payload.get("sources"), dict):
-        raise ValueError("问天知识库格式不完整。")
+        raise HeavenKnowledgeError(
+            f"问天知识库格式不完整（{path.name}）：缺少 version 或 sources。",
+            code="heaven_knowledge_invalid",
+        )
    return payload
+
+
+def clear_heaven_knowledge_cache() -> None:
+    _knowledge_catalog.cache_clear()
@@ -0,0 +1,202 @@
+"""Auditable recent-trading-day snapshot backfill helpers.
+
+Planning and backup stay free of provider imports so feature boundary tests remain green.
+The service layer supplies open trading dates from the live calendar and executes sync.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Any, Iterable
+
+
+MAX_RANGE_TRADING_DAYS = 15
+MAX_RECENT_TRADING_DAYS = 60
+DEFAULT_RECENT_TRADING_DAYS = 60
+
+# Tables touched by a successful historical dashboard sync. User / token / model
+# tables must never appear here.
+SNAPSHOT_BACKFILL_WRITE_TABLES = frozenset(
+    {
+        "dashboard_snapshots",
+        "data_snapshots",
+        "sync_runs",
+    }
+)
+
+
+def clamp_recent_lookback(lookback: int) -> int:
+    value = int(lookback)
+    if value < 1:
+        raise ValueError("回补交易日数量至少为 1。")
+    if value > MAX_RECENT_TRADING_DAYS:
+        raise ValueError(f"单次最多回补最近 {MAX_RECENT_TRADING_DAYS} 个交易日。")
+    return value
+
+
+def calendar_window_start(end_date: str, lookback: int) -> str:
+    """Natural-day lower bound large enough to cover lookback open sessions."""
+    end = datetime.strptime(end_date, "%Y%m%d").date()
+    span = max(40, int(lookback * 2) + 20)
+    return (end - timedelta(days=span)).strftime("%Y%m%d")
+
+
+def select_open_trade_dates(
+    calendar_rows: Iterable[dict[str, Any]],
+    end_date: str,
+    lookback: int,
+) -> list[str]:
+    """Pick the last ``lookback`` open SSE sessions on or before ``end_date``."""
+    lookback = clamp_recent_lookback(lookback)
+    end = normalize_compact_date(end_date)
+    open_dates = sorted(
+        {
+            normalize_compact_date(str(row.get("cal_date") or ""))
+            for row in calendar_rows
+            if int(row.get("is_open") or 0) == 1 and row.get("cal_date")
+        }
+    )
+    open_dates = [item for item in open_dates if item <= end]
+    if not open_dates:
+        raise ValueError("交易日历未返回可用交易日，请检查行情 Token。")
+    return open_dates[-lookback:]
+
+
+def select_open_trade_dates_in_range(
+    calendar_rows: Iterable[dict[str, Any]],
+    start_date: str,
+    end_date: str,
+    *,
+    maximum: int = MAX_RANGE_TRADING_DAYS,
+) -> tuple[list[str], list[str]]:
+    """Return (open_dates, skipped_non_trading_days) inside an inclusive range."""
+    start = normalize_compact_date(start_date)
+    end = normalize_compact_date(end_date)
+    if start > end:
+        raise ValueError("开始日期不能晚于结束日期。")
+    open_set = {
+        normalize_compact_date(str(row.get("cal_date") or ""))
+        for row in calendar_rows
+        if int(row.get("is_open") or 0) == 1 and row.get("cal_date")
+    }
+    open_dates: list[str] = []
+    skipped: list[str] = []
+    cursor = datetime.strptime(start, "%Y%m%d").date()
+    last = datetime.strptime(end, "%Y%m%d").date()
+    while cursor <= last:
+        compact = cursor.strftime("%Y%m%d")
+        if compact in open_set:
+            open_dates.append(compact)
+        else:
+            skipped.append(compact)
+        cursor += timedelta(days=1)
+    if len(open_dates) > maximum:
+        raise ValueError(f"单次最多回补 {maximum} 个交易日。")
+    return open_dates, skipped
+
+
+def classify_snapshot_coverage(
+    trade_dates: list[str],
+    existing_dates: Iterable[str],
+) -> dict[str, Any]:
+    present_set = {
+        normalize_compact_date(item)
+        for item in existing_dates
+        if item
+    }
+    present = [item for item in trade_dates if item in present_set]
+    missing = [item for item in trade_dates if item not in present_set]
+    return {
+        "trade_dates": list(trade_dates),
+        "present": present,
+        "missing": missing,
+        "present_count": len(present),
+        "missing_count": len(missing),
+    }
+
+
+def create_sqlite_backup(
+    source_path: Path,
+    backup_dir: Path,
+    *,
+    label: str = "pre-backfill",
+    stamped_at: datetime | None = None,
+) -> Path:
+    """Create a timestamped SQLite backup via the native backup API."""
+    source = Path(source_path)
+    if not source.exists():
+        raise FileNotFoundError(f"数据库不存在：{source}")
+    stamp = (stamped_at or datetime.now().astimezone()).strftime("%Y%m%d-%H%M%S")
+    safe_label = "".join(ch if ch.isalnum() or ch in "-_" else "-" for ch in label).strip("-") or "backup"
+    backup_dir = Path(backup_dir)
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    target = backup_dir / f"review-{safe_label}-{stamp}.db"
+    source_conn = sqlite3.connect(f"file:{source}?mode=ro", uri=True)
+    try:
+        target_conn = sqlite3.connect(target)
+        try:
+            source_conn.backup(target_conn)
+            target_conn.commit()
+        finally:
+            target_conn.close()
+    finally:
+        source_conn.close()
+    return target
+
+
+def display_date(compact: str) -> str:
+    value = normalize_compact_date(compact)
+    return f"{value[:4]}-{value[4:6]}-{value[6:8]}"
+
+
+def normalize_compact_date(value: str) -> str:
+    compact = str(value or "").replace("-", "").strip()
+    if len(compact) != 8 or not compact.isdigit():
+        raise ValueError("日期格式应为 YYYY-MM-DD。")
+    datetime.strptime(compact, "%Y%m%d")
+    return compact
+
+
+def build_backfill_audit(
+    *,
+    mode: str,
+    end_date: str,
+    lookback: int | None,
+    coverage: dict[str, Any],
+    skipped_non_trading_days: list[str] | None = None,
+    backup_path: str | None = None,
+    dry_run: bool = False,
+    results: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    results = list(results or [])
+    succeeded = [row for row in results if row.get("status") == "success"]
+    skipped = [row for row in results if row.get("status") == "skipped"]
+    failed = [row for row in results if row.get("status") == "failed"]
+    return {
+        "ok": not failed,
+        "mode": mode,
+        "dry_run": dry_run,
+        "end_date": display_date(end_date),
+        "lookback": lookback,
+        "backup_path": backup_path,
+        "write_tables": sorted(SNAPSHOT_BACKFILL_WRITE_TABLES),
+        "trade_dates": [display_date(item) for item in coverage.get("trade_dates") or []],
+        "present": [display_date(item) for item in coverage.get("present") or []],
+        "missing": [display_date(item) for item in coverage.get("missing") or []],
+        "skipped_non_trading_days": [
+            display_date(item) for item in (skipped_non_trading_days or [])
+        ],
+        "present_count": int(coverage.get("present_count") or 0),
+        "missing_count": int(coverage.get("missing_count") or 0),
+        "results": results,
+        "succeeded_count": len(succeeded),
+        "skipped_count": len(skipped),
+        "failed_count": len(failed),
+        "created_dates": [
+            str(row.get("trade_date") or "")
+            for row in succeeded
+            if row.get("action") == "created"
+        ],
+    }
@@ -227,6 +227,31 @@ class MarketRepositoryMixin:
            result.append(payload)
        return result

+    def list_snapshot_trade_dates(
+        self,
+        start_date: str = "",
+        end_date: str = "",
+    ) -> list[str]:
+        clauses: list[str] = []
+        parameters: list[Any] = []
+        if start_date:
+            clauses.append("trade_date >= ?")
+            parameters.append(start_date)
+        if end_date:
+            clauses.append("trade_date <= ?")
+            parameters.append(end_date)
+        where = f"WHERE {' AND '.join(clauses)}" if clauses else ""
+        with self.connect() as connection:
+            rows = connection.execute(
+                f"""
+                SELECT trade_date FROM dashboard_snapshots
+                {where}
+                ORDER BY trade_date
+                """,
+                parameters,
+            ).fetchall()
+        return [str(row["trade_date"]) for row in rows]
+
    def start_sync(self, trade_date: str, source: str) -> int:
        started_at = datetime.now().astimezone().isoformat(timespec="seconds")
        with self.connect() as connection:
@@ -3,9 +3,11 @@ from __future__ import annotations
 import copy
 import re
 from datetime import date, datetime, time as dt_time, timedelta
+from pathlib import Path
 from typing import Any

 from backend.bootstrap.config import (
+    DATA_DIR,
    normalize_date,
    tushare_code,
    validate_stock_code,
@@ -13,6 +15,17 @@ from backend.bootstrap.config import (
 )
 from backend.data.providers.ifind_client import IfindError
 from backend.data.providers.tushare_client import TushareClient, TushareError
+from backend.features.market.backfill_history import (
+    DEFAULT_RECENT_TRADING_DAYS,
+    MAX_RANGE_TRADING_DAYS,
+    build_backfill_audit,
+    calendar_window_start,
+    classify_snapshot_coverage,
+    create_sqlite_backup,
+    display_date,
+    select_open_trade_dates,
+    select_open_trade_dates_in_range,
+)
 from backend.features.market.charts import ChartDataError
 from backend.features.market.insights import MarketInsightsService
 from backend.features.sentiment.engine import SENTIMENT_ENGINE_VERSION
@@ -185,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)
@@ -890,31 +908,226 @@ class MarketServiceMixin:
            "intraday": intraday_points,
        }

-    def backfill(self, start_date: str, end_date: str) -> list[dict[str, Any]]:
-        start = datetime.strptime(normalize_date(start_date), "%Y%m%d").date()
-        end = datetime.strptime(normalize_date(end_date), "%Y%m%d").date()
-        if start > end:
-            raise ValueError("开始日期不能晚于结束日期。")
-        weekdays = []
-        current = start
-        while current <= end:
-            if current.weekday() < 5:
-                weekdays.append(current)
-            current += timedelta(days=1)
-        if len(weekdays) > 15:
-            raise ValueError("单次最多回补 15 个工作日。")
-        results = []
-        for day in weekdays:
-            dashboard = self.sync_dashboard(day.strftime("%Y%m%d"))
+    def backfill(
+        self,
+        start_date: str = "",
+        end_date: str = "",
+        *,
+        lookback: int | None = None,
+        dry_run: bool = False,
+        force: bool = False,
+        create_backup: bool = True,
+    ) -> dict[str, Any]:
+        """Backfill dashboard snapshots for real trading days only.
+
+        - Date-range mode keeps the admin UI contract (max 15 open sessions).
+        - Recent mode fills the last N open sessions (default/max 60).
+        Weekends and holidays are reported as skipped non-trading days, not errors.
+        """
+        if not self.configured:
+            raise ValueError("公共行情尚未配置，无法回补历史快照。")
+        normalized_end = normalize_date(end_date or date.today().isoformat())
+        if lookback is not None or not (start_date and end_date):
+            target_lookback = (
+                DEFAULT_RECENT_TRADING_DAYS if lookback is None else int(lookback)
+            )
+            return self.backfill_recent_trading_days(
+                end_date=normalized_end,
+                lookback=target_lookback,
+                dry_run=dry_run,
+                force=force,
+                create_backup=create_backup,
+            )
+        return self._backfill_date_range(
+            start_date=normalize_date(start_date),
+            end_date=normalized_end,
+            dry_run=dry_run,
+            force=force,
+            create_backup=create_backup,
+        )
+
+    def backfill_recent_trading_days(
+        self,
+        end_date: str = "",
+        lookback: int = DEFAULT_RECENT_TRADING_DAYS,
+        *,
+        dry_run: bool = False,
+        force: bool = False,
+        create_backup: bool = True,
+    ) -> dict[str, Any]:
+        normalized_end = normalize_date(end_date or date.today().isoformat())
+        trade_dates = self._load_recent_open_trade_dates(normalized_end, lookback)
+        existing = self.database.list_snapshot_trade_dates(
+            trade_dates[0], trade_dates[-1]
+        )
+        coverage = classify_snapshot_coverage(trade_dates, existing)
+        return self._execute_snapshot_backfill(
+            mode="recent",
+            end_date=normalized_end,
+            lookback=lookback,
+            coverage=coverage,
+            skipped_non_trading_days=[],
+            dry_run=dry_run,
+            force=force,
+            create_backup=create_backup,
+        )
+
+    def _backfill_date_range(
+        self,
+        start_date: str,
+        end_date: str,
+        *,
+        dry_run: bool = False,
+        force: bool = False,
+        create_backup: bool = True,
+    ) -> dict[str, Any]:
+        window_start = calendar_window_start(end_date, MAX_RANGE_TRADING_DAYS)
+        calendar_rows = self._tushare_client().query(
+            "trade_cal",
+            {
+                "exchange": "SSE",
+                "start_date": min(window_start, start_date),
+                "end_date": end_date,
+            },
+            "cal_date,is_open,pretrade_date",
+        )
+        trade_dates, skipped = select_open_trade_dates_in_range(
+            calendar_rows,
+            start_date,
+            end_date,
+            maximum=MAX_RANGE_TRADING_DAYS,
+        )
+        if not trade_dates:
+            raise ValueError("选定区间内没有交易日，周末或节假日无需回补。")
+        existing = self.database.list_snapshot_trade_dates(trade_dates[0], trade_dates[-1])
+        coverage = classify_snapshot_coverage(trade_dates, existing)
+        return self._execute_snapshot_backfill(
+            mode="range",
+            end_date=end_date,
+            lookback=None,
+            coverage=coverage,
+            skipped_non_trading_days=skipped,
+            dry_run=dry_run,
+            force=force,
+            create_backup=create_backup,
+        )
+
+    def _load_recent_open_trade_dates(self, end_date: str, lookback: int) -> list[str]:
+        start_date = calendar_window_start(end_date, lookback)
+        calendar_rows = self._tushare_client().query(
+            "trade_cal",
+            {
+                "exchange": "SSE",
+                "start_date": start_date,
+                "end_date": end_date,
+            },
+            "cal_date,is_open,pretrade_date",
+        )
+        return select_open_trade_dates(calendar_rows, end_date, lookback)
+
+    def _execute_snapshot_backfill(
+        self,
+        *,
+        mode: str,
+        end_date: str,
+        lookback: int | None,
+        coverage: dict[str, Any],
+        skipped_non_trading_days: list[str],
+        dry_run: bool,
+        force: bool,
+        create_backup: bool,
+    ) -> dict[str, Any]:
+        targets = list(coverage["trade_dates"] if force else coverage["missing"])
+        backup_path: str | None = None
+        if create_backup and not dry_run and targets:
+            backup = create_sqlite_backup(
+                Path(self.database.path),
+                DATA_DIR / "backups",
+                label=f"pre-{mode}-backfill",
+            )
+            backup_path = str(backup)
+
+        results: list[dict[str, Any]] = []
+        if dry_run:
+            for trade_date in coverage["trade_dates"]:
+                exists = trade_date in coverage["present"]
+                if exists and not force:
+                    status = "skipped"
+                    action = "exists"
+                else:
+                    status = "planned"
+                    action = "refresh" if exists else "create"
+                results.append(
+                    {
+                        "requested_date": display_date(trade_date),
+                        "trade_date": display_date(trade_date),
+                        "status": status,
+                        "action": action,
+                    }
+                )
+            return build_backfill_audit(
+                mode=mode,
+                end_date=end_date,
+                lookback=lookback,
+                coverage=coverage,
+                skipped_non_trading_days=skipped_non_trading_days,
+                backup_path=backup_path,
+                dry_run=True,
+                results=results,
+            )
+
+        present_before = set(coverage["present"])
+        for trade_date in targets:
+            existed = trade_date in present_before
+            try:
+                dashboard = self.sync_dashboard(trade_date)
+                actual = normalize_date(
+                    str(dashboard.get("meta", {}).get("trade_date") or trade_date)
+                )
+                results.append(
+                    {
+                        "requested_date": display_date(trade_date),
+                        "trade_date": display_date(actual),
+                        "status": "success",
+                        "action": "refreshed" if existed else "created",
+                        "source": dashboard.get("meta", {}).get("source"),
+                        "records": self._record_count(dashboard),
+                    }
+                )
+            except Exception as exc:
+                results.append(
+                    {
+                        "requested_date": display_date(trade_date),
+                        "trade_date": display_date(trade_date),
+                        "status": "failed",
+                        "action": "refresh" if existed else "create",
+                        "error": str(exc),
+                    }
+                )
+
+        for trade_date in coverage["present"]:
+            if force:
+                continue
            results.append(
                {
-                    "requested_date": day.isoformat(),
-                    "trade_date": dashboard["meta"]["trade_date"],
-                    "source": dashboard["meta"]["source"],
-                    "records": self._record_count(dashboard),
+                    "requested_date": display_date(trade_date),
+                    "trade_date": display_date(trade_date),
+                    "status": "skipped",
+                    "action": "exists",
                }
            )
-        return results
+
+        results.sort(key=lambda row: str(row.get("requested_date") or ""))
+        return build_backfill_audit(
+            mode=mode,
+            end_date=end_date,
+            lookback=lookback,
+            coverage=coverage,
+            skipped_non_trading_days=skipped_non_trading_days,
+            backup_path=backup_path,
+            dry_run=False,
+            results=results,
+        )

    def _stock_identity(self, code: str, trade_date: str) -> tuple[str, str]:
        snapshot = self.database.get_snapshot(trade_date) or {}
@@ -955,4 +1168,3 @@ class MarketServiceMixin:
            len(dashboard.get(key) or [])
            for key in ("limits", "broken", "down_limits", "yesterday_limits")
        )
-
@@ -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,
@@ -29,11 +29,17 @@ class SystemRoutesMixin:
    def backfill_data(self) -> None:
        try:
            body = self.read_json_body()
-            results = self.application_service.backfill(
+            lookback_raw = body.get("lookback")
+            lookback = int(lookback_raw) if lookback_raw not in (None, "") else None
+            audit = self.application_service.backfill(
                str(body.get("start_date") or ""),
                str(body.get("end_date") or ""),
+                lookback=lookback,
+                dry_run=bool(body.get("dry_run")),
+                force=bool(body.get("force")),
+                create_backup=body.get("create_backup", True) is not False,
            )
-            self.send_json({"ok": True, "results": results})
+            self.send_json({"ok": True, **audit, "results": audit.get("results") or []})
        except ValueError as exc:
            self.send_json({"error": str(exc)}, HTTPStatus.BAD_REQUEST)
        except Exception as exc:
@@ -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 (
@@ -372,9 +372,9 @@
  "css_layers": [
    "/shared/tokens.css?v=20260820-3",
    "/shared/base.css?v=20260806-1",
-    "/shared/shell.css?v=20260820-8",
+    "/shared/shell.css?v=20260827-hel183",
    "/shared/auth.css?v=20260820-5",
-    "/shared/components/controls.css?v=20260820-2",
+    "/shared/components/controls.css?v=20260827-hel183",
    "/shared/components/navigation.css?v=20260820-1",
    "/shared/components/cards.css?v=20260820-1",
    "/shared/components/tables.css?v=20260820-1",
@@ -390,8 +390,8 @@
    "/pages/popularity/foundation.css?v=20260820-1",
    "/pages/dragon-tiger/foundation.css?v=20260820-1",
    "/pages/screener/foundation.css?v=20260820-4",
-    "/pages/mentor/foundation.css?v=20260820-2",
-    "/pages/heaven/foundation.css?v=20260806-2",
+    "/pages/mentor/foundation.css?v=20260827-hel183",
+    "/pages/heaven/foundation.css?v=20260827-hel183",
    "/pages/review/foundation.css?v=20260820-4"
  ],
  "frontend_composition": {
@@ -436,8 +436,8 @@
  "code_hotspots": [
    {
      "path": "frontend/pages/heaven/foundation.css",
-      "bytes": 185936,
-      "lines": 11734
+      "bytes": 182616,
+      "lines": 11494
    },
    {
      "path": "frontend/pages/screener/foundation.css",
@@ -446,13 +446,13 @@
    },
    {
      "path": "frontend/pages/heaven/page.js",
-      "bytes": 97189,
-      "lines": 2069
+      "bytes": 97268,
+      "lines": 2070
    },
    {
      "path": "frontend/shared/shell.css",
-      "bytes": 63550,
-      "lines": 3757
+      "bytes": 63659,
+      "lines": 3763
    },
    {
      "path": "backend/features/heaven/engine.py",
@@ -461,8 +461,8 @@
    },
    {
      "path": "frontend/index.html",
-      "bytes": 47871,
-      "lines": 661
+      "bytes": 48077,
+      "lines": 662
    },
    {
      "path": "backend/features/screener/catalog.py",
@@ -486,8 +486,8 @@
    },
    {
      "path": "backend/data/providers/tushare_dashboard.py",
-      "bytes": 28051,
-      "lines": 644
+      "bytes": 28234,
+      "lines": 648
    },
    {
      "path": "backend/data/providers/tushare_industries.py",
@@ -501,8 +501,8 @@
    },
    {
      "path": "frontend/pages/heaven/page.html",
-      "bytes": 19747,
-      "lines": 262
+      "bytes": 19885,
+      "lines": 269
    },
    {
      "path": "frontend/pages/screener/page.html",
@@ -541,8 +541,8 @@
    },
    {
      "path": "frontend/shared/admin.js",
-      "bytes": 14145,
-      "lines": 261
+      "bytes": 14410,
+      "lines": 268
    },
    {
      "path": "backend/features/heaven/market_context.py",
@@ -554,6 +554,11 @@
      "bytes": 13176,
      "lines": 293
    },
+    {
+      "path": "frontend/shared/dashboard.js",
+      "bytes": 12894,
+      "lines": 274
+    },
    {
      "path": "backend/features/market/insights_auction_data.py",
      "bytes": 12829,
@@ -574,11 +579,6 @@
      "bytes": 10539,
      "lines": 244
    },
-    {
-      "path": "frontend/shared/dashboard.js",
-      "bytes": 9993,
-      "lines": 220
-    },
    {
      "path": "backend/data/providers/tushare_sectors.py",
      "bytes": 9876,
@@ -769,6 +769,11 @@
      "bytes": 2299,
      "lines": 57
    },
+    {
+      "path": "backend/jobs/service.py",
+      "bytes": 2219,
+      "lines": 60
+    },
    {
      "path": "backend/features/screener/regime.py",
      "bytes": 2202,
@@ -800,9 +805,9 @@
      "lines": 45
    },
    {
-      "path": "backend/jobs/service.py",
-      "bytes": 1746,
-      "lines": 49
+      "path": "backend/features/system/routes.py",
+      "bytes": 1791,
+      "lines": 46
    },
    {
      "path": "backend/features/alerts/routes.py",
@@ -829,11 +834,6 @@
      "bytes": 1455,
      "lines": 48
    },
-    {
-      "path": "backend/features/system/routes.py",
-      "bytes": 1423,
-      "lines": 40
-    },
    {
      "path": "backend/features/themes/routes.py",
      "bytes": 1337,
@@ -0,0 +1,69 @@
+# 行情历史补档（最近 60 个交易日）
+
+用于修复 `dashboard_snapshots` 断档导致情绪周期 / 主题轮动 / 智能选股只剩当天的问题。
+保留 `latest_contiguous_history` 连续性规则；通过真实交易日历回补缺失交易日快照。
+
+## 适用场景
+
+- 库中已有稀疏历史快照，但最近一个真实交易日缺失，接口 `available_days=1`。
+- 需要可重复执行、可审计、可回退的补档，而不是迁库或放宽算法。
+
+## 前置
+
+1. 使用与线上一致的代码分支。
+2. 管理员账号已配置可用的公共 Tushare Token。
+3. 只操作目标环境自己的 `data/review.db`；禁止 `.36` 与 `.11` 互拷。
+
+## 上线步骤（总工执行）
+
+在目标环境容器内执行（应用根目录；宿主机也可直接跑，脚本已自带仓库根 `sys.path` 引导）：
+
+```bash
+# 1) 只读规划：区分已有、真正缺档；不会写入
+docker compose exec xiaobai-review python tools/backfill_recent_snapshots.py --account <管理员账号> --lookback 60 --dry-run --json
+
+# 2) 正式补档：先走 SQLite backup API 写 data/backups/review-pre-recent-backfill-*.db
+#    再对缺失交易日调用现有 sync_dashboard
+docker compose exec xiaobai-review python tools/backfill_recent_snapshots.py --account <管理员账号> --lookback 60 --json
+
+# 3) 验证
+#    GET /api/sentiment/history?trade_date=YYYY-MM-DD&limit=60
+#    期望 available_days >= 20，且不再只有 1 天
+```
+
+管理端日期区间回补（`/api/backfill`）已改为只处理交易日历中的开市日，周末/节假日会进入
+`skipped_non_trading_days`，不再当成错误；单次仍限制 15 个交易日。最近 60 日请用本工具。
+
+## 写入边界
+
+只会通过现有同步路径写入：
+
+- `dashboard_snapshots`
+- 同步审计表 `sync_runs`
+- 必要时的 `data_snapshots`（仅当请求日被解析到其他交易日）
+
+不得改动用户、Token、模型绑定或系统配置表。
+
+## 回滚
+
+1. 优先按审计结果的 `created_dates` 精确删除新增行：
+
+```sql
+DELETE FROM dashboard_snapshots WHERE trade_date IN ('YYYYMMDD', ...);
+```
+
+2. 若需整库回退，停止写入后用补档前备份覆盖：
+
+```bash
+# 示例：把 data/backups/review-pre-recent-backfill-YYYYMMDD-HHMMSS.db
+# 复制回 data/review.db 后重启容器
+```
+
+3. 代码回退：对该提交执行 Git revert 后重新部署镜像。
+
+## 验收要点
+
+- dry-run 与正式执行可重复跑；已有交易日默认跳过。
+- 周末、节假日出现在 `skipped_non_trading_days`，不计入失败。
+- 部分交易日同步失败时，其他日期仍会继续，并在审计结果中标 `failed`。
+- 情绪周期、主题轮动 9 列、智能选股置信度随连续交易日恢复。
@@ -34,9 +34,9 @@
  </script>
  <link rel="stylesheet" href="/shared/tokens.css?v=20260820-3">
  <link rel="stylesheet" href="/shared/base.css?v=20260806-1">
-  <link rel="stylesheet" href="/shared/shell.css?v=20260820-8">
+  <link rel="stylesheet" href="/shared/shell.css?v=20260827-hel183">
  <link rel="stylesheet" href="/shared/auth.css?v=20260820-5">
-  <link rel="stylesheet" href="/shared/components/controls.css?v=20260820-2">
+  <link rel="stylesheet" href="/shared/components/controls.css?v=20260827-hel183">
  <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">
@@ -52,8 +52,8 @@
  <link rel="stylesheet" href="/pages/popularity/foundation.css?v=20260820-1">
  <link rel="stylesheet" href="/pages/dragon-tiger/foundation.css?v=20260820-1">
  <link rel="stylesheet" href="/pages/screener/foundation.css?v=20260820-4">
-  <link rel="stylesheet" href="/pages/mentor/foundation.css?v=20260820-2">
-  <link rel="stylesheet" href="/pages/heaven/foundation.css?v=20260806-2">
+  <link rel="stylesheet" href="/pages/mentor/foundation.css?v=20260827-hel183">
+  <link rel="stylesheet" href="/pages/heaven/foundation.css?v=20260827-hel183">
  <link rel="stylesheet" href="/pages/review/foundation.css?v=20260820-4">
 </head>
 <body>
@@ -609,6 +609,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">
@@ -93,28 +93,6 @@ body[data-active-view="heavenView"] .workspace-view {
  display: none;
 }

-:where(#heavenView) .heaven-tabs {
-  display: flex;
-
-  border-bottom: 1px solid var(--line);
-}
-
-:where(#heavenView) .heaven-tab {
-  border-bottom: 3px solid transparent;
-
-  background: transparent;
-
-  cursor: pointer;
-}
-
-:where(#heavenView) .heaven-tab.active {
-  border-bottom-color: var(--coral);
-}
-
-:where(#heavenView) .heaven-tab:hover {
-  border-bottom-color: var(--coral);
-}
-
 :where(#heavenView) .heaven-panel {
  display: none;
 }
@@ -1875,60 +1853,6 @@ body[data-active-view="heavenView"] .workspace-view {
  color: var(--heaven-ink-faint);
 }

-#heavenView .heaven-tab {
-  font-family: var(--heaven-serif);
-
-  height: 52px;
-
-  position: relative;
-
-  padding: 0px 2px;
-
-  border: 0px;
-
-  color: var(--heaven-ink-soft);
-
-  font-size: 14px;
-
-  font-weight: 600;
-}
-
-#heavenView .heaven-tab::after {
-  content: "";
-
-  position: absolute;
-
-  right: 0px;
-
-  bottom: 0px;
-
-  left: 0px;
-
-  height: 2px;
-
-  background: var(--heaven-cinnabar);
-
-  opacity: 0;
-
-  transform: scaleX(0.3);
-
-  transition: opacity 220ms ease, transform 260ms var(--ease-out);
-}
-
-#heavenView .heaven-tab.active {
-  color: var(--heaven-ink);
-}
-
-#heavenView .heaven-tab:hover {
-  color: var(--heaven-ink);
-}
-
-#heavenView .heaven-tab.active::after {
-  opacity: 1;
-
-  transform: scaleX(1);
-}
-
 :where(#heavenView) .heaven-proverb {
  margin: 0px;

@@ -1960,7 +1884,7 @@ body[data-active-view="heavenView"] .workspace-view {
 }

 #heavenView .button:focus-visible,
-#heavenView .heaven-tab:focus-visible,
+#heavenView .segment:focus-visible,
 #heavenView summary:focus-visible {
  outline: 2px solid var(--heaven-cinnabar);

@@ -2623,12 +2547,6 @@ body[data-active-view="heavenView"] .workspace-view {
    padding: 0px 14px;
  }

-  #heavenView .heaven-tabs {
-    gap: 22px;
-
-    padding: 0px 14px;
-  }
-
  .heaven-proverb {
    padding: 8px 14px;

@@ -3093,7 +3011,7 @@ body[data-active-view="heavenView"] .workspace-view {

 #heavenView.heaven-data-loading .heaven-panel,
 #heavenView.heaven-data-loading .heaven-proverb,
-#heavenView.heaven-data-loading .heaven-tabs {
+#heavenView.heaven-data-loading .heaven-page-head {
  opacity: 0.42;

  pointer-events: none;
@@ -3695,7 +3613,7 @@ body[data-active-view="heavenView"] .workspace-view {
@media (max-width: 900px) {
  #heavenView .heaven-panel > ,
 #heavenView .heaven-proverb,
-#heavenView .heaven-tabs,
+#heavenView .heaven-page-head,
 #heavenView .heaven-toolbar {
    width: min(100% - 28px, 1280px);
  }
@@ -3746,22 +3664,6 @@ body[data-active-view="heavenView"] .workspace-view {
    display: none;
  }

-  #heavenView .heaven-tabs {
-    display: grid;
-
-    grid-template-columns: repeat(3, minmax(0px, 1fr));
-
-    gap: 0px;
-
-    padding: 0px;
-  }
-
-  #heavenView .heaven-tab {
-    width: 100%;
-
-    min-width: 0px;
-  }
-
  #heavenFortunePanel .fortune-heading {
    display: flex;

@@ -3867,18 +3769,6 @@ body[data-active-view="heavenView"] .workspace-view {
 }

@media (max-width: 520px) {
-  .heaven-tabs {
-    gap: 0px;
-
-    padding: 0px 8px;
-  }
-
-  .heaven-tab {
-    min-width: 0px;
-
-    flex: 1 1 0%;
-  }
-
  .heaven-controls {
    grid-template-columns: 1fr;

@@ -6232,26 +6122,6 @@ body[data-active-view="heavenView"] .workspace-view {
  padding: 12px 20px;
 }

-#heavenView .heaven-tabs {
-  align-items: stretch;
-
-  gap: 30px;
-
-  border-color: var(--heaven-rule);
-
-  background: rgba(253, 252, 248, 0.96);
-
-  width: min(100% - 40px, 1280px);
-
-  margin-right: auto;
-
-  margin-left: auto;
-
-  min-height: 54px;
-
-  padding: 0px 20px;
-}
-
 #heavenView .heaven-proverb {
  margin-right: auto;

@@ -6297,12 +6167,6 @@ body[data-active-view="heavenView"] .workspace-view {
    padding: 10px 14px;
  }

-  #heavenView .heaven-tabs {
-    min-height: 52px;
-
-    padding: 0px 14px;
-  }
-
  #heavenView .heaven-proverb {
    padding: 9px 14px;
  }
@@ -6668,18 +6532,6 @@ body[data-active-view="heavenView"] .workspace-view {
  color: var(--wt-faint);
 }

-:root[data-theme="light"] #heavenView .wt-tabs .wt-tab {
-  color: var(--wt-muted);
-}
-
-:root[data-theme="light"] #heavenView .wt-tabs .wt-tab small {
-  color: var(--wt-faint);
-}
-
-:root[data-theme="light"] #heavenView .wt-tabs .wt-tab.on {
-  color: var(--wt-gold-bright);
-}
-
 :root[data-theme="light"] #heavenView .wt-empty {
  color: var(--wt-muted);
 }
@@ -7128,88 +6980,6 @@ body[data-active-view="heavenView"] .workspace-view {
    letter-spacing: 4px;
  }

-  .wt-tabs {
-    display: flex;
-
-    justify-content: center;
-
-    gap: 34px;
-
-    margin-top: 20px;
-  }
-
-  .wt-tabs .wt-tab {
-    position: relative;
-
-    padding: 8px 4px;
-
-    border: 0px;
-
-    background: transparent;
-
-    color: rgba(216, 210, 189, 0.5);
-
-    font-size: 15px;
-
-    letter-spacing: 3px;
-
-    transition: color 0.2s;
-  }
-
-  .wt-tabs .wt-tab small {
-    display: block;
-
-    margin-top: 3px;
-
-    color: rgba(216, 210, 189, 0.3);
-
-    font-family: inherit;
-
-    font-size: 10px;
-
-    letter-spacing: 1px;
-  }
-
-  .wt-tabs .wt-tab::after {
-    content: "";
-
-    position: absolute;
-
-    bottom: -2px;
-
-    left: 50%;
-
-    width: 0px;
-
-    height: 1.5px;
-
-    background: var(--wt-gold);
-
-    transform: translateX(-50%);
-
-    transition: 0.25s;
-  }
-
-  .wt-tabs .wt-tab.on {
-    color: var(--wt-gold-bright);
-  }
-
-  .wt-tabs .wt-tab.on::after {
-    width: 100%;
-  }
-
-  .wt-tabs .wt-tab:disabled {
-    cursor: default;
-  }
-
-  .wt-tabs .wt-tab:focus {
-    outline: none;
-  }
-
-  .wt-tabs .wt-tab:focus-visible {
-    box-shadow: rgba(201, 165, 92, 0.45) 0px 2px 0px;
-  }
-
  .heaven-proverb {
    margin: 8px 0px 0px;

@@ -9072,16 +8842,6 @@ body[data-active-view="heavenView"] .workspace-view {
      gap: 5px;
    }

-    .wt-tabs {
-      gap: 16px;
-    }
-
-    .wt-tabs .wt-tab {
-      font-size: 13px;
-
-      letter-spacing: 2px;
-    }
-
    .heaven-proverb {
      text-align: center;
    }
@@ -1,16 +1,23 @@
    <section id="heavenView" class="workspace-view member-feature-view heaven-shell wt">
      <div class="member-gate" hidden><div class="member-gate-icon"><i data-lucide="lock-keyhole"></i></div><div><strong>问天仅对会员开放</strong><span>开通会员后可使用观势、观气、观心及平台解读。会员状态可从顶部账号标识进入。</span></div></div>
+      <div class="section-toolbar redesigned-page-head heaven-page-head">
+        <div class="section-title-group">
+          <h2>问天</h2>
+          <span class="section-subtitle"><b id="heavenDataDate">--</b></span>
+        </div>
+        <div class="toolbar-controls">
+          <div class="segmented" role="group" aria-label="问天模块">
+            <button class="segment active on" type="button" data-heaven-panel="trend" aria-current="page">观势</button>
+            <button class="segment" type="button" data-heaven-panel="fortune">观气</button>
+            <button class="segment" type="button" data-heaven-panel="heart">观心</button>
+          </div>
+        </div>
+      </div>
      <header class="wt-head">
        <div class="wt-title-line">
          <h1 class="wt-serif">问 天</h1>
-          <span id="heavenDataDate">--</span>
        </div>
        <div class="verse wt-serif">观天之道 · 执天之行</div>
-        <nav class="wt-tabs" aria-label="问天模块">
-          <button class="wt-tab wt-serif on" type="button" data-heaven-panel="trend" aria-current="page">观势<small>三才六爻 · 量化成卦</small></button>
-          <button class="wt-tab wt-serif" type="button" data-heaven-panel="fortune">观气<small>五运六气 · 日辰生克</small></button>
-          <button class="wt-tab wt-serif" type="button" data-heaven-panel="heart">观心<small>静心占卜 · 第一念</small></button>
-        </nav>
      </header>
      <p class="heaven-proverb wt-serif">遇事不决可问春风，春风不语即随本心</p>
      <div id="heavenNotice" class="inline-notice" role="status" hidden></div>
@@ -1363,7 +1363,8 @@ async function interpretHeaven(mode) {
  } catch (error) {
    stopHeavenReadingAnimation();
    state.heavenReadingLoading = false;
-    state.heavenReadingError = error.message || "问天解读失败";
+    const detail = error?.payload?.message || error?.payload?.error || error.message;
+    state.heavenReadingError = detail || "问天解读失败";
    renderHeavenReadingDialog();
    showHeavenNotice(state.heavenReadingError);
    showToast(state.heavenReadingError);
@@ -49,7 +49,7 @@ body[data-active-view="mentorView"] .app-page-context span {
  height: 100%;
  min-height: 0;
  flex-direction: column;
-  padding: 0;
+  padding: var(--page-pad-y) 0 0;
  color: var(--qp-text-1);
  font-family: "PingFang SC", "Microsoft YaHei", system-ui, sans-serif;
 }
@@ -7,7 +7,14 @@ async function backfillData() {
      start_date: document.querySelector("#backfillStart").value,
      end_date: document.querySelector("#backfillEnd").value,
    });
-    showToast(`历史回补完成，共处理 ${payload.results.length} 个工作日`);
+    const failed = (payload.failed_count || 0);
+    const skipped = (payload.skipped_non_trading_days || []).length;
+    const suffix = failed
+      ? `，失败 ${failed} 个`
+      : skipped
+        ? `，跳过 ${skipped} 个非交易日`
+        : "";
+    showToast(`历史回补完成，共处理 ${payload.results.length} 个交易日${suffix}`);
    state.sentimentHistory = null;
    state.sentimentHistoryKey = "";
    if (state.activeView === "sentimentCycleView") {
@@ -46,12 +46,29 @@
    }
  }

+  function readableRequestError(error) {
+    const message = String(error?.message || "");
+    if (
+      error instanceof TypeError
+      || /failed to fetch|networkerror|load failed|network request failed/i.test(message)
+    ) {
+      return "网络请求失败，服务暂时不可用，请稍后重试。";
+    }
+    return message || "请求失败";
+  }
+
  async function request(url, method = "GET", body = null, options = {}) {
-    const response = await fetch(url, requestOptions(method, body, options.signal));
+    let response;
+    try {
+      response = await fetch(url, requestOptions(method, body, options.signal));
+    } catch (error) {
+      throw new ApiError(readableRequestError(error), 0, null);
+    }
    const payload = await parseJson(response);
    handleUnauthorized(response, url);
    if (!response.ok || payload.error) {
-      throw new ApiError(payload.error || "请求失败", response.status, payload);
+      const message = payload.message || payload.error || "请求失败";
+      throw new ApiError(message, response.status, payload);
    }
    return payload;
  }
@@ -471,6 +471,32 @@
  line-height: 1.6;
 }

+.admin-refresh-status {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  margin-top: 12px;
+  padding: 10px 12px;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  background: var(--surface-muted);
+  color: var(--text-muted);
+  font-size: 12px;
+  line-height: 1.55;
+}
+
+.admin-refresh-status svg {
+  flex: 0 0 auto;
+  width: 15px;
+  height: 15px;
+  margin-top: 2px;
+}
+
+.admin-refresh-status[data-tone="running"] { color: var(--primary); }
+.admin-refresh-status[data-tone="success"] { color: var(--down); }
+.admin-refresh-status[data-tone="warning"] { color: var(--warning); }
+.admin-refresh-status[data-tone="failure"] { color: var(--up); }
+
 .account-button > span {
  flex: 0 0 auto;

@@ -660,7 +660,9 @@ body.sidebar-collapsed .sidebar-collapse-button .lucide {

  text-align: left;

-  min-height: 38px;
+  height: var(--size-statusbar);
+
+  min-height: var(--size-statusbar);

  display: flex;

@@ -670,7 +672,7 @@ body.sidebar-collapsed .sidebar-collapse-button .lucide {

  margin: auto -8px -8px;

-  padding: 10px 16px;
+  padding: 0 16px;

  border-right: 0px;

@@ -691,6 +693,12 @@ body.sidebar-collapsed .sidebar-collapse-button .lucide {
  font-size: 12px;
 }

+.sidebar-collapse-button .lucide {
+  width: 14px;
+
+  height: 14px;
+}
+
 body.sidebar-collapsed .sidebar-collapse-button span {
  display: none;
 }
@@ -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 });
-    showToast(payload.message || "后台刷新已提交");
-    setStatus("后台刷新运行中，当前页面保持不变");
+    const payload = await apiRequest("/api/admin/refresh", "POST", { trade_date: requestedDate });
+    if (!payload.started || !payload.job_key) {
+      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;
@@ -1294,7 +1294,9 @@ body.sidebar-collapsed {
 }

 .sidebar-brand {
-  min-height: 55px;
+  height: var(--size-topbar);
+
+  min-height: var(--size-topbar);

  display: flex;

@@ -1304,7 +1306,7 @@ body.sidebar-collapsed {

  margin: 0px -8px 7px;

-  padding: 0px 16px;
+  padding: 0 16px;

  border-bottom: 1px solid var(--r2-line-soft);

@@ -2146,13 +2148,17 @@ body.sidebar-collapsed .status-bar {
 }

 .module-nav .sidebar-brand {
+  height: var(--size-topbar);
+
+  min-height: var(--size-topbar);
+
  display: flex;

  align-items: center;

  gap: 8px;

-  padding: 14px 16px;
+  padding: 0 16px;

  border-bottom: 1px solid var(--line-soft);
 }
@@ -3494,7 +3500,7 @@ body.sidebar-collapsed .status-bar {
  flex: 0 0 auto;
  align-items: center;
  gap: var(--header-action-gap);
-  margin-left: 0;
+  margin-left: auto;
  overflow: visible;
 }

@@ -3735,3 +3735,99 @@ test("desktop header keeps commands in view and tape text unclipped across works
  await page.screenshot({ path: path.join(shotDir, "admin-390-night.png") });
  fs.writeFileSync(path.join(shotDir, "measurements.json"), `${JSON.stringify(measurements, null, 2)}\n`);
 });
+
+test("HEL-183 heaven tools right-align and shell heights unify", async ({ page }) => {
+  const fs = require("node:fs");
+  const path = require("node:path");
+  const shotDir = path.join(__dirname, "../../runtime/hel183-shots");
+  fs.mkdirSync(shotDir, { recursive: true });
+  await page.setViewportSize({ width: 1440, height: 900 });
+  await mockApplication(page, session("admin", true));
+  await page.goto("/index.html");
+
+  const measure = () => page.evaluate(() => {
+    const box = (node) => {
+      if (!node) return null;
+      const r = node.getBoundingClientRect();
+      return { x: r.x, y: r.y, right: r.right, width: r.width, height: r.height };
+    };
+    const brand = document.querySelector(".module-nav .sidebar-brand") || document.querySelector(".sidebar-brand");
+    const header = document.querySelector(".app-header");
+    const actions = document.querySelector(".header-actions");
+    const collapse = document.querySelector(".sidebar-collapse-button");
+    const status = document.querySelector(".status-bar");
+    const overview = document.querySelector(".overview-strip");
+    const brandBox = box(brand);
+    const headerBox = box(header);
+    const actionsBox = box(actions);
+    const collapseBox = box(collapse);
+    const statusBox = box(status);
+    return {
+      brandHeight: brandBox ? Math.round(brandBox.height) : null,
+      headerHeight: headerBox ? Math.round(headerBox.height) : null,
+      brandBottom: brandBox ? Math.round(brandBox.y + brandBox.height) : null,
+      headerBottom: headerBox ? Math.round(headerBox.y + headerBox.height) : null,
+      collapseHeight: collapseBox ? Math.round(collapseBox.height) : null,
+      statusHeight: statusBox ? Math.round(statusBox.height) : null,
+      actionsNearRight: actionsBox && headerBox ? (headerBox.right - actionsBox.right) < 24 : false,
+      actionsMarginLeft: actions ? getComputedStyle(actions).marginLeft : null,
+      overviewDisplay: overview ? getComputedStyle(overview).display : null,
+      mentorPadTop: (() => {
+        const mentor = document.querySelector("#mentorView");
+        return mentor ? getComputedStyle(mentor).paddingTop : null;
+      })(),
+    };
+  });
+
+  await page.locator('[data-view="sentimentCycleView"]').first().click();
+  await expect(page.locator("#sentimentCycleView")).toHaveClass(/active-view/);
+  let geo = await measure();
+  expect(geo.brandHeight, "logo height").toBe(64);
+  expect(geo.headerHeight, "header height").toBe(64);
+  expect(geo.brandBottom, "logo/header bottom align").toBe(geo.headerBottom);
+  expect(geo.collapseHeight, "collapse height").toBe(28);
+  expect(geo.statusHeight, "status height").toBe(28);
+  expect(geo.actionsNearRight, "sentiment tools right").toBe(true);
+  await page.locator(".app-header").screenshot({ path: path.join(shotDir, "sentiment-header-day.png") });
+  await page.screenshot({ path: path.join(shotDir, "sentiment-page-day.png") });
+
+  await page.locator('[data-view="heavenView"]').first().click();
+  await expect(page.locator("#heavenView")).toHaveClass(/active-view/);
+  await expect(page.locator("#heavenView .heaven-page-head")).toBeVisible();
+  await expect(page.locator("#heavenView .heaven-page-head .segment")).toHaveCount(3);
+  geo = await measure();
+  expect(geo.overviewDisplay, "heaven hides overview").toBe("none");
+  expect(geo.actionsMarginLeft, "tools margin-left resolved").not.toBe("0px");
+  expect(Number.parseFloat(geo.actionsMarginLeft), "tools left auto gap").toBeGreaterThan(40);
+  expect(geo.actionsNearRight, "heaven tools right").toBe(true);
+  expect(geo.brandHeight).toBe(64);
+  expect(geo.collapseHeight).toBe(28);
+  await page.locator(".app-header").screenshot({ path: path.join(shotDir, "heaven-header-day.png") });
+  await page.screenshot({ path: path.join(shotDir, "heaven-page-day.png") });
+
+  await page.locator('[data-heaven-panel="fortune"]').click();
+  await expect(page.locator('[data-heaven-panel="fortune"]')).toHaveClass(/active/);
+  await expect(page.locator("#heavenFortunePanel")).toHaveClass(/active-heaven-panel/);
+
+  await page.locator('[data-view="mentorView"]').first().click();
+  await expect(page.locator("#mentorView")).toHaveClass(/active-view/);
+  geo = await measure();
+  expect(geo.mentorPadTop, "mentor top padding").toBe("14px");
+  await page.screenshot({ path: path.join(shotDir, "mentor-page-day.png") });
+
+  await page.locator("#themeToggle").click();
+  await page.locator('[data-view="heavenView"]').first().click();
+  await expect(page.locator("#heavenView")).toHaveClass(/active-view/);
+  geo = await measure();
+  expect(geo.actionsNearRight, "heaven night tools right").toBe(true);
+  expect(geo.brandHeight).toBe(64);
+  await page.locator(".app-header").screenshot({ path: path.join(shotDir, "heaven-header-night.png") });
+  await page.screenshot({ path: path.join(shotDir, "heaven-page-night.png") });
+
+  await page.locator('[data-view="sentimentCycleView"]').first().click();
+  await page.locator(".app-header").screenshot({ path: path.join(shotDir, "sentiment-header-night.png") });
+  await page.screenshot({ path: path.join(shotDir, "sentiment-page-night.png") });
+
+  await page.locator('[data-view="mentorView"]').first().click();
+  await page.screenshot({ path: path.join(shotDir, "mentor-page-night.png") });
+});
@@ -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()
@@ -1,13 +1,162 @@
 from __future__ import annotations

+import json
+import tempfile
 import unittest
+from http import HTTPStatus
+from pathlib import Path
+from unittest.mock import patch

 from backend.features.heaven.engine import build_five_phase_field, hexagram_from_lines
-from backend.features.heaven.knowledge import prepare_heaven_context
+from backend.features.heaven.http import HeavenHttpMixin
+from backend.features.heaven.knowledge import (
+    HeavenKnowledgeError,
+    clear_heaven_knowledge_cache,
+    prepare_heaven_context,
+    resolve_heaven_knowledge_path,
+    _knowledge_catalog,
+)
 from backend.features.heaven.six_yao import build_six_yao_chart


 class HeavenKnowledgeTests(unittest.TestCase):
+    def tearDown(self) -> None:
+        clear_heaven_knowledge_cache()
+
+    def test_catalog_loads_from_trusted_repo_file(self):
+        clear_heaven_knowledge_cache()
+        path = resolve_heaven_knowledge_path()
+        catalog = _knowledge_catalog()
+        self.assertTrue(path.is_file())
+        self.assertEqual(path.name, "heaven_knowledge.json")
+        self.assertTrue(str(catalog.get("version") or "").startswith("2026."))
+        self.assertIn("zhouyi", catalog["sources"])
+        self.assertIn("neijing", catalog["sources"])
+        self.assertEqual(len(catalog["fortune"]["qi"]), 6)
+        self.assertEqual(len(catalog["fortune"]["personal_relations"]), 10)
+
+    def test_missing_knowledge_file_raises_chinese_structured_error(self):
+        clear_heaven_knowledge_cache()
+        missing = Path(tempfile.mkdtemp()) / "missing-heaven_knowledge.json"
+        with patch(
+            "backend.features.heaven.knowledge.KNOWLEDGE_FILE", missing
+        ), patch(
+            "backend.features.heaven.knowledge.KNOWLEDGE_SEED_FILE",
+            missing.with_name("missing-seed.json"),
+        ):
+            with self.assertRaises(HeavenKnowledgeError) as raised:
+                _knowledge_catalog()
+        self.assertEqual(raised.exception.error_code, "heaven_knowledge_missing")
+        self.assertIn("缺失", str(raised.exception))
+
+    def test_corrupt_knowledge_json_raises_chinese_structured_error(self):
+        clear_heaven_knowledge_cache()
+        with tempfile.TemporaryDirectory() as temp_dir:
+            broken = Path(temp_dir) / "heaven_knowledge.json"
+            broken.write_text("{not-json", encoding="utf-8")
+            with patch(
+                "backend.features.heaven.knowledge.KNOWLEDGE_FILE", broken
+            ), patch(
+                "backend.features.heaven.knowledge.KNOWLEDGE_SEED_FILE",
+                Path(temp_dir) / "unused-seed.json",
+            ):
+                with self.assertRaises(HeavenKnowledgeError) as raised:
+                    _knowledge_catalog()
+        self.assertEqual(raised.exception.error_code, "heaven_knowledge_invalid")
+        self.assertIn("损坏", str(raised.exception))
+
+    def test_interpret_http_returns_structured_chinese_error_for_missing_file(self):
+        class FakeHandler(HeavenHttpMixin):
+            def __init__(self) -> None:
+                self.payload = None
+                self.status = None
+                self.application_service = type(
+                    "Svc",
+                    (),
+                    {
+                        "heaven_interpret": staticmethod(
+                            lambda _body: (_ for _ in ()).throw(
+                                HeavenKnowledgeError(
+                                    "问天知识文件缺失：未找到 heaven_knowledge.json。",
+                                    code="heaven_knowledge_missing",
+                                )
+                            )
+                        )
+                    },
+                )()
+
+            def read_json_body(self):
+                return {"mode": "trend", "trade_date": "2026-08-04"}
+
+            def send_json(self, payload, status=HTTPStatus.OK, headers=None):
+                self.payload = payload
+                self.status = status
+
+        handler = FakeHandler()
+        handler.heaven_interpret()
+        self.assertEqual(handler.status, HTTPStatus.BAD_REQUEST)
+        self.assertIn("缺失", handler.payload["error"])
+        self.assertEqual(handler.payload["code"], "heaven_knowledge_missing")
+
+    def test_interpret_http_returns_structured_chinese_error_for_corrupt_json(self):
+        class FakeHandler(HeavenHttpMixin):
+            def __init__(self) -> None:
+                self.payload = None
+                self.status = None
+                self.application_service = type(
+                    "Svc",
+                    (),
+                    {
+                        "heaven_interpret": staticmethod(
+                            lambda _body: (_ for _ in ()).throw(
+                                HeavenKnowledgeError(
+                                    "问天知识文件 JSON 损坏（heaven_knowledge.json），无法解析：第 1 行附近。",
+                                    code="heaven_knowledge_invalid",
+                                )
+                            )
+                        )
+                    },
+                )()
+
+            def read_json_body(self):
+                return {"mode": "trend", "trade_date": "2026-08-04"}
+
+            def send_json(self, payload, status=HTTPStatus.OK, headers=None):
+                self.payload = payload
+                self.status = status
+
+        handler = FakeHandler()
+        handler.heaven_interpret()
+        self.assertEqual(handler.status, HTTPStatus.BAD_REQUEST)
+        self.assertIn("损坏", handler.payload["error"])
+        self.assertEqual(handler.payload["code"], "heaven_knowledge_invalid")
+
+    def test_seed_fallback_when_data_file_missing(self):
+        clear_heaven_knowledge_cache()
+        with tempfile.TemporaryDirectory() as temp_dir:
+            seed = Path(temp_dir) / "seed.json"
+            seed.write_text(
+                json.dumps(
+                    {
+                        "version": "test-seed",
+                        "sources": {"zhouyi": {"title": "周易"}},
+                        "trend": {"method": "m", "rules": {"stable": "s", "single": "a", "multiple": "b"}},
+                        "fortune": {},
+                        "heart": {},
+                    },
+                    ensure_ascii=False,
+                ),
+                encoding="utf-8",
+            )
+            missing_data = Path(temp_dir) / "data-heaven_knowledge.json"
+            with patch(
+                "backend.features.heaven.knowledge.KNOWLEDGE_FILE", missing_data
+            ), patch(
+                "backend.features.heaven.knowledge.KNOWLEDGE_SEED_FILE", seed
+            ):
+                catalog = _knowledge_catalog()
+        self.assertEqual(catalog["version"], "test-seed")
+
    def test_fortune_context_excludes_weighted_summary_and_adds_bounded_industry_symbols(self):
        field = build_five_phase_field("2026-08-04")
        prepared = prepare_heaven_context(
@@ -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()
@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+import json
+import tempfile
+import threading
+import unittest
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from unittest.mock import patch
+
+from backend.features.market.backfill_history import (
+    build_backfill_audit,
+    classify_snapshot_coverage,
+    create_sqlite_backup,
+    select_open_trade_dates,
+    select_open_trade_dates_in_range,
+)
+from backend.features.market.service import MarketServiceMixin
+from backend.features.sentiment.engine import (
+    build_sentiment_history,
+    latest_contiguous_history,
+)
+from backend.features.sentiment.service import SentimentServiceMixin
+from database import ReviewDatabase
+
+
+def _snapshot(trade_date: str, previous_trade_date: str) -> dict[str, Any]:
+    display = f"{trade_date[:4]}-{trade_date[4:6]}-{trade_date[6:8]}"
+    previous_display = (
+        f"{previous_trade_date[:4]}-{previous_trade_date[4:6]}-{previous_trade_date[6:8]}"
+        if previous_trade_date
+        else ""
+    )
+    return {
+        "meta": {
+            "trade_date": display,
+            "previous_trade_date": previous_display,
+            "source": "tushare",
+        },
+        "overview": {
+            "up_count": 2500,
+            "down_count": 2000,
+            "flat_count": 100,
+            "amount_billion": 12000,
+            "limit_up_count": 40,
+            "limit_down_count": 5,
+            "broken_count": 10,
+            "seal_rate": 70,
+            "max_height": 3,
+            "second_board_count": 8,
+            "three_plus_count": 4,
+            "previous_limit_count": 35,
+            "previous_positive_rate": 55,
+            "average_previous_change": 1.2,
+            "median_previous_change": 0.8,
+            "advance_rate": 20,
+            "severe_loss_rate": 5,
+            "previous_down_count": 3,
+            "ladder_completeness": 60,
+            "limit_amount_billion": 300,
+        },
+        "limits": [{"code": "000001"}],
+        "broken": [],
+        "down_limits": [],
+        "yesterday_limits": [],
+    }
+
+
+class _BackfillHarness(MarketServiceMixin, SentimentServiceMixin):
+    def __init__(self, database: ReviewDatabase) -> None:
+        self.database = database
+        self.sync_lock = threading.Lock()
+        self.configured = True
+        self.token = "test-token"
+        self.current_user_id = 1
+        self._calendar_rows: list[dict[str, Any]] = []
+        self._fail_dates: set[str] = set()
+        self.sync_calls: list[str] = []
+
+    def _tushare_client(self):  # type: ignore[override]
+        harness = self
+
+        class _Client:
+            def query(self, api_name, params, fields=""):
+                assert api_name == "trade_cal"
+                start = str(params["start_date"])
+                end = str(params["end_date"])
+                return [
+                    row
+                    for row in harness._calendar_rows
+                    if start <= str(row["cal_date"]) <= end
+                ]
+
+        return _Client()
+
+    def sync_dashboard(self, trade_date: str) -> dict[str, Any]:  # type: ignore[override]
+        compact = trade_date.replace("-", "")
+        self.sync_calls.append(compact)
+        if compact in self._fail_dates:
+            raise ValueError(f"simulated failure for {compact}")
+        previous = ""
+        for row in self._calendar_rows:
+            if str(row["cal_date"]) == compact:
+                previous = str(row.get("pretrade_date") or "")
+                break
+        payload = _snapshot(compact, previous)
+        self.database.save_snapshot(compact, "tushare", payload)
+        return payload
+
+    def _apply_reason_overrides(self, dashboard: dict[str, Any]) -> dict[str, Any]:
+        return dashboard
+
+    def _with_storage(self, dashboard: dict[str, Any], cached: bool) -> dict[str, Any]:
+        return dashboard
+
+
+class BackfillHistoryHelperTests(unittest.TestCase):
+    def test_select_open_trade_dates_skips_weekends_and_holidays(self) -> None:
+        rows = [
+            {"cal_date": "20260821", "is_open": 1, "pretrade_date": "20260820"},
+            {"cal_date": "20260822", "is_open": 0, "pretrade_date": "20260821"},  # Sat
+            {"cal_date": "20260823", "is_open": 0, "pretrade_date": "20260821"},  # Sun
+            {"cal_date": "20260824", "is_open": 1, "pretrade_date": "20260821"},
+            {"cal_date": "20260825", "is_open": 1, "pretrade_date": "20260824"},
+            {"cal_date": "20260826", "is_open": 1, "pretrade_date": "20260825"},
+            {"cal_date": "20260827", "is_open": 1, "pretrade_date": "20260826"},
+        ]
+        selected = select_open_trade_dates(rows, "20260827", 4)
+        self.assertEqual(selected, ["20260824", "20260825", "20260826", "20260827"])
+
+    def test_range_mode_reports_non_trading_days_separately(self) -> None:
+        rows = [
+            {"cal_date": "20260821", "is_open": 1},
+            {"cal_date": "20260824", "is_open": 1},
+        ]
+        open_dates, skipped = select_open_trade_dates_in_range(
+            rows, "20260821", "20260824"
+        )
+        self.assertEqual(open_dates, ["20260821", "20260824"])
+        self.assertEqual(skipped, ["20260822", "20260823"])
+
+    def test_classify_snapshot_coverage_finds_real_gaps(self) -> None:
+        coverage = classify_snapshot_coverage(
+            ["20260824", "20260825", "20260826", "20260827"],
+            ["20260824", "20260827"],
+        )
+        self.assertEqual(coverage["missing"], ["20260825", "20260826"])
+        self.assertEqual(coverage["present"], ["20260824", "20260827"])
+
+
+class ContiguousHistoryGapTests(unittest.TestCase):
+    def test_missing_previous_trade_day_collapses_to_today(self) -> None:
+        payloads = [
+            _snapshot("20260824", "20260821"),
+            _snapshot("20260827", "20260826"),  # gap: 20260826 missing
+        ]
+        series = latest_contiguous_history(build_sentiment_history(payloads))
+        self.assertEqual([row["trade_date"] for row in series], ["20260827"])
+
+    def test_continuous_history_keeps_full_tail(self) -> None:
+        payloads = [
+            _snapshot("20260825", "20260824"),
+            _snapshot("20260826", "20260825"),
+            _snapshot("20260827", "20260826"),
+        ]
+        series = latest_contiguous_history(build_sentiment_history(payloads))
+        self.assertEqual(
+            [row["trade_date"] for row in series],
+            ["20260825", "20260826", "20260827"],
+        )
+
+
+class SnapshotBackfillServiceTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temporary = tempfile.TemporaryDirectory()
+        self.db_path = Path(self.temporary.name) / "review.db"
+        self.database = ReviewDatabase(self.db_path)
+        self.service = _BackfillHarness(self.database)
+        self.service._calendar_rows = [
+            {"cal_date": "20260820", "is_open": 1, "pretrade_date": "20260819"},
+            {"cal_date": "20260821", "is_open": 1, "pretrade_date": "20260820"},
+            {"cal_date": "20260822", "is_open": 0, "pretrade_date": "20260821"},
+            {"cal_date": "20260823", "is_open": 0, "pretrade_date": "20260821"},
+            {"cal_date": "20260824", "is_open": 1, "pretrade_date": "20260821"},
+            {"cal_date": "20260825", "is_open": 1, "pretrade_date": "20260824"},
+            {"cal_date": "20260826", "is_open": 1, "pretrade_date": "20260825"},
+            {"cal_date": "20260827", "is_open": 1, "pretrade_date": "20260826"},
+        ]
+        # Sparse history mimicking .11: keep 0824 and today, miss 0825/0826.
+        self.database.save_snapshot("20260824", "tushare", _snapshot("20260824", "20260821"))
+        self.database.save_snapshot("20260827", "tushare", _snapshot("20260827", "20260826"))
+
+    def tearDown(self) -> None:
+        self.temporary.cleanup()
+
+    def test_recent_backfill_fills_gap_and_restores_history(self) -> None:
+        before = self.service.sentiment_history("20260827", 20)
+        self.assertEqual(before["available_days"], 1)
+
+        with patch(
+            "backend.features.market.service.create_sqlite_backup",
+            return_value=Path(self.temporary.name) / "fake-backup.db",
+        ) as backup:
+            audit = self.service.backfill_recent_trading_days(
+                end_date="20260827",
+                lookback=4,
+                dry_run=False,
+                create_backup=True,
+            )
+
+        backup.assert_called_once()
+        self.assertEqual(sorted(self.service.sync_calls), ["20260825", "20260826"])
+        self.assertEqual(audit["missing"], ["2026-08-25", "2026-08-26"])
+        self.assertEqual(sorted(audit["created_dates"]), ["2026-08-25", "2026-08-26"])
+        after = self.service.sentiment_history("20260827", 20)
+        self.assertGreaterEqual(after["available_days"], 4)
+        self.assertEqual(
+            [row["trade_date"] for row in after["rows"]],
+            ["20260824", "20260825", "20260826", "20260827"],
+        )
+
+    def test_dry_run_does_not_write_snapshots(self) -> None:
+        audit = self.service.backfill_recent_trading_days(
+            end_date="20260827",
+            lookback=4,
+            dry_run=True,
+            create_backup=True,
+        )
+        self.assertTrue(audit["dry_run"])
+        self.assertEqual(self.service.sync_calls, [])
+        self.assertIsNone(audit["backup_path"])
+        self.assertEqual(
+            self.database.list_snapshot_trade_dates("20260824", "20260827"),
+            ["20260824", "20260827"],
+        )
+
+    def test_repeat_execution_skips_existing_days(self) -> None:
+        with patch(
+            "backend.features.market.service.create_sqlite_backup",
+            return_value=Path(self.temporary.name) / "fake-backup.db",
+        ):
+            first = self.service.backfill_recent_trading_days(
+                end_date="20260827", lookback=4
+            )
+            self.service.sync_calls.clear()
+            second = self.service.backfill_recent_trading_days(
+                end_date="20260827", lookback=4
+            )
+        self.assertEqual(first["succeeded_count"], 2)
+        self.assertEqual(self.service.sync_calls, [])
+        self.assertEqual(second["missing_count"], 0)
+        self.assertEqual(second["skipped_count"], 4)
+        self.assertIsNone(second["backup_path"])
+
+    def test_partial_failure_continues_remaining_days(self) -> None:
+        self.service._fail_dates.add("20260825")
+        with patch(
+            "backend.features.market.service.create_sqlite_backup",
+            return_value=Path(self.temporary.name) / "fake-backup.db",
+        ):
+            audit = self.service.backfill_recent_trading_days(
+                end_date="20260827", lookback=4
+            )
+        self.assertFalse(audit["ok"])
+        self.assertEqual(audit["failed_count"], 1)
+        self.assertEqual(audit["succeeded_count"], 1)
+        self.assertIn("20260826", self.database.list_snapshot_trade_dates())
+        self.assertNotIn("20260825", self.database.list_snapshot_trade_dates())
+
+    def test_range_backfill_skips_weekend_without_treating_as_error(self) -> None:
+        with patch(
+            "backend.features.market.service.create_sqlite_backup",
+            return_value=Path(self.temporary.name) / "fake-backup.db",
+        ):
+            audit = self.service.backfill(
+                start_date="2026-08-21",
+                end_date="2026-08-24",
+            )
+        self.assertEqual(audit["mode"], "range")
+        self.assertEqual(audit["skipped_non_trading_days"], ["2026-08-22", "2026-08-23"])
+        self.assertEqual(sorted(self.service.sync_calls), ["20260821"])
+        self.assertTrue(audit["ok"])
+
+    def test_sqlite_backup_api_creates_restorable_copy(self) -> None:
+        backup_dir = Path(self.temporary.name) / "backups"
+        backup = create_sqlite_backup(
+            self.db_path,
+            backup_dir,
+            label="pre-recent-backfill",
+            stamped_at=datetime(2026, 8, 27, 15, 30, 0),
+        )
+        self.assertTrue(backup.exists())
+        self.assertIn("pre-recent-backfill-20260827-153000", backup.name)
+        restored = ReviewDatabase(backup)
+        self.assertEqual(
+            restored.list_snapshot_trade_dates(),
+            ["20260824", "20260827"],
+        )
+
+    def test_audit_lists_only_snapshot_related_write_tables(self) -> None:
+        audit = build_backfill_audit(
+            mode="recent",
+            end_date="20260827",
+            lookback=60,
+            coverage={"trade_dates": [], "present": [], "missing": [], "present_count": 0, "missing_count": 0},
+        )
+        self.assertEqual(
+            audit["write_tables"],
+            ["dashboard_snapshots", "data_snapshots", "sync_runs"],
+        )
+        self.assertNotIn("users", audit["write_tables"])
+        self.assertNotIn("system_settings", audit["write_tables"])
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -17,6 +17,9 @@ registry, and verification tools.
  `backend/features/*/routes.py` owners.
 - `python tools/build_architecture_inventory.py [--check]`: generate or verify
  `config/architecture-inventory.json` from the current source tree.
+- `python tools/backfill_recent_snapshots.py --account <admin> [--lookback 60] [--dry-run]`:
+  auditable recent trading-day dashboard snapshot backfill. See
+  `docs/maintenance/行情历史补档.md`.

 `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;
@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Auditable recent trading-day dashboard snapshot backfill.
+
+Examples:
+
+  python tools/backfill_recent_snapshots.py --account admin --dry-run
+  python tools/backfill_recent_snapshots.py --account admin --lookback 60
+  python tools/backfill_recent_snapshots.py --account admin --end-date 2026-08-27 --force
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import date
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from backend.application import SERVICE
+from backend.bootstrap.config import normalize_date
+from backend.features.market.backfill_history import DEFAULT_RECENT_TRADING_DAYS
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Backfill the latest N real trading-day dashboard snapshots"
+    )
+    parser.add_argument(
+        "--account",
+        required=True,
+        help="Account that can resolve the shared Tushare token",
+    )
+    parser.add_argument(
+        "--end-date",
+        default=date.today().isoformat(),
+        help="Inclusive end date YYYY-MM-DD (default: today)",
+    )
+    parser.add_argument(
+        "--lookback",
+        type=int,
+        default=DEFAULT_RECENT_TRADING_DAYS,
+        help=f"Number of open trading days to cover (default {DEFAULT_RECENT_TRADING_DAYS}, max 60)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Plan only: classify missing gaps without writing",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Re-sync days that already have snapshots",
+    )
+    parser.add_argument(
+        "--no-backup",
+        action="store_true",
+        help="Skip the SQLite backup API step (not recommended)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print the full audit payload as JSON",
+    )
+    args = parser.parse_args()
+
+    user = SERVICE.database.user_by_username(args.account.strip())
+    if not user:
+        raise SystemExit("account not found")
+    SERVICE.bind_user(int(user["id"]))
+
+    end_date = normalize_date(args.end_date)
+    audit = SERVICE.backfill_recent_trading_days(
+        end_date=end_date,
+        lookback=args.lookback,
+        dry_run=args.dry_run,
+        force=args.force,
+        create_backup=not args.no_backup,
+    )
+
+    if args.json:
+        print(json.dumps(audit, ensure_ascii=False, indent=2))
+        raise SystemExit(0 if audit.get("ok") else 1)
+
+    print(
+        f"mode={audit['mode']} end={audit['end_date']} lookback={audit['lookback']} "
+        f"dry_run={audit['dry_run']}"
+    )
+    print(
+        f"present={audit['present_count']} missing={audit['missing_count']} "
+        f"succeeded={audit['succeeded_count']} skipped={audit['skipped_count']} "
+        f"failed={audit['failed_count']}"
+    )
+    if audit.get("backup_path"):
+        print(f"backup={audit['backup_path']}")
+    if audit.get("missing"):
+        print("missing_dates=" + ",".join(audit["missing"]))
+    if audit.get("created_dates"):
+        print("created_dates=" + ",".join(audit["created_dates"]))
+    failed = [row for row in audit.get("results") or [] if row.get("status") == "failed"]
+    for row in failed:
+        print(f"failed {row.get('requested_date')}: {row.get('error')}")
+    if not audit.get("ok"):
+        raise SystemExit(1)
+    print("backfill complete")
+
+
+if __name__ == "__main__":
+    main()
Author	SHA1	Message	Date
总管andmultica-agent	89b8d33de7	fix(HEL-164): 排除构建中的数据库备份 Co-authored-by: multica-agent <github@multica.ai>	2026-08-28 11:32:21 +00:00
总管andmultica-agent	d9ee725744	fix(HEL-164): 拒绝缓存不完整涨停快照 Co-authored-by: multica-agent <github@multica.ai>	2026-08-28 09:44:51 +00:00
总管andmultica-agent	1cb2745867	feat(HEL-164): 显示管理员刷新实际结果 Co-authored-by: multica-agent <github@multica.ai>	2026-08-28 09:29:06 +00:00
总管andmultica-agent	f27471238a	fix(HEL-164): 撤回盘后刷新改动并恢复原逻辑 Co-authored-by: multica-agent <github@multica.ai>	2026-08-28 09:05:42 +00:00
总工andmultica-agent	6d7a839202	chore(HEL-208): 刷新 architecture-inventory 以对齐 HEL-207 行情改动 Co-authored-by: multica-agent <github@multica.ai>	2026-08-28 08:09:49 +00:00
总工	fc1e5b89e4	merge(HEL-208): 集成收盘行情修复 `cf206c7` 到 .11 正式线（基于 09a935a）	2026-08-28 08:09:28 +00:00
总工 Cursor multica-agent	cf206c7de9	fix(HEL-207): 收盘后改走日线，禁止误调 rt_k，回退旧快照记失败将实时窗口与调度窗口统一到 15:05；盘后优先日线并补关闭盘后同步；沿用旧快照时 sync/job 记 failed。 Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: multica-agent <github@multica.ai>	2026-08-28 08:00:08 +00:00
总工andmultica-agent	09a935aac4	merge(HEL-193): 以 .11 线上基线 `013ed29` 整合行情历史补档 8e94c7b（HEL-190/HEL-199） - 合入 agent/agent/ebb4e3e0638a：真实交易日历补最近60日快照 + sys.path 引导返工 - architecture-inventory 于合并后重新生成 Co-authored-by: multica-agent <github@multica.ai>	2026-08-27 16:13:34 +00:00
总工 Cursor multica-agent	8e94c7b429	fix(HEL-199): 为补档工具补上仓库根 sys.path 引导使 python3 tools/backfill_recent_snapshots.py --help 在干净环境下可直接运行，并同步文档运行示例为容器内执行。 Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: multica-agent <github@multica.ai>	2026-08-27 15:12:42 +00:00
总工	013ed29ffb	merge(HEL-192): 集成问天解势修复到 .11 正式线（含 HEL-183 顶栏修复）	2026-08-27 14:58:11 +00:00
施工员 Cursor multica-agent	7ad445bc9f	fix(HEL-190): 按真实交易日历补齐最近60日快照，修复断档后只显示当天保留连续性过滤，新增可审计补档工具与备份步骤；周末/节假日与真缺档分开处理，支持重复执行与部分失败续跑。 Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: multica-agent <github@multica.ai>	2026-08-27 14:50:32 +00:00
施工员 Cursor multica-agent	ef86b31f6b	fix(HEL-191): 补回问天解势知识文件兜底并消除 Failed to fetch 宿主机 data 挂载会遮盖镜像内 heaven_knowledge.json；增加不受挂载影响的 seed，并将缺文件/坏 JSON 转为结构化中文错误，前端展示可读提示而非 Failed to fetch。 Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: multica-agent <github@multica.ai>	2026-08-27 14:47:27 +00:00
施工员 Cursor multica-agent	94e6f618c8	施工(HEL-188): 刷新 architecture-inventory 以对齐 HEL-183 运行时资源指纹 Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: multica-agent <github@multica.ai>	2026-08-27 14:05:18 +00:00
施工员 Cursor multica-agent	f68f950106	施工(HEL-183): 问天工具行右对齐并统一 logo/收起/问师顶距与页头签恢复顶栏工具行 margin-left:auto，问天隐藏行情条后仍靠右；logo 区与收起按钮对齐顶栏/状态条高度；问师恢复页顶 14px；问天三签改用全站 segmented 页头。 Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: multica-agent <github@multica.ai>	2026-08-27 13:41:23 +00:00