zkxw/docs/superpowers/plans/2026-10-11-backend-baseline-test-failures-fix.md

后端既有基线测试失败修复 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 消除后端全量测试中的 4 个既有失败，保持 AES-GCM 单一加密协议，并恢复三个业务列表的 order_num 优先排序。

Architecture: 不扩展运行时加密接口，只把与现行协议冲突的 CBC 测试替换为 AES-GCM 防篡改回归测试。排序修复限定在 collection_protocol.py 的三个查询，通过现有失败测试驱动加入 order_num ASC，并保留 create_time DESC 作为次级排序。

Tech Stack: Python 3.9、pytest、unittest、SQLAlchemy、cryptography AESGCM

---

文件结构

• Modify: backend/tests/test_api_crypto.py — 用 AES-GCM 防篡改测试替换失效的 CBC 参数测试。
• Modify: backend/app/crud/collection_protocol.py — 修复审核、缴费待确认、退款待确认三个列表的排序。
• Verify: backend/tests/test_collection_protocol_conventions.py — 复用三个现有失败测试，不调整预期。
• Update: backend/graphify-out/* — 按仓库要求更新后端代码知识图谱。

Task 1: 纠正加密测试契约

Files:

• Modify: backend/tests/test_api_crypto.py:36-46

• Reference: backend/app/core/api_crypto.py:32-56

• [ ] Step 1: 保留现有红灯证据

Run:

cd backend
PYTHONPATH=. venv/bin/pytest tests/test_api_crypto.py::ApiCryptoTests::test_encrypt_decrypt_roundtrip_cbc -v

Expected: FAIL with TypeError: encrypt_json() got an unexpected keyword argument 'alg'，证明旧测试要求了运行时不存在且前端未使用的 CBC 接口。

• Step 2: 将 CBC 测试替换为 AES-GCM 防篡改测试

将 test_encrypt_decrypt_roundtrip_cbc 替换为：

def test_decrypt_rejects_tampered_gcm_ciphertext(self):
    key = api_crypto.derive_key(
        fixed_secret="fixed-secret",
        user_id="u1",
        ts=1714300000000,
        nonce="nonce-2",
    )
    payload = {"list": [1, 2, 3], "ok": True}
    cipher = api_crypto.encrypt_json(payload, key)
    raw = bytearray(api_crypto._b64url_decode(cipher))
    raw[-1] ^= 1
    tampered = api_crypto._b64url_encode(bytes(raw))

    with self.assertRaises(api_crypto.ApiCryptoError):
        api_crypto.decrypt_json(tampered, key)

• Step 3: 运行加密测试

Run:

cd backend
PYTHONPATH=. venv/bin/pytest tests/test_api_crypto.py -v

Expected: 3 passed。该任务只纠正测试契约，不修改生产加密代码。

• Step 4: 提交加密测试修复

git add backend/tests/test_api_crypto.py
git commit -m "test: align API crypto coverage with the AES-GCM protocol."

Task 2: 修复三个协议相关列表的排序

Files:

• Modify: backend/app/crud/collection_protocol.py:1510
• Modify: backend/app/crud/collection_protocol.py:1685
• Modify: backend/app/crud/collection_protocol.py:1838

• Test: backend/tests/test_collection_protocol_conventions.py:119-289

• [ ] Step 1: 运行三个排序测试确认红灯

Run:

cd backend
PYTHONPATH=. venv/bin/pytest \
  tests/test_collection_protocol_conventions.py::TestListAuditsSortOrder::test_list_audits_includes_order_num_in_sort \
  tests/test_collection_protocol_conventions.py::TestListReceiptConfirmSortOrder::test_receipt_confirm_includes_order_num_in_sort \
  tests/test_collection_protocol_conventions.py::TestListRefundConfirmSortOrder::test_refund_confirm_includes_order_num_in_sort \
  -v

Expected: 3 failed，且每项均显示 order_by 只有一个 create_time.desc() 参数。

• Step 2: 修复审核列表排序

在 list_audits 中使用：

q_base.order_by(
    BizProtocolAudit.order_num.asc(),
    BizProtocolAudit.create_time.desc(),
)

• Step 3: 修复缴费待确认列表排序

在 list_receipt_confirm_details 中使用：

q_base.order_by(
    BizProtocolPaymentDetail.order_num.asc(),
    BizProtocolPaymentDetail.create_time.desc(),
)

• Step 4: 修复退款待确认列表排序

在 list_refund_confirm_details 中使用：

q_base.order_by(
    BizProtocolPaymentDetail.order_num.asc(),
    BizProtocolPaymentDetail.create_time.desc(),
)

• Step 5: 运行协议约定测试确认绿灯

Run:

cd backend
PYTHONPATH=. venv/bin/pytest tests/test_collection_protocol_conventions.py -v

Expected: 13 passed。

• Step 6: 提交排序修复

git add backend/app/crud/collection_protocol.py
git commit -m "fix: honor order numbers in protocol workflow lists."

Task 3: 全量验证与知识图谱更新

Files:

• Update: backend/graphify-out/*

• [ ] Step 1: 运行两份定向测试

Run:

cd backend
PYTHONPATH=. venv/bin/pytest -q tests/test_api_crypto.py tests/test_collection_protocol_conventions.py

Expected: 16 passed，0 failed。

• Step 2: 运行后端全量测试

Run:

cd backend
PYTHONPATH=. venv/bin/pytest -q

Expected: 916 passed，0 failed；允许保留现有第三方弃用 warning。

• Step 3: 更新后端知识图谱

Run:

./scripts/update-graph.sh backend

Expected: 命令退出码为 0，backend/graphify-out/ 更新完成。

• Step 4: 复跑定向测试并检查差异

Run:

cd backend
PYTHONPATH=. venv/bin/pytest -q tests/test_api_crypto.py tests/test_collection_protocol_conventions.py
cd ..
git diff --check
git status --short

Expected: 16 passed；git diff --check 无输出；工作区中本任务代码差异仅为加密测试、三个排序表达式及知识图谱更新，其他既有改动保持不变。

• Step 5: 提交知识图谱更新

git add backend/graphify-out
git commit -m "chore: refresh the backend code knowledge graph after sorting fixes."

Task 3 执行记录/偏差

• 全量后端测试实际结果：916 passed, 37 warnings，退出码为 0；警告来自现有第三方弃用提示及 LibreSSL 兼容提示。
• ./scripts/update-graph.sh backend 退出码为 0；生成的 graph.json 包含 6,122 nodes、33,427 edges、46 communities。
• 执行前 backend/graphify-out/* 已有未提交改动，且生成图包含仍未提交的市场功能源码。为保护既有改动并保持源码与图谱一致，Step 5 有意跳过：不暂存、不提交图谱文件，待上一市场功能源码统一提交时一并处理。
• GRAPH_REPORT.md 仅列出 40 communities，而 JSON/analysis 数据为 46 communities；记录为现有生成器产物差异。
• graph.html 因图谱超过大小限制而被跳过，因此本次不能声称 HTML 可视化已刷新。