@1aboveio/skills 1.0.21 → 1.0.23

package/skills/risk-compliance/portfolio-payment-analysis/SKILL.md

@@ -1,170 +1,90 @@
 ---
 name: portfolio-payment-analysis
-description: >
-  Analyze submerchants in Helipay/Worldpay aggregator exports: compare merchants
-  and investigate selected merchants' authorization, settlement and disputes,
-  including descriptor mapping and overlapping exports. Portfolio-level payment
-  overviews belong to payment-analysis; fraud rule discovery belongs to fraud-detection.
-release-version: 0.50.1
+description: Analyze Helipay/Worldpay submerchants from authorization, settlement, dispute and DART-340 exports; compare merchants and produce an offline interactive Chinese merchant report. Use for aggregator merchant comparisons, merchant authorization performance, issuer drilldown, merchant fraud/dispute histories and VAMP extract estimates. Portfolio-wide overviews belong to payment-analysis; fraud rule discovery belongs to fraud-detection.
+release-version: 0.50.3
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Portfolio payment analysis
 
-Before report drafting or substantive review, read
-`{house-style baseDir}/references/analytical-reporting.md` and its
-required writing-pattern and definition references. Use `write-report` for the report stage
-with this skill's merchant template, not `write-doc` or the portfolio report layout. Give
-delegated writers and reviewers the same resolved reference paths and require the reads;
-keep merchant metrics, confidentiality and specialist checks unchanged. Individual native
-selections also need `write-report` and its required `terminology` dependency; installation
-metadata does not load instructions. Missing required resources leave the report stage incomplete.
+Analyze attributed payment portfolios and produce an internal Chinese merchant report
+by default. Worldpay CSV and DART-340 are the bundled adapters; other sources need
+verified field and identity mappings. Keep private extracts local and synthetic
+fixtures in the repository.
 
-Produce an internal submerchant report in Chinese by default, with merchant comparisons
-and detail for merchants the user selects. Treat the extracts as confidential; do not
-publish them or include cardholder data in the report. Use the installed
-`payment-analysis` skill as the base: read its `SKILL.md` and relevant references for
-periods, event layers, metrics, daily USD FX, disputes, visualization and editorial
-checks. This skill owns the aggregator report structure in
-[metrics and reporting](references/metrics-and-reporting.md); that template replaces
-the base report's chapter order and mandatory Sankey. Inherit the base's metric,
-FX, dispute, terminology and fact-preservation rules. Pass the aggregator template
-to editorial review. Scope any payment-stage evidence to a merchant; do not include a
-portfolio funnel or Sankey.
-
-For a clean individual native installation, select `portfolio-payment-analysis`,
-`payment-analysis`, `write-report`, `editorial-review`, `polish-cn`, `terminology`, and `house-style`; the native
-picker does not install dependencies automatically. The generated Payment install
-group recipe includes the dependency closure.
+Start with [workflow and module contracts](references/workflow-and-contracts.md), then
+apply the [report structure](references/metrics-and-reporting.md). Follow the stages
+below in order; scripts implement these contracts rather than define business scope.
 
 ## Workflow
 
