# CFC · 测试工作 Runbook（发现/跟踪 + 本机执行）

> 生成日期：2026-11-01 ｜ 模式：discovery-only（发现/跟踪）
> 本仓库的 tdd-orchestrator 定位为「发现 / 格式化 / 跟踪已有测试」，**实际跑测试在开发机完成**
> （需 mvn / MySQL / 已配好的 Python 环境）。本沙箱负责发现、编目、规划与进度跟踪。
> **⚠️ 测试目标环境：`http://cfc.iwintrue.com`（远程测试环境）。本机跑测试只针对该环境，不指向本地后端 / 不指向生产。**

## 1. 当前测试资产（只读扫描，2026-11-01）

| 来源 | 文件数 | 用例/方法 |
|---|---|---|
| 结构化用例 `tests/test-cases/*.md` | 9 | 678 |
| Playwright `tests/**/*.spec.js` | 70 | 411 |
| Python pytest（`cfc-langgraph` + `tools/xaf_agent_hub`） | 12 | 47 |
| Java 后端 `@Test`（`cfc-backend/src/test/java`） | 182 | 1379 |
| 用户场景 `tests/user-scenarios/*.md` | 8 | 文件级 |
| **合计** | — | **2515** |

后端 Controller 共 357 个、handler 方法 1933，**已覆盖仅 199（10.3%）**，未覆盖 271 个。

## 2. 后端覆盖缺口 Backlog（按模块，真实扫描结果）

> 缺口 = 当前测试源中没有任何 handler 被命中的 Controller。这是发现出的真实缺口，非发明。

| 模块 | 未覆盖 | 总数 | 覆盖率 | 优先级 |
|---|---|---|---|---|
| `admin`（运营后台） | 103 | 120 | 14% | **P0** |
| `guide`（规划师） | 14 | 19 | 26% | P1 |
| `family`（家庭） | 8 | 15 | 47% | P1 |
| `mind`（心理） | 6 | 8 | 25% | P2 |
| `assessment`（测评） | 5 | 6 | 17% | P2 |
| `diet` / `recommendation` / `fatloss` / `task` / `wealth` / `user` 等 | 各 3–5 | 0% | — | P2/P3 |

`admin` 占全部未覆盖的约 38%，且多为核心管理接口，补测收益最高。

## 3. 执行 Runbook（开发机）

### 3.1 Java 纯单测子集（无需数据库）
```bash
cd cfc-backend
mvn -q -DskipTests compile
# 只跑不依赖 Spring 上下文 / 数据库的纯单测包
mvn test -Dtest='com.etotem.cfc.unit.**,com.etotem.cfc.util.**,com.etotem.cfc.common.**'
```

### 3.2 Java 集成测试（需 MySQL@3306 + Redis@6379 已起）
```bash
cd cfc-backend
mvn test -Dtest='com.etotem.cfc.integration.**'
# 全量（耗时较长，需完整基础设施）：
mvn test
```

### 3.3 Python（cfc-langgraph）—— **远程执行，不在本地跑**

> ⚠️ `cfc-langgraph`（Python / FastAPI / LangGraph）**部署在 `192.168.16.251`（opencode.iwintrue.com）测试环境主机上**，不在本机跑。其 pytest 通过 `opencode_sessions.junit`（client=`opencode-iwintrue`）远程派发执行。
> 本沙箱只做**发现/编目**（扫描 `cfc-langgraph/tests` 仓库内容），**不本地安装 venv / 不本地运行 langgraph 测试**。
> 此前"langgraph 需本地 Python 3.14 venv"的判断已作废 —— 该服务在远程测试环境运行，本地无需配置其运行环境。

```bash
# 发现/编目（本地只读扫描，OK）
python <skill>/test_inventory.py --project d:/cfc
# 实际运行 langgraph pytest：经 opencode.iwintrue.com 远程会话派发（delegation_enabled=true）
# 由 tdd_orchestrate.py 的 --auto / --alloc-session 选 label=python / langgraph 路由到 junit 会话
```

### 3.4 Playwright E2E / API（针对 cfc.iwintrue.com 测试环境）

> 项目 Playwright 配置**默认已指向测试环境**：
> - `playwright.config.api.js` → baseURL 直接 `http://cfc.iwintrue.com`（API 级 e2e）
> - `playwright.config.js`（主） → 默认 `http://cfc.iwintrue.com`（可用 `PW_BASE_URL` 覆盖）
> - `playwright.config.func.js` / `playwright.config.smoke.js` → 默认 `http://127.0.0.1:9082`，**跑测试环境需显式覆盖**
> - `e2e_complete_test.py` → `BASE = http://cfc.iwintrue.com:80`
>
> **⚠️ 后台小程序 Web 版前端部署在 `http://cfc.iwintrue.com/frontend`**（根路径 `/` 返回 404 白标，非 API 路径 `/frontend` 才是 SPA）。
> 因此：
> - **API 级 e2e**（走 `request` 上下文，不依赖前端）→ 直接对 `cfc.iwintrue.com` 跑（已验证）。
> - **UI 级 e2e**（依赖 `page.goto`/DOM）→ baseURL 须指向 `http://cfc.iwintrue.com/frontend`，否则会因根路径 404 而全部失败。UI 用例**可在本沙箱直接用已装 chromium 跑**（不依赖 opencode）；也可经 opencode 派发到 189/本机跑（见 3.5）。

