visual-spec 0.1.8 → 0.1.10

package/skills/visual-spec/prompts/vspec_qc/banking_quality_cases.md

@@ -0,0 +1,99 @@
+#### 1. 金额计算口径不清：关键词“金额/精度/舍入/分摊/尾差”
+- 问题分类：模糊表达
+- 关键词：关键词“金额/精度/舍入/分摊/尾差”
+- 问题描述：金额/费用/税费/折扣/汇率换算的口径不清，会导致前后端实现不一致、对账失败、尾差累计、审计不可追溯
+- 错误问题示例：应收 = 单价 * 数量 - 优惠（未说明币种、精度、舍入规则、是否含税、分摊顺序）
+- 解决方案：用“公式表 + 口径说明 + 输入输出样例”明确：币种；精度（小数位）；舍入（round/floor/ceil）与时点；计算顺序；分摊维度与尾差处理（尾差归属策略）；前后端一致性
+- 解决方案示例：应收金额(元)=round(含税单价(元)*数量 - 优惠(元) + 运费(元), 2)；分摊顺序：先分摊优惠再分摊运费；尾差处理：尾差归最后一条明细；提供 3 组输入输出样例
+- 方案收益：避免实现与验收偏差，减少财务差错与返工，提升可测试性与可审计性
+- 应用场景：计费/收费/手续费/利息/分期/分摊/退款/对账等所有涉及金额的需求
+- 关联质量标准：精确性
+
+#### 2. 平账/对账口径缺失：关键词“对账/平账/清算/入账”
+- 问题分类：遗漏关键规则
+- 关键词：关键词“对账/平账/清算/入账”
+- 问题描述：未定义“账目如何平、以谁为准、差异如何处理”，会导致清算失败、财务无法落账、差错无法闭环
+- 错误问题示例：每日对账后生成对账报表（未说明对账维度、差异阈值、差异处理与责任系统）
+- 解决方案：补齐对账模型与流程：对账对象（订单/流水/分录/清算文件）；对账维度键（商户号/渠道/日期/金额/币种/流水号）；对账周期与截止时间（cutoff）；差异分类；差异处理（自动/人工）；以谁为准与回写方式；对账报表口径；可追溯链路
+- 解决方案示例：对账维度=渠道+商户号+交易日+币种；差异阈值=0.01 元；差异类型=缺单/多单/金额不一致/状态不一致；处理=自动生成差错单→分派→补单/冲正/人工复核；以支付渠道清算文件为准，系统侧生成差额分录
+- 方案收益：确保资金与账务一致，降低结算风险，提升运营效率与可审计性
+- 应用场景：支付、清算、分账、代付、充值、退款、资金归集等
+- 关联质量标准：完整性
+
+#### 3. 误差与容差规则缺失：关键词“误差/容差/尾差/差额”
+- 问题分类：边界条件缺失
+- 关键词：关键词“误差/容差/尾差/差额”
+- 问题描述：未定义误差阈值与处理策略，会导致小额差异长期累积、对账无法自动化、争议无法裁决
+- 错误问题示例：对账差额自动处理（未说明差额阈值与归属）
+- 解决方案：明确容差策略：阈值（按币种/渠道/产品不同）；差额归属（平台/商户/渠道/用户）；自动处理条件与审批；累计阈值；报表展示口径；审计留痕
+- 解决方案示例：容差阈值=0.01 元；当差额绝对值<=阈值且同一渠道同日累计<=1 元时自动平账；超出则生成差错单并需财务复核；所有自动平账必须记录原因码与规则版本
+- 方案收益：提升对账自动化率，降低人工成本，减少争议
+- 应用场景：分摊、汇兑、清算、跨系统统计对齐
+- 关联质量标准：一致性
+
+#### 4. 冲正/补记/退款的会计口径不清：关键词“冲正/补记/退款/撤销”
+- 问题分类：状态与动作口径缺失
+- 关键词：关键词“冲正/补记/退款/撤销”
+- 问题描述：冲正与退款/撤销语义混淆，会导致分录方向错误、重复记账、对账无法闭环
+- 错误问题示例：交易失败后做退款处理（未区分“未入账/已入账/已清算”）
+- 解决方案：定义动作语义与前置状态：撤销（未清算/未入账）、冲正（已入账需反向分录）、退款（资金已清算需走资金回退）；定义每个动作的分录模板、状态机、对外通知、对账影响与追溯字段
+- 解决方案示例：已入账但需撤回：生成冲正分录（debit/credit 反向），关联 original_entry_id；退款必须产生 refund_id、refund_entry_id，且与原交易一一关联；提供状态机图与 2 组例子
+- 方案收益：减少财务差错与重复操作，提升可审计性
+- 应用场景：支付/代扣/代付/充值/退款/冲正/撤销
+- 关联质量标准：正确性
+
+#### 5. 幂等与重复扣款/重复入账风险：关键词“幂等/重试/重复扣款/重复入账”
+- 问题分类：可靠性不足
+- 关键词：关键词“幂等/重试/重复扣款/重复入账”
+- 问题描述：金融链路中重试与网络抖动常见，若未设计幂等键与去重策略，会产生重复扣款、重复入账、对账差异与客诉
+- 错误问题示例：请求超时后前端重试下单/扣款（后端未做幂等）
+- 解决方案：定义幂等策略：幂等键来源（业务单号/渠道流水号）；幂等范围（扣款/入账/通知）；去重存储（幂等表/唯一索引）；幂等窗口；并发控制；回放与补偿；对账字段一致性
+- 解决方案示例：idempotency_key=merchant_order_no；扣款接口以该 key 建唯一索引；重复请求返回同一结果（含交易状态）；对账以 channel_txn_id + merchant_order_no 双键匹配
+- 方案收益：降低资金风险与客诉，提升链路可靠性
+- 应用场景：支付/清算/通知回调/批处理/文件导入
+- 关联质量标准：鲁棒性
+
+#### 6. 反洗钱（AML）规则与流程缺失：关键词“KYC/AML/可疑交易/制裁名单”
+- 问题分类：合规缺失
+- 关键词：关键词“KYC/AML/可疑交易/制裁名单”
+- 问题描述：未定义 AML/KYC 要求，会导致合规风险、监管处罚、系统无法通过内控审计
+- 错误问题示例：用户开通后即可大额交易（未做实名/黑名单/可疑监测）
+- 解决方案：补齐合规能力清单：KYC 等级与要素；制裁/黑名单筛查；交易监测规则（阈值、频率、结构化交易、异常地理/设备）；可疑交易处理流程（冻结/人工审核/上报）；留痕与审计字段；数据保留期限
+- 解决方案示例：KYC level=0/1/2；level2 才允许单笔>5 万；命中制裁名单：禁止交易并记录 hit_detail；可疑交易：生成 STR case，状态=待复核/已上报/已结案；所有规则需有 version 与生效时间
+- 方案收益：降低合规风险，提升可审计性与可运营性
+- 应用场景：开户、转账、充值、提现、跨境、交易撮合等
+- 关联质量标准：合规性
+
+#### 7. 反欺诈规则与风控处置缺失：关键词“反欺诈/风控/限额/黑白名单”
+- 问题分类：风险控制缺失
+- 关键词：关键词“反欺诈/风控/限额/黑白名单”
+- 问题描述：未定义风控策略与处置动作，会导致盗刷、套现、撞库、薅羊毛等损失
+- 错误问题示例：活动补贴发放（未限制同设备/同账号/同银行卡多次领取）
+- 解决方案：补齐风控策略：限额（单笔/日/月/渠道/用户等级）；设备指纹/地理位置/行为特征；黑白名单；风险评分阈值；处置（拦截/二次验证/人工审核/冻结）；申诉流程与放行策略；监控告警
+- 解决方案示例：风险分>=80 拦截；60-79 触发短信/人脸二次验证；同设备 24h 内最多领取 1 次；失败原因必须可解释并展示给用户（含客服口径码）
+- 方案收益：降低欺诈损失，提升可运营与可解释性
+- 应用场景：支付、营销补贴、开户、提现、转账、登录
+- 关联质量标准：安全性
+
+#### 8. 利息/汇率/跨币种口径缺失：关键词“计息/利率/汇率/币种”
+- 问题分类：模糊表达
+- 关键词：关键词“计息/利率/汇率/币种”
+- 问题描述：利息计算（年化/日利率）、汇率来源与生效时点不清，会导致金额偏差、争议与审计问题
+- 错误问题示例：按日计息（未说明日切时间、计息基数、是否含当日、利率取值规则）
+- 解决方案：定义金融口径：计息方法（单利/复利）、计息基数（360/365/366）、日切时间与时区、是否含首尾日；汇率来源（中间价/牌价/渠道价）、取价时点、锁价规则与有效期；异常策略（缺汇率/汇率波动）
+- 解决方案示例：日利率=年利率/365；计息天数=自然日，含起息日不含止息日；汇率取支付时刻的渠道汇率并锁定到订单；缺汇率则阻断并给出错误码
+- 方案收益：减少金额争议，提升一致性与可审计性
+- 应用场景：跨境支付、分期、贷款、理财、结售汇
+- 关联质量标准：精确性
+
+#### 9. 数据留痕与不可抵赖不足：关键词“审计/日志/留痕/不可篡改”
+- 问题分类：合规缺失
+- 关键词：关键词“审计/日志/留痕/不可篡改”
+- 问题描述：资金类操作缺少审计留痕（操作者/时间/前后值/原因码/规则版本），会导致无法追责与无法通过审计
+- 错误问题示例：管理员修改限额（未记录修改前后与审批链）
+- 解决方案：定义审计日志矩阵：记录哪些操作；字段级前后值；原因/备注；审批链；日志保留期限；不可篡改策略（WORM/哈希链/签名）；查询与导出权限
+- 解决方案示例：变更限额需审批；审批通过后写入 audit_log：actor、role、ip、device、before/after、reason_code、approval_id、rule_version；审计导出仅合规角色可见
+- 方案收益：提升可审计性与可追责性
+- 应用场景：资金、风控、权限、配置、清算、对账
+- 关联质量标准：可追溯性
+

