dcjxb.microservice/docs/plans/2026-04-13-outlook-report-style-alignment.md

Outlook Report Style Alignment Implementation Plan

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

Goal: Rebuild the Outlook PDF report so its visual hierarchy, module naming, and card/chart presentation are highly similar to the provided reference HTML while keeping the current request payload and Playwright rendering pipeline.

Architecture: Keep the existing async report flow and server-side HTML-to-PDF conversion. Replace the current template with a print-safe layout that mirrors the reference page structure, render charts as server-generated inline SVG or static HTML fragments instead of browser JavaScript, and stabilize typography through explicit font handling that works with Playwright/Chromium PDF output.

Tech Stack: Java 17+, Spring components, Playwright Java, server-side HTML template rendering, JUnit 5 / AssertJ, Maven multi-module build.

---

Task 1: Lock the new reference-oriented output contract with tests

Files:

• Modify: ability-integration/src/test/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRendererTest.java
• Optional create if helpful: ability-integration/src/test/resources/outlook-report/reference-style-notes.txt

Step 1: Write the failing test

Update renderBuildsStructuredOutlookReportWithChartsAndModules() so it asserts the new high-similarity structure instead of the current MVP wording. The test should verify at least these strings/fragments are present in rendered HTML:

assertThat(html).contains("高考英语临考词汇突击潜力展望报告");
assertThat(html).contains("科学规划 · 精准提分 · 短期见效");
assertThat(html).contains("模块一：个人学情分析");
assertThat(html).contains("模块二：科学备考建议");
assertThat(html).contains("模块三：上届学员提分案例");
assertThat(html).contains("report-container");
assertThat(html).contains("analysis-grid");
assertThat(html).contains("frequency-grid");
assertThat(html).contains("student-case");
assertThat(html).doesNotContain("https://cdn.jsdelivr.net");

Keep the PDF smoke test and add 1-2 assertions that rendered HTML contains inline chart markup expected by the new chart strategy (for example <svg or a stable chart wrapper class).

Step 2: Run test to verify it fails

Run:

mvn -pl ability-integration -Dtest=ClasspathOutlookReportHtmlRendererTest test

Expected: FAIL because the current template still uses the old “hero / 词汇掌握诊断 / 方案建议 / 案例拆解” structure.

Step 3: Write minimal implementation target notes in the test fixture

Inside the test class, refresh sampleRequest() copy where needed so the sample data reads naturally in the new three-module layout. Do not change the request schema; only adjust sample values if they help the new assertions stay meaningful.

Step 4: Run test again after edits

Run the same command and confirm the failure message now points to missing new structure/classes rather than a broken test.

Step 5: Commit

Only if the user explicitly requests commits later:

git add ability-integration/src/test/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRendererTest.java
git commit -m "test: define outlook report reference-style expectations"

Task 2: Rebuild the HTML template to match the reference page structure

Files:

• Modify: ability-integration/src/main/resources/templates/outlook-report-template.html
• Reference only: /Users/exiao/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/wxid_3350043499412_c79f/msg/file/2026-04/临考突击展望报告-设计.html
• Test: ability-integration/src/test/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRendererTest.java

Step 1: Write the failing test

Use the Task 1 assertions as the guardrail. Add at least one assertion for a reference-style title block and one for each major module container.

Step 2: Run test to verify it fails

Run:

mvn -pl ability-integration -Dtest=ClasspathOutlookReportHtmlRendererTest#renderBuildsStructuredOutlookReportWithChartsAndModules test

Expected: FAIL.

Step 3: Write minimal implementation

Rewrite outlook-report-template.html as a print-safe version of the reference HTML:

• Replace the current hero block with a centered title/subtitle section using:
  • 高考英语临考词汇突击潜力展望报告
  • 科学规划 · 精准提分 · 短期见效
• Replace the current section order with exactly three modules:
  1. 模块一：个人学情分析
  2. 模块二：科学备考建议
  3. 模块三：上届学员提分案例
