dcjxb.microservice/docs/plans/2026-04-13-outlook-report-module-one-charts.md

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 + openhtmltopdf 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, openhtmltopdf 1.0.10, 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:

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:

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:

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:

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

Expected: PASS.

Step 3: Run final module verification

Run:

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.