@1aboveio/skills 0.14.0 → 0.16.1

package/skills/payment/payment-analysis/references/auth-rate-actions.md

@@ -0,0 +1,30 @@
+# Actions that often lift auth rate
+
+Use this list when writing **运营影响**. Pick only items the extract
+supports. Do not dump the whole list. These are routing / retry operations,
+not a `fraud-analysis` rule package (no precision/recall, no “loss saved”).
+
+Auth rate = 授权成功 / 授权尝试. BIN country = 发卡行国家.
+
+| # | When the data shows | Action | Do not write |
+|---|---|---|---|
+| 1 | BIN countries under SCA (e.g. UK, Spain, Italy) and Authentication method is empty / None | Route **3DS** for those 发卡行国家 | 强客户认证 as the standing term (use SCA); claiming 3DS will raise conversion |
+| 2 | A country (or book) where 疑似欺诈 is a large share of 授权拒绝 | **风控拦截** and/or **3DS** on that 发卡行国家 | Calling 疑似欺诈 “confirmed fraud”; putting this in the 3DS 与风控 exec slot as a decline mix |
+| 3 | Material **软性拒绝** (issuer soft: 余额不足, Do not honor, 超限, …) | **Retry** the authorization (same or later attempt, per acquirer retry rules) | Treating 无效卡 / 账户关闭 as retry-eligible |
+| 4 | 余额不足, 安全码无效, 有效期无效, Do not honor 等可解释的拒绝 | On the **payment page**, show the matching reason (余额不足 / 安全码错误 / 有效期错误), not a generic “支付失败” | Inventing copy the issuer did not return; hiding the reason |
+
+## How to cite in the report
+
+One short 运营影响 bullet per action, with the evidence already in the
+report (country, share, 软性拒绝 count). Example shapes:
+
+- SCA：英国、西班牙、意大利受 SCA 约束，当前分析时段内无 3DS，建议对这些发卡行国家路由 3DS。
+- 疑似欺诈：某国疑似欺诈占授权拒绝 X%，建议风控拦截或 3DS。
+- 软性拒绝：软性拒绝 N 笔（余额不足 / Do not honor / …），可按收单行规则重试。
+- 支付页提示：余额不足、安全码无效、有效期无效应在支付页给出对应提示，便于用户换卡或改卡号、有效期、安全码。
+
+## Out of scope
+
+- Supervised thresholds, holdout, 3DS/block “packages” → `fraud-analysis`
+- Inventing retry counts or expected auth-rate lift
+- Mixing portfolio and merchant grains in one file

package/skills/payment/payment-analysis/references/chargebacks.md

