chore: 项目初始化 — 工程文档、配置与目录骨架

- AGENT.md / docs/ARCHITECTURE.md 约束与架构文档入库（README 覆盖远端模板）
- 根级配置：.gitignore / .env.example / config.yaml（密钥只走 .env，不入库）
- 目录占位：data(parquet/qlib/raw/normalized) / experiments / docker / frontend/web / scripts

.env.example

@@ -0,0 +1,24 @@
+# ============================================================
+# 复制本文件为项目根目录 .env 并填入真实值。
+# .env 已被 .gitignore 忽略 —— 严禁把真实密钥提交进 Git。
+# 各变量用途：被根目录 config.yaml 中对应 *_env 字段引用，
+# 或由后端 app.core.config 直接读取。
+# ============================================================
+
+# ---- Tushare Pro token（首选数据源，Phase 1 数据管线使用）----
+TUSHARE_TOKEN=
+
+# ---- 数据库连接 ----
+# 留空时使用默认 SQLite：<项目根>/data/quant.db（相对路径自动解析到项目根）
+DATABASE_URL=
+# SQLite 示例（显式指定）：
+# DATABASE_URL=sqlite:///./data/quant.db
+# MySQL 示例（未来切换，仅需改此值，业务代码不变）：
+# DATABASE_URL=mysql+pymysql://user:password@127.0.0.1:3306/quant
+
+# ---- AI Agent / LLM（Phase 5 接入，先留空）----
+LLM_API_KEY=
+LLM_BASE_URL=
+
+# ---- API 应用密钥（必须修改为随机值）----
+APP_SECRET_KEY=please-change-me

.gitignore

@@ -0,0 +1,50 @@
+# ================= Python =================
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+htmlcov/
+.coverage
+dist/
+build/
+
+# ================= 密钥 / 凭证 =================
+# 真实密钥只放根目录 .env（复制自 .env.example），严禁提交
+.env
+*.pem
+*.key
+
+# ================= 前端 / Node =================
+node_modules/
+.next/
+out/
+
+# ================= 本地数据（不入库） =================
+# 行情、数据库、缓存均不入库；只保留目录占位 .gitkeep
+data/*
+!data/**/.gitkeep
+*.db
+*.db-wal
+*.db-shm
+*.sqlite
+*.sqlite3
+*.parquet
+*.csv
+*.h5
+*.pkl
+
+# ================= 实验产物 =================
+experiments/*
+!experiments/**/.gitkeep
+
+# ================= OS / 编辑器 =================
+.DS_Store
+.idea/
+.vscode/
+*.swp

README.md

@@ -1,3 +1,98 @@
-# qlib
+# qlib-platform
 
