YouYiDianNotificationCenter/docs/新项目接入清单.md

新项目接入清单

1. 开通项目

• 业务项目只提供一个可识别的项目名称。
• 通知中心自动生成项目代码和项目密钥。
• 将通知中心地址、项目代码、项目密钥通过安全渠道交给业务项目后端。

不需要提前填写负责人、通知场景、预计发送量、跳转域名、收件人方式或花名清单。

2. 业务项目配置

YYD_NOTIFICATION_CENTER_URL=https://sc.jiansun.vip/notification-center
YYD_NOTIFICATION_PROJECT_CODE=通知中心生成的项目代码
YYD_NOTIFICATION_PROJECT_SECRET=通知中心生成的项目密钥

• 三项配置只保存在业务后端，不进入前端或 Git。
• 请求使用项目密钥生成 HMAC 签名。
• 每次请求生成新 nonce，并使用稳定的 idempotencyKey 防止重复通知。

3. 每次发送

• recipientUserId 与 recipientAlias 二选一。
• 花名由通知中心从 gongxiangp2 花名册解析；找不到对应钉钉 userId 时不会推送。
• 业务项目只提交业务标题和正文，不重复抬头；通知中心在可见正文顶部固定显示 【项目名称】业务标题。
• 按钮文字和跳转地址均为可选，由业务项目决定；需要 ActionCard 时提供非空 actionUrl，无地址时发送无按钮的普通 Markdown 消息。
• 需要加粗、分段、引用等样式时，在 content 中使用 Markdown，参照消息规范的完整示例。
• 跳转地址按业务项目提交值使用，不限制 HTTPS、公网域名或项目域名白名单。
• 保存通知中心返回的投递 ID；202 只表示已接收，不表示已经送达。

4. 上线验证

• 正常收件人能够收到通知，聊天卡片可见抬头中的项目名称正确，正文格式和所选消息模板一致。
• 花名不存在时返回明确错误，且没有产生投递记录。
• 相同项目和幂等键不会产生重复通知。
• 一个项目不能查询另一个项目的投递记录。
• 需要跳转时，ActionCard 的按钮文字正确，点击能进入业务项目指定的 HTTP、HTTPS 或内网页面。
• 发送失败时能查询到明确状态和错误原因。

以上通过即可完成接入，不增加其它前置表单或审批门槛。