@@ -0,0 +1,88 @@
+# Chargeback / dispute rate (Visa vs Mastercard)
+
+Topic **4.8 拒付 / 争议**. Put the Visa / Mastercard formulas as a **note
+under the monthly rate chart**. Count rates follow card-network monitoring
+programmes, **not** origination-month vintage and **not** a blended
+Visa+Mastercard ratio.
+
+Official Visa and Mastercard rulebooks are acquirer-gated. The formulas
+below are the processor restatements used in production monitoring
+(Stripe, Braintree). Caption the report as **network-style estimates
+from this extract**, not as a Visa/Mastercard identification notice.
+
+## When a point is drawn
+
+A monthly point for a card brand is drawn **only if**
+
+- numerator (chargebacks **received** that calendar month for that brand) > 0, and
+- denominator (sales count for that brand, month as defined below) > 0.
+
+Otherwise **omit the point**. Do not plot `0`. Do not invent a prior-month
+sale count. If a brand has no drawable points, omit the series. If no
+series remain, omit the rate chart (keep the reason-category bars if CBs
+exist).
+
+## Formulas (count)
+
+Numerator for both brands: chargebacks **received** in calendar month `M`
+(`Chargeback date`), `Payment method` = that brand. Not original
+transaction month. Inquiries / RDR-cleared cases are not in this extract;
+count every CB row.
+
+| Brand | Programme (current) | Rate |
+|---|---|---|
+| Visa | VAMP dispute/sales count (same month) | `CB_Visa(M) / Sales_Visa(M)` |
+| Mastercard | ECP / ECM chargeback rate (lagged sales) | `CB_MC(M) / Sales_MC(M−1)` |
+
+`Sales_*` = settlement type Sale, that brand, **transaction/capture month**.
+Do not mix refunds into the denominator.
+
+Mastercard **must** use the previous calendar month’s sales. If `M−1`
+sales are missing from the extract, skip Mastercard for month `M`.
+
+## Visa notes (do not over-claim VAMP)
+
+Since 2025-04 Visa folded VDMP/VFMP into **VAMP**. Full VAMP Count is
+`opened Visa chargebacks (TC15) + reported fraud (TC40 EFW)`, same-month
+sales in the denominator. This skill’s extract usually has chargebacks
+only → report **Visa 拒付率 = Visa CB count / Visa same-month sales**.
+Do not label it “VAMP ratio” unless TC40/EFW is in the file.
+
+VAMP also has volume and enumeration legs; those are out of scope here.
+
+## Mastercard notes
+
+ECP (ECM / HECM) uses **both** a count threshold and the lagged rate.
+This report draws the **rate** series only. Do not say the merchant is
+“in ECM” from the extract.
+
+EFM is a different (fraud-reason + 3DS mix) programme; do not substitute
+it for ECP.
+
+## Amount rate (optional footnote)
+
+`abs(dispute amount) / sale amount` with the **same month alignment as
+the count rate** for that brand. Secondary; the line chart is count %.
+
+## Window caveat
+
+A short extract (e.g. 22 days of August plus a handful of July sales)
+cannot produce a Mastercard lagged rate for August unless July Mastercard
+sales exist, and cannot produce Visa July if July CBs are absent. Follow
+the skip rules; do not pad.
+
+## Sources
+
+- Stripe, *Dispute and fraud card monitoring programs*: Visa uses
+  disputes/fraud vs **same-month** payments; Mastercard uses
+  disputes/fraud vs **previous-month** payments; both assign the CB to
+  the month it was **received**.
+  https://docs.stripe.com/disputes/monitoring-programs
+- Braintree, *Visa Acquirer Monitoring Program (VAMP)*: VAMP ratio =
+  VAMP Count / **same-month** Visa sales count
+  (example: August count / August sales).
+  https://developer.paypal.com/braintree/articles/risk-and-security/card-brand-monitoring-programs/visa-programs/visa-dispute-monitoring-program
+- Chargebacks911 primer on Mastercard ECM rate: chargebacks in the
+  **current** month / Mastercard transactions in the **previous** month
+  (April 10,000 sales and May 90 CBs → May rate 1%).
+  https://chargebacks911.com/mastercard-chargebacks/mastercard-excessive-fraud-chargeback-monitoring-programs/mastercard-ecm-program-how-to-calculate-your-mastercard-chargeback-rate/

package/skills/payment/payment-analysis/references/event-layers.md

@@ -0,0 +1,79 @@
+# Event layers, grains, and joins
+
+## Layers
+
+| Layer | Example filename pattern | Default grain | Usual time field |
+|---|---|---|---|
+| Authorizations | `Authorizations_*authorizations.csv` | one auth attempt | `Timestamp` |
+| Settlements | `Sales-and-refunds_*settlements.csv` | one sale or refund | `Timestamp` or `Settlement date` |
+| Chargebacks | `Chargebacks_*chargebacks.csv` | one dispute | `Chargeback date`; origination via `Original transaction timestamp` |
+
+A run may use one, two, or all three layers. Name every layer used and every layer
+missing.
+
+## Portfolio constants to record
+
+When columns exist and are near-constant, state them once (do not treat as
+drivers):
+
+- MID / Gateway MID
+- MCC
+- Provider / acquirer path
+- Transaction source / entry method
+- Billing descriptor / sub merchant
+
+## Keys and joins
+
+| Join | Left | Right | Notes |
+|---|---|---|---|
+| Auth ↔ Chargeback | `Order ID` | `Original transaction order ID` | Primary for this Pazien-style extract |
+| Auth ↔ Settlement | `Order ID` | `Order ID` | May be 1:n if capture/refund splits |
+| Weak identity | masked `Account`, `IIN` | same | Collisions possible; fine for contribution tables, not unique-customer claims |
+
+Report match rates whenever a join supports a claim (“N of M chargebacks match an
+auth in file”).
+
+## Currency
+
+Reporting amounts are USD. Conversion rules: [fx.md](fx.md).
+
+1. Prefer native USD rows; convert every non-USD amount before summing.
+2. Never add USD + EUR (etc.) into one total without FX and a disclosure.
+3. Count KPIs never need FX.
+
+## Window selection
+
+| User ask | Default |
+|---|---|
+| Full extract | min→max of chosen time field |
+| Most recent week / last 7 days | `(max_ts - 7d, max_ts]` |
+| Calendar week | dates in that Mon–Sun (or local week rule; state it) |
+| Compare recent vs prior | split at the same cut; show both |
+
+Chargeback **programme 拒付率** uses received month (`Chargeback date`) per
+[chargebacks.md](chargebacks.md). If you also show origination-month incidence,
+label that separately so it is not mistaken for the Visa/Mastercard rate.
+
+## Decline taxonomy (auth)
+
+Map with both code and message when present (example Pazien-style):
+
+| Code | Message (typical) | Class |
+|---|---|---|
+| A001 | Approval - generic | approval |
+| D102 | Suspected fraud | hard / fraud-coded |
+| D104 | Insufficient funds | soft / funds |
+| D387 | Policy reasons | hard / policy |
+| D202 | Security code invalid | hard / data |
+| D204 | Invalid Expiration date | hard / data |
+| D210 | Do not honor | soft / issuer |
+| R014 | Invalid transaction | reject |
+
+Always recompute from the file; do not assume codes are portable across gateways.
+
+## What not to infer
+
+- BIN country ≠ shipping or billing country
+- Approval ≠ settled funds
+- Suspected-fraud decline ≠ confirmed fraud loss
+- Chargeback reason Fraud ≠ first-party vs third-party adjudication

