Hua.Todo/.trae/rules/项目/04-即时状态记忆.md

即时状态记忆（Hua.Todo 专属）

适用范围：本规则属于 项目规则（仅 Hua.Todo 项目生效）。

本文档保存"当前实现到哪一步、未完结事项、临时决策"等短期快照，用于跨会话/跨智能体快速对齐。 与 .trae/memory/ 的差别：memory 偏长期沉淀，此处偏即时状态，更新频率高。

维护要求：智能体每完成一个研发工单或观察到状态变化时，必须更新本文件的对应章节。

---

一、当前活跃版本

• 进行中版本：v1.2.0（收尾中）、v1.3.0（规划中）
• v1.2.0 研发工单总览：docs/project/研发工单-v1.2.0/00-工单总览.md
• v1.3.0 研发工单总览：docs/project/研发工单-v1.3.0/00-工单总览.md
• PRD：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	已完成	待验证
04	富文本描述、附件与外部链接	已完成	待验证

四、关键临时决策

• 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 部分仍为"待验证"）

• CloudSync UNIQUE 约束修复（2026-06-14）：修复了 existingTasks 查询在事务外导致并发重同步时 T_Tasks.Id UNIQUE 约束冲突；新增 7 个测试（含 5 个 SQLite 集成测试）

• v1.3.0 工单01 - MCP 服务转换已完成（2026-06-16）：DynamicMcpToolExtensions 自动扫描所有 IDynamicApiService 接口并生成 MCP 工具；当前覆盖 ITaskService（9 个工具）+ IVoiceService（4 个工具）= 13 个 MCP 工具；新增 4 个测试（描述验证、InputSchema 验证、服务调用、工具调用端到端），共计 17 个测试全部通过；CloudSync 服务因未实现 IDynamicApiService 暂未覆盖，记录为已知缺口

• 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 错误

• 测试项目重构（2026-06-17）：原 src/Hua.Todo.Tests 拆分为三个宿主对应测试项目，放入 src/test/ 目录：Hua.Todo.Host.Tests（后端服务测试，144 个用例全过）、Hua.Todo.Maui.Tests（骨架）、Hua.Todo.Avalonia.Tests（骨架）；更新 .slnx 与 docs 引用

• EF Core 迁移合并（2026-06-17）：10 个历史迁移合并为单一 20260616203619_InitialCreate，Migrations 目录从 21 个文件减至 3 个；DatabaseMigrationTests 断言同步更新；157 个测试全部通过

• 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 个测试 全部通过

• 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 个测试全部通过

• 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 个测试全部通过

---

更新约定：每次智能体修改本文件时，必须更新顶部的"进行中版本"和"工单状态快照"两节，确保信息不过时。