初始提交：浏览器首页 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,55 @@
+using MyHomePage.Api.Models.Entities;
+
+namespace MyHomePage.Api.Models.Dtos;
+
+/// <summary>链接输出 DTO</summary>
+public class BookmarkDto
+{
+    public int Id { get; set; }
+    public int CategoryId { get; set; }
+    public string Title { get; set; } = string.Empty;
+    public string Url { get; set; } = string.Empty;
+    public string? Description { get; set; }
+    public string? Icon { get; set; }
+    public string IconType { get; set; } = "lucide";
+    public string? IconUrl { get; set; }
+    public string? ColorBg { get; set; }
+    public int Sort { get; set; }
+    public DateTime CreatedAt { get; set; }
+    public DateTime UpdatedAt { get; set; }
+
+    /// <summary>
+    /// 集中映射 Bookmark → BookmarkDto。BookmarkService / SyncService 共用，
+    /// 避免手写 new BookmarkDto { ... } 漏字段（P28 Bug 教训）。
+    /// </summary>
+    public static BookmarkDto FromEntity(Bookmark b) => new()
+    {
+        Id = b.Id,
+        CategoryId = b.CategoryId,
+        Title = b.Title,
+        Url = b.Url,
+        Description = b.Description,
+        Icon = b.Icon,
+        IconType = b.IconType,
+        IconUrl = b.IconUrl,
+        ColorBg = b.ColorBg,
+        Sort = b.Sort,
+        CreatedAt = b.CreatedAt,
+        UpdatedAt = b.UpdatedAt
+    };
+}
+
+/// <summary>链接创建/更新入参</summary>
+public class BookmarkUpsertRequest
+{
+    public int? Id { get; set; }
+    public int CategoryId { get; set; }
+    public string Title { get; set; } = string.Empty;
+    public string Url { get; set; } = string.Empty;
+    public string? Description { get; set; }
+    public string? Icon { get; set; }
+    public string? IconType { get; set; }
+    public string? IconUrl { get; set; }
+    public string? ColorBg { get; set; }
+    public int Sort { get; set; }
+}
@@ -0,0 +1,82 @@
+using MyHomePage.Api.Models.Entities;
+
+namespace MyHomePage.Api.Models.Dtos;
+
+/// <summary>分类输出 DTO（包含二级子项）</summary>
+public class CategoryDto
+{
+    public int Id { get; set; }
+    public int ParentId { get; set; }
+    public string Name { get; set; } = string.Empty;
+    public string? Icon { get; set; }
+    public int Sort { get; set; }
+    public DateTime CreatedAt { get; set; }
+    public DateTime UpdatedAt { get; set; }
+    public List<CategoryDto> Children { get; set; } = new();
+
+    /// <summary>
+    /// 把扁平的 Category 实体集合构建为树形 DTO 列表。
+    /// 规则：parentId == 0 → 顶级；其余 → 挂到对应父分类的 Children 下。
+    /// 若父分类在当前集合中不存在（孤儿），降级为顶级。
+    /// 子项按 Sort, Id 升序排列。
+    /// </summary>
+    public static List<CategoryDto> BuildTree(IEnumerable<Category> entities)
+    {
+        var list = entities
+            .Select(c => new CategoryDto
+            {
+                Id = c.Id,
+                ParentId = c.ParentId,
+                Name = c.Name,
+                Icon = c.Icon,
+                Sort = c.Sort,
+                CreatedAt = c.CreatedAt,
+                UpdatedAt = c.UpdatedAt
+            })
+            .ToList();
+        return BuildTreeFromFlat(list);
+    }
+
+    /// <summary>
+    /// 把扁平的 DTO 集合构建为树形 DTO 列表（按 Id 重新组织父子关系）。
+    /// </summary>
+    public static List<CategoryDto> BuildTreeFromFlat(IEnumerable<CategoryDto> flat)
+    {
+        var all = flat.ToList();
+        var byId = all.ToDictionary(d => d.Id);
+        var roots = new List<CategoryDto>();
+
+        // 重置所有 Children（防止调用方传入了预填的 Children 造成重复）
+        foreach (var d in all) d.Children = new List<CategoryDto>();
+
+        foreach (var d in all.OrderBy(x => x.Sort).ThenBy(x => x.Id))
+        {
+            if (d.ParentId == 0 || !byId.TryGetValue(d.ParentId, out var parent))
+            {
+                // 顶级 OR 孤儿（父分类不存在）→ 降级为顶级
+                roots.Add(d);
+            }
+            else
+            {
+                parent.Children.Add(d);
+            }
+        }
+
+        // 给每个父分类的 children 排序
+        foreach (var r in roots)
+        {
+            r.Children = r.Children.OrderBy(x => x.Sort).ThenBy(x => x.Id).ToList();
+        }
+        return roots;
+    }
+}
+
+/// <summary>分类创建/更新入参</summary>
+public class CategoryUpsertRequest
+{
+    public int? Id { get; set; }
+    public int ParentId { get; set; }
+    public string Name { get; set; } = string.Empty;
+    public string? Icon { get; set; }
+    public int Sort { get; set; }
+}
@@ -0,0 +1,49 @@
+using MyHomePage.Api.Models.Entities;
+
+namespace MyHomePage.Api.Models.Dtos;
+
+/// <summary>搜索引擎输出 DTO</summary>
+public class SearchEngineDto
+{
+    public int Id { get; set; }
+    public string Name { get; set; } = string.Empty;
+    public string UrlTemplate { get; set; } = string.Empty;
+    public string IconType { get; set; } = "lucide";
+    public string? Icon { get; set; }
+    public string? IconUrl { get; set; }
+    public string? ColorBg { get; set; }
+    public int Sort { get; set; }
+    public bool IsDefault { get; set; }
+    public DateTime CreatedAt { get; set; }
+    public DateTime UpdatedAt { get; set; }
+
+    /// <summary>从实体映射（中心化转换，防止漏字段，与 BookmarkDto.FromEntity 对齐）</summary>
+    public static SearchEngineDto FromEntity(SearchEngine e) => new()
+    {
+        Id = e.Id,
+        Name = e.Name,
+        UrlTemplate = e.UrlTemplate,
+        IconType = e.IconType,
+        Icon = e.Icon,
+        IconUrl = e.IconUrl,
+        ColorBg = e.ColorBg,
+        Sort = e.Sort,
+        IsDefault = e.IsDefault,
+        CreatedAt = e.CreatedAt,
+        UpdatedAt = e.UpdatedAt
+    };
+}
+
+/// <summary>搜索引擎创建/更新入参</summary>
+public class SearchEngineUpsertRequest
+{
+    public int? Id { get; set; }
+    public string Name { get; set; } = string.Empty;
+    public string UrlTemplate { get; set; } = string.Empty;
+    public string IconType { get; set; } = "lucide";
+    public string? Icon { get; set; }
+    public string? IconUrl { get; set; }
+    public string? ColorBg { get; set; }
+    public int Sort { get; set; }
+    public bool IsDefault { get; set; }
+}
@@ -0,0 +1,59 @@
+using MyHomePage.Api.Models.Entities;
+
+namespace MyHomePage.Api.Models.Dtos;
+
+/// <summary>设置输出 DTO</summary>
+public class SettingDto
+{
+    public string ThemeMode { get; set; } = "dark";
+    public string AccentColor { get; set; } = "#6c5ce7";
+    public string? BackgroundImage { get; set; }
+    public string BackgroundType { get; set; } = "preset";
+    public bool OpenLinksInNewTab { get; set; } = true;
+
+    /// <summary>搜索框行为（P46）：true = 搜索结果在新选项卡打开（默认）；false = 当前选项卡打开</summary>
+    public bool OpenSearchInNewTab { get; set; } = true;
+
+    // ===== P34 360 在线壁纸模式 =====
+    /// <summary>是否启用 360 在线壁纸（按分类随机 + 定时切换）</summary>
+    public bool WallpaperEnabled { get; set; } = false;
+    /// <summary>360 壁纸分类 ID，空字符串 = 全部/推荐</summary>
+    public string WallpaperCategoryId { get; set; } = "";
+    /// <summary>自动切换间隔（分钟），0 = 不自动切换</summary>
+    public int WallpaperInterval { get; set; } = 30;
+
+    public DateTime UpdatedAt { get; set; }
+
+    /// <summary>从实体构造 DTO，统一所有 Controller / Service 的转换逻辑，避免漏字段。</summary>
+    public static SettingDto FromEntity(Setting s) => new()
+    {
+        ThemeMode = s.ThemeMode,
+        AccentColor = s.AccentColor,
+        BackgroundImage = s.BackgroundImage,
+        BackgroundType = s.BackgroundType,
+        OpenLinksInNewTab = s.OpenLinksInNewTab != 0,
+        OpenSearchInNewTab = s.OpenSearchInNewTab != 0,
+        WallpaperEnabled = s.WallpaperEnabled != 0,
+        WallpaperCategoryId = s.WallpaperCategoryId ?? "",
+        WallpaperInterval = s.WallpaperInterval,
+        UpdatedAt = s.UpdatedAt
+    };
+}
+
+/// <summary>设置更新入参（全部可选）</summary>
+public class SettingUpdateRequest
+{
+    public string? ThemeMode { get; set; }
+    public string? AccentColor { get; set; }
+    public string? BackgroundImage { get; set; }
+    public string? BackgroundType { get; set; }
+    public bool? OpenLinksInNewTab { get; set; }
+
+    /// <summary>搜索框行为（P46）：true = 搜索结果在新选项卡打开（默认）；false = 当前选项卡打开</summary>
+    public bool? OpenSearchInNewTab { get; set; }
+
+    // ===== P34 360 在线壁纸 =====
+    public bool? WallpaperEnabled { get; set; }
+    public string? WallpaperCategoryId { get; set; }
+    public int? WallpaperInterval { get; set; }
+}
@@ -0,0 +1,32 @@
+namespace MyHomePage.Api.Models.Dtos;
+
+/// <summary>同步单条记录</summary>
+public class SyncChangeDto
+{
+    public string EntityType { get; set; } = string.Empty;
+    public int EntityId { get; set; }
+    public string Operation { get; set; } = "update";
+    public DateTime Timestamp { get; set; }
+}
+
+/// <summary>同步响应</summary>
+public class SyncChangesResponse
+{
+    /// <summary>本次拉取的变更记录</summary>
+    public List<SyncChangeDto> Changes { get; set; } = new();
+
+    /// <summary>全量最新数据快照（按实体类型分组）</summary>
+    public SyncSnapshot Snapshot { get; set; } = new();
+
+    /// <summary>服务器当前时间（用作下次 since）</summary>
+    public DateTime ServerTime { get; set; } = DateTime.UtcNow;
+}
+
+/// <summary>全量快照</summary>
+public class SyncSnapshot
+{
+    public List<CategoryDto> Categories { get; set; } = new();
+    public List<BookmarkDto> Bookmarks { get; set; } = new();
+    public List<SearchEngineDto> SearchEngines { get; set; } = new();
+    public SettingDto? Settings { get; set; }
+}
@@ -0,0 +1,17 @@
+namespace MyHomePage.Api.Models.Dtos;
+
+/// <summary>文件上传结果</summary>
+public class UploadResultDto
+{
+    /// <summary>相对 BaseUrl 的子路径（如 2026/07/04/abc.png）</summary>
+    public string Path { get; set; } = string.Empty;
+
+    /// <summary>前端可直接访问的完整 URL</summary>
+    public string Url { get; set; } = string.Empty;
+
+    /// <summary>原始文件名</summary>
+    public string FileName { get; set; } = string.Empty;
+
+    /// <summary>文件大小（字节）</summary>
+    public long Size { get; set; }
+}
@@ -0,0 +1,29 @@
+namespace MyHomePage.Api.Models.Dtos;
+
+/// <summary>360 壁纸分类（P34）</summary>
+public class WallpaperCategoryDto
+{
+    /// <summary>分类 ID（字符串，例："36"）</summary>
+    public string Id { get; set; } = string.Empty;
+    /// <summary>分类名（中文，例："4K专区"）</summary>
+    public string Name { get; set; } = string.Empty;
+    /// <summary>排序权重（P34.1 主人反馈：360 接口真实数据有此字段，降序展示）</summary>
+    public int OrderNum { get; set; }
+}
+
+/// <summary>随机壁纸返回结果（P34）</summary>
+public class WallpaperRandomDto
+{
+    /// <summary>最终 URL（命中 360 预设分辨率的 img_* 字段，或兜底 RewriteUrl 自构）</summary>
+    public string Url { get; set; } = string.Empty;
+    /// <summary>360 接口原始 url（bdr/__85 画质低的版本，调试用）</summary>
+    public string OriginalUrl { get; set; } = string.Empty;
+    /// <summary>请求的视口宽度（px）</summary>
+    public int Width { get; set; }
+    /// <summary>请求的视口高度（px）</summary>
+    public int Height { get; set; }
+    /// <summary>命中的 360 预设分辨率（形如 "1600x900"）；未命中为 null（走 RewriteUrl 兜底）</summary>
+    public string? Preset { get; set; }
+    /// <summary>是否走 RewriteUrl 兜底（true = preset 没命中）</summary>
+    public bool UsedFallback { get; set; }
+}