# v2.0 开发文档

> **版本**: 2.0.0
> **状态**: ✅ 已完成
> **最后更新**: 2025-12-15
> **文档类型**: 技术开发文档

---

## 文档概述

本文档详细记录了书签管理系统 v2.0 的完整技术实现，包括：
- 从 v1.0（本地单用户）到 v2.0（云端多用户）的架构升级
- 后端 API（ASP.NET Core + FreeSql）完整实现
- 前端应用（Vue 3 + TypeScript）技术栈
- 浏览器扩展自动同步机制
- 后台管理系统实现细节

---

## 核心任务完成情况

### ✅ 已完成功能

**后端 API（100%）**
- [x] JWT 认证系统（包含 RefreshToken 机制）
- [x] 用户注册/登录/登出
- [x] 设备自动注册与管理（设备指纹识别）
- [x] 书签 CRUD（含搜索、批量操作、可见性控制）
- [x] 标签管理
- [x] 后台管理接口（用户管理、设备管理、统计数据）

**前端应用（100%）**
- [x] 用户认证界面（登录/注册）
- [x] 书签管理界面（列表、编辑、搜索）
- [x] 设备管理界面
- [x] 可见性控制界面
- [x] Pinia 状态管理（auth、bookmark、device、tag）

**浏览器扩展（90%）**
- [x] 书签自动同步（监听浏览器书签创建事件）
- [x] 文件夹路径转标签
- [x] URL 重复检测
- [x] 同步状态提示
- [ ] 删除/修改同步（预留接口）

**后台管理系统（100%）**
- [x] 仪表盘（系统统计数据）
- [x] 用户管理（列表、详情、禁用、重置密码）
- [x] 设备管理（强制下线、禁用设备）
- [x] 书签管理（查看、删除）

---


## 技术架构变化

###

```mermaid
graph LR
    v1[v1.0_本地单用户]
    v2[v2.0_云端多用户]
    
    v1 -->|架构升级| v2
    
    subgraph v1_arch [v1.0架构]
        fe1[Vue前端]
        idb[IndexedDB]
        ext1[扩展监控]
        fe1 --> idb
        ext1 -.-> fe1
    end
    
    subgraph v2_arch [v2.0架构]
        fe2[Vue前端]
        api[.NET_API]
        db[(SQL数据库)]
        admin[Vue后台]
        ext2[扩展增强]
        
        fe2 --> api
        ext2 --> api
        admin --> api
        api --> db
    end
```

### 技术栈选型

基于用户确认的技术选型：

| 组件 | 技术选择 | 说明 |

|------|---------|------|

| 后端框架 | ASP.NET Core 8 (LTS) | 长期支持版本，稳定可靠 |

| 数据库 | SQL Server / PostgreSQL | 通过 FreeSql 支持多数据库 |

| ORM | FreeSql | 高性能 .NET ORM，支持多数据库、CodeFirst、丰富的查询功能 |

| 认证 | JWT Bearer Token | 无状态认证，支持多设备 |

| 后台管理 | Vue 3 + Element Plus | 与前端技术栈统一 |

| API 文档 | Swagger / OpenAPI | 自动生成接口文档 |

### FreeSql 核心优势

- 支持多种数据库（SQL Server、PostgreSQL、MySQL、Oracle 等）
- CodeFirst 自动同步实体结构到数据库
- 强大的表达式解析引擎，支持复杂查询
- 内置分页、软删除、乐观锁等功能
- Repository + UnitOfWork 模式支持
- 性能优秀，支持批量操作

## 文档结构设计

新文档 `v2.0-开发文档.md` 将包含以下章节：

### 1. 项目概述

- v2.0 产品定位和核心变化
- 从 MVP 到生产级的演进路径
- 多用户、多设备、云同步的业务价值

### 2. 系统架构

**完整架构图**：

```
用户层
├── Bookmark SPA (Vue 3)
├── Browser Extension (Manifest V3)
└── Admin Panel (Vue 3)
         ↓
API 网关层
├── ASP.NET Core 8 Web API
├── JWT 认证中间件
├── 设备识别中间件
└── 可见性过滤中间件
         ↓
业务逻辑层
├── 用户服务 (UserService)
├── 设备服务 (DeviceService)
├── 书签服务 (BookmarkService)
└── 标签服务 (TagService)
         ↓
数据访问层
├── FreeSql IFreeSql 实例
├── Repository 模式
└── UnitOfWork 工作单元
         ↓
数据库层 (SQL Server / PostgreSQL)
```

