# pbls

PBL Agent OS 验证原型应用（唯一入口 `app/pbls.py`，端口以
`projects/pbls/env/test.json` 为唯一事实源）。业务模块见机构 `modules/pbl_*`。

## 测试依赖（DISC.2）

**结论：pytest 已显式声明，不再依赖临时注入 `PYTHONPATH`。** 宿主 `python3` 上没有 pytest
（`python3 -m pytest` → `No module named pytest`），且本机宿主 user site 是只读文件系统
（`pip install --user` 报 `[Errno 30] Read-only file system`），所以测试依赖的落点是 **venv**。

### 新增/相关文件清单

| 路径 | 层级 | 职责 |
|---|---|---|
| `apps/pbls/requirements-test.txt` | 应用级 | 测试前置依赖清单（`pytest>=7.0,<10`），由 `build.sh` **第 7b 步**装进应用 venv |
| `apps/pbls/build.sh` 第 7b 步 | 应用级 | `pip install -r requirements-test.txt` + `import pytest` 自证；`PBL_SKIP_TEST_DEPS=1` 可跳过 |
| `modules/pbl_evidence/requirements-dev.txt` | 模块级 | 同一版本区间的模块侧清单（不装本包也能跑离线单测的最短路径） |
| `modules/pbl_evidence/scripts/setup_test_env.sh` | 模块级 | 建 `.venv-test` 并安装 `requirements-dev.txt`（含仓库卫生门禁） |
| `modules/pbl_evidence/scripts/activate_test_env.sh` | 模块级 | 打印激活/直接调用测试 venv 解释器的方式 |
| `modules/pbl_evidence/scripts/run_tests.sh` | 模块级 | 一条命令跑测试：无 pytest 时自动引导，再执行 pytest |
| `modules/pbl_evidence/README.md` §Running tests | 文档 | 排障入口 + `PBL_EVIDENCE_TEST_DB` 开关用法 |

### 为什么是两份清单（应用级 vs 模块级）

- `requirements-test.txt`（应用级）服务**整应用**的测试环境：跑 `build.sh` 后 venv 内即有 pytest，
  任何 `modules/pbl_*/tests/` 都能用同一个解释器执行。
- `requirements-dev.txt`（模块级）服务**只测本模块**的 CI/离线场景：不安装 pbls 应用、不装本包
  （`pip install -e .`）也能一条命令装好依赖。
- 两份**版本区间同源**（`>=7.0,<10`），避免"应用装了 9.x、模块 CI 装了 7.x"导致用例语义漂移。
- 两者都刻意与运行时清单 `requirements.txt` 分离：pytest 不进生产镜像，也不进
  `build.sh` 第 5 步的运行时依赖核验（该步只核验 ahserver/sqlor/apppublic/appbase/rbac/PyMySQL）。

### 推荐调用顺序

```bash
# 场景 1：完整应用环境（部署/联调机）
bash apps/pbls/build.sh                       # 第 7 步 venv → 7b 测试依赖 → 8 装模块
source apps/pbls/venv/bin/activate
python3 -m pytest modules/pbl_evidence/tests/test_m5a_idempotency.py -v

# 场景 2：只跑 pbl_evidence 单测（测试机/CI，最短路径）
bash modules/pbl_evidence/scripts/run_tests.sh          # 无 pytest 时自动引导 .venv-test

# 场景 3：只要环境不要跑（手工用 venv 解释器）
bash modules/pbl_evidence/scripts/setup_test_env.sh
bash modules/pbl_evidence/scripts/activate_test_env.sh
```

### 期望结果

- 不带 `PBL_EVIDENCE_TEST_DB`：`8 passed, 1 skipped`，RC=0（`test_double_collect_is_idempotent_with_db`
  需真实 MariaDB，未设开关时按设计 SKIPPED，属预期）。
- 带 `PBL_EVIDENCE_TEST_DB`（用法见 `modules/pbl_evidence/README.md` §Running tests）：`9 passed`。
- 实测日志：`projects/pbls/docs/02-develop/m5a-disc2-pytest-run.log`。
- 禁止为凑通过修改测试断言逻辑。