初始提交：浏览器首页 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,48 @@
+using Microsoft.AspNetCore.Mvc;
+using MyHomePage.Api.Common;
+using MyHomePage.Api.Models.Dtos;
+using MyHomePage.Api.Services;
+
+namespace MyHomePage.Api.Controllers;
+
+/// <summary>链接收藏。</summary>
+[ApiController]
+[Route("api/bookmarks")]
+public class BookmarksController : ControllerBase
+{
+    private readonly IBookmarkService _service;
+
+    public BookmarksController(IBookmarkService service) => _service = service;
+
+    /// <summary>获取链接列表，可按分类过滤</summary>
+    [HttpGet]
+    public async Task<ApiResponse<List<BookmarkDto>>> List([FromQuery] int? categoryId = null) =>
+        await ApiResponse<List<BookmarkDto>>.OkListAsync(_service.ListAsync(categoryId));
+
+    /// <summary>根据 ID 获取链接</summary>
+    [HttpGet("{id:int}")]
+    public async Task<ApiResponse<BookmarkDto>> GetById(int id)
+    {
+        var dto = await _service.GetByIdAsync(id)
+            ?? throw new BusinessException("链接不存在", 404);
+        return ApiResponse<BookmarkDto>.Ok(dto);
+    }
+
+    /// <summary>创建链接</summary>
+    [HttpPost]
+    public async Task<ApiResponse<BookmarkDto>> Create([FromBody] BookmarkUpsertRequest request) =>
+        ApiResponse<BookmarkDto>.Ok(await _service.CreateAsync(request));
+
+    /// <summary>更新链接</summary>
+    [HttpPut("{id:int}")]
+    public async Task<ApiResponse<BookmarkDto>> Update(int id, [FromBody] BookmarkUpsertRequest request) =>
+        ApiResponse<BookmarkDto>.Ok(await _service.UpdateAsync(id, request));
+
+    /// <summary>删除链接（软删）</summary>
+    [HttpDelete("{id:int}")]
+    public async Task<ApiResponse> Delete(int id)
+    {
+        await _service.DeleteAsync(id);
+        return ApiResponse.Ok();
+    }
+}
@@ -0,0 +1,48 @@
+using Microsoft.AspNetCore.Mvc;
+using MyHomePage.Api.Common;
+using MyHomePage.Api.Models.Dtos;
+using MyHomePage.Api.Services;
+
+namespace MyHomePage.Api.Controllers;
+
+/// <summary>分类管理：支持二级树形结构。</summary>
+[ApiController]
+[Route("api/categories")]
+public class CategoriesController : ControllerBase
+{
+    private readonly ICategoryService _service;
+
+    public CategoriesController(ICategoryService service) => _service = service;
+
+    /// <summary>获取全量分类（树形）</summary>
+    [HttpGet]
+    public async Task<ApiResponse<List<CategoryDto>>> GetTree() =>
+        await ApiResponse<List<CategoryDto>>.OkListAsync(_service.GetTreeAsync());
+
+    /// <summary>根据 ID 获取分类</summary>
+    [HttpGet("{id:int}")]
+    public async Task<ApiResponse<CategoryDto>> GetById(int id)
+    {
+        var dto = await _service.GetByIdAsync(id)
+            ?? throw new BusinessException("分类不存在", 404);
+        return ApiResponse<CategoryDto>.Ok(dto);
+    }
+
+    /// <summary>创建分类</summary>
+    [HttpPost]
+    public async Task<ApiResponse<CategoryDto>> Create([FromBody] CategoryUpsertRequest request) =>
+        ApiResponse<CategoryDto>.Ok(await _service.CreateAsync(request));
+
+    /// <summary>更新分类</summary>
+    [HttpPut("{id:int}")]
+    public async Task<ApiResponse<CategoryDto>> Update(int id, [FromBody] CategoryUpsertRequest request) =>
+        ApiResponse<CategoryDto>.Ok(await _service.UpdateAsync(id, request));
+
+    /// <summary>删除分类</summary>
+    [HttpDelete("{id:int}")]
+    public async Task<ApiResponse> Delete(int id)
+    {
+        await _service.DeleteAsync(id);
+        return ApiResponse.Ok();
+    }
+}
@@ -0,0 +1,48 @@
+using Microsoft.AspNetCore.Mvc;
+using MyHomePage.Api.Common;
+using MyHomePage.Api.Models.Dtos;
+using MyHomePage.Api.Services;
+
+namespace MyHomePage.Api.Controllers;
+
+/// <summary>搜索引擎管理。</summary>
+[ApiController]
+[Route("api/search-engines")]
+public class SearchEnginesController : ControllerBase
+{
+    private readonly ISearchEngineService _service;
+
+    public SearchEnginesController(ISearchEngineService service) => _service = service;
+
+    [HttpGet]
+    public async Task<ApiResponse<List<SearchEngineDto>>> List() =>
+        await ApiResponse<List<SearchEngineDto>>.OkListAsync(_service.ListAsync());
+
+    [HttpGet("{id:int}")]
+    public async Task<ApiResponse<SearchEngineDto>> GetById(int id)
+    {
+        var dto = await _service.GetByIdAsync(id)
+            ?? throw new BusinessException("搜索引擎不存在", 404);
+        return ApiResponse<SearchEngineDto>.Ok(dto);
+    }
+
+    [HttpPost]
+    public async Task<ApiResponse<SearchEngineDto>> Create([FromBody] SearchEngineUpsertRequest request) =>
+        ApiResponse<SearchEngineDto>.Ok(await _service.CreateAsync(request));
+
+    [HttpPut("{id:int}")]
+    public async Task<ApiResponse<SearchEngineDto>> Update(int id, [FromBody] SearchEngineUpsertRequest request) =>
+        ApiResponse<SearchEngineDto>.Ok(await _service.UpdateAsync(id, request));
+
+    [HttpDelete("{id:int}")]
+    public async Task<ApiResponse> Delete(int id)
+    {
+        await _service.DeleteAsync(id);
+        return ApiResponse.Ok();
+    }
+
+    /// <summary>将指定 ID 的引擎设为默认（唯一）</summary>
+    [HttpPut("{id:int}/default")]
+    public async Task<ApiResponse<SearchEngineDto>> SetDefault(int id) =>
+        ApiResponse<SearchEngineDto>.Ok(await _service.SetDefaultAsync(id));
+}
@@ -0,0 +1,24 @@
+using Microsoft.AspNetCore.Mvc;
+using MyHomePage.Api.Common;
+using MyHomePage.Api.Models.Dtos;
+using MyHomePage.Api.Services;
+
+namespace MyHomePage.Api.Controllers;
+
+/// <summary>用户设置：单行配置。</summary>
+[ApiController]
+[Route("api/settings")]
+public class SettingsController : ControllerBase
+{
+    private readonly ISettingService _service;
+
+    public SettingsController(ISettingService service) => _service = service;
+
+    [HttpGet]
+    public async Task<ApiResponse<SettingDto>> Get() =>
+        ApiResponse<SettingDto>.Ok(await _service.GetAsync());
+
+    [HttpPut]
+    public async Task<ApiResponse<SettingDto>> Update([FromBody] SettingUpdateRequest request) =>
+        ApiResponse<SettingDto>.Ok(await _service.UpdateAsync(request));
+}
@@ -0,0 +1,45 @@
+using Microsoft.AspNetCore.Mvc;
+using MyHomePage.Api.Common;
+using MyHomePage.Api.Models.Dtos;
+using MyHomePage.Api.Services;
+
+namespace MyHomePage.Api.Controllers;
+
+/// <summary>多端同步：拉取增量变更 + 全量快照。</summary>
+[ApiController]
+[Route("api/sync")]
+public class SyncController : ControllerBase
+{
+    private readonly ISyncService _service;
+    private readonly ILogger<SyncController> _logger;
+
+    public SyncController(ISyncService service, ILogger<SyncController> logger)
+    {
+        _service = service;
+        _logger = logger;
+    }
+
+    /// <summary>
+    /// 拉取自 <paramref name="since"/> 之后的变更。
+    /// <paramref name="since"/> 为空或解析失败时返回全量（P34.2 防御：避免前端传 ?since=undefined 触发 400）。
+    /// </summary>
+    [HttpGet("changes")]
+    public async Task<ApiResponse<SyncChangesResponse>> Changes([FromQuery] string? since)
+    {
+        DateTime? sinceDt = null;
+        if (!string.IsNullOrWhiteSpace(since))
+        {
+            // 严格解析（RoundtripKind 接受 ISO8601 字符串）；失败则降级为全量
+            if (DateTime.TryParse(since, System.Globalization.CultureInfo.InvariantCulture,
+                System.Globalization.DateTimeStyles.RoundtripKind, out var parsed))
+            {
+                sinceDt = parsed;
+            }
+            else
+            {
+                _logger.LogWarning("Sync changes received unparseable since={Since}, fallback to full snapshot", since);
+            }
+        }
+        return ApiResponse<SyncChangesResponse>.Ok(await _service.GetChangesAsync(sinceDt));
+    }
+}
@@ -0,0 +1,30 @@
+using Microsoft.AspNetCore.Mvc;
+using MyHomePage.Api.Common;
+using MyHomePage.Api.Models.Dtos;
+using MyHomePage.Api.Services;
+
+namespace MyHomePage.Api.Controllers;
+
+/// <summary>文件上传（图片为主）。</summary>
+[ApiController]
+[Route("api/upload")]
+public class UploadController : ControllerBase
+{
+    private readonly IUploadService _service;
+
+    public UploadController(IUploadService service) => _service = service;
+
+    /// <summary>单文件上传</summary>
+    /// <remarks>
+    /// Swashbuckle 6.x 不支持 [FromForm] IFormFile 自动生成 schema（会抛 SwaggerGeneratorException），
+    /// 这里用 [ApiExplorerSettings(IgnoreApi = true)] 让 swagger UI 跳过此端点的文档生成，
+    /// 实际 API 功能完全不受影响（前端 BookmarkForm 仍可正常调用）。
+    /// </remarks>
+    [HttpPost]
+    [ApiExplorerSettings(IgnoreApi = true)]
+    public async Task<ApiResponse<UploadResultDto>> Upload([FromForm] IFormFile file)
+    {
+        var result = await _service.SaveAsync(file);
+        return ApiResponse<UploadResultDto>.Ok(result);
+    }
+}
@@ -0,0 +1,43 @@
+using System.ComponentModel.DataAnnotations;
+using Microsoft.AspNetCore.Mvc;
+using MyHomePage.Api.Common;
+using MyHomePage.Api.Services;
+
+namespace MyHomePage.Api.Controllers;
+
+/// <summary>工具类 API：favicon 抓取等小工具（手动测试用 / 调试入口）。</summary>
+[ApiController]
+[Route("api/utility")]
+public class UtilityController : ControllerBase
+{
+    private readonly FaviconService _favicon;
+
+    public UtilityController(FaviconService favicon) => _favicon = favicon;
+
+    /// <summary>
+    /// P31：手动触发 favicon 抓取（不影响正常创建流程）。
+    /// 任何失败（网络/404/SSRF）均返回 iconUrl=null，由调用方静默用默认。
+    /// </summary>
+    [HttpPost("favicon")]
+    public async Task<ApiResponse<FaviconResultDto>> FetchFavicon([FromBody] FaviconRequest request)
+    {
+        if (string.IsNullOrWhiteSpace(request.Url))
+            throw new BusinessException("URL 不能为空", 400);
+
+        var iconUrl = await _favicon.FetchAndSaveAsync(request.Url, HttpContext.RequestAborted);
+        return ApiResponse<FaviconResultDto>.Ok(new FaviconResultDto { Url = request.Url, IconUrl = iconUrl });
+    }
+}
+
+/// <summary>favicon 抓取请求 DTO</summary>
+public class FaviconRequest
+{
+    [Required] public string Url { get; set; } = string.Empty;
+}
+
+/// <summary>favicon 抓取结果 DTO</summary>
+public class FaviconResultDto
+{
+    public string Url { get; set; } = string.Empty;
+    public string? IconUrl { get; set; }
+}
@@ -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);
+    }
+}