#!/usr/bin/env python3 # -*- coding: utf-8 -*- """M5b 自测（pbl_evidence 证据聚合与查询契约）—— 纯 stdlib，无需 DB / 无需 pytest。 覆盖设计 docs/01-design/modules/pbl_evidence.md §3.2 的 M5b 需求点： 1. **四类证据幂等采集**：``pbl_evidence_collect_idempotent`` 首次 ``created=True``， 重复（同 idempotency_key / 同唯一索引三元组）``created=False`` 且不产生第二行； 2. **idempotency_key 归一**：显式键原样透传；缺省键由 ``tenant|source_event_id| evidence_type`` 派生且稳定（重放同键）；非四类 evidence_type 报 ``PBL_E_VALIDATION``； 3. **聚合契约**：``pbl_evidence_aggregate`` 四类计数 + 覆盖度 + 分组 + 时间水位； 4. **列表查询契约**：``pbl_evidence_query`` 分页 total/rows + payload 解析 + 水位； 5. **主体档案契约**：``pbl_evidence_subject_summary`` 学生 / 团队四类分组明细； 6. **Q-OPEN-10**：预览 / Playtest 数据（payload 标记、显式预览会话、STUDENT 私有可见性） 默认剔除，``include_preview=True`` 才纳入，且 ``preview_filter`` 回显剔除口径； 7. **租户 fail-closed**：无 tenant_id 直接 ``PBL_E_TENANT_MISSING``，不落到 SQL。 内存版 DB 会**校验拼出的 SQL**（列清单、LIMIT 占位、无 ``None`` 泄漏）并按 params 过滤， 因此不只是「函数不报错」，而是验证了查询参数与 SQL 的对应关系。 运行： cd modules/pbl_evidence && python3 scripts/selftest_m5b.py # 或： python3 -m pytest scripts/selftest_m5b.py -q （test_* 函数可直接被收集） """ import asyncio import json import os import sys sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) for sib in ('pbl_common',): p = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname( os.path.abspath(__file__)))), sib) if os.path.isdir(p) and p not in sys.path: sys.path.insert(0, p) from pbl_common.api import PblError # noqa: E402 import pbl_evidence.aggregation as A # noqa: E402 TENANT = '1' EVIDENCE_COLS = ['id', 'tenant_id', 'artifact_id', 'evidence_type', 'source_event_id', 'session_id', 'learner_id', 'blueprint_id', 'payload_json', 'occurred_at', 'dedup_key', 'collect_batch_id', 'created_at', 'updated_at'] ARTIFACT_COLS = ['id', 'tenant_id', 'artifact_uid', 'session_id', 'blueprint_id', 'team_id', 'creator_id', 'title', 'artifact_type', 'content_json', 'version_no', 'status', 'submitted_at', 'created_at', 'updated_at'] _CAPTURED = {'sql': [], 'params': []} def _row(idx, etype, learner='S01', session='101', blueprint='9', artifact=0, occurred='2026-09-20 10:00:0%d' % (idx % 9), payload=None, source=None): return { 'id': idx, 'tenant_id': TENANT, 'artifact_id': artifact, 'evidence_type': etype, 'source_event_id': source or ('EV%03d' % idx), 'session_id': session, 'learner_id': learner, 'blueprint_id': blueprint, 'payload_json': json.dumps(payload or {'event_type': 'mission.completed'}, ensure_ascii=False), 'occurred_at': occurred, 'dedup_key': 'K%03d' % idx, } def seed_rows(): """正式环境证据 5 条（四类齐）+ 预览/Playtest 证据 4 条（应被默认过滤）。""" return [ _row(1, 'decision'), _row(2, 'action'), _row(3, 'observation', learner='S02'), _row(4, 'artifact_version', artifact=77, learner='S02'), _row(5, 'decision', learner='S03', occurred='2026-09-21 08:00:00'), # ── 预览 / Playtest 族（Q-OPEN-10 默认剔除）──────────────── _row(6, 'action', payload={'pbl_preview': True, 'event_type': 'mission.completed'}), _row(7, 'observation', payload={'env_mode': 'playtest'}), _row(8, 'decision', session='999', payload={'event_type': 'team.decision'}), # 显式预览会话 999 _row(9, 'artifact_version', artifact=88, payload={'visibility': 'student', 'content_ref': 'draft'}), # STUDENT 私有 ] class FakeDB: """内存版证据库：按 params 过滤，同时校验 SQL 文本合法性。""" def __init__(self, rows): self.rows = rows async def table_columns(self, table): if table == 'pbl_evidence': return list(EVIDENCE_COLS) if table == 'pbl_artifact': return list(ARTIFACT_COLS) return [] @staticmethod def _match(row, params): for key, val in (params or {}).items(): if key in ('scan_limit', 'time_from', 'time_to') or key.startswith('etype'): continue if key in row and str(row[key]) != str(val): return False if 'time_from' in (params or {}) and row.get('occurred_at'): if str(row['occurred_at']) < str(params['time_from']): return False if 'time_to' in (params or {}) and row.get('occurred_at'): if str(row['occurred_at']) > str(params['time_to']): return False types = [v for k, v in (params or {}).items() if k.startswith('etype')] if types and str(row.get('evidence_type')) not in [str(t) for t in types]: return False return True async def q_all(self, sql, params=None): _CAPTURED['sql'].append(sql) _CAPTURED['params'].append(dict(params or {})) low = sql.lower() assert 'none' not in low.replace('is null', ''), 'SQL 泄漏 None：%s' % sql if 'from `pbl_evidence`' in low: assert 'limit ${scan_limit}$' in low, '缺少扫描上限（防全表拖库）：%s' % sql assert 'tenant_id' in low, '证据查询必须带租户条件：%s' % sql limit = int((params or {}).get('scan_limit') or A.MAX_SCAN_ROWS) rows = [r for r in self.rows if self._match(r, params)] rows.sort(key=lambda r: (str(r.get('occurred_at') or ''), int(r.get('id') or 0)), reverse=True) return rows[:limit] if 'count(*)' in low and 'pbl_artifact' in low: return [{'c': 2}] return [] async def q_one(self, sql, params=None): rows = await self.q_all(sql, params) return rows[0] if rows else None def install_fake(rows, tenant=TENANT): """把 aggregation 的 IO 依赖换成内存实现（不碰真实 DB）。""" db = FakeDB(rows) A.table_columns = db.table_columns A.q_all = db.q_all A.q_one = db.q_one A.tenant_id = lambda *a, **k: tenant return db def run(coro): return asyncio.get_event_loop().run_until_complete(coro) # ══════════════════════════════════════════════════════════════════════ # 1. 幂等采集（含 created 布尔 + 重复不产生第二行） # ══════════════════════════════════════════════════════════════════════ def test_idempotent_collect_created_flag(): rows = seed_rows() install_fake(rows) store = {} async def fake_collect(**kw): key = (str(kw.get('tenant_id') or TENANT), str(kw.get('source_event_id')), str(kw.get('evidence_type'))) if key in store: return {'ok': True, 'deduped': True, 'id': store[key], 'unique_index': 'uk_ev_dedup', 'evidence_type': key[2]} nid = 1000 + len(store) store[key] = nid rows.append(_row(nid, key[2], source=key[1])) return {'ok': True, 'deduped': False, 'id': nid, 'unique_index': 'uk_ev_dedup', 'evidence_type': key[2]} import pbl_evidence.api as api origin = api.pbl_evidence_collect api.pbl_evidence_collect = fake_collect try: first = run(A.pbl_evidence_collect_idempotent( source_event_id='EV900', evidence_type='decision', learner_id='S01', blueprint_id='9', session_id='101', payload={'choice': 'A'})) assert first['created'] is True, first assert first['deduped'] is False, first assert first['idempotency_key'].startswith('IK') and len(first['idempotency_key']) == 26 assert first['idempotency_key_derived'] is True, first second = run(A.pbl_evidence_collect_idempotent( source_event_id='EV900', evidence_type='decision', learner_id='S01', blueprint_id='9', session_id='101', payload={'choice': 'A'})) assert second['created'] is False, second assert second['deduped'] is True, second assert second['id'] == first['id'], (first, second) assert second['idempotency_key'] == first['idempotency_key'], '派生键必须稳定' assert len(store) == 1, '重复采集不得产生第二行：%s' % store # 显式 idempotency_key 原样透传 third = run(A.pbl_evidence_collect_idempotent( source_event_id='EV901', evidence_type='action', idempotency_key='IK-EXTERNAL-01', learner_id='S01')) assert third['idempotency_key'] == 'IK-EXTERNAL-01', third assert third['idempotency_key_derived'] is False, third finally: api.pbl_evidence_collect = origin def test_collect_rejects_non_fourth_type(): install_fake(seed_rows()) try: run(A.pbl_evidence_collect_idempotent(source_event_id='EV902', evidence_type='research_upload')) raise AssertionError('非四类 evidence_type 必须被拒') except PblError as exc: assert exc.code == 'PBL_E_VALIDATION', exc.code def test_tenant_fail_closed(): install_fake(seed_rows(), tenant=None) for fn, kw in ((A.pbl_evidence_aggregate, {}), (A.pbl_evidence_query, {}), (A.pbl_evidence_subject_summary, {'subject_id': 'S01'}), (A.pbl_evidence_collect_idempotent, {'source_event_id': 'EV1'})): try: run(fn(**kw)) raise AssertionError('%s 缺租户时必须 fail-closed' % fn.__name__) except PblError as exc: assert exc.code == 'PBL_E_TENANT_MISSING', (fn.__name__, exc.code) # ══════════════════════════════════════════════════════════════════════ # 2. 聚合契约 # ══════════════════════════════════════════════════════════════════════ def test_aggregate_four_types_and_coverage(): install_fake(seed_rows()) res = run(A.pbl_evidence_aggregate(group_by='learner')) assert res['ok'] is True and res['status'] == 'OK', res assert res['total'] == 5, res['total'] # 9 行中 4 行预览族被默认剔除 assert res['by_type'] == {'decision': 2, 'action': 1, 'observation': 1, 'artifact_version': 1}, res['by_type'] assert res['coverage']['covered_types'] == 4, res['coverage'] assert res['coverage']['missing_types'] == [], res['coverage'] keys = {g['group_key'] for g in res['groups']} assert keys == {'S01', 'S02', 'S03'}, keys assert res['watermark']['max_occurred_at'] == '2026-09-21 08:00:00', res['watermark'] assert res['preview_filter']['excluded_preview'] == 3, res['preview_filter'] assert res['preview_filter']['excluded_student'] == 1, res['preview_filter'] assert res['preview_filter']['applied'] is True, res['preview_filter'] assert res['truncated'] is False, res def test_aggregate_group_by_type_and_time_range(): install_fake(seed_rows()) res = run(A.pbl_evidence_aggregate(group_by='type', time_from='2026-09-21 00:00:00', time_to='2026-09-21 23:59:59')) assert res['total'] == 1, res assert res['groups'][0]['group_key'] == 'decision', res['groups'] res2 = run(A.pbl_evidence_aggregate(group_by='session', time_range={'from': '2026-09-20 00:00:00', 'to': '2026-09-20 23:59:59'})) assert res2['group_by'] == 'session_id', res2 assert res2['total'] == 3, res2 def test_aggregate_evidence_types_filter(): install_fake(seed_rows()) res = run(A.pbl_evidence_aggregate(evidence_types=['decision', 'action'])) assert set(res['by_type']) == {'decision', 'action', 'observation', 'artifact_version'} assert res['total'] == 2, res['total'] assert res['coverage']['missing_types'] == ['observation', 'artifact_version'], res['coverage'] try: run(A.pbl_evidence_aggregate(evidence_types='decision,bogus')) raise AssertionError('非法 evidence_types 必须被拒') except PblError as exc: assert exc.code == 'PBL_E_VALIDATION', exc.code # ══════════════════════════════════════════════════════════════════════ # 3. 列表查询契约（分页 + payload + 水位） # ══════════════════════════════════════════════════════════════════════ def test_query_pagination_and_payload(): install_fake(seed_rows()) res = run(A.pbl_evidence_query(page=1, rows=2)) assert res['total'] == 5, res['total'] assert len(res['rows']) == 2, len(res['rows']) assert res['rows'][0]['payload'].get('event_type'), res['rows'][0] page2 = run(A.pbl_evidence_query(page=2, rows=2)) ids = {r['id'] for r in res['rows']} ^ {r['id'] for r in page2['rows']} assert len(ids) == 4, ids # 翻页不重叠 tail = run(A.pbl_evidence_query(page=3, rows=2)) assert len(tail['rows']) == 1, tail['rows'] assert run(A.pbl_evidence_query(page=9, rows=20))['rows'] == [] def test_query_filters_by_learner_and_type(): install_fake(seed_rows()) res = run(A.pbl_evidence_query(learner_id='S02')) assert res['total'] == 2, res['total'] assert {r['learner_id'] for r in res['rows']} == {'S02'}, res['rows'] res2 = run(A.pbl_evidence_query(evidence_type='decision')) assert res2['total'] == 2, res2['total'] # ══════════════════════════════════════════════════════════════════════ # 4. 主体档案契约（学生 / 团队） # ══════════════════════════════════════════════════════════════════════ def test_subject_summary_student_and_team(): install_fake(seed_rows()) stu = run(A.pbl_evidence_subject_summary(subject_type='student', subject_id='S02')) assert stu['ok'] is True, stu assert stu['evidence_total'] == 2, stu['evidence_total'] assert stu['by_type']['action'] == 1 and stu['by_type']['artifact_version'] == 1, stu['by_type'] assert set(stu['evidence']) == {'decision', 'action', 'observation', 'artifact_version'} assert stu['artifact_count'] == 2, stu['artifact_count'] tea = run(A.pbl_evidence_subject_summary(subject_type='team', team_id='101', blueprint_id='9')) assert tea['subject_id'] == '101', tea assert tea['evidence_total'] == 2, tea['evidence_total'] # 999 预览会话已剔除 try: run(A.pbl_evidence_subject_summary(subject_type='school', subject_id='X')) raise AssertionError('非法 subject_type 必须被拒') except PblError as exc: assert exc.code == 'PBL_E_PARAM', exc.code try: run(A.pbl_evidence_subject_summary(subject_type='student')) raise AssertionError('缺 subject_id 必须被拒') except PblError as exc: assert exc.code == 'PBL_E_PARAM', exc.code # ══════════════════════════════════════════════════════════════════════ # 5. Q-OPEN-10 预览 / Playtest 默认过滤 # ══════════════════════════════════════════════════════════════════════ def test_qopen10_preview_excluded_by_default(): install_fake(seed_rows()) default = run(A.pbl_evidence_query()) withprev = run(A.pbl_evidence_query(include_preview=True, include_student_private=True, preview_session_ids=['999'])) assert default['total'] == 5, default['total'] assert withprev['total'] == 9, withprev['total'] assert withprev['preview_filter']['applied'] is False, withprev['preview_filter'] assert withprev['by_type']['observation'] == 2, withprev['by_type'] def test_qopen10_rules_pure(): prev, rule = A.is_preview_row({'payload_json': json.dumps({'pbl_preview': True}), 'session_id': '1'}) assert prev and rule == 'payload:pbl_preview', rule prev, rule = A.is_preview_row({'payload_json': json.dumps({'env_mode': 'playtest'}), 'session_id': '1'}) assert prev and rule == 'payload:env_mode', rule prev, rule = A.is_preview_row({'payload_json': json.dumps({'mode': 'demo'}), 'session_id': '1'}) assert prev and rule == 'payload:mode', rule prev, rule = A.is_preview_row({'payload_json': json.dumps({'event_type': 'x'}), 'session_id': '999'}, ['999']) assert prev and rule == 'preview_session:999', rule prev, _ = A.is_preview_row({'payload_json': '{bad json', 'session_id': '1'}) assert prev is False, '坏 JSON 不得误判为预览' priv, rule = A.is_student_private({'payload_json': json.dumps({'visibility': 'STUDENT'})}) assert priv and rule.startswith('payload:visibility'), rule priv, _ = A.is_student_private({'payload_json': json.dumps({'visibility': 'teacher'})}) assert priv is False kept, stats = A.apply_default_filters( [{'id': 1, 'payload_json': '{}', 'session_id': '1', 'learner_id': 'S01'}], {'subject_type': 'student', 'subject_id': 'S02'}) assert kept == [] and stats['excluded_subject'] == 1, stats key, derived = A.resolve_idempotency_key({'tenant_id': '1', 'source_event_id': 'EV1', 'evidence_type': 'action'}) key2, _ = A.resolve_idempotency_key({'tenant_id': '1', 'source_event_id': 'EV1', 'evidence_type': 'action'}) assert key == key2 and derived is True, (key, key2) assert A.resolve_idempotency_key({'idempotency_key': 'abc'})[0] == 'abc' def test_sql_shape_and_column_pruning(): install_fake(seed_rows()) _CAPTURED['sql'].clear() run(A.pbl_evidence_aggregate(group_by='learner')) sql = [s for s in _CAPTURED['sql'] if 'from `pbl_evidence`' in s.lower()][0] assert 'select `id`, `evidence_type`' in sql.lower(), sql assert '`source_event_id`' in sql and '`dedup_key`' in sql and '`payload_json`' in sql, sql assert 'order by `occurred_at` desc' in sql.lower(), sql assert 'limit ${scan_limit}$' in sql.lower(), sql def test_watermark_contract(): install_fake(seed_rows()) agg = run(A.pbl_evidence_aggregate(group_by='blueprint')) wm = agg['watermark'] assert wm['count'] == 5 and wm['max_id'] == 5, wm assert wm['min_occurred_at'] == '2026-09-20 10:00:01', wm q = run(A.pbl_evidence_query(learner_id='S03')) assert q['watermark']['max_occurred_at'] == '2026-09-21 08:00:00', q['watermark'] ALL_TESTS = sorted([v for k, v in list(globals().items()) if k.startswith('test_') and callable(v)]) def main(): passed, failed = 0, 0 for fn in ALL_TESTS: try: fn() except Exception as exc: failed += 1 print('FAIL %s: %s' % (fn.__name__, exc)) else: passed += 1 print('PASS %s' % fn.__name__) print('\n== M5b selftest: %d passed, %d failed, %d total ==' % (passed, failed, len(ALL_TESTS))) return 1 if failed else 0 if __name__ == '__main__': sys.exit(main())