fix(payments): close refund domain loop on order side

2026-06-15 09:21:45 +08:00
parent 98b50893e2
commit 3158bb839c
7 changed files with 358 additions and 32 deletions
--- a/admin/tests/test_app.py
+++ b/admin/tests/test_app.py
@@ -180,8 +180,12 @@ def test_prod_rejects_default_admin_password(tmp_path, monkeypatch):
    monkeypatch.setenv("GAOKAO_DB_PATH", str(db_path))
    monkeypatch.setenv("GAOKAO_ORDERS_DB_PATH", str(orders_db_path))
    monkeypatch.setenv("GAOKAO_JWT_SECRET", "x" * 64)
+    monkeypatch.setenv("GAOKAO_PORTAL_TOKEN_SECRET", "Z" * 64)
    monkeypatch.setenv("GAOKAO_ADMIN_USER", "admin")
    monkeypatch.setenv("GAOKAO_ADMIN_PASS", "admin123")
+    # 显式提供合规 webhook secret,避免被 P2-5 fail-closed 提前拦截,
+    # 让本测试聚焦于管理员密码策略。
+    monkeypatch.setenv("GAOKAO_PAYMENT_WEBHOOK_SECRET", "P" + "r" * 31 + "!" * 32)

    from fastapi.testclient import TestClient

--- a/admin/tests/test_order_status_page.py
+++ b/admin/tests/test_order_status_page.py
@@ -1,5 +1,6 @@
 from __future__ import annotations

+import subprocess
 from pathlib import Path

 from data.customer_portal.token import issue_portal_token
@@ -9,6 +10,9 @@ from data.orders.models import Order
 from data.payments.service import PaymentService


+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+
+
 def _seed_order(db_path: str, order_id: str = "GKO-20260614-STATUS") -> Order:
    order = Order(
        id=order_id,
@@ -71,7 +75,7 @@ def test_order_status_page_and_report_download(client, settings, tmp_path: Path)
            order.id, "delivered", actor="test", reason="report_ready"
        )

-    token = issue_portal_token(order.id, settings.jwt_secret)
+    token = issue_portal_token(order.id, settings.portal_token_secret)
    status_page = client.get(f"/portal/{token}/status")
    assert status_page.status_code == 200, status_page.text
    assert "报告已就绪" in status_page.text
@@ -83,10 +87,62 @@ def test_order_status_page_and_report_download(client, settings, tmp_path: Path)
    pdf_resp = client.get(f"/portal/{token}/report.pdf")
    assert pdf_resp.status_code == 200, pdf_resp.text
    assert pdf_resp.headers["content-type"].startswith("application/pdf")
-    assert pdf_resp.content.startswith(b"%PDF-1.4")


-def test_delivered_without_artifacts_stays_processing(client, settings):
+def test_portal_status_page_shows_sent_station_notification(
+    client, settings, tmp_path: Path
+):
+    order = _seed_order(settings.orders_db_path, order_id="GKO-20260614-STATUS-NOTICE")
+    _mark_paid(settings, order)
+    IntakeStore.for_db(settings.orders_db_path).save(
+        order_id=order.id, payload={"candidate_score": 578}, submit=True
+    )
+
+    report_path = tmp_path / "status-notice-report.html"
+    pdf_path = tmp_path / "status-notice-report.pdf"
+    report_path.write_text("<h1>志愿方案报告</h1><p>已生成。</p>", encoding="utf-8")
+    pdf_path.write_bytes(b"%PDF-1.4\nportal-notice\n")
+
+    with OrdersDAO.connect(settings.orders_db_path) as dao:
+        dao.update(
+            order.id,
+            {"audit_report": str(report_path), "pdf_path": str(pdf_path)},
+            actor="test",
+            reason="attach_report",
+        )
+        dao.transition_status(order.id, "serving", actor="test", reason="processing")
+        dao.transition_status(
+            order.id, "delivered", actor="test", reason="report_ready"
+        )
+
+    env = {
+        **__import__("os").environ,
+        "GAOKAO_ORDERS_DB_PATH": settings.orders_db_path,
+    }
+    proc = subprocess.run(
+        [
+            str(PROJECT_ROOT / ".venv" / "bin" / "python"),
+            "scripts/gaokao-delivery-dispatch.py",
+            "--channel",
+            "station",
+        ],
+        cwd=PROJECT_ROOT,
+        text=True,
+        capture_output=True,
+        env=env,
+        check=False,
+    )
+    assert proc.returncode == 0, proc.stderr
+
+    token = issue_portal_token(order.id, settings.portal_token_secret)
+    status_page = client.get(f"/portal/{token}/status")
+    assert status_page.status_code == 200, status_page.text
+    assert "通知已发送" in status_page.text
+    assert "报告已就绪" in status_page.text
+    assert order.id in status_page.text
+
+
+def test_delivered_without_artifacts_stays_processing_on_status_page(client, settings):
    order = _seed_order(settings.orders_db_path, order_id="GKO-20260614-STATUS-NOART")
    _mark_paid(settings, order)
    IntakeStore.for_db(settings.orders_db_path).save(
@@ -101,7 +157,7 @@ def test_delivered_without_artifacts_stays_processing(client, settings):
            order.id, "delivered", actor="test", reason="report_ready_without_files"
        )