### 3. 数据模型设计

#### 3.1 核心实体

**Users (用户表)**

```csharp
using FreeSql.DataAnnotations;

[Table(Name = "users")]
public class User
{
    [Column(IsPrimary = true)]
    public Guid Id { get; set; }
    
    [Column(IsNullable = false, StringLength = 200)]
    [Index("idx_user_email", IsUnique = true)]
    public string Email { get; set; }
    
    [Column(IsNullable = false, StringLength = 100)]
    public string UserName { get; set; }
    
    [Column(IsNullable = false, StringLength = 500)]
    public string PasswordHash { get; set; }
    
    [Column(StringLength = 500)]
    public string? Avatar { get; set; }
    
    [Column(ServerTime = DateTimeKind.Utc)]
    public DateTime CreatedAt { get; set; }
    
    [Column(IsNullable = true)]
    public DateTime? LastLoginAt { get; set; }
    
    [Column(MapType = typeof(int))]
    public UserStatus Status { get; set; }
    
    // 导航属性
    [Navigate(nameof(Device.UserId))]
    public List<Device> Devices { get; set; }
    
    [Navigate(nameof(Bookmark.UserId))]
    public List<Bookmark> Bookmarks { get; set; }
}

public enum UserStatus
{
    Normal = 0,
    Disabled = 1
}
```

**Devices (设备表)**

```csharp
[Table(Name = "devices")]
public class Device
{
    [Column(IsPrimary = true)]
    public Guid Id { get; set; }
    
    [Column(IsNullable = false)]
    public Guid UserId { get; set; }
    
    [Column(IsNullable = false, StringLength = 200)]
    public string DeviceName { get; set; }
    
    [Column(IsNullable = false, StringLength = 200)]
    public string DeviceType { get; set; }
    
    [Column(IsNullable = false)]
    [Index("idx_device_user_admin")]
    public bool IsAdmin { get; set; }
    
    [Column(ServerTime = DateTimeKind.Utc)]
    public DateTime CreatedAt { get; set; }
    
    [Column(ServerTime = DateTimeKind.Utc, IsOnUpdateValue = true)]
    public DateTime LastActiveAt { get; set; }
    
    [Column(MapType = typeof(int))]
    public DeviceStatus Status { get; set; }
    
    // 导航属性
    [Navigate(nameof(UserId))]
    public User User { get; set; }
}

public enum DeviceStatus
{
    Normal = 0,
    Disabled = 1
}
```

**Bookmarks (书签表)**

```csharp
[Table(Name = "bookmarks")]
[Index("idx_bookmark_user_order", nameof(UserId), nameof(Order))]
public class Bookmark
{
    [Column(IsPrimary = true)]
    public Guid Id { get; set; }
    
    [Column(IsNullable = false)]
    public Guid UserId { get; set; }
    
    [Column(IsNullable = false, StringLength = 500)]
    public string Title { get; set; }
    
    [Column(IsNullable = false, StringLength = 2000)]
    public string Url { get; set; }
    
    [Column(StringLength = 2000)]
    public string? Description { get; set; }
    
    [Column(StringLength = -1)]  // TEXT/NTEXT
    public string? Icon { get; set; }
    
    [Column(MapType = typeof(string), StringLength = -1)]  // JSON 存储
    public string[] Tags { get; set; }
    
    [Column(IsNullable = false)]
    public int VisitCount { get; set; }
    
    public DateTime? LastVisitTime { get; set; }
    
    [Column(IsNullable = false)]
    public long Order { get; set; }
    
    [Column(MapType = typeof(int))]
    public VisibilityType Visibility { get; set; }
    
    [Column(MapType = typeof(string), StringLength = -1)]  // JSON 存储
    public Guid[]? AllowedDevices { get; set; }
    
    [Column(ServerTime = DateTimeKind.Utc)]
    public DateTime CreatedAt { get; set; }
    
    [Column(ServerTime = DateTimeKind.Utc, IsOnUpdateValue = true)]
    public DateTime UpdatedAt { get; set; }
    
    // 导航属性
    [Navigate(nameof(UserId))]
    public User User { get; set; }
}

public enum VisibilityType
{
    Public = 0,
    Private = 1,
    Specified = 2
}
```

