# A 股基本面分析框架

项目已完成第一阶段 M1 的可运行闭环，并打通 M2 因子研究底座。当前能力包括证券与行业主表、点时可用财务数据、复权行情、工商企业及金融行业评分、财务与治理排雷、质量信号代理、行业热点、候选股池、个股体检卡和滚动样本外因子实验。

项目内 `vendor/` 保存隔离依赖，不改动系统 Python 环境。重新安装可执行：

```powershell
& 'C:\Users\jyfss\Python312\python.exe' -m pip install -r requirements.txt --target vendor
```

## 运行命令

完整刷新 M1：

```powershell
$env:PYTHONIOENCODING='utf-8'
& 'C:\Users\jyfss\Python312\python.exe' run_m1.py
```

单独刷新质押及风险公告等外部数据：

```powershell
$env:PYTHONIOENCODING='utf-8'
& 'C:\Users\jyfss\Python312\python.exe' refresh_external_data.py
```

运行 M2 月度因子实验：

```powershell
$env:PYTHONIOENCODING='utf-8'
& 'C:\Users\jyfss\Python312\python.exe' run_m2_research.py
```

生成第三阶段研究工作台看板：

```powershell
$env:PYTHONIOENCODING='utf-8'
& 'C:\Users\jyfss\Python312\python.exe' run_dashboard.py
```

生成后直接打开 `reports/dashboard/index.html`。看板是自包含的静态页面，无需额外前端依赖；重新运行命令会读取最新 M1/M2 产物并更新数据快照。

如需在看板打开期间自动感知新数据，使用本地服务入口：

```powershell
& 'C:\Users\jyfss\Python312\python.exe' serve_dashboard.py
```

然后打开 `http://127.0.0.1:8765/reports/dashboard/index.html`。页面每分钟检查一次新版本，发现更新时先提示，由用者点击后载入，不会打断当前阅读。

手动执行完整日更：

```powershell
$env:PYTHONIOENCODING='utf-8'
& 'C:\Users\jyfss\Python312\python.exe' run_daily_update.py
```

日更按 `M1 数据刷新 → M2 因子研究 → 看板生成` 顺序运行，并在 `reports/dashboard/update_status.json` 保存状态、在 `reports/dashboard/logs/` 保存逐次日志。同一时间只允许一个日更任务；中途失败时保留上一版可用看板。

### 24 小时 Windows 小主机调度

日更不依赖 Codex。把项目和 Python 3.12 环境放在小主机后，先双击或在命令行执行 `run_daily_update.cmd` 确认能完整运行。再使用 PowerShell 安装工作日 18:00 的 Windows 计划任务：

在真正执行前可先做环境检查（不会刷新数据）：

```powershell
.\run_daily_update.cmd --check
```

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install_daily_task.ps1
```

如果 Python 不在 `PATH` 中，指定它的绝对路径：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install_daily_task.ps1 `
  -PythonPath "C:\Python312\python.exe"
```

安装脚本会注册 `FundamentalResearchDailyUpdate`：周一至周五 18:00 运行，错过时间后尽快补跑，已有实例运行时不重复启动。它默认以当前 Windows 用户运行，因此需保持该用户会话登录；如需在用户退出后仍运行，请在任务计划程序中将其改为“不管用户是否登录都要运行”并配置该主机的凭据。

M2 参数位于 `config/m2_research.toml`；非结构化研究输入契约见 `data/input/README.md`。

## 主要输出

基础数据与评分：

- `data/processed/security_master.parquet`
- `data/processed/industry_current.parquet`
- `data/processed/financial_statement_pit.parquet`
- `data/processed/financial_latest.parquet`
- `data/processed/daily_price.parquet`
- `data/processed/fundamental_metrics.parquet`
- `data/processed/fundamental_scores.parquet`
- `data/processed/fundamental_risk_flags.csv`
- `data/processed/financial_sector_metrics.parquet`

治理、质量与筛选：

- `data/processed/external_pledge_latest.parquet`
- `data/processed/external_risk_notices.parquet`
- `data/processed/external_governance_risk_flags.csv`
- `data/processed/quality_signal_proxies.parquet`
- `data/processed/industry_hotspot_scores.parquet`
- `data/processed/stock_screen_candidates.parquet`
- `data/processed/stock_health_cards.parquet`

研究与回测：

- `data/processed/factor_monthly_panel.parquet`
- `data/processed/factor_summary.csv`
- `data/processed/factor_group_returns.csv`
- `data/processed/factor_ic_series.csv`
- `data/processed/factor_weight_history.csv`
- `data/processed/factor_oos_returns.csv`
- `data/processed/m2_stock_candidates.parquet`

数据库与报告：

- `data/database/fundamental_mvp.duckdb`；若本机策略阻止 DuckDB，则自动生成 SQLite 版本。
- `reports/M1_实施状态.md`
- `reports/M1_数据质量报告.md`
- `reports/M1_财务字段质量报告.md`
- `reports/M1_行情标准化报告.md`
- `reports/M1_基本面评分报告.md`
- `reports/M1_治理与外部风险报告.md`
- `reports/M1_行业热点与候选股池.md`
- `reports/M2_深度研究与因子实验.md`
- `reports/dashboard/index.html`（交互式研究看板）

## 解释边界

- “护城河、创新、管理质量”当前是量化代理信号，不是经过年报、专利或产业链证据确认的事实。
- 外部风险公告采用标题规则筛查；未命中不等于不存在审计或监管风险。
- 回测仍可能受当前行业分类、生存者偏差和历史财务修订影响，研究结果不应直接视为实盘收益预期。

本项目只读取旧量化工程和通达信目录，不会改写源数据。