ShaoHua
3213d4c718
- 重构架构：抽离AddCloudSyncServer到扩展类，补全中间层文档对齐 - 修复根路径404与鉴权跳转：新增中间件处理浏览器请求302跳转 - 实现种子数据初始化：添加默认管理员账号自动创建逻辑 - 优化前端代理与构建：新增Vite代理配置与自动构建Target - 补全测试与文档：新增集成测试，更新开发与部署文档
106 lines
10 KiB
Markdown
106 lines
10 KiB
Markdown
# 研发工单 v1.3.0 - 05：架构文档与代码实际路径对齐
|
||
|
||
> 术语澄清：本文件中"研发工单"指智能体/开发者执行的**编码工作项**，与业务侧的 Todo 待办项无关。详见 [.trae/rules/全局/04-研发工单全流程规范.md](../../../.trae/rules/全局/04-研发工单全流程规范.md)。
|
||
|
||
---
|
||
|
||
## 一、背景与动机
|
||
|
||
在修正「云同步探测 307 → HTTPS 重定向规则」时，重写了 `.trae/rules/项目/01-项目架构.md` §3「两种运行模式」与 §5「关键扩展点」以固化正确链路。但对照代码后发现：**规则文档中的两处描述已与当前代码结构不一致**，会导致后续智能体/开发者按规则路径搜索文件时直接落空，进而引发与本次 307 同类的"链路理解错位 → 改错文件"问题。
|
||
|
||
本工单是纯**工程化对齐工单**（无用户可见的业务功能变更），目标是让 01-项目架构.md 成为"代码的单一事实来源"：要么文档改到与代码一致，要么代码重构到与文档一致，**不允许中间的灰色状态**。
|
||
|
||
## 二、缺口清单（代码 vs 01-项目架构.md 规则）
|
||
|
||
| # | 缺口 | 规则写的内容 | 代码实际情况 | 本工单处理方式 |
|
||
|---|---|---|---|---|
|
||
| A | **§1 项目清单漏列 HttpApi.AspNetCore 层** | Core / Application / Host / Maui / Avalonia / Web 共 6 行 | 存在 `src/Hua.Todo.HttpApi.AspNetCore/`（CloudSync/DynamicApi/Mcp 三层 ASP.NET Core 专属实现），Host 直接引用它 | **规则加表项**：补齐项目条目，注明"承载 ASP.NET Core 专属的 HTTP 层代码（Application 保持 netstandard 兼容）" |
|
||
| B | **§2 依赖方向图缺失 HttpApi.AspNetCore 中间层** | `Application ← { Host, Maui, Avalonia }` 直接三层 | 实际是 `Application ← HttpApi.AspNetCore ← Host`，MAUI/Avalonia 只按需引用 HttpApi.AspNetCore 的部分子模块 | **规则改 ASCII 图**：新增中间层 + 注释跨层引用的边界 |
|
||
| C | **§5 扩展点路径：AddCloudSyncServer 所在文件名错误** | `Hua.Todo.HttpApi.AspNetCore/CloudSync/CloudSyncServiceCollectionExtensions.cs` | 定义在 `CloudSync/Services/CloudSyncServerService.cs` 内（非 *Extensions 命名，与 Mcp / DynamicApi 的命名习惯不一致） | **代码重命名/抽离**：新建 `CloudSyncServiceCollectionExtensions.cs`，把 `AddCloudSyncServer()` 移入；原 `CloudSyncServerService.cs` 仅保留服务实现类 |
|
||
| D | **§5 扩展点路径：MapCloudSyncProxySettings 所在文件缺失** | `Hua.Todo.HttpApi.AspNetCore/CloudSync/CloudSyncEndpointExtensions.cs`（仅保留 `MapCloudSyncProxySettings`） | Grep 显示该方法**仅被 Host Program.cs 调用，定义文件不存在**（即时状态记忆 2026-06-17 条目说"仅保留 MapCloudSyncProxySettings"，但文件未落地） | **代码补齐**：新建 `CloudSyncEndpointExtensions.cs`，写入 `MapCloudSyncProxySettings` 扩展方法（将目前分散的或在旧文件被删除的内容还原），并更新引用命名空间 |
|
||
| E | **§5 扩展点：McpServerMiddleware 实际不存在** | `DynamicMcpToolExtensions.cs + McpServerMiddleware` | 只有 `McpEndpointExtensions.cs`（`MapMcpServer`）+ `McpServiceCollectionExtensions.cs`（`AddMcpServerServices`），无 Middleware 类型 | **规则改路径**：改为 `McpEndpointExtensions.cs` + `McpServiceCollectionExtensions.cs`；不强求新增 Middleware 类型（EndpointRouting 扩展符合 ASP.NET Core 主流模式），只改描述 |
|
||
|
||
## 三、目标 / 范围
|
||
|
||
### 3.1 做什么
|
||
|
||
- 对齐 01-项目架构.md §1/§2/§5 三章共 5 处缺口（A–E，见上表）
|
||
- 代码改动：C（文件抽离+重命名）、D（新建+还原）
|
||
- 文档改动：A、B、E（仅改规则文档，不改代码）
|
||
|
||
### 3.2 不做什么
|
||
|
||
- 不改业务逻辑（不触碰 CloudSyncServerService 内的方法体、不改动 DynamicApiMiddleware 行为）
|
||
- 不改公共 API 契约（AddCloudSyncServer / MapCloudSyncProxySettings 的签名保持不变，仅迁移到新文件）
|
||
- 不做 v1.2.0 工单 10 范围内的工作（DataSeeder）
|
||
|
||
## 四、前置条件 / 依赖
|
||
|
||
- 无；可与 v1.3.0 工单 06、03 并行执行
|
||
- 共享文件：`.trae/rules/项目/01-项目架构.md`（只读，只做局部追加替换；不重排原有章节结构）
|
||
- 共享文件：`Hua.Todo.HttpApi.AspNetCore.csproj`（新增 2 个源文件，C# 编译级冲突风险极低）
|
||
|
||
## 五、验收标准（Given-When-Then）
|
||
|
||
| # | 场景 | GIVEN | WHEN | THEN |
|
||
|---|---|---|---|---|
|
||
| 1 | 缺口 A/B（规则补层） | - | 打开规则文档 §1/§2 | §1 出现 `Hua.Todo.HttpApi.AspNetCore` 表项，描述包含"ASP.NET Core 专属 HTTP 层"；§2 ASCII 图新增中间层，箭头方向正确（单向 Application → HttpApi.AspNetCore → Host） |
|
||
| 2 | 缺口 C（DI 扩展抽离新文件） | `CloudSyncServerService.cs` 当前包含 `AddCloudSyncServer(this IServiceCollection)` | 抽离为 `CloudSyncServiceCollectionExtensions.cs` | 新文件存在且命名空间为 `Hua.Todo.HttpApi.AspNetCore.CloudSync`；`Program.cs` 编译通过无需改 using；旧文件仅保留服务实现（非 static / 非扩展方法）|
|
||
| 3 | 缺口 D（MapCloudSyncProxySettings 新建文件） | `MapCloudSyncProxySettings(this IEndpointRouteBuilder)` 在 Program.cs 被调用但无定义文件 | 创建 `CloudSyncEndpointExtensions.cs` 并补全方法体 | 新文件存在；`Program.cs` 加对应 using 后编译通过；该端点在 Host 启动后响应 `/api/cloud-sync/proxy-settings`（与既有集成测试一致） |
|
||
| 4 | 缺口 E（规则改 Middleware 描述） | §5 写 "McpServerMiddleware" | 将 §5 对应行改为 "McpEndpointExtensions.cs（MapMcpServer 端点） + McpServiceCollectionExtensions.cs（DI 注册）" | 规则路径描述与实际文件一一对应，Grep 两个路径都能找到 |
|
||
| 5 | 回归（全部编译通过） | - | `dotnet build src/Hua.Todo.Host/Hua.Todo.Host.csproj` + `dotnet test test/Hua.Todo.Host.Tests/` 全量 | 0 编译错误；既有测试（含 AddCloudSyncServer DI 注册测试）全部通过，不允许新增失败用例 |
|
||
|
||
## 六、并行冲突规避
|
||
|
||
| Touch List | 共享文件策略 | 编译绿线策略 |
|
||
|---|---|---|
|
||
| `.trae/rules/项目/01-项目架构.md` | 追加/局部替换，**不改 §3 模式 A/B 的正文段落和 §6 版本统一/§7 测试架构**；本工单只动 §1 表、§2 ASCII 图 + 说明、§5 表 | 纯 Markdown，无编译；提交前 diff 确认未改动他人段落 |
|
||
| `Hua.Todo.HttpApi.AspNetCore/CloudSync/CloudSyncServerService.cs` | 只移除 `AddCloudSyncServer` 静态方法块，**不改动类的其他成员**；新文件独立写入，无双向合并 | `dotnet build Hua.Todo.HttpApi.AspNetCore.csproj` 必须 0 错误 |
|
||
| `Hua.Todo.HttpApi.AspNetCore/CloudSync/CloudSyncServiceCollectionExtensions.cs` | 新建；其他并行工单不改同名文件 | 同上 |
|
||
| `Hua.Todo.HttpApi.AspNetCore/CloudSync/CloudSyncEndpointExtensions.cs` | 新建；其他并行工单不改同名文件 | 同上 |
|
||
| `Hua.Todo.Host/Program.cs` | 可能需要追加 `using Hua.Todo.HttpApi.AspNetCore.CloudSync;`（如果原 using 不完整）；不碰其他语句 | `dotnet build Hua.Todo.Host.csproj` 0 错误 |
|
||
|
||
## 七、风险与回滚
|
||
|
||
| 风险 | 影响 | 回滚策略 |
|
||
|---|---|---|
|
||
| C/D 移动方法体时遗漏了 using 或扩展方法的 `this` 参数 | Host 编译失败 | git 单文件 revert；不要手改多个地方 |
|
||
| §2 依赖方向图改动后，后续智能体仍按旧图改代码 | 跨工单改错 | 规则文档 §2 顶部加一句"本图为 2026-08-08 v1.3.0 工单 05 更新版"作为时间戳标记 |
|
||
| D 还原的 MapCloudSyncProxySettings 方法体与"即时状态记忆 2026-06-17"实际实现不一致 | 端点行为变化 | 先从 git 历史（CloudSyncEndpointExtensions.cs 被删前的版本）原样恢复，不做任何逻辑修改 |
|
||
|
||
## 八、与其他工单的语音/UI 入口衔接
|
||
|
||
> 按 [05-多入口功能同步规范.md](../../../.trae/rules/项目/05-多入口功能同步规范.md) 第 3.2 条：纯基础设施调整无需检查双入口。
|
||
|
||
| 入口 | 已规划 | 方案 |
|
||
|---|---|---|
|
||
| UI | ❌（无需） | 纯工程化，用户无感知 |
|
||
| 语音 | ❌（无需） | 不涉及业务操作 |
|
||
|
||
---
|
||
|
||
**创建日期**：2026-08-08
|
||
**关联规则**：[01-项目架构.md](../../../.trae/rules/项目/01-项目架构.md)
|
||
**关联工单**：v1.2.0 工单 08 / 工单 10；v1.3.0 工单 01 / 06
|
||
|
||
---
|
||
|
||
## 九、执行期设计修正（2026-08-08，不违反 §2.1：本段落为本次执行前新增，未改动 §二 缺口表原有行）
|
||
|
||
### 9.1 缺口 D 重判：`MapCloudSyncProxySettings` 实际上不应作为手动 Map 存在
|
||
|
||
**执行前代码核对结果**：`ICloudSyncProxySettingsService` 已继承 `IDynamicApiService`（见 `src/Hua.Todo.Application/Services/CloudSync/Services/ICloudSyncProxySettingsService.cs`），因此代理设置端点（GET/POST `/api/cloudSyncProxySettings`）**由 DynamicApiMiddleware 自动暴露**。即时状态记忆 2026-06-17 条目记录的「CloudSyncEndpointExtensions 仅保留 `MapCloudSyncProxySettings`」属于"CloudSync 端点 DynamicApi 化"过程中的中间状态快照：移除 16 个手动 Map 时，旧 MapCloudSyncProxySettings 本应连同删除却留下了文档引用，造成规则文档 §5 出现了「云同步代理设置端点 → CloudSyncEndpointExtensions.cs」这个错误路径。
|
||
|
||
**修正后缺口 D**：从「代码侧新建 CloudSyncEndpointExtensions.cs 还原方法」**改为「规则侧清理过时引用」**：
|
||
- 01-项目架构.md §5：把「云同步代理设置端点 → CloudSyncEndpointExtensions.cs」改为 `ICloudSyncProxySettingsService`（DynamicApi 自动暴露，仅在嵌入式 AddCloudSyncProxy 时注册）
|
||
- v1.3.0 00-工单总览 §5 关键决策「Host 中间件顺序固定模板」：末尾移除 `→ MapCloudSyncProxySettings`（Host 上代理设置端点本来就不注册）
|
||
- 代码侧：不新建 CloudSyncEndpointExtensions.cs，也不在 Program.cs 追加 `MapCloudSyncProxySettings()` 调用
|
||
|
||
**验收影响**：
|
||
- §五 验收 #3 对应取消；新增验收 #3b：01-项目架构.md §5 中不再出现 `CloudSyncEndpointExtensions.cs` 和 `MapCloudSyncProxySettings` 两个字符串；`ICloudSyncProxySettingsService` 行出现且描述正确
|
||
- §五 验收 #5 回归编译仍然保留（仍然是 0 错误 + 既有测试全过）
|
||
|
||
### 9.2 其余缺口 A/B/C/E 不变
|
||
|
||
A（§1 补条目）、B（§2 ASCII 补中间层）、C（抽离 AddCloudSyncServer 到 *Extensions 文件）、E（Mcp 描述改 EndpointExtensions + ServiceCollectionExtensions）与代码实际核对一致，按原计划执行。
|