#### 3.2 数据库索引策略

- Users: Email 唯一索引
- Devices: UserId + IsAdmin 复合索引（用于快速查找管理员设备）
- Bookmarks: UserId + Order 复合索引（列表查询优化）

### 4. FreeSql 配置与使用

#### 4.1 IFreeSql 实例配置

```csharp
// Program.cs
using FreeSql;

var builder = WebApplication.CreateBuilder(args);

// 配置 FreeSql
var freeSqlBuilder = new FreeSqlBuilder()
    .UseConnectionString(GetDataType(), builder.Configuration.GetConnectionString("DefaultConnection"))
    .UseAutoSyncStructure(builder.Environment.IsDevelopment())  // 开发环境自动同步结构
    .UseMonitorCommand(cmd => Console.WriteLine(cmd.CommandText))  // 监控 SQL
    .Build();

// 注册为单例
builder.Services.AddSingleton<IFreeSql>(freeSqlBuilder);

// 辅助方法：根据配置获取数据库类型
DataType GetDataType()
{
    var provider = builder.Configuration["DatabaseProvider"];
    return provider?.ToLower() switch
    {
        "postgresql" => DataType.PostgreSQL,
        "sqlserver" => DataType.SqlServer,
        _ => DataType.SqlServer
    };
}

// appsettings.json
{
  "ConnectionStrings": {
    "DefaultConnection": "Server=.;Database=BookmarkDb;..."
  },
  "DatabaseProvider": "SqlServer"  // 或 "PostgreSQL"
}
```

#### 4.2 Repository 模式

```csharp
// IRepository.cs
public interface IRepository<TEntity> where TEntity : class
{
    ISelect<TEntity> Select { get; }
    Task<TEntity> GetAsync(object id);
    Task<List<TEntity>> GetListAsync();
    Task<TEntity> InsertAsync(TEntity entity);
    Task<int> UpdateAsync(TEntity entity);
    Task<int> DeleteAsync(object id);
}

// 实现
public class Repository<TEntity> : IRepository<TEntity> where TEntity : class
{
    private readonly IFreeSql _freeSql;
    
    public Repository(IFreeSql freeSql)
    {
        _freeSql = freeSql;
    }
    
    public ISelect<TEntity> Select => _freeSql.Select<TEntity>();
    
    public Task<TEntity> GetAsync(object id) 
        => _freeSql.Select<TEntity>().WhereDynamic(id).FirstAsync();
    
    public Task<List<TEntity>> GetListAsync() 
        => _freeSql.Select<TEntity>().ToListAsync();
    
    public Task<TEntity> InsertAsync(TEntity entity) 
        => _freeSql.Insert(entity).ExecuteInsertedAsync();
    
    public Task<int> UpdateAsync(TEntity entity) 
        => _freeSql.Update<TEntity>().SetSource(entity).ExecuteAffrowsAsync();
    
    public Task<int> DeleteAsync(object id) 
        => _freeSql.Delete<TEntity>().WhereDynamic(id).ExecuteAffrowsAsync();
}
```

#### 4.3 UnitOfWork 工作单元

```csharp
// IUnitOfWork.cs
public interface IUnitOfWork : IDisposable
{
    void BeginTransaction();
    void Commit();
    void Rollback();
    IRepository<TEntity> GetRepository<TEntity>() where TEntity : class;
}

// 实现
public class UnitOfWork : IUnitOfWork
{
    private readonly IFreeSql _freeSql;
    private DbTransaction? _transaction;
    
    public UnitOfWork(IFreeSql freeSql)
    {
        _freeSql = freeSql;
    }
    
    public void BeginTransaction()
    {
        _transaction = _freeSql.Ado.BeginTransaction();
    }
    
    public void Commit()
    {
        _transaction?.Commit();
        _transaction?.Dispose();
        _transaction = null;
    }
    
    public void Rollback()
    {
        _transaction?.Rollback();
        _transaction?.Dispose();
        _transaction = null;
    }
    
    public IRepository<TEntity> GetRepository<TEntity>() where TEntity : class
    {
        return new Repository<TEntity>(_freeSql);
    }
    
    public void Dispose()
    {
        _transaction?.Dispose();
    }
}
```

### 5. 后端 API 设计

#### 5.1 RESTful API 规范

