ShaoHua
4fe0b5a963
本次提交完成了项目核心基础架构升级： 1. 新增动态API中间件与权限控制系统，支持匿名/鉴权接口分离 2. 搭建云同步服务体系，包含认证、任务同步、安全策略等核心模块 3. 实现语音控制全链路，从STT/意图解析到命令执行 4. 新增任务类型、附件实体与相关仓储接口 5. 重构前端配置与代理规则，统一后端端口为5057 6. 新增多平台测试项目与CI脚本优化 7. 完善项目文档与代码注释规范 移除了旧版迁移文件与冗余代理配置，调整项目结构适配跨平台部署需求。
158 lines
15 KiB
Markdown
158 lines
15 KiB
Markdown
# 即时状态记忆（Hua.Todo 专属）
|
||
|
||
> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。
|
||
>
|
||
> 本文档保存"当前实现到哪一步、未完结事项、临时决策"等**短期快照**，用于跨会话/跨智能体快速对齐。
|
||
> 与 [.trae/memory/](../../memory) 的差别：memory 偏长期沉淀，此处偏即时状态，更新频率高。
|
||
>
|
||
> **维护要求**：智能体每完成一个研发工单或观察到状态变化时，必须更新本文件的对应章节。
|
||
|
||
---
|
||
|
||
## 一、当前活跃版本
|
||
|
||
- **进行中版本**：v1.2.0（收尾中）、v1.3.0（规划中）
|
||
- **v1.2.0 研发工单总览**：[docs/project/研发工单-v1.2.0/00-工单总览.md](../../../docs/project/研发工单-v1.2.0/00-工单总览.md)
|
||
- **v1.3.0 研发工单总览**：[docs/project/研发工单-v1.3.0/00-工单总览.md](../../../docs/project/研发工单-v1.3.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 |
|
||
|
||
## 三、v1.3.0 工单状态快照
|
||
|
||
| 子工单 | 实现状态 | 验证状态 | 简要说明 |
|
||
|---|---|---|---|
|
||
| 01 - HTTP 服务转换 MCP 服务 | 进行中 | 待验证 | 将现有 HTTP API 映射为 MCP 工具描述符 |
|
||
| 02 - 语音控制与 AI 辅助 | 已完成（核心基础设施） | 待验证 | Core 接口（IVoiceInputService/IVoiceOutputService/IVoiceIntentParser）、VoiceIntent 枚举与 DTO、LLM 客户端（LlmClientService）、双策略意图解析器（LlmIntentParser + RuleIntentParser + HybridVoiceIntentParser）、VoiceCommandExecutor、AiBreakdownService、VoiceService（Dynamic API）、DI 注册；26 个单元测试通过；平台 STT/TTS 实现待补 |
|
||
| 03 - 会议任务拆分 | 待开始 | 待验证 | 会议类型入口 + 录音/文字输入 + AI 拆分建议 + 确认批量创建 |
|
||
| 03-01 - 会议数据模型与 API | 待开始 | 待验证 | TaskType 枚举、MeetingNotes/AudioDuration 字段、MeetingController |
|
||
| 03-02 - 音频录制与转写 | 待开始 | 待验证 | 前端 MediaRecorder 录音 + 后端 STT 转写 |
|
||
| 03-03 - AI 任务拆分服务 | 待开始 | 待验证 | 会议专用 LLM prompt + 批量创建子任务 |
|
||
| 03-04 | 任务建议与确认 UI | 已完成 | 待验证 | MeetingBreakdownDialog.vue + meeting.ts 拆分/确认 API；待集成到 TaskItem |
|
||
| 04 | 富文本描述、附件与外部链接 | 已完成 | 待验证 | Description 字段 + AttachmentEntity 模型 + 附件 CRUD API + 外部链接 + 平台文件打开器（Maui/Avalonia）+ 前端类型和 API 模块完善 + EF 迁移 + 19 个单元测试通过 |
|
||
|
||
## 四、关键临时决策
|
||
|
||
- **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 集成测试）
|
||
|
||
- [x] v1.3.0 工单01 - MCP 服务转换已完成（2026-06-16）：DynamicMcpToolExtensions 自动扫描所有 IDynamicApiService 接口并生成 MCP 工具；当前覆盖 ITaskService（9 个工具）+ IVoiceService（4 个工具）= 13 个 MCP 工具；新增 4 个测试（描述验证、InputSchema 验证、服务调用、工具调用端到端），共计 17 个测试全部通过；CloudSync 服务因未实现 IDynamicApiService 暂未覆盖，记录为已知缺口
|
||
|
||
- [x] MAUI 平台编译修复（2026-06-16）：(1) Application.csproj 非 net10.0 目标新增排除 CloudSync/**/*.cs（其依赖 Microsoft.AspNetCore.App）；(2) 新增 Microsoft.Extensions.Http 包引用（Voice 服务使用 AddHttpClient）；(3) MobileEmbeddedWebServerService.cs Android 平台 int→Guid 适配（TaskEntity ABP 重构遗留）；验证通过：MAUI Android/Windows + Host 均 0 错误
|
||
|
||
- [x] 测试项目重构（2026-06-17）：原 src/Hua.Todo.Tests 拆分为三个宿主对应测试项目，放入 src/test/ 目录：Hua.Todo.Host.Tests（后端服务测试，144 个用例全过）、Hua.Todo.Maui.Tests（骨架）、Hua.Todo.Avalonia.Tests（骨架）；更新 .slnx 与 docs 引用
|
||
|
||
- [x] EF Core 迁移合并（2026-06-17）：10 个历史迁移合并为单一 `20260616203619_InitialCreate`，Migrations 目录从 21 个文件减至 3 个；DatabaseMigrationTests 断言同步更新；157 个测试全部通过
|
||
|
||
- [x] MAUI Windows 云同步代理功能修复（2026-06-17）：
|
||
- **问题**：`Hua.Todo.Application.csproj` 第 14-18 行在非 net10.0 目标上排除了整个 CloudSync 目录，导致 MAUI Windows 编译时 CloudSync 代码不存在
|
||
- **影响**：MAUI Windows 的 `EmbeddedWebServerService` 缺少云同步代理支持（`AddCloudSyncProxy()`、`UseCloudSyncProxy()`、`MapCloudSyncProxySettings()`），前端云同步设置弹窗无法工作
|
||
- **修复**：
|
||
1. 从 Application.csproj 移除 CloudSync 的自动排除（保留 SkipCloudSync=true 手动开关）
|
||
2. MAUI Windows `EmbeddedWebServerService` 添加云同步代理支持（参考 Avalonia 实现）
|
||
3. `WebServerSettings` 新增 `CloudSyncUrl` 属性
|
||
- **验证**：MAUI Windows + Host + 152 个测试 全部通过
|
||
|
||
- [x] DynamicApi/Mcp/CloudSync ASP.NET Core 依赖隔离（2026-06-17）：
|
||
- **问题**：Application.csproj 在非 net10.0 目标上整体排除 DynamicApi/**/*.cs 和 Mcp/**/*.cs，并用桩文件（Compatibility/DynamicApiStubs.cs）替代；CloudSync 通过 SkipCloudSync=true 手动排除；核心属性类（HttpAttributes、RemoteServiceAttribute 等）在移动平台不可用
|
||
- **修复**：
|
||
1. 移除 csproj 中 DynamicApi/Mcp 的整体排除、桩文件排除、SkipCloudSync 开关
|
||
2. 新增 `ASPNETCORE` 编译符号（仅 net10.0 目标定义）
|
||
3. DynamicApi 核心属性文件（HttpAttributes.cs、ParameterBindingAttributes.cs、RemoteServiceAttribute.cs）全平台编译
|
||
4. DynamicApi/Mcp/CloudSync 中 13 个 ASP.NET Core 依赖文件用 `#if ASPNETCORE` 包裹
|
||
5. ClaimsPrincipalExtensions.cs 用 `FindFirst()?.Value` 替代 ASP.NET Core 的 `FindFirstValue` 扩展方法
|
||
6. 删除 Compatibility/DynamicApiStubs.cs 桩文件
|
||
7. 清理测试项目中的 SkipCloudSync 排除
|
||
- **验证**：Application(net10.0 + net10.0-android) + Host + MAUI(Windows + Android) 全部 0 错误；152 个测试全部通过
|
||
|
||
## 六、最近一次重大重构（如有）
|
||
|
||
- **术语统一与目录中文化**（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` 不带序号（入口文件）
|
||
- **`docs/manual/` 指南重组**（2026-06-16）：
|
||
- 新增 `00-目录与导读.md` 双入口导航（普通用户 / 开发者）
|
||
- 拆分用户面与开发者面：01-02 为用户安装使用；05-10 为开发者架构/构建/规范
|
||
- 合并重叠与过时内容，精简用户文档篇幅
|
||
- 同步更新 README.md 与 `.trae/rules/项目/` 中的交叉引用
|
||
- **全局 Serilog 文件日志**（2026-06-16）：
|
||
- Application 层新增 `LoggingConfiguration.cs` 统一日志配置（Console + 按天滚动文件）
|
||
- Host / MAUI / Avalonia 宿主层全部接入 Serilog，日志目录 `logs/`（Host）或 `{LocalApplicationData}/Hua.Todo/logs/`（客户端）
|
||
- 修复 `DynamicApiMiddleware` 及 Application 层 8 个服务类的 catch 块（原静默吞异常→记日志）
|
||
- 修复 MAUI 端 2 个 WebServer 文件 + Avalonia 端 `App.axaml.cs` / `EmbeddedWebServerService` 的 Console/Debug→Serilog
|
||
- 修复 `CloudTaskSyncService` SQL UNIQUE 约束冲突重试日志
|
||
- 144 个测试全部通过
|
||
|
||
- **Host 云同步端点补齐 + 测试目录迁移 + 规则新增**（2026-06-17）：
|
||
- **问题**：`Hua.Todo.Host/Program.cs` 未调用 `AddCloudSyncServer()` 和 `MapCloudSyncEndpoints()`，导致 `/auth/*` `/tasks/*` `/sync/*` `/security/*` `/cloud-sync/*` 全部 404
|
||
- **修复**：Program.cs 新增 `AddCloudSyncServer()` + `MapCloudSyncEndpoints()` + `MapCloudSyncProxySettings()`；`vite.config.ts` 新增 6 条云同步路径代理
|
||
- **测试**：`CloudSyncEndpointRegistrationTests.cs` 新增 5 个 DI 注册测试（完整 AddApplicationServices + AddCloudSyncServer 链路验证），157→157 全部通过
|
||
- **目录迁移**：`src/test/` → `test/`（上移一级），更新 3 个 `.csproj` 的 `<ProjectReference>` 路径 + `.slnx`
|
||
- **规则新增**：
|
||
- `.trae/rules/全局/08-修正与新功能自动测试门禁.md`：用户明确要求修正 bug 或新功能时自动触发测试先行
|
||
- `.trae/rules/项目/06-测试项目分层规范.md`：测试目录结构、分层规则（禁止跨层）、技术栈与命名规范
|
||
- **前端默认值**：`CloudSyncSettingsDialog` 默认地址 `http://localhost:5173`、默认账号 `admin`/`123456`
|
||
- **前端云同步入口**：`TaskList.vue` 新增登录/登出/同步按钮 + 用户信息 + 服务器地址显示；`App.vue` 修复 `CloudSyncSettingsDialog` 缺少 import 导致弹窗不打开
|
||
|
||
- **前端大量补齐**（2026-06-17 v1.3.0）：
|
||
- 新增 7 个文件（AttachmentList/LinkInputDialog/useAttachments/voice.ts/useVoiceInput/规则2个）
|
||
- 修改 5 个文件（TaskEditDialog/TaskItem/TaskList/tasks.ts/localStorageService）
|
||
- 删除 1 个无用文件（HelloWorld.vue）
|
||
- 编译 0 错误，105 个模块构建成功
|
||
|
||
- **CloudSync 端点 DynamicApi 化**（2026-06-17）：
|
||
- **问题**：`CloudSyncEndpointExtensions.MapCloudSyncEndpoints()` 手动映射 16 个端点（auth/tasks/sync/security/admin/probe），与项目中 ITaskService 等通过 IDynamicApiService 自动暴露的模式不一致
|
||
- **修复**：
|
||
1. 新增 `DynamicApiRouteAttribute`（服务级路由前缀覆盖）和 `RequirePermissionAttribute`（权限检查）
|
||
2. 扩展 `DynamicApiMiddleware`：支持 `DynamicApiRoute` 自定义路由前缀、`AllowAnonymous` / `RequirePermission` 权限检查、统一错误响应（401/403）
|
||
3. 创建 5 个 IDynamicApiService 接口：`ICloudAuthService`（`/api/auth`）、`ICloudTaskSyncService`（`/api/tasks`）、`ISecurityPolicyService`（`/api/security`）、`ICloudAdminService`（`/api/admin`）、`ICloudProbeService`（`/api/cloud-sync`）
|
||
4. 修改 5 个 Service 实现类：添加 `IHttpContextAccessor` 支持、接口方法（无 CancellationToken）、保留原有方法（Guided by CancellationToken）向后兼容
|
||
5. 移除 `MapCloudSyncEndpoints()` 入口和 16 个 handler 方法，`CloudSyncEndpointExtensions` 仅保留 `MapCloudSyncProxySettings()`
|
||
6. Host `Program.cs` 新增 `app.UseAuthentication()` 确保 SessionAuthenticationHandler 在 DynamicApi 前运行
|
||
7. `ResetPasswordRequest` 新增 `UserId` 字段（admin 重置密码路由扁平化）
|
||
8. `DynamicMcpToolExtensions` 新增 `RemoteServiceAttribute` 过滤（CloudSync 接口标记 `IsEnabled=false` 排除 MCP 暴露）
|
||
9. 4 个 Service 文件（CloudTaskSync/SecurityPolicy/CloudProbe/CloudAuth-接口方法）新增 `#if ASPNETCORE` 条件编译
|
||
- **验证**：Application(net10.0+android+ios+maccatalyst) + Host + Tests 全部编译通过，161 个测试全部通过
|
||
|
||
- [x] CloudSync Swagger + DynamicApi 路由修复（2026-06-17）：
|
||
- **问题1**：所有 CloudSync 接口标记 `[RemoteService(IsEnabled=false)]`，`DynamicApiSwaggerDocumentFilter` 用 `IsEnabled` 过滤 → CloudSync 接口在 Swagger 中完全不可见（只有 DTO Schema 没有 Path）
|
||
- **问题2**：同样的 `IsEnabled=false` 导致 `DynamicApiMiddleware` 跳过 CloudSync 请求 → `/auth/*` `/tasks/*` `/security/*` `/admin/*` `/cloud-sync/*` 全部 404
|
||
- **修复**：
|
||
1. `DynamicApiSwaggerDocumentFilter.IsRemoteServiceEnabled` 改为检查 `IsMetadataEnabled`（与 `IsEnabled` 解耦：原 `IsEnabled=false` 的接口 Swagger 仍可见）
|
||
2. 移除 6 个 CloudSync 接口 + `ICloudSyncProxySettingsService` 的 `[RemoteService(IsEnabled=false)]`
|
||
3. MCP 工具改为命名空间过滤：`IsCloudSyncService(type)` 排除 `Hua.Todo.Application.CloudSync.*` 命名空间
|
||
- **验证**：编译 0 错误，161 个测试全部通过
|
||
|
||
---
|
||
|
||
> **更新约定**：每次智能体修改本文件时，必须更新顶部的"进行中版本"和"工单状态快照"两节，确保信息不过时。
|