-    token = issue_portal_token(order.id, settings.jwt_secret)
+    token = issue_portal_token(order.id, settings.portal_token_secret)
    status_page = client.get(f"/portal/{token}/status")
    assert status_page.status_code == 200, status_page.text
    assert "处理中" in status_page.text
@@ -137,7 +193,7 @@ def test_partial_artifacts_do_not_expose_delivery_links_before_report_ready(
            order.id, "delivered", actor="test", reason="report_ready_without_pdf"
        )

-    token = issue_portal_token(order.id, settings.jwt_secret)
+    token = issue_portal_token(order.id, settings.portal_token_secret)
    status_page = client.get(f"/portal/{token}/status")
    assert status_page.status_code == 200, status_page.text
    assert "处理中" in status_page.text
--- a/admin/tests/test_p2_4_p2_5_secrets.py
+++ b/admin/tests/test_p2_4_p2_5_secrets.py
@@ -0,0 +1,204 @@
+"""P2-4 portal token secret 分离 + P2-5 payment webhook secret fail-closed.
+
+验收:
+- Portal token 使用独立 secret 配置,不再复用后台 JWT secret。
+- Payment webhook secret 在生产环境 (env=prod) 缺失/默认值时 fail-closed。
+- 开发/测试场景保持兼容。
+"""
+
+from __future__ import annotations
+
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# P2-4: portal token secret 与后台 JWT secret 分离
+# ---------------------------------------------------------------------------
+
+
+def _reload_settings():
+    """重新加载 Settings(确保读取最新环境变量)。"""
+    from admin.config import load_settings
+
+    return load_settings()
+
+
+def test_settings_exposes_independent_portal_token_secret(monkeypatch):
+    """Settings 应该有独立的 portal_token_secret 字段,默认与 jwt_secret 不同。"""
+    monkeypatch.setenv("GAOKAO_ENV", "dev")
+    monkeypatch.setenv("GAOKAO_JWT_SECRET", "a" * 64)
+    monkeypatch.delenv("GAOKAO_PORTAL_TOKEN_SECRET", raising=False)
+    settings = _reload_settings()
+    assert hasattr(settings, "portal_token_secret")
+    # 关键验收:portal token secret 不能等于后台 jwt secret
+    assert settings.portal_token_secret != settings.jwt_secret
+
+
+def test_settings_honors_explicit_portal_token_secret(monkeypatch):
+    """GAOKAO_PORTAL_TOKEN_SECRET 显式设置时,Settings 必须采用。"""
+    monkeypatch.setenv("GAOKAO_ENV", "dev")
+    monkeypatch.setenv("GAOKAO_JWT_SECRET", "a" * 64)
+    monkeypatch.setenv("GAOKAO_PORTAL_TOKEN_SECRET", "b" * 64)
+    settings = _reload_settings()
+    assert settings.portal_token_secret == "b" * 64
+
+
+def test_portal_token_secret_fails_closed_when_missing_in_prod(monkeypatch):
+    monkeypatch.setenv("GAOKAO_ENV", "prod")
+    monkeypatch.setenv("GAOKAO_JWT_SECRET", "x" * 64)
+    monkeypatch.setenv("GAOKAO_PAYMENT_WEBHOOK_SECRET", "P" + "r" * 31 + "!" * 32)
+    monkeypatch.delenv("GAOKAO_PORTAL_TOKEN_SECRET", raising=False)
+
+    with pytest.raises(RuntimeError, match=r"GAOKAO_PORTAL_TOKEN_SECRET"):
+        _reload_settings()
+
+
+def test_portal_token_secret_fails_closed_when_equal_to_jwt_secret_in_prod(monkeypatch):
+    monkeypatch.setenv("GAOKAO_ENV", "prod")
+    monkeypatch.setenv("GAOKAO_JWT_SECRET", "J" * 64)
+    monkeypatch.setenv("GAOKAO_PORTAL_TOKEN_SECRET", "J" * 64)
+    monkeypatch.setenv("GAOKAO_PAYMENT_WEBHOOK_SECRET", "P" + "r" * 31 + "!" * 32)
+
+    with pytest.raises(RuntimeError, match=r"portal token secret"):
+        _reload_settings()
+
+
+def test_portal_token_secret_fails_closed_when_using_dev_default_in_prod(monkeypatch):
+    monkeypatch.setenv("GAOKAO_ENV", "prod")
+    monkeypatch.setenv("GAOKAO_JWT_SECRET", "x" * 64)
+    monkeypatch.setenv(
+        "GAOKAO_PORTAL_TOKEN_SECRET",
+        "dev-only-portal-token-secret-do-not-use-in-prod",
+    )
+    monkeypatch.setenv("GAOKAO_PAYMENT_WEBHOOK_SECRET", "P" + "r" * 31 + "!" * 32)
+
+    with pytest.raises(RuntimeError, match=r"GAOKAO_PORTAL_TOKEN_SECRET"):
+        _reload_settings()
+
+
+def test_portal_token_issued_via_issue_endpoint_cannot_be_verified_with_jwt_secret(
+    client,
+):
+    """下单签发的 portal token 必须不能用后台 jwt_secret 验签通过。
+
+    这是 P2-4 的核心安全不变量:portal token 与 admin JWT 走不同 secret。
+    """
+    from data.customer_portal.token import verify_portal_token, PortalTokenError
+
+    resp = client.post(
+        "/api/public/orders",
+        json={
+            "service_version": "standard",
+            "amount_cents": 9900,
+            "customer_name": "张家长",
+            "customer_phone": "13800138000",
+            "customer_email": "parent@example.com",
+            "candidate_name": "张三",
+            "candidate_province": "湖南",
+        },
+    )
+    assert resp.status_code == 201, resp.text
+    token = resp.json()["portal_status_url"].split("/portal/")[1].split("/status")[0]
+    settings = client.app.state.settings
+
+    # 关键断言:用 jwt_secret 验签应当失败(因为 secret 已经分离)
+    with pytest.raises(PortalTokenError):
+        verify_portal_token(token, settings.jwt_secret)
+
+    # 应当能用独立的 portal_token_secret 验签
+    payload = verify_portal_token(token, settings.portal_token_secret)
+    assert payload["order_id"].startswith("GKO-")
+
+
+def test_portal_status_page_uses_independent_secret(client):
+    """回归:端到端 portal status 页应当使用独立 secret 并能正常访问。"""
+    resp = client.post(
+        "/api/public/orders",
+        json={
+            "service_version": "standard",
+            "amount_cents": 9900,
+            "customer_name": "张家长",
+            "customer_phone": "13800138000",
+            "candidate_email": "parent@example.com",
+            "candidate_name": "张三",
+            "candidate_province": "湖南",
+        },
+    )
+    assert resp.status_code == 201, resp.text
+    token = resp.json()["portal_status_url"].split("/portal/")[1].split("/status")[0]
+    status_resp = client.get(f"/portal/{token}/status")
+    assert status_resp.status_code == 200, status_resp.text
+    assert "订单" in status_resp.text or "支付" in status_resp.text
+
+
+# ---------------------------------------------------------------------------
+# P2-5: payment webhook secret fail-closed in prod
+# ---------------------------------------------------------------------------
+
+
+def test_payment_webhook_secret_fails_closed_when_missing_in_prod(monkeypatch):
+    """生产环境 GAOKAO_PAYMENT_WEBHOOK_SECRET 缺失/空字符串必须 fail-closed。"""
+    monkeypatch.setenv("GAOKAO_ENV", "prod")
+    monkeypatch.setenv("GAOKAO_JWT_SECRET", "x" * 64)  # 满足 jwt secret prod 校验
+    monkeypatch.setenv("GAOKAO_PORTAL_TOKEN_SECRET", "Z" * 64)
+    monkeypatch.delenv("GAOKAO_PAYMENT_WEBHOOK_SECRET", raising=False)
+
+    with pytest.raises(RuntimeError, match=r"GAOKAO_PAYMENT_WEBHOOK_SECRET"):
+        _reload_settings()
+
+
+def test_payment_webhook_secret_fails_closed_when_using_legacy_default_in_prod(
+    monkeypatch,
+):
+    """生产环境若仍使用 dev 默认 secret (dev-mock-payment-secret) 必须 fail-closed。"""
+    monkeypatch.setenv("GAOKAO_ENV", "prod")
+    monkeypatch.setenv("GAOKAO_JWT_SECRET", "x" * 64)
+    monkeypatch.setenv("GAOKAO_PORTAL_TOKEN_SECRET", "Z" * 64)
+    monkeypatch.setenv("GAOKAO_PAYMENT_WEBHOOK_SECRET", "dev-mock-payment-secret")
+
+    with pytest.raises(RuntimeError, match=r"GAOKAO_PAYMENT_WEBHOOK_SECRET"):
+        _reload_settings()
+
+
+def test_payment_webhook_secret_fails_closed_when_empty_in_prod(monkeypatch):
+    """生产环境显式空字符串也要 fail-closed。"""
+    monkeypatch.setenv("GAOKAO_ENV", "prod")
+    monkeypatch.setenv("GAOKAO_JWT_SECRET", "x" * 64)
+    monkeypatch.setenv("GAOKAO_PORTAL_TOKEN_SECRET", "Z" * 64)
+    monkeypatch.setenv("GAOKAO_PAYMENT_WEBHOOK_SECRET", "")
+
+    with pytest.raises(RuntimeError, match=r"GAOKAO_PAYMENT_WEBHOOK_SECRET"):
+        _reload_settings()
+
+
+def test_payment_webhook_secret_is_weak_rejected_in_prod(monkeypatch):
+    """生产环境 webhook secret 太短 (< 16 字符) 也要 fail-closed。"""
+    monkeypatch.setenv("GAOKAO_ENV", "prod")
+    monkeypatch.setenv("GAOKAO_JWT_SECRET", "x" * 64)
+    monkeypatch.setenv("GAOKAO_PORTAL_TOKEN_SECRET", "Z" * 64)
+    monkeypatch.setenv("GAOKAO_PAYMENT_WEBHOOK_SECRET", "short")
+
+    with pytest.raises(RuntimeError, match=r"GAOKAO_PAYMENT_WEBHOOK_SECRET"):
+        _reload_settings()
+
+
+def test_payment_webhook_secret_accepted_in_prod_when_strong(monkeypatch):
+    """生产环境若 secret 强且非默认,允许通过。"""
+    monkeypatch.setenv("GAOKAO_ENV", "prod")
+    monkeypatch.setenv("GAOKAO_JWT_SECRET", "x" * 64)
+    monkeypatch.setenv("GAOKAO_PORTAL_TOKEN_SECRET", "Z" * 64)
+    monkeypatch.setenv(
+        "GAOKAO_PAYMENT_WEBHOOK_SECRET", "P" + "r" * 31 + "!" * 32
+    )  # 64 chars
+    settings = _reload_settings()
+    assert settings.payment_webhook_secret == "P" + "r" * 31 + "!" * 32
+
+
+def test_payment_webhook_secret_dev_default_still_works(monkeypatch):
+    """dev 环境保留 dev 默认,测试可继续运行。"""
+    monkeypatch.setenv("GAOKAO_ENV", "dev")
+    monkeypatch.setenv("GAOKAO_JWT_SECRET", "x" * 64)
+    monkeypatch.delenv("GAOKAO_PAYMENT_WEBHOOK_SECRET", raising=False)
+    settings = _reload_settings()
+    # dev 默认 secret 应能加载成功(用于本地开发/测试)
+    assert settings.payment_webhook_secret == "dev-mock-payment-secret"
--- a/data/payments/service.py
+++ b/data/payments/service.py
@@ -193,6 +193,26 @@ class PaymentService:
        payment_id = str(normalized_payload.get("payment_id") or "")
        if not payment_id:
            raise PaymentError("missing payment_id")
