doc:整理文档

docs/manual/代码规范文档.md

@@ -0,0 +1,675 @@
+# Hua.Todo 代码规范文档 v1.1.0
+
+## 1. 概述
+本文档定义 Hua.Todo 项目的代码规范，包括 C#、JavaScript/TypeScript、Vue.js 和其他相关技术的编码标准。遵循这些规范有助于提高代码质量、可读性和可维护性。
+
+## 2. 通用规范
+
+### 2.1 命名约定
+- **使用有意义的名称**: 变量、函数、类名应清晰表达其用途
+- **避免缩写**: 除非是广泛认知的缩写（如 ID、URL、API）
+- **一致性**: 在整个项目中保持命名风格一致
+
+### 2.2 注释规范
+- **公共 API 必须添加 XML 文档注释**
+- **复杂逻辑添加行内注释**
+- **避免注释显而易见的代码**
+- **保持注释与代码同步更新**
+
+### 2.3 代码格式化
+- **使用统一的代码格式化工具**
+- **保持一致的缩进和空格**
+- **每行代码不超过 120 字符**
+- **文件末尾保留一个空行**
+
+## 3. C# 代码规范
+
+### 3.1 命名规范
+
+#### 类和接口
+```csharp
+// 类名使用 PascalCase
+public class TaskService
+{
+}
+
+// 接口名使用 PascalCase，以 I 开头
+public interface ITaskService
+{
+}
+```
+
+#### 方法和属性
+```csharp
+// 方法名使用 PascalCase
+public Task<List<Task>> GetTasksAsync()
+{
+}
+
+// 属性名使用 PascalCase
+public string Title { get; set; }
+```
+
+#### 变量和参数
+```csharp
+// 私有字段使用 _camelCase
+private readonly ITaskRepository _taskRepository;
+
+// 局部变量使用 camelCase
+var taskList = await GetTasksAsync();
+
+// 方法参数使用 camelCase
+public void CreateTask(string title, TaskPriority priority)
+{
+}
+```
+
+#### 常量
+```csharp
+// 常量使用 PascalCase
+public const int MaxTaskTitleLength = 200;
+```
+
+### 3.2 代码组织
+
+#### 文件结构
+```csharp
+// 1. using 语句（按字母顺序）
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+
+// 2. 命名空间
+namespace Hua.Todo.Api.Services;
+
+// 3. XML 文档注释
+/// <summary>
+/// 任务服务实现
+/// </summary>
+public class TaskService : ITaskService
+{
+    // 4. 私有字段
+    private readonly ITaskRepository _taskRepository;
+
+    // 5. 构造函数
+    public TaskService(ITaskRepository taskRepository)
+    {
+        _taskRepository = taskRepository;
+    }
+
+    // 6. 公共方法
+    public async Task<List<Task>> GetTasksAsync()
+    {
+        // 实现
+    }
+
+    // 7. 私有方法
+    private bool ValidateTask(Task task)
+    {
+        // 实现
+    }
+}
+```
+
+#### 命名空间组织
+- 每个文件只包含一个命名空间
+- 命名空间结构应与目录结构一致
+- 使用 `.` 分隔层级
+
+### 3.3 编码规范
+
+#### 异步编程
+```csharp
+// 异步方法应以 Async 结尾
+public async Task<Task> GetTaskByIdAsync(int id)
+{
+    return await _taskRepository.GetByIdAsync(id);
+}
+
+// 使用 await 而非 .Result 或 .Wait
+var task = await GetTaskByIdAsync(id);
+
+// 使用 ConfigureAwait(false) 在库代码中
+public async Task<List<Task>> GetTasksAsync()
+{
+    return await _taskRepository.GetAllAsync().ConfigureAwait(false);
+}
+```
+
+#### 依赖注入
+```csharp
+// 优先使用构造函数注入
+public class TaskService : ITaskService
+{
+    private readonly ITaskRepository _taskRepository;
+    private readonly ILogger<TaskService> _logger;
+
+    public TaskService(ITaskRepository taskRepository, ILogger<TaskService> logger)
+    {
+        _taskRepository = taskRepository;
+        _logger = logger;
+    }
+}
+```
+
+#### 异常处理
+```csharp
+// 使用具体的异常类型
+public async Task<Task> GetTaskByIdAsync(int id)
+{
+    var task = await _taskRepository.GetByIdAsync(id);
+    
+    if (task == null)
+    {
+        throw new NotFoundException($"Task with id {id} not found");
+    }
+    
+    return task;
+}
+
+// 使用 using 语句管理资源
+using var context = new TodoDbContext();
+```
+
+#### LINQ 使用
+```csharp
+// 优先使用方法语法
+var completedTasks = tasks.Where(t => t.IsCompleted).ToList();
+
+// 复杂查询使用查询语法
+var query = from task in tasks
+            where task.IsCompleted
+            orderby task.CreatedAt descending
+            select task;
+```
+
+### 3.4 文档注释
+```csharp
+/// <summary>
+/// 获取指定 ID 的任务
+/// </summary>
+/// <param name="id">任务 ID</param>
+/// <returns>任务对象</returns>
+/// <exception cref="NotFoundException">当任务不存在时抛出</exception>
+public async Task<Task> GetTaskByIdAsync(int id)
+{
+    // 实现
+}
+```
+
+## 4. JavaScript/TypeScript 代码规范
+
+### 4.1 命名规范
+
+#### 变量和函数
+```typescript
+// 变量使用 camelCase
+const taskList = [];
+let currentTask = null;
+
+// 函数使用 camelCase
+function getTasks() {
+  // 实现
+}
+
+// 常量使用 UPPER_SNAKE_CASE
+const MAX_TASK_TITLE_LENGTH = 200;
+```
+
+#### 类和接口
+```typescript
+// 类名使用 PascalCase
+class TaskService {
+  // 实现
+}
+
+// 接口名使用 PascalCase
+interface Task {
+  id: number;
+  title: string;
+}
+
+// 类型别名使用 PascalCase
+type TaskPriority = 'high' | 'medium' | 'low';
+```
+
+### 4.2 代码组织
+
+#### 文件结构
+```typescript
+// 1. 导入语句
+import { ref, computed } from 'vue';
+import { useTaskStore } from '@/stores/tasks';
+import type { Task } from '@/types/task';
+
+// 2. 类型定义
+interface TaskForm {
+  title: string;
+  priority: TaskPriority;
+}
+
+// 3. 常量定义
+const DEFAULT_PRIORITY: TaskPriority = 'medium';
+
+// 4. 组合式函数或组件
+export function useTasks() {
+  // 实现
+}
+```
+
+#### 模块导入
+```typescript
+// 优先使用 ES6 模块语法
+import { ref } from 'vue';
+import axios from 'axios';
+
+// 导出使用具名导出
+export function useTasks() {
+  // 实现
+}
+
+export default useTasks;
+```
+
+### 4.3 TypeScript 规范
+
+#### 类型定义
+```typescript
+// 为所有函数参数和返回值添加类型
+function getTaskById(id: number): Task | null {
+  // 实现
+}
+
+// 使用接口定义对象类型
+interface Task {
+  id: number;
+  title: string;
+  priority: TaskPriority;
+  isCompleted: boolean;
+  createdAt: Date;
+}
+
+// 使用类型别名定义联合类型
+type TaskPriority = 'high' | 'medium' | 'low';
+
+// 使用泛型提高代码复用性
+interface ApiResponse<T> {
+  data: T;
+  message: string;
+}
+```
+
+#### 类型断言
+```typescript
+// 优先使用类型守卫而非类型断言
+function isTask(obj: unknown): obj is Task {
+  return typeof obj === 'object' && obj !== null && 'id' in obj;
+}
+
+// 避免使用 as any
+const task = response.data as Task; // 避免
+```
+
+### 4.4 异步编程
+```typescript
+// 使用 async/await 而非 Promise 链
+async function getTasks(): Promise<Task[]> {
+  const response = await axios.get('/api/tasks');
+  return response.data;
+}
+
+// 错误处理
+try {
+  const tasks = await getTasks();
+} catch (error) {
+  console.error('Failed to fetch tasks:', error);
+}
+```
+
+## 5. Vue.js 代码规范
+
+### 5.1 组件命名
+```vue
+<!-- 组件名使用 PascalCase -->
+<script setup lang="ts">
+// 组件名应与文件名一致
+</script>
+
+<template>
+  <!-- 模板中使用 kebab-case -->
+  <task-item :task="task" />
+</template>
+```
+
+### 5.2 组件结构
+```vue
+<template>
+  <!-- 1. 模板 -->
+  <div class="task-list">
+    <task-item
+      v-for="task in tasks"
+      :key="task.id"
+      :task="task"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+// 2. 导入
+import { ref, computed } from 'vue';
+import { useTaskStore } from '@/stores/tasks';
+import TaskItem from './TaskItem.vue';
+
+// 3. Props 定义
+interface Props {
+  filter: 'all' | 'active' | 'completed';
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  filter: 'all'
+});
+
+// 4. Emits 定义
+const emit = defineEmits<{
+  (e: 'task-created', task: Task): void;
+}>();
+
+// 5. 响应式状态
+const taskStore = useTaskStore();
+const tasks = computed(() => taskStore.filteredTasks(props.filter));
+
+// 6. 方法
+const handleCreateTask = async (title: string) => {
+  const task = await taskStore.createTask(title);
+  emit('task-created', task);
+};
+</script>
+
+<style scoped>
+/* 6. 样式 */
+.task-list {
+  padding: 16px;
+}
+</style>
+```
+
+### 5.3 组合式函数规范
+```typescript
+// composables/useTasks.ts
+import { ref, computed } from 'vue';
+import { useTaskStore } from '@/stores/tasks';
+
+export function useTasks() {
+  const taskStore = useTaskStore();
+  const loading = ref(false);
+  const error = ref<string | null>(null);
+
+  const tasks = computed(() => taskStore.tasks);
+  const completedTasks = computed(() => taskStore.completedTasks);
+
+  const fetchTasks = async () => {
+    loading.value = true;
+    error.value = null;
+    
+    try {
+      await taskStore.fetchTasks();
+    } catch (err) {
+      error.value = 'Failed to fetch tasks';
+      console.error(err);
+    } finally {
+      loading.value = false;
+    }
+  };
+
+  return {
+    tasks,
+    completedTasks,
+    loading,
+    error,
+    fetchTasks
+  };
+}
+```
+
+### 5.4 状态管理规范
+```typescript
+// stores/tasks.ts
+import { defineStore } from 'pinia';
+import { ref, computed } from 'vue';
+import type { Task } from '@/types/task';
+
+export const useTaskStore = defineStore('tasks', () => {
+  // State
+  const tasks = ref<Task[]>([]);
+  const loading = ref(false);
+  const error = ref<string | null>(null);
+
+  // Getters
+  const activeTasks = computed(() => 
+    tasks.value.filter(task => !task.isCompleted)
+  );
+
+  const completedTasks = computed(() => 
+    tasks.value.filter(task => task.isCompleted)
+  );
+
+  // Actions
+  async function fetchTasks() {
+    loading.value = true;
+    try {
+      const response = await fetch('/api/tasks');
+      tasks.value = await response.json();
+    } catch (err) {
+      error.value = 'Failed to fetch tasks';
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  return {
+    tasks,
+    loading,
+    error,
+    activeTasks,
+    completedTasks,
+    fetchTasks
+  };
+});
+```
+
+## 6. API 设计规范
+
+### 6.1 RESTful API 设计
+```csharp
+// 使用名词复数形式
+[HttpGet("tasks")]
+public async Task<ActionResult<List<Task>>> GetTasks()
+{
+}
+
+// 使用资源 ID
+[HttpGet("tasks/{id}")]
+public async Task<ActionResult<Task>> GetTask(int id)
+{
+}
+
+// 使用 HTTP 方法表示操作
+[HttpPost("tasks")]
+public async Task<ActionResult<Task>> CreateTask(CreateTaskDto dto)
+{
+}
+
+[HttpPut("tasks/{id}")]
+public async Task<ActionResult<Task>> UpdateTask(int id, UpdateTaskDto dto)
+{
+}
+
+[HttpDelete("tasks/{id}")]
+public async Task<ActionResult> DeleteTask(int id)
+{
+}
+```
+
+### 6.2 响应格式
+```csharp
+// 统一的响应格式
+public class ApiResponse<T>
+{
+    public bool Success { get; set; }
+    public T Data { get; set; }
+    public string Message { get; set; }
+    public List<string> Errors { get; set; }
+}
+
+// 成功响应
+return Ok(new ApiResponse<Task>
+{
+    Success = true,
+    Data = task,
+    Message = "Task created successfully"
+});
+
+// 错误响应
+return BadRequest(new ApiResponse<object>
+{
+    Success = false,
+    Message = "Validation failed",
+    Errors = new List<string> { "Title is required" }
+});
+```
+
+## 7. Git 提交规范
+
+### 7.1 提交信息格式
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### 7.2 Type 类型
+- `feat`: 新功能
+- `fix`: 修复 bug
+- `docs`: 文档更新
+- `style`: 代码格式调整（不影响代码运行）
+- `refactor`: 重构（既不是新功能也不是修复 bug）
+- `perf`: 性能优化
+- `test`: 测试相关
+- `chore`: 构建过程或辅助工具的变动
+
+### 7.3 示例
+```
+feat(api): add task completion endpoint
+
+- Add PATCH /api/tasks/{id}/complete endpoint
+- Update task service to handle completion logic
+- Add unit tests for completion functionality
+
+Closes #123
+```
+
+## 8. 测试规范
+
+### 8.1 单元测试
+```csharp
+// 测试类命名: ClassName + Tests
+public class TaskServiceTests
+{
+    [Fact]
+    public async Task GetTasksAsync_ReturnsAllTasks()
+    {
+        // Arrange
+        var mockRepository = new Mock<ITaskRepository>();
+        var service = new TaskService(mockRepository.Object);
+        
+        // Act
+        var result = await service.GetTasksAsync();
+        
+        // Assert
+        Assert.NotNull(result);
+        Assert.Equal(3, result.Count);
+    }
+}
+```
+
+### 8.2 集成测试
+```csharp
+public class ApiIntegrationTests : IClassFixture<WebApplicationFactory<Program>>
+{
+    private readonly HttpClient _client;
+
+    public ApiIntegrationTests(WebApplicationFactory<Program> factory)
+    {
+        _client = factory.CreateClient();
+    }
+
+    [Fact]
+    public async Task GetTasks_ReturnsSuccessAndCorrectContentType()
+    {
+        // Act
+        var response = await _client.GetAsync("/api/tasks");
+
+        // Assert
+        response.EnsureSuccessStatusCode();
+        Assert.Equal("application/json", response.Content.Headers.ContentType?.MediaType);
+    }
+}
+```
+
+## 9. 代码审查清单
+
+### 9.1 代码质量
+- [ ] 代码符合项目规范
+- [ ] 变量和函数命名清晰
+- [ ] 没有重复代码
+- [ ] 复杂逻辑有注释说明
+- [ ] 没有硬编码的魔法数字
+
+### 9.2 功能正确性
+- [ ] 功能实现符合需求
+- [ ] 边界条件已处理
+- [ ] 错误处理完善
+- [ ] 有相应的单元测试
+
+### 9.3 性能和安全
+- [ ] 没有性能问题
+- [ ] 敏感数据已保护
+- [ ] 输入验证完善
+- [ ] 没有安全漏洞
+
+## 10. 工具配置
+
+### 10.1 C# 工具
+- **代码格式化**: dotnet format
+- **代码分析**: Roslyn Analyzers
+- **代码风格**: .editorconfig
+- **文档生成**: DocFX
+
+### 10.2 JavaScript/TypeScript 工具
+- **代码格式化**: Prettier
+- **代码检查**: ESLint
+- **类型检查**: TypeScript
+- **代码风格**: .prettierrc
+
+### 10.3 .editorconfig 示例
+```ini
+root = true
+
+[*.cs]
+indent_style = space
+indent_size = 4
+end_of_line = crlf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{js,ts,vue}]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+```

