多租户/多品牌消息系统中设计 Sender Profile…

在配置多租户、多品牌、多渠道消息发送系统时，用 Sender Profile 作为租户身份、渠道配置、继承资源、计费和凭据的运营边界，避免品牌、合规、限流和 webhook 归属混乱。

适用场景

解决思路

1. 当租户需要隔离时，推荐一个 Sent organization 下每个租户一个 Sender Profile；仅当租户真正共享同一品牌、发送资源、合规姿态、计费/限流预期和运营爆炸半径时才使用共享 profile。
2. 不要默认推荐池化架构；使用 references/multi-tenancy-patterns.md 明确做出隔离决策。
3. 认证模式二选一：profile 专用 API key 使用 `x-api-key`，凭据和限流上下文限定在 profile 范围，不要添加 `x-profile-id`；organization API key 代表子 profile 时使用 `x-api-key` 加 `x-profile-id: <profile UUID>`，organization 凭据可访问允许的子 profile，但限流仍在 organization 池中。
4. 只有 organization key 可以发送 `x-profile-id`；profile key 发送它会收到 `403`；组织外的 profile 返回 `404`；`X-Profile-Id` 可在限定范围的响应中回显。
5. `x-sender-id` 仅属于 v1/v2 遗留术语，不要用于 v3 认证或路由。
6. 当租户级凭据隔离和撤销是首要目标时选择 profile key；当集中控制的集成能保护更广的凭据并有意接受共享 organization 限流池时选择 organization-key scoping。
7. 使用 `POST /v3/profiles` 创建 profile，`name` 必填；可选区域包括：identity（`icon`、`description`、`short_name`）、sharing（`allow_contact_sharing`、`allow_template_sharing`）、inheritance（`inherit_contacts`、`inherit_templates`、`inherit_tcr_brand`、`inherit_tcr_campaign`）、billing（`billing_model`、`billing_contact` 和临时 `payment_details`）、专用 WABA 凭据（`whatsapp_business_account` 含 `waba_id`、可选 `phone_number_id` 和 `access_token`）、专用品牌（`brand.contact`、`brand.business`、`brand.compliance`）。
8. 不要添加单独的 brand 端点；专用品牌随 profile 一起创建；campaign 在 `/v3/profiles/{profileId}/campaigns` 下管理。
9. 继承规则：`inherit_tcr_brand: true` 表示 profile 使用 organization 的品牌，不能提交自己的 `brand` 对象；`inherit_tcr_campaign: true` 使继承的 campaign 对该 profile 只读；继承品牌且 `inherit_tcr_campaign: false` 是受支持的专用 campaign 模式；sharing 标志暴露 profile 的联系人/模板，inheritance 标志消费 organization 资源，要分别对待这两个方向。
10. 计费和号码引用：`billing_model` 当前支持 `profile`、`organization` 和 `profile_and_organization`；profile 或回退计费模型在不存在时要求 `billing_contact`；卡字段转发给支付处理器，不得记录或持久化。
11. Profile 更新可管理 `sending_phone_number_profile_id`、`sending_whatsapp_number_profile_id`、`sending_phone_number`、`whatsapp_phone_number` 和 `allow_number_change_during_onboarding`；分别建模引用 ID 和直接号码，并防止一个 profile 引用另一个 profile 时形成循环。
12. WABA 有三条不同路径：1）仪表盘中的 Organization Embedded Signup；2）organization 已有 WABA 后，子 profile 通过省略 `whatsapp_business_account` 继承；3）使用 `waba_id` 和 `access_token` 的专用 profile WABA，`phone_number_id` 可选。
13. 没有公开端点可启动 organization Embedded Signup；`POST /v3/profiles` 上的直接凭据不是“Embedded Signup 端点”；操作流程使用 `waba-embedded-signup`。
14. 10DLC 和 campaign：使用 profile 的 `brand` 对象创建专用品牌；在 `GET|POST /v3/profiles/{profileId}/campaigns` 和 `PUT|DELETE /v3/profiles/{profileId}/campaigns/{campaignId}` 管理 campaign；payload 和策略层使用 `sms-10dlc-registration`。
15. 使用 `POST /v3/profiles/{profileId}/complete` 和必填的 `webHookUrl` 完成 profile，例如 `{"webHookUrl": "https://example.com/webhooks/profile-complete", "sandbox": true}`。
16. 状态因表面而异：创建响应当前演示小写 `incomplete`；完成 `202` 表示处理已开始且不含最终状态；完成 `200` 当前演示已完成的 profile 为小写 `completed`；完成回调可报告 `COMPLETED`、`SUBMITTED` 或 `failed`；REST 指南和 OpenAPI 发布的 profile 状态集不同。
17. 不要断言封闭的 REST 枚举；保留未知字符串，并记录产生它们的端点/回调表面。
18. Webhook 归属：Sent 事件不包含你的应用租户 ID；发送前将返回的 `message_id` 与租户和 profile 一起持久化；通过该映射路由出站状态事件；对于入站消息，将接收号码/profile 资源映射到租户。
19. 建立映射：`message_id -> tenant_id, profile_id, logical_send_id, channel` 和 `receiving_number -> tenant_id, profile_id`。
20. 不要仅从 `account_id` 推断租户归属；多个租户 profile 可属于同一个 organization。
21. 设计检查清单：租户/品牌隔离决策明确；凭据模式和限流/爆炸半径已记录；sharing 和 inheritance 方向是有意为之；计费归属已命名；号码引用不能形成循环；WABA 路径是 organization signup、inheritance 或 dedicated credentials，而非臆造的混合；专用品牌/campaign 路径基于 profile；`message_id` 和入站号码映射支持 webhook 归属；容忍未知 profile 状态；租户 offboarding 撤销凭据、禁用发送、安全分离资源并保留审计证据。
22. 实现模式参考 references/sender-profile-data-model.md 和 references/profile-boundary-examples.md。

适用边界 · 注意事项

• 不要默认推荐池化架构；仅当租户真正共享同一品牌、发送资源、合规姿态、计费/限流预期和运营爆炸半径时才使用共享 profile。
• 不要使用 `x-sender-id` 进行 v3 认证或路由，它仅属于 v1/v2 遗留术语。
• 不要添加单独的 brand 端点，也不要把 `POST /v3/profiles` 上的直接凭据当作 Embedded Signup 端点。