-1. Inventory authorized Helipay/Worldpay inputs, source coverage, event dates,
-   timezone, currencies, identifiers, field dictionaries and reporting periods.
-   Record missing and partial layers. Use the requested period and merchant selection;
-   otherwise apply the base skill's period-selection rule, then pass both required
-   CLI dates explicitly. Identify an unsupported or unresolved period
-   rather than inventing one.
-2. Read [identity and reconciliation](references/identity-and-reconciliation.md)
-   before deduplication or joining. Build the mapping and reconciliation evidence;
-   scope every join to the same verified merchant and source namespace. Unknown or
-   conflicting identities are not reassigned by descriptor or order similarity.
-3. Read [metrics and reporting](references/metrics-and-reporting.md). Compute
-   merchant rates with merchant-specific denominators and disclose sample counts.
-   Include week-by-week comparisons for every submerchant within the report period,
-   using Monday–Sunday weeks and explicit partial-week labels. Compare other periods
-   for individual merchants when explicitly requested and supported.
-   Read [risk history](references/risk-history.md) for 340FRD, dispute histories
-   and VAMP. Use the base skill's FX and dispute rules; leave unsupported figures
-   unresolved, not zero.
-4. Present merchant findings, comparison, selected merchant detail and merchant-specific
-   investigation actions. Explain missing data, conflicts, unmatched records, rate
-   denominators and attribution limits. Keep totals only as internal reconciliation
-   evidence; do not report portfolio summaries, trends, decomposition, funnels or
-   overall dispute chapters.
-   Follow the base skill's editorial review, Chinese polish and fact-preservation
-   checks when producing a complete report.
-
-## CLI and scope
-
-The bundled workflow uses Python 3 standard-library scripts and local Worldpay CSV
-exports. It makes no network calls. Authorization data is required; settlement and
-dispute files are used when supplied. Run all three commands:
+1. Read the installed `payment-analysis/SKILL.md` and its event-layer, metric, FX,
+   dispute and terminology references. Inventory authorized inputs, source dictionaries,
+   merchant/provider identifiers, coverage, timezone and currencies. Fix explicit main
+   dates using the user's period or the base period-selection question. The common cutoff
+   is the earliest supplied layer's last event date for the main table and risk history.
+   Authorization charts use the earlier of requested end and last authorization date,
+   independently of settlement coverage; disclose both cutoffs and partial periods.
+2. Before deduplication or joins, read [identity and reconciliation](references/identity-and-reconciliation.md).
+   Scope identity and joins to the verified merchant/provider namespace. Descriptor,
+   Gateway MID and MID are not interchangeable submerchant keys. Conflicting auth or
+   settlement identities stop generation; retain unresolved attribution explicitly.
+3. Read [metrics and reporting](references/metrics-and-reporting.md) and
+   [risk history](references/risk-history.md). Use the bundled calculator and builder
+   for merchant-specific denominators, two-period detail, current-week issuer top five,
+   eight-week amount/count trends and risk count/rate histories. Unknown amounts or
+   missing daily USD FX leave affected sums unavailable, not mixed-currency totals.
+4. Use `write-report` for the report stage with this skill's template. Read
+   `house-style/references/analytical-reporting.md`, `analytical-writing-patterns.md`
+   and `definitions-and-metrics.md`; load required `terminology`, `editorial-review`
+   and domain-required `polish-cn`. Pass the same references and merchant template to
+   any authorized writer/reviewer. Missing dependencies leave report review incomplete.
+   Review `presentation.json`, apply narrative edits there and rerender both outputs.
+5. Verify arithmetic, chart values, current-week issuer selection, null/zero semantics,
+   tabs, tooltips, drilldown and offline printing. Open the saved HTML in a local browser;
+   rendering instructions alone are not visual verification. Retain check evidence outside
+   the business report and state any unverified rendering or missing data.
+
+## Local CLI
+
+The calculator uses Python standard-library CSV exports. ECharts is pinned and bundled;
+report generation and viewing make no network calls.
 
 ```sh
-python3 {portfolio-payment-analysis baseDir}/scripts/analyze.py --input PATH --output OUTPUT --main-start YYYY-MM-DD --main-end YYYY-MM-DD
-python3 {portfolio-payment-analysis baseDir}/scripts/build_report.py --facts OUTPUT/facts.json --output OUTPUT
-# After editing or polishing presentation.json, rerender without rebuilding its narrative:
-python3 {portfolio-payment-analysis baseDir}/scripts/render.py --model OUTPUT/presentation.json --output OUTPUT
+python3 {skill-dir}/scripts/analyze.py --input PATH --output OUTPUT --main-start YYYY-MM-DD --main-end YYYY-MM-DD
+python3 {skill-dir}/scripts/build_report.py --facts OUTPUT/facts.json --output OUTPUT
+python3 {skill-dir}/scripts/render.py --model OUTPUT/presentation.json --output OUTPUT
 ```
 
