FinClaw V1 Sub-Packet: Commercial Signal — 工程实现
状态：Pending / 等待 sub-1 完成 + ProfileConsent / SensitiveInputHandling 已实现 日期：2026-05-16 Lane：Engineering Owner：FinClaw Controller 分发，AI Coding Agent 执行 Parent Packet：v1-commercial-signal-instrumentation-task-packet.md
1. 目标
把 schema 转化为运行时能采集 / 查询 / 周报的工程实现，覆盖 v1-commercial-signal-instrumentation-design.md §3-§9：
- POST endpoint + event sink；
- Consent Gate + Sensitive Filter；
- 6 个漏斗 + 4 类 cohort 留存查询脚本；
- Pricing Intent 入口（feature flag，仅 trial cohort 可见，明确「意愿调查不会扣款」文案）；
- 周报 CLI；
- Consent 撤回路径（48h tick 清理 events + cohort 衍生）。
2. 允许读取
见 frontmatter must_read / reference_only。
3. 禁止范围
- 不绕过 ProfileConsent.consent_for_trial_data 直接写事件；
- 不收集真实付款凭证 / 卡号 / 银行账户；
- 不在试运营期间真实扣款；
- 不与第三方分析 SaaS 共享原始事件；
- 不在事件 payload 中保留任何凭证 / 私钥 / 助记词模式（必须依赖 Sensitive Filter）；
- 不实现完整 BI / 数据仓库 / A/B 框架（design §10 Out of Scope）；
- 不允许新增 schema（schema 由 sub-1 冻结）；
- 不修改 design 文档正文（如需改 schema 必须先回写 design Open Items 再做 sub-1 修订）。
4. Acceptance Criteria
| AC ID | 验收项 |
|---|---|
| AC-1 | POST /api/v1/events 端点接受 sub-1 schema 全部 7 类事件，e2e 测试覆盖 |
| AC-2 | Consent Gate 单测：100% 阻挡 consent_for_trial_data=false 的事件并返回 403/204 + 不写库 |
| AC-3 | Sensitive Filter 单测：模拟 PII / 账户 / 链上地址 payload 必须丢弃整条事件并打 metric |
| AC-4 | 6 个漏斗（Funnel-1..Funnel-6）查询脚本可在 fixture 上输出预期结果 |
| AC-5 | 4 类 cohort（Cohort-A..Cohort-D）留存计算脚本可在 fixture 上输出 D7 / D14 / D28 数字 |
| AC-6 | Pricing Intent UI 入口必须在 feature flag 关闭时不可见；开启时显示「意愿调查不扣款」文案（snapshot test） |
| AC-7 | 周报 CLI 可输出 evaluation/finclaw/runs/commercial-signal/<week>.yaml，结构符合 design §7 |
| AC-8 | Consent 撤回 e2e：写 5 条事件 → 撤回 → 48h tick → 验证 events + cohort 衍生全部删除（含 weekly report 中相关 user_anon_id 段） |
| AC-9 | 工程完成后 1 个工作日内回写 v1-governance-engineering-alignment.md M-C4 状态 + cs-instr 章节 |
5. 回写位置
- 实现 → 工程仓库
server/api/、server/agent/、server/jobs/、web/src/； - 测试 → 工程仓库
tests/； - 周报 → 治理库
evaluation/finclaw/runs/commercial-signal/； - 治理库 alignment / design Open Items 回写；
- Hand-off anchor →
handoff-anchors/v1-cs-instr-sub-2-engineering-impl.yaml； - 解除依赖：trial sub-2（事件采集就位 → trial 启动）、cs-instr sub-3（已有可评审的实现）。
6. 风险与裁决项
- 风险 E-1：事件量爆炸 → V1 阶段坚持轻量埋点（仅 §4 列出的事件，不允许自发扩张）；
- 风险 E-2：Pricing Intent 被用户误读为真实付费窗口 → UI 文案 + 上线前 Trial owner 必须做 1 轮真人 dry-run；
- 风险 E-3：事件包含偶发的 PII（例如用户在 value_articulation 中写出真名）→ Sensitive Filter 必须有「不通过则丢弃整条事件 + 打 metric」回退；
- 风险 E-4：weekly report 在小样本（Labs 内测 N=3）下指标失真 → 报表中必须强制显示 N 与置信度声明；
- 裁决项 J-1：撤回 SLA 是 48h vs 24h 由项目发起人 + Legal 决议（默认按 design 48h）。
7. 与其他 Sub-Packet 的关系
- 依赖：cs-instr sub-1、eng-impl sub-1 ProfileConsent、eng-impl sub-2 SensitiveInputHandling、eng-impl sub-3 TrainingAssetCandidate；
- 解除：trial sub-2、cs-instr sub-3；
- 共享文件：
server/agent/event_sink.py（与 ProfileConsent 实现共享 consent 查询入口）。