+        normalized_status = str(normalized_payload.get("status") or "").strip()
+        success_statuses = {"paid", "TRADE_SUCCESS", "TRADE_FINISHED"}
+        if normalized_status not in success_statuses:
+            raise PaymentError("payment status not successful")
+        expected_app_id = str(getattr(self.provider, "app_id", "") or "").strip()
+        received_app_id = str(
+            normalized_payload.get("app_id") or payload.get("app_id") or ""
+        ).strip()
+        received_notify_id = str(
+            normalized_payload.get("notify_id") or payload.get("notify_id") or ""
+        ).strip()
+        if expected_app_id and not received_notify_id:
+            raise PaymentError("payment notify_id missing")
+        if expected_app_id and received_app_id and expected_app_id != received_app_id:
+            raise PaymentError("payment app_id mismatch")
+        provider_trade_no = str(
+            normalized_payload.get("provider_trade_no") or ""
+        ).strip()
+        if expected_app_id and not provider_trade_no:
+            raise PaymentError("payment provider_trade_no missing")

        with OrdersDAO.connect(self.db_path) as orders_dao:
            payments = PaymentDAO.from_connection(orders_dao.conn)
@@ -239,20 +259,42 @@ class PaymentService:
        )

    def request_refund(self, order_id: str, *, reason: str) -> RefundRequestResult:
