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

新项目接入清单

A. 业务项目提交

• 项目有明确的业务负责人和技术负责人。
• projectCode 使用稳定的英文标识，创建后不会随产品中文名变化。
• 项目中文名称简短，适合显示在钉钉标题中。
• 已列出全部生产卡片跳转域名，且均为标准 HTTPS 域名。
• 已说明通知场景、触发条件、收件人和预计发送量。
• 已确认项目使用钉钉 userId 还是已登记花名；花名方式已提交准确清单。
• 已确认是否需要钉钉 H5 免登；普通通知默认不启用。

B. 通知中心配置

• 在 YYD_NOTIFICATION_PROJECTS_JSON 中新增独立项目配置。
• 为项目生成独立高强度随机 HMAC 密钥，不复用其他项目密钥。
• 通过安全渠道向业务项目交付项目代码、密钥和通知中心地址。
• 配置 allowedHosts，不使用通配符，不包含协议、端口或路径。
• 如使用花名，recipients 中每个花名只绑定一个已确认的在职员工 userId，且归一化后无重复。
• 如启用免登，配置精确 callbackUrl 和最小化的回跳路径前缀。
• 备份生产配置后再发布，并验证 /health。

C. 业务项目实现

• 三项连接配置仅存在于服务端环境变量。
• 签名使用实际发送的原始 JSON 正文。
• 签名路径不包含域名和反向代理前缀。
• 每次请求生成新 nonce，服务器时间已经同步。
• 幂等键包含事件、业务记录、收件人和消息版本。
• 多人通知逐人发送，并为每名收件人生成独立幂等键。
• 每条通知只提交 recipientUserId 或 recipientAlias 其中一个。
• 保存通知中心返回的投递 id。
• 202 不被当成“已送达”。
• 标题、正文和按钮符合 消息规范。
• 前端、日志和错误响应均不会暴露项目密钥。

D. 联调验证

• 项目负责人收到真实单聊。
• 至少另一名真实员工收到真实单聊。
• 无效钉钉 userId 能进入明确失败状态。
• 如使用花名，已登记花名能发送，未登记花名返回明确错误且不会发送。
• 重复发送同一请求不会产生第二条消息。
• 同一幂等键提交不同内容会被拒绝。
• 最终标题使用 【项目名称】业务主题，项目来源正确且醒目。
• 正文首行与最终标题一致，时间紧随其后，各字段之间有空行。
• 正文第一眼能看出业务主题、发生时间、核心内容和需要采取的动作。
• 按钮名称明确，跳转到正确的白名单域名。
• 能查询到 sent / unread / read / failed 状态。
• 如启用免登，票据只能消费一次，且业务项目重新核验本地账号和权限。

E. 上线与交接

• 已记录通知中心配置变更和业务项目接入版本。
• 已明确发生失败时由谁处理。
• 已配置必要的失败日志或监控，不记录敏感凭证。
• 已完成生产环境双人真实通知验证。
• 已把接入文档路径交给项目后续维护人员或开发 Agent。

只有 A～E 全部完成，才视为正式接入“由壹点”统一通知。

推荐交接入口：先阅读仓库根目录 README.md，再依次阅读本清单、接入指南和消息规范；不要从其他业务项目复制钉钉应用凭证或机器人直连代码。