# 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:

```java
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```java
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:

```bash
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:

```bash
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:

```java
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.

```bash
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.