From d81aa06681d233a09ae22979f3b38ba28df23ed1 Mon Sep 17 00:00:00 2001 From: ShaoHua <345265198@qqcom> Date: Sun, 14 Jun 2026 00:58:26 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E9=87=8D=E6=9E=84=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E7=BB=93=E6=9E=84=E4=B8=8E=E7=8E=AF=E5=A2=83=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=EF=BC=8C=E7=BB=9F=E4=B8=80=E7=A0=94=E5=8F=91=E5=B7=A5?= =?UTF-8?q?=E5=8D=95=E5=91=BD=E5=90=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. 更新 .env 配置文件，替换原有云同步变量为 API 目标配置 2. 调整 publish-linux.ps1 中的文档路径，使用研发工单目录 3. 重构项目文档目录：将原 v1.2.0-tasks 迁移为研发工单-v1.2.0 目录，统一术语为"研发工单"替代"任务" 4. 更新 README.md 与各 PRD 文档的术语对照表，明确业务实体与研发工作项的区分 5. 新增多个研发工单文档，覆盖搜索、云同步、Linux 打包等模块 6. 删除旧的任务拆分文档，统一使用新的研发工单体系 --- README.md | 25 +++++++++++--- docs/project/产品需求文档-1.1.0.md | 9 +++++ docs/project/产品需求文档-1.2.0.md | 9 +++++ docs/project/产品需求文档.md | 9 +++++ .../00-工单总览.md} | 34 ++++++++++--------- .../01-Linux-Avalonia入口与WebView.md | 12 +++---- .../02-Linux-打包与交付.md | 9 +++-- .../02.1-版本统一与打包方案.md | 0 .../03-Search-关键词检索.md | 19 ++++++----- .../04-CloudSync-服务端基础能力.md | 26 +++++++------- .../05-CloudSync-客户端配置与工作流.md | 23 +++++++------ .../06-CloudSync-安全与可控落盘.md | 27 ++++++++------- .../06.1-CloudSync-服务端安全设计方案.md | 33 +++++++++--------- .../07-文档同步与验收清单.md | 9 ++--- .../08-cloud_sync_refactor_plan.md | 18 +++++----- publish-linux.ps1 | 4 +-- src/Hua.Todo.Web/.env.maui | 4 +-- src/Hua.Todo.Web/.env.production | 4 +-- 18 files changed, 162 insertions(+), 112 deletions(-) rename docs/project/{v1.2.0-tasks/00-任务总览.md => 研发工单-v1.2.0/00-工单总览.md} (59%) rename docs/project/{v1.2.0-tasks => 研发工单-v1.2.0}/01-Linux-Avalonia入口与WebView.md (89%) rename docs/project/{v1.2.0-tasks => 研发工单-v1.2.0}/02-Linux-打包与交付.md (81%) rename docs/project/{v1.2.0-tasks => 研发工单-v1.2.0}/02.1-版本统一与打包方案.md (100%) rename docs/project/{v1.2.0-tasks => 研发工单-v1.2.0}/03-Search-关键词检索.md (55%) rename docs/project/{v1.2.0-tasks => 研发工单-v1.2.0}/04-CloudSync-服务端基础能力.md (79%) rename docs/project/{v1.2.0-tasks => 研发工单-v1.2.0}/05-CloudSync-客户端配置与工作流.md (64%) rename docs/project/{v1.2.0-tasks => 研发工单-v1.2.0}/06-CloudSync-安全与可控落盘.md (63%) rename docs/project/{v1.2.0-tasks => 研发工单-v1.2.0}/06.1-CloudSync-服务端安全设计方案.md (79%) rename docs/project/{v1.2.0-tasks => 研发工单-v1.2.0}/07-文档同步与验收清单.md (82%) rename docs/project/{v1.2.0-tasks => 研发工单-v1.2.0}/08-cloud_sync_refactor_plan.md (95%) diff --git a/README.md b/README.md index d772715..efeedc9 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,17 @@ ### 核心功能 - **跨平台支持**：基于 MAUI + Avalonia + WebView 架构，覆盖 Windows、macOS、Android、iOS 和 Linux 五大平台 - **任务管理**：支持任务创建、编辑、删除、完成状态切换，以及子任务管理 -- **云同步 (CloudSync)**：支持手动配置服务端地址并登录后拉取云端任务，支持安全策略配置 +- **任务排序**：支持按创建时间、完成时间、优先级排序，可切换升序/降序 +- **云同步 (CloudSync)**：支持手动配置服务端地址并登录后拉取/推送云端任务，支持安全策略配置（内存模式、同步开关、二次认证、受信任设备限制） +- **用户管理与权限**：支持多用户管理、RBAC 细粒度权限控制（6 个权限点）、管理员密码加盐存储、首次登录强制修改密码 +- **审计日志**：记录所有安全事件（登录/注销/密码修改/引导等），支持管理员查询 +- **会话管理**：Bearer Token 认证，支持二次认证（step-up）提升权限，Token 即时失效 - **关键词检索**：支持按任务标题实时过滤，支持 Esc 清空，大小写不敏感 -- **本地数据持久化**：使用 SQLite 数据库保存数据，支持 DateTime 兼容性解析 +- **本地数据持久化**：使用 SQLite 数据库保存数据（WAL 模式优化），支持 DateTime 兼容性解析 +- **离线模式**：支持完全离线使用，数据优先保存于本地；安全策略禁止时可切换为内存模式不落盘 - **动态 API**：后端自动生成 RESTful API 并集成 Swagger UI，便于联调与调试 -- **全局快捷键**：支持系统级快捷键快速唤起应用 +- **全局快捷键**：支持系统级快捷键快速唤起应用，修饰键与主键均可配置 +- **系统托盘**：支持最小化到系统托盘，关闭窗口隐藏到托盘，托盘菜单快捷操作 ## 📦 安装与使用 @@ -134,11 +140,22 @@ Hua.Todo/ |------|------|------| | POST | `/auth/bootstrap` | 初始化管理员（仅首次） | | POST | `/auth/login` | 用户登录 | +| POST | `/auth/logout` | 用户注销 | | POST | `/auth/step-up` | 二次验证（提升权限） | +| POST | `/auth/change-password` | 修改密码 | | GET | `/tasks/` | 获取云端任务（只读） | | POST | `/sync/` | 推送/拉取合并同步 | | GET | `/security/policy` | 获取安全策略 | | PUT | `/security/policy` | 更新安全策略 | +| POST | `/cloud-sync/probe` | 服务端可达性探测 | +| GET | `/admin/users` | 获取用户列表 | +| POST | `/admin/users` | 创建用户 | +| POST | `/admin/users/{userId}/reset-password` | 重置用户密码 | +| DELETE | `/admin/users/{userId}` | 删除用户 | +| GET | `/admin/sessions` | 获取活跃会话列表 | +| DELETE | `/admin/sessions/{sessionId}` | 强制终止会话 | +| GET | `/admin/audit-logs` | 获取审计日志 | +| GET | `/admin` | 管理后台入口 | ## 📊 模块说明 @@ -171,7 +188,7 @@ Hua.Todo/ ### 项目进度与需求 - [产品需求文档](docs/project/产品需求文档.md) -- [v1.2.0 任务清单](docs/project/v1.2.0-tasks/00-任务总览.md) +- [v1.2.0 研发工单总览](docs/project/研发工单-v1.2.0/00-工单总览.md) - [实现对比文档](docs/project/实现对比文档.md) --- diff --git a/docs/project/产品需求文档-1.1.0.md b/docs/project/产品需求文档-1.1.0.md index 3263e7e..18774a3 100644 --- a/docs/project/产品需求文档-1.1.0.md +++ b/docs/project/产品需求文档-1.1.0.md @@ -1,5 +1,14 @@ # Hua.Todo 产品需求文档 (PRD) v1.1.0 +> **术语对照（必读）** +> +> | 术语 | 含义 | 出现位置 | +> |---|---|---| +> | **Todo 待办项 / 任务 / 子任务（业务实体）** | 用户在 Hua.Todo 应用中创建的待办事项，对应代码 `Task` / `SubTask` 实体、`/api/task` 接口、UI 列表项 | 本文及 `docs/manual/`、业务代码 | +> | **研发工单（Dev Work Item）** | 智能体 / 开发者执行的编码工作项（需求拆分、并行开发） | `docs/project/研发工单-*/`、`.trae/rules/全局/05-研发工单规则.md` | +> +> 本文中"任务/子任务"统一指业务实体；如涉及编码侧拆分请使用"研发工单"。 + ## 1. 项目概述 本项目是一个基于 MAUI + WebView 架构开发的跨平台代办管理应用 (Hua.Todo)。旨在提供轻量、高效的任务管理体验，特别是通过快捷键快速唤起记录功能，最大化用户的操作效率。v1.1.0 版本将实现跨平台支持，覆盖 Windows、macOS、Android、iOS 和 Linux（预览）平台。 diff --git a/docs/project/产品需求文档-1.2.0.md b/docs/project/产品需求文档-1.2.0.md index cedd8ec..8c3022f 100644 --- a/docs/project/产品需求文档-1.2.0.md +++ b/docs/project/产品需求文档-1.2.0.md @@ -1,5 +1,14 @@ # Hua.Todo 产品需求文档 (PRD) v1.2.0 +> **术语对照（必读）** +> +> | 术语 | 含义 | 出现位置 | +> |---|---|---| +> | **Todo 待办项 / 任务 / 子任务（业务实体）** | 用户在 Hua.Todo 应用中创建的待办事项，对应代码 `Task` / `SubTask` 实体、`/api/task` 接口、UI 列表项 | 本文及 `docs/manual/`、业务代码 | +> | **研发工单（Dev Work Item）** | 智能体 / 开发者执行的编码工作项（需求拆分、并行开发） | `docs/project/研发工单-*/`、`.trae/rules/全局/05-研发工单规则.md` | +> +> 本文中"任务/子任务"统一指业务实体；如涉及编码侧拆分请使用"研发工单"。 + ## 1. 项目概述 在 v1.1.0 版本成功实现 MAUI + WebView 跨平台架构的基础上，v1.2.0 版本将以“**MAUI 入口保持不动 + Linux 新增 Avalonia 入口**”的方式落地 Linux 支持（继续使用 WebView 承载 Vue 前端），并在此基础上探索 Avalonia 对其他终端的支持情况；若验证效果良好，后续版本将推进各终端入口统一切换到 Avalonia。 diff --git a/docs/project/产品需求文档.md b/docs/project/产品需求文档.md index 1439a9a..73d8dee 100644 --- a/docs/project/产品需求文档.md +++ b/docs/project/产品需求文档.md @@ -1,5 +1,14 @@ # Hua.Todo 产品需求文档 (PRD) +> **术语对照（必读）** +> +> | 术语 | 含义 | 出现位置 | +> |---|---|---| +> | **Todo 待办项 / 任务 / 子任务（业务实体）** | 用户在 Hua.Todo 应用中创建的待办事项，对应代码 `Task` / `SubTask` 实体、`/api/task` 接口、UI 列表项 | 本文及 `docs/manual/`、业务代码 | +> | **研发工单（Dev Work Item）** | 智能体 / 开发者执行的编码工作项（需求拆分、并行开发） | `docs/project/研发工单-*/`、`.trae/rules/全局/05-研发工单规则.md` | +> +> 本文中"任务/子任务"统一指业务实体；如涉及编码侧拆分请使用"研发工单"。 + ## 1. 项目概述 本项目是一个基于 C# WPF (.NET 10) 开发的桌面代办管理应用 (Hua.Todo)。旨在提供轻量、高效的任务管理体验，特别是通过快捷键快速唤起记录功能，最大化用户的操作效率。 diff --git a/docs/project/v1.2.0-tasks/00-任务总览.md b/docs/project/研发工单-v1.2.0/00-工单总览.md similarity index 59% rename from docs/project/v1.2.0-tasks/00-任务总览.md rename to docs/project/研发工单-v1.2.0/00-工单总览.md index 6dda33e..9a4b9b9 100644 --- a/docs/project/v1.2.0-tasks/00-任务总览.md +++ b/docs/project/研发工单-v1.2.0/00-工单总览.md @@ -1,49 +1,51 @@ -# Hua.Todo v1.2.0 任务拆分总览 +# Hua.Todo v1.2.0 研发工单总览 -本目录用于把 [产品需求文档-1.2.0.md](file:///d:/Proj/6.Hua.Todo/docs/project/产品需求文档-1.2.0.md) 拆解为可落地、可并行推进的子任务。各任务文件之间尽量解耦；存在明确依赖时会在任务内标注。 +> 术语澄清：本目录下"工单 / 子工单 / 研发工单"指**编码工作项**；文中提到的"任务/任务列表/任务标题/父子任务/拉取任务/同步任务"等指 Hua.Todo 项目业务领域的 **Todo 待办项**（Task 实体），二者请勿混淆。详见 `.trae/rules/全局/05-研发工单规则.md`。 + +本目录用于把 [产品需求文档-1.2.0.md](file:///d:/Proj/6.Hua.Todo/docs/project/产品需求文档-1.2.0.md) 拆解为可落地、可并行推进的子工单。各工单文件之间尽量解耦；存在明确依赖时会在工单内标注。 ## 目标（来自 PRD） -- Linux 平台官方支持：MAUI 入口保持不动，Linux 新增 Avalonia 入口；继续用 WebView 承载同一套 Vue 前端；复用既有“本地 API ↔ 前端”的交互协议 -- 任务检索（Search）：主界面顶部新增搜索框，按任务标题模糊匹配 -- 云同步（基础可用）：用户手动配置服务端地址；RBAC + 二次认证；用户级数据隔离；服务端配置驱动的“可控落盘” +- Linux 平台官方支持：MAUI 入口保持不动，Linux 新增 Avalonia 入口；继续用 WebView 承载同一套 Vue 前端；复用既有"本地 API ↔ 前端"的交互协议 +- Todo 待办项检索（Search）：主界面顶部新增搜索框，按 Todo 待办项标题模糊匹配 +- 云同步（基础可用）：用户手动配置服务端地址；RBAC + 二次认证；用户级数据隔离；服务端配置驱动的"可控落盘" -## 当前实现基线（用于任务定位） +## 当前实现基线（用于工单定位） - MAUI 启动与内嵌 WebServer：`src/Hua.Todo.Maui` - 前端（Vue）与 API client：`src/Hua.Todo.Web` - 后端宿主（ASP.NET，动态 API）：`src/Hua.Todo.Host` + `src/Hua.Todo.Application/DynamicApi` - 现有 WebView ↔ 前端注入协议（示例）：`window.__API_BASE_URL__`、`window.mauiInterop`（用于 JS 侧拿到 API base 与若干事件桥接） -## 任务流（并行建议） +## 工单流（并行建议） - **Linux 入口线**：`01-*` + `02-*` - 01：新增 Avalonia 入口、选择 Linux 可用的 WebView 控件、复用现有前后端协议 - 02：Linux 打包/交付产物（已落地：`.tar.gz` 发布脚本 + Flatpak 基础结构；详见 `publish-linux.ps1` 与 `pack/linux/`） - **Search 线**：`03-*` - 主要在前端完成；与云同步/平台入口基本无耦合，可并行 - - 03：已完成：主界面搜索框（按标题包含匹配；命中即显示含上下文；Esc 清空；英文大小写不敏感） + - 03：已完成：主界面搜索框（按 Todo 待办项标题包含匹配；命中即显示含上下文；Esc 清空；英文大小写不敏感） - **云同步线**：`04-*` + `05-*` + `06-*` - - 04：服务端基础能力（登录、任务同步/读取、配置下发、用户隔离） - - 05：客户端配置与同步工作流（手动指定服务端地址、登录后拉取任务） - - 06：安全与落盘策略（RBAC、二次认证、可控落盘与“内存模式”） + - 04：服务端基础能力（登录、Todo 数据同步/读取、配置下发、用户隔离） + - 05：客户端配置与同步工作流（手动指定服务端地址、登录后拉取 Todo 数据） + - 06：安全与落盘策略（RBAC、二次认证、可控落盘与"内存模式"） - **文档与验收线**：`07-*` - 对齐文档与现实现状/接口；补齐验收步骤与自测清单 ## 待验证表 -| 子任务 | 实现状态 | 验证状态 | 备注 | +| 子工单 | 实现状态 | 验证状态 | 备注 | |---|---|---|---| | 01 - Linux 入口 | 已完成 | 待验证 | 基于 Avalonia + WebView.Avalonia 实现 | | 02 - Linux 打包/交付 | 已落地 | 待验证 | `.tar.gz` 发布脚本 + Flatpak 基础结构 | -| 03 - Search 关键词检索 | 已完成 | 待验证 | 搜索框 + 树状任务标题包含匹配 | +| 03 - Search 关键词检索 | 已完成 | 待验证 | 搜索框 + 树状 Todo 待办项标题包含匹配 | | 04 - 云同步 服务端基础能力 | 已完成 | 已验证 | API 契约与错误码已固化到 04 文档 | -| 05 - 云同步 客户端配置与同步 | 已完成 | 待验证 | 新增“云同步设置”弹窗：地址校验+保存探测、登录/登出、登录后拉取云端任务并在主界面只读展示 | +| 05 - 云同步 客户端配置与同步 | 已完成 | 待验证 | 新增"云同步设置"弹窗：地址校验+保存探测、登录/登出、登录后拉取云端 Todo 数据并在主界面只读展示 | | 06 - 安全与落盘策略 | 未标注 | 待验证 | | | 07 - 文档与验收 | 未标注 | 待验证 | | ## 交付判定（v1.2.0 Done Definition） - Linux：在基线发行版（建议 Ubuntu LTS）上可启动、可渲染前端、可调用本地 API；且有可安装/可运行的交付产物 -- Search：可在主界面按标题实时过滤任务（含层级任务的展示策略清晰） -- 云同步（基础可用）：可配置服务端地址；登录后可拉取该用户任务；服务端可下发“是否允许落盘”；客户端在禁止落盘时不产生本地持久化 +- Search：可在主界面按 Todo 待办项标题实时过滤（含层级 Todo 的展示策略清晰） +- 云同步（基础可用）：可配置服务端地址；登录后可拉取该用户的 Todo 数据；服务端可下发"是否允许落盘"；客户端在禁止落盘时不产生本地持久化 diff --git a/docs/project/v1.2.0-tasks/01-Linux-Avalonia入口与WebView.md b/docs/project/研发工单-v1.2.0/01-Linux-Avalonia入口与WebView.md similarity index 89% rename from docs/project/v1.2.0-tasks/01-Linux-Avalonia入口与WebView.md rename to docs/project/研发工单-v1.2.0/01-Linux-Avalonia入口与WebView.md index 9124b1b..fc83fb0 100644 --- a/docs/project/v1.2.0-tasks/01-Linux-Avalonia入口与WebView.md +++ b/docs/project/研发工单-v1.2.0/01-Linux-Avalonia入口与WebView.md @@ -4,7 +4,7 @@ - 新增一个 **Linux 桌面端入口**（Avalonia）作为 Hua.Todo 的 Linux 宿主 - 在 Linux 宿主中用 **WebView** 加载同一套 Vue 前端（与 MAUI 端共用前端构建产物与资源路径约定） -- 复用既有“前端 ↔ 本地 API”的交互方式（HTTP API + 现有注入变量/事件名），保证前端无需为 Linux 分叉 +- 复用既有"前端 ↔ 本地 API"的交互方式（HTTP API + 现有注入变量/事件名），保证前端无需为 Linux 分叉 ## 范围 @@ -16,7 +16,7 @@ ## 依赖 -- 依赖 `04-*`/`05-*` 的云同步工作不强依赖本任务，可并行 +- 依赖 `04-*`/`05-*` 的云同步工作不强依赖本工单，可并行 - 依赖前端已有构建产物或构建流程（至少能得到 `dist/` 或等效 `wwwroot/`） ## 关键决策点（必须在实现前落定） @@ -30,7 +30,7 @@ 选型必须满足的最低能力： - 基础导航与本地资源加载 - JS 执行/注入（用于对齐 `window.__API_BASE_URL__` 等契约） -- JS ↔ Native 双向通信（至少开发阶段可观测；可先只保证“HTTP API”路径通） +- JS ↔ Native 双向通信（至少开发阶段可观测；可先只保证"HTTP API"路径通） - 开发期可用 DevTools（至少能定位网络请求与控制台错误） ### 2) 资源加载策略（与 MAUI 对齐） @@ -75,12 +75,12 @@ - 提供 App/Window/MainView 基础结构 2. 接入 WebView 控件并完成最小加载闭环 - 能显示 `index.html`，能打开前端路由 -3. 对齐与 MAUI 端一致的“前端契约” +3. 对齐与 MAUI 端一致的"前端契约" - 注入 `window.__API_BASE_URL__`（值应为 `${BaseUrl}/api`） - 若沿用 `window.mauiInterop` 事件名，需在 Linux 端同名注入（建议命名逐步抽象为更通用的 `nativeInterop`，但 v1.2.0 以兼容为优先） 4. 复用本地 API（内嵌 WebServer） - 评估复用 `Hua.Todo.Host`/现有 Kestrel 组件的可能性 - - 明确 Linux 端是否也走“内嵌 WebServer + WebView 指向 BaseUrl”的方式（推荐一致化，减少前端差异） + - 明确 Linux 端是否也走"内嵌 WebServer + WebView 指向 BaseUrl"的方式（推荐一致化，减少前端差异） 5. 输入法/字体/DPI 验证与可配置化 - 至少验证：中文输入法、缩放、Wayland/X11 下可用性 @@ -88,6 +88,6 @@ - 在 Linux（建议 Ubuntu LTS）上启动 Avalonia 入口后： - WebView 正常渲染前端主界面 - - 前端能通过 `window.__API_BASE_URL__` 正确请求本地 `/api/*`（至少任务列表接口可用） + - 前端能通过 `window.__API_BASE_URL__` 正确请求本地 `/api/*`（至少 Todo 待办项列表接口可用） - 页面路由/刷新不会出现 404（SPA fallback 生效） - 开发态可调试（至少能看到控制台/网络错误，或能通过日志定位） diff --git a/docs/project/v1.2.0-tasks/02-Linux-打包与交付.md b/docs/project/研发工单-v1.2.0/02-Linux-打包与交付.md similarity index 81% rename from docs/project/v1.2.0-tasks/02-Linux-打包与交付.md rename to docs/project/研发工单-v1.2.0/02-Linux-打包与交付.md index 45d7de8..4db3de7 100644 --- a/docs/project/v1.2.0-tasks/02-Linux-打包与交付.md +++ b/docs/project/研发工单-v1.2.0/02-Linux-打包与交付.md @@ -2,7 +2,7 @@ ## 目标 -- 为 Linux 提供可安装/可分发的交付产物，并尽量做到“用户机器无需手动补大量依赖即可运行” +- 为 Linux 提供可安装/可分发的交付产物，并尽量做到"用户机器无需手动补大量依赖即可运行" - 明确最低支持发行版范围（建议 Ubuntu LTS 作为基线）与依赖策略（WebView 运行时/字体/输入法等） ## 范围 @@ -17,7 +17,7 @@ ## 交付形式（PRD 约束） -- 优先提供一种“自包含”官方安装方式（AppImage/Flatpak 二选一，建议先做一条跑通） +- 优先提供一种"自包含"官方安装方式（AppImage/Flatpak 二选一，建议先做一条跑通） - 同时保留 `.deb` 或 `.tar.gz` 作为补充分发形式（以脚本产出为准） ## 实施步骤（建议） @@ -25,7 +25,7 @@ 1. 确定 Linux 发行版基线与运行时依赖清单 - 记录：最低 glibc、Wayland/X11、WebView 运行时依赖、字体包 2. 选择并落地一种自包含交付形式 - - AppImage：偏“拎包即用”，对依赖捆绑要求高 + - AppImage：偏"拎包即用"，对依赖捆绑要求高 - Flatpak：沙盒与运行时生态更成熟，但需要 manifest 与权限策略 3. 补充 `.deb` 或 `.tar.gz` - `.deb`：适合 Ubuntu/Debian 系；需要 desktop entry、图标、依赖声明 @@ -35,7 +35,6 @@ ## 验收标准 -- 产物可在“干净环境”（尽量接近用户机）安装/运行 +- 产物可在"干净环境"（尽量接近用户机）安装/运行 - 启动后 WebView 能渲染前端，且本地 API 可用 - 文档中给出的安装/运行步骤可复现，且与产物一致 - diff --git a/docs/project/v1.2.0-tasks/02.1-版本统一与打包方案.md b/docs/project/研发工单-v1.2.0/02.1-版本统一与打包方案.md similarity index 100% rename from docs/project/v1.2.0-tasks/02.1-版本统一与打包方案.md rename to docs/project/研发工单-v1.2.0/02.1-版本统一与打包方案.md diff --git a/docs/project/v1.2.0-tasks/03-Search-关键词检索.md b/docs/project/研发工单-v1.2.0/03-Search-关键词检索.md similarity index 55% rename from docs/project/v1.2.0-tasks/03-Search-关键词检索.md rename to docs/project/研发工单-v1.2.0/03-Search-关键词检索.md index 4f8d4a0..168a0d9 100644 --- a/docs/project/v1.2.0-tasks/03-Search-关键词检索.md +++ b/docs/project/研发工单-v1.2.0/03-Search-关键词检索.md @@ -1,15 +1,17 @@ -# 03 - Search：任务标题关键词检索 +# 03 - Search：Todo 待办项标题关键词检索 + +> 术语：本工单所指"Todo 待办项 / 任务标题 / 父子任务"为业务实体（Task / SubTask）；"工单"指本研发工单本身。 ## 目标 - 在主界面顶部增加搜索框 -- 支持按任务标题进行模糊匹配（实时过滤） +- 支持按 Todo 待办项标题进行模糊匹配（实时过滤） ## 范围 - 前端 UI：输入框、清空按钮、键盘交互（Esc 清空、Enter 可选） -- 过滤逻辑：对“树状任务”给出明确策略 -- 性能：任务量增大时仍保持可用（至少避免 O(n^2) 的明显退化） +- 过滤逻辑：对"树状 Todo（父子任务）"给出明确策略 +- 性能：Todo 数据量增大时仍保持可用（至少避免 O(n^2) 的明显退化） ## 依赖 @@ -17,15 +19,15 @@ ## 过滤策略（需在实现时确定，并写入实现说明） -树状任务（父子任务）常见两种策略，任选其一并保持一致： +树状 Todo（父子任务）常见两种策略，任选其一并保持一致： 1. **命中即显示（含上下文）** - 任意节点标题命中则显示该节点 - 若子任务命中，可同时显示其祖先链（便于理解层级） 2. **扁平化命中** - - 只显示命中的任务（可能丢失层级语义） + - 只显示命中的 Todo（可能丢失层级语义） -建议优先采用“命中即显示（含上下文）”，用户可更快定位。 +建议优先采用"命中即显示（含上下文）"，用户可更快定位。 ## 实施步骤（建议） @@ -39,7 +41,6 @@ ## 验收标准 -- 输入关键字后，任务列表实时过滤，仅展示命中结果（符合上述策略） +- 输入关键字后，Todo 列表实时过滤，仅展示命中结果（符合上述策略） - 清空后恢复原列表 - 对中英文与大小写的处理行为明确（至少：英文大小写不敏感；中文按包含匹配） - diff --git a/docs/project/v1.2.0-tasks/04-CloudSync-服务端基础能力.md b/docs/project/研发工单-v1.2.0/04-CloudSync-服务端基础能力.md similarity index 79% rename from docs/project/v1.2.0-tasks/04-CloudSync-服务端基础能力.md rename to docs/project/研发工单-v1.2.0/04-CloudSync-服务端基础能力.md index 92a859f..b3bd1e4 100644 --- a/docs/project/v1.2.0-tasks/04-CloudSync-服务端基础能力.md +++ b/docs/project/研发工单-v1.2.0/04-CloudSync-服务端基础能力.md @@ -1,19 +1,21 @@ # 04 - 云同步（基础可用）：服务端基础能力 +> 术语：本工单文件本身归属"研发工单"；文中"任务/Todo 数据"指业务实体（Task / SubTask）。 + ## 目标（PRD 约束） -- 支持用户级任务数据同步/读取（用户隔离） +- 支持用户级 Todo 待办项数据同步/读取（用户隔离） - 提供基于角色/权限的访问控制（RBAC） - 对高风险操作支持二次认证（能力以服务端实现为准） -- 下发“可控落盘”配置（服务端配置驱动） +- 下发"可控落盘"配置（服务端配置驱动） ## 范围（建议最小闭环） - 认证（登录/会话） -- 任务数据 API（按用户隔离） +- Todo 数据 API（按用户隔离） - 配置下发 API（是否允许落盘、终端可信度/会话策略等） -- RBAC 最小落地（至少能区分“允许同步/禁止同步”或“只读/读写”） -- 二次认证最小落地（至少覆盖“启用/关闭同步、切换账号、调整落盘策略”等高风险操作的接口） +- RBAC 最小落地（至少能区分"允许同步/禁止同步"或"只读/读写"） +- 二次认证最小落地（至少覆盖"启用/关闭同步、切换账号、调整落盘策略"等高风险操作的接口） ## 依赖 @@ -53,7 +55,7 @@ v1.2.0 已实现一套最小可用契约（用于 05/06 客户端对接时冻结 - Body：`{ "userName": "admin", "password": "..." }` - 200：`{ accessToken, expiresAtUtc, userId, role, permissions[] }` -- 二次认证（step-up，v1.2.0 最小实现为“复用登录口令进行再认证”）： +- 二次认证（step-up，v1.2.0 最小实现为"复用登录口令进行再认证"）： - `POST /auth/step-up` - Header：`Authorization: Bearer ...` - Body：`{ "password": "..." }` @@ -61,7 +63,7 @@ v1.2.0 已实现一套最小可用契约（用于 05/06 客户端对接时冻结 ### Tasks -- 获取当前用户任务全量： +- 获取当前用户 Todo 待办项全量： - `GET /tasks` - Header：`Authorization: Bearer ...` - 权限：`tasks:read` @@ -120,7 +122,7 @@ v1.2.0 已实现一套最小可用契约（用于 05/06 客户端对接时冻结 ## 关键实现点（建议） -详细实现方案请参考：[06.1-CloudSync-服务端安全设计方案.md](file:///d:/Proj/6.Hua.Todo/docs/project/v1.2.0-tasks/06.1-CloudSync-服务端安全设计方案.md) +详细实现方案请参考：[06.1-CloudSync-服务端安全设计方案.md](file:///d:/Proj/6.Hua.Todo/docs/project/研发工单-v1.2.0/06.1-CloudSync-服务端安全设计方案.md) 1. 用户隔离 - 服务端所有读写必须绑定当前登录用户上下文 @@ -128,20 +130,20 @@ v1.2.0 已实现一套最小可用契约（用于 05/06 客户端对接时冻结 - 定义最小角色：例如 `user`、`admin` - 定义最小权限：例如 `tasks:read`、`tasks:write`、`sync:enable` 3. 二次认证 - - 选择实现方式（示例）：二次口令/一次性验证码（TOTP）/短信（若无能力则先实现“二次口令”） + - 选择实现方式（示例）：二次口令/一次性验证码（TOTP）/短信（若无能力则先实现"二次口令"） - 能力不足时必须返回明确错误，使客户端可提示用户 4. 落盘策略下发 - 支持按用户或按会话/终端下发 - - 默认策略建议为“允许落盘”，便于可用性；但需支持“禁止落盘” + - 默认策略建议为"允许落盘"，便于可用性；但需支持"禁止落盘" ## 验收标准 -- 使用不同用户登录后获取任务，数据严格隔离 +- 使用不同用户登录后获取 Todo 数据，数据严格隔离 - 未授权角色/权限访问受限接口会被拒绝（错误响应可被客户端识别） - 能返回安全策略配置（至少包含 `allowPersist`），并可通过配置切换行为 ## 当前实现说明（v1.2.0） - 数据隔离：`Tasks` 表新增 `UserId` 外键，云端 API 的所有读写按当前会话用户隔离；本地模式使用固定的 `local` 用户 ID（不影响既有 Dynamic API）。 -- RBAC：内置 `admin / user / readonly / nosync` 角色与权限映射；并叠加 `SecurityPolicies.AllowSync` 作为“是否允许同步写入”的策略开关。 +- RBAC：内置 `admin / user / readonly / nosync` 角色与权限映射；并叠加 `SecurityPolicies.AllowSync` 作为"是否允许同步写入"的策略开关。 - 二次认证：通过 `POST /auth/step-up` 将会话提升到 step-up 状态；`POST /sync` 与 `PUT /security/policy` 会强制要求 step-up。 diff --git a/docs/project/v1.2.0-tasks/05-CloudSync-客户端配置与工作流.md b/docs/project/研发工单-v1.2.0/05-CloudSync-客户端配置与工作流.md similarity index 64% rename from docs/project/v1.2.0-tasks/05-CloudSync-客户端配置与工作流.md rename to docs/project/研发工单-v1.2.0/05-CloudSync-客户端配置与工作流.md index d55d52b..592aff6 100644 --- a/docs/project/v1.2.0-tasks/05-CloudSync-客户端配置与工作流.md +++ b/docs/project/研发工单-v1.2.0/05-CloudSync-客户端配置与工作流.md @@ -1,21 +1,23 @@ # 05 - 云同步（基础可用）：客户端配置与同步工作流 +> 术语：本工单文件归属"研发工单"；文中"任务/Todo 数据"指业务实体（Task / SubTask）。 + ## 目标（PRD 约束） - 首次启用同步时，用户需要**手动填写服务端地址**（例如 `https://example.com`），并允许后续在设置中修改 - 客户端对地址格式做基础校验，并在保存时提示可达性/证书异常等风险信息 -- 用户登录成功后，从服务端获取该用户任务并更新到前端展示 +- 用户登录成功后，从服务端获取该用户 Todo 数据并更新到前端展示 ## 范围（建议最小闭环） -- “同步设置”入口与界面（服务端地址、登录、同步开关） +- "同步设置"入口与界面（服务端地址、登录、同步开关） - 地址校验与风险提示 -- 登录后拉取任务并刷新 UI -- 与本地数据的关系（v1.2.0 建议先做到“服务端为准/或本地为准”的单一策略，避免引入复杂冲突解决） +- 登录后拉取 Todo 数据并刷新 UI +- 与本地数据的关系（v1.2.0 建议先做到"服务端为准/或本地为准"的单一策略，避免引入复杂冲突解决） ## 依赖 -- 依赖 `04-*` 提供可用的服务端接口（至少登录 + 获取任务 + 获取安全策略） +- 依赖 `04-*` 提供可用的服务端接口（至少登录 + 获取 Todo 数据 + 获取安全策略） - 与 `03-*`（Search）互不影响，可并行 ## 关键交互与状态 @@ -28,7 +30,7 @@ ## 实施步骤（建议） -1. 增加“同步设置”UI +1. 增加"同步设置"UI - 放置在主界面可发现位置（例如顶部右侧设置按钮/侧边栏） 2. 服务端地址配置 - 基础校验：`https?://`、host 合法性、尾部 `/` 处理规则 @@ -36,13 +38,12 @@ 3. 登录与凭据存储策略（与 `06-*` 协同） - 在允许落盘场景下可持久化 token/会话 - 在禁止落盘场景下仅保留内存会话（退出即失效） -4. 登录后拉取任务 - - 拉取成功后更新前端任务列表 +4. 登录后拉取 Todo 数据 + - 拉取成功后更新前端 Todo 列表 - 拉取失败给出可理解提示，并允许重试 ## 验收标准 - 首次启用同步必须先配置服务端地址；地址非法时不可保存并提示原因 -- 保存地址时能提示“不可达/证书异常”等风险信息（至少能区分：成功、失败、存在风险但可继续） -- 登录后能从服务端拉取任务并展示在主界面 - +- 保存地址时能提示"不可达/证书异常"等风险信息（至少能区分：成功、失败、存在风险但可继续） +- 登录后能从服务端拉取 Todo 数据并展示在主界面 diff --git a/docs/project/v1.2.0-tasks/06-CloudSync-安全与可控落盘.md b/docs/project/研发工单-v1.2.0/06-CloudSync-安全与可控落盘.md similarity index 63% rename from docs/project/v1.2.0-tasks/06-CloudSync-安全与可控落盘.md rename to docs/project/研发工单-v1.2.0/06-CloudSync-安全与可控落盘.md index 1f55e0b..50d8eb7 100644 --- a/docs/project/v1.2.0-tasks/06-CloudSync-安全与可控落盘.md +++ b/docs/project/研发工单-v1.2.0/06-CloudSync-安全与可控落盘.md @@ -1,10 +1,12 @@ -# 06 - 云同步（基础可用）：安全（RBAC/二次认证）与“可控落盘” +# 06 - 云同步（基础可用）：安全（RBAC/二次认证）与"可控落盘" + +> 术语：本工单文件归属"研发工单"；文中"任务/Todo 数据"指业务实体（Task / SubTask）。 ## 目标（PRD 约束） -- 高风险操作支持二次认证（例如启用/关闭同步、切换账号、调整“是否允许落盘”等） -- 客户端读取服务端安全配置，决定任务信息是否允许落盘 -- 当服务端标记“终端不可信/不允许落盘”时，客户端只能在内存中持有任务信息；退出应用后不保留任务数据 +- 高风险操作支持二次认证（例如启用/关闭同步、切换账号、调整"是否允许落盘"等） +- 客户端读取服务端安全配置，决定 Todo 数据是否允许落盘 +- 当服务端标记"终端不可信/不允许落盘"时，客户端只能在内存中持有 Todo 数据；退出应用后不保留 Todo 数据 ## 范围 @@ -19,10 +21,10 @@ ## 关键设计点（v1.2.0 必须明确） -### 1) “落盘”定义与边界 +### 1) "落盘"定义与边界 -需要明确“哪些数据算落盘”，并在禁止落盘时全部避免： -- 任务数据（列表/详情） +需要明确"哪些数据算落盘"，并在禁止落盘时全部避免： +- Todo 数据（列表/详情） - 同步状态（上次同步时间、待同步队列等） - 登录凭据（token/refresh token/会话标识） @@ -38,20 +40,19 @@ ### 3) 二次认证（挑战-响应） -建议采用“服务端驱动”的挑战流程： +建议采用"服务端驱动"的挑战流程： - 客户端发起高风险操作 -- 服务端返回“需要二次认证”的响应（包含 challenge 信息） +- 服务端返回"需要二次认证"的响应（包含 challenge 信息） - 客户端弹出二次认证输入（例如二次口令/一次性验证码） - 客户端携带证明再次提交 -若服务端暂不支持二次认证，也需有“能力探测/降级提示”，避免客户端卡死。 +若服务端暂不支持二次认证，也需有"能力探测/降级提示"，避免客户端卡死。 ## 验收标准 - 服务端返回 `allowPersist=false` 时： - - 客户端不会把任务数据与凭据写入任何持久化介质 - - 退出应用后重新进入，任务数据为空（需重新登录/拉取） + - 客户端不会把 Todo 数据与凭据写入任何持久化介质 + - 退出应用后重新进入，Todo 数据为空（需重新登录/拉取） - 对指定高风险操作： - 无二次认证证明时被拒绝，并提示需要二次认证 - 提供正确二次认证后操作成功 - diff --git a/docs/project/v1.2.0-tasks/06.1-CloudSync-服务端安全设计方案.md b/docs/project/研发工单-v1.2.0/06.1-CloudSync-服务端安全设计方案.md similarity index 79% rename from docs/project/v1.2.0-tasks/06.1-CloudSync-服务端安全设计方案.md rename to docs/project/研发工单-v1.2.0/06.1-CloudSync-服务端安全设计方案.md index 80bd51c..1431d75 100644 --- a/docs/project/v1.2.0-tasks/06.1-CloudSync-服务端安全设计方案.md +++ b/docs/project/研发工单-v1.2.0/06.1-CloudSync-服务端安全设计方案.md @@ -55,7 +55,7 @@ ## 4. 二次认证与会话提升 (Step-up) -针对高风险操作（如 `sync:write`、`policy:write`），要求会话必须处于“提升状态”。 +针对高风险操作（如 `sync:write`、`policy:write`），要求会话必须处于"提升状态"。 ### 流程设计 @@ -69,13 +69,13 @@ ## 5. 安全策略 (Security Policy) 存储与下发 -安全策略决定了客户端的“落盘”行为及二次认证频率。 +安全策略决定了客户端的"落盘"行为及二次认证频率。 ### 策略定义 (SecurityPolicies 表) - `Id`: `int` (主键) - `UserId`: `Guid` (外键) -- `AllowPersist`: `bool` (是否允许客户端持久化任务数据) +- `AllowPersist`: `bool` (是否允许客户端持久化 Todo 数据) - `AllowSync`: `bool` (是否允许该用户同步) - `SecondFactorExpiryMinutes`: `int` (二次认证状态保持时长，默认 30) - `IsTrustedDeviceOnly`: `bool` (是否仅限受信任终端) @@ -101,33 +101,33 @@ ### 8.1 二次认证 (Step-up) 交互流程 -1. **静默拦截**: 当用户触发高风险操作（如点击“立即同步”且 Token 已过期或未提升）时，客户端拦截请求并检测到 `403 SECOND_FACTOR_REQUIRED`。 -2. **弹出对话框**: 弹出“安全验证”模态框。 +1. **静默拦截**: 当用户触发高风险操作（如点击"立即同步"且 Token 已过期或未提升）时，客户端拦截请求并检测到 `403 SECOND_FACTOR_REQUIRED`。 +2. **弹出对话框**: 弹出"安全验证"模态框。 - **标题**: 需要二次认证。 - - **描述**: “为了保护您的数据安全，执行此操作需要验证身份。” + - **描述**: "为了保护您的数据安全，执行此操作需要验证身份。" - **输入**: 密码输入框（或 TOTP 验证码输入框）。 - **操作**: \[取消] \[验证并继续]。 -3. **状态保持**: 验证成功后，UI 应显示短暂的“验证成功”提示，并自动重试刚才被拦截的操作。 +3. **状态保持**: 验证成功后，UI 应显示短暂的"验证成功"提示，并自动重试刚才被拦截的操作。 ### 8.2 客户端 UI (针对普通用户) -在客户端“设置 -> 云同步 -> 安全”路径下： +在客户端"设置 -> 云同步 -> 安全"路径下： - **落盘策略 (AllowPersist)**: - **展示**: 状态开关（Toggle）。 - **交互**: - - 若由服务端强制禁止，开关应为禁用状态（Disabled），并附带说明：“受服务端策略限制，当前终端禁止落盘”。 - - 若允许修改，关闭开关时应弹出强提醒：“关闭后，所有本地任务数据将被立即清除，退出应用后数据将不再保留。确定继续吗？” + - 若由服务端强制禁止，开关应为禁用状态（Disabled），并附带说明："受服务端策略限制，当前终端禁止落盘"。 + - 若允许修改，关闭开关时应弹出强提醒："关闭后，所有本地 Todo 数据将被立即清除，退出应用后数据将不再保留。确定继续吗？" - **二次认证频率**: - **展示**: 显示当前二次认证的有效期（如 30 分钟）。 -### 8.3 “不可落盘”模式下的视觉提示 +### 8.3 "不可落盘"模式下的视觉提示 当 `allowPersist == false` 时： -- **状态栏/标题栏**: 增加“无痕模式”或“内存存储”小图标/文字提醒。 -- **登录页**: 增加提醒：“当前环境配置为禁止落盘，数据仅在本次运行期间有效”。 -- **退出应用**: 点击退出时，若有未同步数据，强提醒：“数据未同步且本地禁止落盘，退出将导致数据丢失。确定退出吗？” +- **状态栏/标题栏**: 增加"无痕模式"或"内存存储"小图标/文字提醒。 +- **登录页**: 增加提醒："当前环境配置为禁止落盘，数据仅在本次运行期间有效"。 +- **退出应用**: 点击退出时，若有未同步数据，强提醒："数据未同步且本地禁止落盘，退出将导致数据丢失。确定退出吗？" *** @@ -146,7 +146,7 @@ ### 9.2 系统初始化 (Bootstrap) - **触发条件**: 当检测到数据库中无任何用户时，访问 `/admin` 自动跳转至 `/admin/bootstrap`。 -- **功能**: 创建首个“超级管理员”账号。 +- **功能**: 创建首个"超级管理员"账号。 - **UI**: 简单的表单（用户名、密码、确认密码）。 ### 9.3 用户管理 (User Management) @@ -169,7 +169,7 @@ ### 9.6 审计日志查看器 (Audit Log Viewer) - **过滤查询**: 按时间、用户、事件类型（登录、同步、策略变更）过滤。 -- **高亮显示**: 对“二次认证失败”、“异常 IP 登录”等敏感事件进行红色高亮。 +- **高亮显示**: 对"二次认证失败"、"异常 IP 登录"等敏感事件进行红色高亮。 *** @@ -178,4 +178,3 @@ - **Token 吊销**: 默认 JWT 是无状态的。若需支持强制下线，需引入 Redis/DB 黑名单。 - **HTTPS**: 所有安全通信必须基于 TLS，防止中间人攻击窃取 Token。 - **暴力破解**: 需在 `POST /auth/login` 接口增加限流（Rate Limiting）机制。 - diff --git a/docs/project/v1.2.0-tasks/07-文档同步与验收清单.md b/docs/project/研发工单-v1.2.0/07-文档同步与验收清单.md similarity index 82% rename from docs/project/v1.2.0-tasks/07-文档同步与验收清单.md rename to docs/project/研发工单-v1.2.0/07-文档同步与验收清单.md index 2527190..89cfab4 100644 --- a/docs/project/v1.2.0-tasks/07-文档同步与验收清单.md +++ b/docs/project/研发工单-v1.2.0/07-文档同步与验收清单.md @@ -1,5 +1,7 @@ # 07 - 文档同步与验收清单（v1.2.0） +> 术语：本工单文件本身归属"研发工单"；文中"任务/Todo 待办项"指业务实体（Task / SubTask）。 + ## 目标 - 保证 v1.2.0 实现后，README 与 docs 中的说明与实际代码一致 @@ -9,7 +11,7 @@ - README：Features、运行方式、API 说明（如涉及） - docs：技术设计文档/技术栈与模块/版本记录（如涉及） -- 本目录任务文件：保持与实现同步（必要时更新验收口径与依赖关系） +- 本目录工单文件：保持与实现同步（必要时更新验收口径与依赖关系） ## 必做同步点（结合当前仓库现状） @@ -23,7 +25,7 @@ ### Linux - [x] Linux 上可启动并打开主界面 - [x] WebView 能渲染 Vue 前端且路由可用（刷新不 404） -- [x] 前端能成功请求本地 `/api/*` 并加载任务列表 +- [x] 前端能成功请求本地 `/api/*` 并加载 Todo 待办项列表 - [x] 有至少一种自包含交付产物（AppImage/Flatpak 二选一）可运行（见 pack/linux/README.md） ### Search @@ -33,7 +35,6 @@ ### 云同步（基础可用） - [x] 可手动配置服务端地址，并有基础校验与风险提示 -- [x] 登录后能拉取该用户任务并展示 +- [x] 登录后能拉取该用户的 Todo 数据并展示 - [x] 服务端策略 `allowPersist=false` 时客户端不落盘，退出后数据不保留 - [x] 高风险操作触发二次认证（服务端支持时） - diff --git a/docs/project/v1.2.0-tasks/08-cloud_sync_refactor_plan.md b/docs/project/研发工单-v1.2.0/08-cloud_sync_refactor_plan.md similarity index 95% rename from docs/project/v1.2.0-tasks/08-cloud_sync_refactor_plan.md rename to docs/project/研发工单-v1.2.0/08-cloud_sync_refactor_plan.md index 405ca2b..7e9d012 100644 --- a/docs/project/v1.2.0-tasks/08-cloud_sync_refactor_plan.md +++ b/docs/project/研发工单-v1.2.0/08-cloud_sync_refactor_plan.md @@ -16,12 +16,12 @@ src/ │ ├── Hua.Todo.Host/ ← ASP.NET 服务端（云同步接口的提供方） │ └── Program.cs -│ ├── AddApplicationServices() ← 任务 CRUD 服务 +│ ├── AddApplicationServices() ← Todo CRUD 服务 │ └── AddCloudSyncServer() ← 云同步认证/授权/端点 **仅服务端** │ └── Hua.Todo.Maui/ ← 桌面/移动客户端（嵌入 WebView） └── MauiProgram.cs - └── AddApplicationServices() ← **仅** 任务 CRUD 服务 + └── AddApplicationServices() ← **仅** Todo CRUD 服务 （不注册 AddCloudSyncServer，不暴露云同步端点） ``` @@ -41,9 +41,9 @@ src/ │ proxy /api │ ├───────────────────────────────┤ │ ASP.NET Host (:5173) │ -│ AddApplicationServices() │ 任务 CRUD +│ AddApplicationServices() │ Todo CRUD │ AddCloudSyncServer() │ 云同步端点 ← **服务端** -│ ├─ /api/* (本地任务) │ +│ ├─ /api/* (本地 Todo) │ │ └─ /auth/* (云同步) │ │ /tasks/* │ │ /cloud-sync/probe (新增) │ @@ -59,19 +59,19 @@ src/ │ │ Vue 前端 (静态托管) │ │ │ │ cloudClient │ │ │ │ baseURL = 同源 │ │ 同源请求 -│ │ → /api/* (本地任务) │──┼───────→ Embedded WebServer +│ │ → /api/* (本地 Todo) │──┼───────→ Embedded WebServer │ │ → /auth/* (❌ 不可用) │ │ (不暴露云同步端点) │ └─────────────────────────┘ │ ├───────────────────────────────┤ │ Embedded WebServer (:5057) │ -│ AddApplicationServices() │ 仅任务 CRUD +│ AddApplicationServices() │ 仅 Todo CRUD │ AddCloudSyncServer() │ ❌ 未注册 -│ UseDynamicApi() │ 仅本地任务 API +│ UseDynamicApi() │ 仅本地 Todo API │ MapCloudSyncEndpoints() │ ❌ 未映射 └───────────────────────────────┘ ``` -> **关键区别**：`Hua.Todo.Application` 被两方引用，但云同步能力**仅在 Host 端通过 `AddCloudSyncServer()` 激活**。MAUI 端只使用 `AddApplicationServices()` 获取任务 CRUD 能力，**不暴露也不应暴露云同步端点**。 +> **关键区别**：`Hua.Todo.Application` 被两方引用，但云同步能力**仅在 Host 端通过 `AddCloudSyncServer()` 激活**。MAUI 端只使用 `AddApplicationServices()` 获取 Todo CRUD 能力，**不暴露也不应暴露云同步端点**。 #### 1.3 核心问题 @@ -272,7 +272,7 @@ server: { |---|---|---| | **用途** | 云同步 API 的 base URL（前端直连） | 仅用于"服务端探测"的目标地址 | | **存储位置** | `localStorage` | 不变（探测时使用） | -| **影响登录/任务拉取** | 是（前端用它做 baseURL） | 否（走 Host 自身端点） | +| **影响登录/Todo 拉取** | 是（前端用它做 baseURL） | 否（走 Host 自身端点） | ### 4. 需要变更的文件清单 diff --git a/publish-linux.ps1 b/publish-linux.ps1 index 0aca511..37e512e 100644 --- a/publish-linux.ps1 +++ b/publish-linux.ps1 @@ -6,7 +6,7 @@ - 在 Windows 开发机上也能交叉发布 linux-x64（便于 CI 前的本地验证） 约束： - - Avalonia Linux 入口项目需先落地（参见 docs/project/v1.2.0-tasks/01-*） + - Avalonia Linux 入口项目需先落地（参见 docs/project/研发工单-v1.2.0/01-*） - 仅打包为 tar.gz；Flatpak/AppImage 需要在 Linux 环境执行相关工具链（参见 pack/linux/ 说明） #> @@ -126,7 +126,7 @@ if ($null -eq $ProjectFile) { Write-Error @" 未找到 Avalonia Linux 入口项目（无法生成 Linux 交付产物）。 -请先完成 docs/project/v1.2.0-tasks/01-Linux-Avalonia入口与WebView.md 对应实现，并确保下列路径之一存在： +请先完成 docs/project/研发工单-v1.2.0/01-Linux-Avalonia入口与WebView.md 对应实现，并确保下列路径之一存在： $candidatesText "@ exit 1 diff --git a/src/Hua.Todo.Web/.env.maui b/src/Hua.Todo.Web/.env.maui index 5136ea6..c28215b 100644 --- a/src/Hua.Todo.Web/.env.maui +++ b/src/Hua.Todo.Web/.env.maui @@ -1,2 +1,2 @@ -# MAUI 构建：云同步远端地址 -VITE_CLOUD_SYNC_URL=https://api.hua-todo.example.com +# MAUI 模式：API 与云同步共用本地后端代理目标 +VITE_API_TARGET=http://localhost:5057 \ No newline at end of file diff --git a/src/Hua.Todo.Web/.env.production b/src/Hua.Todo.Web/.env.production index 555f69f..71b846a 100644 --- a/src/Hua.Todo.Web/.env.production +++ b/src/Hua.Todo.Web/.env.production @@ -1,2 +1,2 @@ -# Production 构建：云同步远端地址（proxy 在 build 时无效，此变量可由其他构建逻辑使用） -VITE_CLOUD_SYNC_URL=https://api.hua-todo.example.com +# Production 模式：API 与云同步共用本地后端代理目标 +VITE_API_TARGET=http://localhost:5173