**认证接口 (`/api/auth`)**

- `POST /register` - 用户注册
- `POST /login` - 用户登录（返回 JWT + 自动注册设备）
- `POST /logout` - 退出登录
- `POST /refresh` - 刷新 Token
- `POST /password/reset` - 重置密码（P1）

**用户接口 (`/api/user`)**

- `GET /profile` - 获取用户信息
- `PUT /profile` - 更新用户信息

**设备接口 (`/api/devices`)**

- `GET /` - 获取设备列表
- `PUT /{id}` - 更新设备信息（重命名）
- `DELETE /{id}` - 移除设备
- `PUT /{id}/admin` - 设置/取消管理员设备（P1）

**书签接口 (`/api/bookmarks`)**

- `GET /` - 获取书签列表（根据设备可见性自动过滤）
- `POST /` - 新增书签
- `GET /{id}` - 获取书签详情
- `PUT /{id}` - 更新书签
- `DELETE /{id}` - 删除书签
- `PUT /{id}/visibility` - 设置可见性
- `POST /batch` - 批量操作（P1）
- `POST /{id}/visit` - 记录访问

**标签接口 (`/api/tags`)**

- `GET /` - 获取标签列表及统计
- `PUT /{name}` - 重命名标签（P1）
- `DELETE /{name}` - 删除标签（P1）

#### 5.2 可见性过滤实现（FreeSql）

```csharp
// BookmarkService.cs
public async Task<List<Bookmark>> GetUserBookmarksAsync(Guid userId, Guid deviceId, bool isAdminDevice)
{
    var query = _freeSql.Select<Bookmark>()
        .Where(b => b.UserId == userId)
        .Where(b => 
            b.Visibility == VisibilityType.Public ||
            (b.Visibility == VisibilityType.Private && isAdminDevice) ||
            (b.Visibility == VisibilityType.Specified && 
             _freeSql.Select<Bookmark>()
                .Where(x => x.Id == b.Id)
                .Where($"AllowedDevices LIKE '%{deviceId}%'")
                .Any()
            )
        )
        .OrderByDescending(b => b.Order);
    
    return await query.ToListAsync();
}
```

#### 5.3 示例 API Controller

```csharp
[ApiController]
[Route("api/[controller]")]
[Authorize]
public class BookmarksController : ControllerBase
{
    private readonly IFreeSql _freeSql;
    private readonly ILogger<BookmarksController> _logger;
    
    public BookmarksController(IFreeSql freeSql, ILogger<BookmarksController> logger)
    {
        _freeSql = freeSql;
        _logger = logger;
    }
    
    [HttpGet]
    public async Task<ActionResult<List<BookmarkDto>>> GetBookmarks()
    {
        var userId = GetCurrentUserId();
        var deviceId = GetCurrentDeviceId();
        var isAdmin = await IsAdminDeviceAsync(deviceId);
        
        var bookmarks = await _freeSql.Select<Bookmark>()
            .Where(b => b.UserId == userId)
            .WhereIf(!isAdmin, b => b.Visibility == VisibilityType.Public)
            .OrderByDescending(b => b.Order)
            .ToListAsync();
        
        return Ok(bookmarks);
    }
    
    [HttpPost]
    public async Task<ActionResult<BookmarkDto>> CreateBookmark([FromBody] CreateBookmarkDto dto)
    {
        var userId = GetCurrentUserId();
        
        var bookmark = new Bookmark
        {
            Id = Guid.NewGuid(),
            UserId = userId,
            Title = dto.Title,
            Url = dto.Url,
            Description = dto.Description,
            Tags = dto.Tags ?? Array.Empty<string>(),
            Visibility = dto.Visibility,
            AllowedDevices = dto.AllowedDevices,
            Order = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
            CreatedAt = DateTime.UtcNow
        };
        
        await _freeSql.Insert(bookmark).ExecuteAffrowsAsync();
        
        return CreatedAtAction(nameof(GetBookmark), new { id = bookmark.Id }, bookmark);
    }
    
    // 其他 API 方法...
}
```

### 6. 前端架构更新

#### 6.1 数据层变化

**v1.0**: IndexedDB (Dexie) → **v2.0**: RESTful API + Axios

**新增服务层**：