package/skills/{visual-spec-skill → visual-spec}/prompts/vspec_qc/qc.md

@@ -1,8 +1,14 @@
 你是一名资深交付质量负责人（QA Lead）。你的任务是：基于质量标准对项目内的 `/specs/` 产物进行质量检查，并输出“质量不合格清单”表格。
 
+语言与本地化（必须）：
+- 读取 `/scheme.yaml` 的 `selected.language`（支持 `en`、`zh`、`ja`；若缺失/非法则按 `en` 处理；`zh-CN` 视为 `zh` 的别名）
+- 输出报告必须统一使用该语言（标题、表头、描述文案等）；禁止混用其他语言
+
 输入信息：
 - 内嵌质量标准：`prompts/vspec_qc/quality_standard.md`
+- 内嵌领域案例补充：`prompts/vspec_qc/banking_quality_cases.md`（如存在；作为领域补充标准参与合并）
 - 用户质量标准（如存在）：项目根目录下的 `quality_standard.md`
+- 领域/行业质量标准（如存在）：项目根目录下的 `domain_quality_standard.md`
 - 需求质量错题本（如存在）：项目下 `qc/` 目录内的“需求质量错题本”文件（文件名以实际为准）
 - 需求与产物目录：`/specs/`
 
@@ -12,7 +18,9 @@
    - 生成/更新项目根目录 `quality_standard.md`，用于本次与后续 `/vspec:qc` 的检查
 1. 合并质量标准：
    - 以“内嵌质量标准”为默认基线
