BuildFlow 后端优化闭环 SOP

本文档说明如何从干净工作树执行后端架构、迁移、集成、并发恢复和性能门禁，并保留可复查证据。脚本任何阶段失败或出现 skipped 测试都会返回非零退出码，不得把部分通过视为完成。

前置条件

macOS 或 Linux Bash 环境。
.NET SDK 10。
可用的 Docker daemon 与 Docker Compose。
git、rg、curl 已安装。
当前分支已提交全部跟踪和未跟踪改动，git status --short 为空。
Docker 有足够空间运行 PostgreSQL、Redis、MongoDB 和 MinIO。

脚本不会写入本地敏感配置文件，也不会连接项目开发库。测试凭据只用于本次独立 Compose 项目。

手动生成 EF Migration 时，Monitoring、Platform、Workflow 和 Scripting 的设计时工厂要求显式提供基础 PostgreSQL 连接。工厂只替换目标数据库名，不再包含仓库内固定密码：

BUILDFLOW_EF_DESIGN_TIME_CONNECTION='Host=127.0.0.1;Port=<port>;Username=<user>;Password=<password>;Database=postgres' \
  dotnet ef migrations add <MigrationName> --project <InfrastructureProject> --startup-project src/BuildFlow.Host

执行方式

从仓库根目录运行：

scripts/backend-optimization-sop.sh

默认报告写入：

artifacts/backend-optimization-sop/<UTC时间戳-进程号>/

可通过 BACKEND_SOP_ARTIFACT_ROOT 指定其他报告根目录。若目录位于仓库内，应确保它已被 Git 忽略；推荐使用绝对路径：

BACKEND_SOP_ARTIFACT_ROOT=/tmp/buildflow-sop-evidence \
  scripts/backend-optimization-sop.sh

隔离资源

脚本为每次执行生成唯一的独立 Compose 项目名。PostgreSQL、Redis、MongoDB、MinIO 均绑定 127.0.0.1 的 Docker 随机端口，端口启动后动态发现，不占用固定开发端口。

脚本仅向测试进程导出以下变量：

BUILDFLOW_WORKFLOW_TEST_CONNECTION
BUILDFLOW_MONITORING_TEST_CONNECTION
BUILDFLOW_RAG_REDIS_TEST_CONNECTION
BUILDFLOW_IM_TEST_POSTGRES_CONNECTION
BUILDFLOW_IM_TEST_MONGO_CONNECTION
BUILDFLOW_IM_TEST_REDIS_CONNECTION
BUILDFLOW_FILE_S3_TEST_ENDPOINT
BUILDFLOW_FILE_S3_TEST_ACCESS_KEY
BUILDFLOW_FILE_S3_TEST_SECRET_KEY

无论成功或失败，EXIT 清理都会按本次项目名执行 docker compose ... down -v。它不会停止、删除或复用开发者已有容器、网络和卷。

阶段说明

01-preflight：检查 .NET 10、Docker、Compose、Git、ripgrep、curl 和干净工作树。
02-static-guards：扫描固定密码、裸业务异常、Endpoint DbContext、InProcess bridge、DateTime.Now 和 Workflow Task.Run。
03-restore-build：仅 restore 一次，再以 --no-restore -warnaserror 构建，要求 0 warning / 0 error。
04-unit-tests：运行非外部依赖的单元测试、Host 测试和全部架构护栏。
05-start-infrastructure：启动独立 Compose 项目，等待四个服务健康并生成随机端口连接变量。
06-database-migrations：验证 Workflow 空库迁移和前版本结构升级，两条路径都保留 TRX。
07-integration-tests：验证 PostgreSQL UPSERT、Redis、MongoDB/SignalR、MinIO、RAG handler 与 SSE 协议。
08-recovery-tests：验证双 worker 竞争、租约过期、崩溃等价恢复和重复处理保护。
09-performance-tests：验证大表单查询数、导入事务数、长上下文、Redis 并发、S3 并发和 50,000 行 Excel 内存峰值。
10-full-solution：在同一隔离环境运行完整解决方案测试，并再次拒绝任何 skipped。

报告结构

每次运行目录包含：

summary.md
stages.tsv
infrastructure.env
cleanup.log
logs/<stage>.log
trx/**/*.trx
SUCCESS

summary.md：最终状态、测试总计、阶段耗时、命令、日志路径和所有 SOP_METRIC。
stages.tsv：每个阶段的开始/结束时间、秒数、退出码、日志和命令。
logs/：完整控制台输出，可用于定位第一个失败命令。
trx/：各门禁原始 TRX，报告中的 passed/failed/skipped 从这里聚合。
SUCCESS：仅在全部十个阶段通过、总 skipped 为 0 时生成。

主要指标包括 SQL 查询数、导入提交数、Redis 并发追加和列表长度、RAG 上下文消息/token、S3 最大并发数，以及 Excel 行数和峰值托管内存。

失败处理

脚本使用 fail-fast 行为。失败时：

查看终端给出的 summary.md 路径。
在摘要中确认失败阶段和 failure log。
打开对应 logs/<stage>.log，定位首个非零命令。
查看相关 TRX 的失败测试和标准输出。
修复后从干净工作树重新完整执行，不跳过失败阶段。

若 Compose 清理失败，运行也会标记失败，cleanup.log 保存项目级清理输出。失败、缺失 TRX、任何 skipped > 0、未生成 SUCCESS 均表示闭环未完成。

4.8 KiB Raw Blame History Unescape Escape