- `src/services/api/client.js` - Axios 实例配置（拦截器、Token 注入）
- `src/services/api/authApi.js` - 认证接口封装
- `src/services/api/userApi.js` - 用户接口
- `src/services/api/deviceApi.js` - 设备接口
- `src/services/api/bookmarkApi.js` - 书签接口
- `src/services/api/tagApi.js` - 标签接口
- `src/services/auth/tokenService.js` - JWT Token 管理（localStorage）
- `src/services/auth/deviceService.js` - 设备指纹识别

#### 6.2 Pinia Store 更新

**新增**：

- `stores/auth.js` - 用户认证状态（登录、登出、Token 管理）
- `stores/device.js` - 设备信息（当前设备、是否管理员）

**更新**：

- `stores/links.js` - 从 Dexie 调用改为 API 调用
- `stores/settings.js` - 部分设置迁移到服务器端

#### 6.3 新增功能组件

**用户认证**：

- `components/auth/LoginDialog.vue` - 登录对话框
- `components/auth/RegisterDialog.vue` - 注册对话框
- `components/auth/PasswordResetDialog.vue` - 密码重置（P1）

**设备管理**：

- `components/devices/DeviceList.vue` - 设备列表
- `components/devices/DeviceCard.vue` - 设备卡片
- `components/devices/DeviceManageDialog.vue` - 设备管理对话框

**可见性控制**：

- `components/links/VisibilitySelector.vue` - 可见性选择器
- `components/links/VisibilityBadge.vue` - 可见性徽章

### 7. 浏览器扩展增强

#### 7.1 新增核心功能

**自动同步** (`background/sync.js`):

- 监听 `chrome.bookmarks.onCreated` 事件
- 提取书签信息（标题、URL、图标、文件夹路径）
- 文件夹路径转标签（如：「工作/项目A」→ ["工作", "项目A"]）
- 调用云端 API 保存书签
- 显示同步成功/失败通知

**新标签页替换**:

```json
// manifest.json
{
  "chrome_url_overrides": {
    "newtab": "app/index.html"
  }
}
```

**全局快捷键搜索** (`content/search-overlay.js`):

- Content Script 注入所有页面
- 监听快捷键（Alt+K 或自定义）
- 浮层搜索框（遮罩层 + 搜索输入 + 结果列表）
- 调用 API 实时搜索
- 键盘导航（上下键、回车打开）

**一键收藏** (`popup/quick-save.js`):

- Popup 中的快速收藏表单
- 自动填充当前页标题和 URL
- 可编辑标签、可见性
- 可选择是否同时保存到浏览器书签
- 收藏成功提示

#### 7.2 认证集成

- 使用 `chrome.storage.local` 存储 JWT Token 和设备 ID
- API 请求时自动携带 Token
- Token 过期时自动刷新或提示登录
- 未登录时提示用户登录

### 8. 后台管理系统

#### 8.1 技术栈与项目结构

**技术栈**: Vue 3 + Vite + Vue Router + Pinia + Element Plus + Axios

```
admin-panel/
├── src/
│   ├── views/
│   │   ├── Dashboard.vue          # 仪表盘
│   │   ├── users/
│   │   │   ├── UserList.vue       # 用户列表
│   │   │   └── UserDetail.vue     # 用户详情
│   │   ├── devices/
│   │   │   └── DeviceList.vue     # 设备管理
│   │   └── bookmarks/
│   │       └── BookmarkList.vue   # 书签管理
│   ├── components/
│   ├── stores/
│   │   └── admin.js               # 管理员状态
│   ├── services/
│   │   └── adminApi.js            # 后台 API
│   └── router/
│       └── index.js
├── package.json
└── vite.config.js
```

#### 8.2 核心功能页面

**仪表盘**:

- 关键指标卡片（用户总数、活跃用户、书签总数、设备总数）
- 趋势图表（P2 优先级，使用 ECharts）

**用户管理**:

- 用户列表（分页、搜索、筛选）
- 禁用/启用用户操作
- 查看用户详情（基本信息、设备列表、书签统计）
- 重置密码（P1）

**设备管理**:

- 查看用户的所有设备
- 强制设备下线（P1）
- 禁用设备（P1）

**书签管理**:

- 查看用户的书签列表（分页、搜索）
- 按可见性筛选
- 删除违规书签（P1）

### 9. 数据库迁移与种子数据

#### 9.1 CodeFirst 自动同步

