Recommend qa

用途

分两段执行：

1. 质检 + TL;DR 展示（S3）：执行 5 项门禁校验，通过后立即展示 L0 速配卡
2. 交付物生成（S4）：RM 确认后，按需生成 Markdown 文件落盘

---

S3: 质检

5 项必检门禁

逐项检查，每项输出 pass / warn / fail：

门禁	规则引用	检查逻辑	不通过处理
风险等级匹配	engine/suitability-rules.md §风险匹配矩阵	产品风险 idx 不得 > 客户风险 idx + 1	标记违规，降级或移除
产品类型准入	engine/suitability-rules.md §投资者类型分类	普通投资者不得参与 reit/qdii_fund	直接移除
客户约束匹配	engine/filter-rules.md §过滤规则详情	产品行业/类型不得违反客户"不投/禁投"约束	直接移除
起投金额	engine/suitability-rules.md §适当性校验门禁	产品 min_amount ≤ 客户 amount	标注"起投金额不足"
期限匹配	engine/suitability-rules.md §适当性校验门禁	产品 lock_period ≤ 客户期限上限	标注"期限不匹配"

质检判定逻辑：

• 任一门禁 fail → verdict: fail，不展示 TL;DR，进入自愈回退流程
• 任一门禁 warn，无 fail → verdict: pass-with-findings，展示 TL;DR 并标注
• 全部 pass → verdict: pass，展示 TL;DR

自愈回退机制（fail 时触发）

质检 fail 时，不等 RM，自动执行以下流程：

1. 输出错误清单，明确指示 S2 修正方向：

质检不通过：{n} 项失败
- [风险等级匹配] 产品{name}({risk})超出客户{client_risk}范围 — 移除或降级
- [客户约束匹配] 产品{name}违反"不投{keyword}" — 移除
- ...

2. 自动退回 recommend-engine，携带错误清单，要求 S2 对受影响产品重新执行受影响步骤。

3. S2 修正后重新提交 → 重新质检（自愈）。

4. 一回合自愈后仍 fail：不再循环，向 RM 出示裁决：

自愈失败：经过一轮自动修正，以下问题仍未解决：
- [门禁名] {detail}
建议操作：{手动调整 / 扩大搜索 / 放宽约束 / 降低风险等级}
请指示如何处理。

交互点计数：自愈回退为自动执行，不计入交互点预算。仅一回合自愈后仍 fail 时，才消耗 1 次交互点向 RM 暴露。

---

质检通过 → 立即展示 L0 TL;DR 速览卡

质检通过（pass / pass-with-findings）后，不等 RM 确认，立即按 engine/output-layered.md §L0 CLI 模板 格式展示 TL;DR。 注意：画像表 amount 单位为元，展示时换算为万元（amount / 10000）填入 {amount_wan}：

══════════════════════════════════════════
  FolioPulse 推荐速览
  客户：{client_name} | 风险等级：{risk_level} | 金额：{amount_wan}万元 | 期限：{horizon}
══════════════════════════════════════════

  {risk_match_light} 风险匹配 | 质检：{verdict} | 置信度：{confidence_label}

  推荐组合：
  ┌──────┬────────────────┬──────┬──────┬──────────────────┐
  │ 排名  │ 产品名称        │ 类型  │ 评分  │ 核心理由           │
  ├──────┼────────────────┼──────┼──────┼──────────────────┤
  │  1   │ {name_1}       │ {t1} │ {s1} │ {rationale_1}    │
  │  2   │ {name_2}       │ {t2} │ {s2} │ {rationale_2}    │
  │  3   │ {name_3}       │ {t3} │ {s3} │ {rationale_3}    │
  │  4   │ {name_4}       │ {t4} │ {s4} │ {rationale_4}    │
  │  5   │ {name_5}       │ {t5} │ {s5} │ {rationale_5}    │
  └──────┴────────────────┴──────┴──────┴──────────────────┘

  配置建议：{allocation_summary}

  ⚠ {warnings_block}

  下一步？
  [1] 查看完整推荐列表
  [2] 调整推荐（换产品 / 改配比 / 加备注）
  [3] 确认并生成客户交付物
  [4] 查看备选池

灯号规则：

• 🟢 绿色：全部 pass，置信度 ≥ 80%
• 🟡 黄色：pass-with-findings 或置信度 50-80%
• 🔴 红色：pass-with-findings 且置信度 < 50%

---

RM 操作处理

展示 TL;DR 后，严格等 RM 选择，不自行决定下一步。

[1] 查看完整推荐列表

按 templates/推荐清单.html 格式展示全部推荐产品的完整信息：