```bash
cd tests
npm install
npx playwright install chromium
# 针对测试环境（func/smoke 需带 PW_BASE_URL；api/主配置默认即是）
PW_BASE_URL=http://cfc.iwintrue.com npx playwright test --project=api      # API 级 e2e（默认指向测试环境）
PW_BASE_URL=http://cfc.iwintrue.com npx playwright test --project=smoke    # 冒烟（覆盖 localhost 默认）
PW_BASE_URL=http://cfc.iwintrue.com npx playwright test --project=func     # 功能（覆盖 localhost 默认）
PW_BASE_URL=http://cfc.iwintrue.com npx playwright test                    # 全量
# UI 级 e2e 针对小程序前端（baseURL 指向 /frontend）
PW_BASE_URL=http://cfc.iwintrue.com/frontend npx playwright test --project=desktop   # 桌面端 UI（如有）
# Python 端到端（已硬编码 cfc.iwintrue.com:80）
python e2e_complete_test.py
```

### 3.5 小程序 Web 自动化（opencode 派发，189 / 本机）

> **后台小程序的 Web 自动化测试在 `192.168.16.189:4090`（189）与 `localhost:4091`（本机）两台 opencode 会话上派发执行**，均针对 `http://cfc.iwintrue.com/frontend`。
> - `opencode_sessions.testing`（client=`web-4091`）→ 项目目录 `d:/cfc`（本机）
> - `opencode_sessions.production`（client=`web-189-4090`）→ 项目目录 `c:/code/cfc`（189）
> - 并发约束：`agent_session_limit=1`（每台 Web 自动化服务器同时最多 1 个会话，**含跨项目**）。
>
> ⚠️ **当前执行阻塞（R8）**：三台 opencode 共用 `AgnesAI` LLM 配额已耗尽（429），agent 无法完成工具循环，故经 opencode 派发的小程序 Web 自动化**暂时跑不起来**。
> **替代方案**：UI 级 e2e 可直接在本沙箱用 Playwright + chromium 对 `cfc.iwintrue.com/frontend` 跑（见 3.4），不依赖 opencode 配额。待 R8 解除后，opencode 派发即可恢复。

## 4. 推荐执行顺序（先立基线，再补重依赖）

1. **Java 纯单测子集** —— 最快建立通过基线，本地编译运行、不依赖远程（验证代码层，非环境层）。
2. **Python pytest（cfc-langgraph）** —— **远程执行**：经 `opencode.iwintrue.com` 会话派发（label=`python`/`langgraph`），不在本机跑。
3. **Java 集成测试** —— 连测试环境 DB/Redis 或本地基础设施后跑（环境层验证）。
4. **Playwright E2E / API** —— 针对 `cfc.iwintrue.com` 测试环境跑（见 3.4，func/smoke 带 `PW_BASE_URL`）。

## 5. 进度跟踪（本沙箱侧车）

- 进度落 `.tdd/test-progress.json`，按 `anchor = source_path#local_id` 索引（如 `tests/test-cases/admin.md#TC-A-01`）。
- 执行后在本沙箱跑 `test_inventory.py` 即从侧车派生 `docs/tdd/test/automation-status.md`。
- **原始测试文件零侵入**：只改侧车，不改 `.md` / `.spec.js` / `.py` / `.java`。
- 发现 / 台账命令（只读）：
  ```bash
  python <skill>/discover_tests.py --project d:/cfc
  python <skill>/test_inventory.py --project d:/cfc
  ```
  `<skill>` = `C:/Users/iwt/.workbuddy/skills/tdd-orchestrator/scripts`

## 6. 优先级与下一步

- **先补 `admin` 模块**（103 未覆盖，核心管理接口），再 `guide` / `family` / `mind` / `assessment`。
- 在开发机执行完任一子集后，把结果回填侧车（`通过 / 失败 / 阻塞`），再跑 `test_inventory.py` 刷新共享台账。
- 所有 E2E / API 测试一律针对 `http://cfc.iwintrue.com` 测试环境；Java 单测为本地代码层验证，集成测试连测试环境基础设施。
- 本沙箱不推送 `.tdd/`；`docs/tdd/test/*.md` 可提交推送给测试团队。