package/skills/payment/payment-analysis/references/fx.md

@@ -0,0 +1,59 @@
+# Amount currency → USD (Forex Service)
+
+Reporting amounts are **USD**. Count KPIs never need FX.
+
+Use the Forex Service (`~/projects/forex`), not a provider SDK, not a
+spreadsheet rate, not realtime quotes for historical windows.
+
+## Which amount
+
+| Layer | Amount | Currency |
+|---|---|---|
+| Authorization | `Transaction amount` | `Transaction amount currency` |
+| Settlement | `Settlement amount` (fallback `Transaction amount`) | `Settlement amount currency` |
+| Chargeback | `Dispute amount` | `Dispute amount currency` |
+
+Ignore empty `Pre-DCC amount` (often `0` with blank currency). Do not treat BIN
+country as the transaction currency.
+
+## Rules
+
+1. If every used currency field is `USD`, keep native amounts. Write
+   `金额均为 USD`. Do **not** call Forex Service and do **not** write
+   `未做汇率折算`.
+2. If any row is not USD, convert **that row** to USD before any amount sum,
+   share, ticket size, or dual-axis amount chart.
+3. Historical / windowed reports use **daily** conversion, not realtime:
+
+   `POST {FOREX_BASE_URL}/api/v1/conversions/daily`
+
+   Body:
+
+   ```json
+   {
+     "quoteCurrency": "USD",
+     "date": "<UTC Rate Date = transaction date in the extract>",
+     "items": [{ "currency": "EUR", "amount": "100.00" }]
+   }
+   ```
+
+   Prefer one request per Rate Date: either `conversions/daily` for the day's
+   distinct currencies, or `POST /api/v1/rates/daily` then multiply locally
+   (`converted = native × rate`, decimal strings).
+4. Fail closed if a non-USD row has no daily rate. Do not drop it silently and
+   do not mix native EUR with USD in one total.
+5. Auth: `forex:read` bearer token, audience `forex-service`. Base URL default
+   `https://forex.1above.io`. Contract: `GET /integration/agent.json`.
+6. Footnote converted reports: Rate Date rule, quote USD, Forex Service daily
+   conversion (not realtime). Mark `realtimeFallback` if a current UTC day was
+   served as provisional.
+
+## Env
+
+| Variable | Role |
+|---|---|
+| `FOREX_BASE_URL` | Default `https://forex.1above.io` |
+| `FOREX_TOKEN` | Bearer with scope `forex:read` |
+
+Mint the token from Identity (`client_credentials`, audience `forex-service`,
+scope `forex:read`) as in the Forex Service integration guide.

package/skills/payment/payment-analysis/references/journey.md