-The calculator caps the requested end at the earliest last event date among supplied
-layers. It reports the effective cutoff and compares the corresponding prior-month
-dates. Source event ranges alone do not establish continuous coverage. Check period lengths
-and source coverage before interpreting a comparison.
-
-The report outputs are `overview.zh.html` and `overview.zh.md`, backed by the reviewed
-`presentation.json`. Supporting internal files are `facts.json`, `merchant-metrics.csv`,
-`merchant-mapping.csv`, `merchant-weekly.csv`, `merchant-segments.csv`,
-`merchant-detail-comparison.csv`, `merchant-risk-history.csv`, and
-`coverage-and-reconciliation.json`; legacy aggregate fields
-in these files are not report deliverables. The HTML is self-contained, supports
-merchant filtering and printing, and sends no data to external services. Use
-`--detail-merchant ID` on `build_report.py` (repeat it for several IDs) when the user
-names merchants. Otherwise expand the largest merchant by attempts and the lowest-rate
-merchant with at least 30 attempts, while keeping every other merchant available in
-collapsed detail sections. This is a navigation rule, not a significance test.
-Section 2 retains full weekly history. Section 3 uses charts to compare only this week
-with last week, matching weekdays when the current week is partial. Every merchant
-has BIN-country, card-product (payment method × card type), fixed USD amount-bucket,
-authentication and unsuccessful-response charts. Country and card-product charts use
-compact paired bars. Amount buckets use side-by-side histograms, unsuccessful responses
-use side-by-side bars, and authentication uses paired pies for counts and USD amounts,
-not rates. Each pair compares aligned weeks. Use the shared `comparison_charts.py` for
-all report charts. Section 3 omits settlement sales/refunds. Include merchant risk
-history charts as specified in the risk reference. Treat 340FRD file generation date
-as its report date, retaining the earliest date for exact repeats. Monthly dispute
-and fraud charts offer counts and network-style rate estimates with numerator and
-denominator details; weekly charts retain counts. Visa uses same-month sales,
-Mastercard ECP uses prior-month sales, and EFM uses fraud chargebacks divided by
-prior-month e-commerce sales, not all 340FRD Mastercard reports. Fix groups across the union of the
-two comparison periods, and display
-only those two ranges in chart legends and expandable metric-row tables. Follow the
-segment and denominator contract in the reporting reference.
-Include merchant-specific historical refund and dispute follow-ups in the action table
-when supported, without adding portfolio history chapters. If the user says a merchant is
-historical and out of this report, pass `--exclude-merchant ID` (repeat it for several IDs).
-That removes the merchant from comparison, weekly tables, detail, the action list, and every
-linked merchant CSV. State the exclusion once: it is not a closure finding and not missing data.
-Do not lead the report with an excluded merchant. A later rebuild without the flag puts the
-merchant back.
-
-The generated lowest-authorization-rate sentence only chooses an authorization review. It is
-not the investigation order. If fraud or predispute history would change who a reader checks
-first, put that merchant and month in the opening, and say whether the month is inside the
-report window. Do not title a real extract 样本报告; 样本 is only for a small attempt count.
-
-A packed week cell that includes dollars must say 授权成功 USD. The rule against repeating a
-metric label applies only when the column header already names that measure. When the sales
-column contains both 0.00 and blank, say which merchants have an observed zero and which have
-no settlement layer. An invalid or post-cutoff 340FRD file must state the effect on counts, not
-only the date. Unmatched fraud records must state the count and amount excluded from merchant
-figures.
-
-The report includes per-submerchant weekly counts, rates, successful authorization
-amount USD, settled sales, refunds and dispute observations. Each merchant's breakdown
-uses date/week columns and metric rows; successful authorization amount has its own
-row and never substitutes settled sales. Only adjacent full calendar weeks with available observations and valid
-denominators receive week-over-week changes; partial weeks retain their metrics but
-have no week-over-week change. Read the weekly contract in the reporting reference.
-
-The optional `--fx-rates` accepts caller-supplied daily USD rates. The CLI does not
-verify their provenance; obtain and preserve Forex Service evidence as specified by
-the base FX contract before relying on converted amounts. Without a required rate,
-the affected amount is unavailable while count metrics remain available. Render unavailable
-cells blank, not N/A; show only `USD 33...` in a USD value cell, without repeating its
-metric label. Remove extra explanatory prose while retaining necessary coverage limits.
-
-Source fields remain unchanged in JSON. CSV exports prefix spreadsheet-sensitive
-text with an apostrophe so opening a report does not execute merchant names or
-labels as formulas; numeric metrics remain numeric.
-
-Treat internal authorization counters together with `layer_observed.auth`: a zero
-observation count with that flag false is not confirmed zero business activity.
-The report and business CSV cells remain blank in that case. Distinguish observed
-dispute snapshots from deduplicated case-stage counts and verified opening counts;
-they answer different questions and need not match. Formatting-only aliases of a
-verified provider are duplicates, not new snapshots. Sales or refunds without
-stable event identity remain observations, not confirmed monetary totals.
-
-The report is an extract-based operational view. The v1 CLI refuses generation if
-any authorization or settlement identity has conflicting values; resolve those
-sources before rerunning. This conservative refusal can block clean periods too.
-It never substitutes totals from an unlabeled clean subset. An absent layer or a
-window without observed settlement/dispute rows produces unavailable metrics, not
-confirmed zero activity. Dispute rows remain observed
-snapshots until opening semantics are verified. The CLI computes supported
-network-style extract estimates, not official network assessments; unsupported rate
-cells stay blank. Merchant-scoped settlement and join evidence must not imply that all
-current-period sales descend from current-period approvals. Review the saved
-`presentation.json` as the narrative source, then rerender both formats. Preserve
-raw customer data in the input project; use synthetic fixtures for repository tests.
+Outputs: `overview.zh.html`, `overview.zh.md`, reviewed `presentation.json`, `facts.json`
+and merchant CSV/JSON reconciliation evidence. HTML embeds ECharts, all aggregate data
+and third-party notices; it works offline without React or a CDN. Calculations stay in
+facts, presentation owns narrative, rendering does not recompute payments.
+
+`--detail-merchant ID` selects the initial merchant tab; all merchants remain accessible.
+`--exclude-merchant ID` removes an explicitly excluded historical merchant from report and
+business exports; repeat either flag as needed. State an exclusion once, not as a closure
+finding. `--fx-rates` accepts daily USD rates only with preserved Forex Service provenance;
+the CLI cannot certify caller-supplied provenance.
+
+For selected Parquet snapshots, retain their source-selection accounting. Recover missing
+source fields only through verified file hashes and source row references, with row-count
+reconciliation. Do not rerun raw overlapping exports as a second payment population or
+infer merchant identity from descriptors. The CSV CLI does not directly read Parquet.
+
+## Presentation contract
+
+Use only `1. 子商户对比` and `3. 重点子商户详情`, with merchant findings above them.
+The first table includes daily authorization-attempt count sparklines and actual approved
+authorization USD amounts, not sales. Every merchant gets a tab; the tab starts with up
+to eight observed calendar weeks of amount bars and count lines. Country and card-product
+charts show approval rate plus approvals/attempts only. Country drilldown selects its
+Top 5 banks using positive **current-period** attempts, keeps prior-period values for
+those same banks and retains undefined rates as gaps. Other comparison dimensions keep
+the paired-chart layouts in the reporting reference.
+
+All five risk histories show count bars and rate lines simultaneously. VAMP is an explicitly
+labeled extract estimate from Visa TC40 plus already-opened formal disputes over same-month
+merchant Visa sales; pending/response/loss/reversal status does not remove a formal case.
+Official network assessment remains distinct. No portfolio funnel, totals chapter, weekly
+summary chapter, action chapter, coverage chapter, chart detail expansion or VAMP component
+table is rendered; supporting evidence remains available in files.

