docs: 文档重构 — 清理 AI agent 残留，整合 docs/ 目录结构

- 删除 11 个残留文件: continuation.md, init_plan.md, reasonix.toml, djapi/continuation.md, djapi/.serena/, djapi/.claude/, djapi/.mcp.json, .claude/skills/, docs/usage.html, docs/db_schema.md, docs/report_db_design.md
- 7 个 CLAUDE-*.md 移入 docs/ 并重命名去 CLAUDE- 前缀
- 新增 4 个文档: architecture.md, development.md, api.md, deployment.md
- 重写 usage.md, README.md
- 修复所有过时引用和交叉链接

docs/data-layer.md

@@ -0,0 +1,99 @@
+# 数据层 + 数据库
+
+## DataManager (`finance/data/data_manager.py`)
+
+双数据源：Tushare（优先）→ AkShare（fallback）。DB 缓存优先。
+
+```python
+from data.data_manager import DataManager
+dm = DataManager()
+dm.init_db()  # 首次建表（幂等）
+```
+
+### 关键方法
+
+```python
+stocks = dm.get_stock_list()          # → 5524 只, DB 优先
+daily  = dm.get_daily("000001.SZ")    # DB优先 → Tushare → AkShare
+fina   = dm.get_financial("000001.SZ")  # 同花顺 + fallback
+n      = dm.sync_daily("000001.SZ")   # 增量同步: latest>=today → 跳过
+```
+
+### 指数 vs 个股路由
+
+`_try_fetch()` 自动检测 `is_index_code()`：
+- `000001.SH` / `399001.SZ` → `fetch_index_daily()`（Tushare `index_daily` / AkShare `index_zh_a_hist`）
+- `000001.SZ` / `600519.SH` → `fetch_daily()`（stock daily）
+
+### 数据源 (`finance/data/sources/`)
+
+- `akshare_source.py` — `AkShareSource`（个股+指数+财务）
+- `tushare_source.py` — `TushareSource`（需 `TUSHARE_TOKEN`，`available=False` 自动跳过）
+
+## 数据库 (`finance/database/`)
+
+### 连接
+
+```python
+from database.connection import get_engine, test_connection
+# get_engine() 自动检测断连 → 运行 autossh.sh → 重建引擎
+```
+
+### 表结构（mac_ 前缀）
+
+| 表 | 内容 | 主键 |
+|----|------|------|
+| `mac_stock_basic` | A股列表, 5524只 | ts_code |
+| `mac_stock_daily` | 日线 OHLCV | (ts_code, trade_date) |
+| `mac_stock_financial` | 财务指标 | (ts_code, end_date) |
+| `mac_report` | 报告持久化 | id |
+
+### DAO (`finance/database/dao.py`)
+
+- `_DAILY_COLS` / `_FINA_COLS` — 入库前字段筛选
+- `get_latest_trade_date(ts_code)` → 增量判断
+- `save_report()` / `query_reports()` → 报告管理
+
+### 配置
+
+```bash
+# SSH 隧道
+bash shared/script/autossh.sh
+# host: 127.0.0.1:13306  user: myquant  database: myquant
+```
+
+## 缓存策略
+
+- `sync_daily`: 已缓存且最新 → 0.04s 跳过
+- 未缓存 → 提示 `agent_cli.py warmup`
+- 每日增量只更新已缓存股票，未缓存统计跳过
+
+## ⚠️ 已知 Bug 速查（避免重复踩坑）
+
+### B1: `.env` 加载路径
+- **症状**: Tushare available=False, QWEN_API_KEY 读不到
+- **根因**: `load_dotenv()` 不传路径，从 CWD 找 .env，而非 `finance/`
+- **修复**: `config/settings.py` 用 `Path(__file__).parent.parent / ".env"`
+- **加固**: `tushare_source.py`, `qwen_client.py`, `news_source.py` 顶部 `import config.settings`
+
+### B2: SSH 重连只生效一次
+- **症状**: 第一次断连能恢复，第二次断连无法恢复
+- **根因**: `_ssh_auto_attempted` 全局变量设 True 后永不重置
+- **修复**: 移除该变量。`get_engine()` 每次断连都触发 `_reconnect_ssh()` → `dispose()` → 重建
+
+### B3: 连接池半开连接
+- **症状**: `_test_engine()` 返回 True 但实际查询报 `_read_bytes` 超时
+- **根因**: 池中有活连接也有死连接，test 取到活的，查询取到死的
+- **修复**: `pool_pre_ping=True` + `pool_recycle=600` + 断连时 `_engine.dispose()`
+
+### B4: save_daily 主键冲突
+- **症状**: `IntegrityError: Duplicate entry '000001.SZ-20260603'`
+- **根因**: Tushare 返回的数据含已存在的日期，`append` 模式遇主键冲突
+- **修复**: 写入前 `DELETE FROM mac_stock_daily WHERE ts_code IN (...) AND trade_date IN (...)`
+
+### B5: 数据不更新排查清单
+- 检查 SSH 隧道: `lsof -i :13306 | grep LISTEN`
+- 检查 Tushare: `python -c "from data.sources.tushare_source import TushareSource; print(TushareSource().available)"`
+- 检查最新数据: `from database.dao import get_latest_trade_date; print(get_latest_trade_date('000001.SZ'))`
+- 手动触发 sync: `dm.sync_daily('000001.SZ')`
+- 预期行为: T+1 数据产出，节假日无新数据属于正常