# Outlook Report Module One Charts Implementation Plan

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

**Goal:** Rebuild module one of the Outlook PDF report into a reference-style 2x2 chart dashboard, making three cards data-faithful with the current DTO and keeping the common-vocabulary card as an explicitly approximate visual.

**Architecture:** Keep the existing template + server-side renderer + Playwright pipeline. Replace module-one chart fragments with print-safe inline SVG charts that resemble the reference screenshot: a donut chart, a total-vs-unknown bar chart, an approximate dual-bar common-vocabulary card, and a vertical frequency chart. Avoid browser JS and keep the request DTO unchanged.

**Tech Stack:** Java 17+, Spring component rendering, Playwright Java, inline SVG, JUnit 5 / AssertJ, Maven.

---

### Task 1: Lock the new module-one chart contract with tests

**Files:**
- Modify: `ability-integration/src/test/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRendererTest.java`

**Step 1: Write the failing test**

Add or update assertions so rendered HTML proves module one now contains:

```java
assertThat(html).contains("模块一：个人学情分析");
assertThat(html).contains("module-one-grid");
assertThat(html).contains("donut-chart");
assertThat(html).contains("exam-volume-chart");
assertThat(html).contains("common-estimate-chart");
assertThat(html).contains("frequency-column-chart");
assertThat(html).contains("近似展示");
```

Add a targeted regression that checks the exam card shows total-word and unknown-word values from the DTO, and the case of common-vocabulary approximate wording is present.

**Step 2: Run test to verify it fails**

Run:

```bash
mvn -pl ability-integration -am -Dtest=ClasspathOutlookReportHtmlRendererTest -Dsurefire.failIfNoSpecifiedTests=false clean test
```

Expected: FAIL because current module-one cards still use the older generic chart wrappers.

**Step 3: Refresh fixture text if needed**

Update only sample text in `sampleRequest()` if it helps the new assertions stay readable. Do not change the DTO.

**Step 4: Re-run the same test**

Expected: still FAIL, but for the intended missing-module-one-structure reason.

**Step 5: Commit**

Do not commit unless the user explicitly asks later.

### Task 2: Rework module-one template layout into a chart-first 2x2 dashboard

**Files:**
- Modify: `ability-integration/src/main/resources/templates/outlook-report-template.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.

**Step 2: Run test to verify it fails**

Run the same focused Maven command from Task 1.

**Step 3: Write minimal implementation**

Rebuild only the module-one section so it visually resembles the screenshot:

- rename the 2x2 table class to something module-one-specific such as `module-one-grid`
- make each card more chart-first with larger chart area and lighter caption text below
- keep four cards in this order:
  1. `考纲词汇掌握情况`
  2. `真题试卷词汇掌握情况`
  3. `常考词汇掌握情况`
  4. `词频区间掌握度`
- add styles for the new chart wrappers:
  - `donut-chart`
  - `exam-volume-chart`
  - `common-estimate-chart`
  - `frequency-column-chart`
- add a subtle note style for the approximate common-vocabulary card, e.g. `近似展示` / `基于现有词汇模块估算`

Keep the rest of the report unchanged except for any shared CSS needed to support the new cards.

**Step 4: Run test to verify it passes**

Run the focused test command again.

Expected: PASS for the structural assertions.

**Step 5: Commit**

Do not commit unless the user explicitly asks later.

### Task 3: Replace module-one chart generation with screenshot-style SVG variants

**Files:**
- Modify: `ability-integration/src/main/java/cn/yunzhixue/microservice/ability/report/outlook/integration/OutlookReportSvgChartBuilder.java`
- 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**

Add assertions covering the expected module-one behaviors:

```java
assertThat(html).contains("真题总词");
assertThat(html).contains("生词量");
assertThat(html).contains("已掌握");
assertThat(html).contains("待突破");
assertThat(html).contains("高频词");
assertThat(html).contains("中频词");
assertThat(html).contains("低频词");
```

Add one regression asserting that the exam card uses `totalWords` and `totalWords - masteredWords` from the request.

**Step 2: Run test to verify it fails**

Run the same focused Maven command.

**Step 3: Write minimal implementation**

In `OutlookReportSvgChartBuilder`, add print-safe methods that resemble the screenshot more closely:

- a donut chart for syllabus mastery with two labeled segments (`已掌握` / `未掌握` or `待突破`)
- a two-column chart for exam vocabulary (`真题总词` vs `生词量`)
- an approximate two-column chart for common vocabulary using current DTO-derived percentages or word groups, clearly marked as approximate in the renderer/template copy
- a vertical column chart for high/mid/low frequency bands

In `ClasspathOutlookReportHtmlRenderer`, remap module-one card builders to use those new chart methods and update the narrative copy beneath each chart so the chart and caption match the screenshot style.

Do not fabricate business-critical metrics; the common-vocabulary card may approximate as approved, but it must visually signal that fact.

**Step 4: Run test to verify it passes**

Run the focused renderer suite again.

Expected: PASS.

**Step 5: Commit**

Do not commit unless the user explicitly asks later.

### Task 4: Regression + PDF verification

**Files:**
- Test only: `ability-integration/src/test/java/cn/yunzhixue/microservice/ability/report/outlook/integration/ClasspathOutlookReportHtmlRendererTest.java`

**Step 1: Keep the PDF smoke test intact**

Ensure `renderedOutlookReportCanBeConvertedToPdf()` still passes with the new module-one SVG output.

**Step 2: Run focused module verification**

Run:

```bash
mvn -pl ability-integration -am -Dtest=ClasspathOutlookReportHtmlRendererTest -Dsurefire.failIfNoSpecifiedTests=false clean test
```

Expected: PASS.

**Step 3: Run final module verification**

Run:

```bash
mvn -pl ability-integration -am clean test
```

Expected: BUILD SUCCESS.

**Step 4: Commit**

Do not commit unless the user explicitly asks later.

## Notes for the implementer

- This workspace is not a git repository, so worktree setup is not available here.
- Keep the request DTO unchanged.
- Prioritize screenshot-style visual resemblance for module one, but keep the data meaning honest.
- The common-vocabulary card is intentionally approximate in this scope; label it accordingly rather than pretending it is an exact business metric.