sender-profile-architect

Sender Profile 架构设计师

Sender Profile 是用于界定租户身份、渠道配置、继承资源、计费和凭证的操作边界。如果边界划分不当会混淆品牌、合规态势、速率限制影响范围或 webhook 归属，请在配置前使用此技能。

对于实时 MCP Profile 生命周期操作，请使用 sent-profile-provisioning；对于市场要求，请使用 sent-compliance。对于普通账户工具，MCP 可通过可选的 profileId 选择执行操作的 Profile，但仅适用于组织授权。sender_profiles.* 工具针对目标 id 操作，并会拒绝执行操作的 profileId。下方的 REST 标头不是 MCP 参数。

推荐的租户模型

当租户需要隔离时，建议使用一个 Sent 组织，并为每个租户设置一个 Sender Profile。只有当租户确实共用同一品牌、发送方资源、合规态势、计费／速率限制预期以及运营影响范围时，才适合共用一个 Profile。

不要默认建议使用池化架构。请使用 references/multi-tenancy-patterns.md 明确做出隔离决策。

身份验证模式

Sent v3 支持以下两种模式：

模式	标头	影响范围
Profile 专用 API 密钥	x-api-key	凭证和速率限制上下文仅适用于该 Profile。不要添加 x-profile-id。
代表子 Profile 操作的组织 API 密钥	x-api-key 加 x-profile-id: <profile UUID>	组织凭证可访问获准的子 Profile；速率限制仍属于组织池。

只有组织密钥可以发送 x-profile-id。Profile 密钥发送该标头时会收到 403。不属于该组织的 Profile 会返回 404。作用域受限的响应中可能会回显 X-Profile-Id。

x-sender-id 仅是旧版 v1/v2 术语。请勿将其用于 v3 身份验证或路由。

如果租户级凭证隔离和撤销是首要考虑因素，请选择 Profile 密钥。如果集成由中心统一控制，能够妥善保护权限更广的凭证，并有意接受共用组织速率限制池，请选择组织密钥作用域。

Profile 创建模型

使用 POST /v3/profiles 创建。name 为必填项。目前可选的配置包括：

• 身份信息：icon、description、short_name；
• 共享设置：allow_contact_sharing、allow_template_sharing；
• 继承设置：inherit_contacts、inherit_templates、inherit_tcr_brand、inherit_tcr_campaign；
• 计费设置：billing_model、billing_contact 和临时的 payment_details；
• 专用 WABA 凭证：使用 waba_id、可选的 phone_number_id 和 access_token 配置 whatsapp_business_account；
• 专属品牌：brand.contact、brand.business 和 brand.compliance。

不要添加单独的品牌端点。创建 Profile 时会一并创建专属品牌；在 /v3/profiles/{profileId}/campaigns 下管理 campaign。

继承规则

• inherit_tcr_brand: true 表示 Profile 使用组织的品牌，且不能提交自己的 brand 对象。
• inherit_tcr_campaign: true 会使继承的 campaign 对该 Profile 变为只读。
• 继承品牌且 inherit_tcr_campaign: false 是受支持的专属 campaign 模式。
• 共享标志会开放 Profile 的联系人／模板；继承标志则会使用组织资源。请分别处理这两个方向。

计费和号码引用

billing_model 目前支持 profile、organization 和 profile_and_organization。如果没有现成的 billing_contact，则 Profile 级或回退计费模式需要提供 billing_contact。卡片字段会转发给支付处理方，不得记录日志或持久化。

Profile 更新可管理 sending_phone_number_profile_id、sending_whatsapp_number_profile_id、sending_phone_number、whatsapp_phone_number 和 allow_number_change_during_onboarding。请将模型引用 ID 和直接号码分开处理，并在 Profile 之间相互引用时防止形成循环。

WABA 选项

有三种不同的路径：

1. 在控制面板中进行组织嵌入式注册。
2. 组织拥有 WABA 后，省略 whatsapp_business_account，以继承子配置文件。
3. 使用 waba_id 和 access_token 配置专用配置文件 WABA；phone_number_id 为可选项。

没有用于启动组织嵌入式注册的公共端点。POST /v3/profiles 中的直接凭据并不是“嵌入式注册端点”。请使用 waba-embedded-signup 完成实际操作流程。

10DLC 和营销活动

使用配置文件 brand 对象来配置专属品牌。在以下端点管理营销活动：

• GET|POST /v3/profiles/{profileId}/campaigns
• PUT|DELETE /v3/profiles/{profileId}/campaigns/{campaignId}

使用 sms-10dlc-registration 处理负载和策略层。

完成和状态处理

使用 POST /v3/profiles/{profileId}/complete 完成配置文件，并提供必需的 webHookUrl：

{
  "webHookUrl": "https://example.com/webhooks/profile-complete",
  "sandbox": true
}

状态因接口而异：

• 创建响应目前显示小写的 incomplete。
• 完成操作返回 202，表示处理已开始，且不包含最终状态。
• 对于已完成的配置文件，完成操作返回 200 时目前显示小写的 completed。
• 完成回调可能会报告 COMPLETED、SUBMITTED 或 failed。
• REST 指南和 OpenAPI 发布的配置文件状态集合不同。

不要假定 REST 状态枚举是封闭的。保留未知字符串，并记录产生该状态的端点或回调接口。

Webhook 归属关系

已发送事件不包含你的应用租户 ID。发送前，请将返回的 message_id 与租户和配置文件一并持久化。通过此映射路由出站状态事件。对于入站消息，请将接收号码或配置文件资源映射到相应租户。

message_id -> tenant_id, profile_id, logical_send_id, channel
receiving_number -> tenant_id, profile_id

不要仅根据 account_id 推断租户归属。多个租户配置文件可以属于同一个组织。

设计检查清单

• 已明确租户／品牌隔离决策。
• 已记录凭据模式以及速率限制／影响范围。
• 共享和继承的方向符合预期。
• 已指定账单归属方。
• 号码引用不会形成循环。
• WABA 路径为组织注册、继承或专用凭据，而不是臆造的混合模式。
• 专属品牌／营销活动采用基于配置文件的路径。
• message_id 和入站号码映射可支持 Webhook 归属识别。
• 能够容忍未知的配置文件状态。
• 租户停用时会撤销凭据、禁用发送、安全地分离资源，并保留审计证据。

实现模式请参见 references/sender-profile-data-model.md 和 references/profile-boundary-examples.md。