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

后端既有基线测试失败修复设计

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 列表排序

三个待修复查询统一使用：

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 相同时仍按创建时间倒序。