|
|
@@ -0,0 +1,135 @@
|
|
|
+# OpenHTMLToPDF Print-Friendly CSS Implementation Plan
|
|
|
+
|
|
|
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
|
|
+
|
|
|
+**Goal:** 将考试冲刺报告模板中的现代浏览器 CSS 降级为 OpenHTMLToPDF 兼容的 print-friendly CSS，避免已知 CSS parser warning，并保持 PDF 文本与版式结构稳定。
|
|
|
+
|
|
|
+**Architecture:** 只修改资源模板与模板兼容性测试，不改 PDF 生成器行为。使用现有 `OutlookExamSprintReportTemplateCompatibilityTest` 作为 CSS 合约测试，先新增“不包含 OpenHTMLToPDF 不支持属性/选择器”的失败断言，再调整 `outlook-exam-sprint-report-template.html`。
|
|
|
+
|
|
|
+**Tech Stack:** Java 17, Maven, JUnit 5, AssertJ, Spring `ClassPathResource`, OpenHTMLToPDF, HTML/CSS template resources.
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Task 1: Outlook 模板 CSS 兼容 OpenHTMLToPDF
|
|
|
+
|
|
|
+**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:
|
|
|
+
|
|
|
+```java
|
|
|
+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:
|
|
|
+
|
|
|
+```bash
|
|
|
+mvn -pl abilities/exam-sprint/infrastructure -am -Dtest=OutlookExamSprintReportTemplateCompatibilityTest test
|
|
|
+```
|
|
|
+
|
|
|
+Expected: FAIL because current template still contains `-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 unsupported print color controls from `body`:
|
|
|
+
|
|
|
+```css
|
|
|
+-webkit-print-color-adjust: exact;
|
|
|
+print-color-adjust: exact;
|
|
|
+```
|
|
|
+
|
|
|
+2. Remove unsupported shadow from `.report-container`:
|
|
|
+
|
|
|
+```css
|
|
|
+box-shadow: 0 2px 15px rgba(0, 0, 0, 0.06);
|
|
|
+```
|
|
|
+
|
|
|
+3. Remove unsupported flex declarations from `.card` while keeping existing block layout and sizing:
|
|
|
+
|
|
|
+```css
|
|
|
+display: flex;
|
|
|
+flex-direction: column;
|
|
|
+```
|
|
|
+
|
|
|
+4. Replace the unsupported print selector with a direct class on the second module section. Change HTML:
|
|
|
+
|
|
|
+```html
|
|
|
+<div class="section">
|
|
|
+```
|
|
|
+
|
|
|
+for module two to:
|
|
|
+
|
|
|
+```html
|
|
|
+<div class="section module-section-two">
|
|
|
+```
|
|
|
+
|
|
|
+and replace CSS:
|
|
|
+
|
|
|
+```css
|
|
|
+.section:nth-of-type(2) {
|
|
|
+ margin-top: 0;
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+with:
|
|
|
+
|
|
|
+```css
|
|
|
+.module-section-two {
|
|
|
+ margin-top: 0;
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+5. Remove unsupported modern pagination declaration and keep legacy print pagination:
|
|
|
+
|
|
|
+```css
|
|
|
+break-before: page;
|
|
|
+page-break-before: always;
|
|
|
+```
|
|
|
+
|
|
|
+becomes:
|
|
|
+
|
|
|
+```css
|
|
|
+page-break-before: always;
|
|
|
+```
|
|
|
+
|
|
|
+**Step 4: Run test to verify it passes**
|
|
|
+
|
|
|
+Run:
|
|
|
+
|
|
|
+```bash
|
|
|
+mvn -pl abilities/exam-sprint/infrastructure -am -Dtest=OutlookExamSprintReportTemplateCompatibilityTest test
|
|
|
+```
|
|
|
+
|
|
|
+Expected: PASS.
|
|
|
+
|
|
|
+**Step 5: Run PDF smoke test and inspect parser warnings**
|
|
|
+
|
|
|
+Run:
|
|
|
+
|
|
|
+```bash
|
|
|
+mvn -pl abilities/exam-sprint/infrastructure -am -Dtest=OpenHtmlToPdfExamSprintReportPdfGeneratorTest#generateCreatesPdfSmokeWithExtractableOutlookKeyText test
|
|
|
+```
|
|
|
+
|
|
|
+Expected: PASS. The prior OpenHTMLToPDF CSS parser warnings for `-webkit-print-color-adjust`, `print-color-adjust`, `box-shadow`, `flex`, `flex-direction`, `nth-of-type`, and `Value page` should no longer appear for the Outlook PDF smoke test.
|
|
|
+
|
|
|
+**Step 6: Do not commit unless explicitly requested**
|
|
|
+
|
|
|
+Leave changes in the worktree for review. Report the absolute worktree path and verification commands.
|
