docs: add BuildFlow API optimization design

2026-07-20 08:29:10 +08:00 · 2026-07-20 08:29:10 +08:00 · e549d3e3fb
commit e549d3e3fb
parent 51eea796e2
1 changed files with 416 additions and 0 deletions
--- a/docs/superpowers/specs/2026-07-20-buildflow-api-optimization-design.md
+++ b/docs/superpowers/specs/2026-07-20-buildflow-api-optimization-design.md
@ -0,0 +1,416 @@
 # BuildFlow API 全面优化设计
 ## 1. 目标
 本设计用于系统性修复当前 BuildFlow API 已确认的安全、可靠性、性能和架构规范问题，并建立可重复执行的深度测试与闭环 SOP。
 完成标准不是“代码能够编译”，而是同时满足以下条件：
 - 已确认的高风险安全问题全部关闭。
 - 工作流 Timer 和异步导入在多实例、进程重启和异常重试场景下保持可靠、幂等。
 - 已确认的 N+1、无界上下文、整表内存加载和串行远程调用被消除或受到明确上限约束。
 - HTTP 层、模块边界、异常错误码和文件组织符合 `rag-coding-api`。
 - EF Migration 可在空库和存量库上执行，并验证升级前后数据不丢失。
 - 单元测试、集成测试、并发测试、性能门禁和 HTTP/SSE 冒烟测试全部通过。
 - 最终提供一个可重复运行、失败可定位、结果可归档的后端优化 SOP。
 ## 2. 范围与兼容性
 ### 2.1 范围
 本次覆盖：
 - `BuildFlow.Host`
 - `modules/platform`
 - `modules/rag`
 - `modules/file`
 - `modules/monitoring`
 - `modules/workflow`
 - `shared/BuildFlow.Shared`
 - 对应测试项目、EF Migration 和 SOP 脚本
 ### 2.2 兼容性约束
 - 保持现有 HTTP 路由不变。
 - 保持现有成功响应信封和 SSE 事件协议兼容。
 - 权限收紧属于预期行为变化：越权、匿名 Obsidian 同步和缺少部署密钥的管理员初始化将被拒绝。
 - 数据库允许新增表、字段和索引，但不得通过删除重建现有表实现迁移。
 - 保留当前工作树中的用户改动；每批修改只触碰该批明确列出的文件。
 - 不引入跨模块 service/interface bridge；跨模块协作只能使用目标模块 Application 拥有的 MediatR Command/Query。
 ## 3. 实施策略
 采用“风险优先的纵向批次”，而不是按模块逐个重构或一次性大改。
 本文是总设计和顺序约束，不直接展开为一个超大实施计划。五个批次分别生成独立的 TDD 实施计划；每个批次完成并通过验收后，才为下一批编写计划。这样可以让每批保持可审查、可验证和可回滚。
 每个批次必须形成独立闭环：
 1. 写失败测试并确认失败原因正确。
 2. 实现最小修复。
 3. 运行该批测试和受影响模块测试。
 4. 运行架构测试和解决方案构建。
 5. 记录契约、Migration、性能和未验证项。
 6. 通过门禁后再进入下一批。
 批次顺序固定为：
 1. 安全与对象权限。
 2. 持久化任务和多实例可靠性。
 3. 数据库查询与批处理性能。
 4. 聊天、文件和 Excel I/O 性能。
 5. 架构规范收口与完整 SOP。
 ### 3.1 基线修复门禁
 当前工作树构建通过，但 RAG 测试存在两个已知失败：测试容器注册 `IOptions<AiOptions>`，而生产解析器已经依赖 `IOptionsMonitor<AiOptions>`。开始第一批生产代码修改前，先修复这两个测试的依赖注册并运行现有全解决方案测试，建立可信的绿色基线。
 基线修复只允许调整测试装配，不改变生产行为；若全量测试发现其他失败，先记录并判断是否由当前工作树已有改动造成，不能把红色基线带入后续批次。
 ## 4. 第一批：安全与对象权限
 ### 4.1 管理员初始化
 现状会在空库中创建固定密码 `admin123` 的最高权限管理员。
 目标设计：
 - 新增 `Platform:BootstrapAdmin` 配置节，包含 `Enabled`、`Username`、`Email` 和 `Password`。
 - 默认 `Enabled=false`，生产环境不会隐式创建管理员。
 - 启用初始化时，密码必须来自 IConfiguration，即环境变量、Secrets 或 Consul；仓库配置文件不得提供真实默认密码。
 - 密码必须通过与注册接口相同的强度规则。
 - 数据库已有管理员时不重置密码。
 - 日志只能记录“已创建/已跳过”，不得记录账号密码。
 验收证据：
 - 未启用时空库不会创建固定管理员。
 - 启用但密码缺失或弱密码时启动种子步骤明确失败并记录原因。
 - 合法部署密钥只在首次初始化创建管理员，后续启动不修改密码。
 - 生产源码和配置扫描不存在固定管理员默认口令；测试样例和安全设计文档不计入该扫描。
 ### 4.2 Obsidian 同步边界
 目标设计：
 - Endpoint 从 `AllowAnonymous()` 改为现有知识库写权限。
 - Handler 注入 `ICurrentUserContext`，验证知识库属于当前用户；知识库以 `CreatedBy` 作为现有所有权依据。
 - 新增 `Rag:Obsidian` 配置：`AllowedRoots`、`MaxFiles`、`MaxFileBytes`、`MaxTotalBytes`。
 - 请求路径规范化后必须位于某个允许根目录中；符号链接解析后不得逃逸根目录。
 - 枚举过程流式执行，不先对整个目录 `ToList()`。
 - 在读取前检查文件数、单文件大小和累计大小，超限抛 `ErrorCode.TooLarge`。
 - 单文件读取使用流式哈希，不为计算 SHA256 分配完整 `byte[]`。
 - 目录权限、文件消失和取消操作必须产生可诊断日志，不泄露文件内容。
 验收证据：
 - 未认证、无权限、非所有者、根目录逃逸、符号链接逃逸、数量超限和大小超限均被拒绝。
 - 合法目录可增量同步，未变文件不会重复写入。
 - 大目录测试证明内存不随文件总大小线性增长。
 ### 4.3 RAG 会话所有权
 以下操作统一执行对象级所有权校验：详情、更新、删除、普通发送、流式发送、编辑后重新生成。
 目标设计：
 - Application handler 注入 `ICurrentUserContext`。
 - 查询条件直接包含 `Conversation.Id` 和 `Conversation.UserId`，避免先查再判断产生信息泄露。
 - 非所有者统一抛 `NotFoundException(ErrorCode.NotFound, "会话不存在")`，不暴露资源是否存在。
 - Endpoint 不承载所有权逻辑。
 - 相关缓存 key 仍以会话 ID 标识，但只有通过所有权校验后才能访问。
 验收证据：
 - 用户 A 无法读取、更新、删除或向用户 B 的会话发送消息。
 - 用户 A 的所有现有会话操作保持兼容。
 - 流式和非流式路径使用同一所有权规则。
 ### 4.4 配置日志
 - Consul Provider 不再输出任何配置值或其截断片段。
 - 日志只包含 key 数量、版本索引和刷新结果。
 - 增加静态测试，禁止配置 Provider 出现值输出模板。
 ## 5. 第二批：持久化任务和多实例可靠性
 ### 5.1 工作流 Timer 数据模型
 新增 `WorkflowTimerJob`，映射到 `b_workflow_timer_jobs`。核心字段：
 - `Id`
 - `InstanceId`
 - `TokenId`
 - `NodeId`
 - `DueAt`
 - `Status`
 - `LeaseOwner`
 - `LeaseExpiresAt`
 - `AttemptCount`
 - `LastError`
 - `CompletedAt`
 - 标准审计字段
 约束与索引：
 - `TokenId` 唯一，确保一个 token 最多一个 Timer Job。
 - `(Status, DueAt)` 组合索引支撑到期扫描。
 - `(Status, LeaseExpiresAt)` 支撑过期租约恢复。
 状态限定为 `Pending`、`Processing`、`Completed`、`Failed`、`Cancelled`。
 ### 5.2 Timer 执行链
 - `ProcessEngine` 遇到未来 Timer 时只持久化 Timer Job，不再创建 `Task.Run`。
 - 新增 Host `WorkflowTimerSchedulerService`，只负责周期触发 Application processor。
 - Application processor 使用 PostgreSQL `FOR UPDATE SKIP LOCKED` 或等价原子语句批量抢占到期任务。
 - 抢占时写入实例唯一 `LeaseOwner` 和 `LeaseExpiresAt`。
 - 处理前重新验证实例、token 和 Timer Job 状态。
 - 消费 token、创建下游 token、更新 Timer Job 必须处于同一数据库事务。
 - 进程中断后，租约过期的 `Processing` 任务重新进入可领取状态。
 - 达到最大重试次数后标记 `Failed` 并保留 `LastError`，不得无限热重试。
 - 实例终止或 token 非 Active 时标记 `Cancelled`，不得继续投递。
 ### 5.3 导入任务原子抢占
 在现有导入任务增加：
 - `LeaseOwner`
 - `LeaseExpiresAt`
 - `AttemptCount`
 - `LastHeartbeatAt`
 并增加 `(Status, CreatedAt)`、`(Status, LeaseExpiresAt)` 索引。
 后台服务不再先查询 ID 再普通更新，而是调用 Application 层原子领取命令。领取规则：
 - 只领取 `Pending` 或租约过期的 `Running` 任务。
 - 一次最多领取配置数量。
 - 多实例不得领取同一任务。
 - 处理过程中按批次更新心跳。
 - 完成、失败和取消都清理租约字段。
 验收证据：
 - 两个并发 worker 只能有一个获得同一 Timer 或导入任务。
 - worker 在领取后崩溃，租约过期后另一 worker 能恢复任务。
 - 相同 token 不会创建两个下游 token。
 - 导入恢复不会重复插入已经确认完成的批次。
 ## 6. 第三批：数据库查询与批处理性能
 ### 6.1 表单统计
 把当前“目标行 × 统计字段”的查询模式改为一次构建计算计划：
 - Schema 只解析一次。
 - 按来源表单编码分组统计字段。
 - 一次批量加载来源表单定义。
 - 一次批量加载当前实例需要的来源 FormData。
 - 在内存中按来源表单和关系值建立索引。
 - 计算全部目标行后统一更新 `WorkflowInstance.Variables` 一次。
 - 单次刷新只执行一次 `SaveChangesAsync`。
 查询次数门禁不依赖运行时长，而使用 EF CommandInterceptor 计数。固定输入规模增大时，SQL 次数必须保持常数级，不得随目标行数和统计字段数线性增长。
 ### 6.2 导入批处理
 - Excel 解析结果以流或可迭代行提供，不一次性保存全部行对象。
 - 每批默认 200 行，可配置但有上限。
 - 每行继续执行派生和 Schema 校验，但表单定义与 Schema 解析结果在任务内复用。
 - 每批执行一次数据库提交和一次任务进度/心跳更新。
 - 聚合字段在批次写入后统一刷新，不为每行单独刷新两次。
 - 移除手动 `new SubmitFormDataCommandHandler(...)`，由模块内明确的批量用例承载导入逻辑。
 - 行 InstanceId 使用完整 `jobId + rowIndex` 确定性哈希，不再只覆盖 Guid 的两个字节。
 - 每个导入任务记录已提交行游标，使租约恢复从下一未完成批次继续。
 ### 6.3 Monitoring UPSERT
 - `SyncedRecord` 以现有 `(ExternalSystemId, ExternalId, RecordType)` 唯一键进行 PostgreSQL `ON CONFLICT DO UPDATE`。
 - 每批最多 500 条，参数化执行，不拼接外部输入。
 - 同步任务、记录写入和系统最近同步信息保持清晰事务边界。
 - JSON payload 解析失败仍保留 `_raw`，但记录结构化告警。
 验收证据：
 - 同步 N 条记录不再产生 N 次查询。
 - 并发同步相同外部记录不产生重复行或唯一键异常。
 - 更新记录保留最新 `SyncJobId`、`OccurredAt` 和 payload。
 ## 7. 第四批：聊天、文件和 Excel I/O 性能
 ### 7.1 聊天上下文窗口
 新增 `Rag:Chat` 配置：
 - `MaxContextMessages`
 - `MaxContextTokens`
 - `CacheTtlMinutes`
 生成路径按 `ConversationId + CreatedAt` 倒序只读取有限消息，再恢复时间顺序。`ChatContextWindowBuilder` 从最新消息向前累加估算 token，达到上限后停止；完整历史仍保留在数据库。
 新增 `(ConversationId, CreatedAt)` 组合索引。普通发送、流式发送和编辑后重新生成必须复用同一个上下文构建器，避免三套行为漂移。
 ### 7.2 Redis 消息缓存
 - key 固定为 `chat:messages:{conversationId}`。
 - 存储结构从单个 JSON 字符串改为 Redis List。
 - 追加使用原子 `RPUSH`，并通过事务或 Lua 同时刷新 TTL。
 - 读取详情使用 `LRANGE`，缓存 miss 才回源数据库并重建 List。
 - 删除会话继续删除整个 key。
 - 不再使用非原子“读完整列表、追加、写完整列表”。
 验收证据：
 - 多个并发追加不会丢消息。
 - 单次追加传输量不随历史长度增长。
 - 缓存失效后可从数据库完整重建。
 ### 7.3 文件大小回填
 - 新增 `SizeVerified` 字段；新上传文件在落库时直接标记已验证。
 - 历史记录迁移规则：`Size > 0` 标记已验证，`Size == 0` 保持待验证。
 - 文件夹树和文件列表不再调用 S3 HeadObject，也不在 GET 请求中写数据库。
 - 新增后台修复 processor，每轮领取有限数量未验证文件，并以配置的有限并发查询 S3。
 - 对象大小为 0 仍标记已验证；对象不存在记录警告并标记已验证，避免永久重试。
 - 临时网络失败保持未验证，下一轮重试。
 ### 7.4 Excel 边界
 - 上传入口在读取前限制文件字节数。
 - 导入限制最大数据行数和最大单元格文本长度。
 - 导入使用流式 OpenXML reader，避免 `ReadAllBytesAsync` 和整表对象常驻。
 - 导出使用 OpenXmlWriter 顺序写行，并从数据库按稳定游标分页读取。
 - HTTP 下载保持现有文件响应契约；生成过程使用临时文件或可回收流，避免同时保留完整实体集合和最终字节数组。
 - 临时文件在成功、失败和取消路径都必须清理。
 验收证据：
 - 超限文件在进入深度解析前被拒绝并返回 `ErrorCode.TooLarge`。
 - 大数据导入/导出测试记录峰值内存，数据规模扩大时不再近似多份完整文件线性叠加。
 - 取消导出后无残留临时文件。
 ## 8. 第五批：架构规范收口
 ### 8.1 Endpoint CQRS
 以下 Endpoint 迁移为纯 HTTP 适配器：
 - `ChangePasswordEndpoint`
 - `RAGStreamEndpoint`
 - `StreamMessageEndpoint`
 - `EditMessageStreamEndpoint`
 非流式操作使用普通 MediatR Command/Query。流式操作使用 MediatR `IStreamRequest<TEvent>`；Application handler 负责业务、持久化和产生领域流事件，Endpoint 只负责把事件编码为现有 SSE 协议。
 ### 8.2 移除跨模块 Bridge
 移除以下 Host 注册和实现：
 - `InProcessUserInfoService`
 - `InProcessFileStorageClient`
 - `InProcessAvatarUrlResolver`
 替代方式：
 - IM 需要用户信息时直接发送 Platform Application 的批量用户 Query。
 - RAG 需要上传/下载文件时直接发送 File Application 的 Command/Query。
 - Platform 需要头像访问地址时发送 File Application 的预览路径 Query，或只返回 object key 由已有文件 Endpoint 解析；不得再注入 Host bridge。
 目标模块拥有 Command、Query 和 DTO，调用模块只引用这些契约。
 ### 8.3 异常和文件组织
 - 全量清理共享 `BusinessException`、`NotFoundException`、`UnauthorizedException` 的旧单参数调用。
 - 按语义选择 `ErrorCode`，不做无脑统一替换。
 - 拆分所有一个文件包含多个顶级 class、record 或 enum 的源文件。
 - Command、Query、Handler、Endpoint、Request 和 DTO 继续保持一文件一类型。
 ### 8.4 架构护栏
 扩展 `BuildFlow.Architecture.Tests`，至少验证：
 - Endpoint 构造函数不允许依赖任何 DbContext。
 - Host 不允许存在 `InProcess*` 跨模块桥接注册。
 - 业务异常调用必须显式携带 `ErrorCode`。
 - 一个源文件只允许一个顶级 class、record 或 enum，明确的嵌套配置类型除外。
 - 模块不能出现独立 Program、launchSettings 或 Api 项目。
 架构测试必须扫描当前源码而不是只验证少量已知文件，确保新增代码也受约束。
 ## 9. Migration 设计
 预计涉及：
 - Workflow：新增 Timer Job 表、导入租约/进度字段及索引。
 - RAG：新增聊天消息组合索引。
 - File：新增 `SizeVerified` 字段及待验证查询索引。
 Migration 验证分两条路径：
 1. 空库从零执行全部 Migration，验证最终模型与 Snapshot 一致。
 2. 从本次变更前的数据库结构升级，验证原有数据、主键、外键和索引保留。
 每个 Migration 必须检查生成 SQL，不接受意外 `DropTable`、`DropColumn` 或数据丢失式重建。涉及数据回填时使用明确、幂等的 SQL。
 ## 10. 深度测试策略
 ### 10.1 测试层级
 - 单元测试：所有权、路径边界、上下文窗口、状态转换、批量计算和错误分类。
 - EF 集成测试：使用真实 PostgreSQL 验证 Migration、锁、`SKIP LOCKED`、UPSERT 和索引支持的查询。
 - Redis 集成测试：验证原子追加、并发一致性、TTL 和缓存重建。
 - S3 集成测试：验证空对象、缺失对象、网络失败和后台回填。
 - Host 集成测试：验证权限、响应信封、HTTP 状态、SSE 事件顺序和取消传播。
 - 并发测试：至少两个 processor 实例同时竞争 Timer、Import 和 Monitoring 数据。
 - 大数据测试：表单统计、导入、导出、长会话和大量待回填文件。
 ### 10.2 稳定性能门禁
 性能验收优先使用确定性指标，避免只依赖容易抖动的墙钟时间：
 - SQL 命令数量。
 - 远程 S3 调用数量和最大并发数。
 - Redis 每次追加的命令数量与传输对象大小。
 - LLM 上下文消息数和估算 token 上限。
 - 导入每批事务数量。
 - 峰值托管内存和临时文件清理结果。
 墙钟耗时只作为辅助报告，不作为唯一门禁。
 ## 11. 闭环 SOP
 新增后端优化 SOP，按以下顺序执行：
 1. 环境检查：.NET 10、Docker、PostgreSQL、Redis、S3 兼容服务和必要配置。
 2. 静态扫描：固定密码、裸异常、Endpoint DbContext、InProcess bridge、单文件多类型、`DateTime.Now`。
 3. 格式与构建：`dotnet build BuildFlow.slnx --no-restore`，要求 0 warning / 0 error。
 4. 单元与架构测试：运行全部非外部依赖测试，禁止 skipped。
 5. 基础设施启动：启动隔离的 PostgreSQL、Redis 和 S3 测试容器。
 6. Migration 测试：空库迁移和存量结构升级。
 7. 集成测试：数据库锁、UPSERT、Redis、S3、Host HTTP/SSE。
 8. 并发与恢复：双 worker 竞争、worker 崩溃、租约过期、Host 重启。
 9. 大数据场景：长会话、大表单、大 Excel、大目录。
 10. 结果归档：命令、通过数、失败数、skipped 数、耗时、查询计数、内存结果和失败日志路径。
 SOP 脚本任何一步失败必须立即返回非零退出码，不得继续输出“完成”。脚本不得修改开发者现有数据库或覆盖本地 Secrets。
 ## 12. 回滚与故障处理
 - 每批独立提交；下一批开始前上一批必须全绿。
 - 行为改造保留配置开关时，开关只用于短期回滚，不长期维持两套实现。
 - Timer 和 Import Migration 的 Down 只删除本批新增结构；执行 Down 前必须明确会丢失尚未完成的任务状态。
 - 后台 processor 出现持续失败时停止领取新任务，但 Host 其他 API 保持可用。
 - 配置缺失导致安全边界无法建立时采用 fail closed，不回退匿名或固定密码行为。
 ## 13. 完成审计
 最终完成前逐项核对：
 - 第一至第五批所有验收证据均有对应测试或命令输出。
 - 全解决方案测试通过，0 skipped；若第三方环境导致无法执行，目标不得标记完成。
 - 空库和升级 Migration 均通过。
 - 所有静态规范扫描为零违规。
 - 现有 API 路由和 SSE 协议回归通过。
 - 没有遗留 `Task.Run` Timer、非原子 Redis 读改写、导入任务先查后抢、逐记录 Monitoring 查询或 GET 路径 S3 回填。
 - SOP 从干净测试环境完整运行一次并生成归档报告。