初始提交：浏览器首页 MyHomePage 全栈项目

# 项目概述个人浏览器首页导航应用，支持书签分类管理、搜索引擎快捷搜索、必应每日壁纸轮播、前后端分离部署，适配 1Panel 服务器（Docker 模式）。 # 技术栈 - 前端：Vue 3 + TypeScript + Vite + Pinia + Capacitor（Android 打包） - 后端：.NET 8 + SqlSugar（多数据库） + SQLite/MySQL + Swashbuckle - 部署：1Panel 应用商店自定义应用（Docker Compose 模式） # 项目结构 - backend/ .NET 8 API 后端（8 个 Controller + 15 个 Service） - frontend/ Vue 3 前端（19 个组件 + 9 个 API 模块 + 5 个 Store） - docker/ Docker 部署文件（后端镜像 + Nginx 反代） - docs/ 部署手册（1Panel 实战版） - scripts/ E2E 测试脚本 # 已实现功能 - 书签管理：增删改查 + 树形分类 + 拖拽排序 + 主色自适应 - 搜索引擎：8 个内置引擎 + 自定义引擎 + favicon 自动抓取 - 必应壁纸：每日轮播 + 多分辨率自动选择 + 1.6MP 质量优先 - 全局设置：主题/行为/数据/工具 4 分类 + 跨设备同步 - 文件上传：图标/书签/通用（容器持久化 + 跨域 URL 拼接） - 同步：基于变更日志的设备间数据同步 - 跨域部署：前后端分离 + runtime config.json 无需重新编译 # 进度记录 - 已完成 P0~P52 共 53 个开发节点（详细见说明文档.md） - 当前版本：v1.0 部署就绪 # 部署文档 - README.md：项目说明 + 快速开始 - 说明文档.md：完整开发进度（中文） - docs/DEPLOY.md：1Panel 部署手册（Docker 模式）
2026-07-05 05:09:56 +08:00
commit 68be41e7a2
129 changed files with 15900 additions and 0 deletions
@@ -0,0 +1,80 @@
+using Microsoft.AspNetCore.Mvc;
+using MyHomePage.Api.Common;
+using MyHomePage.Api.Models.Dtos;
+using MyHomePage.Api.Services;
+
+namespace MyHomePage.Api.Controllers;
+
+/// <summary>
+/// 360 在线壁纸代理（P34）：
+///   - GET  /api/wallpaper/categories     拉全部分类（24h 缓存）
+///   - GET  /api/wallpaper/random         按视口分辨率返回 1 张随机图
+///   - POST /api/wallpaper/refresh        立即刷新分类池子并返回 1 张新随机图
+/// </summary>
+[ApiController]
+[Route("api/wallpaper")]
+public class WallpaperController : ControllerBase
+{
+    private readonly WallpaperService _wallpaper;
+    private readonly ILogger<WallpaperController> _logger;
+
+    public WallpaperController(WallpaperService wallpaper, ILogger<WallpaperController> logger)
+    {
+        _wallpaper = wallpaper;
+        _logger = logger;
+    }
+
+    /// <summary>全部分类列表（24h 缓存）。失败返回空集合（前端展示「暂无可用分类」）。</summary>
+    [HttpGet("categories")]
+    public async Task<ApiResponse<List<WallpaperCategoryDto>>> GetCategories(CancellationToken ct)
+    {
+        var cats = await _wallpaper.GetCategoriesAsync(ct);
+        return ApiResponse<List<WallpaperCategoryDto>>.Ok(cats);
+    }
+
+    /// <summary>
+    /// 按分类 + 视口分辨率返回 1 张随机壁纸 URL。
+    /// 查询参数：cid（可空，例 "36"）、w（视口宽 px，默认 1920）、h（视口高 px，默认 1080）。
+    /// </summary>
+    [HttpGet("random")]
+    public async Task<ApiResponse<WallpaperRandomDto>> GetRandom(
+        [FromQuery] string? cid,
+        [FromQuery] int? w,
+        [FromQuery] int? h,
+        CancellationToken ct)
+    {
+        var (width, height) = SanitizeViewport(w, h);
+        var result = await _wallpaper.GetRandomAsync(cid ?? "", width, height, ct);
+        if (result is null)
+            throw new BusinessException("暂无可用壁纸（分类可能无效或 360 接口暂不可达）", 404);
+        return ApiResponse<WallpaperRandomDto>.Ok(result);
+    }
+
+    /// <summary>
+    /// 立即刷新指定分类的池子（清缓存重新拉 200 张），并立即返回 1 张新随机图。
+    /// 即主人要求的「立即切换」按钮后端入口。
+    /// </summary>
+    [HttpPost("refresh")]
+    public async Task<ApiResponse<WallpaperRandomDto>> Refresh(
+        [FromQuery] string? cid,
+        [FromQuery] int? w,
+        [FromQuery] int? h,
+        CancellationToken ct)
+    {
+        var (width, height) = SanitizeViewport(w, h);
+        var result = await _wallpaper.RefreshAsync(cid ?? "", width, height, ct);
+        if (result is null)
+            throw new BusinessException("暂无可用壁纸（分类可能无效或 360 接口暂不可达）", 404);
+        _logger.LogInformation("Wallpaper manual refresh: cid={Cid} {W}x{H}", cid ?? "", width, height);
+        return ApiResponse<WallpaperRandomDto>.Ok(result);
+    }
+
+    /// <summary>把客户端上报的 w/h 限制在合理范围（避免异常大数把 360 路径撑爆）</summary>
+    private static (int w, int h) SanitizeViewport(int? w, int? h)
+    {
+        // 默认 1920x1080 = PC 桌面
+        var width = w is > 0 and < 8000 ? w.Value : 1920;
+        var height = h is > 0 and < 8000 ? h.Value : 1080;
+        return (width, height);
+    }
+}