-Qlib base的选股和回测平台
+个人 A 股量化研究平台：**选股 · 因子研究 · 回测**，面向低频 / 中低频交易研究。
+
+> 核心量化引擎：[Qlib](https://github.com/microsoft/qlib) · 首选数据源：Tushare（新浪财经为备用）· 当前数据库：SQLite（未来 MySQL，业务层无感切换）
+
+## 定位
+
+- 个人开发项目，中低频选股 / 因子 / 组合回测
+- **不做**高频交易、不做过度的微服务化
+- 以 Qlib 为研究引擎，但 Qlib 只是计算引擎而不是整个系统
+- AI Agent（Phase 5）只能通过受控 Tool 调用研究能力
+
+## 架构
+
+详见 [AGENT.md](./AGENT.md)（开发约束）与 [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)（架构文档），**改代码前必须阅读**。
+
+```text
+Web 前端 (frontend/web)
+   ↓ REST / SSE
+FastAPI (backend)
+   ↓ Research Specification
+Application Service ── Quant Service ── Qlib Adapter ── Qlib
+   ↓                    ↓
+Repository / DAO      Parquet / SQLite
+```
+
+### 目录结构
+
+```text
+qlib/
+├── backend/            # FastAPI 后端（uv 管理，Python 3.12）
+│   ├── app/
+│   │   ├── api/                # HTTP API 层（面向业务对象，禁止暴露 Qlib/SQL）
+│   │   ├── application/        # 用例 / 应用服务（编排，不含框架细节）
+│   │   ├── domain/             # 领域实体 + Repository Protocol
+│   │   ├── infrastructure/     # SQLAlchemy / Alembic 等基础设施实现
+│   │   ├── quant/qlib_adapter/ # Qlib 适配层（业务禁止直接 import qlib）
+│   │   ├── agent/              # AI Research Agent（Phase 5，仅 Tool 访问）
+│   │   └── core/               # 配置、通用组件
+│   └── tests/
+├── frontend/web/       # React / Next.js 前端（Phase 3 初始化）
+├── data/               # raw / normalized / parquet / qlib（不入库，gitignore）
+├── experiments/        # 实验产物（不入库，gitignore）
+├── scripts/            # 数据同步、运维脚本
+├── docker/             # 部署（Phase 后引入，第一阶段不过度工程）
+├── docs/
+├── AGENT.md
+├── config.yaml         # 可配置项（无密钥）
+└── .env.example        # 密钥模板（复制为 .env，勿提交）
+```
+
+## 快速开始（后端）
+
+前置：安装 [uv](https://docs.astral.sh/uv/)（`pip install uv` 或官方脚本）。
+
+```bash
+# 1. 配置密钥（复制模板，填入 TUSHARE_TOKEN 等）
+cp .env.example .env
+
+# 2. 安装依赖（自动使用 Python 3.12，见 backend/.python-version）
+cd backend
+uv sync
+
+# 3. 运行测试
+uv run pytest
+
+# 4. 启动开发服务
+uv run uvicorn app.main:app --reload --port 8000
+# 健康检查：http://127.0.0.1:8000/api/health
+# 交互文档：http://127.0.0.1:8000/docs
+```
+
+### 数据库迁移（Alembic，已就位）
+
+```bash
+cd backend
+uv run alembic upgrade head          # 首次运行会在 data/quant.db 建立版本表
+uv run alembic revision --autogenerate -m "add xxx table"   # 修改 Model 后生成迁移
+```
+
+## 开发阶段（对应架构文档 §20）
+
+- **Phase 1 数据**：Tushare → 标准化 → SQLite（stock / daily / 复权因子 / 交易日历 / 财务指标），Parquet 导出
+- **Phase 2 Qlib**：Parquet → Qlib Dataset → 因子（Alpha158 / 自定义）→ LightGBM → 回测
+- **Phase 3 Web**：股票池 / 因子研究 / 选股 / 回测 / 结果可视化（Next.js + ECharts）
+- **Phase 4 Experiment**：所有研究自动可复现存档
+- **Phase 5 AI Agent**：自然语言 → Research Plan → 受控 Tool → Experiment
+
+## 约定速查
+
+- 回答与文档使用中文
+- 一切时间相关数据防「未来函数」：财务数据区分 `report_date` / `announce_date`，查询支持 `as_of_date`
+- 数据源必须经 `MarketDataProvider`（Tushare 优先，Sina 兜底且记录来源），业务层禁止直接 import 新浪 / Tushare 实现
+- 业务层禁止直接操作 sqlite3 / SQL / SQLAlchemy Session，只能走 Repository
+- 新表：Model → Alembic Migration → Test
+- 禁止修改 site-packages/qlib 源码，一律走 Adapter / Wrapper
+- API 输入输出用 Pydantic DTO，禁止把 ORM Model 直接暴露给前端

config.yaml

@@ -0,0 +1,43 @@
+# ============================================================
+# 全局可配置项（可提交，不含任何密钥）
+# 约定（见 AGENT.md §2 / §33）：
+#   - 可配置项统一写入本文件（项目根 config.yaml）
+#   - 密钥统一放根目录 .env（见 .env.example），
+#     本文件通过 *_env 字段引用对应环境变量名，不写明文
+# ============================================================
+
+app:
+  name: "qlib-platform"
+  version: "0.1.0"
+  debug: false
+  # 从 .env 读取应用密钥的环境变量名
+  secret_key_env: "APP_SECRET_KEY"
+
+api:
+  prefix: "/api"
+
+database:
+  # 留空 → 默认 sqlite:///./data/quant.db（相对路径自动解析到项目根 data/）
+  url_env: "DATABASE_URL"
+  echo: false
+  # Alembic 迁移脚本目录（相对 backend/）
+  migrations_dir: "app/infrastructure/persistence/migrations"
+
+data_source:
+  primary: "tushare"
+  fallback: "sina"
+  tushare_token_env: "TUSHARE_TOKEN"
+
+storage:
+  # 相对项目根目录
+  raw_dir: "data/raw"
+  normalized_dir: "data/normalized"
+  parquet_dir: "data/parquet"
+  qlib_dir: "data/qlib"
+
+job:
+  # 第一阶段异步任务模式：local（FastAPI BackgroundTasks 级）；Phase 复杂后再引入队列
+  mode: "local"
+
+logging:
+  level: "INFO"

frontend/web/README.md

@@ -0,0 +1,6 @@
+# frontend/web
+
+React / Next.js 前端（Phase 3 初始化，当前为占位目录）。
+
+按 docs/ARCHITECTURE.md §12-§14：前端只面对业务 Domain API（/api/stocks、/api/factors、
+/api/backtests ...），消费标准化 BacktestResult，禁止接触 Qlib 内部配置 / SQL / ORM 对象。

scripts/README.md

@@ -0,0 +1,3 @@
+# scripts
+
+数据同步 / 运维 / 一次性脚本（如 Tushare 拉数 CLI、Parquet 导出、Qlib Dataset 构建）。