110 lines
4.8 KiB
Markdown
110 lines
4.8 KiB
Markdown
# 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` 均表示闭环未完成。
|