增加天气服务文档说明

docs/.vuepress/config.js

@@ -12,7 +12,8 @@ module.exports = {
             { text: '任务调度', link: '/task/' },
             { text: '报警系统', link: '/alarm/' },
 //            { text: '报表统计系统', link: '/report/' },
-            { text: '数据仓库', link: '/dw/' }
+            { text: '数据仓库', link: '/dw/' },
+            { text: '天气服务', link: '/wther/' }
         ],
 
         sidebarDepth: 2,
@@ -90,7 +91,14 @@ module.exports = {
                     children: [{ title: '对象数据', path: '/rwd/instance_object' }, { title: '关系数据', path: '/rwd/instance_relation' }]
                 },
                 { title: 'IOT', path: '/rwd/iot' }
-            ]
+            ],
+            '/wther': [
+                {
+                    title: '天气服务',
+                    collapsable: false,
+                    children: [{ title: '服务介绍', path: '/wther/wther_prod' }, { title: '服务接口', path: '/wther/wther_api' }]
+                }
+            ],
         }
     }
 }

docs/wther/index.md

@@ -0,0 +1,9 @@
+## 天气服务
+
+#### [产品介绍](/wther/wther_prod.md)
+
+#### [接口文档](/wther/wther_api.md)
+
+
+
+

docs/wther/wther_api.md

