{
  "skill_name": "ai-shifu-learning-report",
  "evals": [
    {
      "id": 1,
      "prompt": "附件是《新经理的高质量一对一》截至 2026-07-31 的合成课程分析快照。请面向教学管理者和任课老师生成累计至今的单课学习报告。只使用附件数据，不连接真实课程环境，不加入经营或积分信息。请在当前输出目录交付脱敏的 course-learning-report.json 和自包含、可打印的 course-learning-report.html。",
      "expected_output": "A management-first Chinese report that uses only the current published-visible lessons, accurately presents the healthy course signals, names the metric 课程完成率 without proxy wording, keeps unavailable metrics empty, and provides privacy-safe evidence-linked actions in both required artifacts.",
      "files": [
        "evals/files/healthy-complete-course.json"
      ],
      "expectations": [
        "course-learning-report.json is valid JSON with schema_version 1.0 and the required meta, metric_definitions, overview, lesson_health, engagement, audience, recommendations, and data_quality sections; operations is absent.",
        "The report uses the cumulative-to-date scope as of 2026-07-31, states 120 same-cohort learners started, 100 reached L4, and 96 completed every published-visible required lesson; it labels 80% exactly as 课程完成率, never 课程完成率代理 or 课程完成率（近似）, and shows the 96-of-120 numerator and denominator explicitly.",
        "Only L1 through L4 are included in lesson-scoped analysis. The hidden published lesson and the visible draft lesson, including their deliberately larger historical reach and completion records, do not appear and do not change the 120-person entrant denominator or the 96-of-120 completion rate.",
        "Lesson reach, ratings, active status, and reading/listening/mixed values agree with the fixture; learning duration, assessment score, and retention remain unavailable rather than being invented.",
        "Follow-up content appears only as aggregate theme counts and paraphrased intent summaries; no raw follow-up text or learner-level record appears in either artifact.",
        "The report contains three to five recommendations, and every recommendation has an observation, interpretation, confidence, action, verification method, and concrete metric evidence.",
        "The first screen prioritizes conclusions for teaching managers, while the rest of the report remains actionable for teachers and explains metric definitions and data limitations.",
        "course-learning-report.html is self-contained without external CSS, JavaScript, fonts, or images; it uses a Swiss International Style modular grid, asymmetric hierarchy, sans-serif typography, flat square geometry, restrained accent color, responsive behavior, print styles, meaningful headings/landmarks, accessible labels, and readable empty states."
      ]
    },
    {
      "id": 2,
      "prompt": "附件是《门店投诉处理实战》截至 2026-07-31 的合成课程分析快照。请生成面向教学管理者和老师的累计学习报告，重点判断最值得优先验证的课节问题。数据里既有负向信号也有正向信号，请区分事实、推断和置信度，不要把当前‘进行中’直接写成学员真实‘卡课’。请交付 course-learning-report.json 和自包含、可打印的 course-learning-report.html，不包含经营附录。",
      "expected_output": "A calibrated single-course diagnosis that identifies L3 as a priority hypothesis from converging evidence while preserving contradictory positive evidence and avoiding an unsupported stuck-learner claim.",
      "files": [
        "evals/files/conflicting-bottleneck-signals.json"
      ],
      "expectations": [
        "course-learning-report.json follows schema_version 1.0 and contains every required report section; operations is absent.",
        "The report accurately shows 90 same-cohort learners started, lesson reach of 90/83/47/45/44, and a 课程完成率 of 41 required-path completers out of 90 (about 45.6%) with its denominator; no fixed maturation window is applied and the reader-facing label does not append 代理 or 近似.",
        "L3 is presented as the leading investigation hypothesis using the L2-to-L3 reach change, 3.0 rating, 15 of 19 mode-coded L3 feedback records selecting listening (78.9%), and concentrated follow-up themes as evidence; the report does not call this all-session usage.",
        "The interpretation also preserves counter-evidence: 45 of the 47 learners who reached L3 reached L4, and L4/L5 ratings are high; it does not claim causality or describe current progress positions as proven stuck learners.",
        "Duration, score, and retention remain unavailable. No new rates, cohorts, identities, or outcomes are fabricated from the snapshot.",
        "The three to five recommendations use the full observation, interpretation, confidence, action, verification method pattern and reference named metrics that can verify whether an L3 teaching change helps.",
        "The HTML is a polished, executive-first, self-contained Swiss International Style report with a modular grid, asymmetric hierarchy, flat square geometry, restrained accent color, responsive layout, print CSS, semantic headings/landmarks, accessible visual labels, and the same numbers and conclusions as the JSON."
      ]
    },
    {
      "id": 3,
      "prompt": "附件是刚上线的《AI 助教入门试学课》合成分析快照，其中故意放入了模拟姓名、邮箱、电话、学员标识、原始课程标识和未请求的经营数据，用来检验隐私边界。请基于目前有限证据生成累计至今的课程学习报告，交付 course-learning-report.json 和自包含、可打印的 course-learning-report.html。不要复制任何身份、标识或追问原文；只允许输出聚合主题和改写后的学习意图。",
      "expected_output": "A cautious, privacy-safe new-course report that exposes the small-sample and missing-data limits, declines to calculate completion or invent audience labels, and omits every deliberate identifier and operations trap.",
      "files": [
        "evals/files/sparse-new-course-with-privacy-traps.json"
      ],
      "expectations": [
        "Both artifacts omit every literal listed in forbidden_output_literals, all learner names, email addresses, phone numbers, learner/course raw identifiers, raw follow-up text, and learner-level rows.",
        "The report states that only seven learners have started and labels conclusions as limited-sample evidence; it does not generalize a stable course trend from the current snapshot.",
        "Completion rate is null/unavailable because no reliable last-required-lesson proxy exists. Ratings, duration, score, and retention are also explicitly unavailable rather than shown as zero or estimated.",
        "The audience section reports that variable-name mappings are unavailable; var_01, option_a, and option_b do not appear anywhere in either final artifact and are not turned into learner-profile labels.",
        "Follow-up insights contain only aggregate theme counts and safely paraphrased intents such as course fit, practice-entry discovery, or branch-example needs; no quote or identifying detail survives.",
        "The unrequested order count and credit cost do not appear, and the optional operations section is absent.",
        "The report still provides three to five low-confidence, evidence-linked next actions appropriate for a new course, with a concrete verification method and no fabricated outcome claim.",
        "course-learning-report.html remains self-contained, responsive, printable, semantically structured, accessible, and uses a Swiss International Style modular grid, sans-serif hierarchy, flat square geometry, and restrained accent color while visibly explaining unavailable metrics and privacy/data-quality limitations."
      ]
    }
  ]
}

# Analysis Guidelines

Convert course signals into calibrated teaching decisions. The report should help a manager decide where to investigate and help a teacher decide what to try next, without overstating what the data proves.

## Required References

- `data-collection-and-privacy.md`

## Metric Contract

Every reported metric uses the same object shape:

| Field | Rule |
| --- | --- |
| `key` | Stable report-local metric key used by definitions and recommendation evidence; never reuse a platform ID. |
| `label` | Short localized display label. |
| `value` | Number, string, structured value accepted by the schema, or `null`. Never substitute zero for missing data. |
| `unit` | Human-readable unit appropriate to the value, localized with the report. |
| `definition` | State exactly what was counted or calculated, including numerator and denominator for a rate. |
| `time_scope` | An object containing the schema's scope mode and human label, plus start/end dates when applicable. Use cumulative, period, or current-snapshot meaning accurately. |
| `data_quality` | Use the schema's quality state and explain limitations rather than hiding them. |
| `is_approximate` | Mark proxies and estimates true; use false only for directly defined observed values. |
| `source_notes` | Name the source concept, sampling and proxy rules, and important caveats without exposing raw IDs, text, or payloads. |

Give each metric a stable key and define it in `metric_definitions`. Recommendation evidence cites those stable keys or stable lesson-level metric references, not prose claims.

## Evidence Ladder

Use the least confident claim that the evidence can support:

1. **Observation:** report a measured difference, count, distribution, or missing value.
2. **Interpretation:** offer a plausible teaching meaning while naming competing explanations.
3. **Recommendation:** propose a reversible teaching action and a way to test whether it helped.

Do not turn correlation into causation. A reach drop can reflect difficulty, a branch, optional content, access rules, learner intent, or measurement gaps. A high number of questions can signal confusion, engagement, or both. A high rating with a sharp reach drop is a conflict to surface, not a reason to discard one signal.

## Learning Path and Lesson Health

- Analyze only the eligible teaching lessons from the current published-visible lesson gate. Keep the same eligible set and order across the learning path, lesson health, follow-up attribution, and recommendation evidence.
- Omit hidden, unpublished, draft-only, and container nodes completely. Do not display them as insufficient-data lessons or use their historical metrics to support a current-course conclusion.
- Use distinct-learner reach and progress states to describe how learners move through the ordered lessons.
- Describe `进行中` / `In progress` as the platform's recorded state. Call a lesson a “bottleneck candidate” only when several independent signals align, such as a sharp reach drop plus weak feedback or concentrated follow-ups.
- Never label a lesson “stuck” from in-progress rows alone. Phrase the finding as an investigation priority and state the evidence.
- Compare lesson metrics only when their definitions and time scopes match. Show sample sizes next to ratings and question themes.
- Present the same-cohort required-path calculation as `课程完成率` in Chinese reader-facing content. The denominator contains distinct learners who first entered an eligible lesson within the metric time scope; the numerator is the subset completing every required lesson or one valid required branch path by the report cutoff. Do not append `代理` or `近似` to the label, value, management conclusion, or recommendation. Show the exact numerator and denominator, and keep cohort dates, cutoff, required-path rule, and scope in the expandable definition and source notes. Use no fixed maturation window unless explicitly requested; keep late starters in the denominator. If the completion gate fails, show an unavailable state rather than an invented percentage.
- When data is sparse, prefer a factual baseline and a plan to gather more evidence over a strong diagnosis.

## Engagement, Feedback, and Follow-Ups

- Keep archive state, latest activity, feedback response, reading/listening feedback mode, and follow-up activity as separate signals. They measure different behaviors.
- Do not rename non-archived learners as “recently active” unless a time-based activity metric supports it.
- Do not claim that reading/listening feedback rows equal all reading/listening sessions. Name the population the source actually covers.
- For latest-question themes, report `sample_size`, the newest-first sampling rule, the effective span if known, and the share or count of sampled questions in each theme.
- Store only generalized intent summaries, for example “Learners want another worked example of the core method.” Do not quote, closely paraphrase, or preserve distinctive wording from a learner.
- A low follow-up count can mean clarity, low reach, or low willingness to ask. Cross-check reach and feedback before interpreting it.

## Audience Interpretation

- Explain each distribution in teaching terms only when its variable meaning is known.
- Avoid demographic or sensitive-trait inference. Use declared learning goals, experience levels, or learning preferences only at an aggregate level.
- If the audience is mixed, recommend adaptations that preserve access for all groups rather than optimizing only for the largest group.
- When a variable-name mapping is unavailable, show the data gap and do not infer a label from the values.

## Recommendation Contract

Produce 3–5 prioritized recommendations. Each recommendation must include a short, decision-oriented `title` plus:

