FinClaw V1 Sub-Packet: Commercial Signal — Schema 设计与冻结
状态：Pending / 等待 sub-1 ProfileConsent 完成（提供 consent gate 字段） 日期：2026-05-16 Lane：Engineering Owner：FinClaw Controller 分发，AI Coding Agent 执行 Parent Packet：v1-commercial-signal-instrumentation-task-packet.md
1. 目标
落地 v1-commercial-signal-instrumentation-design.md §3 Event Schema 与 §4 Event Catalog（7 类事件）的代码级 schema：
- 定义 dataclass / pydantic schema（统一 envelope + 7 类 payload）；
- 与 v1-product-object-and-schema-design.md §8 ProfileConsent / §9 SensitiveInputHandling / §11 TrainingAssetCandidate 的字段对齐；
- 写 schema 单测（结构、枚举、允许字段、disallowed PII patterns）；
- 不实现埋点写入逻辑（由 sub-2 承接）；
- 不实现漏斗 / 留存 / 周报（由 sub-2 承接）。
本 sub-packet 是 cs-instr 切片中的 schema-only 阶段，目的是先把数据契约冻结。
2. 允许读取
见 frontmatter must_read / reference_only。
3. 禁止范围
- 不写
event_sink.write/ API endpoint（sub-2 负责）； - 不写漏斗 / cohort 查询脚本（sub-2 负责）；
- 不接入第三方分析 SaaS（design §10 Out of Scope）；
- 不在 schema 中允许任何凭证 / 卡号 / 助记词字段；
- 不允许新增 design §4 之外的事件类型（任何新增必须先回写 design Open Items）。
4. Acceptance Criteria
| AC ID | 验收项 |
|---|---|
| AC-1 | 7 类事件 schema dataclass / pydantic 实现完整，与 design §3+§4 一一对应 |
| AC-2 | envelope 字段（event_id / event_type / event_ts / user_anon_id / session_id / cohort / consent_for_trial_data / source_surface / app_version / payload）100% 必填校验 |
| AC-3 | payload 中含 PII pattern（手机/邮箱/身份证/卡号/链上地址/助记词）的样例数据被 schema validator 拒绝 |
| AC-4 | catalog yaml 列出全部 7 类事件 + 字段 + 允许的 source_surface |
| AC-5 | schema 单测覆盖：合法 payload 通过、非法 payload 被拒、unknown event_type 被拒 |
| AC-6 | 与 eng-impl sub-1 ProfileConsent 字段对齐（consent_for_trial_data / consent_for_training_pool / withdrawal_at） |
| AC-7 | hand-off anchor 输出包含 schema 文件 hash 供 sub-2 比对 |
5. 回写位置
- Schema 实现 → 工程仓库
server/schemas/； - Schema 测试 → 工程仓库
tests/； - 治理库 design §11 Open Items 如有变更 → 回写 v1-commercial-signal-instrumentation-design.md；
- Hand-off anchor →
handoff-anchors/v1-cs-instr-sub-1-schema-design.yaml； - 解除依赖：cs-instr sub-2（schema 已冻结，可开始埋点 + 查询实现）、cs-instr sub-3（schema 已冻结，可开始隐私评审）。
6. 风险与裁决项
- 风险 S-1：design §3 字段在 trial 期间需要扩展 → 必须先回写 design Open Items 再加字段（不允许 schema 与 design 漂移）；
- 风险 S-2：与 ProfileConsent 字段命名冲突 → 以 eng-impl sub-1 实现为准；
- 裁决项 J-1：是否使用 dataclass / pydantic / msgspec 由 AI Agent 在工程仓库已有约定基础上选择，并在 hand-off anchor 中说明。
7. 与其他 Sub-Packet 的关系
- 依赖：v1-eng-impl-sub-1-profile-consent.md（consent 字段先就绪）；
- 解除：cs-instr sub-2（埋点实现）、cs-instr sub-3（隐私评审）；
- 共享文件：
server/schemas/commercial_events.py（sub-2 会引用）。