@@ -0,0 +1,78 @@
+# Payment journey (Sankey)
+
+The journey is a **count** Sankey across checkpoints. Prefer ECharts (or
+equivalent). Do not mix count and amount on one Sankey.
+
+## Checkpoint order
+
+```text
+start → risk decision → 3DS → authorization → settlement
+```
+
+## Canonical state transitions
+
+Use these edge names when the underlying fields exist:
+
+| From | To |
+|---|---|
+| risk decision | accept |
+| risk review | 3DS init |
+| accept | non-3DS authorization |
+| non-3DS authorization | non-3DS authorization approved |
+| non-3DS authorization | non-3DS authorization declined |
+| 3DS init | 3DS challenge |
+| 3DS init | 3DS frictionless |
+| 3DS init | 3DS reject |
+| 3DS challenge | 3DS authenticated |
+| 3DS challenge | 3DS authentication failed |
+| 3DS authenticated | 3DS authorization |
+| 3DS authorization | 3DS authorization approved |
+| 3DS authorization | 3DS authorization declined |
+
+Settlement edges (when settlement layer present), from approved authorization
+nodes only:
+
+| From | To |
+|---|---|
+| non-3DS / 3DS authorization approved | settled sale |
+| non-3DS / 3DS authorization approved | approved not settled |
+| settled sale | refund (only if Order ID joins cleanly) |
+| settled sale | chargeback fraud / non-fraud (optional) |
+
+## Skip unavailable checkpoints
+
+If a checkpoint has no usable field in the extract, **omit its nodes and edges**.
+Do not invent risk decisions or 3DS outcomes.
+
+Examples:
+
+- `Authentication method` / 3DS result all null → skip risk decision, risk
+  review, and every 3DS node. Collapse to:
+
+  ```text
+  start → authorization → authorization approved / declined → settlement…
+  ```
+
+- Settlement file absent → stop after authorization approved/declined.
+- Refunds with Order IDs that do not join auth approvals → footnote only; do not
+  force a refund edge.
+
+Caption must list skipped checkpoints.
+
+## Mapping hints (when fields exist)
+
+| Journey node | Typical source |
+|---|---|
+| risk decision / risk review | gateway risk action, review queue, step-up flag |
+| accept | risk allow / no step-up |
+| 3DS init / challenge / frictionless / reject | 3DS status / ECI / transStatus |
+| 3DS authenticated / failed | challenge result |
+| non-3DS / 3DS authorization approved | auth response = approval |
+| non-3DS / 3DS authorization declined | auth response ≠ approval |
+| settled sale | settlement type = Sale joined on Order ID |
+
+## Anti-patterns
+
+- Drawing 3DS branches when authentication fields are empty
+- Using amount on the journey Sankey
+- Putting decline-reason fan-out on the journey (keep that in Topics charts)

package/skills/payment/payment-analysis/references/metrics.md

@@ -0,0 +1,62 @@
+# Metrics and denominators
+
+Compute with explicit denominators. Prefer count and amount side by side.
+Amounts are USD per [fx.md](fx.md) before any sum or share.
+
+## Authorization
+
+| KPI | Formula | Notes |
+|---|---|---|
+| Attempts | count of auth rows in window | |
+| Approvals | count where response = approval | |
+| Auth rate | approvals / attempts | Not capture rate |
+| Approved amount | sum(amount \| approval) | USD after [fx.md](fx.md) |
+| Declines | attempts − approvals | Or hard-only if stated |
+| Decline rate | declines / attempts | |
+| Reason share (of declines) | reason_count / declines | Default for mix tables |
+| Reason incidence (of attempts) | reason_count / attempts | Label clearly if used |
+| Country attempt share | country_attempts / attempts | |
+| Country amount share | country_amount / total_amount | Often diverges from attempt share |
+| Country auth rate | country_approvals / country_attempts | Require min-n (e.g. ≥30) for rankings |
+
+Trend grains: daily (`Timestamp` date) and weekly (state week rule, e.g. W-SUN).
+
+Card product: `Payment method` × `Card type` when both exist.
+
+## Settlement
+
+| KPI | Formula | Notes |
+|---|---|---|
+| Sale count / amount | Settlement type = Sale | |
+| Refund count / amount | Settlement type = Refund | Show sign or absolute + label |
+| Net settled amount | sales + refunds (refunds negative) | |
+| Refund rate (count) | refunds / sales | |
+| Refund rate (amount) | abs(refund amount) / sale amount | |
+| Status mix | by Settlement status | |
+
+Do not equalize settled sales to approved auth amount without a timing caveat.
+
+## Chargebacks
+
+Monthly **拒付率** by brand is [chargebacks.md](chargebacks.md): Visa
+same-month sales, Mastercard previous-month sales, skip empty brand-months,
+no blended Visa+Mastercard ratio. The table below is mix / match, not that
+programme rate.
+
+| KPI | Formula | Notes |
+|---|---|---|
+| CB count / dispute amount | as filed | Amounts USD after [fx.md](fx.md); use abs for magnitude if signed |
+| Reason mix | by Reason category / code | Fraud ≠ all CBs |
+| Match rate to auths | matched / CB rows | State join key |
+| Visa monthly 拒付率 | CB_Visa(M) / Sales_Visa(M) | Received month; not VAMP unless TC40 in file |
+| Mastercard monthly 拒付率 | CB_MC(M) / Sales_MC(M−1) | Skip M if M−1 sales missing |
+
+Lag: chargeback date is later than original auth. Programme rates use
+**received** month, not origination vintage.
+
+## Ranking and “Other”
+
+- Rank countries by attempts unless the user asks for amount.
+- Roll the long tail into `Other` after top 10–15; show Other share.
+- For decline-by-country matrices, use top countries by attempts and top reasons
+  globally; collapse remaining reasons to `Other declines`.

