# macro-station

**Repository Path**: powercs12/macro-station

## Basic Information

- **Project Name**: macro-station
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-25
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Economic Data Site

一个用于学习和展示经济指标的单体仓库：React 前端、TypeScript API、Python 3.13 采集器、PostgreSQL 主存储和 Redis 可选缓存。首页默认展示一个国家的指标卡片报表，可切换国家；点开卡片看详情，并在弹框内做跨国家对比。当前已注册 **52 个指标、17 个族、44 张卡片**（含 8 个读时计算的衍生指标），覆盖中国、美国、日本、英国、德国五国。
**CPI、失业率、政策利率、GDP 这四个族是跨国横向对比的**（CPI 有 5 国、失业率与政策利率各 4 国）。

按维度看：

- **价格**：中国 CPI（全国/城市/农村）、美国 CPI 与核心 CPI、中国 PPI、美国 PPI 与核心 PPI
- **就业**：中国城镇调查失业率、美国失业率与新增非农
- **利率**：中国 LPR、美国联邦基金利率目标区间
- **景气**：中美 PMI（制造业与非制造业/ISM 服务业）、消费者信心、企业景气指数
- **增长**：中国 GDP 与工业增加值、美国 GDP 与耐用品订单
- **消费**：中国社零、美国零售销售
- **货币**：中国 M2
- **地产**：中国 70 城房价、美国新屋开工/成屋销售/未决销售
- **外贸**：中国海关进出口、美国贸易差额
- **财政/外储/能源**：中国财政收入、外汇储备、全社会用电量

日英德的接入方式是"对齐已有族"——只选了能和现有族并排比较的指标（CPI、失业率、政策利率、GDP），
所以它们直接进入已有的对比视图，不需要新的界面。欧元区没有接入：它的接口走经济日历格式，
那批在 2025-09 之后整体停更。

**发布事件档案**（`#/events`）为每次美国 CPI 发布冻结"当时现场"：发布前预期快照与证据链接、官方初值与当时前值、分口径预期差，以及发布后 5m/30m/1h/1d 的标普期货、美元指数、美债收益率反应（由原始 5 分钟行情确定性计算，不靠 AI 推测）。

```bash
cp .env.example .env
createdb economic_data
npm install
npm run db:init
npm run db:seed   # 从 data/ 导入中国 + 美国 CPI，需要 API 已启动
npm run dev
```

默认前端地址是 `http://127.0.0.1:5173`；如果端口被占用，Vite 会自动切换到其他端口。API 端口由 `.env` 中的 `API_PORT` 决定，当前示例为 `6767`。

历史数据用 `db:seed` 从 `data/` 全量导入；之后新发布的月份增量拉取：`npm run collect:all`（或单独的 `collect:china` / `collect:usa` / `collect:fred`）。`ops/` 里的 launchd 配置装好后由常驻进程采集——**发布窗口感知调度**：某个指标临近发布日（freshness 推算 48h 内）就小时级探测，平时维持日更。每次采集都会写入一条运行记录，页面据此区分“来源停更”和“采集失败”。页面查询永远只读数据库。

**2026-10-25 起的能力**（设计见 [docs/designs/2026-10-25-feature-blueprint.md](docs/designs/2026-10-25-feature-blueprint.md)）：

- **衍生指标**：实际利率（中美日英）、痛苦指数，注册在数据库里读时计算，自动进卡片与多国对比
- **经济日历**（`#/calendar`）+ **发布/停更/质量/周报通知**（飞书 webhook，`notification_channels` 配置）
- **任意序列对比**（`#/compare`）：跨指标跨国家 2–6 条，同比/指数化/z-score，URL 即分享链接
- **全球总览矩阵**（`#/global`）、**⌘K 搜索**、**图表事件标注**（衰退底纹/加息周期）、**修订统计**（"初值平均被上修多少"）
- **AI 本期解读**（配置 LLM 后生成、按期缓存；支持 OpenAI / Anthropic 协议，DeepSeek Search 参考资料与链接可选，失败降级不影响数据）
- **FRED 第二来源**（配 `FRED_API_KEY` 恢复停更序列）、**数据质量守护**（离谱值入库即告警+页面 ⚠）
- **CSV/PNG 导出**、**开放 API**（`/api/v1` + token，默认关闭）、**采集健康视图**（`#/ops`）
- **工程化**：`npm run db:migrate` / `db:backup`、docker-compose.dev.yml、GitHub Actions CI、Playwright E2E

数据是否陈旧按**统计期**判定，不看采集时间：来源停更时采集器仍会成功返回 0 条。AkShare 的美国环比与核心环比接口曾在 2025-08 前后停更（序列一度落后 12 期），现已恢复；FRED 第二来源已就位兜底。

指标注册在数据库（`indicator_fields`）而不是代码里：加一个指标只需要写 SQL，API 和前端都不用改。增量采集带 12 期修订窗口，上游对历史月份的修订会被捕获，旧值归档到 `observation_revisions` 而不是静默覆盖。

Redis 只缓存指标元数据，不是数据权威来源。Redis 不可用时，API 会直接从 PostgreSQL 读取。

项目文档集中在 [`docs/`](docs/README.md)：

- [架构总览](docs/architecture.md)
- [仓库与代码目录](docs/repository-structure.md)
- [前端说明](docs/frontend.md)
- [API 说明](docs/api.md)
- [采集器说明](docs/collector.md)
- [数据库与元数据](docs/database.md)
- [编码规范](docs/coding-standards.md)
- [开发与验证](docs/development.md)