package/skills/risk-compliance/portfolio-payment-analysis/references/metrics-and-reporting.md

@@ -1,170 +1,37 @@
-# Metrics and report
-
-## Calculation and coverage
-
-Use the installed `payment-analysis` references for formulas, FX, disputes and
-terminology. For each merchant rate, show the merchant-specific numerator,
-denominator, population and dates. A zero denominator is undefined. A known zero
-requires coverage of the relevant period and population; missing layers, unverified
-identity, conflicts and missing historical coverage are not zeros. Show small samples
-with raw counts and a caveat. Do not rank unavailable rates.
-
-Keep authorization, settlement, refund and dispute measures separate. Approval is
-not settlement. Scope countries, decline reasons, authentication, settlement and
-disputes to the merchant and the relevant event population. Do not imply that all
-sales in a period descend from approvals in that period. Dispute snapshots are not
-necessarily new openings; apply the base dispute rules and disclose unverified stage,
-opening and coverage. Missing FX leaves affected USD amounts unresolved rather than
-creating mixed-currency totals. Apply the verified 340FRD and dispute history contract
-in [risk history](risk-history.md); do not use those observations as VAMP inputs.
-
-For an explicitly requested merchant-specific period comparison, state each date
-range, actual duration, cutoff and coverage. Prior-month endpoints may clamp to the
-month's last day, changing duration. Do not infer a merchant's onboarding or departure
-from observation in only one period. An extract-based comparison is not proof of
-complete coverage or causation. Portfolio totals may support internal reconciliation,
-including the unknown bucket, but are not report content.
-
-## Weekly submerchant comparison
-
-Include every Monday–Sunday calendar week intersecting the effective report period
-for every submerchant, including weeks with no observed events. Preserve the full
-calendar boundaries and the included date range. Mark edge weeks shorter than seven
-days as partial; never silently compare a partial week with a full week.
-
-Show per-merchant weekly attempts, approvals, approval rate, successful authorization
-amount USD, sales USD, refunds and observed dispute records. Successful authorization
-amount sums `Transaction amount` only where `Response type` is approval, using the
-authorization date and daily USD rates from the base FX contract. Never substitute
-settlement amount. Missing approved amounts, currencies or rates make the affected
-sum unavailable; no auth observations also yield an unavailable sum. Observed auths with no approvals have
-an observed approved amount of zero. Keep the merchant's numerator and denominator together.
-Use authorization time, settlement date and dispute date consistently with the base
-metrics. Missing layer observations or FX make affected measures unavailable, not
-zero growth or confirmed zero activity.
-
-Week-over-week changes use only the immediately preceding calendar week. Both weeks
-must be full seven-day bins. Compare only measures whose layer has observations in
-both weeks; relative changes additionally require a positive previous denominator.
-Attempt and sales changes are `(current / previous) - 1`; approval-rate changes are
-`100 * (current rate - previous rate)` percentage points. Do not average merchants,
-bridge a missing week, infer onboarding from a first observation, or report portfolio
-trends. A full calendar week does not prove continuous export coverage: all changes
-remain descriptive comparisons of the supplied observations.
-
-## Merchant detail breakdowns
-
-Section 3 provides the same breakdown suite for every merchant, comparing only this
-week with last week. This week is the Monday-based week containing the effective
-cutoff; compare the included weekdays with the same weekdays seven days earlier.
-For example, a Friday cutoff compares Monday–Friday with the preceding Monday–Friday,
-not a five-day period with a seven-day period. Restrict both populations to the
-requested main-period source scope and disclose unavailable earlier observations.
-Show the exact two date ranges in every chart legend and supporting table. Section 2
-continues to own the full weekly history; no main-period-total or older-week columns
-belong in section 3.
-
-Charts are the primary presentation, with these fixed layouts:
-
-- BIN country and card product: compact paired bar charts; two differently colored
-  bars per category compare the weeks for every metric, including rates.
-- Amount buckets: two histograms side by side, one color per week, using the same
-  six bins and y-axis scale. Default to count; counts and USD weights can be selected,
-  but not approval-rate/share metrics. The unequal/open-ended amount bands are shown
-  as equal-width categories, explicitly labeled as binned values rather than density.
-  Unknown amounts are listed separately, never drawn as a numeric interval.
-- Unsuccessful response reasons: two bar charts side by side, one color per week,
-  with identical category order and scale. Do not re-rank or rescale each week.
-- Authentication: paired pies for the aligned weeks, with count and USD selectors
-  only. If any category value is unavailable or negative, do not draw that period's
-  pie from an incomplete sum. Keep the supporting cells blank.
-
-Do not include settlement sales/refund charts in section 3. Sections 1 and 2 still
-retain their settlement metrics. A metric selector switches supported measures,
-including successful authorization amount USD where applicable. Render unavailable cells
-blank and chart values as gaps, not zeros. Do not repeat a metric label in a cell whose
-column header already names that measure: use `USD 33...`, not `授权成功金额 USD 33...`.
-A packed week cell that also shows attempts and a rate must say `授权成功 USD`, because the
-report also shows settled sales. Use the shared
-`comparison_charts.py` for all report charts. Expandable supporting tables keep metrics as rows and the two periods
-as columns. HTML is self-contained with no external chart service; Markdown retains
-the supporting values.
-Derive groupings only from the merchant's authorized attempts in those two periods;
-do not join settlement amounts into authorization groups.
-
-- BIN country: `Issuing bank country`; keep the merchant's top ten by attempts across
-  the two comparison periods, `Other` for the rest, and a separate unknown group.
-- Card product: `Payment method` × `Card type`, following payment-analysis. Preserve
-  every observed combination and unknown components.
-- Amount bucket: use each attempt's `Transaction amount` converted to USD by its
-  authorization date. Fixed half-open ranges are `[0,25)`, `[25,50)`, `[50,100)`,
-  `[100,200)`, `[200,500)`, `[500,+inf)`. Missing, nonfinite, negative or unconvertible
-  amounts belong to unknown; never silently put them into the zero bucket.
-- Authentication: every observed `Authentication method` value, with unknown separate.
-- Unsuccessful response: code × message among non-approvals only. Keep the merchant's
-  top ten reasons across the two comparison periods, Other and unknown. The share denominator is
-  that merchant's non-approvals, not all attempts. Unknown responses are not confirmed
-  issuer declines or fraud.
-
-Freeze group membership from the union of the two comparison periods before calculating each.
-Never re-rank each period independently. Synthetic Other/unknown have distinct keys and display
-labels from literal source strings with those names. For all-attempt groups show
-count, share of merchant attempts, approvals, rate, attempt amount USD and approved
-amount USD. For non-approval reasons show count, share of merchant non-approvals and
-unsuccessful amount USD. Group counts and amounts reconcile to the corresponding
-merchant population; a zero denominator is unavailable, not zero percent.
-
-Missing merchant-week observations remain blank. A group absent from an observed
-merchant-week may have zero observed counts, but no approval rate when its count is
-zero. Missing amount or FX invalidates the affected amount sum, not the count.
-Export the two-period group values in `merchant-detail-comparison.csv` for review.
-Add per-merchant dispute and fraud history and monthly VAMP charts using the periods,
-series and availability rules in [risk history](risk-history.md). Use 340FRD file
-generation dates as report dates. Monthly charts switch between counts and rates;
-rate tables and `merchant-risk-history.csv` expose numerator, denominator and its
-month. Keep weekly counts without inventing a weekly monitoring rate. Mastercard
-EFM rates use fraud chargebacks, not the 340FRD count series. These are not
-authorization-cohort metrics. Settlement sales/refunds are omitted from section 3.
-
-## Chinese report structure
-
-Use this template for editorial review in place of the base report's chapter order
-and Sankey. Do not add portfolio summary, trends, change decomposition, funnel or
-overall dispute chapters.
-
-- Scope header: title, period, effective cutoff, sources and timezone/coverage caveats;
-  include a comparison period only when a merchant comparison across periods is requested.
-- 商户要点: merchant-specific findings with counts, denominators and date basis. The lowest authorization rate chooses an authorization review, not the investigation order. If fraud or predispute history would change who is checked first, name that merchant and month here, and say whether the month is inside the report window. A user-excluded historical merchant appears once as an exclusion, not as a finding, and is absent from the tables.
-- 1. 子商户比较: stable IDs and display labels, merchant-level attempts, approvals,
-  rates, settlement, refunds and observed disputes where supported. Keep small samples
-  visible and unavailable values distinct from zero.
-- 2. 子商户逐周对比: a merchant-by-week matrix of approvals/attempts and rates,
-  followed by per-merchant tables with date/week columns horizontally and metrics
-  vertically, including successful authorization amount USD as a separate row from
-  settled sales. Preserve the same orientation for selected and collapsed merchants.
-  Keep all merchants reachable; default detail selections may be expanded while other
-  merchant weekly tables are collapsed. Explain partial weeks and unavailable changes.
-- 3. 重点子商户: the full merchant breakdown suite above, using interactive this-week
-  versus last-week charts and two-period supporting tables. No report-period total
-  or older weeks in the two-week comparisons. Risk history uses its own longer windows.
-  Priority merchants are expanded, and all other merchants remain accessible in
-  collapsed sections, including when merchants are explicitly selected. Default priority means the largest by attempts and
-  the lowest authorization rate among merchants with at least 30 attempts; this is
-  a navigation rule, not a significance test. Keep source limitations beside the
-  affected merchant and show group denominator definitions once. Remove extra explanatory
-  prose; keep only limitations needed to interpret the evidence.
-- 4. 商户行动表: identify the merchant, evidence and next investigation for each row;
-  distinguish hypotheses from facts. Include supported historical refund and dispute
-  follow-ups for the relevant merchant, not portfolio history.
-- 5. 归因与覆盖: sources, identity, deduplication, conflicts, unknowns, join coverage,
-  FX and unresolved attribution limits. Link supporting CSV/JSON reconciliation
-  evidence without presenting aggregate totals in the report or exposing cardholder data.
-
-## Done when
-
-A reader can identify which merchants to investigate and why, including a stated historical exclusion; each rate identifies
-its merchant, population and period; unsupported data is not presented as zero; and
-merchant attribution does not cross identity boundaries. Internal reconciliation
-accounts for unknowns and conflicts without advertising aggregate fields as deliverables.
-The Markdown and HTML use the same reviewed narrative and separate verified findings
-from operational hypotheses.
+# Merchant report layout and interaction
+
+Use this template in `write-report` and editorial review. Internal calculations may retain weekly tables, reconciliation and actions; the reader-facing report has only the two sections below. User instructions can override presentation without changing event identity or arithmetic.
+
+## 1. 子商户对比
+
+Show every verified merchant, including historical merchants with no current observations, unless explicitly excluded. Keep unverified/unknown identities in reconciliation evidence, not as merchant rows or tabs. Columns: merchant, stable merchant ID, authorization attempts, approvals, approval rate, daily attempt-count sparkline, approved authorization amount USD, refund count, refund amount USD and dispute observation count (display label `争议笔数`). The dispute column remains an observation metric, not an official opening count. Explain that distinction beside the report's scope when material.
+
+Amounts in the approved column use approved authorization attempts and authorization-date daily USD conversion. Never substitute settled sales. Missing authorization observations leave count/rate/amount cells blank; observed attempts with no approvals have zero approved amount and a zero approval rate. Zero attempts have an undefined rate.
+
+Sparklines show daily authorization attempt counts for the two detail periods, not approval rates. Use a common zero-based scale across merchants. Preserve absent days as gaps and never connect across them. Tooltip shows the date and count. No merchant-search control or sample-note column.
+
+## 3. 重点子商户详情
+
+One tab per merchant; all merchants are reachable. Detail selection controls the initial tab only, not which merchants are present. Keep tab focus and arrow/Home/End keyboard navigation, resize charts after a hidden tab becomes visible, and print all tabs.
+
+At each tab's top, show the latest eight Monday–Sunday calendar weeks ending at the authorization cutoff (the earlier of requested end and last observed authorization date). Draw only weeks containing that merchant's observed authorization attempts; fewer observed weeks produce fewer categories. Count is a line on the right axis; attempt amount USD is a bar on the left axis. Calculate with the same daily FX rules. Missing FX leaves amount unavailable while counts remain visible. A merchant with no observations has an explicit empty state.
+
+Below that, compare the week containing the authorization cutoff with the same weekdays one week earlier, even when the earlier period lies outside the main report start. Read those authorized historical source rows instead of creating false prior-period blanks. Preserve both period placeholders when observations are absent. Main comparison-table and risk-history dates use the common cutoff; authorization sparklines, details and eight-week trends use the independent authorization cutoff. A settlement cutoff must not truncate available weekend authorization records. State both cutoffs. Calculate groups across the union of both periods.
+
+- BIN country: top ten by two-period attempts, Other and unknown separate. Display only approval rate with `approvals/attempts` labels. Clicking a real country expands/collapses its top five issuing banks inline; rank banks by **current-period** attempts descending, ties by bank name. Include only banks with positive current attempts. Compare the same selected banks against the previous period. Unknown bank labels remain explicit; do not merge similarly spelled issuers without a verified dictionary. Other is an aggregate, not a country. Keep denominator and missing-data rules for bank rows; unknown current/previous observations are gaps, while attempts with zero approvals have a genuine 0%.
+- Card product: payment method × card type. Approval rate only, with approvals/attempts labels and no metric selector.
+- Amount buckets: `[0,25)`, `[25,50)`, `[50,100)`, `[100,200)`, `[200,500)`, `[500,+inf)` USD; two histograms with shared ranges/scales. Unknown or unconvertible amounts remain separate.
+- Authentication: paired pies for counts or amounts; an incomplete amount sum leaves that period's pie unavailable.
+- Non-approval reasons: code × message, top ten across both periods, Other and unknown separate; two side-by-side bar panels. Shares use that merchant's non-approvals.
+
+No weekly summary table, action-list chapter, coverage chapter, per-tab two-week summary table, daily-record expansion, chart-data expansion or VAMP component table appears in the business report. Keep calculation details and reconciliation in linked supporting artifacts. Necessary date, denominator and estimate limitations stay near the affected plot.
+
+## Risk charts
+
+Every merchant has five simultaneous dual-axis charts: monthly and weekly disputes, monthly and weekly fraud, and monthly VAMP extract estimate. Counts are bars on the left; rates are lines on the right. No count/rate toggle. Keep twelve month positions and eight week positions; gaps remain gaps. Refer to [risk-history.md](risk-history.md) for numerator/denominator semantics.
+
+ECharts is bundled locally and embedded with its license/NOTICE into a single HTML. No CDN or runtime data fetch. Hover/touch tooltips show period, full series label, count, ratio and numerator/denominator where available. Legends can toggle series. Preserve responsive horizontal scrolling for dense charts and resize only when containers change; do not reset chart options on every hover. Use SVG rendering for portable printing.
+
+## Verification
+
+Reconcile merchant/group counts and approved amounts to their source populations. Verify all chart series against `presentation.json`; inspect real rendered scales, dual-axis units, count/rate tooltips, undefined rates, missing FX, empty history, tab switching, current-week issuer ranking and expand/collapse. Exercise the saved HTML with network disabled and verify zero external requests. Only synthetic fixtures belong in the skill repository.