package/skills/payment/payment-analysis/references/report-template.md

@@ -0,0 +1,98 @@
+# Report template
+
+Save:
+
+```text
+reports/payment-analysis/<scope>_overview.md
+reports/payment-analysis/<scope>_overview.zh.md
+reports/payment-analysis/<scope>_overview.zh.html   # preferred when charts
+```
+
+Follow [visualization.md](visualization.md), [journey.md](journey.md),
+[terminology.md](terminology.md), and [fx.md](fx.md) for amount currency. Omit
+topic sections whose layer is missing.
+No Markdown bold in report body. After writing, grep banned strings in
+terminology.md.
+
+## Required structure
+
+English Markdown headings on the left; Chinese HTML / `.zh.md` on the right.
+
+```markdown
+# Payment Overview — <window>          # 支付业务概览 — <window>
+
+## 1. Executive summary                 # 1. 执行摘要
+## 2. Top statistics                    # 2. 核心指标
+## 3. Payment journey (Sankey)          # 3. 支付旅程（Sankey）
+## 4. Topics                            # 4. 专题
+### 4.1 Overall transaction volume      # 4.1 整体交易量
+### 4.2 Week-on-week trend              # 4.2 周趋势
+### 4.3 Authorization rate              # 4.3 授权成功率
+### 4.4 Contribution by BIN country     # 4.4 BIN 国家贡献
+### 4.5 Decline by reason code          # 4.5 授权拒绝原因贡献
+### 4.6 Decline by BIN country          # 4.6 各国授权拒绝结构
+### 4.7 Settlements (when present)      # 4.7 清算
+### 4.8 Chargebacks (optional)          # 4.8 拒付
+## 5. Operational impact                # 5. 运营影响
+## 6. Appendix                          # 6. 附录
+```
+
+HTML uses the Chinese headings. KPI labels, legends, and Sankey node names use
+the glossary in terminology.md (`授权尝试`, `授权成功`, `授权拒绝`,
+`发卡行国家`, `差错`, `产品服务质量`, `Do not honor`).
+
+## Chapter requirements
+
+### 1. Executive summary / 执行摘要
+
+≤5 numbered findings: volume, trend, auth rate, country concentration, main
+decline or settlement/CB driver.
+
+### 2. Top statistics / 核心指标
+
+KPI cards / table from auth + settlement: attempts, approvals, auth rate,
+attempt amount, approved amount, sale count/amount, refund count/amount, net
+settled, distinct PAN/BIN/countries, portfolio constants (MID, MCC, provider).
+
+Chinese labels: 授权尝试, 授权成功, 授权成功率, 授权成功金额, 清算销售, 退款,
+净清算, 发卡行国家.
+
+### 3. Payment journey (Sankey) / 支付旅程
+
+Count Sankey per [journey.md](journey.md). Caption lists skipped checkpoints
+(e.g. risk decision / 3DS when authentication fields are empty).
+
+Collapsed nodes when 3DS/risk are absent:
+
+`开始 → 授权 → 授权成功 / 授权拒绝 → 已清算销售 / 授权成功未清算`
+
+### 4. Topics / 专题
+
+Each topic: short lede + chart(s) + supporting table.
+
+| Topic | Minimum viz |
+|---|---|
+| 4.1 Volume | count + amount bars (dual axis) |
+| 4.2 WoW trend | weekly count + amount bars; auth-rate line |
+| 4.3 Auth rate | rate line by day and/or segment |
+| 4.4 BIN country | count + amount bars dual axis; rate line |
+| 4.5 Decline reason | count bars |
+| 4.6 Decline by country | stacked count bars |
+| 4.7 Settlements | sale/refund amount bars; country contribution dual axis |
+| 4.8 Chargebacks | reason-category bars; Visa / Mastercard monthly 拒付率 line per [chargebacks.md](chargebacks.md) (note under the rate chart; skip empty brand-months) |
+
+Use both authorization and settlement data when both files are present.
+
+### 5. Operational impact / 运营影响
+
+Numbered operational takeaways. Do not title this 运营含义. Do not invent
+supervised fraud rules. Choose from
+[auth-rate-actions.md](auth-rate-actions.md) only when the extract supports
+the trigger (SCA → 3DS; high 疑似欺诈 country → 风控拦截 or 3DS; 软性拒绝 →
+retry).
+
+### 6. Appendix / 附录
+
+Definitions (from terminology.md) and caveats (FX per [fx.md](fx.md),
+issuer country ≠ ship-to, auth rate ≠ capture, journey skips,
+chargeback rates are network-style estimates).