```csharp
// Program.cs
var freeSql = new FreeSqlBuilder()
    .UseConnectionString(dataType, connectionString)
    .UseAutoSyncStructure(true)  // 自动同步实体结构到数据库
    .Build();

// 首次运行时自动创建表和索引
```

#### 9.2 种子数据

```csharp
// 创建超级管理员账号
public static async Task SeedDataAsync(IFreeSql freeSql)
{
    var adminExists = await freeSql.Select<User>()
        .Where(u => u.Email == "admin@bookmarks.local")
        .AnyAsync();
    
    if (!adminExists)
    {
        var admin = new User
        {
            Id = Guid.NewGuid(),
            Email = "admin@bookmarks.local",
            UserName = "Administrator",
            PasswordHash = BCrypt.Net.BCrypt.HashPassword("Admin@123"),
            Status = UserStatus.Normal,
            CreatedAt = DateTime.UtcNow
        };
        
        await freeSql.Insert(admin).ExecuteAffrowsAsync();
    }
}
```

### 10. 开发指南

#### 10.1 环境搭建

**后端环境**:

- .NET 8 SDK
- SQL Server 2019+ 或 PostgreSQL 14+
- Visual Studio 2022 / Rider / VS Code + C# 扩展
- Postman / Swagger UI

**前端环境**:

- Node.js 20+
- npm 8+
- Chrome 90+

#### 10.2 本地开发流程

```bash
# 1. 克隆项目
git clone <repository>

# 2. 后端启动
cd backend-api
dotnet restore
dotnet run
# 首次运行会自动创建数据库表

# 3. 前端启动
cd bookmark-spa
npm install
npm run dev

# 4. 后台管理启动
cd admin-panel
npm install
npm run dev

# 5. 浏览器扩展
cd bookmark-spa
npm run build
cp -r dist/* ../browser-extension/app/
# 在 Chrome 中加载扩展
```

#### 10.3 FreeSql 常用操作示例

```csharp
// 查询
var users = await _freeSql.Select<User>()
    .Where(u => u.Status == UserStatus.Normal)
    .Page(1, 20)
    .ToListAsync();

// 插入
var user = new User { /* ... */ };
await _freeSql.Insert(user).ExecuteAffrowsAsync();

// 更新
await _freeSql.Update<User>()
    .Set(u => u.LastLoginAt, DateTime.UtcNow)
    .Where(u => u.Id == userId)
    .ExecuteAffrowsAsync();

// 删除
await _freeSql.Delete<User>()
    .Where(u => u.Id == userId)
    .ExecuteAffrowsAsync();

// 事务
using var uow = _freeSql.CreateUnitOfWork();
try
{
    var repo = uow.GetRepository<Bookmark>();
    await repo.InsertAsync(bookmark);
    uow.Commit();
}
catch
{
    uow.Rollback();
    throw;
}
```

### 11. 部署指南

#### 11.1 后端部署

**Docker 容器化**:

```dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY publish/ .
EXPOSE 80
ENTRYPOINT ["dotnet", "BookmarkApi.dll"]
```

**环境变量**:

- `ConnectionStrings__DefaultConnection`
- `DatabaseProvider` (SqlServer / PostgreSQL)
- `JwtSettings__SecretKey`
- `JwtSettings__Issuer`
- `JwtSettings__Audience`
- `JwtSettings__ExpiryMinutes`

#### 11.2 前端部署

- Bookmark SPA: Nginx / Vercel / Netlify
- Admin Panel: Nginx（需配置访问控制）
- Browser Extension: Chrome Web Store

#### 11.3 数据库部署

- SQL Server: Azure SQL / 自托管
- PostgreSQL: Azure PostgreSQL / AWS RDS / 自托管
- 定期备份策略

### 12. 安全实践

#### 12.1 认证与授权

- 密码使用 BCrypt 或 Argon2 哈希
- JWT Token 有效期设置（1 小时）
- Refresh Token 机制（7 天有效期）
- 设备绑定（Token 包含设备 ID）

#### 12.2 API 安全

- HTTPS 强制传输
- CORS 跨域配置
- 速率限制（ASP.NET Core Rate Limiting）
- FreeSql 自动参数化防止 SQL 注入
- 输入验证和输出编码防止 XSS

### 13. 测试策略

#### 13.1 后端测试