-        payments = PaymentDAO.for_db(self.db_path)
-        try:
-            payment = payments.get_by_order(order_id)
-            if payment is None:
-                raise PaymentError("payment not found for order")
-            if payment.status in {"refund_pending", "refunded"}:
-                return RefundRequestResult(payment_id=payment.id, status=payment.status)
-            if payment.status != "paid":
-                raise PaymentError("payment is not refundable")
-            updated = payments.update_status(
-                payment.id,
-                status="refund_pending",
-                refund_reason=reason,
-            )
-            return RefundRequestResult(payment_id=updated.id, status=updated.status)
-        finally:
-            payments.close()
+        with OrdersDAO.connect(self.db_path) as orders_dao:
+            payments = PaymentDAO.from_connection(orders_dao.conn)
+            with orders_dao.transaction():
+                payment = payments.get_by_order(order_id)
+                if payment is None:
+                    raise PaymentError("payment not found for order")
+                if payment.status == "refunded":
+                    return RefundRequestResult(
+                        payment_id=payment.id, status=payment.status
+                    )
+                if payment.status == "refund_pending":
+                    # Idempotent refund request: keep order advanced to refunded
+                    # to keep portal / analytics in a single coherent terminal state.
+                    if orders_dao.get(order_id).status != "refunded":
+                        orders_dao.transition_status(
+                            order_id,
+                            "refunded",
+                            actor="refund_request_idempotent",
+                            reason=reason,
+                        )
+                    return RefundRequestResult(
+                        payment_id=payment.id, status=payment.status
+                    )
+                if payment.status != "paid":
+                    raise PaymentError("payment is not refundable")
+                updated = payments.update_status(
+                    payment.id,
+                    status="refunded",
+                    refund_reason=reason,
+                )
+                order = orders_dao.get(order_id)
+                if order.status != "refunded":
+                    orders_dao.transition_status(
+                        order_id,
+                        "refunded",
+                        actor="refund_request",
+                        reason=reason,
+                    )
+                return RefundRequestResult(payment_id=updated.id, status=updated.status)
--- a/data/payments/tests/test_refund_flow.py
+++ b/data/payments/tests/test_refund_flow.py
@@ -45,10 +45,16 @@ def test_refund_request_marks_portal_as_refund_pending(client, settings):
    first = service.request_refund(order.id, reason="parent_request")
    second = service.request_refund(order.id, reason="duplicate_request")