• Use print-safe containers and avoid depending on browser JS.
• Keep CSS self-contained in <style> and prefer table/block/fixed-width constructs over advanced browser-only layout.
• Mirror the reference color system (#2b4c8a, #ff7d00, light blue cards, warm case-study panel) and spacing as closely as practical.
• Introduce stable class names aligned with the reference where useful: report-container, report-title, report-subtitle, section, analysis-grid, card, frequency-grid, freq-card, suggest-box, student-case, case-info.
• Preserve @page and A4-friendly margins.

Do not copy the external <script> tag or any ECharts initialization code into the PDF template.

Step 4: Run test to verify it passes

Run the focused test command from Step 2.

Expected: PASS for structural assertions.

Step 5: Commit

Only if the user explicitly requests commits later:

git add ability-integration/src/main/resources/templates/outlook-report-template.html ability-integration/src/test/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRendererTest.java
git commit -m "feat: align outlook pdf template with reference layout"

Task 3: Remap renderer output into the new three-module narrative

Files:

• Modify: ability-integration/src/main/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRenderer.java
• Test: ability-integration/src/test/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRendererTest.java

Step 1: Write the failing test

Extend assertions so sample content lands in the correct module wording. Examples:

assertThat(html).contains("考纲词汇掌握情况");
assertThat(html).contains("真题试卷词汇掌握情况");
assertThat(html).contains("常考词汇掌握情况");
assertThat(html).contains("词频区间掌握度");
assertThat(html).contains("练习学案频率与提分规划");
assertThat(html).contains("真实提分 · 效果可复制");

Step 2: Run test to verify it fails

Run:

mvn -pl ability-integration -Dtest=ClasspathOutlookReportHtmlRendererTest#renderBuildsStructuredOutlookReportWithChartsAndModules test

Expected: FAIL because placeholders are still mapped to the old copy and card structure.

Step 3: Write minimal implementation

Update ClasspathOutlookReportHtmlRenderer so it feeds the new template structure without changing the request schema:

• Map current overview/syllabus/vocabulary/frequency/case-study data into the three reference-style modules.
• Rebuild helper methods so they output reference-style fragments:
  • analysis cards for module one
  • recommendation/frequency cards for module two
  • highlighted case-study content for module three
• Keep escaping for all user-controlled text.
• Avoid introducing external assets or runtime dependencies.

If a reference block needs a value not directly present in the payload, derive a reasonable display value from existing fields rather than changing CreateOutlookReportTaskRequest.

Step 4: Run test to verify it passes

Run the focused renderer test again.

Expected: PASS.

Step 5: Commit

Only if the user explicitly requests commits later:

git add ability-integration/src/main/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRenderer.java ability-integration/src/test/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRendererTest.java
git commit -m "feat: remap outlook report content into reference-style modules"

Task 4: Upgrade chart rendering to print-safe charts that resemble the reference

Files:

• Modify: ability-integration/src/main/java/cn/yunzhixue/microservice/ability/report/outlook/integration/OutlookReportSvgChartBuilder.java
• Modify if needed: ability-integration/src/main/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRenderer.java
• Test: ability-integration/src/test/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRendererTest.java

Step 1: Write the failing test

Add assertions that the rendered HTML contains stable chart wrappers for the new chart forms, for example:

assertThat(html).contains("analysis-chart");
assertThat(html).contains("frequency-grid");
assertThat(html).contains("case-chart");
assertThat(html).contains("<svg");

Step 2: Run test to verify it fails

Run:

mvn -pl ability-integration -Dtest=ClasspathOutlookReportHtmlRendererTest#renderBuildsStructuredOutlookReportWithChartsAndModules test

Expected: FAIL.

Step 3: Write minimal implementation

Refactor OutlookReportSvgChartBuilder so it produces print-safe chart fragments that visually echo the reference:

• Donut/ring-style chart or equivalent summary graphic for syllabus/case sections
• Simple vertical/horizontal bar chart markup for exam/common/frequency comparisons
• Frequency recommendation cards with inline percent fills rendered as CSS backgrounds or inline SVG, avoiding JS

Prefer inline SVG when it materially improves fidelity and remains deterministic in Playwright-generated PDFs. Keep all text escaped.

Step 4: Run tests to verify they pass

Run:

mvn -pl ability-integration -Dtest=ClasspathOutlookReportHtmlRendererTest test

Expected: PASS, including the existing PDF smoke test.

Step 5: Commit

Only if the user explicitly requests commits later:

git add ability-integration/src/main/java/cn/yunzhixue/microservice/ability/report/outlook/integration/OutlookReportSvgChartBuilder.java ability-integration/src/main/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRenderer.java ability-integration/src/test/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRendererTest.java
git commit -m "feat: add print-safe reference-style outlook charts"

Task 5: Stabilize font behavior and verify PDF rendering output

Files:

• Modify: ability-integration/src/main/java/cn/yunzhixue/microservice/ability/report/outlook/integration/PlaywrightOutlookReportPdfGenerator.java
• Create if approved/available: ability-integration/src/main/resources/fonts/<chosen-cjk-font-file>
• Test: ability-integration/src/test/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRendererTest.java

Step 1: Write the failing test or assertion target

Preserve the existing %PDF smoke assertion and add renderer assertions that confirm the template uses the intended font-family stack/class names for the new layout.

Step 2: Run test to establish baseline

Run:

mvn -pl ability-integration -Dtest=ClasspathOutlookReportHtmlRendererTest#renderedOutlookReportCanBeConvertedToPdf test

Expected: PASS before font hardening, or at least establish baseline behavior.

Step 3: Write minimal implementation

Improve font stability in one of these ways, preferring the first if a licensed font file is available in-repo:

1. Register a bundled CJK font from src/main/resources/fonts/
2. Otherwise expand the font registration/fallback stack and template font-family so the rendered PDF is acceptable on macOS and Linux

Do not break current environments that rely on system fonts.

Step 4: Run verification

Run:

mvn -pl ability-integration test

Expected: PASS.

If practical, also run a manual local smoke flow to regenerate one PDF and inspect typography.

Step 5: Commit

Only if the user explicitly requests commits later:

git add ability-integration/src/main/java/cn/yunzhixue/microservice/ability/report/outlook/integration/PlaywrightOutlookReportPdfGenerator.java ability-integration/src/main/resources/fonts
git commit -m "fix: stabilize outlook pdf font rendering"

Task 6: End-to-end verification of the updated report look

Files:

• No mandatory source changes
• Verify against: ability-bootstrap/scripts/outlook-report-demo.sh

Step 1: Run module tests

Run:

mvn -pl ability-integration test

Expected: PASS.

Step 2: Run full report flow locally

Run the app/service as needed, then submit a report and download the resulting PDF using the existing curl flow or demo script.

Example verification targets:

• PDF downloads successfully
• New title/subtitle render correctly
• Three-module layout appears in the PDF
• Charts are visible without JS
• Chinese text and emphasized numbers are legible
• A4 pagination is acceptable

Step 3: Record any fidelity gaps

If the PDF is still meaningfully different from the reference, capture the remaining gaps in bullet form next to the changed files so a follow-up pass is easy.

Step 4: Commit

Only if the user explicitly requests commits later.

git add .
git commit -m "feat: restyle outlook pdf report to match reference"

Notes for the implementer

• The reference HTML contains ECharts and browser JS. Do not port those scripts directly.
• Keep the current request DTO unchanged for this “A: high similarity” scope.
• Prefer deterministic server-rendered markup over clever CSS that makes Playwright PDF output unstable.
• When unsure between visual fidelity and PDF stability, choose the more stable print-safe implementation.
• Before claiming success, attach evidence from test output and at least one rendered PDF.