# 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 openhtmltopdf 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 in openhtmltopdf.

**Tech Stack:** Java 17+, Spring components, openhtmltopdf 1.0.10, 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 openhtmltopdf. 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/OpenHtmlToPdfOutlookReportPdfGenerator.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/OpenHtmlToPdfOutlookReportPdfGenerator.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 unsupported by `openhtmltopdf`.
- 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.
