@1aboveio/skills 1.0.10 → 1.0.12

package/skills/risk-compliance/portfolio-payment-analysis/scripts/build_report.py

@@ -0,0 +1,386 @@
+#!/usr/bin/env python3
+"""Build a submerchant-only Chinese report from analyze.py facts.
+
+Usage: python3 build_report.py --facts OUTPUT/facts.json --output OUTPUT
+Portfolio fields remain calculation/reconciliation evidence; this report never renders them.
+Edit presentation.json for narrative review, then rerender with render.py.
+"""
+import argparse
+from csv_export import safe_writer
+import json
+from datetime import date
+from decimal import Decimal
+from pathlib import Path
+from render import render
+
+
+def number(value):
+    return '' if value is None else f'{value:,.0f}'
+
+
+def money(value):
+    return '' if value is None else f'{Decimal(str(value)):,.2f}'
+
+
+def percent(value):
+    return '' if value is None else f'{value*100:.2f}%'
+
+
+def name(merchant):
+    if not merchant.get('id'):
+        return '未归属'
+    return merchant.get('name', merchant['id']).removeprefix('HLP*')
+
+
+def amount(merchant, kind, magnitude=False):
+    value=(merchant.get(kind) or {}).get('usd')
+    return money(abs(Decimal(value)) if value is not None and magnitude else value)
+
+
+def para(text, kind='paragraph'):
+    return {'type':kind,'text':text}
+
+
+def table(headers, rows, **extra):
+    return {'type':'table','headers':headers,'rows':rows,**extra}
+
+
+def top_reasons(merchant):
+    return sorted(merchant.get('decline_reasons',[]),key=lambda r:(-r['count'],r['code'],r['message']))[:5]
+
+
+def weekly_blocks(facts, merchants, selected):
+    series={entry.get('id'):entry for entry in facts.get('merchant_weeks',[])}
+    blocks=[]
+    if not series:
+        return blocks+[para('尚未生成子商户周数据，请先运行最新计算脚本。','callout')]
+    grid=next(iter(series.values()))['weeks']
+    def label(week):
+        return week['start']+' 至 '+week['end']+('（不完整周）' if week['partial_week'] else '（完整周）')
+    rows=[]
+    for merchant in merchants:
+        weeks=series.get(merchant.get('id'),{}).get('weeks',[])
+        cells=[]
+        for week in weeks:
+            metrics=week['metrics']
+            if not metrics.get('layer_observed',{}).get('auth',False):
+                cells.append('')
+            else:
+                successful_usd=amount(metrics,'approved_amount')
+                cells.append(number(metrics['approvals'])+' / '+number(metrics['attempts'])+' · '+percent(metrics['auth_rate'])+(' · 授权成功 USD '+successful_usd if successful_usd else ''))
+        rows.append([name(merchant),merchant.get('id') or '未归属',*cells])
+    blocks.append(para('周汇总格里的美元是授权成功金额，不是销售金额。结算层未观察到时，销售金额留空，授权成功金额仍可出现。','note'))
+    blocks.append(table(['子商户','商户 ID',*[label(w) for w in grid]],rows,wrap_headers=True))
+    chosen={m.get('id') for m in selected}
+    for merchant in merchants:
+        weeks=series.get(merchant.get('id'),{}).get('weeks',[])
+        metric_labels=['授权尝试','授权成功笔数','授权成功率','授权成功金额 USD','较上周（百分点）','尝试笔数周环比','销售金额 USD','销售金额周环比','退款笔数','退款金额 USD','争议快照记录']
+        weekly_columns=[]
+        for week in weeks:
+            metric=week['metrics'];comparison=week['comparison'];observed=metric.get('layer_observed',{}).get('auth',False)
+            pp=comparison.get('auth_rate_pp')
+            weekly_columns.append([number(metric['attempts']) if observed else '',number(metric['approvals']) if observed else '',percent(metric['auth_rate']),amount(metric,'approved_amount'),('' if pp is None else f'{pp:+.2f}'),percent(comparison.get('attempts_pct')),amount(metric,'sales'),percent(comparison.get('sales_usd_pct')),number(metric['refund_count']) if metric['layer_observed']['settlement'] else '',amount(metric,'refunds',True),number(metric['dispute_snapshots']) if metric['layer_observed']['dispute'] else ''])
+        weekly_rows=[[metric_label,*[column[i] for column in weekly_columns]] for i,metric_label in enumerate(metric_labels)]
+        blocks.append(table(['指标',*[label(w) for w in weeks]],weekly_rows,wrap_headers=True,collapsed=merchant.get('id') not in chosen,caption=name(merchant)+' · '+str(merchant.get('id') or '未归属')+' · 每周明细'))
+        if merchant.get('id') in chosen:
+            # Visible tables need a merchant heading; collapsed ones have a summary caption.
+            blocks.insert(len(blocks)-1,para(name(merchant)+' · '+str(merchant.get('id') or '未归属')+' · 每周明细','heading'))
+    return blocks
+
+
+def write_weekly_csv(facts, output):
+    with (output/'merchant-weekly.csv').open('w',encoding='utf-8',newline='') as handle:
+        writer=safe_writer(handle,numeric_columns={11,13,15})
+        writer.writerow(['merchant_id','merchant_name','week_start','week_end','observed_start','observed_end','days','partial_week','attempts','approvals','auth_rate','approved_amount_usd','sale_count','sales_usd','refund_count','refunds_usd','dispute_snapshots','auth_rate_change_pp','attempts_change_fraction','sales_change_fraction','comparison_reason'])
+        for merchant in facts.get('merchant_weeks',[]):
+            for week in merchant['weeks']:
+                metrics=week['metrics'];comparison=week['comparison']
+                writer.writerow([merchant.get('id'),merchant.get('name'),week['week_start'],week['week_end'],week['start'],week['end'],week['days'],week['partial_week'],metrics['attempts'] if metrics.get('layer_observed',{}).get('auth',False) else None,metrics['approvals'] if metrics.get('layer_observed',{}).get('auth',False) else None,metrics['auth_rate'],(metrics.get('approved_amount') or {}).get('usd'),metrics['sale_count'] if metrics['layer_observed']['settlement'] else None,(metrics.get('sales') or {}).get('usd'),metrics['refund_count'] if metrics['layer_observed']['settlement'] else None,(metrics.get('refunds') or {}).get('usd'),metrics['dispute_snapshots'] if metrics['layer_observed']['dispute'] else None,comparison.get('auth_rate_pp'),comparison.get('attempts_pct'),comparison.get('sales_usd_pct'),comparison.get('reason')])
+
+
+def segment_charts(merchant, periods):
+    blocks=[]
+    series=[{'key':p['key'],'label':p['label']+' '+p['start']+' 至 '+p['end']} for p in periods]
+    for dimension in merchant.get('dimensions',[]):
+        decline=dimension['population']=='non_approvals'
+        histogram=dimension['key']=='amount_bucket'
+        layout={'bin_country':'paired_bars','card_product':'paired_bars','amount_bucket':'histogram_pair','decline_reason':'bars_pair','authentication':'pie_pair'}.get(dimension['key'])
+        metrics=[{'key':'count','label':'未成功笔数' if decline else '授权尝试','format':'count'},
+                 {'key':'share','label':'占该商户未成功记录比例' if decline else '占该商户授权尝试比例','format':'percent'}]
+        if not decline:
+            metrics.extend([{'key':'approvals','label':'授权成功笔数','format':'count'},{'key':'auth_rate','label':'授权成功率','format':'percent'}])
+        metrics.append({'key':'attempt_amount','label':'未成功金额 USD' if decline else '授权尝试金额 USD','format':'usd'})
+        if not decline:metrics.append({'key':'approved_amount','label':'授权成功金额 USD','format':'usd'})
+        if histogram or dimension['key']=='authentication':metrics=[metric for metric in metrics if metric['format']!='percent']
+        if not any((period['metrics'].get('count') or 0)>0 for group in dimension['groups'] for period in group['periods']):
+            continue
+        categories=[]
+        for group in dimension['groups']:
+            key=json.loads(group['key'])
+            if not (histogram and key[0]=='bucket') and not any((p['metrics'].get('count') or 0)>0 for p in group['periods']):
+                continue
+            label=('未知（缺失或不可换算）' if dimension['key']=='amount_bucket' else '未知（缺失）') if key==['unknown'] else '其他（合并）' if key==['other'] else group['label']
+            values={}
+            for period in group['periods']:
+                data=period['metrics']
+                values[period['key']]={metric['key']:((data.get(metric['key']) or {}).get('usd') if metric['format']=='usd' else data.get(metric['key'])) for metric in metrics}
+            categories.append({'label':label,'values':values,'is_unknown':key==['unknown']})
+        if not categories:
+            blocks.append(para(dimension['label']+'：两期均未观察到可细分记录。','note'))
+            continue
+        chart={'type':'comparison_chart','title':dimension['label'],'series':series,'metrics':metrics,'default_metric':'count' if decline or histogram or dimension['key']=='authentication' else 'auth_rate','categories':categories}
+        if layout:chart['layout']=layout
+        blocks.append(chart)
+    return blocks
+
+
+def merchant_detail_blocks(merchant, periods):
+    return segment_charts(merchant,periods)
+
+
+def risk_charts(history):
+    if not history:
+        return []
+    disputes=[{'key':'visa_predispute','label':'Visa Predispute'},
+              {'key':'visa_dispute','label':'Visa Dispute'},
+              {'key':'mastercard_chargeback','label':'Mastercard chargeback'}]
+    fraud=[{'key':'visa','label':'Visa'},{'key':'mastercard','label':'Mastercard'}]
+    if any((p.get('values',{}).get('other') or 0)>0 for p in history['fraud']['monthly']):
+        fraud.append({'key':'other','label':'其他卡组织'})
+    blocks=[]
+    for kind,title,series,basis in [
+        ('disputes','争议案件观察',disputes,'同阶段最早观察到的争议日期'),
+        ('fraud','欺诈报告',fraud,'340FRD 文件生成日作为报告日；完全重复记录取最早报告日')]:
+        for frequency,label in [('monthly','月度'),('weekly','周度')]:
+            points=history[kind][frequency]
+            block={'type':'time_series_chart','title':title+' · '+label,'unit':'count','series':series,'points':points,'date_basis':basis}
+            if frequency=='monthly':
+                rate_series=([{**s,'label':s['label']+('（描述性）' if s['key']=='visa_predispute' else '')} for s in disputes] if kind=='disputes' else [{'key':'visa','label':'Visa 欺诈报告率'},{'key':'mastercard_efm','label':'Mastercard EFM 欺诈拒付率'}])
+                block['default_view']='count'
+                block['views']=[
+                    {'key':'count','label':'笔数','unit':'count','points':points},
+                    {'key':'rate','label':'比率（估算）','unit':'percent','series':rate_series,
+                     'points':[{**p,'values':p.get('rates',{})} for p in points],
+                     'date_basis':'按卡组织月度时间口径估算',
+                     'status_note':'Visa 同月分母；Mastercard 上月分母。' if kind=='disputes' else 'Visa：欺诈报告 / 同月交易；Mastercard EFM：欺诈拒付 / 上月电商交易。'}]
+            if kind=='fraud' and history['fraud'].get('status')=='no_valid_files':
+                block['status_note']='未提供有效欺诈文件'
+            blocks.append(block)
+    blocks.append({'type':'time_series_chart','title':'VAMP · 月度','unit':'percent','series':[{'key':'vamp_ratio','label':'VAMP'}],'points':history['vamp']['monthly'],'status_note':history['vamp'].get('reason') or ''})
+    return blocks
+
+
+def write_risk_csv(facts, output):
+    with (output/'merchant-risk-history.csv').open('w',encoding='utf-8-sig',newline='') as handle:
+        writer=safe_writer(handle,numeric_columns={7,10,11})
+        writer.writerow(['merchant_id','merchant_name','metric','frequency','start','end','series','value','date_basis','status','numerator','denominator','denominator_start','denominator_end','formula','reason'])
+        for merchant in facts.get('merchant_risk_history',[]):
+            for metric in ('disputes','fraud','vamp'):
+                history=merchant[metric]
+                for frequency in ('monthly','weekly'):
+                    for point in history.get(frequency,[]):
+                        for series,value in point['values'].items():
+                            writer.writerow([merchant.get('id'),merchant.get('name'),metric,frequency,point['start'],point['end'],series,value,history.get('basis',''),history.get('status',''),'','','','','',''])
+                        for series,value in point.get('rates',{}).items():
+                            detail=point.get('rate_details',{}).get(series,{})
+                            writer.writerow([merchant.get('id'),merchant.get('name'),metric+'_rate',frequency,point['start'],point['end'],series,value,detail.get('date_basis',''),detail.get('status',''),detail.get('numerator'),detail.get('denominator'),detail.get('denominator_start'),detail.get('denominator_end'),detail.get('formula'),detail.get('reason')])
+
+
+def write_segment_csv(facts, output):
+    with (output/'merchant-segments.csv').open('w',encoding='utf-8',newline='') as handle:
+        writer=safe_writer(handle,numeric_columns={14,15})
+        writer.writerow(['merchant_id','merchant_name','dimension','population','group_key','group_label','period_kind','start','end','partial_week','count','approvals','auth_rate','share','attempt_amount_usd','approved_amount_usd'])
+        for merchant in facts.get('merchant_breakdowns',[]):
+            for dimension in merchant['dimensions']:
+                for group in dimension['groups']:
+                    periods=[{'kind':'main','start':facts['metadata']['main_start'],'end':facts['metadata']['main_end'],'partial_week':None,'metrics':group['metrics']},*[dict(w,kind='week') for w in group['weeks']]]
+                    for period in periods:
+                        metric=period['metrics']
+                        writer.writerow([merchant['id'],merchant['name'],dimension['key'],dimension['population'],group['key'],group['label'],period['kind'],period['start'],period['end'],period['partial_week'],metric['count'],metric['approvals'],metric['auth_rate'],metric['share'],(metric.get('attempt_amount') or {}).get('usd'),(metric.get('approved_amount') or {}).get('usd')])
+
+
+def write_detail_csv(facts, output):
+    with (output/'merchant-detail-comparison.csv').open('w',encoding='utf-8',newline='') as handle:
+        writer=safe_writer(handle,numeric_columns={13,14})
+        writer.writerow(['merchant_id','merchant_name','dimension','population','group_key','group_label','period','start','end','count','approvals','auth_rate','share','attempt_amount_usd','approved_amount_usd'])
+        for merchant in facts.get('merchant_detail_comparison',{}).get('merchants',[]):
+            for dimension in merchant['dimensions']:
+                for group in dimension['groups']:
+                    for period in group['periods']:
+                        metric=period['metrics']
+                        writer.writerow([merchant['id'],merchant['name'],dimension['key'],dimension['population'],group['key'],group['label'],period['key'],period['start'],period['end'],metric['count'],metric['approvals'],metric['auth_rate'],metric['share'],(metric.get('attempt_amount') or {}).get('usd'),(metric.get('approved_amount') or {}).get('usd')])
+
+
+def without_merchants(facts, excluded):
+    if not excluded:
+        return facts
+    def keep(item):
+        return item.get('id') not in excluded
+    out=dict(facts)
+    out['merchants']=[m for m in facts.get('merchants',[]) if keep(m)]
+    out['merchant_weeks']=[m for m in facts.get('merchant_weeks',[]) if keep(m)]
+    out['merchant_risk_history']=[m for m in facts.get('merchant_risk_history',[]) if keep(m)]
+    out['merchant_breakdowns']=[m for m in facts.get('merchant_breakdowns',[]) if keep(m)]
+    detail=facts.get('merchant_detail_comparison') or {}
+    out['merchant_detail_comparison']={**detail,'merchants':[m for m in detail.get('merchants',[]) if keep(m)]}
+    return out
+
+
+def filter_existing_csv(path, excluded):
+    if not path.exists() or not excluded:
+        return
+    with path.open(newline='',encoding='utf-8-sig') as handle:
+        rows=list(csv.reader(handle))
+    if not rows:
+        return
+    header,body=rows[0],rows[1:]
+    id_at=next((i for i,cell in enumerate(header) if cell in ('merchant_id','id')),None)
+    kept=[row for row in body if (row[id_at] if id_at is not None and id_at<len(row) else None) not in excluded and not any(cell in excluded for cell in row)]
+    with path.open('w',newline='',encoding='utf-8') as handle:
+        csv.writer(handle).writerows([header,*kept])
+
+
+def build(facts, detail_merchants=None, excluded_ids=None):
+    excluded=set(excluded_ids or [])
+    known={m.get('id') for m in facts.get('merchants',[])}
+    unknown=excluded-known
+    if unknown:
+        raise ValueError('Unknown excluded merchant IDs: '+', '.join(sorted(unknown)))
+    excluded_merchants=[m for m in facts.get('merchants',[]) if m.get('id') in excluded]
+    facts=without_merchants(facts,excluded)
+    meta=facts['metadata']
+    merchants=sorted(facts['merchants'],key=lambda m:(-m['attempts'],m.get('id') or ''))
+    active=[m for m in merchants if m['attempts']]
+    eligible=[m for m in active if m['attempts']>=30 and m['auth_rate'] is not None]
+    lowest=min(eligible,key=lambda m:m['auth_rate']) if eligible else None
+    followups=[m for m in merchants if not m['attempts'] and ((m['refund_count'] or 0)>0 or (m['dispute_snapshots'] or 0)>0)]
+    selected=active[:1]
+    if lowest and lowest not in selected:
+        selected.append(lowest)
+    if detail_merchants:
+        requested=set(detail_merchants)
+        known={m.get('id') for m in merchants}
+        if not requested.issubset(known):
+            raise ValueError('Unknown detail merchant IDs: '+', '.join(sorted(requested-known)))
+        selected=[m for m in merchants if m.get('id') in requested]
+    findings=[]
+    if lowest:
+        findings.append(f"授权核查可从 {name(lowest)} 开始：在授权尝试不少于 30 笔的子商户中，其授权成功率最低，为 {percent(lowest['auth_rate'])}（{number(lowest['approvals'])} / {number(lowest['attempts'])}）。商户间的国家和卡种差异尚未控制，该排名只用于挑选授权核查对象，不是已确认原因。")
+    if active:
+        largest=active[0]
+        findings.append(f"{name(largest)} 的授权尝试最多，为 {number(largest['attempts'])} 笔，授权成功率为 {percent(largest['auth_rate'])}。详细分析其拒绝响应和发卡行国家，有助于确定需要核查的交易群体。")
+    if followups:
+        findings.append('本期未观察到授权、但仍有退款或争议记录的子商户包括 '+ '、'.join(name(m) for m in followups)+'。应核对历史交易和后续处理责任，不能据此认定商户已经停业。')
+    if excluded_merchants:
+        findings.append('、'.join(name(m)+'（'+str(m.get('id'))+'）' for m in excluded_merchants)+'已按历史商户排除，不进入本期对比、明细和核查清单。排除不是停业结论，也不是数据缺失。')
+    if not findings:
+        findings.append('本期没有足够的子商户授权记录用于比较。请先核对各商户的数据覆盖与归属。')
+    days=(date.fromisoformat(meta['main_end'])-date.fromisoformat(meta['main_start'])).days+1
+    model={
+        'title':'子商户支付表现分析',
+        'subtitle':'根据 Worldpay 授权、结算、争议和欺诈文件整理 · 比较子商户表现，定位商户问题，明确逐商户核查事项。',
+        'periods':[f"报告期：{meta['main_start']} 至 {meta['main_end']}（{days} 天）",'时间口径：保留源文件日期；时区未验证'],
+        'summary_title':'子商户核查重点','summary':findings,'sections':[],
+        'links':[{'label':'商户风险历史 CSV','file':'merchant-risk-history.csv'},{'label':'本周与上周同期细分 CSV','file':'merchant-detail-comparison.csv'},{'label':'子商户每周指标 CSV','file':'merchant-weekly.csv'},{'label':'子商户指标 CSV','file':'merchant-metrics.csv'},{'label':'商户归属 CSV','file':'merchant-mapping.csv'},{'label':'归属与核验记录 JSON','file':'coverage-and-reconciliation.json'},{'label':'Markdown 报告','file':'overview.zh.md'}],
+        'footer':'来源：Worldpay 授权、结算、争议及 DART-340 欺诈文件。'}
+    sections=model['sections']
+    comparison=[]
+    for m in merchants:
+        status='本期有授权记录' if m['attempts'] else '本期无授权记录'
+        if 0<m['attempts']<30:status='样本少于 30 笔'
+        observed=m.get('layer_observed',{}).get('auth',False)
+        comparison.append([name(m),m.get('id') or '未归属',number(m['attempts']) if observed else '',number(m['approvals']) if observed else '',percent(m['auth_rate']),amount(m,'sales'),number(m['refund_count']),amount(m,'refunds',True),number(m['dispute_snapshots']),status])
+    sections.append({'title':'1. 子商户对比','nav':'子商户对比','blocks':[
+        table(['子商户','商户 ID','授权尝试','授权成功','授权成功率','销售金额 USD','退款笔数','退款金额 USD','争议快照记录','样本说明'],comparison,filter=True),
+    ]})
+    sections.append({'title':'2. 子商户逐周对比','nav':'逐周对比','blocks':weekly_blocks(facts,merchants,selected)})
+    detail_groups=[]
+    comparison_data=facts.get('merchant_detail_comparison',{})
+    periods=comparison_data.get('periods',[])
+    comparisons={item.get('id'):item for item in comparison_data.get('merchants',[])}
+    histories={item.get('id'):item for item in facts.get('merchant_risk_history',[])}
+    expanded={m.get('id') for m in selected}
+    for m in merchants:
+        comparison=comparisons.get(m.get('id'))
+        blocks=merchant_detail_blocks(comparison,periods) if comparison else []
+        blocks.extend(risk_charts(histories.get(m.get('id'))))
+        detail_groups.append({'type':'group','caption':name(m)+' · '+str(m.get('id') or '未归属'),'collapsed':m.get('id') not in expanded,'blocks':blocks})
+    sections.append({'title':'3. 重点子商户详情','nav':'商户详情','blocks':detail_groups})
+    action_rows=[]
+    for m in selected:
+        reasons=top_reasons(m)
+        if reasons:
+            reason=reasons[0]
+            evidence=f"{reason['message']}：{number(reason['count'])} 笔；授权成功率 {percent(m['auth_rate'])}"
+            action='核对该响应在该商户下的处理商含义，再按发卡行国家和认证状态细分检查。'
+        else:
+            evidence=f"授权成功 {number(m['approvals'])} / {number(m['attempts'])}；缺少可展开的拒绝响应"
+            action='核对该商户的响应字段与来源覆盖，避免根据缺失原因直接调整策略。'
+        action_rows.append([name(m),m.get('id') or '未归属',evidence,action,'不将观察差异视为已确认原因，不估算可挽回金额。'])
+    for m in followups:
+        action_rows.append([name(m),m.get('id') or '未归属',f"未观察到本期授权；退款 {number(m['refund_count'])} 笔，争议快照记录 {number(m['dispute_snapshots'])} 条",'核对原始销售所属商户、退款处理及争议责任。','无本期授权不代表停业；争议记录不等于新增案件。'])
+    if not action_rows:
+        action_rows=[['未归属或缺少观察','','缺少支持逐商户判断的记录','先补齐商户身份及来源覆盖。','暂不形成商户表现结论。']]
+    sections.append({'title':'4. 逐商户核查清单','nav':'核查清单','blocks':[table(['子商户','商户 ID','观察依据','下一步核查','解释边界'],action_rows)]})
+    coverage=[table(['子商户','商户 ID','授权记录','结算记录','争议记录'],[[name(m),m.get('id') or '未归属',*['✓' if m.get('layer_observed',{}).get(layer,False) else '' for layer in ('auth','settlement','dispute')]] for m in merchants])]
+    audit=facts.get('quality',{}).get('risk_history',{})
+    if audit:
+        attribution=audit.get('fraud_attribution',{})
+        files=audit.get('files',[])
+        invalid=[item.get('date',item['file']) for item in files if item.get('status')=='invalid']
+        future=[item.get('date',item['file']) for item in files if item.get('status')=='future_not_parsed']
+        unmatched=attribution.get('unmatched')
+        amounts=audit.get('unmatched_amounts_by_currency') or {}
+        rows=[
+            ['欺诈记录归属',str(attribution.get('attributed',0))+' / '+str(audit.get('distinct_exact_rows',0))],
+            ['无效欺诈文件日期','、'.join(invalid) or '无'],
+            ['数据截至',meta['main_end']]
+        ]
+        if future:
+            rows.append(['晚于截止日、未解析的欺诈文件','、'.join(future)])
+        if unmatched:
+            amount_text='、'.join(currency+' '+money(value) for currency,value in amounts.items())
+            rows.append(['未归属欺诈记录',str(unmatched)+' 条'+(('，金额 '+amount_text) if amount_text else '')+'，未计入商户笔数'])
+        coverage.append(table(['数据范围','观察值'],rows))
+        notes=[]
+        if any(item.get('error')=='missing_header' for item in files):
+            notes.append('缺少表头的欺诈文件未解析，因此没有进入笔数。')
+        if future:
+            notes.append('晚于截止日的欺诈文件未解析。')
+        if unmatched:
+            notes.append('未能归属的欺诈记录不计入商户笔数。')
+        definitions_note=''.join(notes)
+    else:
+        definitions_note=''
+    definitions=[
+        para('空白为不可用或未观察到的数据，不作为 0；0 仅表示提供的记录中观察到的零值。'),
+        para('授权、销售与退款按各自事件日期统计。授权成功金额与结算销售金额不同，退款金额以绝对值展示。周汇总格里的美元是授权成功金额，不是销售金额。销售金额 0.00 是结算层观察到的零值；没有结算层记录时销售金额留空。'),
+        para('争议趋势按同一阶段最早观察到的争议日期统计案件，状态更新不重复计数；并非新增案件。欺诈按 340FRD 文件生成日作为报告日，完全重复记录取最早报告日。'),
+        para('比率按卡组织月度时间口径作提取数据估算，并非正式监控结果。Visa 使用当月分母，Mastercard 拒付与 EFM 使用上月分母；EFM 分子是 4837/4863 欺诈拒付，不是 340FRD 的全部 Mastercard 报告。周图仅展示笔数；预争议比率为描述性指标，不纳入 VAMP。'),
+        para('340FRD 报告日已按文件生成日确认。'+definitions_note+'VAMP 仍需核验 TC15/TC05 处理日、事件身份、适用范围及排除标记。')
+    ]
+    coverage.append({'type':'group','caption':'数据口径','collapsed':True,'blocks':definitions})
+    sections.append({'title':'5. 商户归属与覆盖','nav':'归属与覆盖','blocks':coverage})
+    return model
+
+
+if __name__=='__main__':
+    parser=argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--facts',type=Path,required=True)
+    parser.add_argument('--output',type=Path,required=True)
+    parser.add_argument('--detail-merchant',action='append',help='Merchant ID to expand; repeat to select several')
+    parser.add_argument('--exclude-merchant',action='append',help='Merchant ID to omit as historical; repeat to exclude several')
+    args=parser.parse_args()
+    facts=json.loads(args.facts.read_text(encoding='utf-8'))
+    excluded=set(args.exclude_merchant or [])
+    model=build(facts,args.detail_merchant,excluded)
+    report_facts=without_merchants(facts,excluded)
+    args.output.mkdir(parents=True,exist_ok=True)
+    write_weekly_csv(report_facts,args.output)
+    write_segment_csv(report_facts,args.output)
+    write_detail_csv(report_facts,args.output)
+    write_risk_csv(report_facts,args.output)
+    for filename in ('merchant-metrics.csv','merchant-mapping.csv'):
+        filter_existing_csv(args.output/filename,excluded)
+    (args.output/'presentation.json').write_text(json.dumps(model,ensure_ascii=False,indent=2)+'\n',encoding='utf-8')
+    render(model,args.output)