# 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 连接。工厂只替换目标数据库名，不再包含仓库内固定密码：

```bash
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
```

## 执行方式

从仓库根目录运行：

```bash
scripts/backend-optimization-sop.sh
```

默认报告写入：

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

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

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

## 隔离资源

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

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

```text
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`。它不会停止、删除或复用开发者已有容器、网络和卷。

## 阶段说明

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

## 报告结构

每次运行目录包含：

```text
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 行为。失败时：

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

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