package/skills/payment/payment-analysis/references/terminology.md

@@ -0,0 +1,85 @@
+# Terminology
+
+Use these terms consistently in payment-analysis reports. Read this file before
+writing English or Chinese copy. After writing, run the proofread step in
+`SKILL.md`.
+
+## Canonical glossary
+
+| English | Chinese | Do not write |
+|---|---|---|
+| Attempt | 授权尝试 | 单独的「尝试」；交易；conversion |
+| Approval | 授权成功 | 批准；成功（易与清算混淆） |
+| Auth rate | 授权成功率 | 转化率；单独的「成功率」（首次出现时） |
+| Decline | 授权拒绝 | 全部叫欺诈 |
+| Hard / soft / reject | 硬性拒绝 / 软性拒绝 / 风控拦截 | hard 拦截（指拒绝类型时） |
+| Reason / reason code | 拒绝原因 / 原因码 | |
+| Insufficient funds | 余额不足 | 余额 |
+| Suspected fraud | 疑似欺诈 | 已确认欺诈；正文里写 D102（表内 Pazien 代码可保留） |
+| Invalid expiration date | 有效期无效 | |
+| Security code invalid | 安全码无效 | |
+| Policy reasons | 政策原因 | |
+| Do not honor | Do not honor | 拒绝承兑 |
+| BIN / IIN | BIN / IIN | |
+| BIN country | 发卡行国家 / BIN 国家 | 客户国家；收货国；发卡国 |
+| Settlement | 清算 | |
+| Sale / Refund | 销售 / 退款 | 把销售金额写成清算金额 |
+| Chargeback / dispute | 拒付 / 争议 | 与清算混用 |
+| Clerical | 差错 | 文书；文书错误 |
+| Quality | 产品服务质量 | 质量；质量争议 |
+| Incidence | 发生率（必须写出分母） | |
+| GMV (loose) | 销售金额合计（说明是否含退款） | |
+| Week-on-week trend | 周趋势 | 周环比（除非单元格是环比百分比） |
+| Operational impact | 运营影响 | 运营含义 |
+| Ticket size | 客单价 | |
+| Debit / credit | 借记卡 / 贷记卡 | 借记；贷记 |
+| Payment journey | 支付旅程 | 支付旅程 Sankey；Sankey 旅程（标题/结构行） |
+| This analysis window | 当前分析时段内 | 本窗口 |
+| SCA | SCA | 强客户认证（可在首次括注后只用 SCA） |
+| Authentication / 3DS | 鉴权 / 认证 / 3DS | 把 3DS 叫转化 |
+| Visa / Mastercard 拒付率 | Visa / Mastercard 拒付率 | VAMP ratio（无 TC40 时）；ECM（从本抽取断言商户在项目中） |
+| Amounts in USD | 金额均为 USD | 未做汇率折算（当全部已是 USD） |
+| Count-heavy / amount-light | 授权尝试笔数多但金额小 | 走廊；笔数负担型走廊 |
+
+Keep proper nouns in source form when useful: Visa, MasterCard, BIN, 3DS,
+Sankey (in chart captions only), Order ID, MCC, Worldpay, Pazien, MID.
+Do not use Pazien codes (e.g. D102) in prose; use 疑似欺诈 / suspected fraud.
+Tables may still show the code column.
+
+## Axis and UI exceptions
+
+- Rate axis may say `成功率 %` if the legend or lede already says 授权成功率.
+  Amount axes still use the full metric plus currency
+  ([visualization.md](visualization.md)).
+- Week-over-week *percentage* columns may say 笔数周环比 / 金额周环比.
+- Product rankings that exclude tiny samples: write
+  `在授权尝试超过 50 笔的卡种里` (or the n actually used), never
+  `有规模的最弱卡种` or `弱卡种`.
+- If every amount is USD, write `金额均为 USD`. Do not add `未做汇率折算`.
+  Only mention missing FX conversion when mixed currencies were actually summed
+  or dropped.
+- Chart amount fields append the currency: `授权拒绝金额 USD`.
+- HTML footer: data-source filenames only. No skill name, no Chart.js / ECharts.
+- Do not call issuer country “customer country”.
+- Do not call auth rate “conversion” unless contrasting checkout vs issuer
+  response, and then say so.
+
+## Banned strings (grep after writing)
+
+Chinese: `走廊`, `杠杆`, `弱转化`, `转化率`, `赋能`, `抓手`, `闭环`, `打法`,
+`运营含义`, `本窗口`, `弱卡种`, `有规模的最弱`, `强客户认证`, `拒绝承兑`,
+`文书错误`, `质量争议`, `发卡国`
+
+English: `auth drag`, `conversion problem`, `count-heavy`, `amount-light`,
+`Protect US amount`, `Unlike currencies`
+
+If a hit is a legitimate exception (e.g. 周环比 as a table header for WoW %,
+or D102 in a reason-code table), leave it and do not expand the ban.
+
+## Proofread
+
+1. Apply the glossary to headings, KPI labels, chart legends, Sankey skip
+   chips, and body copy.
+2. Grep the report files for the banned strings.
+3. Replace hits using this table. Do not change numbers, formulas, or file
+   paths.

