docs: plan the backend baseline test failure fixes.

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

@@ -0,0 +1,208 @@
+# 后端既有基线测试失败修复 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:
+
+```bash
+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` 替换为：
+
+```python
+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:
+
+```bash
+cd backend
+PYTHONPATH=. venv/bin/pytest tests/test_api_crypto.py -v
+```
+
+Expected: `3 passed`。该任务只纠正测试契约，不修改生产加密代码。
+
+- [ ] **Step 4: 提交加密测试修复**
+
+```bash
+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:
+
+```bash
+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` 中使用：
+
+```python
+q_base.order_by(
+    BizProtocolAudit.order_num.asc(),
+    BizProtocolAudit.create_time.desc(),
+)
+```
+
+- [ ] **Step 3: 修复缴费待确认列表排序**
+
+在 `list_receipt_confirm_details` 中使用：
+
+```python
+q_base.order_by(
+    BizProtocolPaymentDetail.order_num.asc(),
+    BizProtocolPaymentDetail.create_time.desc(),
+)
+```
+
+- [ ] **Step 4: 修复退款待确认列表排序**
+
+在 `list_refund_confirm_details` 中使用：
+
+```python
+q_base.order_by(
+    BizProtocolPaymentDetail.order_num.asc(),
+    BizProtocolPaymentDetail.create_time.desc(),
+)
+```
+
+- [ ] **Step 5: 运行协议约定测试确认绿灯**
+
+Run:
+
+```bash
+cd backend
+PYTHONPATH=. venv/bin/pytest tests/test_collection_protocol_conventions.py -v
+```
+
+Expected: `13 passed`。
+
+- [ ] **Step 6: 提交排序修复**
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+cd backend
+PYTHONPATH=. venv/bin/pytest -q
+```
+
+Expected: `916 passed`，0 failed；允许保留现有第三方弃用 warning。
+
+- [ ] **Step 3: 更新后端知识图谱**
+
+Run:
+
+```bash
+./scripts/update-graph.sh backend
+```
+
+Expected: 命令退出码为 0，`backend/graphify-out/` 更新完成。
+
+- [ ] **Step 4: 复跑定向测试并检查差异**
+
+Run:
+
+```bash
+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: 提交知识图谱更新**
+
+```bash
+git add backend/graphify-out
+git commit -m "chore: refresh the backend code knowledge graph after sorting fixes."
+```
+