# 后端既有基线测试失败修复 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."
```

### 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 可视化已刷新。