package/skills/payment/payment-analysis/references/visualization.md

@@ -0,0 +1,47 @@
+# Visualization rules
+
+Preferred deliverable: self-contained HTML with Chart.js (KPI charts) and
+ECharts (Sankey). Markdown tables remain required beside charts.
+
+## Mark encoding
+
+| Metric kind | Chart mark | Notes |
+|---|---|---|
+| Count | Bar | Vertical or horizontal |
+| Amount | Bar | Never encode amount as a line |
+| Rate | Line | Percent on its own axis |
+
+## Multi-metric charts
+
+1. Count and amount in the same chart → both are **bars** on **different axes**
+   (left = count, right = amount).
+2. Rate with count and/or amount → rate is a **line** on a dedicated % axis.
+3. Rate alone → line chart (points allowed). No bars for a lone rate series.
+4. Composition of one total → doughnut or stacked bars; not for time trends.
+
+## Axis hygiene
+
+- Label every axis with the full metric name. Amount axes/legends include
+  currency (`授权尝试金额 USD`, `授权拒绝金额 USD`, `清算销售金额 USD`,
+  `拒付金额 USD`). Do not use bare `笔数` / `金额` / `%`.
+- Only one axis draws the main grid on dual-axis charts.
+- Stacked bars = mix within a group (e.g. decline reasons by country), never rate.
+- Sort categories by a stated order (usually attempts desc).
+
+## Required charts (HTML)
+
+1. Payment journey Sankey — see [journey.md](journey.md)
+2. Volume trend (WoW / daily): count bar + amount bar (dual axis) + auth-rate line
+3. Authorization rate by segment (card product and/or country): rate as line
+4. BIN-country contribution: count bar + amount bar (dual axis)
+5. Decline by reason: count bars (+ amount bars/dual axis if shown)
+6. Decline mix by BIN country: stacked count bars
+
+## Anti-patterns
+
+- Line for amount or count
+- Bar for a standalone rate series
+- Count and amount on one axis without dual-axis scaling
+- Mixing native EUR (etc.) with USD in one amount series; convert first ([fx.md](fx.md))
+- Plotting a 0% chargeback-rate point for a brand-month with no CBs ([chargebacks.md](chargebacks.md))
+- Inventing Sankey checkpoints not present in the data