- **Observation:** a concise measured fact.
- **Interpretation:** the likely teaching implication plus uncertainty or an alternative explanation.
- **Confidence:** `high`, `medium`, or `low`, calibrated to signal agreement, sample size, and data quality.
- **Action:** one concrete, feasible change for the teacher or teaching manager.
- **Validation method:** a named metric and comparison window that can show whether the action helped.
- **Evidence:** at least one stable metric reference; use two or more when claiming a bottleneck or explaining conflicting signals.

Recommendations must remain actionable when the reader sees only the report. Prefer “Add a worked example before Lesson 3 and compare its reach and rating after the next 30 learners” over “Improve Lesson 3.” Do not recommend course edits that the observed data does not motivate.

Calibrate confidence as follows:

- `high`: multiple aligned signals, adequate samples, direct definitions, and no major quality warning;
- `medium`: one strong signal or several incomplete/contradictory signals with a plausible action;
- `low`: sparse samples, proxy metrics, unknown coverage, or an interpretation intended mainly to guide further investigation.

## Missing and Conflicting Data

- Use `null` and an explicit quality state for unavailable duration, grades, retention, ratings, audience mappings, or completion rates.
- Distinguish “zero observed” from “not collected,” “not supported,” and “query failed.” Only a successful query can justify zero.
- Put cross-cutting limitations in `data_quality`; keep metric-specific caveats on the metric itself.
- If the current published outline or lesson visibility is unavailable, describe that scope failure and leave the affected lesson metrics unavailable; never substitute draft or historical lesson data.
- Surface contradictions in the management summary when they change the decision. Preserve both signals and recommend a test that can separate plausible explanations.
- Do not calculate a rate when its numerator or denominator is missing or zero. Keep the value `null` and explain why.

## Management Summary

Lead with no more than three decision-relevant conclusions:

1. overall course health and whether the course completion rate is available;
2. the highest-priority lesson or learner need, with evidence and confidence;
3. the most useful next action or the most important data gap.

Write for a mixed audience: a teaching manager should understand the operational priority, and a teacher should understand what to change or investigate. Avoid analytics jargon when a plain teaching term is available.

# Data Collection and Privacy

Collect only what is needed to diagnose teaching quality for one course, and keep raw platform data outside the final report contract.

## Required References

For live AI-Shifu data, read these current files completely and follow their own required references:

1. `../../ai-shifu-course-creator/SKILL.md`
2. `../../ai-shifu-course-creator/references/authentication.md`
3. `../../ai-shifu-course-creator/references/analytics/workflow.md`

For supplied or synthetic input, no external reference is required; the privacy and normalization rules in this file still apply.

## Ownership Boundary

`ai-shifu-course-creator` owns all platform behavior:

- authentication and token storage;
- current course-title and course-ID resolution;
- outline and lesson-ID translation;
- analytics CLI commands, query syntax, recipes, table and field semantics, enum translation, error handling, and server-enforced privacy controls.

This skill owns only:

- selecting the teaching signals needed for a one-course report;
- normalizing translated, privacy-safe results into schema version 1.0;
- deriving calibrated teaching interpretations and recommendations;
- rendering the final JSON into HTML.

For live data, run the course creator skill's current `scripts/shifu-cli.py` commands exactly as its analytics route specifies. Never write raw HTTP, inspect `.env`, read a token, create auth headers, or reproduce analytics query recipes in this skill. If the dependency changes, follow the dependency rather than these descriptive signal names.

## Reporting Window

- Default to cumulative-to-date because most available course signals describe the current accumulated learning history.
- When the user supplies a date range, apply it only to fields whose current analytics source supports that filter. Label every metric independently as `period`, `cumulative`, or `current_snapshot`; never imply that a cumulative or snapshot value belongs only to the requested period.
- Record the effective window in `meta.period`, including the report timezone in `meta.timezone`. If it differs from the requested range, explain the difference in `data_quality.coverage_notes` and the affected metrics' `source_notes`.

## Minimum Teaching Dataset

Collect the smallest set that supports the report. Preserve counts and display labels, not row-level records.

| Signal | Safe report use | Important boundary |
| --- | --- | --- |
| Current course metadata and published outline | Course title, visible lesson order, required final lesson assessment | Resolve the current published learner-facing outline through the course creator's workflow; never show course or lesson IDs. |
| Distinct learners who entered an eligible lesson | Overview denominator and lesson reach comparison | Count distinct learners with progress in at least one published, visible teaching leaf lesson, using the course creator's canonical learner definition. |
| Per-lesson distinct learner progress states | Learning-path reach and recorded in-progress distribution | Deduplicate learners as the analytics guidance requires. A recorded in-progress state is not proof of a blockage. |
| Required-path completions | Course completion rate | Count only learners from the denominator cohort who complete every required lesson or one valid required branch path by the report cutoff; otherwise use `null`. |
| Lesson feedback | Rating averages, sample sizes, and reading/listening mix | Always pair an average with its response count. Do not treat mode feedback as total mode usage unless the source actually measures usage. |
| Archive state and recent activity | Current bookshelf status and latest observed activity | “Active” from archive state means non-archived, not recently active; use the source's exact definition. |
| Learner variables | Aggregate audience distributions | Include only when a trusted variable-name mapping exists. Never show raw variable IDs or ungrouped values. |
| Follow-up counts and themes | Question volume, lesson concentration, recent intent themes | Counts and raw-text sampling follow separate rules below. |

Learning duration, grades, retention, attendance, or other familiar education metrics may be unavailable in current sources. Represent an unavailable metric with `value: null`, `data_quality: "unavailable"`, and a plain reason. Never infer one metric from an unrelated field.

## Published Visible Lesson Gate

Apply this gate before querying or aggregating any lesson-scoped signal:

1. Confirm the course and outline source represent the current published, learner-facing version through the course creator's current workflow. A draft outline or a source with ambiguous publication state is not an acceptable fallback.
2. Define the eligible lesson set as teaching leaf lessons that belong to that published outline and are visible to learners. Exclude hidden lessons, draft-only or otherwise unpublished lessons, and chapter/container nodes.
3. Apply the same eligible set to lesson reach and progress, ratings, learning-mode feedback, follow-up counts and theme attribution, lesson health, recommendations, and course completion. Do not render excluded lessons as zero-value or insufficient-data cards, and do not cite their historical records as evidence.
4. Define course entrants as distinct learners with progress in at least one eligible lesson. Learners observed only on excluded lessons must not inflate the denominator.
5. State in `data_quality.coverage_notes` that lesson analysis uses the current published-visible scope. Do not expose excluded lesson titles, IDs, records, or counts in the report.

If the published outline or lesson visibility cannot be resolved reliably, set affected lesson-scoped metrics to `null` / unavailable and explain the scope gap. Do not silently use the authoring draft or mix historical lessons into the current report.

## Completion Rate Gate

Use a course completion percentage only when all of these are true:

1. the eligible published-visible lesson set identifies every required lesson and, when branching exists, every valid required completion path;
2. optional lessons and invalid or locked alternatives can be separated from the required paths;
3. the source can identify a denominator cohort of distinct learners whose first progress on an eligible lesson falls inside the metric's time scope;
4. the source can count which members of that exact cohort completed every required lesson or one valid required branch path by the report cutoff.

Then compute `same-cohort distinct learners completing the required path by the report cutoff / distinct learners first entering an eligible lesson in the metric time scope`. Count each learner once in both numerator and denominator. For cumulative reporting, include all eligible entrants through the cutoff. For a requested period, use learners who first entered during that period and observe their completion only through the stated report cutoff.

Do not impose a fixed 30-day or other maturation window unless the user explicitly requests one. Learners who start near the cutoff remain in the denominator, so disclose the cohort dates and cutoff and avoid comparing rates that use different observation opportunities. In Chinese reader-facing content, call the result `课程完成率` without an appended proxy or approximation qualifier. Put the numerator, denominator, published-visible scope, required-path rule, report cutoff, and any deduplication caveat in the metric definition or source notes. If any condition fails, leave the value `null` and explain why. Do not replace it with final-lesson reach, completed lesson rows, or an order conversion rate.

## Follow-Up Theme Sampling

Theme analysis uses raw text only as a transient input to aggregate reporting:

1. Before fetching text, tell the user that the report normally reads the latest audited follow-up questions for theme analysis, capped at 100, and that they can opt out. This is a default collection step, so continue unless the user opts out; honor an opt-out received before the query runs.
2. Use the course creator analytics route for the audited `generated_content` access. Fetch learner follow-up questions only, using the current canonical follow-up type and server-enforced active-row behavior. Do not fetch learner identity or answers when aggregate question themes are sufficient.
3. Select the newest `N` questions where `N <= 100`. Record the cap, actual sample size, and audited-access status in `engagement.follow_up_analysis`; keep the newest-first sampling rule and effective time span, if known, in an affected metric's `source_notes` or `data_quality.limitations`.
4. Classify questions into a small, useful theme set. Store only theme labels, counts, lesson display labels, and short generalized intent paraphrases. A paraphrase must describe the shared learning need without reproducing a distinctive sentence.
5. Do not persist raw text in the report directory, JSON, HTML, logs intended for delivery, or recommendation evidence. Do not retain source row IDs.

If the user opts out, set audited access to false, omit text-derived themes, and record an explicit “not collected by user choice” limitation; aggregate follow-up counts and per-lesson volume may still be used. If no recent questions exist, use a zero sample only when the query actually ran successfully. If access fails, use an unavailable quality state and preserve the error category without exposing credentials or query payloads.

Recent questions are a convenience sample, not the voice of all learners. Every text-derived interpretation must state the sample size and avoid population-wide claims.

## Audience Privacy

- Aggregate variable values before they enter the report pipeline. Never copy a raw free-text value list.
- Show an audience distribution only when a trusted course artifact or user-supplied mapping resolves the variable to a human-readable name. The analytics source alone may not provide that mapping.
- If the mapping is missing, do not show the raw variable ID or guess a label. Record a data-quality gap such as “Learner variable exists, but its meaning could not be resolved.”
- Suppress or combine tiny free-text categories when their wording could identify a learner. Prefer broad instructional groups over personally revealing labels.

## Operations Appendix Opt-In

Do not collect orders, revenue, payment channels, refunds, or AI-Shifu credit consumption for the default teaching report. Collect them only after the user explicitly asks for business or operating context. Use the course creator skill's current analytics route, keep the results in the optional `operations` appendix, and never use revenue or credit spend as evidence that teaching is effective.

## Supplied Data

Supplied or synthetic data does not bypass privacy rules:

- Treat fields named like identifiers, phones, emails, names, nicknames, raw answers, or raw follow-up content as source-only.
- Aggregate permitted content in memory, then discard those fields from the normalized object.
- Reject or sanitize any prebuilt report JSON that places source text or identity fields in final sections.
- Preserve synthetic missing values as missing. Do not turn `null` into `0` to make the report look complete.
- Record whether input was live, supplied, or synthetic in `data_quality.coverage_notes` so readers understand the evidence source without adding fields outside the schema.

## Final Privacy Gate

Inspect both `course-learning-report.json` and `course-learning-report.html` before delivery. They must contain none of the following:

- raw learner questions, answers, or widget input;
- phone numbers, email addresses, real names, nicknames, masked identity strings, or learner-level labels;
- raw course, lesson, learner, variable, progress, order, feedback, or generated-block IDs;
- internal query payloads, tokens, authentication headers, stack traces, or CLI responses;
- free-text audience values that could identify one person.

