6.1 KiB
M0a 云开发中间件环境实施计划
For agentic workers: REQUIRED SUB-SKILL: Use
superpowers:executing-plansto implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.
目标: 让开发者以未提交的 .env 使用已提供的云 PostgreSQL 与 Redis,同时保留 Docker Compose v2 作为后续完整平台 Compose/E2E 的本机工具前提。
架构: 根 .env.example 只声明连接字段和无敏感默认端口;根 .env 保存本机实际凭据,始终被 Git 忽略。scripts/check_dev_services.py 只在显式 make check-dev-services 时读取 .env 并执行 TCP 连通性检查,输出 host/port 与状态但绝不输出用户名或密码。当前不创建 compose.yaml,因为本工作项不启动本地 PostgreSQL/Redis 容器。
技术栈: Docker Compose v2、Python 3.12 标准库 socket、GNU Make、Git 忽略规则。
全局约束
- 凭据只能写在根
.env;不得出现在 Git、.env.example、文档、测试、Make 输出或 CI。 make check、make ci和scripts/ci.sh保持离线/只读,不读取.env,不连接云服务,也不启动 Docker。make check-dev-services是唯一的显式云网络检查入口;它只做 TCP 连通性,不执行 SQL、写数据库、清 Redis 或调用 RAG。- 本工作项不创建
compose.yaml、数据库 schema/migration、FastAPI、worker、DDD、前端业务页面或真实 Run。 - Docker Compose v2 仅验证版本;本次不以本地容器替代已提供的云 PostgreSQL/Redis。
Task 1:记录云开发环境决策与修订工作项
文件:
-
修改:
docs/decisions/decisions.md -
修改:
docs/plan/work-items/W-M0a-04-compose-and-environment-baseline.md -
修改:
docs/plan/TODO.md、docs/plan/traceability.md、docs/README.md -
Step 1: 写明 D-019 与 W-M0a-04 的范围变化
将开发依赖明确为受控云 PostgreSQL/Redis;Compose v2 保留为未来完整本地编排的前提,但当前不定义服务容器。
- Step 2: 验证文档链接
运行:make check-docs
预期:新决策、工作项和追踪链接均通过。
Task 2:以测试驱动建立安全的云服务检查器
文件:
- 新建:
scripts/tests/test_check_dev_services.py - 新建:
scripts/check_dev_services.py
接口: python3 scripts/check_dev_services.py --env <path> 读取键值环境文件,要求 PostgreSQL 与 Redis 的 host/port 字段;对每个端点执行超时受限的 TCP 连通性检查,失败返回非零。输出中不得出现用户名或密码。
- Step 1: 写出失败测试
覆盖缺少必要字段、可连接本地临时 TCP 服务、无法连接端口,以及错误输出不回显输入中的密码。
- Step 2: 验证 RED
运行:python3 scripts/tests/test_check_dev_services.py
预期:因检查器不存在而失败。
- Step 3: 实现最小标准库检查器
只解析简单 KEY=VALUE 行与显式 host/port;不依赖数据库或 Redis Python client,不打印敏感值,不连接实际云服务,除非从命令行显式调用。
- Step 4: 验证 GREEN
运行:python3 scripts/tests/test_check_dev_services.py
预期:所有 fixture 行为通过。
Task 3:添加环境样例与显式 Make 入口
文件:
- 新建:
.env.example - 新建(被忽略):
.env - 修改:
Makefile、.gitignore - 修改:
scripts/tests/test_make_targets.py
接口: make check-dev-services 必须显式读取 ENV_FILE(默认 .env)并调用检查器;make check 不依赖该 target。.env.example 只有字段名和无敏感端口;.env 的实际值永不进入 Git。
- Step 1: 写出失败的 Make 合同测试
断言 dry-run 的 check-dev-services 使用 .env 和 scripts/check_dev_services.py,并断言 make --dry-run check 不包含该网络目标。
- Step 2: 验证 RED
运行:python3 scripts/tests/test_make_targets.py MakeTargetTest.test_check_dev_services_target_is_available
预期:目标尚不存在而失败。
- Step 3: 添加
.env.example、本机.env与 Make target
实际凭据只写进 Git 忽略的 .env;复核 .env.example、lockfile 和文档仍会被 Git 正确追踪或忽略。
- Step 4: 验证 GREEN
运行:python3 scripts/tests/test_make_targets.py && make check
预期:所有本地质量门通过,且未连接云服务。
Task 4:提供安全使用说明并验证显式外部连通性
文件:
-
新建:
docs/guides/cloud-dev-services.md -
修改:
docs/README.md、docs/plan/work-items/W-M0a-04-compose-and-environment-baseline.md -
Step 1: 说明复制样例、显式检查与安全边界
文档不出现实际主机、用户名或密码;说明 Docker Compose v2 已作为工具可用、但当前工作项不定义本地容器。
- Step 2: 验证 Docker Compose v2 与云服务 TCP 连通性
运行:docker compose version 与 make check-dev-services。
预期:报告 Compose 版本及两项云端点可达性;不打印凭据、不写入数据库/Redis。
- Step 3: 完整验证、更新状态并提交
运行:python3 scripts/tests/test_check_docs.py && python3 scripts/tests/test_make_targets.py && make check && make check-dev-services。
预期:全部返回 0;将实际命令与结果写入 W-M0a-04,推送完成分支供审阅。
计划自审
- 覆盖:Task 1 记录外部依赖决策;Task 2 证明检查器不会泄漏敏感值;Task 3 证明云检查与常规质量门隔离;Task 4 验证本机工具和经授权的云 TCP 连通性。
- 范围:不包含 local Compose service、schema/migration、应用代码、API、worker、前端、RAG 或任何数据写入。
- Git:只提交非敏感配置、代码、测试和文档;
.env不暂存也不推送。