YouYiDianNotificationCenter/docs/通知中心新项目开通操作手册.md

通知中心新项目开通操作手册

使用对象：由壹点统一通知中心维护人。

本文不交给业务项目作为开发教程。业务项目请阅读统一通知中心接入操作手册。

一、开通结果是什么

新项目开通完成后，应同时满足：

1. 通知中心生产配置中存在唯一项目代码、项目名称、独立密钥和跳转域名白名单。
2. 通知中心服务已重新加载配置并通过健康检查。
3. 业务项目已通过安全渠道取得 URL、项目代码和项目密钥。
4. 业务项目使用一名真实员工完成首次通知和状态查询。
5. 项目密钥没有进入 Git、群聊、工单、共享文档、截图或普通日志。

仅把接入文档发给对方，不代表项目已经开通。

二、收到申请后先审核

业务项目应提交：

• 项目中文名称；
• 建议 projectCode；
• 业务负责人和技术负责人；
• 通知场景和触发条件；
• 收件人规则以及钉钉 userId 的数据来源；
• 日常和峰值通知量；
• 生产及测试跳转域名；
• 是否需要钉钉 H5 免登；
• 计划联调和上线日期。

审核门槛：

• projectCode 使用 2～40 位小写字母、数字、下划线或短横线，创建后不随中文名称改变。
• 项目名称简短并适合出现在 【项目名称】业务标题 中。
• 跳转域名为业务项目真实控制的 HTTPS 域名，不使用通配符，不包含协议、端口或路径。
• 收件人规则明确，不能使用姓名猜测钉钉 userId。
• 预计发送量在当前串行投递能力可承受范围内；峰值明显较大时先做容量评估。
• 普通通知默认不启用免登；只有点击后必须自动建立登录态时才审核免登配置。

信息不完整时退回补充，不先生成密钥。

三、确认项目身份没有冲突

修改生产配置前只读核对：

1. 当前 YYD_NOTIFICATION_PROJECTS_JSON 能正常解析为数组。
2. 数组中不存在相同 code。
3. 申请的域名没有误写为协议、路径或非标准端口。
4. 项目名称不会与已有项目造成用户无法分辨的通知来源。
5. 如启用免登，回调地址属于该项目的 allowedHosts，回跳路径前缀采用最小范围。

不要删除、重排或重新生成已有项目的密钥。新增项目时必须完整保留所有既有项目配置。

生产项目配置结构：

{
  "code": "product_development",
  "name": "产品开发",
  "secret": "由通知中心维护人生成的独立随机密钥",
  "allowedHosts": ["product.example.com"]
}

启用免登时才增加：

{
  "login": {
    "enabled": true,
    "callbackUrl": "https://product.example.com/api/dingtalk/broker-login",
    "allowedRedirectPathPrefixes": ["/tasks", "/dashboard"]
  }
}

四、生成和保管项目密钥

每个项目必须使用独立的高强度随机密钥，长度至少 24 个字符。推荐在受控服务器或受控工作站生成 32 字节以上的随机值。

要求：

• 不复用其他项目密钥；
• 不使用项目名、日期、手机号或人工编写的口令；
• 生成过程不进入共享终端日志；
• 只写入通知中心生产 .env 和业务项目后端的密钥配置；
• 临时交接文件必须放在已确认不受 Git 跟踪的位置，并限制读取权限；
• 业务项目确认保存后删除不再需要的临时明文副本。

业务项目不需要知道钉钉 AppKey、AppSecret、RobotCode，不得将这些凭证与项目密钥一起交付。

五、变更生产配置

这是生产写入操作，必须获得上线授权后执行。

执行顺序：

1. 确认目标服务器和目录是通知中心，而不是其他业务项目。
2. 备份通知中心 .env，备份文件包含密钥，权限必须限制为仅维护人可读。
3. 备份通知中心 SQLite 数据目录，确保现有通知记录可恢复。
4. 在 YYD_NOTIFICATION_PROJECTS_JSON 数组末尾新增项目，完整保留所有已有项目。
5. 再次解析 JSON，确认项目代码唯一、密钥长度合格、域名格式正确。
6. 使用当前正式发布方式重新加载通知中心配置。
7. 验证本机 /health 与公网 /notification-center/health。
8. 验证现有项目仍可鉴权，新项目能够通过签名请求进入通知队列。