- 单元测试: xUnit + Moq
- FreeSql 内存数据库测试
- API 集成测试: WebApplicationFactory
```csharp
[Fact]
public async Task GetBookmarks_ReturnsUserBookmarks()
{
    // Arrange
    var freeSql = new FreeSqlBuilder()
        .UseConnectionString(DataType.Sqlite, ":memory:")
        .Build();
    
    // Act & Assert
}
```


#### 13.2 前端测试

- 单元测试: Vitest
- E2E 测试: Playwright（包含登录流程）

## v2.0 实际实现情况

### ✅ P0 核心功能（已全部完成）

**后端 API**
- ✅ ASP.NET Core 8 项目搭建
- ✅ FreeSql 配置与实体定义（User、Device、Bookmark、RefreshToken）
- ✅ JWT 认证中间件（包含 RefreshToken 机制）
- ✅ 用户注册/登录 API（含设备自动注册）
- ✅ 书签 CRUD API（含搜索、批量删除、可见性控制）
- ✅ 设备管理 API（重命名、删除、设置管理员）
- ✅ 标签管理 API
- ✅ 后台管理 API（用户管理、设备管理、统计数据）

**前端应用**
- ✅ Vue 3 + TypeScript + Pinia
- ✅ 登录/注册界面
- ✅ JWT Token 管理（自动刷新）
- ✅ 书签列表迁移到 API 调用
- ✅ 设备管理界面
- ✅ 可见性控制界面
- ✅ 全局搜索组件

**浏览器扩展**
- ✅ 用户认证集成
- ✅ Token 存储与管理
- ✅ 书签自动同步（监听 chrome.bookmarks.onCreated）
- ✅ 文件夹路径转标签
- ✅ URL 重复检测
- ✅ 同步状态通知

**后台管理系统**
- ✅ Vue 3 + Element Plus
- ✅ 仪表盘统计（用户数、活跃度、书签数、设备数）
- ✅ 用户管理（列表、详情、禁用/启用、重置密码）
- ✅ 设备管理（查看、强制下线、禁用）
- ✅ 书签管理（查看用户书签、删除）
- ✅ 权限控制（Admin/SuperAdmin）

### 📋 P2-P3 增强功能（v3.0 规划）

**扩展增强**
- 📋 新标签页替换为书签应用
- 📋 全局快捷键搜索（任意页面触发）
- 📋 右键菜单添加书签
- 📋 Popup 快速收藏

**高级功能**
- 📋 统计报表和趋势图
- 📋 标签管理增强（合并、排序）
- 📋 邮箱验证
- 📋 数据导出功能

---

## 已实现的 API 接口清单

### 认证接口 (/api/auth)

| 方法 | 路径 | 描述 | 状态 |
|------|------|------|------|
| POST | /register | 用户注册 | ✅ |
| POST | /login | 用户登录（含设备注册） | ✅ |
| POST | /logout | 退出登录 | ✅ |
| POST | /refresh | 刷新 Access Token | ✅ |

### 用户接口 (/api/user)

| 方法 | 路径 | 描述 | 状态 |
|------|------|------|------|
| GET | /profile | 获取用户信息 | ✅ |
| PUT | /profile | 更新用户信息 | ✅ |
| PUT | /password | 修改密码 | ✅ |

### 设备接口 (/api/devices)

| 方法 | 路径 | 描述 | 状态 |
|------|------|------|------|
| GET | / | 获取设备列表 | ✅ |
| GET | /{id} | 获取设备详情 | ✅ |
| PUT | /{id} | 更新设备名称 | ✅ |
| DELETE | /{id} | 删除设备 | ✅ |
| PUT | /{id}/admin | 设置/取消管理员设备 | ✅ |

### 书签接口 (/api/bookmarks)

| 方法 | 路径 | 描述 | 状态 |
|------|------|------|------|
| GET | / | 获取书签列表（自动过滤可见性） | ✅ |
| GET | /search | 搜索书签 | ✅ |
| GET | /{id} | 获取书签详情 | ✅ |
| POST | / | 新增书签 | ✅ |
| PUT | /{id} | 更新书签 | ✅ |
| DELETE | /{id} | 删除书签 | ✅ |
| POST | /batch/delete | 批量删除 | ✅ |
| PUT | /{id}/visibility | 设置可见性 | ✅ |
| POST | /{id}/visit | 记录访问 | ✅ |
| PUT | /{id}/order | 更新排序 | ✅ |
| GET | /check-url | 检查 URL 是否存在 | ✅ |
| POST | /import | 导入书签 | ✅ |
| GET | /export | 导出书签 | ✅ |

