blog-source/README.md

# Typecho 网站结构说明

这是基于 HarmonyHues 主题的 Typecho 博客站点，目录结构如下：

## 根目录（`/www/wwwroot/www.beihong.wang`）

- `index.php`、`index.html`：前端入口文件。
- `config.inc.php`：Typecho 配置（数据库、站点信息等）。
- `install.php`、`install/`：安装程序及脚本。
- 静态资源：`404.html`、`LICENSE.txt`、`img/` 等。

## 管理后台（`/admin`）

包含所有后台页面和资源，用于登录、发布文章、安装插件、修改主题等。

- 各种 PHP 页面 (`manage-posts.php`、`options-theme.php` 等)。
- `css/`、`js/`、`img/` 子目录存放后台所需的样式、脚本与图片。

## 用户资源（`/usr`）

- `themes/`：主题目录，当前使用 `HarmonyHues`。
  - `core/`：主题基础功能、配置。
  - `components/`：各类组件与小部件。
  - `assets/`：前端静态资源（CSS、JS、图片、一言文本等）。
  - `install/`、`functions.php` 等辅助文件。
- `plugins/`：已安装的插件，例如 AISummary、MarkdownParse 等。
- `uploads/`：用户上传内容，按照年份/月划分（如 `2026/`）。

## 核心代码（`/var`）

Typecho 系统运行时代码库：

- `Typecho/`、`Utils/`、`Widget/` 等子目录，包含框架核心、数据库接口、帮助函数等。
- `IXR/`：XML‑RPC 实现，用于远程发布。

## 说明

- 遇到功能问题时可根据上述结构定位相关文件。例如，
  - 一言组件在 `usr/themes/HarmonyHues/components/widgets/widget-yiyan.php`。
  - 本地资源应使用文件路径，而非通过 URL 访问。

- `/usr/themes/HarmonyHues` 主题目录包含所有与页面显示相关内容，便于定制。
- `/admin` 提供完整的后台管理界面。

如需进一步分析插件、数据库结构或调试，
可在这些目录中查找对应文件或脚本。

## 更新日志

- 2026-03-03：新增天气小部件功能。
  1. 主题 `components/widgets/widget-weather.php` 添加天气查询代码，支持缓存、城市和 API Key 配置。
  2. 在 `components/sidebar.php` 中包含天气组件。
  3. `core/theme-config.php` 增加 `ShowSidebarWeather` 选项以及 `weatherCity`、`weatherApiKey` 配置项。
  4. 风格与一言组件一致；请输入有效 API Key 并在后台启用侧边栏“天气”模块。
  5. 修改前已通过 `tar` 备份主题文件，备份包位于 `usr/themes/HarmonyHues-backup-2026-03-03.tar.gz`。

- 更详细的实现步骤及说明可参考在其它聊天记录的说明。

- 2026-03-03（续）：天气模块进一步增强。
  * 缓存结构升级，城市改变后立即生效并在后台保存查询城市。
  * 城市名称支持中英文互译，常见城市输入英文也能显示中文名。
  * 显示中文描述保持不变，增加体感温度、湿度、气压、风速/风向等信息。
  * 加入 OpenWeatherMap 图标，优化字体、行高、布局与对齐，使输出居中且更协调。
  * 注释和调试输出更详细，方便开发者阅读与排查。

### 注意事项

- 请使用 **有效的天气 API Key**。上述 key `464032d12749b7c0df937df0215af884` 返回错误“Invalid API key”，说明并非 OpenWeatherMap 认可的密钥。访问 https://openweathermap.org/ 获取或检查你的帐号密钥。
- 也可以替换为其他天气服务（和风、心知等），只需改写 `widget-weather.php` 中的请求 URL 和参数。
- 错误信息会在侧边栏显示便于调试。