chore: 完成v1.2版本迭代与代码清理

本次提交完成了多项清理与规范工作： 1. 移除默认管理员硬编码配置与云同步相关代码 2. 简化前端与MAUI端的配置，关闭静态资源托管以外的冗余功能 3. 清理.gitignore与协调目录，移除临时文件与冗余规则 4. 统一项目命名规范，修正包名与版本号 5. 重构后端数据模型，移除ABP审计字段与云同步相关逻辑 6. 简化WebView配置与系统栏样式，移除不必要的平台检测代码 7. 更新文档与规则文件，完善项目规范与版本记录
2026-06-15 22:06:58 +08:00
parent 46db04e43e
commit cf96c56bed
70 changed files with 2514 additions and 2092 deletions
@@ -0,0 +1,75 @@
+# 项目架构（Hua.Todo 专属）
+
+> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。
+>
+> 描述当前仓库的项目划分、依赖方向、运行模式与跨平台策略，供智能体在做改动时快速对齐架构边界。
+> 完整设计参见 [docs/manual/01-技术设计文档.md](../../../docs/manual/01-技术设计文档.md) 与 [docs/manual/03-技术栈与模块.md](../../../docs/manual/03-技术栈与模块.md)。
+
+## 一、项目清单（src/）
+
+| 项目 | 类型 | 职责 | 平台 |
+|---|---|---|---|
+| [Hua.Todo.Core](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Core) | 类库 | 领域实体、仓储接口（`TaskEntity`、`UserEntity`、`SecurityPolicyEntity`、`AuditLogEntity`、`ITaskRepository` 等） | netstandard / net |
+| [Hua.Todo.Application](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Application) | 类库（共享层） | EF Core `TodoDbContext`、`TaskService`/`TaskRepository`、动态 API（`DynamicApi/`）、云同步（`CloudSync/`）、迁移 | net |
+| [Hua.Todo.Host](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Host) | ASP.NET 服务端 | 独立服务端宿主，承载本地动态 API + 云同步端点 + Admin 管理后台静态资源 | Windows/Linux 等服务器 |
+| [Hua.Todo.Maui](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Maui) | MAUI 客户端 | Windows / macOS / iOS / Android 入口；内嵌 WebServer + WebView 承载 Vue 前端 | 多端 |
+| [Hua.Todo.Avalonia](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Avalonia) | Avalonia 客户端 | Linux / Windows 桌面入口；内嵌 WebServer + `WebView.Avalonia` 承载 Vue 前端 | 桌面（含 Linux） |
+| [Hua.Todo.Web](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Web) | Vite + Vue 3 前端 | 同一份前端构建产物，被多个宿主以静态资源形式承载 | 浏览器/WebView |
+
+## 二、依赖方向（必须保持单向）
+
+```
+Hua.Todo.Core
+   ↑
+Hua.Todo.Application
+   ↑
+   ├── Hua.Todo.Host       (服务端注册 AddCloudSyncServer + 动态 API)
+   ├── Hua.Todo.Maui       (客户端，仅注册 AddApplicationServices)
+   └── Hua.Todo.Avalonia   (客户端，仅注册 AddApplicationServices)
+
+Hua.Todo.Web (无 .NET 依赖；通过 HTTP/同源调用上述任一宿主)
+```
+
+- **禁止反向依赖**：Core 不得引用 Application；Application 不得引用任何宿主项目。
+- **客户端不暴露云同步端点**：MAUI / Avalonia 只调用 `AddApplicationServices()`，不调用 `AddCloudSyncServer()`，详见 [docs/project/研发工单-v1.2.0/08-cloud_sync_refactor_plan.md](../../../docs/project/研发工单-v1.2.0/08-cloud_sync_refactor_plan.md)。
+
+## 三、两种运行模式
+
+### 模式 A：嵌入式（MAUI / Avalonia + WebView）
+- 启动内嵌 Kestrel WebServer（默认端口 5057），托管 Vue 前端的静态产物（`wwwroot/`）+ 本地 `/api/*`
+- WebView 加载 `HostUrl`（生产）或 `ForEndUrl`（开发，例如 Vite dev server）
+- 注入：`window.__API_BASE_URL__ = "${HostUrl}/api"`、`window.mauiInterop`
+- 默认 SQLite 路径：`LocalApplicationData/Hua.Todo/Hua.Todo.db`（避免安装目录无写权限）
+- 不暴露云同步端点；登录/同步走外部 Host
+
+### 模式 B：独立服务端（Hua.Todo.Host）
+- 独立部署的 ASP.NET 应用，端口 `:5173`（Vite proxy 目标）
+- 同时注册 `AddApplicationServices()` + `AddCloudSyncServer()`，对外提供：
+  - `/api/*`：本地任务 API（动态 API）
+  - `/auth/*`、`/tasks/*`、`/sync`、`/security/policy`、`/cloud-sync/probe`：云同步端点
+  - `/admin/*`：管理后台前端静态资源
+- 数据库：`src/Hua.Todo.Host/Hua.Todo.db`（开发/测试用）
+
+## 四、跨平台原则
+
+- **业务逻辑统一在 Application 层**，宿主项目只做 DI 装配与平台桥接
+- **平台差异通过接口 + 平台目录**实现（例：`IGlobalHotKeyService` 在 MAUI 与 Avalonia 各有自己的 `Platforms/` 子目录实现）
+- **前端只有一份**：Vue 项目通过不同的 `.env.*` 文件区分模式（`.env.development` / `.env.maui` / `.env.production`）
+
+## 五、关键扩展点
+
+| 扩展点 | 位置 |
+|---|---|
+| DI 注册总入口 | [Hua.Todo.Application/ServiceCollectionExtensions.cs](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Application/ServiceCollectionExtensions.cs) |
+| 云同步 DI | `Hua.Todo.Application/CloudSync/CloudSyncServiceCollectionExtensions.cs` |
+| 云同步端点 | `Hua.Todo.Application/CloudSync/CloudSyncEndpointExtensions.cs` |
+| 动态 API 中间件 | `Hua.Todo.Application/DynamicApi/DynamicApiMiddleware.cs` |
+| 嵌入式 WebServer | `Hua.Todo.{Maui,Avalonia}/Services/EmbeddedWebServerService.cs` |
+| 全局快捷键平台实现 | `Hua.Todo.{Maui,Avalonia}/Services/Platforms/*GlobalHotKeyService.cs` |
+
+## 六、版本统一策略
+
+- 全局版本号通过根目录 `Directory.Build.props` 集中管理（当前 `1.2.3`）
+- Inno Setup 安装包：`src/Hua.Todo.Maui/setup.iss`、`src/Hua.Todo.Avalonia/setup.iss`
+- Linux：`publish-linux.ps1` 产出 `.tar.gz`；`pack/linux/` 含 Flatpak 基础结构
+- 详见 [docs/project/研发工单-v1.2.0/02.1-版本统一与打包方案.md](../../../docs/project/研发工单-v1.2.0/02.1-版本统一与打包方案.md)
@@ -0,0 +1,60 @@
+# 业务命名规范（Hua.Todo 专属）
+
+> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。
+>
+> 本文档规定 **业务实体**（Todo 待办项相关）与 **编码工作项**（研发工单）在代码、文档、提交信息中的命名边界。
+> 全局术语规则参见 [.trae/rules/全局/05-研发工单规则.md](../全局/05-研发工单规则.md)。
+
+## 一、术语对照（核心）
+
+| 概念 | 含义 | 代码标识符 | 文档用语 |
+|---|---|---|---|
+| **Todo 待办项 / 业务任务** | 用户在 Hua.Todo 中创建的待办事项 | `Task` / `SubTask` / `TaskEntity` / `TaskItem` / `TaskService` / `TaskRepository` | "Todo 待办项 / 任务 / 子任务（业务实体）" |
+| **研发工单（Dev Work Item）** | 智能体/开发者执行的编码工作项 | 无（仅文档层概念） | "研发工单 / 工单 / 子工单" |
+
+## 二、代码命名约定（已固化，不要改名）
+
+> 以下标识符已落入 API 契约、数据库表、前端类型，**禁止以"统一术语"为由进行重命名**。
+
+### 2.1 .NET / C# 侧
+- 实体：`TaskEntity`（位于 [Hua.Todo.Core/Entities/TaskEntity.cs](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Core/Entities/TaskEntity.cs)）
+- 字段：`ParentTaskId`（父子任务关系）、`Priority`、`UserId`
+- 服务：`ITaskService` / `TaskService`、`ITaskRepository` / `TaskRepository`
+- 云同步 DTO：`CloudTaskItem`（位于 `Hua.Todo.Application/CloudSync/Models/TaskSyncDtos.cs`）
+- 用户固定 ID：`TodoUserIds.LocalUserId = "local"`（见 `Hua.Todo.Core/Entities/TodoUserIds.cs`）
+
+### 2.2 前端（Vue/TS）侧
+- 类型：`TaskItem` / `TaskNode`（位于 [Hua.Todo.Web/src/types/task.ts](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Web/src/types/task.ts)）
+- 组件：`TaskList.vue` / `TaskItem.vue` / `TaskEditDialog.vue`
+- API 模块：`api/tasks.ts`、`api/cloudSync.ts`
+
+### 2.3 HTTP API 路由
+- 本地动态 API：`/api/task`、`/api/task/{parentTaskId}/subtasks`（由 `Hua.Todo.Application/DynamicApi` 自动暴露）
+- 云端：`GET /tasks`、`POST /sync`、`POST /cloud-sync/probe`
+- 见 [docs/manual/01-技术设计文档.md](../../../docs/manual/01-技术设计文档.md)、[docs/project/研发工单-v1.2.0/04-CloudSync-服务端基础能力.md](../../../docs/project/研发工单-v1.2.0/04-CloudSync-服务端基础能力.md)
+
+### 2.4 数据库表
+- `Tasks`、`Users`、`UserSessions`、`SecurityPolicies`、`AuditLogs`
+- 迁移文件位于 `Hua.Todo.Application/Migrations/`
+
+## 三、新增代码命名指引
+
+### 3.1 与 Todo 业务相关的新代码
+- 沿用 `Task` / `SubTask` 词根，与既有命名保持一致
+- 如：`TaskFilterService`、`SubTaskCounter`、`TaskExportDto`
+
+### 3.2 与研发工单/工程基础设施相关的新代码
+- 不要使用 `Task` 词根（避免与业务实体撞名）
+- 如果是 .NET 异步方法，可使用 `Async` 后缀但不要把方法/类型主体命名为 `Task`
+
+### 3.3 文档与提交信息
+- 业务变更：`feat(todo): 新增 Todo 待办项截止日期字段`
+- 工程变更：`chore(workitem): 拆分 v1.2.0 研发工单 02-后端模型`
+- 严禁含糊措辞：`feat: 完成任务 02`（"任务"歧义）
+
+## 四、命名一致性检查清单
+
+1. [ ] 新增类/接口是否复用了已有 `Task*` 命名习惯？
+2. [ ] HTTP 路由是否与既有 `/api/task` / `/tasks` 风格一致？
+3. [ ] 文档段落是否在首次出现"任务"时明确指向 Todo 待办项还是研发工单？
+4. [ ] 提交信息是否避免了歧义"任务"用法？
@@ -0,0 +1,99 @@
+# 数据模型与迁移约束（Hua.Todo 专属）
+
+> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。
+>
+> 描述当前数据库实体、字段约束、EF Core 迁移历史，约束智能体在改 schema 时遵循的纪律。
+
+## 一、技术栈
+
+- ORM：**EF Core**
+- 数据库：**SQLite**（嵌入式与 Host 开发都走 SQLite；生产 Host 可切其他后端）
+- DbContext：[TodoDbContext](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Application/Data/TodoDbContext.cs)
+- 迁移目录：`Hua.Todo.Application/Migrations/`
+- **表名规范**：遵循 ABP 模板规范，格式为 `T_{实体名}s`，如 `T_Tasks`、`T_Users`
+
+## 二、当前实体清单（src/Hua.Todo.Core/Entities/）
+
+### 2.1 TaskEntity（待重构为 ABP 基类）
+
+> ⚠️ **重大变更预警**：TaskEntity 计划继承 `FullAuditedEntityWithUser<Guid, IdentityUser>`，重构后将包含 ABP 全部审计字段。此改为破坏性变更，详见 [09-CloudSync-同步策略改进方案.md](../../../docs/project/研发工单-v1.2.0/09-CloudSync-同步策略改进方案.md)。
+
+**重构前（当前）**：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `Id` | `int` | 主键（待改为 Guid） |
+| `UserId` | `Guid` | 任务所属用户 |
+| `Title` | `string` | 标题 |
+| `Priority` | `TaskPriority` | 优先级枚举 |
+| `IsCompleted` | `bool` | 是否完成 |
+| `CreatedAt` | `DateTime` | 创建时间 |
+| `UpdatedAt` | `DateTime` | 更新时间 |
+| `ParentTaskId` | `int?` | 父任务ID（待改为 Guid?） |
+
+**重构后（ABP 标准）**：
+
+继承 `FullAuditedEntityWithUser<Guid, IdentityUser>` 后自动获得：
+
+| ABP 审计字段 | 类型 | 说明 |
+|---|---|---|
+| `Id` | `Guid` | 主键（强制 Guid） |
+| `ExtraProperties` | `ExtraPropertyDictionary` | 扩展属性（基类提供） |
+| `ConcurrencyStamp` | `string?` | 并发戳 |
+| `CreationTime` | `DateTime` | 创建时间 |
+| `CreatorId` | `Guid?` | 创建人 |
+| `LastModificationTime` | `DateTime?` | 最后修改时间 |
+| `LastModifierId` | `Guid?` | 最后修改人 |
+| `IsDeleted` | `bool` | 软删除标记 |
+| `DeletionTime` | `DateTime?` | 删除时间 |
+| `DeleterId` | `Guid?` | 删除人 |
+
+业务字段保留：`UserId`、`Title`、`Priority`、`IsCompleted`、`ParentTaskId`
+
+### 2.2 其他实体
+
+| 实体 | 关键字段 | 约束 |
+|---|---|---|
+| `TaskPriority` | 枚举 | Priority 字段对应类型 |
+| `UserEntity` | `Id`、`UserName`、`PasswordHash`、`PasswordSalt`、`Role`、`MustChangePassword` | 唯一索引：`UserName` |
+| `UserSessionEntity` | `SessionId`、`UserId`、`ExpiresAtUtc`、`IsStepUp`、`StepUpExpiresAtUtc` | session token 由 DB 管理（非纯 JWT） |
+| `SecurityPolicyEntity` | `UserId`、`AllowPersist`、`AllowSync`、`SecondFactorExpiryMinutes`、`IsTrustedDeviceOnly` | 与 User 一对一 |
+| `AuditLogEntity` | `Id`、`UserId`、`Action`、`OccurredAtUtc`、`Details` | 关键安全事件 |
+| `TodoUserIds` | `LocalUserId = "local"` | 静态常量类，非实体 |
+
+## 三、迁移历史（按时间）
+
+| 迁移 | 含义 |
+|---|---|
+| `20260313044926_InitialCreate` | 初始 Tasks 表 |
+| `20260313092658_AddParentTaskId` | 父子任务字段 |
+| `20260406172936_AddCloudSyncCoreEntities` | Users / UserSessions / SecurityPolicies |
+| `20260406173734_AddAllowSyncToSecurityPolicy` | `AllowSync` 字段 |
+| `20260413140347_UpdateSecurityEntities` | 安全实体调整 |
+| `20260413140753_AddAuditLogs` | AuditLogs 表 |
+| `20260424164713_AddPasswordSaltToUsers` | 密码加盐 |
+| `20260510171230_AddMustChangePasswordToUsers` | 强制改密标志 |
+| `MakeTaskEntityAbpCompatible`（待创建） | 重构为继承 ABP 基类，新增审计字段，主键从 `int` 改为 `Guid` |
+
+## 四、改 schema 必须遵守的纪律
+
+1. **禁止手改 `*ModelSnapshot.cs`**：使用 `dotnet ef migrations add` 命令生成
+2. **迁移命名以动词开头**：`AddXxx` / `UpdateXxx` / `RemoveXxx` / `RenameXxx`
+3. **避免破坏性迁移**：删除字段前先确认数据已被业务层迁移；优先采用"双写/兼容期"
+4. **嵌入式宿主启动时自动 Migrate**：见 `EmbeddedWebServerService.cs` 中的 `db.Database.Migrate()` 调用；任何破坏迁移幂等性的改动都会让客户端启动失败
+5. **业务字段命名沿用 `Task*` 词根**（即业务实体），编码工作侧不要在实体上用 `Task` 词根之外的同义词
+6. **`UserId` 字段不可为空**：本地模式使用 `TodoUserIds.LocalUserId = "local"`，云端模式使用真实用户 GUID 字符串
+
+## 五、DTO 与实体的映射边界
+
+- **实体（Entity）**：仅在 `Hua.Todo.Core` / `Hua.Todo.Application/Data` 内部使用
+- **DTO（Models）**：跨进程边界（HTTP API、WebView 注入）使用，位于 `Hua.Todo.Application/CloudSync/Models/` 与 `Hua.Todo.Application/Models/`
+- **不要把实体直接序列化为 API 响应**：避免暴露内部字段、避免循环引用
+
+## 六、检查清单（schema 变更）
+
+1. [ ] 是否新增了 EF Core 迁移（而非手改快照）？
+2. [ ] 迁移名称是否以 `AddXxx`/`UpdateXxx`/`RemoveXxx` 开头？
+3. [ ] 是否在 [docs/manual/01-技术设计文档.md](../../../docs/manual/01-技术设计文档.md) 中同步更新数据模型描述？
+4. [ ] 是否在 [docs/manual/06-版本记录.md](../../../docs/manual/06-版本记录.md) 中追加非琐碎变更条目？
+5. [ ] 是否在嵌入式宿主上验证了启动时 Migrate 不报错？
@@ -0,0 +1,62 @@
+# 即时状态记忆（Hua.Todo 专属）
+
+> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。
+>
+> 本文档保存"当前实现到哪一步、未完结事项、临时决策"等**短期快照**，用于跨会话/跨智能体快速对齐。
+> 与 [.trae/memory/](../../memory) 的差别：memory 偏长期沉淀，此处偏即时状态，更新频率高。
+>
+> **维护要求**：智能体每完成一个研发工单或观察到状态变化时，必须更新本文件的对应章节。
+
+---
+
+## 一、当前活跃版本
+
+- **进行中版本**：v1.2.0
+- **研发工单总览**：[docs/project/研发工单-v1.2.0/00-工单总览.md](../../../docs/project/研发工单-v1.2.0/00-工单总览.md)
+- **PRD**：[docs/project/产品需求文档-1.2.0.md](../../../docs/project/产品需求文档-1.2.0.md)
+
+## 二、v1.2.0 工单状态快照
+
+| 子工单 | 实现状态 | 验证状态 | 简要说明 |
+|---|---|---|---|
+| 01 - Linux Avalonia 入口 + WebView | 已完成 | 待验证 | `WebView.Avalonia` + `WebView.Avalonia.Desktop`；Linux 依赖 GTK + WebKitGTK |
+| 02 - Linux 打包/交付 | 已落地 | 待验证 | `publish-linux.ps1` 产 `.tar.gz`；Flatpak 基础结构在 `pack/linux/` |
+| 02.1 - 版本统一打包 | 已落地 | 待验证 | `Directory.Build.props` 统一版本；Avalonia 新增 `setup.iss` |
+| 03 - Search 关键词检索 | 已完成 | 待验证 | 主界面搜索框，按 Todo 标题包含匹配；Esc 清空；英文不分大小写 |
+| 04 - 云同步 服务端基础能力 | 已完成 | 已验证 | API 契约固化；`Tasks` 表加 `UserId` 隔离；RBAC + step-up |
+| 05 - 云同步 客户端配置/工作流 | 已完成 | 待验证 | 新增"云同步设置"弹窗：地址保存探测、登录/登出、登录后只读展示云端 Todo |
+| 06 - 安全与可控落盘 | 未标注 | 待验证 | 框架就绪（`SecurityPolicy`），客户端落盘策略尚未充分覆盖 |
+| 06.1 - 服务端安全设计 | 已设计 | 待实现 | Argon2id/JWT/审计日志/Admin 管理后台规划 |
+| 07 - 文档同步与验收 | 进行中 | 进行中 | README/docs 已基本对齐；术语对照刚完成 |
+| 08 - cloud_sync 重构 | 已设计 | 待实现 | "同源 Host"方案，Vite proxy 补 `/auth` `/tasks` `/sync` `/security` `/cloud-sync` |
+| 09 - CloudSync 同步策略改进 | 已实现 | 待验证 | TaskEntity 继承 ABP 基类；软删除修复（SaveChangesAsync）；前端类型和 cloudSync.ts 已更新；新增 guid.ts |
+
+## 三、关键临时决策
+
+- **MAUI 端不暴露云同步端点**：`MauiProgram.cs` 仅注册 `AddApplicationServices()`，不调 `AddCloudSyncServer()`。云同步端点只在 `Hua.Todo.Host` 暴露。
+- **本地用户 ID 固定为 `"local"`**：嵌入式模式下 `Tasks.UserId = TodoUserIds.LocalUserId`，与云端用户隔离逻辑共存而不冲突。
+- **SQLite WAL 模式**：嵌入式宿主启动时强制开启 WAL，降低锁冲突。
+- **数据库路径**：默认 `LocalApplicationData/Hua.Todo/Hua.Todo.db`（避免安装目录无写权限）；Host 模式使用 `src/Hua.Todo.Host/Hua.Todo.db`（开发/测试）。
+
+## 四、已知未完结事项 / 待办
+
+- [ ] 06 客户端"内存模式"在 `allowPersist=false` 时的端到端落盘清理（含 token、同步队列）尚未充分验证
+- [ ] 06.1 设计中的 Admin 管理后台前端（位于 `Hua.Todo.Host/wwwroot/admin/`）当前仅有 `index.html` 占位，需 Vue 3 + Vite 实现
+- [ ] 08 同源 Host 改造：`cloudClient.ts` 的 baseURL 解耦、Vite proxy 端点补全
+- [ ] Linux Flatpak/AppImage 自包含产物在干净环境的实测验证（v1.2.0 验收 Linux 部分仍为"待验证"）
+- [x] CloudSync UNIQUE 约束修复（2026-06-14）：修复了 `existingTasks` 查询在事务外导致并发重同步时 `T_Tasks.Id` UNIQUE 约束冲突；新增 7 个测试（含 5 个 SQLite 集成测试）
+
+## 五、最近一次重大重构（如有）
+
+- **术语统一与目录中文化**（2026-06）：
+  - `.trae/rules/` 全部中文文件名 + 拆分为 `全局/` 和 `项目/` 两个子目录
+  - `docs/project/v1.2.0-tasks/` → `docs/project/研发工单-v1.2.0/`，`00-任务总览.md` → `00-工单总览.md`
+  - 在 PRD 顶部加入"研发工单 vs Todo 待办项"术语对照表
+  - 业务代码 `Task`/`SubTask` 标识符**保持不动**（已固化于 API、DB、UI）
+- **`.trae` 子目录文件序号化**（2026-06）：
+  - `.trae/rules/全局/`、`.trae/rules/项目/`、`.trae/coordination/`、`.trae/memory/` 下所有文件加 `NN-` 序号前缀
+  - `.trae/索引.md` 不带序号（入口文件）
+
+---
+
+> **更新约定**：每次智能体修改本文件时，必须更新顶部的"进行中版本"和"工单状态快照"两节，确保信息不过时。