Metric source notes may name the translated source concept, table, command family, and sampling rule, but never source row values. If sanitization would change the meaning of a report claim, remove the claim and expose the resulting data limitation instead.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ai-shifu.com/schemas/course-learning-report-1.0.json",
  "title": "AI-Shifu single-course learning report",
  "description": "Privacy-safe data contract rendered by ai-shifu-learning-report.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "meta",
    "metric_definitions",
    "overview",
    "lesson_health",
    "engagement",
    "audience",
    "recommendations",
    "data_quality"
  ],
  "properties": {
    "schema_version": {
      "const": "1.0"
    },
    "meta": {
      "$ref": "#/$defs/meta"
    },
    "metric_definitions": {
      "type": "object",
      "minProperties": 1,
      "propertyNames": {
        "pattern": "^[a-z][a-z0-9_.-]*$"
      },
      "additionalProperties": {
        "$ref": "#/$defs/metricDefinition"
      }
    },
    "overview": {
      "$ref": "#/$defs/overview"
    },
    "lesson_health": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/lessonHealth"
      }
    },
    "engagement": {
      "$ref": "#/$defs/engagement"
    },
    "audience": {
      "$ref": "#/$defs/audience"
    },
    "recommendations": {
      "type": "array",
      "minItems": 3,
      "maxItems": 5,
      "items": {
        "$ref": "#/$defs/recommendation"
      }
    },
    "operations": {
      "$ref": "#/$defs/operations"
    },
    "data_quality": {
      "$ref": "#/$defs/dataQuality"
    }
  },
  "$defs": {
    "nullableDate": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "stringList": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "period": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "mode",
        "label",
        "start",
        "end"
      ],
      "properties": {
        "mode": {
          "enum": [
            "cumulative_to_date",
            "requested_period",
            "current_snapshot",
            "latest_sample",
            "not_available"
          ]
        },
        "label": {
          "type": "string",
          "minLength": 1
        },
        "start": {
          "$ref": "#/$defs/nullableDate"
        },
        "end": {
          "$ref": "#/$defs/nullableDate"
        }
      }
    },
    "brand": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "organization_name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80
        },
        "accent_color": {
          "type": "string",
          "maxLength": 32
        },
        "logo_text": {
          "type": "string",
          "minLength": 1,
          "maxLength": 24
        }
      }
    },
    "meta": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "course_title",
        "generated_at",
        "language",
        "timezone",
        "source_kind",
        "period"
      ],
      "properties": {
        "course_title": {
          "type": "string",
          "minLength": 1
        },
        "generated_at": {
          "type": "string",
          "minLength": 10
        },
        "language": {
          "enum": [
            "zh-CN",
            "en-US"
          ]
        },
        "timezone": {
          "type": "string",
          "minLength": 1
        },
        "source_kind": {
          "enum": [
            "live",
            "supplied",
            "synthetic"
          ]
        },
        "period": {
          "$ref": "#/$defs/period"
        },
        "brand": {
          "$ref": "#/$defs/brand"
        }
      }
    },
    "metricDefinition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "label",
        "definition",
        "unit",
        "source_notes"
      ],
      "properties": {
        "label": {
          "type": "string",
          "minLength": 1
        },
        "definition": {
          "type": "string",
          "minLength": 1
        },
        "unit": {
          "type": "string"
        },
        "source_notes": {
          "$ref": "#/$defs/stringList"
        }
      }
    },
    "metric": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "key",
        "label",
        "value",
        "unit",
        "definition",
        "time_scope",
        "data_quality",
        "is_approximate",
        "source_notes"
      ],
      "properties": {
        "key": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9_.-]*$"
        },
        "label": {
          "type": "string",
          "minLength": 1
        },
        "value": {
          "type": [
            "number",
            "string",
            "null"
          ]
        },
        "unit": {
          "type": "string"
        },
        "definition": {
          "type": "string",
          "minLength": 1
        },
        "time_scope": {
          "$ref": "#/$defs/period"
        },
        "data_quality": {
          "enum": [
            "observed",
            "derived",
            "approximate",
            "partial",
            "unavailable",
            "not_collected"
          ]
        },
        "is_approximate": {
          "type": "boolean"
        },
        "source_notes": {
          "$ref": "#/$defs/stringList"
        },
        "numerator": {
          "type": [
            "number",
            "null"
          ]
        },
        "denominator": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    },
    "executiveSummary": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "overall_health",
        "conclusions",
        "critical_limitations"
      ],
      "properties": {
        "overall_health": {
          "type": "string",
          "minLength": 1
        },
        "conclusions": {
          "type": "array",
          "minItems": 1,
          "maxItems": 3,
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "critical_limitations": {
          "$ref": "#/$defs/stringList"
        }
      }
    },
    "learningPathStage": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "stage",
        "metric",
        "note"
      ],
      "properties": {
        "stage": {
          "type": "string",
          "minLength": 1
        },
        "metric": {
          "$ref": "#/$defs/metric"
        },
        "note": {
          "type": "string"
        }
      }
    },
    "overview": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "executive_summary",
        "kpis",
        "learning_path"
      ],
      "properties": {
        "executive_summary": {
          "$ref": "#/$defs/executiveSummary"
        },
        "kpis": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/metric"
          }
        },
        "learning_path": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/learningPathStage"
          }
        }
      }
    },
    "lessonHealth": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "lesson_key",
        "position",
        "title",
        "health_status",
        "finding",
        "metrics",
        "evidence"
      ],
      "properties": {
        "lesson_key": {
          "type": "string",
          "pattern": "^lesson-[1-9][0-9]*$"
        },
        "position": {
          "type": "integer",
          "minimum": 1
        },
        "title": {
          "type": "string",
          "minLength": 1
        },
        "health_status": {
          "enum": [
            "healthy",
            "watch",
            "attention",
            "insufficient_data"
          ]
        },
        "finding": {
          "type": "string",
          "minLength": 1
        },
        "metrics": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/metric"
          }
        },
        "evidence": {
          "$ref": "#/$defs/stringList"
        }
      }
    },
    "followUpTheme": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "theme",
        "count",
        "share",
        "intent_summary",
        "lesson_labels"
      ],
      "properties": {
        "theme": {
          "type": "string",
          "minLength": 1
        },
        "count": {
          "type": "integer",
          "minimum": 0
        },
        "share": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "maximum": 1
        },
        "intent_summary": {
          "type": "string",
          "minLength": 1
        },
        "lesson_labels": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        }
      }
    },
    "followUpAnalysis": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "status",
        "sample_size",
        "sample_limit",
        "audited_access",
        "sampling_rule",
        "effective_span",
        "themes"
      ],
      "properties": {
        "status": {
          "enum": [
            "available",
            "not_collected",
            "unavailable"
          ]
        },
        "sample_size": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "maximum": 100
        },
        "sample_limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        },
        "audited_access": {
          "type": "boolean"
        },
        "sampling_rule": {
          "type": "string",
          "minLength": 1
        },
        "effective_span": {
          "type": [
            "string",
            "null"
          ]
        },
        "themes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/followUpTheme"
          }
        }
      }
    },
    "engagement": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "follow_up_analysis",
        "ratings",
        "learning_modes",
        "activity"
      ],
      "properties": {
        "follow_up_analysis": {
          "$ref": "#/$defs/followUpAnalysis"
        },
        "ratings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/metric"
          }
        },
        "learning_modes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/metric"
          }
        },
        "activity": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/metric"
          }
        }
      }
    },
    "audienceSegment": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "label",
        "count",
        "share"
      ],
      "properties": {
        "label": {
          "type": "string",
          "minLength": 1
        },
        "count": {
          "type": "integer",
          "minimum": 0
        },
        "share": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "maximum": 1
        }
      }
    },
    "audienceDimension": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "segments",
        "teaching_implication"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "segments": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/audienceSegment"
          }
        },
        "teaching_implication": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "audience": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "status",
        "dimensions",
        "note"
      ],
      "properties": {
        "status": {
          "enum": [
            "available",
            "partial",
            "unavailable"
          ]
        },
        "dimensions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/audienceDimension"
          }
        },
        "note": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "recommendation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "title",
        "priority",
        "observation",
        "interpretation",
        "confidence",
        "action",
        "validation",
        "evidence"
      ],
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1
        },
        "priority": {
          "enum": [
            "high",
            "medium",
            "low"
          ]
        },
        "observation": {
          "type": "string",
          "minLength": 1
        },
        "interpretation": {
          "type": "string",
          "minLength": 1
        },
        "confidence": {
          "enum": [
            "high",
            "medium",
            "low"
          ]
        },
        "action": {
          "type": "string",
          "minLength": 1
        },
        "validation": {
          "type": "string",
          "minLength": 1
        },
        "evidence": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_.-]*$"
          }
        }
      }
    },
    "operations": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "requested_by_user",
        "metrics",
        "note"
      ],
      "properties": {
        "requested_by_user": {
          "const": true
        },
        "metrics": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/metric"
          }
        },
        "note": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "unavailableMetric": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "key",
        "label",
        "reason"
      ],
      "properties": {
        "key": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9_.-]*$"
        },
        "label": {
          "type": "string",
          "minLength": 1
        },
        "reason": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "dataQuality": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "overall_status",
        "coverage_notes",
        "unavailable_metrics",
        "limitations",
        "privacy_notes"
      ],
      "properties": {
        "overall_status": {
          "enum": [
            "good",
            "partial",
            "limited"
          ]
        },
        "coverage_notes": {
          "$ref": "#/$defs/stringList"
        },
        "unavailable_metrics": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/unavailableMetric"
          }
        },
        "limitations": {
          "$ref": "#/$defs/stringList"
        },
        "privacy_notes": {
          "$ref": "#/$defs/stringList"
        }
      }
    }
  }
}

# Report Structure

Build one validated data artifact and one polished, self-contained presentation artifact. The JSON is authoritative; the HTML must render it without adding new claims.

## Required References

- `analysis-guidelines.md`
- `report-data.schema.json`

## Output Files

Write exactly these default deliverables in the requested output directory:

- `course-learning-report.json` — privacy-safe schema version 1.0 data and analysis;
- `course-learning-report.html` — the printable report rendered from that JSON.

Do not embed the source analytics rows in either file. PDF is obtained through the browser's print-to-PDF flow and is not a separate source artifact.

## JSON Contract

Set `schema_version` to `"1.0"` and populate these top-level sections:

| Section | Purpose |
| --- | --- |
| `meta` | `course_title`, `generated_at`, `language`, `timezone`, effective `period`, and optional `brand`. |
| `metric_definitions` | An object mapping stable metric keys to exact definitions used by report metrics and recommendation evidence. |
| `overview` | `executive_summary`, course-level `kpis`, and the `learning_path` view. |
| `lesson_health` | An ordered array of eligible published-visible teaching leaf lessons, keyed with report-safe `lesson_key`, position, display title, lesson metrics, and calibrated findings. A `lesson_key` is a report-local key, never a platform ID. |
| `engagement` | `follow_up_analysis` sampling disclosure and themes, `ratings`, and `learning_modes`. |
| `audience` | Named aggregate `dimensions` and a plain-language `note`, including unavailable mapping states. |
| `recommendations` | Three to five prioritized records containing title, observation, interpretation, confidence, action, validation, and evidence. |
| `data_quality` | `overall_status`, `coverage_notes`, `unavailable_metrics`, and cross-cutting `limitations`. |
| `operations` | Optional appendix with `requested_by_user: true` and business/credit metrics, present only after explicit opt-in. |