docs/manual/其他信息.md

@@ -0,0 +1,19 @@
+# 其他信息
+
+## 🤝 贡献指南
+
+1. Fork 项目
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 打开 Pull Request
+
+## 📄 许可证
+
+本项目采用 AGPL-3.0 许可证 - 查看 [LICENSE](LICENSE) (英文) 或 [LICENSE.zh-CN](LICENSE.zh-CN) (中文) 文件了解详情
+
+## 📞 联系方式
+
+- 项目作者：ShaoHua
+- 项目地址：https://git.we965.cn/Tools/Hua.Todo
+- QQ 交流群：2167048911 (Hua.Todo 交流群)

docs/manual/技术栈与模块.md

@@ -0,0 +1,39 @@
+# 技术栈与模块说明
+
+## 🛠️ 技术栈
+
+### 后端技术栈
+- **开发语言**：C# 10
+- **框架**：.NET 10
+- **UI 框架**：MAUI (Multi-platform App UI)
+- **Web 服务器**：Kestrel (ASP.NET Core 内置)
+- **API 框架**：ASP.NET Core Web API
+- **数据访问**：Entity Framework Core
+- **数据库**：SQLite (本地存储)
+- **依赖注入**：Microsoft.Extensions.DependencyInjection
+
+### 前端技术栈
+- **开发语言**：TypeScript
+- **框架**：Vue.js 3
+- **构建工具**：Vite
+- **HTTP 客户端**：Axios
+- **状态管理**：Pinia
+- **UI 组件库**：Element Plus / Vant (移动端)
+- **CSS 预处理器**：SCSS
+
+## 🎯 核心模块说明
+
+### Hua.Todo.Core
+领域实体层，定义核心实体（TaskEntity）、枚举（TaskPriority）以及仓储接口（ITaskRepository）。
+
+### Hua.Todo.Application
+应用层实现，包含业务逻辑、动态 API 生成逻辑、EF Core 数据库上下文以及具体的服务实现（TaskService）。
+
+### Hua.Todo.Host
+后端 API 宿主，提供运行环境和配置，是后端服务的启动入口。
+
+### Hua.Todo.Web
+前端 Web 项目，基于 Vue.js 3 + TypeScript + Vite，提供用户界面，通过 HTTP API 与后端通信。
+
+### Hua.Todo.Maui
+跨平台客户端项目，将 Web 内容嵌入到原生容器中，支持 Windows、Android、iOS 和 macOS。