### 标签接口 (/api/tags)

| 方法 | 路径 | 描述 | 状态 |
|------|------|------|------|
| GET | / | 获取标签列表及统计 | ✅ |
| PUT | /{name} | 重命名标签 | ✅ |
| DELETE | /{name} | 删除标签 | ✅ |

### 后台管理接口 (/api/admin)

| 方法 | 路径 | 描述 | 状态 |
|------|------|------|------|
| GET | /statistics | 获取系统统计数据 | ✅ |
| GET | /users | 获取用户列表（分页、搜索、筛选） | ✅ |
| GET | /users/{id} | 获取用户详情 | ✅ |
| PUT | /users/{id}/status | 禁用/启用用户 | ✅ |
| POST | /users/{id}/reset-password | 重置用户密码 | ✅ |
| GET | /users/{id}/bookmarks | 获取用户书签列表 | ✅ |
| DELETE | /users/{userId}/bookmarks/{bookmarkId} | 删除用户书签 | ✅ |
| POST | /devices/{id}/force-logout | 强制设备下线 | ✅ |
| PUT | /devices/{id}/status | 禁用/启用设备 | ✅ |

---

## 部署说明

### 环境要求

**后端环境**
- .NET 8 SDK
- SQL Server 2019+ 或 PostgreSQL 14+
- 依赖包：
  - FreeSql (ORM)
  - BCrypt.Net-Next (密码加密)
  - System.IdentityModel.Tokens.Jwt (JWT)
  - Swashbuckle.AspNetCore (API 文档)

**前端环境**
- Node.js 20+
- Vue 3 + TypeScript
- Pinia
- Element Plus

**浏览器扩展**
- Chrome 90+ (Manifest V3)

### 配置说明

**appsettings.json**
```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Server=.;Database=BookmarkDb;..."
  },
  "DatabaseProvider": "SqlServer",
  "JwtSettings": {
    "SecretKey": "your-256-bit-secret",
    "Issuer": "BookmarkApi",
    "Audience": "BookmarkClient",
    "ExpiryMinutes": 60,
    "RefreshTokenDays": 7
  }
}
```

---

## 技术亮点

1. **JWT + RefreshToken 双令牌机制**
   - Access Token 有效期 1 小时
   - Refresh Token 有效期 7 天
   - 自动刷新，无感登录体验

2. **设备指纹识别**
   - Canvas 指纹、屏幕分辨率、时区等多因子识别
   - 自动注册设备，支持设备管理
   - 管理员设备机制，灵活权限控制

3. **书签可见性控制**
   - Public：所有设备可见
   - Private：仅管理员设备可见
   - Specified：仅指定设备可见
   - API 层自动过滤，确保数据安全

4. **自动同步机制**
   - 监听浏览器书签事件
   - 文件夹路径自动转标签
   - URL 重复检测
   - 同步状态实时反馈

5. **后台管理系统**
   - 完整的用户管理功能
   - 系统统计数据实时更新
   - 设备管理（强制下线、禁用）
   - 基于角色的权限控制

6. **TypeScript 支持**
   - 前端全面使用 TypeScript
   - 类型安全，减少运行时错误
   - 更好的开发体验和代码维护性

---

## 后续优化建议

1. **性能优化**
   - 实现 Redis 缓存，提高 API 响应速度
   - 添加 CDN 支持前端资源
   - 数据库查询优化和索引优化

2. **功能增强**
   - 实现新标签页替换
   - 添加全局快捷键搜索
   - 支持邮箱验证
   - 实现数据备份和恢复

3. **监控与日志**
   - 添加结构化日志
   - 实现监控告警
   - 错误追踪和性能分析

4. **安全加固**
   - 实现 2FA 双因素认证
   - 添加操作日志审计
   - API 速率限制增强
   - XSS 和 CSRF 防护加强

---

> **v2.0 开发完成时间**: 2025-12-15
>
> **代码位置**: `/src/` 目录
> - 后端: `/src/backend/`
> - 前端: `/src/frontend/`
> - 扩展: `/src/extension/`
> - 后台管理: `/src/admin/`