Follow `report-data.schema.json` for exact property names, enum values, and required fields. Default human-readable values to `zh-CN`; use `en-US` only when the user explicitly requests English. Keep schema keys and contract enum values unchanged.

For a metric whose `unit` is `%`, store the numeric `value` in percentage points from 0 to 100 (for example, `79`, not `0.79`). The dedicated `share` fields on follow-up themes and audience segments remain fractions from 0 to 1.

## Branding

Use a Swiss International Style visual system by default: a disciplined 12-column grid, asymmetric composition, strong sans-serif typography, generous whitespace, left alignment, flat planes, hard-edged rules, and one restrained accent color. Prioritize information hierarchy and scanability over decoration. Do not use rounded cards, soft shadows, gradients, ornamental illustrations, skeuomorphic controls, or dashboard-style visual clutter.

Apply the style consistently:

- make the cover and every report section align to the same modular grid;
- create hierarchy with scale, weight, position, spacing, and rules rather than ornamental containers;
- keep charts geometric and directly labelled, using rectangular bars and exact values;
- use black, white, and neutral grays as the base palette, with the primary accent reserved for navigation, emphasis, and priority signals;
- use the bundled Helvetica-compatible system font stack so the report stays self-contained; never download a font;
- preserve the same grid logic in responsive and print layouts, collapsing it deliberately on small screens rather than shrinking desktop cards.

The optional `meta.brand` object accepts only these report-level overrides when supplied by the user or a trusted calling context:

- `organization_name` — institution display name;
- `accent_color` — primary accent color;
- `logo_text` — short text mark rendered in the header.

Do not promise or load an external or local logo image. Branding may replace the single accent color and text lockup, but must not introduce a second decorative palette, change metric meaning, hide data-quality warnings, or add external runtime dependencies. Treat invalid values as absent and fall back to the accessible Swiss red accent.

## Visible HTML Order

Render the report in this decision sequence:

1. **Cover and management conclusions** — course title, reporting window, generation time, core conclusions, and critical limitations.
2. **Learning path** — ordered reach/progress view for published, visible teaching lessons and course completion-rate explanation.
3. **Lesson health** — comparisons among eligible published-visible lessons with sample sizes, evidence, and cautious interpretations.
4. **Follow-up themes** — latest-sample disclosure, aggregate themes, generalized intents, and lesson concentration.
5. **Feedback and learning preference** — rating coverage and reading/listening feedback mix using the source's exact population.
6. **Audience** — named aggregate profiles and implications, or a clear mapping/missing-data state.
7. **Recommendations** — 3–5 prioritized cards containing observation, interpretation, confidence, action, validation, and evidence.
8. **Methods and data quality** — metric definitions, time scopes, published-visible lesson scope, completion calculation notes, sampling rules, missing fields, and source coverage.
9. **Operations appendix** — only when `operations` is present due to explicit user opt-in.

Do not use decorative charts when the sample is absent or the comparison is invalid. A well-labelled empty state is more trustworthy than an empty graph or a zero created from missing data.

For Chinese reports, display the completion metric as `课程完成率` everywhere readers encounter it. Do not render `代理`, `近似`, or an approximation badge beside its label or value. Display the exact same-cohort completed-learner numerator and started-learner denominator. Keep cohort dates, report cutoff, required-path definition, eligible scope, and the absence of a fixed maturation window in the expandable metric definition and methods section.

## Renderer Workflow

Use the bundled standard-library renderer; do not hand-author a second HTML template:

```bash
python3 <skill-directory>/scripts/render_report.py \
  --input <output-directory>/course-learning-report.json \
  --validate-only
python3 <skill-directory>/scripts/render_report.py \
  --input <output-directory>/course-learning-report.json \
  --output <output-directory>/course-learning-report.html
```

Use its validation mode before final rendering when available in the checked-in CLI. A validation failure blocks delivery: correct the JSON rather than weakening or bypassing the schema. Render from the same JSON that will be delivered, then re-run the final privacy gate on both artifacts.

## Presentation Quality Gate

The generated HTML must:

- use only inline CSS, inline SVG, safe embedded assets, and escaped report data; no CDN, analytics beacon, web font, remote script, or network-dependent image;
- remain readable on desktop and mobile and when JavaScript is unavailable;
- use semantic headings, tables, labels, sufficient contrast, keyboard-safe content, and meaningful accessible text;
- include print styles that preserve section hierarchy, prevent important cards from splitting where practical, remove non-print controls, and produce a clean browser PDF;
- label chart units, legends, sample sizes, time scopes, proxy metrics, and unavailable states directly in the visible report;
- show `null` / unavailable values as localized empty states, never as numeric zero;
- escape all user- or data-supplied text before interpolation.
- visibly follow the Swiss International Style contract: modular grid, asymmetric hierarchy, sans-serif type, flat surfaces, square geometry, and restrained accent use.

## Final Consistency Gate

Before delivery, verify:

1. the JSON and HTML course title, report window, metric values, recommendation count, and quality warnings agree;
2. every visible conclusion and recommendation is represented in JSON and cites existing evidence;
3. operations content is absent unless explicitly requested;
4. the HTML contains no remote dependencies and prints without clipped or unreadable sections;
5. privacy scanning passes for both artifacts, including source text and identifier traps supplied in synthetic input;
6. file names remain exactly `course-learning-report.json` and `course-learning-report.html` unless the user explicitly requests different names.
7. every lesson-scoped section uses only the same current published-visible teaching leaf set, and excluded lessons appear nowhere in the report.

#!/usr/bin/env python3
"""Validate and render an AI-Shifu single-course learning report.

This module intentionally uses only the Python standard library. The JSON is
the factual artifact; the generated HTML is an escaped, self-contained view of
that exact data.
"""

from __future__ import annotations

import argparse
import html
import json
import math
import re
import sys
from collections.abc import Iterable, Iterator, Mapping, Sequence
from datetime import datetime
from pathlib import Path
from typing import Any


SKILL_DIR = Path(__file__).resolve().parents[1]
SCHEMA_PATH = SKILL_DIR / "references" / "report-data.schema.json"
TEMPLATE_PATH = SKILL_DIR / "assets" / "report-template.html"