package/skills/risk-compliance/portfolio-payment-analysis/references/risk-history.md

@@ -4,7 +4,11 @@ Use the common effective cutoff. Retain 12 calendar months and eight Monday–Su
 weeks, with missing periods blank and the final period partial where applicable.
 Every merchant has dispute and fraud counts. Monthly charts also offer a rate view,
 with numerator, denominator and denominator month in the expandable table and CSV.
-Weekly charts show counts: do not invent a weekly card-network monitoring formula.
+Weekly charts include descriptive same-week rates: observed numerator divided by
+same-merchant, same-brand settled sales by transaction/capture date in that week.
+These are not weekly network monitoring rates. Missing numerator/denominator is a gap;
+zero denominators are undefined. Monthly programme-aligned rate definitions below
+remain separate from these descriptive weekly rates.
 All charts use `comparison_charts.py`; nulls are gaps, never fabricated zeros.
 
 ## 340FRD reporting date and attribution
@@ -35,10 +39,12 @@ incidence. RDR and formal escalation can each appear in their respective series.
 Conflicting identities/brands are quarantined; unknown stages remain unresolved.
 
 A monitoring-style chargeback numerator needs an opening and its received date.
-`First CB Request` with `1st chargeback` is the adapter's supported opening pair.
-Response-, loss- or reversal-only cases cannot be promoted to openings. Preserve
-observed counts while leaving affected rate cells blank. Keep independently supported
-merchant/brand/month cells computable.
+`First CB Request` establishes an explicit received opening date. Response-, loss- and
+reversal-stage records also establish that a formal dispute already opened: count that
+case once regardless of whether it is pending or resolved. When the original request is
+absent, extract estimates use the earliest supplied formal-stage observation date and
+state that this is not a verified network processing month. RDR-only cases are excluded.
+Conflicting merchant, provider or brand identities remain quarantined.
 
 ## Monthly count-rate formulas
 
