windows-desktop: C端基线（Windows 本地实时分析器 + 采集器 bug 修复）

docs/DATA_DICTIONARY.md

@@ -0,0 +1,358 @@
+# A 股事件-市场时间线分析工具链：数据字典
+
+> 项目路径：`C:\Users\lookt\a_stock_timeline`  
+> 数据库：`data/a_stock.db`（SQLite）  
+> 数据导出：`data/a_stock_all.xlsx`（8 个 Sheet）
+
+---
+
+## 一、整体架构
+
+```
+数据采集层（src/fetcher/）
+    │
+    ▼
+数据持久层（data/a_stock.db — 8 张表）
+    │
+    ├──► CSV 备份（data/raw/）
+    │
+    ▼
+时间线对齐层（src/align/）
+    │
+    ▼
+可视化层（src/viz/）
+```
+
+---
+
+## 二、各表详细说明
+
+---
+
+### 2.1 `trade_calendar` —— 交易日历
+
+| 属性 | 说明 |
+|---|---|
+| 行数 | 8,797 |
+| 时间范围 | 1990-12-19 至今 |
+| 数据源 | AkShare `tool_trade_date_hist_sina` |
+| 用途 | 判断某日是否为交易日；时间线对齐的锚点 |
+
+**字段：**
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| `trade_date` | TEXT（YYYY-MM-DD） | 日期 |
+| `is_trade_day` | INTEGER（0/1） | 1=交易日，0=非交易日（周末/节假日） |
+
+**使用示例：**
+- `WHERE is_trade_day = 1` 筛选实际交易日
+- 与 `stock_daily` 做 JOIN，确认某日是否有指数数据
+- 用于快讯/新闻时间戳补全（若时间戳缺失日期，默认填最近交易日）
+
+---
+
+### 2.2 `stock_daily` —— A 股主要指数日线行情
+
+| 属性 | 说明 |
+|---|---|
+| 行数 | 315 |
+| 指数数量 | 5 只（上证、深证、沪深300、创业板、科创50） |
+| 时间范围 | 近 90 个交易日 |
+| 数据源 | AkShare `index_zh_a_hist` |
+| 用途 | 反映大盘整体走势，是时间线的"市场背景层" |
+
+**字段：**
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| `ts_code` | TEXT | 指数代码（sh000001=上证综指，sz399001=深证成指，sh000300=沪深300，sz399006=创业板指，sh000688=科创50） |
+| `trade_date` | TEXT（YYYY-MM-DD） | 交易日期 |
+| `open` | REAL | 开盘点位 |
+| `high` | REAL | 最高点位 |
+| `low` | REAL | 最低点位 |
+| `close` | REAL | 收盘点位 |
+| `volume` | REAL | 成交量（股） |
+| `amount` | REAL（可能为 NULL） | 成交额（元），部分指数无成交额数据 |
+
+**指数代码速查：**
+
+| ts_code | 名称 |
+|---|---|
+| sh000001 | 上证综指 |
+| sz399001 | 深证成指 |
+| sh000300 | 沪深300 |
+| sz399006 | 创业板指 |
+| sh000688 | 科创50 |
+
+**分析提示：**
+- 配合 `pct_change = (close - prev_close) / prev_close * 100` 计算日收益率
+- 与宏观事件 JOIN，观察重大政策/数据发布前后指数的短期反应
+- 与龙虎榜 JOIN，识别"指数下跌 + 游资活跃"的异常交易日
+
+---
+
+### 2.3 `lhb_daily` —— 龙虎榜明细
+
+| 属性 | 说明 |
+|---|---|
+| 行数 | 409 |
+| 时间范围 | 近 90 个交易日 |
+| 数据源 | AkShare `stock_lhb_detail_daily_sina` |
+| 用途 | 追踪活跃游资席位的操作标的，识别短线热点 |
+
+**字段：**
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| `trade_date` | TEXT（YYYY-MM-DD） | 上榜日期 |
+| `ts_code` | TEXT | 股票代码 |
+| `name` | TEXT | 股票名称（可能有编码问题，实际显示正常） |
+| `close` | REAL | 上榜日收盘价 |
+| `pct_change` | REAL | 当日涨跌幅（%） |
+| `amount` | REAL | 龙虎榜成交金额（万元） |
+| `reason` | TEXT | 上榜原因（如：涨跌幅偏离值达7%、日换手率达20%等） |
+
+**常见上榜原因含义：**
+
+| reason 关键词 | 含义 |
+|---|---|
+| 涨跌幅偏离值达7% | 单日涨幅或跌幅过大，被交易所监控 |
+| 日换手率达20% | 筹码换手频繁，可能是游资接力 |
+| 连续3个交易日内涨跌幅偏离值累计达20% | 短线连板股 |
+| 日振幅达15% | 日内波动剧烈，多空分歧大 |
+| 异常波动 | 无明显原因的异动 |
+
+**分析提示：**
+- 按 `reason` 分组，统计近期哪类上榜原因最频繁
+- 结合指数涨跌（`stock_daily`）判断：大盘跌时仍有大量涨停，可能是个股独立行情
+- 高频上榜股（同一股票多日出现）往往是市场主线龙头
+
+---
+
+### 2.4 `news_flash` —— 财经快讯流
+
+| 属性 | 说明 |
+|---|---|
+| 行数 | 10（演示数据，批量采集后可增至数千条/日） |
+| 时间精度 | 分钟级 |
+| 数据源 | EastMoney `np-anotice-stock`（主），AkShare `stock_news_em`（降级） |
+| 用途 | 实时捕获影响市场的突发消息，作为时间线的"事件触发层" |
+
+**字段：**
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| `content` | TEXT | 快讯正文内容（可能有编码问题） |
+| `event_time` | TEXT（YYYY-MM-DD HH:MM:SS） | 事件发生时间 |
+| `source` | TEXT | 来源（如：东方财富Choice数据、证券时报） |
+| `inserted_at` | TEXT（YYYY-MM-DD HH:MM:SS） | 入库时间 |
+
+**分析提示：**
+- 快讯内容可能包含：政策发布、经济数据、监管动态、个股公告
+- 可按关键词（"降息"、"关税"、"制裁"、"收购"）做规则过滤
+- 高频来源（东方财富、同花顺）可作为可信度参考
+
+---
+
+### 2.5 `macro_event` —— 宏观经济事件日历
+
+| 属性 | 说明 |
+|---|---|
+| 行数 | 99 |
+| 数据源 | AkShare `news_economic_baidu`（财经日历） |
+| 用途 | 追踪全球主要经济数据发布时间（如非农、CPI、利率决议） |
+
+**字段：**
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| `event_date` | TEXT（YYYY-MM-DD） | 事件公布日期 |
+| `title` | TEXT | 事件标题（当前入库存在字段映射问题，详见下方警告） |
+| `event_type` | INTEGER | 重要性等级（1=高，2=中，3=低） |
+| `source` | TEXT | 数据来源 |
+| `inserted_at` | TEXT（YYYY-MM-DD HH:MM:SS） | 入库时间 |
+
+> **警告（已知问题）：** 当前入库的 `title` 字段实际包含了原始数据的 `event_date`，而真正的标题内容写入了 `event_date` 字段。这是 AkShare 返回字段名与实际位置不一致导致的映射错误。修复方案：调整 `macro_event_fetcher.py` 中的字段映射逻辑，按返回数据的实际列位置重新对应。
+
+**常见宏观事件类型：**
+
+| 事件 | 典型影响 |
+|---|---|
+| 美国非农就业数据 | 超预期=美元走强，A股承压 |
+| CPI/PPI 数据 | 超预期=通胀担忧，货币政策预期收紧 |
+| 美联储利率决议 | 降息=全球流动性宽松，A股受益 |
+| 中国官方PMI | 超预期=经济复苏预期增强 |
+| 进出口数据 | 超预期=外需强劲 |
+
+---
+
+### 2.6 `news_cn` —— A 股市场新闻
+
+| 属性 | 说明 |
+|---|---|
+| 行数 | 10（演示数据） |
+| 数据源 | AkShare `stock_news_em` |
+| 用途 | 覆盖个股/行业/宏观层面的新闻报道，构建事件叙事 |
+
+**字段：**
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| `id` | INTEGER | 自增主键 |
+| `title` | TEXT | 新闻标题 |
+| `content` | TEXT | 新闻正文摘要 |
+| `pub_date` | TEXT（YYYY-MM-DD HH:MM:SS） | 发布时间 |
+| `source` | TEXT | 来源媒体 |
+| `url` | TEXT | 原文链接 |
+| `keywords` | TEXT | 关键词标签（逗号分隔） |
+| `inserted_at` | TEXT（YYYY-MM-DD HH:MM:SS） | 入库时间 |
+
+---
+
+### 2.7 `money_flow` —— 个股资金流向（主力净流入）
+
+| 属性 | 说明 |
+|---|---|
+| 行数 | 2,085 |
+| 时间范围 | 最近 1 个交易日（全市场个股） |
+| 数据源 | AkShare `stock_fund_flow_individual` |
+| 用途 | 追踪主力资金（超大单+大单）的每日净流入/出，识别资金轮动方向 |
+
+**字段：**
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| `ts_code` | TEXT | 股票代码 |
+| `trade_date` | TEXT（YYYY-MM-DD） | 交易日期 |
+| `main_net_in` | REAL（当前全为 NULL，待修复） | 主力净流入金额（元） |
+
+> **已知问题：** `main_net_in` 字段当前全部为 NULL。原因是 AkShare `stock_fund_flow_individual` 接口返回的数值包含"万"、"亿"等中文单位后缀，字符串转数值时解析失败。修复方案：在 `fund_flow_fetcher.py` 中先对单位字符串进行清洗（去掉"万"/"亿"，按需转换精度），再转为浮点数。
+
+**资金流向分析逻辑：**
+
+| 主力净流入方向 | 市场含义 |
+|---|---|
+| 连续多日净流入某板块 | 机构建仓，可能是主线行情启动 |
+| 大盘下跌但某股净流入 | 护盘资金或逆势买入 |
+| 大盘上涨但某股净流出 | 主力借机减仓 |
+
+---
+
+### 2.8 `global_index` —— 外盘重要指数
+
+| 属性 | 说明 |
+|---|---|
+| 行数 | 14,583 |
+| 时间范围 | 道琼斯（2004-至今）、纳斯达克100（2004-至今）、标普500（2004-至今） |
+| 数据源 | AkShare `index_us_stock_sina` |
+| 用途 | 反映美股走势，作为 A 股的"外围环境层"（隔夜美股涨跌影响次日 A 股情绪） |
+
+**字段：**
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| `index_code` | TEXT | 指数代码（US.DJI=道琼斯，US.NDX=纳斯达克100，US.INX=标普500） |
+| `trade_date` | TEXT（YYYY-MM-DD） | 交易日期 |
+| `close` | REAL | 收盘点位 |
+| `pct_change` | REAL | 当日涨跌幅（%），由收盘价自计算 |
+
+**外盘与 A 股的联动规律：**
+
+| 场景 | A 股次日预期 |
+|---|---|
+| 美股大涨（纳指+2%以上） | 高开概率大 |
+| 美股大跌（道指-2%以上） | A 股低开，但可能低开高走 |
+| 美股窄幅震荡 | A 股按自身逻辑运行 |
+| 美股期货夜盘异动 | 可作为盘前情绪参考 |
+
+---
+
+## 三、数据关联关系
+
+```
+trade_calendar（锚点）
+    │
+    ├──► stock_daily    ON trade_date（大盘指数基准）
+    ├──► lhb_daily      ON trade_date（游资活跃度）
+    ├──► money_flow    ON trade_date（资金流向）
+    │
+news_flash ON event_time（分钟级事件）
+    │
+news_cn    ON pub_date（新闻发布日）
+    │
+macro_event ON event_date（宏观事件日）
+    │
+global_index ON trade_date-1（美股影响传导，差一天）
+```
+
+**时间线对齐策略：**
+1. 以 `trade_date`（交易日）为基准轴
+2. 快讯/新闻精确到分钟，非交易日数据合并到最近交易日
+3. 宏观事件按公布日期对齐
+4. 外盘指数按"美股T日 → A股T+1日"的逻辑传导对齐
+
+---
+
+## 四、数据质量问题汇总
+
+| 问题 | 涉及表 | 严重程度 | 状态 |
+|---|---|---|---|
+| `main_net_in` 全为 NULL | `money_flow` | 高 | 待修复 |
+| 字段映射错位 | `macro_event` | 高 | 待修复并重新入库 |
+| 中文内容乱码（GBK/UTF-8） | `lhb_daily`, `news_flash`, `news_cn` | 低（数据本身正确，仅显示问题） | 排查终端编码 |
+| 采集时间范围受限 | `stock_daily` | 中 | 可扩展至更长历史 |
+| `macro_event` 为历史数据非未来事件 | `macro_event` | 中 | 需配置 AkShare 实时财经日历参数 |
+
+---
+
+## 五、快速查询示例
+
+```sql
+-- 查最近 5 个交易日的大盘涨跌
+SELECT trade_date, close, 
+       ROUND((close - LAG(close) OVER(ORDER BY trade_date)) / LAG(close) OVER(ORDER BY trade_date) * 100, 2) AS pct_change
+FROM stock_daily
+WHERE ts_code = 'sh000001'
+ORDER BY trade_date DESC LIMIT 5;
+
+-- 查近 30 天龙虎榜热门上榜原因
+SELECT reason, COUNT(*) AS cnt
+FROM lhb_daily
+WHERE trade_date >= date('now', '-30 days')
+GROUP BY reason
+ORDER BY cnt DESC LIMIT 10;
+
+-- 查某日主力净流入TOP10个股
+SELECT ts_code, main_net_in
+FROM money_flow
+WHERE trade_date = '2026-09-15'
+ORDER BY main_net_in DESC NULLS LAST LIMIT 10;
+
+-- 查近 7 天重大宏观事件
+SELECT event_date, title
+FROM macro_event
+WHERE event_date >= date('now', '-7 days')
+ORDER BY event_date;
+```
+
+---
+
+## 六、后续数据扩展方向
+
+| 优先级 | 数据类型 | 数据源 | 说明 |
+|---|---|---|---|
+| P0 | 资金流向（修复） | 修复 `fund_flow_fetcher.py` 逻辑 | 解决 NULL 问题 |
+| P0 | 宏观事件（修复） | 修复 `macro_event_fetcher.py` 映射 | 解决字段错位 |
+| P1 | 港股行情 | AkShare `index_hk_hist` | 补充港股恒生指数 |
+| P1 | 期货行情 | AkShare `futures_zh_daily_sina` | 商品期货（黄金/原油） |
+| P1 | 北向资金 | AkShare `stock_hsgt_north_net_flow_in` | 外资流向 |
+| P2 | 行业板块涨跌 | AkShare `stock_board_industry_name_em` | 板块轮动 |
+| P2 | 融资融券 | AkShare `stock_margin_detail_sz` | 杠杆资金动向 |
+| P2 | 恐慌指数（VIX） | AkShare | 市场情绪反向指标 |
+
+---
+
+*文档版本：v1.0*  
+*最后更新：2026-09-15*  
+*对应数据库快照：`data/a_stock.db`（8 表）*