重要限制：

• 日常发布使用仓库当前的 scripts/git-build-deploy.ps1 流程。
• 当前 scripts/deploy-material-host.sh 已具备“保留生产 .env 中未列出的已登记项目”逻辑；使用前仍需确认部署的是包含该保护逻辑的最新版本，并在发布后核对项目列表，不能使用更早的脚本副本。
• 不能为了新增项目而更换其他项目密钥。
• 不能把生产 .env、密钥或完整 docker compose config 输出保存到共享日志。

健康检查只证明服务和数据库可用，不证明新项目已经能够发送通知。仍需完成下一节的真实业务验收。

六、安全交付三项配置

向业务项目技术负责人交付：

YYD_NOTIFICATION_CENTER_URL=https://sc.jiansun.vip/notification-center
YYD_NOTIFICATION_PROJECT_CODE=实际项目代码
YYD_NOTIFICATION_PROJECT_SECRET=实际项目独立密钥

交付方式：

• URL 和项目代码可以写入接入记录；
• 项目密钥只通过双方认可的一对一安全渠道或密钥管理服务交付；
• 密钥与普通接入说明分开发送；
• 要求接收人在业务后端保存后确认，不在群内回复或引用密钥；
• 不替业务项目长期保存收件人名单。

可直接发送给业务项目负责人的非敏感说明：

你的项目已在由壹点统一通知中心完成登记。

公共地址：https://sc.jiansun.vip/notification-center
项目代码：<实际项目代码>
项目密钥：将通过单独的安全渠道发送

请把三项配置只放在业务后端。通知收件人的钉钉 userId 不是接入密钥，
应由你们的业务账号绑定或通讯录映射在每次发送时提供。
接入步骤请按《由壹点统一通知中心接入操作手册》执行。

七、首次联调怎么做

业务项目准备：

• 一名真实测试员工的钉钉 userId；
• 一个只在该员工和业务负责人之间可见的低风险测试场景；
• 一个属于项目白名单域名的 HTTPS 跳转地址；
• 稳定且不会与生产业务事件冲突的测试幂等键。

维护人与业务项目共同确认：

1. 创建接口返回 202 或同幂等请求返回 200。
2. 返回体包含投递 id。
3. 查询接口只能由当前项目查询该投递记录。
4. 最终状态进入 sent、unread、read 或给出明确 failed 原因。
5. 测试员工实际收到“由壹点”机器人单聊。
6. 标题包含正确项目名称。
7. 按钮只进入登记的项目域名和正确页面。
8. 相同幂等键重复请求不产生第二条消息。

首次真实发送只做能证明链路的一次必要调用；未获得真实发送授权时使用客户端示例测试，不向员工发送消息。

八、生产验收和交接记录

正式上线至少由两名真实员工完成通知与跳转验证。记录中不保存密钥，只保存：

项目名称：
projectCode：
allowedHosts：
业务负责人：
技术负责人：
通知中心维护人：
业务项目版本或 Git 提交：
通知中心版本或 Git 提交：
生产验证时间：
测试业务事件 ID：
通知中心投递 ID：
最终投递状态：
按钮跳转结果：
遗留问题：

完成后把统一通知中心接入操作手册、消息规范和错误与状态规范交给项目后续维护人。

九、密钥轮换或停用

密钥泄露、负责人变更或项目停用时，不要直接覆盖后结束：

1. 确认受影响的唯一项目代码和环境。
2. 说明轮换或停用窗口及对发送通知的影响。
3. 备份当前配置并准备恢复原密钥的回滚路径。
4. 新密钥只交付给该项目，不影响其他项目。
5. 协调通知中心与业务后端在约定窗口切换。
6. 使用一条有上限的真实通知验证新密钥。
7. 确认旧密钥失效，并删除不再需要的明文副本。

项目停用前保留必要的历史投递记录，不因停用项目直接删除数据库数据。