docs/manual/技术设计文档.md

@@ -0,0 +1,355 @@
+# Hua.Todo 技术设计文档 v1.1.0
+
+## 1. 项目概述
+本文档描述 Hua.Todo v1.1.0 的技术设计方案，包括项目文件目录结构、模块划分、技术选型和实现细节。
+
+## 2. 技术栈
+
+### 2.1 后端技术栈
+- **开发语言**: C# 10
+- **框架**: .NET 10
+- **UI 框架**: MAUI (Multi-platform App UI)
+- **Web 服务器**: Kestrel (ASP.NET Core 内置)
+- **API 框架**: ASP.NET Core Web API
+- **数据访问**: Entity Framework Core
+- **数据库**: SQLite (本地存储)
+- **日志**: Serilog
+- **依赖注入**: Microsoft.Extensions.DependencyInjection
+
+### 2.2 前端技术栈
+- **开发语言**: JavaScript/TypeScript
+- **框架**: Vue.js 3
+- **构建工具**: Vite
+- **HTTP 客户端**: Axios
+- **状态管理**: Pinia
+- **UI 组件库**: Element Plus / Vant (移动端)
+- **CSS 预处理器**: SCSS
+
+## 3. 项目目录结构
+
+```
+Hua.Todo/
+├── docs/                              # 文档目录
+│   ├── manual/                        # 用户/开发者手册
+│   │   ├── 技术栈与模块.md
+│   │   ├── 版本记录.md
+│   │   ├── 技术设计文档.md（本文件）
+│   │   └── 代码规范文档.md
+│   └── project/                       # 项目进度/需求文档
+│       ├── 产品需求文档.md
+│       └── ...
+│
+├── src/                               # 源代码目录
+│   ├── Hua.Todo.Maui/                 # MAUI 主项目（跨平台入口）
+│   │   ├── Platforms/                 # 平台特定代码
+│   │   │   ├── Windows/               # Windows 平台代码
+│   │   │   │   ├── App.xaml           # Windows 应用入口
+│   │   │   │   └── Services/          # Windows 平台服务
+│   │   │   │       └── HotKeyService.cs
+│   │   │   ├── MacCatalyst/           # macOS 平台代码
+│   │   │   │   ├── App.xaml
+│   │   │   │   └── Services/
+│   │   │   │       └── HotKeyService.cs
+│   │   │   ├── Android/               # Android 平台代码
+│   │   │   │   ├── MainActivity.cs
+│   │   │   │   └── Services/
+│   │   │   │       └── NotificationService.cs
+│   │   │   └── iOS/                   # iOS 平台代码
+│   │   │       ├── AppDelegate.cs
+│   │   │       └── Services/
+│   │   │           └── NotificationService.cs
+│   │   ├── Resources/                 # 资源文件
+│   │   │   ├── Images/                # 图片资源
+│   │   │   ├── Styles/                # 样式资源
+│   │   │   └── Fonts/                 # 字体资源
+│   │   ├── Controls/                  # 自定义控件
+│   │   │   └── WebViewContainer.xaml
+│   │   ├── Services/                  # 服务层
+│   │   │   ├── IHotKeyService.cs
+│   │   │   ├── IPlatformService.cs
+│   │   │   └── AppLifecycleService.cs
+│   │   ├── App.xaml                   # MAUI 应用入口
+│   │   ├── App.xaml.cs
+│   │   ├── MauiProgram.cs             # MAUI 程序配置
+│   │   └── Hua.Todo.Maui.csproj       # MAUI 项目文件
+│   │
+│   ├── Hua.Todo.Api/                  # 后端 API 项目
+│   │   ├── Controllers/               # API 控制器
+│   │   │   ├── TasksController.cs
+│   │   │   ├── SettingsController.cs
+│   │   │   └── SyncController.cs
+│   │   ├── Models/                    # 数据模型
+│   │   │   ├── Task.cs
+│   │   │   ├── TaskDto.cs
+│   │   │   └── ApiResponse.cs
+│   │   ├── Services/                  # 业务服务
+│   │   │   ├── ITaskService.cs
+│   │   │   ├── TaskService.cs
+│   │   │   ├── ISyncService.cs
+│   │   │   └── SyncService.cs
+│   │   ├── Data/                      # 数据访问层
+│   │   │   ├── TodoDbContext.cs
+│   │   │   ├── Repositories/
+│   │   │   │   ├── ITaskRepository.cs
+│   │   │   │   └── TaskRepository.cs
+│   │   │   └── Migrations/            # 数据库迁移
+│   │   ├── Middleware/                # 中间件
+│   │   │   └── ExceptionMiddleware.cs
+│   │   ├── Extensions/                # 扩展方法
+│   │   │   └── ServiceCollectionExtensions.cs
+│   │   ├── Program.cs                 # API 入口
+│   │   ├── appsettings.json           # 配置文件
+│   │   └── Hua.Todo.Api.csproj        # API 项目文件
+│   │
+│   ├── Hua.Todo.Core/                 # 核心业务逻辑层
+│   │   ├── Entities/                  # 实体类
+│   │   │   ├── Task.cs
+│   │   │   └── TaskPriority.cs
+│   │   ├── Interfaces/                # 接口定义
+│   │   │   ├── ITaskRepository.cs
+│   │   │   └── IUnitOfWork.cs
+│   │   ├── ValueObjects/              # 值对象
+│   │   │   └── TaskTitle.cs
+│   │   ├── Specifications/            # 规范模式
+│   │   │   └── TaskSpecifications.cs
+│   │   └── Hua.Todo.Core.csproj       # Core 项目文件
+│   │
+│   ├── Hua.Todo.Web/                  # 前端 Web 项目 (Vue.js)
+│   │   ├── public/                    # 静态资源
+│   │   │   └── index.html
+│   │   ├── src/                       # 源代码
+│   │   │   ├── api/                   # API 调用
+│   │   │   │   ├── client.ts         # HTTP 客户端配置
+│   │   │   │   ├── tasks.ts          # 任务相关 API
+│   │   │   │   └── settings.ts       # 设置相关 API
+│   │   │   ├── assets/                # 资源文件
+│   │   │   │   ├── images/
+│   │   │   │   └── styles/
+│   │   │   ├── components/            # Vue 组件
+│   │   │   │   ├── TaskList.vue
+│   │   │   │   ├── TaskItem.vue
+│   │   │   │   ├── QuickEntry.vue
+│   │   │   │   └── Settings.vue
+│   │   │   ├── composables/           # 组合式函数
+│   │   │   │   ├── useTasks.ts
+│   │   │   │   └── useHotKey.ts
+│   │   │   ├── stores/                # 状态管理 (Pinia)
+│   │   │   │   ├── tasks.ts
+│   │   │   │   └── settings.ts
+│   │   │   ├── types/                 # TypeScript 类型定义
+│   │   │   │   ├── task.ts
+│   │   │   │   └── api.ts
+│   │   │   ├── utils/                 # 工具函数
+│   │   │   │   ├── date.ts
+│   │   │   │   └── storage.ts
+│   │   │   ├── App.vue                # 根组件
+│   │   │   └── main.ts                # 应用入口
+│   │   ├── package.json               # 依赖配置
+│   │   ├── vite.config.ts             # Vite 配置
+│   │   ├── tsconfig.json              # TypeScript 配置
+│   │   └── index.html                 # HTML 模板
+│   │
+│   └── Hua.Todo.Tests/                # 测试项目
+│       ├── Unit/                      # 单元测试
+│       │   ├── Services/
+│       │   │   └── TaskServiceTests.cs
+│       │   └── Controllers/
+│       │       └── TasksControllerTests.cs
+│       ├── Integration/               # 集成测试
+│       │   └── ApiIntegrationTests.cs
+│       └── Hua.Todo.Tests.csproj
+│
+├── .gitignore                         # Git 忽略文件
+├── Hua.Todo.sln                       # 解决方案文件
+└── README.md                          # 项目说明文档
+```
+
+## 4. 模块设计
+
+### 4.1 MAUI 主项目 (Hua.Todo.Maui)
+**职责**: 
+- 应用程序入口和生命周期管理
+- 平台特定功能封装
+- WebView 容器管理
+- 本地 HTTP 服务器启动
+
+**关键组件**:
+- `MauiProgram.cs`: 配置 MAUI 应用和依赖注入
+- `App.xaml.cs`: 应用程序主入口
+- `WebViewContainer`: 封装 WebView 控件
+- 平台特定服务: 快捷键、通知等
+
+### 4.2 后端 API 项目 (Hua.Todo.Api)
+**职责**:
+- 提供 RESTful API 接口
+- 业务逻辑处理
+- 数据访问和持久化
+- 本地 HTTP 服务器托管
+
+**关键组件**:
+- `Controllers`: API 端点实现
+- `Services`: 业务逻辑服务
+- `Data`: 数据访问层和数据库上下文
+- `Program.cs`: API 服务器配置和启动
+
+### 4.3 核心业务层 (Hua.Todo.Core)
+**职责**:
+- 定义领域模型和业务规则
+- 提供核心业务接口
+- 实现领域驱动设计模式
+
+**关键组件**:
+- `Entities`: 领域实体
+- `Interfaces`: 业务接口定义
+- `ValueObjects`: 值对象
+- `Specifications`: 业务规范
+
+### 4.4 前端 Web 项目 (Hua.Todo.Web)
+**职责**:
+- 用户界面展示
+- 用户交互处理
+- HTTP API 调用
+- 状态管理
+
+**关键组件**:
+- `components`: Vue 组件
+- `api`: API 调用封装
+- `stores`: 状态管理
+- `composables`: 组合式函数
+
+## 5. HTTP API 设计
+
+### 5.1 API 基础配置
+- **基础 URL**: `http://localhost:5000/api`
+- **数据格式**: JSON
+- **认证方式**: 暂无（本地应用）
+- **跨域配置**: 允许本地跨域请求
+
+### 5.2 API 端点设计
+
+#### 任务管理 API
+```
+GET    /api/tasks              # 获取任务列表
+GET    /api/tasks/{id}         # 获取单个任务
+POST   /api/tasks              # 创建任务
+PUT    /api/tasks/{id}         # 更新任务
+DELETE /api/tasks/{id}         # 删除任务
+PATCH  /api/tasks/{id}/complete # 标记任务完成
+```
+
+#### 设置管理 API
+```
+GET    /api/settings          # 获取设置
+PUT    /api/settings          # 更新设置
+```
+
+#### 同步 API
+```
+POST   /api/sync/pull         # 拉取远程数据
+POST   /api/sync/push         # 推送本地数据
+```
+
+## 6. 数据库设计
+
+### 6.1 数据库表结构
+
+#### Tasks 表
+```sql
+CREATE TABLE Tasks (
+    Id INTEGER PRIMARY KEY AUTOINCREMENT,
+    Title TEXT NOT NULL,
+    Priority INTEGER NOT NULL DEFAULT 0,
+    IsCompleted INTEGER NOT NULL DEFAULT 0,
+    CreatedAt TEXT NOT NULL,
+    UpdatedAt TEXT NOT NULL
+);
+```
+
+#### Settings 表
+```sql
+CREATE TABLE Settings (
+    Key TEXT PRIMARY KEY,
+    Value TEXT NOT NULL,
+    UpdatedAt TEXT NOT NULL
+);
+```
+
+### 6.2 数据访问策略
+- 使用 Entity Framework Core 进行数据访问
+- 采用 Repository 模式封装数据访问
+- 支持 LINQ 查询和异步操作
+- 数据库迁移管理
+
+## 7. 通信机制
+
+### 7.1 HTTP 通信流程
+1. **C# 后端启动**: MAUI 应用启动时启动本地 Kestrel 服务器
+2. **Vue 前端加载**: WebView 加载 Vue 应用
+3. **API 调用**: Vue 通过 Axios 调用本地 HTTP API
+4. **数据处理**: C# 后端处理请求并返回 JSON 数据
+5. **界面更新**: Vue 接收响应并更新界面
+
+### 7.2 错误处理
+- 统一的错误响应格式
+- 异常中间件捕获和处理
+- 前端错误提示和重试机制
+
+## 8. 部署和打包
+
+### 8.1 开发环境
+- **后端调试**: 使用 Visual Studio 调试 MAUI 应用
+- **前端调试**: 使用 Vite 开发服务器
+- **热重载**: 支持前后端热重载
+
+### 8.2 生产构建
+- **前端构建**: `npm run build` 生成静态文件
+- **后端打包**: MAUI 发布各平台应用
+- **静态文件嵌入**: 将前端静态文件嵌入到 MAUI 应用中
+
+### 8.3 平台特定配置
+- **Windows**: WebView2 运行时要求
+- **macOS**: 代码签名和公证
+- **移动端**: 应用商店发布配置
+
+## 9. 性能优化
+
+### 9.1 前端优化
+- 组件懒加载
+- 虚拟滚动（长列表）
+- 图片懒加载
+- 缓存策略
+
+### 9.2 后端优化
+- 数据库查询优化
+- 响应缓存
+- 异步处理
+- 连接池管理
+
+## 10. 安全考虑
+
+### 10.1 本地安全
+- 本地服务器仅监听 localhost
+- 防止外部访问
+- 数据加密存储（可选）
+
+### 10.2 数据安全
+- 数据库文件权限控制
+- 定期备份机制
+- 敏感数据保护
+
+## 11. 测试策略
+
+### 11.1 单元测试
+- 核心业务逻辑测试
+- 服务层测试
+- 工具函数测试
+
+### 11.2 集成测试
+- API 集成测试
+- 数据库集成测试
+- 前后端集成测试
+
+### 11.3 端到端测试
+- 跨平台功能测试
+- 用户流程测试
+- 性能测试

