# microdata_backend

**Repository Path**: jmdvirus/microdata_backend

## Basic Information

- **Project Name**: microdata_backend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-02
- **Last Updated**: 2026-10-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MacroData Backend

宏观数据服务后端 —— 基于 FastAPI + MongoDB(pymongo)，为前端展示/管理界面提供 REST API。

> 配套文档：[CHANGES.md](./CHANGES.md) 修改记录 ｜ [LESSONS.md](./LESSONS.md) 踩坑与结论（环境/conda/PowerShell/Mongo 数据陷阱，改代码前先看）

## 环境

- Python 运行环境：conda 环境 `pyeasy`
- 依赖：见 `requirements.txt`（fastapi / uvicorn / pymongo / pydantic / python-dotenv）

```bash
# 依赖已安装在 pyeasy 环境中，如需重装：
conda run -n pyeasy pip install -r requirements.txt
```

## 配置

`.env`（gitignore 不提交真实环境时请自行创建）：

```env
MONGO_URI=mongodb://jkstock:jkstock8989@192.168.3.39:27017/stock
MONGO_DB=stock
MONGO_COLLECTION=macro_daily
HOST=0.0.0.0
PORT=8000
```

## 启动

**方式一（推荐）**：双击 `start.bat`（或资源管理器中右键运行）

**方式二**：命令行手动启动

```bash
cd backend
conda run -n pyeasy uvicorn app.main:app --host 0.0.0.0 --port 8000
```

- API 根路径：http://127.0.0.1:8000
- Swagger 文档：http://127.0.0.1:8000/docs

## 工程结构

```
backend/
├── .env                    # 运行配置（Mongo 连接等）
├── requirements.txt
├── app/
│   ├── config.py           # 环境变量加载
│   ├── db.py               # Mongo 客户端单例 + (code,date) 唯一索引
│   ├── schemas.py          # Pydantic v2 校验模型（date 三态：日/月/季）
│   └── main.py             # 全部 REST API
└── scripts/
    ├── check_uncategorized.py   # 排查未分类 code（一次性工具）
    └── recategorize.py          # 按 code 统一 category/name（可重复执行）
```

## API 一览（/api/v1）

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/health` | 健康检查（返回连接状态与总条数） |
| GET | `/macro/meta` | 指标元数据：全部 code/名称/分类/单位/频率/条数/时间范围 |
| GET | `/macro/series` | 多指标时序查询，codes 逗号分隔；支持频率、起止过滤 |
| GET | `/macro/rows` | 单指标明细分页（管理表格用） |
| POST | `/macro/upsert` | 新增/覆盖一条（code+date 唯一键） |
| POST | `/macro/patch` | 按 (code,date) 局部修改部分字段 |
| DELETE | `/macro/delete` | 删除一条 |
| POST | `/macro/batch` | 批量写入，三步校验（空值/payload 内重复/库里已存在），支持 insert_only / upsert / overwrite 三种模式 |
| POST | `/macro/scaffold` | 按频率(日/月/季)在区间内补齐空骨架，已存在自动跳过 |

## 数据模型（macro_daily 集合）

```json
{
  "code": "sh000001",       // 指标代码（唯一键组成之一）
  "name": "上证指数",        // 显示名
  "category": "index_cn",   // 分类：index / index_cn / index_hk / fx / gold / oil / house / macro_cn
  "unit": "%",              // 单位（可空）
  "date": "2026-08-21",     // 三种形态：YYYY-MM-DD(日) / YYYY-MM(月) / YYYY-Qx(季)
  "value": "3891.1751",     // 数值统一字符串存储
  "updated_at": "..."       // 最近更新时间
}
```

- 唯一索引：`uniq_code_date` on `(code, date)`，服务启动时自动确保
- 频率由 date 形态自动推断，meta 接口返回每个 code 的 frequency

## 分类规则（scripts/recategorize.py 维护）

| category | 内容 |
|---|---|
| index | 国际指数 + ETF 相关（dji/ixic/sp/gb_sox/sti/dax/ibex 及 _etf 变体） |
| index_cn | A股指数（上证/深成/创业板/沪深300/科创50） |
| index_hk | 港股指数（恒生/国企/恒生科技） |
| fx | 汇率（USD/EUR/GBP/JPY 对 CNY） |
| gold / oil | COMEX 黄金 / WTI 原油 |
| house | 房价指数（百城新房/二手房、房租） |
| macro_cn | 中国宏观基础（CPI/PPI/PMI/GDP/M2/工业增加值/社零/LPR/外储） |

新增 code 需要调整分类时：修改 `recategorize.py` 的 `CATEGORY_RULES` / `NAME_RULES` 后重跑即可（幂等）。