Hua.Todo/docs/manual/03-版本记录.md

版本更新历史

版本更新

版本策略

• 采用语义化版本号：MAJOR.MINOR.PATCH
• v1.0.0：初始 WPF 版本
• v1.1.0：MAUI + WebView 跨平台版本
• v1.2.0：Linux 支持与增强功能
• v1.3.0（开发中）：MCP 服务与语音控制

v1.3.0 (2026-08-08，Host 双角色+路由+鉴权流修补)

• 修复：根路径 404 / 前端缺失引导：Hua.Todo.Host/Program.cs 新增 MinimalBootstrapPageMiddleware（位于 Swagger 之后、UseDefaultFiles/UseStaticFiles 之前）。当前端 wwwroot/index.html 缺失时，访问 / 或 SPA 路由（如 /settings）不再返回 404，而是返回中文最小引导页（含期望路径、WebRoot、环境版本、三种修复方式：dotnet build Host / 手动 npm build / CI skip build；同时列出 /swagger、/api/auth/bootstrap 等仍可用的入口），解决了"根路径 404 看起来像后端挂了"的误判问题。
• 修复：没权限应该跳登录页：DynamicApiMiddleware 新增 WriteUnauthorizedResponse / WriteForbiddenResponse / IsBrowserHtmlRequest 三个方法。判定规则：请求是 GET/HEAD 且 Accept: text/html 且 非 X-Requested-With: XMLHttpRequest → 视为「用户在地址栏直访问接口页面」→ 返回 302 Location: "/"，回到 Host 前端 SPA，SPA 判断未登录 → 弹出登录/云同步设置 CloudSyncSettingsDialog 完成鉴权。不破坏 axios/fetch：Accept 为 JSON 或非 GET/HEAD 时，继续返回原有的 401/403 JSON（success=false + message）。403 同样走 302 跳转。
• 架构文档对齐（Host 不区分模式 = 双角色统一部署）：更新 01-项目架构.md 模式 B 章节：Host 部署时同时承担 (1) Web 端前端/后端同源部署和 (2) 云同步权威服务端两种职责，不区分"模式"；端点列表扩展为 4 项（/、/api/*、/mcp、/swagger + /admin/*）；明确 401/403 在浏览器页面时 302 跳 / 由 SPA 接管登录；新增中间件顺序硬约束链接。
• 验收测试补齐（ATDD）：新增 test/Hua.Todo.Host.Tests/CloudSync/HostBootstrapAndAuthRedirectTests.cs，覆盖 6 场景：① 无 index.html 时 GET / + AcceptHtml → 200 + 引导页含「前端尚未构建」构建命令；② /settings（SPA 路由）同样 200 引导页；③ 未登录浏览器 GET /api/security/policy（PolicyRead 权限）+ AcceptHtml → 302 /；④ 未登录 AcceptJson 同一接口 → 401 JSON success=false；⑤ PUT /api/security/policy（非 GET）+ AcceptHtml → 仍 401 JSON 不跳转；⑥ 匿名 POST /api/cloud-sync/probe 不被 redirect 或 401 影响。6 个新测试 + 原 WebRootStaticFileTests 4 个场景 = 10 个全部通过。

v1.3.0 (2026-06-17)

• 架构对齐（v1.3.0 工单 05）：新增「Hua.Todo.HttpApi.AspNetCore」中间层到项目清单和依赖图（Core → Application → HttpApi.AspNetCore → {Host,Maui,Avalonia}）；抽离 AddCloudSyncServer 到 CloudSyncServiceCollectionExtensions.cs；清理 01-项目架构.md §5 过时的扩展点路径；00-工单总览.md 明确模式 B 中间件顺序硬约束，MapCloudSyncProxySettings 已废弃（接口改由 DynamicApi 自动暴露）。
• Web 端根路径托管前端（v1.3.0 工单 06）：模式 B 下 Host 同时承担「动态 API + 前端静态站点 + MCP」三大职责；Program.cs 新增 UseDefaultFiles/UseStaticFiles/MapFallbackToFile("index.html") 并对齐中间件顺序；Host.csproj 新增 BuildHuaTodoWebWebRoot Target（增量 npm build + 双份 wwwroot 拷贝 + Node 缺失 Warning）；开发文档新增「模式 B 双开」与「BuildHuaTodoWebWebRoot 自动构建」指南；新增 WebRootStaticFileTests.cs 覆盖根路径 / SPA fallback / API 不覆盖 / Swagger 不覆盖 4 场景。
• CloudSync Swagger + 路由修复：CloudSync 接口改查 IsMetadataEnabled，移除 IsEnabled=false，Swagger 中 /auth/* /tasks/* /security/* /admin/* /cloud-sync/* 可见；MCP 工具改用命名空间过滤 Hua.Todo.Application.CloudSync.*，避免云同步接口暴露为 MCP。
• CloudSync 端点 DynamicApi 化：移除 16 个手动 MapCloudSyncEndpoints()，新增 5 个 IDynamicApiService 接口 + DynamicApiRouteAttribute + RequirePermissionAttribute，中间件支持自定义前缀与权限检查；错误响应统一 401/403。
• 测试项目重构：src/test/ → test/；Host.Tests 161 个测试全部通过。
• Host 云同步端点补齐修复：Program.cs 新增 AddCloudSyncServer() + MapCloudSyncEndpoints()（后已改为 DynamicApi） + app.UseAuthentication() 顺序；前端云同步默认账号 admin/123456 + 默认地址 http://localhost:5173；TaskList.vue 新增登录/登出/同步按钮。

v1.3.0 (2026-06-16)

• MCP 服务：新增 MCP 协议端点（/mcp），DynamicMcpToolExtensions 自动扫描 IDynamicApiService 接口生成 MCP 工具；当前覆盖 ITaskService（9 个）+ IVoiceService（4 个）= 13 个 MCP 工具
• 语音控制核心：新增 Voice 模块（Core 接口、LLM 客户端、双策略意图解析器、指令执行器、AiBreakdownService）；26 个单元测试通过
• 文档重组：docs/manual/ 目录按普通用户/开发者分离重组，新增双入口导航

v1.2.8 (2026-06-14)

• 文档：新增 云同步规则，汇总 Todo 待办项云同步的架构、API 契约、认证鉴权、同步工作流、安全策略与可控落盘等完整规则。

v1.2.8 (2026-04-13)

• 云同步增强：在 Hua.Todo.Application 中深度集成 CloudSync 模块，支持权限验证、安全策略（SecurityPolicy）与任务同步 DTO。
• 动态 API 增强：完善 DynamicApi 逻辑，支持 Swagger 自动过滤与中间件拦截。
• 代码规范同步：强制执行 XML 文档注释与跨平台逻辑分离规范，更新 .trae/rules 规则库。
• 多平台构建优化：优化 Directory.Build.props 与 Directory.Build.targets，精细化控制各平台（Windows/Android/iOS/Linux）的构建开关与依赖。
• 版本号统一：全项目版本号提升至 v1.2.8，同步更新各平台安装包与发布脚本。

v1.2.0（2026-04-07）

• Linux 官方支持：新增 Hua.Todo.Avalonia 项目，正式适配 Linux 平台，同时支持 Windows 和 macOS。
• Avalonia 桌面交互：增加托盘菜单（显示/退出）、关闭隐藏到托盘、Windows 全局热键唤起主窗口、热键配置本地持久化；并对齐 Avalonia 的 appsettings 默认值。
• 关键词检索：主界面增加搜索框，按任务标题实时过滤；采用"命中即显示（含上下文）"策略；支持 Esc 清空；英文大小写不敏感。
• 云同步（基础可用）：新增"云同步设置"弹窗，支持手动配置服务端地址（格式校验 + 保存时可达性/风险提示）；登录成功后拉取云端任务并刷新主界面（v1.2.0 为只读展示）；401/403 时会自动清会话并弹出登录入口。
• MAUI（Windows）内嵌 API 文档：Debug 模式下，内嵌 WebServer 默认提供 Swagger UI（{HostUrl}/swagger）与 OpenAPI JSON（{HostUrl}/swagger/v1/swagger.json），便于本地接口调试。
• Android 启动稳定性修复：在 AndroidManifest 中移除 androidx.startup.InitializationProvider 自动初始化入口，规避 androidx.lifecycle.ProcessLifecycleInitializer 缺失导致的启动崩溃（NoClassDefFoundError）。
• MAUI Android 调试配置修复：在 Hua.Todo.Maui.csproj 中显式启用 AndroidApplication，并将调试架构配置从 AndroidSupportedAbis 切换为 RuntimeIdentifiers=android-x64，减少 Visual Studio 启动 Android 调试时的项目识别与模拟器架构问题。
• Swagger 输出补齐 Dynamic API：任务管理等 Dynamic API 端点会出现在 swagger.json 中，避免"接口缺失"导致联调困难。
• SQLite DateTime 兼容修复：新增 LenientUtcDateTimeStringConverter，本地数据库中若存在历史遗留的 DateTime "ticks/时间戳字符串"脏数据，读取时将被兼容解析，避免 /api/task 等查询因单条坏数据整体失败。
• SPA 路由回落行为修复：当 Release/非 Debug 未启用 Swagger 时，/swagger 不再被当作"后端专用路径"排除，访问会按 SPA 路由规则回落到 /index.html，避免直接 404。
• MAUI 多平台构建开关：在 Windows 开发机上默认仅构建 Android + Windows 目标，避免 iOS/MacCatalyst 目标在非 macOS 环境触发运行时包缺失（NETSDK1082）；在 macOS 上仍会包含 iOS/MacCatalyst 目标。
• 发布脚本整理：拆分/对齐各平台发布入口，新增 publish.ps1 作为统一入口（默认发布 Windows + Linux），Windows 发布脚本支持开关打包与版本自增，发布产物会落盘到 artifacts/。
• Windows 发布打包修复：Inno Setup 安装包文件名带版本号（Hua.Todo_Setup_vX.Y.Z.exe）；安装后快捷方式/启动项指向 Hua.Todo.Maui.exe；发布产物强制 IsUsingStatic=true。
• Windows WebView2 数据目录调整：MAUI（Unpackaged）默认会在安装目录生成 Hua.Todo.Maui.exe.WebView2；现改为写入 %LocalAppData%\Hua.Todo\WebView2，避免污染安装目录。
• Windows WebView2 Runtime 误判修复：当系统已安装 WebView2 Runtime 但发布产物缺少/裁剪 WebView2 托管程序集时，旧检测逻辑会误判为"未安装"；现改为优先从常见安装目录探测 Evergreen 版本，避免阻断主界面加载。
• Windows 三件套开发体验：新增 start-host.ps1 / start-dev.ps1，并在 MAUI 中约定 IsUsingStatic=false 时不启动内置 WebServer，避免注入覆盖 Vite 的 /api -> 5173 代理配置。
• 文档与部署指南：新增部署文档，详细说明开发环境搭建、多平台发布流程（Windows/Linux/Docker）以及关键配置项。

v1.1.1 (2026-04-06)

• 文档规范增强：新增文档同步规则，强制代码变更与文档更新保持同步。
• 项目结构说明校准：修正 README.md 和技术文档中对 Hua.Todo.Host、Hua.Todo.Application 等模块的路径与职责描述。
• 端口配置校准：修正文档中关于前端与后端 API 的端口说明（5173/5174）。
• PRD 校准：移除 v1.2.0 PRD 中"本地迭代不支持"表述与"数据迁移（导入/导出）"小节。
• PRD 校准：移除 v1.2.0 PRD 中"云同步"需求。

v1.1.0 更新内容

• 重构为 MAUI + WebView 架构
• 实现跨平台支持 (Windows, macOS, Android, iOS)
• 使用 HTTP API 进行前后端通信
• 采用 Vue.js 3 作为前端框架
• 使用 SQLite 作为本地数据库
• 实现子任务支持

v1.0.0 初始版本

• 初始 WPF 版本。