docs/manual/版本记录.md

@@ -0,0 +1,30 @@
+# 版本更新历史
+
+## 🔄 版本更新
+
+### 版本策略
+- 采用语义化版本号：`MAJOR.MINOR.PATCH`
+- v1.0.0：初始 WPF 版本
+- v1.1.0：MAUI + WebView 跨平台版本
+- v1.2.0 (规划中)：Linux 支持与增强功能
+
+### v1.1.1 (2026-04-06)
+- **文档规范增强**：新增文档同步规则，强制代码变更与文档更新保持同步。
+- **项目结构说明校准**：修正 README.md 和技术文档中对 `Hua.Todo.Host`、`Hua.Todo.Application` 等模块的路径与职责描述。
+- **端口配置校准**：修正文档中关于前端与后端 API 的端口说明（5173/5174）。
+
+### v1.1.0 更新内容
+- 重构为 MAUI + WebView 架构
+- 实现跨平台支持 (Windows, macOS, Android, iOS)
+- 使用 HTTP API 进行前后端通信
+- 采用 Vue.js 3 作为前端框架
+- 使用 SQLite 作为本地数据库
+- 实现子任务支持
+
+### v1.2.0 规划内容 (即将推出)
+- **Linux 官方支持**：正式适配 Linux 平台。
+- **搜索与过滤**：支持按标题搜索、按优先级和状态过滤。
+- **本地提醒**：支持设置任务提醒时间并发送本地通知。
+- **标签系统**：引入多标签支持，提升任务组织效率。
+- **暗色模式**：全平台适配暗色/深色主题。
+- **数据导出导入**：支持 JSON 格式数据备份与迁移。