@@ -70,16 +76,27 @@ each rate. Do not infer continuous coverage from min/max event dates.
 
 ## VAMP
 
-The file-generation-date reporting convention resolves the fraud report-date choice.
-Do not continue to list that choice as missing. It does not establish TC40 event
-identity, TC15/TC05 processing dates, corrections, CE3.0/pre-dispute exclusions,
-VisaNet CNP eligibility, completeness or descriptor/acquirer/market grouping.
-Keep official VAMP unavailable until the remaining inputs are verified.
-
-VAMP is eligible TC40 fraud plus TC15 disputes divided by TC05 settled transactions
-for the same reporting month. Do not deduplicate across TC40 and TC15. RDR does not
-automatically erase a related TC40. Do not manufacture VAMP by adding the observed
-count series or the descriptive pre-dispute rate.
+The Visa portion of DART-340 is TC40. Use its file-generation reporting month and
+existing exact-repeat handling; Mastercard DART records are not Visa TC40.
+
+Display **VAMP（导出估算）** as `(attributable Visa TC40 records + opened formal
+Visa disputes) / same-merchant same-month Visa settled Sale count`. Formal dispute
+status need not be resolved: count an opened case once, including response, loss or
+reversal records. Exclude RDR-only cases from the formal dispute numerator; RDR does
+not automatically erase related TC40. Do not deduplicate across TC40 and TC15.
+
+Use the earliest supplied formal-stage date when the original request is absent.
+The sales denominator uses the existing transaction/capture-month evidence. Expose
+these date choices beside the plot and in supporting evidence. These are extract
+estimates, not certification of TC15/TC05 processing months, corrections, CE3.0 or
+other exclusions, VisaNet CNP eligibility, complete scope, or descriptor/acquirer/
+market grouping. Official network VAMP remains unavailable until those are verified.
+
+Draw VAMP numerator counts as left-axis bars and the estimate as a right-axis line.
+Keep all twelve months. Missing either numerator component or a positive denominator
+leaves the ratio blank; never replace absent TC40 with zero. Genuine zero ratios may
+be retained in supporting records while omitted as plotted rate points. Every plotted
+ratio has an explicit numerator, denominator and denominator period.
 
 ## Sources