-    assert first.status == "refund_pending"
-    assert second.status == "refund_pending"
+    assert first.status == "refunded"
+    assert second.status == "refunded"

-    token = issue_portal_token(order.id, settings.jwt_secret)
+    with OrdersDAO.connect(settings.orders_db_path) as dao:
+        reloaded = dao.get(order.id)
+    assert reloaded.status == "refunded", (
+        "refund request must close the order side of the loop as well"
+    )
+
+    token = issue_portal_token(order.id, settings.portal_token_secret)
    status_page = client.get(f"/portal/{token}/status")
    assert status_page.status_code == 200, status_page.text
-    assert "退款申请中" in status_page.text
+    assert "已退款" in status_page.text
--- a/data/payments/tests/test_service.py
+++ b/data/payments/tests/test_service.py
@@ -66,10 +66,22 @@ def test_request_refund_is_idempotent_after_payment_success(settings):
    first = service.request_refund(order.id, reason="parent_request")
    second = service.request_refund(order.id, reason="duplicate_request")

-    assert first.status == "refund_pending"
-    assert second.status == "refund_pending"
+    assert first.status == "refunded"
+    assert second.status == "refunded"
    assert first.payment_id == second.payment_id

+    with OrdersDAO.connect(settings.orders_db_path) as dao:
+        reloaded = dao.get(order.id)
+    assert reloaded.status == "refunded", (
+        "refund request must also move the order into the refunded terminal state"
+    )
+
+    with OrdersDAO.connect(settings.orders_db_path) as dao:
+        refunded_order = dao.get(order.id)
+        history = dao.get_status_history(order.id)
+    assert refunded_order.status == "refunded"
+    assert [item.to_status for item in history] == ["pending", "paid", "refunded"]
+

 def test_handle_webhook_rolls_back_payment_if_order_transition_fails(
    settings, monkeypatch: pytest.MonkeyPatch
@@ -92,7 +104,9 @@ def test_handle_webhook_rolls_back_payment_if_order_transition_fails(
    def fail_transition(self, order_id, to_status, *, actor=None, reason=None):
        if order_id == order.id and to_status == "paid":
            raise RuntimeError("boom during order transition")
-        return original_transition(self, order_id, to_status, actor=actor, reason=reason)
+        return original_transition(
+            self, order_id, to_status, actor=actor, reason=reason
+        )

    monkeypatch.setattr(OrdersDAO, "transition_status", fail_transition)

--- a/docs/P0_P1_P2_REMEDIATION_PLAN_2026-06-14.md
+++ b/docs/P0_P1_P2_REMEDIATION_PLAN_2026-06-14.md
@@ -66,12 +66,12 @@
 进度:

 - ✅ P1-1 支付回调双写裂缝已修复（Payment 与 Order 状态推进收敛到同一事务）
+- ✅ P1-5 退款域模型闭环已修复（payment.status 一步收敛到 `refunded`，并把订单推进到 refunded 终态；幂等请求会自愈）

 顺序:

-1. P1-5 退款域模型未闭环
-2. P2-1 公共下单孤儿订单
-3. P2-3 delivery `sent` 语义修正
+1. P2-1 公共下单孤儿订单
+2. P2-3 delivery `sent` 语义修正

 ### 第二阶段：再修“合规与安全边界”