From b2ea79710c1d483175df94d62456f2f79fae494b Mon Sep 17 00:00:00 2001
From: zlwu <704541015@qq.com>
Date: Sun, 11 Oct 2026 09:47:52 +0800
Subject: [PATCH] docs: describe how to resolve the existing backend test
 failures.

---
 ...ckend-baseline-test-failures-fix-design.md | 51 +++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-10-11-backend-baseline-test-failures-fix-design.md

diff --git a/docs/superpowers/specs/2026-10-11-backend-baseline-test-failures-fix-design.md b/docs/superpowers/specs/2026-10-11-backend-baseline-test-failures-fix-design.md
new file mode 100644
index 00000000..27d2e7f3
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-11-backend-baseline-test-failures-fix-design.md
@@ -0,0 +1,51 @@
+# 后端既有基线测试失败修复设计
+
+## 1. 目标
+
+修复后端全量测试中的 4 个既有失败，同时不扩大接口加密能力范围，不改变与前端已经稳定使用的 AES-GCM 协议。
+
+## 2. 问题与根因
+
+1. `test_encrypt_decrypt_roundtrip_cbc` 向 `encrypt_json`、`decrypt_json` 传入不存在的 `alg="cbc"` 参数。当前后端和 Web 管理端均只实现 AES-GCM，该测试与实际加密协议不一致。
+2. `list_audits`、`list_receipt_confirm_details`、`list_refund_confirm_details` 只按 `create_time DESC` 排序，遗漏测试和业务模型约定的 `order_num ASC` 优先级。
+
+## 3. 方案
+
+### 3.1 加密测试
+
+- 保持 `encrypt_json(payload, key)` 和 `decrypt_json(cipher_text, key)` 的 AES-GCM 单一接口，不增加 CBC 分支。
+- 删除失效的 CBC 往返测试，改为 AES-GCM 密文篡改拒绝测试。
+- 篡改测试必须断言 `decrypt_json` 抛出 `ApiCryptoError`，从而保留并增强认证加密的安全回归覆盖。
+
+不选择 CBC 兼容方案，因为前端没有 CBC 调用，加密中间件也没有算法协商字段；仅为通过遗留测试增加 CBC 会扩大协议和安全维护面。
+
+### 3.2 列表排序
+
+三个待修复查询统一使用：
+
+```python
+order_by(Model.order_num.asc(), Model.create_time.desc())
+```
+
+具体对应：
+
+- 协议审核列表：`BizProtocolAudit.order_num ASC, create_time DESC`；
+- 缴费待确认列表：`BizProtocolPaymentDetail.order_num ASC, create_time DESC`；
+- 退款待确认列表：`BizProtocolPaymentDetail.order_num ASC, create_time DESC`。
+
+不修改已确认列表的 `update_time DESC` 排序，因为相关测试已经通过，且它表达的是处理完成时间顺序。
+
+## 4. 测试策略
+
+1. 红灯基线：保留三个现有排序失败；先将 CBC 测试改成 AES-GCM 篡改测试并确认当前实现能够满足该安全契约。
+2. 绿灯实现：只修改三个 `order_by` 调用。
+3. 定向验证：运行 `test_api_crypto.py` 与 `test_collection_protocol_conventions.py`。
+4. 全量验证：运行后端全部 pytest 用例，目标为 0 failed。
+5. 按仓库约定执行 `./scripts/update-graph.sh backend`，再确认工作区差异只包含本次修复和既有用户改动。
+
+## 5. 影响范围
+
+- 不修改数据库结构或数据，不需要 SQL 迁移。
+- 不修改前端接口格式、密钥派生方式或部署配置。
+- 仅影响三个列表中 `order_num` 非相同记录的展示顺序；`order_num` 相同时仍按创建时间倒序。
+