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

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

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

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

一、开通结果是什么

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

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

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

二、收到项目名称后直接创建

业务项目只需要提供项目名称，例如“产品开发平台”。在 gongxiangp2 超级管理员面板中点击“新增接入项目”，填写项目名称后创建：

• 项目代码由通知中心自动生成；确有需要时才在高级设置中自定义。
• 项目密钥自动生成并在创建结果中展示。
• 不要求填写负责人、通知场景、通知量、跳转域名、收件人方式或花名清单。
• 花名在实际发送时由通知中心查询 gongxiangp2 花名册。

三、确认创建结果

创建完成后只需确认：

1. 项目名称正确，最终通知的可见正文顶部会显示 【项目名称】业务标题。
2. 项目代码没有与现有项目冲突。
3. 项目密钥只展示给需要接入的业务后端。
4. 现有项目的代码和密钥没有改变。

普通通知不需要 allowedHosts 或 recipients。只有项目明确启用钉钉 H5 免登时，才额外维护登录回调与回跳路径。

启用免登时才增加：

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

四、生成和保管项目密钥

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

要求：

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

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

五、变更生产配置

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

当管理员密钥与加密密钥都已配置时，通知项目配置的真实来源改为通知中心数据库；YYD_NOTIFICATION_PROJECTS_JSON 只用于把“数据库里还没有的项目”首次或补录导入，不能再把它当成每次发布都全量覆盖的真源。

执行顺序：

1. 确认目标服务器和目录是通知中心，而不是其他业务项目。
2. 备份通知中心 .env，备份文件包含密钥，权限必须限制为仅维护人可读。
3. 备份通知中心 SQLite 数据目录，确保现有通知记录可恢复。
4. 如需用环境变量补录，在 YYD_NOTIFICATION_PROJECTS_JSON 数组末尾新增项目；该数组中的既有项目只作为参考，不会覆盖数据库里已存在项目。
5. 再次解析 JSON，确认项目代码唯一、密钥长度合格。
6. 使用当前正式发布方式重新加载通知中心配置，或在管理员 API 调用 POST /admin/runtime/import-env 导入缺失项目后执行 POST /admin/runtime/refresh。
7. 验证本机 /health 与公网 /notification-center/health。
8. 验证现有项目仍可鉴权，新项目能够通过签名请求进入通知队列。

如果当前环境尚未配置管理员密钥或加密密钥，通知中心会继续使用 legacy YYD_NOTIFICATION_PROJECTS_JSON 内存模式提供旧 /v1/*；此时 /admin/* 不挂载，也不会做数据库项目导入和运行时刷新。

重要限制：

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

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

5.1 管理 API 开通与轮换

维护人现在也可以直接通过管理员 API 管理项目，而不是手工编辑环境变量。管理员鉴权与业务项目 HMAC 密钥分离：

• 主变量：YYD_NOTIFICATION_ADMIN_API_SECRET
• 兼容旧变量：YYD_NOTIFICATION_ADMIN_TOKEN
• 请求头：Authorization: Bearer <YYD_NOTIFICATION_ADMIN_API_SECRET>
• 可选：x-yyd-admin-actor: <操作人标识>，仅用于审计

常用接口：

• POST /admin/projects：创建项目，并只在本次响应返回新密钥和交付业务方的 env
• PATCH /admin/projects/:projectCode：修改名称、启停状态；免登项目可另行维护登录配置
• PUT /admin/projects/:projectCode/recipients：旧版项目级花名映射兼容接口，新接入不使用
• POST /admin/projects/:projectCode/rotate-secret：轮换项目密钥，并只在本次响应返回新密钥和 env
• POST /admin/projects/:projectCode/test：发一条测试通知
• GET /admin/deliveries / GET /admin/audits：查看投递与审计

关键规则：

• secret 和 env.YYD_NOTIFICATION_CENTER_PROJECT_SECRET 只在创建/轮换响应中展示一次，后续列表、详情、审计都不回显；
• 审计日志自动脱敏，不记录明文密钥、签名或 Bearer Token；
• /admin/* 请求体限制为 256 KB，超限返回结构化错误；
• /v1/notifications 等业务接口保持原有签名协议与返回语义。

六、安全交付三项配置

向业务项目后端维护人交付：

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 时传 recipientUserId；
只能提供花名时直接传准确的 recipientAlias；通知中心会查询 `gongxiangp2` 花名册，找不到对应钉钉 userId 时不会发送。
接入步骤请按《由壹点统一通知中心接入操作手册》执行。

七、首次联调怎么做

业务项目准备：

• 一名真实测试员工的钉钉 userId，或准确花名；
• 一个不会影响正常业务的低风险测试场景；
• 一个真实跳转地址；如启用免登，则该地址必须满足现有 HTTPS 登录流程；
• 稳定且不会与生产业务事件冲突的测试幂等键。

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

1. 创建接口返回 202 或同幂等请求返回 200。
2. 返回体包含投递 id。
3. 查询接口只能由当前项目查询该投递记录。
4. 最终状态进入 sent、unread、read 或给出明确 failed 原因。
5. 测试员工实际收到“由壹点”机器人单聊。
6. 钉钉聊天中的可见抬头包含正确项目名称和业务标题，业务正文没有重复抬头。
7. 提供跳转地址时收到 ActionCard，Markdown 正文格式和底部按钮正确，点击进入业务项目提交的页面；无地址时为无按钮的普通 Markdown 消息。样例见消息规范。
8. 相同幂等键重复请求不产生第二条消息。
9. 如使用花名，花名册中存在对应 userId 时能发送，找不到时明确返回 RECIPIENT_ALIAS_NOT_FOUND。

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

八、生产验收和交接记录

正式上线使用一名真实员工完成一次必要的通知与跳转验证。记录中不保存密钥，只保存：

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

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

九、密钥轮换或停用

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

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

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