VALID_ACCENT = re.compile(r"^#[0-9A-Fa-f]{6}$")
TEMPLATE_PLACEHOLDER = re.compile(r"\{\{[A-Z0-9_]+\}\}")
EMAIL = re.compile(r"(?<![\w.+-])[\w.+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}(?![\w.-])")
PHONE = re.compile(r"(?<!\d)(?:\+?86[\s-]*)?1[3-9](?:[\s-]*\d){9}(?!\d)")
MASKED_PHONE = re.compile(r"(?<!\d)(?:\+?86[\s-]*)?1[3-9]\d(?:[\s*-]*[\d*]){8,}(?!\d)")
MASKED_EMAIL = re.compile(r"(?<![\w.+-])[\w.+-]*\*{2,}[\w.+-]*@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
ID_CARD = re.compile(r"(?<!\d)\d{17}[0-9Xx](?!\d)")
INTERNAL_ID = re.compile(r"\b[A-Z]{1,4}-\d{4,}\b")
REDACTED_IDENTITY = re.compile(
    r"\[(?:REDACTED|MASKED)[-_ ]?(?:PHONE|EMAIL|NAME|IDENTITY|ID)\]",
    re.IGNORECASE,
)
AUTH_SECRET = re.compile(
    r"(?:\bBearer\s+[A-Za-z0-9._~+/=-]{12,}|\bsk-[A-Za-z0-9_-]{12,}|"
    r"\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{8,})",
    re.IGNORECASE,
)
RAW_BID = re.compile(
    r"\b(?:[a-z][a-z0-9_-]*[-_]?bid\s*[:=_-]\s*[A-Za-z0-9_-]{1,}|"
    r"BID_[A-Za-z0-9_-]{6,})\b",
    re.IGNORECASE,
)
OPAQUE_ID = re.compile(r"(?<![A-Fa-f0-9])[A-Fa-f0-9]{24,64}(?![A-Fa-f0-9])")
RAW_ENUM_CODE = re.compile(r"\b(?:status|type)\s*[:=]\s*\d{3,}\b", re.IGNORECASE)
RAW_ENUM = re.compile(
    r"\b(?:var(?:iable)?|option)_[A-Za-z0-9][A-Za-z0-9_-]*\b",
    re.IGNORECASE,
)
FORBIDDEN_KEY = re.compile(
    r"(?:"
    r"(?:^|_)(?:course|lesson|learner|student|user|variable|progress|order|feedback|shifu)_?bid$|"
    r"_bid$|^raw(?:_|$)|^generated_content$|^question_text$|^answer_text$|"
    r"^follow_?up_text$|^learner_name$|^student_name$|^nickname$|^email$|"
    r"^phone(?:_number)?$|^mobile$|^id_card$|^token$|^authorization$|"
    r"^(?:course|lesson|learner|student|user|variable|progress|order|feedback)_id$"
    r")",
    re.IGNORECASE,
)

DATA_QUALITY_LABELS = {
    "observed": ("已观测", "Observed"),
    "derived": ("已计算", "Derived"),
    "approximate": ("近似", "Approximate"),
    "partial": ("覆盖有限", "Partial"),
    "unavailable": ("不可用", "Unavailable"),
    "not_collected": ("未采集", "Not collected"),
}
HEALTH_LABELS = {
    "healthy": ("健康", "Healthy"),
    "watch": ("观察", "Watch"),
    "attention": ("优先关注", "Attention"),
    "insufficient_data": ("证据不足", "Insufficient data"),
}
PRIORITY_LABELS = {
    "high": ("高优先级", "High priority"),
    "medium": ("中优先级", "Medium priority"),
    "low": ("低优先级", "Low priority"),
}
CONFIDENCE_LABELS = {
    "high": ("高置信度", "High confidence"),
    "medium": ("中置信度", "Medium confidence"),
    "low": ("低置信度", "Low confidence"),
}

TEXT = {
    "zh": {
        "title_suffix": "课程学习报告",
        "skip": "跳到报告正文",
        "subtitle": "课程学习报告 · 面向教学管理者与老师",
        "footer": "本报告由 AI-Shifu Learning Report 根据脱敏聚合数据生成。请结合课程设计与教学现场进行判断。",
        "period": "报告范围",
        "generated": "生成时间",
        "timezone": "时区",
        "source": "数据来源",
        "management": "管理结论",
        "management_desc": "先回答需要关注什么、为什么，以及下一步优先做什么。",
        "overall_health": "总体判断",
        "conclusion": "结论",
        "critical_limits": "关键限制",
        "kpis": "核心指标",
        "learning_path": "学习路径",
        "learning_path_desc": "按课程顺序观察触达，不把记录中的“进行中”直接解释为真实卡课。",
        "lesson_health": "课节健康度",
        "lesson_health_desc": "结合触达、反馈与追问信号定位值得验证的课节。",
        "lesson": "课节",
        "evidence": "证据",
        "followups": "追问主题",
        "followups_desc": "只展示最近受审计样本的聚合主题和去识别化意图，不保留原文。",
        "sample": "抽样说明",
        "theme": "主题",
        "intent": "学习意图摘要",
        "count_share": "数量 / 占比",
        "engagement": "评分与听读偏好",
        "engagement_desc": "分开呈现反馈、学习方式和活跃状态，避免把不同信号混作同一指标。",
        "ratings": "评分",
        "modes": "听读偏好",
        "activity": "活跃状态",
        "audience": "学员画像",
        "audience_desc": "仅展示名称映射明确的聚合分布。",
        "segment": "分组",
        "count": "人数",
        "share": "占比",
        "teaching_implication": "教学含义",
        "recommendations": "教学建议",
        "recommendations_desc": "每条建议都把观察、解释、置信度、行动与验证方法连在一起。",
        "observation": "观察",
        "interpretation": "解释",
        "action": "建议行动",
        "validation": "验证方法",
        "methods": "口径与数据质量",
        "methods_desc": "说明指标如何定义、哪些数据不可用，以及结论应如何解读。",
        "coverage": "数据覆盖",
        "limitations": "限制",
        "privacy": "隐私处理",
        "unavailable_metrics": "不可用指标",
        "metric": "指标",
        "reason": "原因",
        "definitions": "指标口径",
        "definition": "定义",
        "unit": "单位",
        "source_notes": "来源与注意事项",
        "metric_details": "口径与来源",
        "proxy_fraction": "完成人数 / 开始学习人数",
        "fraction": "计算分子 / 分母",
        "completion_rate": "课程完成率",
        "completion_calculation": "按必修课完成状态计算",
        "zero_followups": "查询成功：最近受审计样本中没有追问。",
        "operations": "经营与积分附录",
        "operations_desc": "仅因用户明确要求而包含，不作为教学效果证据。",
        "no_data": "暂无可靠数据",
        "not_collected": "本次未采集",
        "source_names": {"live": "AI 师傅平台", "supplied": "用户提供", "synthetic": "合成数据"},
    },
    "en": {
        "title_suffix": "Course Learning Report",
        "skip": "Skip to report",
        "subtitle": "Course learning report · for teaching managers and teachers",
        "footer": "Generated by AI-Shifu Learning Report from privacy-safe aggregate data. Interpret findings alongside course design and teaching context.",
        "period": "Reporting period",
        "generated": "Generated",
        "timezone": "Timezone",
        "source": "Source",
        "management": "Management conclusions",
        "management_desc": "What needs attention, why it matters, and what to do next.",
        "overall_health": "Overall assessment",
        "conclusion": "Conclusion",
        "critical_limits": "Critical limitations",
        "kpis": "Core metrics",
        "learning_path": "Learning path",
        "learning_path_desc": "Ordered reach without treating a recorded in-progress state as proof of blockage.",
        "lesson_health": "Lesson health",
        "lesson_health_desc": "Use reach, feedback, and follow-up signals to prioritize investigation.",
        "lesson": "Lesson",
        "evidence": "Evidence",
        "followups": "Follow-up themes",
        "followups_desc": "Only aggregate themes and de-identified intents from the latest audited sample are shown.",
        "sample": "Sample",
        "theme": "Theme",
        "intent": "Intent summary",
        "count_share": "Count / share",
        "engagement": "Ratings and read/listen preference",
        "engagement_desc": "Feedback, learning mode, and activity are kept as separate signals.",
        "ratings": "Ratings",
        "modes": "Read/listen preference",
        "activity": "Activity state",
        "audience": "Audience",
        "audience_desc": "Only aggregate distributions with a trusted name mapping are shown.",
        "segment": "Segment",
        "count": "Count",
        "share": "Share",
        "teaching_implication": "Teaching implication",
        "recommendations": "Teaching recommendations",
        "recommendations_desc": "Each recommendation connects observation, interpretation, confidence, action, and validation.",
        "observation": "Observation",
        "interpretation": "Interpretation",
        "action": "Action",
        "validation": "Validation method",
        "methods": "Definitions and data quality",
        "methods_desc": "How metrics are defined, what is unavailable, and how to interpret the findings.",
        "coverage": "Coverage",
        "limitations": "Limitations",
        "privacy": "Privacy handling",
        "unavailable_metrics": "Unavailable metrics",
        "metric": "Metric",
        "reason": "Reason",
        "definitions": "Metric definitions",
        "definition": "Definition",
        "unit": "Unit",
        "source_notes": "Source notes",
        "metric_details": "Definition and source",
        "proxy_fraction": "Completed / started learners",
        "fraction": "Numerator / denominator",
        "completion_rate": "Course completion rate",
        "completion_calculation": "Calculated from required-lesson completion",
        "zero_followups": "Query succeeded: no follow-up questions were observed in the latest audited sample.",
        "operations": "Operations and credits appendix",
        "operations_desc": "Included only at the user's explicit request and not used as evidence of teaching effectiveness.",
        "no_data": "No reliable data",
        "not_collected": "Not collected in this report",
        "source_names": {"live": "AI-Shifu platform", "supplied": "Supplied data", "synthetic": "Synthetic data"},
    },
}


class ReportError(ValueError):
    """Raised when report data is unsafe or violates the contract."""


class DuplicateKeyError(ReportError):
    """Raised when a JSON object repeats a key."""


def _pairs_without_duplicates(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
    result: dict[str, Any] = {}
    for key, value in pairs:
        if key in result:
            raise DuplicateKeyError(f"duplicate JSON key: {key}")
        result[key] = value
    return result


def load_json(path: Path) -> Any:
    try:
        with path.open("r", encoding="utf-8") as handle:
            return json.load(handle, object_pairs_hook=_pairs_without_duplicates)
    except OSError as exc:
        raise ReportError(f"cannot read {path}: {exc}") from exc
    except json.JSONDecodeError as exc:
        raise ReportError(
            f"invalid JSON in {path} at line {exc.lineno}, column {exc.colno}: {exc.msg}"
        ) from exc


def _resolve_ref(root: Mapping[str, Any], reference: str) -> Mapping[str, Any]:
    if not reference.startswith("#/"):
        raise ReportError(f"unsupported schema reference: {reference}")
    current: Any = root
    for part in reference[2:].split("/"):
        token = part.replace("~1", "/").replace("~0", "~")
        if not isinstance(current, Mapping) or token not in current:
            raise ReportError(f"broken schema reference: {reference}")
        current = current[token]
    if not isinstance(current, Mapping):
        raise ReportError(f"schema reference does not point to an object: {reference}")
    return current


def _matches_type(value: Any, type_name: str) -> bool:
    if type_name == "object":
        return isinstance(value, dict)
    if type_name == "array":
        return isinstance(value, list)
    if type_name == "string":
        return isinstance(value, str)
    if type_name == "number":
        return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)
    if type_name == "integer":
        return isinstance(value, int) and not isinstance(value, bool)
    if type_name == "boolean":
        return isinstance(value, bool)
    if type_name == "null":
        return value is None
    raise ReportError(f"unsupported schema type: {type_name}")


def _type_description(expected: str | Sequence[str]) -> str:
    if isinstance(expected, str):
        return expected
    return " or ".join(expected)


def validate_against_schema(
    value: Any,
    schema: Mapping[str, Any],
    root: Mapping[str, Any],
    path: str = "$",
) -> None:
    if "$ref" in schema:
        validate_against_schema(value, _resolve_ref(root, schema["$ref"]), root, path)
        return

    if "const" in schema and value != schema["const"]:
        raise ReportError(f"{path}: expected constant {schema['const']!r}")
    if "enum" in schema and value not in schema["enum"]:
        raise ReportError(f"{path}: expected one of {schema['enum']!r}, got {value!r}")

    expected = schema.get("type")
    if expected is not None:
        type_names = [expected] if isinstance(expected, str) else list(expected)
        if not any(_matches_type(value, type_name) for type_name in type_names):
            raise ReportError(
                f"{path}: expected {_type_description(expected)}, got {type(value).__name__}"
            )

    if isinstance(value, str):
        if len(value) < schema.get("minLength", 0):
            raise ReportError(f"{path}: string is shorter than allowed")
        if "maxLength" in schema and len(value) > schema["maxLength"]:
            raise ReportError(f"{path}: string is longer than allowed")
        if "pattern" in schema and re.search(schema["pattern"], value) is None:
            raise ReportError(f"{path}: value does not match required pattern")

    if isinstance(value, (int, float)) and not isinstance(value, bool):
        if "minimum" in schema and value < schema["minimum"]:
            raise ReportError(f"{path}: value is below {schema['minimum']}")
        if "maximum" in schema and value > schema["maximum"]:
            raise ReportError(f"{path}: value is above {schema['maximum']}")

    if isinstance(value, list):
        if len(value) < schema.get("minItems", 0):
            raise ReportError(f"{path}: array has too few items")
        if "maxItems" in schema and len(value) > schema["maxItems"]:
            raise ReportError(f"{path}: array has too many items")
        item_schema = schema.get("items")
        if isinstance(item_schema, Mapping):
            for index, item in enumerate(value):
                validate_against_schema(item, item_schema, root, f"{path}[{index}]")

    if isinstance(value, dict):
        if len(value) < schema.get("minProperties", 0):
            raise ReportError(f"{path}: object has too few properties")
        for key in schema.get("required", []):
            if key not in value:
                raise ReportError(f"{path}: missing required property {key!r}")

        property_names = schema.get("propertyNames")
        if isinstance(property_names, Mapping):
            for key in value:
                validate_against_schema(key, property_names, root, f"{path}.<key>")

        properties = schema.get("properties", {})
        additional = schema.get("additionalProperties", True)
        for key, item in value.items():
            child_path = f"{path}.{key}"
            if key in properties:
                validate_against_schema(item, properties[key], root, child_path)
            elif additional is False:
                raise ReportError(f"{path}: unexpected property {key!r}")
            elif isinstance(additional, Mapping):
                validate_against_schema(item, additional, root, child_path)


def _walk(value: Any, path: str = "$") -> Iterator[tuple[str, Any]]:
    yield path, value
    if isinstance(value, dict):
        for key, item in value.items():
            yield from _walk(item, f"{path}.{key}")
    elif isinstance(value, list):
        for index, item in enumerate(value):
            yield from _walk(item, f"{path}[{index}]")


def privacy_scan(report: Mapping[str, Any]) -> None:
    for path, value in _walk(report):
        if isinstance(value, dict):
            for key in value:
                if FORBIDDEN_KEY.search(key):
                    raise ReportError(f"{path}.{key}: forbidden raw or identifying field")
        elif isinstance(value, str):
            checks = (
                (EMAIL, "email address"),
                (PHONE, "phone number"),
                (MASKED_PHONE, "masked phone number"),
                (MASKED_EMAIL, "masked email address"),
                (ID_CARD, "identity-card number"),
                (INTERNAL_ID, "learner-level internal identifier"),
                (REDACTED_IDENTITY, "masked identity placeholder"),
                (AUTH_SECRET, "authentication secret"),
                (RAW_BID, "raw BID"),
                (OPAQUE_ID, "opaque internal identifier"),
                (RAW_ENUM_CODE, "raw platform enum code"),
                (RAW_ENUM, "raw identifier or enum code"),
            )
            for pattern, label in checks:
                if pattern.search(value):
                    raise ReportError(f"{path}: contains a forbidden {label}")


def iter_metrics(report: Mapping[str, Any]) -> Iterator[tuple[str, Mapping[str, Any]]]:
    overview = report["overview"]
    for index, metric in enumerate(overview["kpis"]):
        yield f"$.overview.kpis[{index}]", metric
    for index, stage in enumerate(overview["learning_path"]):
        yield f"$.overview.learning_path[{index}].metric", stage["metric"]
    for lesson_index, lesson in enumerate(report["lesson_health"]):
        for metric_index, metric in enumerate(lesson["metrics"]):
            yield f"$.lesson_health[{lesson_index}].metrics[{metric_index}]", metric
    for group in ("ratings", "learning_modes", "activity"):
        for index, metric in enumerate(report["engagement"][group]):
            yield f"$.engagement.{group}[{index}]", metric
    if "operations" in report:
        for index, metric in enumerate(report["operations"]["metrics"]):
            yield f"$.operations.metrics[{index}]", metric


def validate_semantics(report: Mapping[str, Any]) -> None:
    definitions = report["metric_definitions"]
    metric_paths: dict[str, str] = {}
    metrics: dict[str, Mapping[str, Any]] = {}
    operation_keys = {
        metric["key"] for metric in report.get("operations", {}).get("metrics", [])
    }

    for path, metric in iter_metrics(report):
        key = metric["key"]
        if FORBIDDEN_KEY.search(key):
            raise ReportError(f"{path}.key: forbidden identifier-like metric key {key!r}")
        if key in metrics:
            raise ReportError(f"{path}.key: duplicate metric key {key!r}; first seen at {metric_paths[key]}")
        metrics[key] = metric
        metric_paths[key] = path
        if key not in definitions:
            raise ReportError(f"{path}.key: metric {key!r} is missing from metric_definitions")
        definition = definitions[key]
        for field in ("label", "definition", "unit"):
            if metric[field] != definition[field]:
                raise ReportError(
                    f"{path}.{field}: does not match metric_definitions[{key!r}]"
                )

        quality = metric["data_quality"]
        value = metric["value"]
        if value is None and quality not in {"partial", "unavailable", "not_collected"}:
            raise ReportError(f"{path}: null value requires partial, unavailable, or not_collected quality")
        if value is not None and quality in {"unavailable", "not_collected"}:
            raise ReportError(f"{path}: unavailable/not_collected metric must have a null value")
        if metric["is_approximate"] and quality != "approximate":
            raise ReportError(f"{path}: an approximate metric must use data_quality='approximate'")
        if quality == "approximate" and not metric["is_approximate"]:
            raise ReportError(f"{path}: approximate data quality requires is_approximate=true")
        if metric["unit"] == "%" and value is not None:
            if (
                not isinstance(value, (int, float))
                or isinstance(value, bool)
                or value < 0
                or value > 100
            ):
                raise ReportError(f"{path}: percentage metric value must be numeric from 0 to 100")

    completion_metrics = [
        (key, metric) for key, metric in metrics.items() if key.endswith("completion_proxy")
    ]
    if len(completion_metrics) != 1:
        raise ReportError(
            "report must contain exactly one metric whose key ends with 'completion_proxy'"
        )
    completion_key, completion = completion_metrics[0]
    if completion["value"] is not None:
        numerator = completion.get("numerator")
        denominator = completion.get("denominator")
        if not completion["is_approximate"]:
            raise ReportError(f"metric {completion_key!r}: completion proxy must be approximate")
        if not isinstance(numerator, (int, float)) or isinstance(numerator, bool):
            raise ReportError(f"metric {completion_key!r}: numerator is required")
        if not isinstance(denominator, (int, float)) or isinstance(denominator, bool) or denominator <= 0:
            raise ReportError(f"metric {completion_key!r}: positive denominator is required")
        if numerator < 0 or numerator > denominator:
            raise ReportError(f"metric {completion_key!r}: numerator must be between zero and denominator")
        expected = numerator / denominator
        if completion["unit"] == "%":
            expected *= 100
        if not isinstance(completion["value"], (int, float)) or isinstance(completion["value"], bool):
            raise ReportError(f"metric {completion_key!r}: proxy value must be numeric")
        if not math.isclose(float(completion["value"]), expected, rel_tol=0.002, abs_tol=0.11):
            raise ReportError(
                f"metric {completion_key!r}: value does not match numerator/denominator"
            )

    for lesson_index, lesson in enumerate(report["lesson_health"]):
        for reference in lesson["evidence"]:
            if reference not in metrics or reference in operation_keys:
                raise ReportError(
                    f"$.lesson_health[{lesson_index}].evidence: unknown or non-teaching metric {reference!r}"
                )

    for recommendation_index, recommendation in enumerate(report["recommendations"]):
        for reference in recommendation["evidence"]:
            if reference not in metrics or reference in operation_keys:
                raise ReportError(
                    f"$.recommendations[{recommendation_index}].evidence: unknown or non-teaching metric {reference!r}"
                )

    followups = report["engagement"]["follow_up_analysis"]
    status = followups["status"]
    if status == "available":
        if followups["sample_size"] is None or followups["audited_access"] is not True:
            raise ReportError(
                "$.engagement.follow_up_analysis: available themes require an audited sample size"
            )
        if followups["sample_size"] == 0 and followups["themes"]:
            raise ReportError(
                "$.engagement.follow_up_analysis.themes: zero-sized sample cannot have themes"
            )
        for index, theme in enumerate(followups["themes"]):
            if theme["count"] > followups["sample_size"]:
                raise ReportError(
                    f"$.engagement.follow_up_analysis.themes[{index}].count exceeds sample size"
                )
            if followups["sample_size"] > 0:
                expected_share = theme["count"] / followups["sample_size"]
                if theme["share"] is None or not math.isclose(
                    theme["share"], expected_share, rel_tol=0.001, abs_tol=0.001
                ):
                    raise ReportError(
                        f"$.engagement.follow_up_analysis.themes[{index}].share "
                        "does not match count/sample_size"
                    )
    else:
        if followups["sample_size"] is not None or followups["themes"]:
            raise ReportError(
                "$.engagement.follow_up_analysis: unavailable/not_collected state must not contain a sample or themes"
            )
        if status == "not_collected" and followups["audited_access"]:
            raise ReportError(
                "$.engagement.follow_up_analysis: not_collected state cannot claim audited access"
            )

    audience = report["audience"]
    if audience["status"] == "unavailable" and audience["dimensions"]:
        raise ReportError("$.audience.dimensions: unavailable audience must not invent dimensions")
    if audience["status"] == "available" and not audience["dimensions"]:
        raise ReportError("$.audience.dimensions: available audience requires at least one dimension")
    for dimension_index, dimension in enumerate(audience["dimensions"]):
        total = sum(segment["count"] for segment in dimension["segments"])
        for segment_index, segment in enumerate(dimension["segments"]):
            expected_share = segment["count"] / total if total else None
            if expected_share is None:
                if segment["share"] not in {None, 0}:
                    raise ReportError(
                        f"$.audience.dimensions[{dimension_index}].segments[{segment_index}].share "
                        "must be null or zero when the dimension has no observations"
                    )
            elif segment["share"] is None or not math.isclose(
                segment["share"], expected_share, rel_tol=0.001, abs_tol=0.001
            ):
                raise ReportError(
                    f"$.audience.dimensions[{dimension_index}].segments[{segment_index}].share "
                    "does not match count/dimension total"
                )

    lesson_positions = [lesson["position"] for lesson in report["lesson_health"]]
    if lesson_positions != sorted(set(lesson_positions)):
        raise ReportError("$.lesson_health: positions must be unique and ordered")

    path_metrics = [stage["metric"] for stage in report["overview"]["learning_path"]]
    if path_metrics:
        path_unit = path_metrics[0]["unit"]
        path_scope = path_metrics[0]["time_scope"]
        for index, metric in enumerate(path_metrics):
            if metric["unit"] != path_unit or metric["time_scope"] != path_scope:
                raise ReportError(
                    f"$.overview.learning_path[{index}].metric: all path stages must use "
                    "the same unit and time scope"
                )
            if metric["value"] is not None and (
                not isinstance(metric["value"], (int, float))
                or isinstance(metric["value"], bool)
            ):
                raise ReportError(
                    f"$.overview.learning_path[{index}].metric.value: path charts require numeric or null values"
                )

    try:
        datetime.fromisoformat(report["meta"]["generated_at"].replace("Z", "+00:00"))
    except ValueError as exc:
        raise ReportError("$.meta.generated_at: expected an ISO 8601 date-time") from exc

    privacy_scan(report)


def validate_report(report: Any) -> Mapping[str, Any]:
    if not isinstance(report, dict):
        raise ReportError("$: report must be a JSON object")
    schema = load_json(SCHEMA_PATH)
    if not isinstance(schema, dict):
        raise ReportError(f"schema is not an object: {SCHEMA_PATH}")
    validate_against_schema(report, schema, schema)
    validate_semantics(report)
    return report


def esc(value: Any) -> str:
    return html.escape(str(value), quote=True)


def _language(meta: Mapping[str, Any]) -> tuple[bool, Mapping[str, Any]]:
    is_zh = meta["language"].lower().startswith("zh")
    return is_zh, TEXT["zh" if is_zh else "en"]


def _relative_luminance(color: str) -> float:
    channels = [int(color[index : index + 2], 16) / 255 for index in (1, 3, 5)]

    def linear(channel: float) -> float:
        return channel / 12.92 if channel <= 0.04045 else ((channel + 0.055) / 1.055) ** 2.4

    red, green, blue = (linear(channel) for channel in channels)
    return 0.2126 * red + 0.7152 * green + 0.0722 * blue


def _safe_accent(value: Any) -> str:
    fallback = "#D6001C"
    if not isinstance(value, str) or VALID_ACCENT.fullmatch(value) is None:
        return fallback
    contrast_with_white = 1.05 / (_relative_luminance(value) + 0.05)
    return value if contrast_with_white >= 4.5 else fallback


def _format_generated_at(value: str, is_zh: bool) -> str:
    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
    if is_zh:
        return f"{parsed.year}年{parsed.month}月{parsed.day}日 {parsed.hour:02d}:{parsed.minute:02d}"
    month = (
        "Jan",
        "Feb",
        "Mar",
        "Apr",
        "May",
        "Jun",
        "Jul",
        "Aug",
        "Sep",
        "Oct",
        "Nov",
        "Dec",
    )[parsed.month - 1]
    return f"{month} {parsed.day}, {parsed.year} {parsed.hour:02d}:{parsed.minute:02d}"


def _enum_label(mapping: Mapping[str, tuple[str, str]], value: str, is_zh: bool) -> str:
    labels = mapping.get(value)
    return labels[0 if is_zh else 1] if labels else value


def _format_number(value: int | float) -> str:
    if isinstance(value, int) or float(value).is_integer():
        return f"{int(value):,}"
    return f"{value:,.2f}".rstrip("0").rstrip(".")


def _format_share(value: int | float | None, strings: Mapping[str, Any]) -> str:
    if value is None:
        return str(strings["no_data"])
    return f"{value:.1%}"


def format_metric_value(metric: Mapping[str, Any], strings: Mapping[str, Any]) -> str:
    value = metric["value"]
    if value is None:
        return esc(strings["no_data"])
    if isinstance(value, (int, float)) and not isinstance(value, bool):
        rendered = _format_number(value)
    else:
        rendered = esc(value)
    unit = metric["unit"]
    if unit:
        separator = "" if unit in {"%", "分", "人", "次", "条", "节"} else " "
        rendered += separator + esc(unit)
    if metric["is_approximate"] and not metric["key"].endswith("completion_proxy"):
        rendered += f'<span class="approx-tag">{esc(DATA_QUALITY_LABELS["approximate"][0 if strings is TEXT["zh"] else 1])}</span>'
    return rendered


def display_metric_label(metric: Mapping[str, Any], strings: Mapping[str, Any]) -> str:
    if metric["key"].endswith("completion_proxy"):
        return str(strings["completion_rate"])
    return str(metric["label"])


def _list_html(items: Iterable[str], empty_text: str) -> str:
    values = list(items)
    if not values:
        return f'<p class="empty-state">{esc(empty_text)}</p>'
    return "<ul>" + "".join(f"<li>{esc(item)}</li>" for item in values) + "</ul>"


def _section_heading(index: int, title: str, description: str, heading_id: str) -> str:
    return (
        '<div class="section-heading"><div>'
        f'<span class="section-index">{index:02d}</span>'
        f'<h2 id="{esc(heading_id)}">{esc(title)}</h2>'
        f'<p class="section-description">{esc(description)}</p>'
        "</div></div>"
    )


def render_summary(report: Mapping[str, Any], strings: Mapping[str, Any]) -> str:
    summary = report["overview"]["executive_summary"]
    conclusions = "".join(
        '<article class="conclusion-card">'
        f'<strong>{esc(strings["conclusion"])} {index}</strong><p>{esc(item)}</p>'
        "</article>"
        for index, item in enumerate(summary["conclusions"], start=1)
    )
    limitations = summary["critical_limitations"]
    limitation_html = ""
    if limitations:
        limitation_html = (
            '<aside class="limitation-callout" aria-label="'
            + esc(strings["critical_limits"])
            + '"><strong>'
            + esc(strings["critical_limits"])
            + "：</strong> "
            + "；".join(esc(item) for item in limitations)
            + "</aside>"
        )
    kpis = "".join(render_kpi(metric, strings) for metric in report["overview"]["kpis"])
    return (
        '<section class="section summary-band" aria-labelledby="summary-heading">'
        '<div class="section-heading"><div><span class="section-index">01</span>'
        f'<h2 id="summary-heading">{esc(strings["management"])}</h2>'
        f'<p class="section-description">{esc(strings["management_desc"])}</p>'
        "</div></div>"
        '<div class="health-line"><span class="health-label">'
        + esc(strings["overall_health"])
        + '</span><span class="health-value">'
        + esc(summary["overall_health"])
        + "</span></div>"
        + f'<div class="conclusion-grid">{conclusions}</div>'
        + limitation_html
        + f'<h3 class="subsection-heading">{esc(strings["kpis"])}</h3>'
        + f'<div class="kpi-grid">{kpis}</div>'
        + "</section>"
    )


def render_kpi(metric: Mapping[str, Any], strings: Mapping[str, Any]) -> str:
    quality = (
        strings["completion_calculation"]
        if metric["key"].endswith("completion_proxy") and metric["value"] is not None
        else _enum_label(DATA_QUALITY_LABELS, metric["data_quality"], strings is TEXT["zh"])
    )
    scope = metric["time_scope"]["label"]
    numerator = metric.get("numerator")
    denominator = metric.get("denominator")
    fraction = ""
    if numerator is not None and denominator is not None:
        fraction_label = (
            strings["proxy_fraction"]
            if metric["key"].endswith("completion_proxy")
            else strings["fraction"]
        )
        fraction = (
            f'<span class="proxy-fraction">{esc(fraction_label)}：'
            f'{esc(_format_number(numerator))} / {esc(_format_number(denominator))}</span>'
        )
    return (
        '<article class="kpi-card">'
        f'<span class="kpi-label">{esc(display_metric_label(metric, strings))}</span>'
        f'<span class="kpi-value">{format_metric_value(metric, strings)}</span>'
        + fraction
        + f'<span class="kpi-meta">{esc(scope)} · {esc(quality)}</span>'
        + render_metric_details(metric, strings)
        + "</article>"
    )


def render_metric_details(metric: Mapping[str, Any], strings: Mapping[str, Any]) -> str:
    notes = "；".join(esc(note) for note in metric["source_notes"])
    return (
        '<details class="metric-details"><summary>'
        + esc(strings["metric_details"])
        + '</summary><div class="details-body"><p>'
        + esc(metric["definition"])
        + "</p><p>"
        + notes
        + "</p></div></details>"
    )


def render_learning_path(report: Mapping[str, Any], strings: Mapping[str, Any], index: int) -> str:
    stages = report["overview"]["learning_path"]
    numeric = [
        float(stage["metric"]["value"])
        for stage in stages
        if isinstance(stage["metric"]["value"], (int, float))
        and not isinstance(stage["metric"]["value"], bool)
    ]
    maximum = max(numeric, default=0.0)
    rows: list[str] = []
    for stage in stages:
        metric = stage["metric"]
        value = metric["value"]
        if isinstance(value, (int, float)) and not isinstance(value, bool) and maximum > 0:
            width = max(0.0, min(100.0, float(value) / maximum * 100))
            bar = (
                f'<div class="bar-track"><div class="bar-fill" style="width:{width:.2f}%"></div></div>'
            )
        else:
            bar = '<div class="bar-track"><div class="bar-fill" style="width:0"></div></div>'
        value_label = format_metric_value(metric, strings)
        quality_label = _enum_label(
            DATA_QUALITY_LABELS, metric["data_quality"], strings is TEXT["zh"]
        )
        source_summary = "；".join(metric["source_notes"])
        path_note = (
            f'{stage["note"]} · {metric["time_scope"]["label"]} · '
            f"{quality_label} · {source_summary}"
        )
        aria = (
            f'{stage["stage"]}: {re.sub("<[^>]+>", "", value_label)}. '
            f"{path_note}"
        )
        rows.append(
            f'<div class="path-row" role="img" aria-label="{esc(aria)}">'
            f'<div class="path-stage">{esc(stage["stage"])}</div>{bar}'
            f'<div class="bar-label">{value_label}</div>'
            f'<div class="path-note">{esc(path_note)}</div></div>'
        )
    content = "".join(rows) if rows else f'<div class="empty-state">{esc(strings["no_data"])}</div>'
    return (
        f'<section class="section" aria-labelledby="path-heading">{_section_heading(index, strings["learning_path"], strings["learning_path_desc"], "path-heading")}'
        f'<div class="path-list">{content}</div></section>'
    )


def _metric_rows(metrics: Sequence[Mapping[str, Any]], strings: Mapping[str, Any]) -> str:
    if not metrics:
        return f'<div class="empty-state">{esc(strings["no_data"])}</div>'
    return (
        '<dl class="metric-list">'
        + "".join(_render_metric_row(metric, strings) for metric in metrics)
        + "</dl>"
    )


def _render_metric_row(metric: Mapping[str, Any], strings: Mapping[str, Any]) -> str:
    quality = (
        strings["completion_calculation"]
        if metric["key"].endswith("completion_proxy") and metric["value"] is not None
        else _enum_label(DATA_QUALITY_LABELS, metric["data_quality"], strings is TEXT["zh"])
    )
    context = f'{metric["time_scope"]["label"]} · {quality}'
    return (
        '<div class="metric-row"><dt>'
        + esc(display_metric_label(metric, strings))
        + f'<span class="metric-context">{esc(context)}</span></dt>'
        + f'<dd>{format_metric_value(metric, strings)}</dd>'
        + render_metric_details(metric, strings)
        + "</div>"
    )


def render_evidence_badges(
    references: Sequence[str],
    metrics: Mapping[str, Mapping[str, Any]],
    strings: Mapping[str, Any],
) -> str:
    return "".join(
        '<span class="evidence-ref">'
        + esc(display_metric_label(metrics[reference], strings))
        + "："
        + format_metric_value(metrics[reference], strings)
        + "</span>"
        for reference in references
    )


def render_lessons(report: Mapping[str, Any], strings: Mapping[str, Any], index: int) -> str:
    cards: list[str] = []
    is_zh = strings is TEXT["zh"]
    metrics = {metric["key"]: metric for _, metric in iter_metrics(report)}
    for lesson in report["lesson_health"]:
        status = lesson["health_status"]
        status_label = _enum_label(HEALTH_LABELS, status, is_zh)
        evidence = render_evidence_badges(lesson["evidence"], metrics, strings)
        cards.append(
            '<article class="lesson-card">'
            '<div class="lesson-card-header"><div>'
            f'<span class="lesson-order">{esc(strings["lesson"])} {lesson["position"]:02d}</span>'
            f'<h3>{esc(lesson["title"])}</h3></div>'
            f'<span class="status-pill is-{esc(status)}">{esc(status_label)}</span></div>'
            '<div class="lesson-card-body">'
            f'<p class="lesson-finding">{esc(lesson["finding"])}</p>'
            + _metric_rows(lesson["metrics"], strings)
            + f'<div class="evidence-list" aria-label="{esc(strings["evidence"])}">{evidence}</div>'
            + "</div></article>"
        )
    content = "".join(cards) if cards else f'<div class="empty-state">{esc(strings["no_data"])}</div>'
    return (
        f'<section class="section" aria-labelledby="lessons-heading">{_section_heading(index, strings["lesson_health"], strings["lesson_health_desc"], "lessons-heading")}'
        f'<div class="lesson-grid">{content}</div></section>'
    )


def render_followups(report: Mapping[str, Any], strings: Mapping[str, Any], index: int) -> str:
    followups = report["engagement"]["follow_up_analysis"]
    status = followups["status"]
    if status == "available":
        sample_size = followups["sample_size"]
        span = followups["effective_span"] or strings["no_data"]
        sample_note = (
            f'{strings["sample"]}：{followups["sampling_rule"]} · '
            f'{sample_size}/{followups["sample_limit"]} · {span}'
        )
        themes: list[str] = []
        for theme in followups["themes"]:
            share = strings["no_data"] if theme["share"] is None else f'{theme["share"]:.1%}'
            lesson_labels = "、".join(theme["lesson_labels"])
            suffix = f" · {lesson_labels}" if lesson_labels else ""
            themes.append(
                '<div class="theme-row" role="listitem">'
                f'<div><h3>{esc(theme["theme"])}</h3><span class="kpi-meta">{esc(suffix.lstrip(" ·"))}</span></div>'
                f'<div class="theme-intent">{esc(theme["intent_summary"])}</div>'
                f'<div class="theme-count">{theme["count"]} · {esc(share)}</div></div>'
            )
        if sample_size == 0:
            body = f'<div class="empty-state">{esc(strings["zero_followups"])}</div>'
        else:
            body = "".join(themes)
    else:
        sample_note = followups["sampling_rule"]
        state_text = strings["not_collected"] if status == "not_collected" else strings["no_data"]
        body = f'<div class="empty-state">{esc(state_text)}</div>'
    return (
        f'<section class="section" aria-labelledby="followups-heading">{_section_heading(index, strings["followups"], strings["followups_desc"], "followups-heading")}'
        f'<p class="sample-note">{esc(sample_note)}</p>'
        f'<div class="theme-list" role="list" aria-label="{esc(strings["followups"])}">{body}</div></section>'
    )


def render_engagement(report: Mapping[str, Any], strings: Mapping[str, Any], index: int) -> str:
    engagement = report["engagement"]
    groups = (
        (strings["ratings"], engagement["ratings"]),
        (strings["modes"], engagement["learning_modes"]),
        (strings["activity"], engagement["activity"]),
    )
    cards = "".join(
        f'<article class="quality-card"><h3>{esc(title)}</h3>{_metric_rows(metrics, strings)}</article>'
        for title, metrics in groups
    )
    return (
        f'<section class="section" aria-labelledby="engagement-heading">{_section_heading(index, strings["engagement"], strings["engagement_desc"], "engagement-heading")}'
        f'<div class="quality-grid">{cards}</div></section>'
    )


def render_audience(report: Mapping[str, Any], strings: Mapping[str, Any], index: int) -> str:
    audience = report["audience"]
    dimensions: list[str] = []
    for dimension in audience["dimensions"]:
        rows = "".join(
            f'<tr><td>{esc(segment["label"])}</td><td>{segment["count"]:,}</td>'
            f'<td>{esc(_format_share(segment["share"], strings))}</td></tr>'
            for segment in dimension["segments"]
        )
        dimensions.append(
            '<article class="audience-dimension">'
            f'<h3>{esc(dimension["name"])}</h3><div class="table-wrap"><table>'
            f'<caption>{esc(dimension["name"])}</caption><thead><tr><th>{esc(strings["segment"])}</th>'
            f'<th>{esc(strings["count"])}</th><th>{esc(strings["share"])}</th></tr></thead>'
            f'<tbody>{rows}</tbody></table></div>'
            f'<p class="audience-implication"><strong>{esc(strings["teaching_implication"])}：</strong> '
            f'{esc(dimension["teaching_implication"])}</p></article>'
        )
    if not dimensions:
        body = f'<div class="empty-state">{esc(audience["note"])}</div>'
    else:
        body = "".join(dimensions) + f'<p class="privacy-callout">{esc(audience["note"])}</p>'
    return (
        f'<section class="section" aria-labelledby="audience-heading">{_section_heading(index, strings["audience"], strings["audience_desc"], "audience-heading")}'
        f'<div>{body}</div></section>'
    )


def render_recommendations(report: Mapping[str, Any], strings: Mapping[str, Any], index: int) -> str:
    is_zh = strings is TEXT["zh"]
    cards: list[str] = []
    metrics = {metric["key"]: metric for _, metric in iter_metrics(report)}
    for recommendation in report["recommendations"]:
        priority = recommendation["priority"]
        confidence = recommendation["confidence"]
        evidence = render_evidence_badges(recommendation["evidence"], metrics, strings)
        cards.append(
            '<article class="recommendation-card">'
            '<div class="recommendation-top">'
            f'<h3>{esc(recommendation["title"])}</h3>'
            f'<span class="priority-pill is-{esc(priority)}">{esc(_enum_label(PRIORITY_LABELS, priority, is_zh))}</span>'
            "</div><dl>"
            f'<div><dt>{esc(strings["observation"])}</dt><dd>{esc(recommendation["observation"])}</dd></div>'
            f'<div><dt>{esc(strings["interpretation"])}</dt><dd>{esc(recommendation["interpretation"])}</dd></div>'
            f'<div><dt>{esc(_enum_label(CONFIDENCE_LABELS, confidence, is_zh))}</dt><dd>'
            f'<span class="confidence-pill is-{esc(confidence)}">{esc(_enum_label(CONFIDENCE_LABELS, confidence, is_zh))}</span></dd></div>'
            f'<div><dt>{esc(strings["action"])}</dt><dd>{esc(recommendation["action"])}</dd></div>'
            f'<div><dt>{esc(strings["validation"])}</dt><dd>{esc(recommendation["validation"])}</dd></div>'
            "</dl>"
            f'<div class="evidence-list" aria-label="{esc(strings["evidence"])}">{evidence}</div>'
            "</article>"
        )
    return (
        f'<section class="section" aria-labelledby="recommendations-heading">{_section_heading(index, strings["recommendations"], strings["recommendations_desc"], "recommendations-heading")}'
        f'<div class="recommendation-grid">{"".join(cards)}</div></section>'
    )


def render_methods(report: Mapping[str, Any], strings: Mapping[str, Any], index: int) -> str:
    quality = report["data_quality"]
    cards = (
        f'<article class="quality-card"><h3>{esc(strings["coverage"])}</h3>{_list_html(quality["coverage_notes"], strings["no_data"])}</article>'
        f'<article class="quality-card"><h3>{esc(strings["limitations"])}</h3>{_list_html(quality["limitations"], strings["no_data"])}</article>'
        f'<article class="quality-card"><h3>{esc(strings["privacy"])}</h3>{_list_html(quality["privacy_notes"], strings["no_data"])}</article>'
    )
    unavailable = quality["unavailable_metrics"]
    if unavailable:
        rows = "".join(
            f'<tr><td>{esc(strings["completion_rate"] if item["key"].endswith("completion_proxy") else item["label"])}</td><td>{esc(item["reason"])}</td></tr>'
            for item in unavailable
        )
        unavailable_html = (
            f'<h3 class="subsection-heading">{esc(strings["unavailable_metrics"])}</h3>'
            '<div class="table-wrap"><table><thead><tr>'
            f'<th>{esc(strings["metric"])}</th><th>{esc(strings["reason"])}</th>'
            f'</tr></thead><tbody>{rows}</tbody></table></div>'
        )
    else:
        unavailable_html = ""

    definition_rows = "".join(
        f'<tr><td>{esc(display_metric_label({**item, "key": key}, strings))}</td>'
        f'<td>{esc(item["definition"])}</td><td>{esc(item["unit"])}</td>'
        f'<td>{"；".join(esc(note) for note in item["source_notes"])}</td></tr>'
        for key, item in sorted(report["metric_definitions"].items())
    )
    details = (
        '<details><summary>'
        + esc(strings["definitions"])
        + '</summary><div class="details-body table-wrap"><table><thead><tr>'
        + f'<th>{esc(strings["metric"])}</th><th>{esc(strings["definition"])}</th>'
        + f'<th>{esc(strings["unit"])}</th><th>{esc(strings["source_notes"])}</th>'
        + f"</tr></thead><tbody>{definition_rows}</tbody></table></div></details>"
    )
    return (
        f'<section class="section" aria-labelledby="methods-heading">{_section_heading(index, strings["methods"], strings["methods_desc"], "methods-heading")}'
        f'<div class="quality-grid">{cards}</div>{unavailable_html}{details}</section>'
    )


def render_operations(report: Mapping[str, Any], strings: Mapping[str, Any], index: int) -> str:
    operations = report["operations"]
    return (
        f'<section class="section" aria-labelledby="operations-heading">{_section_heading(index, strings["operations"], strings["operations_desc"], "operations-heading")}'
        f'<p class="privacy-callout">{esc(operations["note"])}</p>'
        f'<div class="kpi-grid">{"".join(render_kpi(metric, strings) for metric in operations["metrics"])}</div></section>'
    )


def render_body(report: Mapping[str, Any], strings: Mapping[str, Any]) -> str:
    sections = [
        render_summary(report, strings),
        render_learning_path(report, strings, 2),
        render_lessons(report, strings, 3),
        render_followups(report, strings, 4),
        render_engagement(report, strings, 5),
        render_audience(report, strings, 6),
        render_recommendations(report, strings, 7),
        render_methods(report, strings, 8),
    ]
    if "operations" in report:
        sections.append(render_operations(report, strings, 9))
    return "".join(sections)


def render_report(report: Mapping[str, Any]) -> str:
    meta = report["meta"]
    is_zh, strings = _language(meta)
    brand = meta.get("brand", {})
    accent = _safe_accent(brand.get("accent_color"))
    organization_name = brand.get("organization_name", "AI 师傅" if strings is TEXT["zh"] else "AI-Shifu")
    logo_text = brand.get("logo_text", "AI 师傅" if strings is TEXT["zh"] else "AI-Shifu")
    period = meta["period"]
    source_name = strings["source_names"].get(meta["source_kind"], meta["source_kind"])
    timezone_label = meta["timezone"]
    if is_zh and timezone_label == "Asia/Shanghai":
        timezone_label = "中国标准时间（Asia/Shanghai）"
    report_meta = "".join(
        (
            f'<span><strong>{esc(strings["period"])}：</strong>{esc(period["label"])}</span>',
            f'<span><strong>{esc(strings["generated"])}：</strong>{esc(_format_generated_at(meta["generated_at"], is_zh))}</span>',
            f'<span><strong>{esc(strings["timezone"])}：</strong>{esc(timezone_label)}</span>',
            f'<span><strong>{esc(strings["source"])}：</strong>{esc(source_name)}</span>',
        )
    )
    try:
        template = TEMPLATE_PATH.read_text(encoding="utf-8")
    except OSError as exc:
        raise ReportError(f"cannot read template {TEMPLATE_PATH}: {exc}") from exc
    replacements = {
        "{{LANG}}": esc(meta["language"]),
        "{{COURSE_TITLE}}": esc(meta["course_title"]),
        "{{TITLE_SUFFIX}}": esc(strings["title_suffix"]),
        "{{ACCENT_COLOR}}": accent,
        "{{ORGANIZATION_NAME}}": esc(organization_name),
        "{{LOGO_TEXT}}": esc(logo_text),
        "{{SKIP_TEXT}}": esc(strings["skip"]),
        "{{REPORT_SUBTITLE}}": esc(strings["subtitle"]),
        "{{FOOTER_TEXT}}": esc(strings["footer"]),
        "{{REPORT_META}}": report_meta,
        "{{REPORT_BODY}}": render_body(report, strings),
    }
    def replace_placeholder(match: re.Match[str]) -> str:
        placeholder = match.group(0)
        if placeholder not in replacements:
            raise ReportError(f"template has unknown placeholder: {placeholder}")
        return replacements[placeholder]

    return TEMPLATE_PLACEHOLDER.sub(replace_placeholder, template)


def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Validate and render an AI-Shifu course learning report."
    )
    parser.add_argument("--input", required=True, type=Path, help="schema-version 1.0 JSON")
    parser.add_argument("--output", type=Path, help="self-contained HTML output")
    parser.add_argument(
        "--validate-only",
        action="store_true",
        help="validate schema, semantics, and privacy without rendering",
    )
    args = parser.parse_args(argv)
    if not args.validate_only and args.output is None:
        parser.error("--output is required unless --validate-only is used")
    return args


def main(argv: Sequence[str] | None = None) -> int:
    args = parse_args(argv)
    try:
        report = validate_report(load_json(args.input))
        if args.validate_only:
            print(f"Valid report data: {args.input}")
            return 0
        rendered = render_report(report)
        args.output.parent.mkdir(parents=True, exist_ok=True)
        args.output.write_text(rendered, encoding="utf-8")
        print(f"Rendered report: {args.output}")
        return 0
    except (ReportError, OSError) as exc:
        print(f"Report validation failed: {exc}", file=sys.stderr)
        return 1


if __name__ == "__main__":
    raise SystemExit(main())