# MyHomePage · 浏览器首页

> 跨端可用的浏览器首页 / 起始页：PC、平板、手机浏览器 + Android APP 共享同一份数据，实时同步。

![MyHomePage](https://trae-api-cn.mchost.guru/api/ide/v1/text_to_image?prompt=modern%20glassmorphism%20browser%20homepage%20with%20gradient%20background%2C%20dark%20theme%2C%20search%20bar%2C%20category%20sidebar%2C%20link%20cards%20grid%2C%20floating%20UI&image_size=landscape_16_9)

## 功能特性

- 二级分类导航（常用工具 > 搜索引擎 / AI 工具 / 开发工具）
- 链接收藏管理：增删改、图标、简介
- 搜索引擎管理：增删改、默认引擎切换
- 设置面板：主题模式（暗/亮/跟随系统）、主色调、背景图（6 套预设 + 自定义上传）
- PC、平板、手机浏览器自适应
- PC、平板、手机、Android APP 四端数据实时同步
- 文件上传（链接图标 / 自定义背景图），落地路径可配置
- 后端支持 MySQL / SQLite，通过 `appsettings.json` 一键切换

## 技术栈

| 层 | 选型 |
|----|------|
| 前端 | Vue 3 + TypeScript + Vite + Pinia + Vue Router |
| UI | 自研组件（玻璃拟态设计 token），图标 lucide-vue-next |
| APP 壳 | Capacitor 6（共享前端代码） |
| 后端 | .NET 8 + ASP.NET Core Web API + C# |
| ORM | SqlSugar（多数据库自动切换） |
| 数据库 | MySQL 8 / SQLite |
| 部署 | Docker Compose |

## 目录结构

```
MyHomePage/
├── frontend/                # Vue 3 前端
│   ├── src/
│   │   ├── api/             # axios 封装
│   │   ├── components/      # 通用组件 + 业务组件
│   │   ├── views/           # HomeView / SettingsView
│   │   ├── stores/          # Pinia stores
│   │   ├── router/          # 路由
│   │   ├── styles/          # tokens.css + global.css
│   │   ├── types/           # TypeScript 类型
│   │   └── utils/           # icon / toast 工具
│   ├── capacitor.config.ts  # Capacitor 配置
│   ├── ANDROID.md           # 打包 Android 指引
│   ├── package.json
│   └── vite.config.ts
├── backend/                 # .NET 8 Web API
│   ├── Controllers/         # 6 个 REST 控制器
│   ├── Services/            # 业务服务
│   ├── Models/              # Entities + Dtos
│   ├── Repositories/        # BaseRepository
│   ├── Common/              # ApiResponse + 异常中间件
│   ├── Infrastructure/      # SqlSugarContext + 配置
│   ├── Uploads/             # 上传文件目录
│   ├── MyHomePage.Api.csproj
│   ├── Program.cs
│   └── appsettings.json
├── docker/                  # Docker 部署资源
│   ├── backend.Dockerfile
│   ├── nginx.conf
│   └── README.md
├── docker-compose.yml
└── browser-homepage/        # 设计稿（已存在）
```

## 快速开始

### 1. 启动后端

```bash
cd backend
dotnet restore
dotnet run
# 默认监听 http://localhost:5080
# Swagger UI: http://localhost:5080/swagger
```

第一次启动会自动建表（CodeFirst）并写入种子数据（常用工具 + AI 工具 + 开发工具 3 个分类 + 6 个链接 + 3 个搜索引擎）。

### 2. 切换数据库

默认 SQLite（`myhomepage.db`）。如需 MySQL：

编辑 `backend/appsettings.json`：

```json
{
  "Database": {
    "Provider": "MySql",
    "ConnectionString": "Server=localhost;Port=3306;Database=myhomepage;Uid=root;Pwd=yourpw;CharSet=utf8mb4;"
  }
}
```

### 3. 启动前端

```bash
cd frontend
npm install
npm run dev
# 默认监听 http://localhost:5173
```

Vite 已配 proxy：`/api` → `http://localhost:5080`。

### 4. 浏览器访问

打开 http://localhost:5173

## 打包 Android APP

见 [frontend/ANDROID.md](file:///d:/Code/MyHomePage/frontend/ANDROID.md)

## Docker 一键部署

见 [docker/README.md](file:///d:/Code/MyHomePage/docker/README.md)

```bash
docker compose up -d --build
# 访问 http://localhost:8080
```

## API 总览

| 方法 | 路径 | 说明 |
|------|------|------|
| GET / POST / PUT / DELETE | `/api/categories` | 分类 CRUD（支持二级树） |
| GET / POST / PUT / DELETE | `/api/bookmarks` | 链接 CRUD，可按 `?categoryId=` 过滤 |
| GET / POST / PUT / DELETE | `/api/search-engines` | 搜索引擎 CRUD |
| PUT | `/api/search-engines/{id}/default` | 设为默认（自动取消其他） |
| GET / PUT | `/api/settings` | 用户设置读写 |
| POST | `/api/upload` | 单文件上传，返回 `{ url, path, ... }` |
| GET | `/api/sync/changes?since={ISO8601}` | 增量同步，返回 `{ changes, snapshot, serverTime }` |
| GET | `/health` | 健康检查 |
| GET | `/swagger` | OpenAPI 文档 |

所有接口统一响应格式：
```json
{ "code": 0, "message": "ok", "data": { ... }, "timestamp": 1783158000000 }
```

`code !== 0` 表示业务错误，`code === 0` 表示成功。

## 上传路径配置

```json
{
  "Upload": {
    "Path": "Uploads",        // 相对 ContentRoot；填绝对路径也支持
    "BaseUrl": "/uploads",    // 前端拼接前缀
    "MaxSizeBytes": 10485760  // 10MB
  }
}
```

通过环境变量覆盖：`Upload__Path=/data/uploads`、`Upload__BaseUrl=https://cdn.example.com/uploads`。

## 开发约定

- 严格按 [说明文档.md](file:///d:/Code/MyHomePage/说明文档.md) 中的 TODO 推进
- 每次完成一个任务立即更新「说明文档」中的进度记录
- 函数级注释（功能 / 参数 / 返回值），便于 AI 理解
- API 错误码用 4xx 表示业务校验失败，5xx 表示系统错误

## License

MIT