-   - 若用户提供 `quality_standard.md`，则将其作为补充/覆盖标准（同名条款以用户为准）
+   - 若存在 `prompts/vspec_qc/banking_quality_cases.md`：将其作为内嵌的领域补充标准（优先级高于内嵌基线，但低于项目级覆盖）
+   - 若存在 `domain_quality_standard.md`：将其作为“领域/行业规范”补充标准（优先级高于内嵌）
+   - 若用户提供 `quality_standard.md`：将其作为项目级补充/覆盖标准（优先级最高；同名条款以用户为准）
 2. 检查范围：
    - 仅检查 `/specs/` 下的需求产物与其引用关系（不扫描源码目录）
 3. 不要给出长篇解释，只输出问题清单表格（必要时可在“修复建议”中给出一句话建议）
@@ -20,8 +28,16 @@
 输出要求（必须）：
 1. 输出一张“质量不合格清单”表（表头固定）：
 
-| 编号 | 检查点 | 标准来源 | 发现位置 | 不合格描述 | 严重级别 | 修复建议 |
-| --- | --- | --- | --- | --- | --- | --- |
+- 表头必须严格按所选语言使用以下版本之一：
+  - 语言=en：
+    - `| ID | Checkpoint | Standard Source | Location | Nonconformance | Severity | Fix Suggestion |`
+    - `| --- | --- | --- | --- | --- | --- | --- |`
+  - 语言=zh：
+    - `| 编号 | 检查点 | 标准来源 | 发现位置 | 不合格描述 | 严重级别 | 修复建议 |`
+    - `| --- | --- | --- | --- | --- | --- | --- |`
+  - 语言=ja：
+    - `| 番号 | チェック項目 | 標準ソース | 発見箇所 | 不適合内容 | 重大度 | 修正案 |`
+    - `| --- | --- | --- | --- | --- | --- | --- |`
 
 2. 严重级别取值固定为：P0（阻断）/ P1（严重）/ P2（一般）
 3. “发现位置”必须尽量精确：