@@ -0,0 +1,450 @@
+# 天气服务接口文档
+
+## 统一说明
+
+所有查询指定城市天气数据的接口，都需要在参数中指明是哪一个城市。目前天气服务支持传入以下三个参数（至少有一个），来定位城市。三个参数的key及说明如下：
+
+| 参数key    | 说明                         |  优先级      | 举例     |
+| --------- | ---------------------------- | ---------- | -------- |
+| cityCode  | 合法数据字典城市编码，6位数字字符串 | 最高       | 110101    |
+| projectId | 合法数据字典项目ID，12位字符串    | 高         | Pj1101010001 |
+| cityName  | 城市中文名，字符串              | 低         | 北京        |
+
+
+## 业务接口
+**注意：** 凡是入参涉及到传城市信息的，以下接口说明中均已cityName作为参数，实际接口调用时，可根据"统一说明"，使用cityCode或者projectId代替cityName参数作为入参。
+
+### 实时数据查询
+
+简介：接口返回指定城市的最新天气数据信息，数据分为两大类A和B。A包括以下信息：天气现象文字(晴、多云...)、天气现象编码、温度、体感温度、气压、相对湿度、能见度、风速、风向文字、风向角度、风力等级、云量（范围0~100，天空被云覆盖的百分比）。
+B包括以下信息：空气质量文字(优、良...)、首要污染物、PM2.5、PM10、so2、no2、co、o3。 
+
+Method：POST 
+
+Header参数：Content-Type=application/json 
+
+URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/dataNow 
+
+请求参数： 
+
+```json
+{
+    "cityName":"城市名称，比如：上海",
+    "dataType":"枚举值字符串：weather,只返回A类数据; air,只返回B类数据; all, 返回A和B类数据"
+}
+```
+
+返回结果：
+
+正确JSON示例
+
+```json
+{
+    "result": "success",
+    "message": null,
+    "data": {
+        "code": "天气现象编码，示例：8", 
+        "o3": "43",
+        "visibility": "能见度示例：9.3",
+        "pm10": "50",
+        "wind_direction": "风向文字，示例：北",
+        "pressure": "气压值，示例：1017", 
+        "clouds": "云量，示例：90", 
+        "co": "0.532",
+        "feels_like": "体感温度，示例：17",
+        "quality": "空气质量文字，示例：优",
+        "no2": "45",
+        "pm25": "30",
+        "so2": "7",
+        "last_update": "2021-01-21 15:50:00",
+        "wind_scale": "风力等级，示例：0",
+        "aqi": "50",
+        "primary_pollutant": "首要污染物，示例：pm25，若无则为空串", 
+        "temperature": "17",
+        "humidity": "相对湿度，示例：82", 
+        "wind_direction_degree": "风向角，示例：0", 
+        "wind_speed": "风速，示例：0.72",
+        "text": "天气现象文字，示例：阴"
+    }
+}
+```
+
+错误JSON示例
+
+```json
+{
+    "result": "fail",
+    "message": "错误信息,如果接口发生错误会返回该字段"
+}
+```
+
+### 预报数据查询
+
+简介：获取未来24小时预报数据，或14天日预报数据。此“未来24小时”包含当前小时整点，以及未来的23个小时的23个整点，共24条天气数据。
+
+Method：POST 
+
+Header参数：Content-Type=application/json 
+
+URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/dataPredict 
+
+请求参数： 
+
+```json
+{
+    "cityName":"城市名称，比如：上海",
+    "dataType":"枚举值字符串：hour,小时预报; day,日预报; disaster,灾害预报",
+    "startTime":"开始时间（包含），dataType为disaster时需要该参数，示例：2021-01-18 00:00:00",
+    "endTime":"结束时间（不包含），dataType为disaster时需要该参数，示例：2021-01-21 00:00:00"
+}
+```
+
+返回结果：
+
+正确JSON，小时预报数据示例
+
+```json
+{
+    "result": "success",
+    "message": null,
+    "data": [
+        {
+            "time": "时间，str，示例：2021-01-21 17:00:00",
+            "text": "天气现象文字，str，示例：晴",
+            "code": "天气现象编码，str，示例：0",
+            "temperature": "温度，str，示例4", 
+            "humidity": "相对湿度，str，示例：41",
+            "wind_direction": "风向文字，str，南",
+            "wind_speed": "风速，str，示例：10"
+        },
+        {
+            "time": "2021-01-21 18:00:00",
+            "text": "晴",
+            "code": "1",
+            "temperature": "1",
+            "humidity": "42",
+            "wind_direction": "西南",
+            "wind_speed": "15"
+        },
+        {
+            "time": "2021-01-22 16:00:00",
+            "text": "晴",
+            "code": "0",
+            "temperature": "4",
+            "humidity": "62",
+            "wind_direction": "南",
+            "wind_speed": "10"
+        }
+    ]
+}
+```
+
+正确JSON，日预报数据示例
+
+```json
+{
+    "result": "success",
+    "message": null,
+    "data": [
+        {
+            "date": "2021-01-21",
+            "high": "日最高温，Str，示例：6",
+            "rainfall": "降雨量，str， 示例：0.0",
+            "codeDay": "白日气象编码，示例：0",
+            "windDirectionDegree": "风向角，str，示例：225", 
+            "textDay": "白日气象文字，str，示例：晴",
+            "codeNight": "白日气象编码，str，示例：1",
+            "low": "日最低温，str，示例：-5",
+            "textNight": "夜晚气象文字，str，示例：晴",
+            "humidity": "相对湿度，str，示例：49",
+            "windDirection": "风向文字，str，示例：西南",
+            "windSpeed": "风速,str，示例：8.4",
+            "windScale": "风力等级,str，示例：2"
+        },
+        {
+            "date": "2021-01-28",
+            "maxTemperature": "4",
+            "rainfall": "0.0",
+            "codeDay": "0",
+            "windDirectionDegree": "225",
+            "textDay": "晴",
+            "codeNight": "1",
+            "minTemperature": "-5",
+            "textNight": "晴",
+            "humidity": "44",
+            "windDirection": "西南",
+            "windSpeed": "8.4",
+            "windScale": "2"
+        }
+    ]
+}
+```
+
+正确JSON，日灾害预警示例
+
+注：
+1. 同一种灾害预警如果级别不同，则结果可能返回多条结果数据；
+2. 灾害数据更新频率为15分钟/次；
+3. 所查询的时间跨度最大支持一年。
+
+```json
+{
+    "result": "success",
+    "message": null,
+    "data": [
+        {
+            "insertTime": "2021-01-19 06:16:06",
+            "path": "北京,北京,中国",
+            "level": "黄色",
+            "pubTime": "2021-01-19 06:08:39",
+            "name": "北京",
+            "description": "市气象台2021年1月19日06时00分发布道路结冰黄色预警信号：目前本市大部分地区出现降雪天气，且地面温度较低，预计当前至20日中午将出现道路结冰现象，请注意防范。",
+            "cityId": "WX4FBXXFKE4F",
+            "title": "北京市气象台2021年1月19日06时00分发布道路结冰黄色预警信号",
+            "type": "道路结冰"
+        }
+    ]
+}
+```
+
+错误JSON示例
+
+```json
+{
+    "result": "fail",
+    "message": "错误信息,如果接口发生错误会返回该字段"
+}
+```
+
+### 历史数据查询
+
+简介：获取小时历史数据或日历史数据。
+
+小时历史数据查询提示：
+1. 该接口能够查询到的最新的小时数据会至少比当前时间滞后半小时，例如结束时间为当天10:10，则接口只能查到最新小时数据为9:00的小时数据；若结束时间为当天10:35则能查到的最新小时数据为10:00的数据；
+2. 目前只支持全国约1200个城市区域；
+3. 改历史历史数据最远可追溯至17年，有些城市最远开始于2020年7月；
+4. 接口最大支持查询7天的数据。
+
+日历史数据查询提示：最大支持一年的数据查询。
+
+Method：POST 
+
+Header参数：Content-Type=application/json 
+
+URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/dataHistory 
+
+请求参数： 
+
+```json
+{
+    "cityName":"城市名称，比如：上海",
+    "dataType":"枚举值字符串：hour,小时数据; day,日数据",
+    "startTime":"开始时间（包含），str，示例：2021-01-01 00:00:00",
+    "endTime":"结束时间（不包含），str，示例：2021-01-03 00:00:00"
+}
+```
+
+返回结果：
+
+正确JSON，小时历史数据示例
+
+```json
+{
+    "result": "success",
+    "message": null,
+    "data": [
+        {
+            "code": "天气现象编码，str，示例：1",
+            "visibility": "能见度，str，示例：15.3",
+            "o3": "7",
+            "pm10": "60",
+            "pressure": "气压值，str，示例：1023",
+            "clouds": "云量，str，示例：0",
+            "co": "0.608",
+            "quality": "空气质量文字，str，示例：良", 
+            "feelsLike": "体感温度，str，示例：-6",
+            "windDirectionDegree": "风向角，str，示例：0",
+            "no2": "52",
+            "hourTime": "2021-01-01 00:00:00",
+            "pm25": "22",
+            "so2": "3",
+            "temperature": "温度，str，示例：-7",
+            "aqi": "气象指标指数，str，示例：55",
+            "humidity": "相对湿度，str，示例：37",
+            "primaryPollutant": "首要污染物，str，示例：PM10",
+            "text": "天气现象文字，str，示例：晴",
+            "windDirection": "风向，str，示例：北",
+            "windSpeed": "风速，str，示例：2.16",
+            "windScale": "风力等级，str，示例：1"
+        }
+    ]
+}
+```
+
+正确JSON，日历史数据示例
+
+```json
+{
+    "result": "success",
+    "message": null,
+    "data": [
+        {
+            "rainfall": "降雨量，str，示例：0.0",
+            "codeDay": "白日气象编码，str，示例：0",
+            "dayTime": "2021-01-01 00:00:00",
+            "windDirectionDegree": "风向角，str，示例：225",
+            "high": "日最高温，str，示例：1",
+            "textDay": "白日天气现象文字，str，示例：晴",
+            "codeNight": "夜晚气象编码，str，示例：1",
+            "low": "日最低温，str，示例：-11",
+            "textNight": "晚间天气现象文字，str，示例：晴",
+            "humidity": "相对湿度，str，示例：24",
+            "windDirection": "降雨量，str，示例：西南",
+            "windSpeed": "风速，str，示例：8.4",
+            "windScale": "风力等级，str，示例：2"
+        }
+    ]
+}
+```
+
+错误JSON示例
+
+```json
+{
+    "result": "fail",
+    "message": "错误信息,如果接口发生错误会返回该字段"
+}
+```
+
+### 统计数据查询
+
+简介：获取以下气象指标【温度、相对湿度、风速、气压、能见度】的日最大/小值和日均值数据。
+
+提示：
+1. 有小时天气历史数据的城市才有日统计数据记录；
+2. 数据在每日0-1时更新；
+3. 接口最大支持一年的数据查询；
+
+Method：POST 
+
+Header参数：Content-Type=application/json 
+
+URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/dataStatistic 
+
+请求参数： 
+
+```json
+{
+    "cityName":"城市名称，比如：上海",
+    "dataSize":"枚举值字符串：max,返回最大最小值; avg,返回均值，all,返回最值和均值",
+    "startTime":"开始时间（包含），str，示例：2021-01-01 00:00:00",
+    "endTime":"结束时间（不包含），str，示例：2021-01-03 00:00:00"
+}
+```
+
+返回结果：
+
+正确JSON示例
+
+```json
+{
+    "result": "success",
+    "message": null,
+    "data": [
+        {
+            "maxVisibility": 27.0,
+            "avgPressure": 1021.5,
+            "maxTemp": 1.0, 
+            "avgHumidity": 37.0,
+            "avgTemp": -5.4, 
+            "minHumidity": 17.0,
+            "dayTime": "2021-01-01 00:00:00",
+            "minTemp": -11.0,
+            "maxWindSpeed": 8.0,
+            "avgWindSpeed": 4.0,
+            "minVisibility": 11.0,
+            "avgVisibility": 17.0,
+            "minPressure": 1020.0,
+            "maxPressure": 1024.0,
+            "minWindSpeed": 1.0,
+            "maxHumidity": 59.0
+        }
+    ]
+}
+```
+
+错误JSON示例
+
+```json
+{
+    "result": "fail",
+    "message": "错误信息,如果接口发生错误会返回该字段"
+}
+```
+
+### 日出日落时间计算
+
+简介：根据坐标或者数据字典城市编码或者包含数据字典城市编码的项目数据字典ID计算日出日落时间。
+
+提示：入参支持数据字典城市名称，数据字典城市编码，符合数据字典命名规范的项目ID，经纬度值，四项参数不能全部为空，使用优先级：经纬度值> 数据字典城市编码 > 项目ID > 城市名称。该接口支持最长一年的数据计算。
+
+Method：POST 
+
+Header参数：Content-Type=application/json 
+
+URL：/EMS_Weather/Spring/MVC/entrance/unifierJson/sunRiseAndSetCompute 
+
+请求参数： 
+
+```json
+{
+    "cityName":"城市名称，比如：上海",
+    "longitude":116.4,
+    "latitude":39.9,
+    "startDay":"开始日（含），str，示例：2021-02-14",
+    "endDay":"结束日（不含），str，示例：2021-02-15"
+}
+```
+
+返回结果：
+
+正确JSON示例
+
+```json
+{
+    "result": "success",
+    "message": null,
+    "data": [
+        {
+            "day": "日时间yyyy-MM-dd，str，示例：2021-02-14",
+            "sunSet": "日落时间HH:mm:ss，str，示例：17:50:00",
+            "sunRise": "日出时间HH:mm:ss，str，示例：07:06:00"
+        }
+    ]
+}
+```
+
+错误JSON示例
+
+```json
+{
+    "result": "fail",
+    "message": "错误信息,如果接口发生错误会返回该字段"
+}
+```
+
+### 天气现象图标下载
+
+简介：获取天气现象编码对应的图标图片数据。
+
+Method：GET 
+
+URL：/EMS_Weather/Spring/MVC/entrance/download/icon/weatherCode-theme-size 
+
+URL说明：
+1. 以HTTP-GET访问接口，接口参数在URL最后面；
+2. 参数格式为weatherCode-theme-size。其中weatherCode为天气现象编码，必需；theme为图片主题，非必需，支持dark、light、classic三种；size为图标大小，非必需，支持big、small两种。
+3. 接口请求示例：/EMS_Weather/Spring/MVC/entrance/download/icon/5-classic-big
+
+返回结果：数据流

