Weather Box - 天气盒子

一个轻量级的天气查询 Web 平台，输入城市或开启定位即可查看实时天气、7 天预报、温度走势图，并给出运动与出行建议。支持 AI 天气播报和 AI 出行问答。

---

项目简介

天气盒子是一个基于 Node.js + Express 的天气查询 Web 平台，前端采用原生 HTML/CSS/JavaScript 构建，无需任何前端框架。项目接入和风天气（QWeather）作为主要数据源，并以 Open-Meteo 作为免 Key 兜底数据源，支持 AI 天气播报与出行问答。

---

技术栈

层级	技术	说明
后端	Node.js + Express 4.x	单文件 server.js，极简依赖
前端	原生 HTML / CSS / JS	无框架、无构建步骤
图表	Chart.js	本地 vendor 引入
天气数据	QWeather + Open-Meteo	双源兜底，QWeather 优先
AI 模型	智谱 GLM (glm-4-flash)	OpenAI 兼容接口，后端代理调用
缓存	内存 Map	10 分钟 TTL
历史记录	本地 JSON 文件	最多保留 20 条

---

功能特性

基础天气

• 城市搜索：输入城市名，自动补全最多 8 条候选
• 定位查询：基于浏览器地理定位反查城市天气
• 热门城市：北京 / 上海 / 广州 / 深圳 / 杭州 / 成都 快捷入口
• 实时天气：温度、体感、湿度、风向、风力、降水量、能见度、气压、云量
• 7 天预报：日期、天气图标、温度区间、天气描述
• 温度走势：Chart.js 折线图展示最高/最低温变化
• 出行建议：基于温度 / 降水 / 风力 / 能见度 / 湿度的规则引擎生成
• 查询历史：本地持久化存储，点击可重新查询，支持清空
• 天气主题：主卡背景随天气状况动态变化

AI 增强

• AI 天气播报：基于实时 + 预报数据生成自然语言解读
• AI 出行问答：支持自然语言提问穿搭 / 出行建议，多轮上下文对话
• 优雅降级：未配置 AI Key 时自动隐藏相关功能，不影响主流程

---

项目结构

weather-box/
├── server.js                     # Express 后端（全部 API 端点）
├── package.json                  # 仅依赖 express
├── .env.example                  # 环境变量模板
├── public/
│   ├── index.html                # 前端页面入口
│   ├── app.js                    # 前端逻辑
│   ├── styles.css                # 样式文件
│   └── vendor/
│       └── chart.umd.min.js      # Chart.js 本地副本
├── data/                         # 运行时创建，存放 history.json
├── docs/
│   └── adr/                      # 架构决策记录
│       ├── 0001-qweather-node.md # 数据源选型
│       └── 0002-zhipu-glm.md     # AI 模型选型
├── CONTEXT.md                    # 术语表
├── PLAN.md                       # 项目计划
└── PLAN-AI.md                    # AI 功能计划

---

API 接口

方法	路径	说明
GET	/api/config	返回配置状态
GET	/api/geo/lookup	城市搜索与自动补全
GET	/api/weather	综合天气数据（实时 + 7 天预报 + 建议）
GET	/api/history	读取查询历史
DELETE	/api/history	清空查询历史
POST	/api/ai/brief	AI 天气播报
POST	/api/ai/ask	AI 出行问答

---

快速开始

环境要求

• Node.js 18+
• npm

1. 安装依赖

npm install

2. 配置环境变量（可选）

cp .env.example .env

.env 示例：

# 和风天气 API Key（可选，不配则使用 Open-Meteo 兜底）
QWEATHER_API_KEY=your_qweather_key
QWEATHER_API_HOST=https://devapi.qweather.com
QWEATHER_GEO_HOST=https://geoapi.qweather.com

# 智谱 GLM API Key（可选，不配则禁用 AI 功能）
ZHIPU_API_KEY=your_zhipu_key
ZHIPU_MODEL=glm-4-flash

# 服务端口
PORT=3000

3. 启动服务

npm start

访问 http://localhost:3000

---

数据来源

• 和风天气 QWeather：国内数据精准，需申请免费 Key
• Open-Meteo：全球免费天气数据源，无需 Key，作为兜底方案

---

项目亮点

• 极简依赖：后端仅依赖 express
• 双源兜底：QWeather 不可用时自动切换 Open-Meteo
• 无框架前端：原生 HTML/CSS/JS，加载快、易理解
• 规则引擎建议：无需大模型即可生成运动与出行建议
• AI 增强可选：配置 Key 即可启用 AI 播报与问答
• 本地历史记录：零数据库依赖

---

许可证

MIT License