powerquant-cli 0.2.6__py3-none-any.whl

quant_cli/examples/full_market_screen.py

@@ -0,0 +1,189 @@
+"""全市场收盘后因子试算；只通过 SDK 读取，不发布因子、不下单。
+
+在 apps/quant_cli 运行：python -m examples.full_market_screen --day YYYY-MM-DD
+该示例使用当前修订的数据，不构成历史 PIT 回测或可成交性保证。
+"""
+
+import argparse
+import asyncio
+import csv
+import hashlib
+import json
+from collections import Counter
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from pathlib import Path
+from zoneinfo import ZoneInfo
+
+from pqdata.schema.bar_schema import BarQuery
+from quant_core.app.factor.computation.python_factor_executor import execute_python_panel
+from quant_core.app.factor.schema.factor_computation_schema import FactorComputationSpec
+from quant_core.app.factor.schema.factor_panel import FactorPanel, FactorPanelRow
+
+from quant_cli.app.data.data_dependency import build_market_query
+from quant_cli.common.utils.platform_utils import configure_utf8_output
+
+SOURCE = """def compute_panel(panel, parameters):
+    result = {}
+    for row in panel.rows:
+        f = row.fields
+        result[(row.as_of, row.instrument_id)] = (
+            f["close"] / f["open"] - 1 if row.eligible else None
+        )
+    return result
+"""
+
+
+async def run(day: date, output: Path, minimum_amount: Decimal, top: int) -> dict:
+    """固定行情修订批量读取，调用现有面板执行器并保存完整审计结果。"""
+    cn = ZoneInfo("Asia/Shanghai")
+    start = datetime.combine(day, time.min, cn)
+    end = datetime.combine(day, time.max, cn)
+    observed_at = datetime.now(cn)
+    if observed_at <= end:
+        raise ValueError("只支持已结束的历史交易日")
+    async with build_market_query() as client:
+        revision = (await client.snapshot(day, day))["canonical"]
+        catalog = await client.search_instruments(limit=10000)
+        if len(catalog) >= 10000:
+            raise ValueError("标的目录可能截断，拒绝冒充全市场")
+        stocks = [i for i in catalog if i.instrument_type == "stock"]
+        unknown_listing = [i.instrument_id for i in stocks if i.listed_date is None]
+        universe = {
+            i.instrument_id: i
+            for i in stocks
+            if i.listed_date is not None
+            and i.listed_date <= day
+            and (i.delisted_date is None or i.delisted_date >= day)
+        }
+        ids = sorted(universe)
+        bars = {}
+        for offset in range(0, len(ids), 1000):
+            query = BarQuery(
+                instrument_ids=ids[offset : offset + 1000],
+                frequency="1d",
+                start=start,
+                end=end,
+                revision=revision,
+            )
+            async for page in client.iter_bar_pages(query):
+                for bar in page.items:
+                    if bar.instrument_id in bars:
+                        raise ValueError("同一证券出现重复日线")
+                    bars[bar.instrument_id] = bar
+            print(f"已读取 {min(offset + 1000, len(ids))}/{len(ids)} 只候选", flush=True)
+        if (await client.snapshot(day, day))["canonical"] != revision:
+            raise ValueError("读取期间数据修订变化，请重新运行")
+    if not bars:
+        raise ValueError("当日无日线数据")
+    reasons = dict.fromkeys(unknown_listing, "unknown_listing_date")
+    rows = []
+    for instrument_id in ids:
+        instrument = universe[instrument_id]
+        bar = bars.get(instrument_id)
+        reason = "eligible"
+        if bar is None:
+            reason = "missing_bar"
+        elif bar.suspended or bar.volume <= 0:
+            reason = "suspended_or_no_volume"
+        elif (
+            bar.open <= 0
+            or bar.low <= 0
+            or not (bar.low <= min(bar.open, bar.close) <= max(bar.open, bar.close) <= bar.high)
+        ):
+            reason = "invalid_ohlc"
+        elif day - instrument.listed_date < timedelta(days=120):
+            reason = "listed_less_than_120_calendar_days"
+        elif bar.amount is None or bar.amount < minimum_amount:
+            reason = "insufficient_amount"
+        reasons[instrument_id] = reason
+        rows.append(
+            FactorPanelRow(
+                instrument_id=instrument_id,
+                as_of=datetime.combine(day, time(15), cn),
+                available_at=observed_at,
+                eligible=reason == "eligible",
+                fields={"open": bar.open if bar else None, "close": bar.close if bar else None},
+            )
+        )
+    universe_digest = hashlib.sha256(
+        json.dumps(
+            [universe[i].model_dump(mode="json") for i in ids],
+            sort_keys=True,
+        ).encode()
+    ).hexdigest()
+    panel = FactorPanel(
+        decision_time=observed_at,
+        price_basis="raw_same_day_ratio",
+        universe_ref="listed_a_share_catalog",
+        universe_revision=universe_digest,
+        market_revision=revision,
+        units={"open": "CNY", "close": "CNY"},
+        rows=tuple(rows),
+    )
+    spec = FactorComputationSpec(
+        name="intraday_strength",
+        input_kind="panel",
+        inputs=["bar/1d"],
+        python_source=SOURCE,
+        description="收盘价 / 开盘价 - 1；成交额与上市时间过滤",
+    )
+    values = execute_python_panel(spec, panel)
+    ranked = sorted(
+        [(i, score) for (_, i), score in values.items() if score is not None],
+        key=lambda item: (-item[1], item[0]),
+    )
+    output.mkdir(parents=True, exist_ok=True)
+    with (output / "ranking.csv").open("w", encoding="utf-8-sig", newline="") as stream:
+        writer = csv.writer(stream)
+        writer.writerow(["rank", "instrument_id", "name", "intraday_return", "amount_cny"])
+        for rank, (i, score) in enumerate(ranked, 1):
+            writer.writerow([rank, i, universe[i].name, score, bars[i].amount])
+    audit = {
+        "day": str(day),
+        "observed_at": observed_at.isoformat(),
+        "revision": revision,
+        "input_digest": panel.input_digest,
+        "definition_digest": spec.content_digest,
+        "catalog_stocks": len(stocks),
+        "universe": len(ids),
+        "bars": len(bars),
+        "filter_counts": dict(Counter(reasons.values())),
+        "minimum_amount": str(minimum_amount),
+        "top": [{"id": i, "name": universe[i].name, "score": str(s)} for i, s in ranked[:top]],
+        "limitations": [
+            "当前修订快照，不是历史PIT回测",
+            "未过滤历史ST和涨跌停，非可成交名单",
+            "仅验证选股链路，未验证收益预测能力",
+        ],
+    }
+    for name, content in {
+        "summary.json": audit,
+        "exclusions.json": {i: r for i, r in reasons.items() if r != "eligible"},
+        "bars.json": [bars[i].model_dump(mode="json") for i in sorted(bars)],
+        "universe.json": [universe[i].model_dump(mode="json") for i in ids],
+        "factor.json": spec.model_dump(mode="json"),
+    }.items():
+        (output / name).write_text(
+            json.dumps(content, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+    return audit
+
+
+if __name__ == "__main__":
+    configure_utf8_output()
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--day", type=date.fromisoformat, required=True)
+    parser.add_argument("--output", type=Path, default=Path(".cache/full_market_screen"))
+    parser.add_argument("--minimum-amount", type=Decimal, default=Decimal("20000000"))
+    parser.add_argument("--top", type=int, default=20)
+    args = parser.parse_args()
+    if args.minimum_amount < 0 or args.top < 1:
+        parser.error("成交额不能为负，top 必须为正数")
+    print(
+        json.dumps(
+            asyncio.run(run(args.day, args.output, args.minimum_amount, args.top)),
+            ensure_ascii=False,
+            indent=2,
+        )
+    )

quant_cli/examples/local_quant_validation.py

@@ -0,0 +1,196 @@
+"""显式本地快照验证：因子独立复算、研究归档、真实交易回放与重启读取。"""
+
+import argparse
+import asyncio
+import json
+import sys
+from datetime import date, datetime, time
+from decimal import Decimal
+from pathlib import Path
+from unittest.mock import patch
+from zoneinfo import ZoneInfo
+
+from quant_core.app.backtest.schema import BacktestConfig, BacktestResult
+from quant_core.app.factor.factor_dependency import build_factor_diagnostics
+from quant_core.app.factor.schema.local_factor_schema import LocalFactorRequest
+from quant_core.app.research.schema.dataset_schema import ResearchLabel
+from quant_core.common.local_run import RunStatus
+
+from quant_cli.app.backtest.local_backtest_dependency import build_local_backtest_store
+from quant_cli.app.backtest.local_backtest_schema import LocalBacktestRequest
+from quant_cli.app.backtest.service.local_backtest_service import run_local_backtest
+from quant_cli.app.data.service.dataset_load_service import load_dataset
+from quant_cli.app.factor.local_factor_dependency import (
+    build_local_factor_query,
+    build_local_factor_store,
+)
+from quant_cli.app.factor.service.local_factor_service import run_local_factor
+from quant_cli.app.research.local_research_dependency import build_local_research_store
+from quant_cli.app.research.schema.local_research_schema import LocalEvaluationRequest
+from quant_cli.app.research.service.local_research_service import (
+    compare_local_research,
+    evaluate_local_factor,
+)
+
+CN = ZoneInfo("Asia/Shanghai")
+SOURCE = (
+    "from quant_core.app.factor.computation.factor_expression import MA, Factor\n"
+    "factors = {'reversal5': -MA(Factor('close') / Factor('open') - 1, 5)}"
+)
+
+
+async def validate(manifest: Path, database: Path, backtest_manifest: Path) -> dict:
+    assert "quant_backend.common.database.database_session" not in sys.modules
+    factor_store = build_local_factor_store(database)
+    research_store = build_local_research_store(database)
+    with patch("socket.socket", side_effect=AssertionError("离线计算禁止网络")):
+        market, _ = load_dataset(manifest, 1000000)
+        ids = tuple(sorted(market.facts))
+        request = LocalFactorRequest(
+            source=SOURCE,
+            manifest_path=manifest,
+            instrument_ids=ids,
+            start=date(2026, 9, 8),
+            end=date(2026, 9, 24),
+        )
+        factor_run = await run_local_factor(request, factor_store)
+        assert factor_run.status == RunStatus.COMPLETED, factor_run.error
+        values = factor_store.load_values(factor_run.uuid)["reversal5"]
+        maximum_error = Decimal(0)
+        labels = []
+        for instrument in ids:
+            info = await market.get_instrument(instrument)
+            calendar = await market.list_trading_days(
+                info.exchange, market.start.date(), market.end.date()
+            )
+            days = sorted(x.trade_date for x in calendar if x.is_open)
+            bars = await market.list_bars(instrument, "1d", market.start, market.end, 10000)
+            lookup = {bar.timestamp.astimezone(CN).date(): bar for bar in bars}
+            for (ts, key), actual in values.items():
+                if key != instrument:
+                    continue
+                day = ts.astimezone(CN).date()
+                index = days.index(day)
+                window = [lookup.get(d) for d in days[index - 4 : index + 1]]
+                expected = None
+                if len(window) == 5 and all(b and not b.suspended and b.open > 0 for b in window):
+                    expected = -sum((b.close / b.open - 1 for b in window), Decimal(0)) / 5
+                assert (expected is None) == (actual is None)
+                if expected is not None:
+                    maximum_error = max(maximum_error, abs(expected - actual))
+                    assert abs(expected - actual) < Decimal("1e-12")
+                if index + 2 < len(days):
+                    buy, sell = lookup.get(days[index + 1]), lookup.get(days[index + 2])
+                    # 显式原始价格标签，只用于流程验证，不宣称投资有效性。
+                    value = (
+                        sell.close / buy.close - 1
+                        if buy and sell and not buy.suspended and not sell.suspended
+                        else None
+                    )
+                    labels.append(
+                        ResearchLabel(
+                            ts,
+                            instrument,
+                            datetime.combine(days[index + 2], time(15), CN),
+                            value,
+                            "raw-next-session-close-to-following-close",
+                            market.revision,
+                        )
+                    )
+        evaluation = LocalEvaluationRequest(
+            factor_run_uuid=factor_run.uuid, factor_name="reversal5", labels=tuple(labels)
+        )
+        research_runs = []
+        for _ in range(2):
+            record = evaluate_local_factor(evaluation, factor_store, build_factor_diagnostics())
+            assert record.status == RunStatus.COMPLETED, record.error
+            research_store.save(record)
+            research_runs.append(record.uuid)
+        assert compare_local_research(research_store, tuple(research_runs))["comparable"]
+        last = max(ts for ts, _ in values)
+        top = tuple(
+            key
+            for key, value in sorted(
+                [
+                    (key, value)
+                    for (ts, key), value in values.items()
+                    if ts == last and value is not None
+                ],
+                key=lambda item: (-item[1], item[0]),
+            )[:5]
+        )
+        query, aliases = await build_local_factor_query(
+            factor_run, {"reversal5": values}, market, market.end.date()
+        )
+        before = await query.get_snapshot(list(aliases.values()), list(ids), last)
+        assert all(row.as_of < last for row in before.values)
+        after = await query.get_snapshot(
+            list(aliases.values()), list(ids), datetime(2026, 9, 28, 9, 30, tzinfo=CN)
+        )
+        assert after.values and all(row.available_at <= after.decision_time for row in after.values)
+        source = """def handle_bar(context, bars):
+    if context.event_time.date().isoformat() == "2026-09-28":
+        for key in context.universe:
+            context.order_shares(key, 200)
+    elif context.event_time.date().isoformat() == "2026-09-30":
+        for key in context.universe:
+            context.order_target(key, 0)
+"""
+        backtest_request = LocalBacktestRequest(
+            source=source,
+            manifest_path=backtest_manifest,
+            parameters={"selection_run_uuid": str(factor_run.uuid)},
+            config=BacktestConfig(
+                strategy_id="local_validation",
+                instrument_ids=top,
+                frequency="1d",
+                start=datetime(2026, 9, 28, 9, 30, tzinfo=CN),
+                end=datetime(2026, 9, 30, 15, tzinfo=CN),
+                initial_cash=Decimal(1000000),
+                strategy_adjustment_type="none",
+            ),
+        )
+        backtest = await run_local_backtest(backtest_request, factor_store)
+        assert backtest.status == RunStatus.COMPLETED, backtest.error
+        build_local_backtest_store(database).save(backtest)
+        result = BacktestResult.model_validate(
+            build_local_backtest_store(database).get(backtest.uuid).result
+        )
+        assert len(result.fills) == 10
+        expected_cash = Decimal(1000000) + sum(
+            (
+                (1 if f.side.value == "sell" else -1) * f.price * f.quantity - f.fees.total
+                for f in result.fills
+            ),
+            Decimal(0),
+        )
+        assert result.final_portfolio_snapshot.cash.total_cash == expected_cash
+    assert "quant_backend.common.database.database_session" not in sys.modules
+    return {
+        "status": "passed",
+        "factor_run": str(factor_run.uuid),
+        "research_runs": [str(x) for x in research_runs],
+        "backtest_run": str(backtest.uuid),
+        "instruments": len(ids),
+        "cells": len(values),
+        "maximum_error": str(maximum_error),
+        "fills": len(result.fills),
+        "final_cash": str(expected_cash),
+        "database": str(database),
+        "factor_market_revision": factor_run.provenance["market_revision"],
+        "backtest_market_revision": backtest.provenance["market_revision"],
+        "labels": "raw-next-session-close-to-following-close; pipeline validation only",
+    }
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--manifest", type=Path, required=True)
+    parser.add_argument("--database", type=Path, required=True)
+    parser.add_argument("--backtest-manifest", type=Path, required=True)
+    args = parser.parse_args()
+    report = asyncio.run(validate(args.manifest, args.database, args.backtest_manifest))
+    (args.database.parent / "validation_report.json").write_text(
+        json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    print(json.dumps(report, ensure_ascii=False))

quant_cli/examples/published_definition_validation.py

@@ -0,0 +1,219 @@
+"""固定五股样本：下载定义后，断网 CLI 计算、依赖复用与独立数值/成交复核。"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from datetime import date, datetime
+from decimal import Decimal
+from pathlib import Path
+from zoneinfo import ZoneInfo
+
+from quant_core.app.backtest.schema import BacktestResult
+
+from quant_cli.app.data.service.dataset_load_service import load_dataset
+
+CN = ZoneInfo("Asia/Shanghai")
+BOOTSTRAP = """
+import asyncio, sys
+from importlib.abc import MetaPathFinder
+from unittest.mock import patch
+class Guard(MetaPathFinder):
+    def find_spec(self, fullname, path=None, target=None):
+        if fullname.startswith('quant_backend'):
+            raise AssertionError('Remote infrastructure import: ' + fullname)
+sys.meta_path.insert(0, Guard())
+from quant_cli.app.quant_cli import main
+with asyncio.Runner() as runner:
+    runner.get_loop()
+    with (
+        patch('socket.socket', side_effect=AssertionError('Offline network access')),
+        patch('asyncio.run', runner.run),
+    ):
+        main()
+"""
+
+
+def validate(manifest: Path, factor: Path, strategy: Path, output: Path) -> dict:
+    output.mkdir(parents=True, exist_ok=True)
+    database = str(output / "research.duckdb")
+    market, _ = load_dataset(manifest, 1000000)
+    ids = sorted(market.facts)
+
+    def command(*args, expected=0):
+        result = subprocess.run(
+            [os.environ.get("PQ_VALIDATION_CLIENT_PYTHON", sys.executable), "-c", BOOTSTRAP, *args],
+            cwd=output,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=180,
+            env={**os.environ, "PYTHONIOENCODING": "utf-8"},
+        )
+        assert result.returncode == expected, result.stdout + result.stderr
+        return json.loads(result.stdout)
+
+    def config(name, payload):
+        path = output / f"{name}.json"
+        path.write_text(
+            json.dumps(payload, default=str, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+        return str(path)
+
+    factor_request = {
+        "manifest_path": str(manifest),
+        "instrument_ids": ids,
+        "start": "2026-09-08",
+        "end": "2026-09-30",
+    }
+    computed = command(
+        "factor",
+        "compute",
+        "--database",
+        database,
+        "--definition",
+        str(factor),
+        "--config",
+        config("factor-request", factor_request),
+    )
+    cells = command(
+        "factor", "values", "--run", computed["uuid"], "--limit", "10000", "--database", database
+    )
+    error, selection = Decimal(0), []
+    for cell in cells:
+        instrument = cell["instrument_id"]
+        day = datetime.fromisoformat(cell["as_of"]).astimezone(CN).date()
+        days = sorted(row.trade_date for row in market.facts[instrument].calendar if row.is_open)
+        bars = {bar.timestamp.astimezone(CN).date(): bar for bar in market.bars[(instrument, "1d")]}
+        index = days.index(day)
+        window = [bars.get(d) for d in days[max(0, index - 4) : index + 1]]
+        expected = None
+        if len(window) == 5 and all(bar and not bar.suspended and bar.open > 0 for bar in window):
+            expected = -sum((bar.close / bar.open - 1 for bar in window), Decimal(0)) / 5
+        actual = None if cell["value"] is None else Decimal(cell["value"])
+        assert (actual is None) == (expected is None)
+        if expected is not None:
+            error = max(error, abs(actual - expected))
+            assert abs(actual - expected) < Decimal("1e-12")
+        if day == date(2026, 9, 24) and expected is not None:
+            selection.append((instrument, expected))
+    top = [key for key, value in sorted(selection, key=lambda row: (-row[1], row[0]))[:3]]
+    bundle = json.loads(strategy.read_text(encoding="utf-8"))
+    backtest_request = {
+        "manifest_path": str(manifest),
+        "config": {
+            "strategy_id": bundle["definition"]["strategy_id"],
+            "instrument_ids": ids,
+            "frequency": "1d",
+            "start": "2026-09-28T09:30:00+08:00",
+            "end": "2026-09-30T15:00:00+08:00",
+            "initial_cash": "1000000",
+            "strategy_adjustment_type": "none",
+        },
+    }
+    automatic = command(
+        "strategy",
+        "run",
+        "--database",
+        database,
+        "--definition",
+        str(strategy),
+        "--config",
+        config("automatic-request", backtest_request),
+    )
+    reused = command(
+        "strategy",
+        "run",
+        "--database",
+        database,
+        "--definition",
+        str(strategy),
+        "--config",
+        config(
+            "reuse-request",
+            {
+                **backtest_request,
+                "factor_run_uuid": computed["uuid"],
+            },
+        ),
+    )
+    result = BacktestResult.model_validate(automatic["result"])
+    again = BacktestResult.model_validate(reused["result"])
+    assert len(result.fills) == 6
+    assert sorted(
+        fill.instrument_id for fill in result.fills if fill.side.value == "buy"
+    ) == sorted(top)
+    cash = Decimal(1000000)
+    for fill in result.fills:
+        bars = {
+            bar.timestamp.astimezone(CN).date(): bar
+            for bar in market.bars[(fill.instrument_id, "1d")]
+        }
+        day = date(2026, 9, 28) if fill.side.value == "buy" else date(2026, 9, 30)
+        assert fill.quantity == 200
+        assert fill.price == bars[day].close
+        notional = fill.price * 200
+        fees = max(notional * Decimal("0.0003"), Decimal(5))
+        if fill.side.value == "sell":
+            fees += notional * Decimal("0.0005")
+        assert fill.fees.total == fees
+        cash += (1 if fill.side.value == "sell" else -1) * notional - fees
+    assert result.final_portfolio_snapshot.cash.total_cash == cash
+    assert again.final_portfolio_snapshot.cash.total_cash == cash
+
+    def business(r):
+        return [(f.instrument_id, f.side, f.quantity, f.price, f.fees.total) for f in r.fills]
+
+    assert business(result) == business(again)
+    for kind, record in (("factor", computed), ("backtest", automatic), ("backtest", reused)):
+        assert command(kind, "get", "--run", record["uuid"], "--database", database) == record
+    # 用同一包再次执行；进程重启后固定版本和业务结果仍稳定。
+    repeated = command(
+        "strategy",
+        "run",
+        "--database",
+        database,
+        "--definition",
+        str(strategy),
+        "--config",
+        str(output / "automatic-request.json"),
+    )
+    assert business(BacktestResult.model_validate(repeated["result"])) == business(result)
+    report = {
+        "status": "passed",
+        "environment": computed["provenance"]["environment"],
+        "offline": True,
+        "manifest": str(manifest),
+        "factor_version": computed["provenance"]["published_definitions"],
+        "strategy": automatic["provenance"]["published_strategy"],
+        "cells": len(cells),
+        "maximum_error": str(error),
+        "selected": top,
+        "fills": len(result.fills),
+        "final_cash": str(cash),
+        "automatic": automatic["uuid"],
+        "reuse": reused["uuid"],
+        "repeat": repeated["uuid"],
+        "limitations": ["五股固定工程样本，非全市场或投资收益验收"],
+    }
+    config("validation-report", report)
+    return report
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    for name in ("manifest", "factor", "strategy", "output"):
+        parser.add_argument(f"--{name}", required=True, type=Path)
+    args = parser.parse_args()
+    print(
+        json.dumps(
+            validate(
+                args.manifest.resolve(),
+                args.factor.resolve(),
+                args.strategy.resolve(),
+                args.output.resolve(),
+            ),
+            ensure_ascii=False,
+        )
+    )

quant_cli/examples/research/factor_pit_coverage.py

@@ -0,0 +1,87 @@
+"""研究因子历史值与可见时间的覆盖，不推断收益预测能力。"""
+
+from datetime import datetime, time
+from zoneinfo import ZoneInfo
+
+from quant_core.app.factor.constants import FactorFrequency, FactorStatus
+from quant_core.app.factor.schema.factor_contract import FactorIdentity
+
+CN = ZoneInfo("Asia/Shanghai")
+NAMES = ("momentum_20d", "volume_ratio_5d", "ma_close_10")
+STOCKS = (
+    "CN.XSHE.000001",
+    "CN.XSHE.300750",
+    "CN.XSHG.600519",
+    "CN.XSHG.688981",
+)
+
+
+async def run(context, parameters):
+    if context.factors is None:
+        raise ValueError("研究运行未注入因子查询能力")
+    start = datetime.combine(context.start, time.min, CN)
+    end = datetime.combine(context.end, time.max, CN)
+    decision_time = datetime.combine(context.end, time(15), CN)
+    observations = []
+    exclusions = []
+    values_total = 0
+    for name in NAMES:
+        identity = FactorIdentity(
+            name=name,
+            source="local-python",
+            definition_version="1",
+            frequency=FactorFrequency.DAILY,
+        )
+        for instrument_id in STOCKS:
+            values = await context.factors.get_series(
+                identity, instrument_id, start, end, decision_time
+            )
+            available = [row for row in values if row.status is FactorStatus.AVAILABLE]
+            if not available:
+                exclusions.append(
+                    {
+                        "factor": name,
+                        "instrument_id": instrument_id,
+                        "reason": "决策时点无可见因子值",
+                    }
+                )
+                continue
+            assert all(row.available_at <= decision_time for row in values)
+            values_total += len(available)
+            observations.append(
+                {
+                    "factor": name,
+                    "instrument_id": instrument_id,
+                    "available_count": len(available),
+                    "first_as_of": min(row.as_of for row in available).isoformat(),
+                    "last_as_of": max(row.as_of for row in available).isoformat(),
+                    "latest_available_at": max(row.available_at for row in available).isoformat(),
+                }
+            )
+    return {
+        "question": "本地三因子对四只股票的 PIT 历史覆盖是否足以开展收益研究？",
+        "conclusion": (
+            f"12 个因子×股票组合中 {len(observations)} 个有可见值，"
+            f"共 {values_total} 个可见因子值；当前只能验收覆盖和可见时间，"
+            "样本不足以判断预测能力。"
+        ),
+        "methodology": "按因子身份和股票分别读取截至样本结束日 15:00 已可见的历史值；不填补缺失。",
+        "sample_start": context.start,
+        "sample_end": context.end,
+        "candidate_count": len(NAMES) * len(STOCKS),
+        "observations": observations,
+        "exclusions": exclusions,
+        "metrics": [
+            {
+                "key": "available_values",
+                "label": "可见因子值行数",
+                "value": values_total,
+                "unit": "count",
+                "explanation": "按因子身份×标的×归属日期统计；不是独立收益样本数。",
+            }
+        ],
+        "limitations": [
+            "只检查三因子、四只股票和短窗口，不能外推至全市场。",
+            "未计算未来收益、IC、分层表现或样本外结果，不构成因子有效性证明。",
+        ],
+    }