dcjxb.microservice/docs/plans/2026-04-29-playwright-print-css.md

Playwright Print-Friendly CSS Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: 将考试冲刺报告模板中的 CSS 收敛为 Playwright/Chromium PDF 稳定的 print-friendly CSS，并保持 PDF 文本与版式结构稳定。

Architecture: 只修改资源模板与模板兼容性测试，不改 PDF 生成器行为。使用现有 OutlookExamSprintReportTemplateCompatibilityTest 作为 CSS 合约测试，先新增“不包含不稳定打印属性/选择器”的失败断言，再调整 outlook-exam-sprint-report-template.html。

Tech Stack: Java 17, Maven, JUnit 5, AssertJ, Spring ClassPathResource, Playwright Java, HTML/CSS template resources.

---

Task 1: Outlook 模板 CSS 兼容 Playwright PDF 输出

Files:

• Modify: abilities/exam-sprint/infrastructure/src/test/java/cn/yunzhixue/ability/center/examsprint/infrastructure/report/rendering/outlook/OutlookExamSprintReportTemplateCompatibilityTest.java
• Modify: abilities/exam-sprint/infrastructure/src/main/resources/templates/outlook-exam-sprint-report-template.html

Step 1: Write the failing test

In OutlookExamSprintReportTemplateCompatibilityTest.templateMatchesDesignDraftWithPdfSafeLayoutStyles, update the compatibility assertions so the normalized template:

assertThat(normalizedTemplate)
        .doesNotContain("-webkit-print-color-adjust")
        .doesNotContain("print-color-adjust")
        .doesNotContain("box-shadow")
        .doesNotContain("display: flex")
        .doesNotContain("flex-direction")
        .doesNotContain(":nth-of-type")
        .doesNotContain("break-before: page")
        .containsPattern("\\.card\\s*\\{[^}]*min-height\\s*:\\s*370px\\s*;[^}]*}")
        .containsPattern("\\.page-break-before-module2\\s*\\{[^}]*page-break-before\\s*:\\s*always\\s*;[^}]*}");

Also replace the old positive assertion requiring .card { display: flex; flex-direction: column; ... } with a print-safe .card assertion that keeps page-break-inside: avoid and min-height: 370px only.

Step 2: Run test to verify it fails

Run:

mvn -pl abilities/exam-sprint/infrastructure -am -Dtest=OutlookExamSprintReportTemplateCompatibilityTest test

Expected: FAIL if the current template still contains these print-unstable constructs: -webkit-print-color-adjust, print-color-adjust, box-shadow, display: flex, flex-direction, :nth-of-type, and break-before: page.

Step 3: Write minimal implementation

In outlook-exam-sprint-report-template.html:

1. Remove print color controls from body if they make Playwright PDF output unstable:

   -webkit-print-color-adjust: exact;
   print-color-adjust: exact;
   

2. Remove shadow from .report-container if it makes Playwright PDF output unstable:

   box-shadow: 0 2px 15px rgba(0, 0, 0, 0.06);
   

3. Remove flex declarations from .card while keeping existing block layout and sizing if the PDF layout is more stable without flex:

   display: flex;
   flex-direction: column;
   

4. Replace the print selector with a direct class on the second module section if the selector makes PDF layout verification brittle. Change HTML:

   <div class="section">
   

for module two to:

<div class="section module-section-two">

and replace CSS:

.section:nth-of-type(2) {
    margin-top: 0;
}

with:

.module-section-two {
    margin-top: 0;
}

1. Remove modern pagination declaration if Playwright PDF output is more stable with the legacy print pagination rule:

   break-before: page;
   page-break-before: always;
   

becomes:

page-break-before: always;

Step 4: Run test to verify it passes

Run:

mvn -pl abilities/exam-sprint/infrastructure -am -Dtest=OutlookExamSprintReportTemplateCompatibilityTest test

Expected: PASS.

Step 5: Run PDF smoke test and inspect parser warnings

Run:

mvn -pl abilities/exam-sprint/infrastructure -am -Dtest=PlaywrightExamSprintReportPdfGeneratorTest#generateCreatesReadablePdfForOutlookReportTemplate test

Expected: PASS. The Outlook PDF smoke test should render without relying on unstable print CSS constructs.

Step 6: Do not commit unless explicitly requested

Leave changes in the worktree for review. Report the absolute worktree path and verification commands.