docs/wther/wther_prod.md

@@ -0,0 +1,136 @@
+# 天气服务介绍
+
+## 基本情况
+
+### 简介
+
+本天气服务通过定时访问第三方天气服务商的服务，将得到的指定城市的天气数据存入本地，并向外提供了可获取天气数据的HTTP接口，供各产品线业务系统查询使用。
+
+### 数据服务
+
+本服务支持以下气象指标和数据类型的查询
+
+#### 气象指标全集
+
+| 指标名        | 英文标识       | 单位                      | 说明                                    |
+| ------------ | ------------ | ------------------------- | -------------------------------------- |
+| 气温          | temperature  | c，摄氏度                  | 对应日最高/低温标识：high/low              |
+| 体感温度       | feels_like   | c，摄氏度                  | 英文标识2：feelsLike                    |
+| 相对湿度       | humidity     | 数值在0~100之间，是百分比数值 |                                        |
+| 气压          | pressure     | 单位mbar，百帕              |                                        |
+| 能见度        | visibility   | km，千米                    |                                        |
+| 风速          | wind_speed   | km/h，千米每小时             | 英文标识2：windSpeed                     |
+| 风力等级       | wind_scale   | 数值，>=0，无单位            | 英文标识2：windScale                     |
+| 风向文字       | wind_direction   |   无单位              | 英文标识2：windDirection                  |
+| 风向角度       | wind_direction_degree   | 角度数值，0~360，0为正北，90为正东，180为正南 | 英文标识2：windDirectionDegree         |
+| 降水量         | rainfall    | mm，毫米                     |                                         |
+| 首要污染物      | primary_pollutant   | 无单位             | 英文标识2：primaryPollutant               |
+| 气象文字描述    | text      | 阴、晴、雨、雪...，无单位        | 对应白日/夜晚标识：textDay/textNight      |
+| 气象编码       | code      | 无单位                        | 对应白日/夜晚标识：codeDay/codeNight        |
+| 云量           | clouds      | 数值，0~100，无单位             |                                         |
+| pm25          | pm25       | 1小时平均值。单位：μg/m³        |                                         |
+| pm10          | pm10       | 1小时平均值。单位：μg/m³        |                                         |
+| so2           | so2        | 1小时平均值。单位：μg/m³        |                                         |
+| no2           | no2        | 1小时平均值。单位：μg/m³        |                                         |
+| co           | co          | 1小时平均值。单位：μg/m³        |                                         |
+| o3           | o3          | 1小时平均值。单位：μg/m³        |                                         |
+| aqi          | aqi         | 数值，无单位                   |                                         |
+
+#### 气象指标枚举值
+
+##### 空气质量类别
+
+```json
+["优", "良", "轻度污染", "中度污染", "重度污染", "严重污染"]
+```
+
+##### 天气现象编码与文字描述
+
+```json
+{
+    "0": "晴",
+    "1": "晴",
+    "2": "晴",
+    "3": "晴",
+    "4": "多云",
+    "5": "晴间多云",
+    "6": "晴间多云",
+    "7": "大部多云",
+    "8": "大部多云",
+    "9": "阴",
+    "10": "阵雨",
+    "11": "雷阵雨",
+    "12": "雷阵雨伴有冰雹",
+    "13": "小雨",
+    "14": "中雨",
+    "15": "大雨",
+    "16": "暴雨",
+    "17": "大暴雨",
+    "18": "特大暴雨",
+    "19": "冻雨",
+    "20": "雨夹雪",
+    "21": "阵雪",
+    "22": "小雪",
+    "23": "中雪",
+    "24": "大雪",
+    "25": "暴雪",
+    "26": "浮尘",
+    "27": "扬沙",
+    "28": "沙尘暴",
+    "29": "强沙尘暴",
+    "30": "雾",
+    "31": "霾",
+    "32": "风",
+    "33": "大风",
+    "34": "飓风",
+    "35": "热带风暴",
+    "36": "龙卷风",
+    "37": "冷",
+    "38": "热",
+    "99": "未知"
+}
+```
+
+##### 灾害预警类型
+
+```json
+["台风", "暴雨", "暴雪", "寒潮", "大风", "沙尘暴", "高温", "干旱", "雷电", "冰雹", "霜冻", "大雾", "道路结冰", "雷雨大风"]
+```
+
+##### 灾害级别
+
+```json
+["白色", "蓝色", "黄色", "橙色", "红色"]
+```
+
+
+#### 数据类型
+按时间划分，支持以下类型数据查询： 
+
+* 实时数据，气象指标：支持全部气象指标；
+* 24小时预报，气象指标：温度、相对湿度、能见度、气象文字、气象代码、风向、风速；
+* 14日天气预报，气象指标：日最高/低温、相对湿度、白天气象文字/代码、夜晚气象文字/代码、风向文字、风向角、风速、风力等级、降水量；
+* 小时级别历史数据，最早支持到2017年1月1日。 气象指标： 温度、相对湿度、气象文字、气压、能见度、风向文字、风速、风向角风速、风力等级、（2020.7.1之前不支持以下类型）体感温度、空气质量、云量、pm25、pm10、so2、no2、co、o3；
+* 日历史数据，最早支持到2017年1月1日。 气象指标： 日最高温、日最低温、相对湿度、白日气象文字、夜晚气象文字、风向文字、风速、风向角风速、风力等级、（2020.7.1之前不支持以下类型）白天夜晚\气象代码、降雨量；
+
+按功能划分，还支持以下数据获取： 
+
+* 灾害预警，支持气象部门发布的灾害预警数据查询；
+* 统计数据，支持以下气象指标 [温度, 相对湿度, 风速, 气压, 能见度] 的日最大/小值，日均值；
+* 日出日落时间计算，支持基于经纬度坐标（数据字典项目ID或数据字典城市编码）的日出日落时间计算；
+* 天气现象图标，支持天气现象（即阴晴雨雪...）图标下载
+
+### 数据来源
+
+本天气服务中所有天气相关数据来源于服务提供商——心知天气（https://www.seniverse.com/）。
+
+### 支持城市
+* 天气实况数据，日历史天气数据，预报数据和灾害预警数据支持3000+个城市地区（几乎涵盖全国所有地区）
+* 小时历史数据和统计数据支持约1200个城市地区（涵盖全国所有一、二、三、四、五线城市的市级，部分涵盖区级）
+
+### 产品更新记录
+
+* 2020年8月15日，对整个底层代码逻辑行了重构，重新设计了表结构及存储方式，优化了定时任务，升级了数据字典城市编码与第三方城市码的匹配算法。新增若干接口，支持约1200个城市的小时天气数据查询和日天气数据统计查询，支持3000多个城市区域的日天气数据查询，支持日出日落数据数据查询，支持天气气象图标下载；
+* 2019年6月，新增若干接口，支持约300个城市小时天气数据查询和日数据统计查询，约1000个城市地区的日天气数据查询，并增加了灾害预警数据查询、月级别统计数据的计算；
+* 2018年10月，健全了项目的说明文档，接口文档，并对项目的定时任务逻辑进行了简单重构；
+* 2017年4月，作为一个定制项目被创建，提供了4个HTTP服务接口，支持约100个城市的日天气数据查询；