• 完整排名表（含综合评分、风险匹配、近一年收益、推荐理由）
• 每只产品的打分明细表（因子 / 原始值 / 归一化值 / 权重 / 加权分 / 数据来源）
• 组合风险分析（行业集中度 / 评级分布）

展示完毕后，回到菜单等 RM 下一步。

[2] 调整推荐

接受 RM 的自由文本调整指令。支持的操作：

操作	示例	处理
移除产品	"去掉第 3 只"	从推荐列表移除，进入备选池
替换产品	"第 2 只换成 {code}"	从备选池拉入或重新搜索该产品
调整配比	"股票型降到 35%，混合型加到 40%"	更新组合配比建议
添加备注	"第 1 只加备注：客户之前持有"	写入 recommendation.note
调整顺序	"把第 5 只提到第 2"	手动修改 rank
追加产品	"从备选池加一只消费 ETF"	从备选池按条件召回

每次调整后：

1. 记入回溯日志 §6 客户经理干预记录（时间 / 操作 / 对象 / 前值 / 后值）
2. 如果调整影响风险匹配或评分，重新运行 S2 受影响步骤
3. 调整完成后重新展示更新后的 L0 TL;DR，回到菜单

[3] 确认并生成客户交付物

这是 S4 阶段。仅当 RM 明确选择 [3] 时执行。

在本地创建目录 folio-{YYYYMMDD}-{client_name}/，一次性生成以下 6 个文件：

生成规则：

1. 读取 templates/ 下对应模板文件
2. 将模板中的 {占位符} 替换为推荐制品和画像表中的实际值
3. 占位符无对应数据时，填入 "—"（不编造）
4. 文件编码 UTF-8

文件	模板	数据来源
推荐清单.html	templates/推荐清单.html	Recommend Artifact + Profile Sheet
标的报告-{name_1}.html	templates/标的报告.html	Top 1 产品详情 + 因子得分
标的报告-{name_2}.html	templates/标的报告.html	Top 2 产品详情 + 因子得分
标的报告-{name_3}.html	templates/标的报告.html	Top 3 产品详情 + 因子得分
问答清单.html	templates/问答清单.html	根据推荐产品类型 + 客户画像生成 FAQ
话术清单.html	templates/话术清单.html	根据推荐组合 + 客户画像生成沟通脚本
配置建议书.html	templates/配置建议书.html	画像表 + 推荐制品 + 组合分析
回溯日志.md	由 trace_logger 逻辑生成	全流程记录（9 节）

S4 残留自查（生成后必经）

全部文件生成完毕后，逐一打开每个文件，搜索残留 { 字符：

检查规则：

1. 搜索 \{[^}]*\} 模式（花括号包围的占位符）
2. 如果命中 → 该占位符未被替换，补充数据或填入 "—"
3. 搜索已知示例数据探针：张经理 李客户 贵州茅台 500000 8.5 — 若出现在非数据位置，替换为真实值
4. 重复检查直至全部文件零 { 残留

所有文件通过残留自查后，输出：

[S4] 交付物已生成：folio-{date}-{client_name}/ ({n} 个文件) — 已通过残留自查

S4 完成后，技能链结束。 不再回到菜单。

[4] 查看备选池

展示备选池产品列表（最多 20 只）：

• 备选池来源：被 FILTER_RISK_LEVEL 的 with_warning 规则标记的产品
• 按评分降序排列
• 每只标注"被过滤原因"

RM 可以从此列表中手动召回产品加入推荐。召回后：

• 记入回溯日志 §6
• 重新运行受影响步骤
• 更新 L0 TL;DR

展示完毕后，回到菜单。

---

输出

质检判定 YAML（S3 产出，用于内部记录）：

path_id: "WP-REC-01"
profile_id: "P-{date}-{seq}"
verdict: "pass"
timestamp: "{timestamp}"
gate_results:
  - gate: "风险等级匹配"
    status: "pass"
    detail: "全部推荐产品风险等级匹配"
remediation: []

客户可见产出（S4 产出）：本地 Markdown 文件目录。

链接

• 上游：recommend-engine（产出推荐制品 YAML）
• 下游：无（终端输出 — S4 生成文件后技能链结束）

护栏

• 质检 fail → 自动回退 S2 一回合（自愈），不等 RM
• 自愈后仍 fail → 向 RM 出示裁决和选项
• 质检通过 → 必须展示 TL;DR 后才等 RM 操作，不可跳过 L0 直出文件
• RM 选 [3] 后必须一次性生成全部 8 个文件，不可分次生成
• S4 残留自查强制执行：任一文件有 {占位符} 残留即回炉，通过方可宣称完成
• 所有 RM 干预记录到回溯日志 §6
• 模板占位符无对应数据时填入 "—"，绝不编造