# Satellite Agent · 数据字典(Data Dictionary)

> 卫星互联网产业决策辅助 Agent(`agent/`)的数据库 schema 与种子数据说明 · 状态:与 Phase 1 + Phase 3a 同步(2026-06-02)
>
> 关联文档:[PRD](../PRD.md) · [架构说明](./architecture.md) · [本体](./ontology.md) · [API](./api.md)
>
> 本文档的定位:架构说明里 schema 散落在 `db.py` 的代码与正文叙述中。这份数据字典把它独立成册,作为字段级的唯一参考,便于前端、抓取层(Phase 2)和决策层(Phase 3)对齐字段口径。

---

## 1. 存储概述

当前阶段用 **SQLite** 作真相源(这是一个有意的取舍:在事件量级达到 10⁵ 之前,SQLite 的零运维优势压过 Postgres 的并发能力,见架构说明 §1)。数据落盘后,事件、市场模型、公司卡片、分析结果都持久化,可被 CLI 与 FastAPI 双接口读取。

主要的表有四组:`events`(事件)、`companies`(公司卡片)、`market_model`(市场模型情景)、`thesis_state`(主线 thesis 状态)。下面逐表展开字段。

---

## 2. events — 事件表

事件是系统的最小输入单元。每条新闻、公告、政策、产品发布、标准演进进来后,被分类器(`classifier.py`)解析为一条结构化事件。

| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| `id` | TEXT/INT | 事件唯一标识 | 主键 |
| `title` | TEXT | 事件标题 | 必填 |
| `body` | TEXT | 事件正文 | 可空 |
| `published_at` | DATE | 发布日期 | 用于周期聚合 |
| `main_line` | TEXT(enum) | 所属主线 | 核心网/终端/芯片/运营支撑,取自 ontology |
| `scenario` | TEXT(enum) | 场景 | 低空/车载/海事航空/工业IoT/应急/具身智能 |
| `impact_dim` | TEXT(enum) | 影响维度 | 技术/产品/市场空间/商业模式/公司竞争力/风险 |
| `thesis_impact` | TEXT(enum) | thesis 影响 | 增强/削弱/中性 |
| `confidence` | REAL | 分类置信度 | 0–1;< 0.55 触发 Phase 2.1 LLM 兜底 |
| `order_amount` | REAL | 订单金额 | **Phase 2 抓取必须解析**,不能只存文本 |
| `capex` | REAL | 资本开支 | Phase 2 数字字段 |
| `opex` | REAL | 运营开支 | Phase 2 数字字段 |
| `time_window` | TEXT | 时间窗 | Phase 2 数字字段 |
| `customer` | TEXT | 客户主体 | Phase 2 数字字段 |
| `next_indicator` | TEXT | 下一步跟踪指标 | 供 Tracking Agent 跟进 |
| `company_id` | TEXT | 关联公司 | 外键 → companies |
| `source` | TEXT | 数据来源 | 用于追溯 |

> 设计要点:`order_amount` / `capex` / `opex` / `time_window` / `customer` 这五个数字字段是 Phase 2 抓取的硬要求——PRD §3.1 明确"抓取必须解析,不能只存事件文本"。当前 Phase 1 这些字段允许为空,Phase 2 接入抓取后逐步填充。

---

## 3. companies — 公司卡片表

公司维度承载"同主线相对位势"的计算。

| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| `id` | TEXT | 公司唯一标识 | 主键 |
| `name` | TEXT | 公司名 | 必填 |
| `main_line` | TEXT(enum) | 所属主线 | 取自 ontology |
| `flagship_product` | TEXT | 代表产品 | |
| `orders` | REAL/JSON | 订单实数与客户 | **必填**,Phase 2 抓取来源 |
| `revenue_mapping` | JSON | 收入映射 | 订单 → 主线 → 财报科目的传导 |
| `tech_barrier` | TEXT | 技术壁垒 | 定性 |
| `risk` | TEXT | 风险 | 定性 |
| `score` | REAL | 综合评分 | |
| `peer_rank` | INT | 同主线内排名 | 本周排名,供位势矩阵 |
| `peer_rank_prev` | INT | 上周排名 | 用于"本周 vs 上周"变化 |

---

## 4. market_model — 市场模型表

维护四主线 2025–2031 年的市场空间情景。种子数据由 `seed.py` 生成,规模为 **4 主线 × 7 年 × 3 情景 = 84 行**。

| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| `main_line` | TEXT(enum) | 主线 | 4 取值 |
| `year` | INT | 年份 | 2025–2031,共 7 年 |
| `scenario` | TEXT(enum) | 情景 | 保守/基准/乐观 |
| `market_size` | REAL | 市场空间 | Phase 3b 用真实 capex/opex/订单滚动修正 |
| `is_seed` | BOOL | 是否种子值 | 区分占位数与抓取修正值 |

> 设计要点:Phase 1 的 `market_size` 是静态占位;Phase 3b 的目标是"由抓取层产出的真实 capex/opex/订单数字滚动修正情景,而非静态占位数"(PRD §3.2.1)。`is_seed` 标志用于区分两者。

---

## 5. thesis_state — 主线 thesis 状态表

记录每条主线的 thesis 随时间的演进,供决策层(`decision.py`)计算主驱动变量与主线评分。

| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| `main_line` | TEXT(enum) | 主线 | |
| `week` | TEXT | 周标识 | 用于"本周 vs 上周/N周均值" |
| `score` | REAL | 主线评分 | |
| `net_thesis` | REAL | 净 thesis 影响 | 增强减削弱的净值 |
| `top_driver` | TEXT | 本周期主驱动变量 | `decision.py::_top_drivers` 产出 |

---

## 6. 决策层产物(派生,不一定落表)

决策层在上述表之上计算两类视角输出(对应 PRD §3.3),通常作为派生结果按需生成而非长期落表:CEO 视角的主驱动变量 + 战略建议(`_top_drivers`),投资视角的公司相对位势矩阵(`_company_matrix`,composite 综合订单+营收+点名+净 thesis)与仓位调节信号(`_position_signals`,各主线 加/减/持 + 证据链)。

---

## 7. 字段口径维护原则

新增或修改字段时遵循三条:第一,枚举字段(main_line/scenario/impact_dim/thesis_impact)的取值必须来自 `ontology.py`,不允许在表里出现 ontology 之外的自由值;第二,数字字段(order_amount/capex/opex)入库前做类型校验,解析失败置空而非塞文本;第三,任何 schema 变更同步更新本数据字典与 `architecture.md` §2 的模块说明,保持三处一致。

---

> **免责声明** — 本数据字典描述的 schema 随 Phase 演进可能调整,以 `db.py` 实际定义为准。所属系统产出仅用于研究效率提升,不构成投资建议。