style:use restful api

README.md

@@ -46,13 +46,36 @@ uv run uvicorn app.main:app --reload
 
 ## API 端点
 
-### POST `/data` — 接收气象数据
+### GET `/stations` — 列出所有气象站
+
+获取所有已知气象站的列表（从观测数据中派生）。
+
+成功响应（200）：
+
+```json
+{
+  "stations": [
+    {
+      "name": "北京站",
+      "observation_count": 156,
+      "latest_observation_at": "2026-06-19T11:45:00.654321+00:00"
+    },
+    {
+      "name": "上海站",
+      "observation_count": 89,
+      "latest_observation_at": "2026-06-19T10:30:00.123456+00:00"
+    }
+  ],
+  "count": 2
+}
+```
+
+### POST `/stations/{station_name}/observations` — 接收气象数据
 
 请求体（JSON）：
 
 ```json
 {
-  "station_name": "北京站",
   "temperature": 26.5,
   "pressure": 1013.2,
   "relative_humidity": 68.0
@@ -63,11 +86,12 @@ uv run uvicorn app.main:app --reload
 
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `station_name` | string | 是 | 气象站名称 |
 | `temperature` | float | 否 | 温度（摄氏度） |
 | `pressure` | float | 否 | 气压（hPa） |
 | `relative_humidity` | float | 否 | 相对湿度（%，0-100） |
 
+> 气象站名称从 URL 路径中获取，不再出现在请求体中。
+
 成功响应（201）：
 
 ```json
@@ -83,12 +107,12 @@ uv run uvicorn app.main:app --reload
 
 `received_at` 由服务端在收到数据时自动记录。
 
-### GET `/data/{station_name}` — 查询最新数据
+### GET `/stations/{station_name}/observations/latest` — 查询最新数据
 
-获取指定气象站的最新一条记录。站名支持中文，直接放在 URL 路径中即可：
+获取指定气象站的最新一条记录：
 
 ```
-GET /data/北京站
+GET /stations/北京站/observations/latest
 ```
 
 成功响应（200）：
@@ -106,35 +130,44 @@ GET /data/北京站
 
 未找到数据时返回 404。
 
-### GET `/data/{station_name}/history` — 查询历史数据
+### GET `/stations/{station_name}/observations` — 查询历史数据
 
 获取指定时间范围内的所有记录。支持两种查询方式：
 
 **按最近 N 小时查询：**
 
 ```
-GET /data/北京站/history?hours=24
+GET /stations/北京站/observations?hours=24
 ```
 
 **按自定义时间范围查询：**
 
 ```
-GET /data/北京站/history?start=2026-06-19T00:00:00&end=2026-06-19T12:00:00
+GET /stations/北京站/observations?start=2026-06-19T00:00:00&end=2026-06-19T12:00:00
+```
+
+**分页查询：**
+
+```
+GET /stations/北京站/observations?limit=50&offset=0
 ```
 
 参数说明：
 
 | 参数 | 类型 | 说明 |
 |------|------|------|
-| `hours` | int | 从现在往前推 N 小时。如果同时指定了 `start`，则仅影响 `start` |
+| `hours` | int | 从现在往前推 N 小时。如果同时指定了 `start`，则覆盖 `start` |
 | `start` | datetime | 时间范围起点（ISO 8601 格式，UTC），不传则不限制 |
 | `end` | datetime | 时间范围终点（ISO 8601 格式，UTC），不传则默认到当前时刻 |
+| `limit` | int | 返回的最大记录数 |
+| `offset` | int | 跳过的记录数（用于分页），默认 0 |
 
 成功响应（200）：
 
 ```json
 {
   "station_name": "北京站",
+  "count": 2,
   "records": [
     {
       "id": 42,
@@ -156,7 +189,7 @@ GET /data/北京站/history?start=2026-06-19T00:00:00&end=2026-06-19T12:00:00
 }
 ```
 
-未找到匹配数据时返回空列表。
+未找到匹配数据时返回空列表，气象站不存在时返回 404。
 
 ---