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

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

> 使用对象：由壹点统一通知中心维护人。
>
> 本文不交给业务项目作为开发教程。业务项目请阅读[统一通知中心接入操作手册](./统一通知中心接入交接说明.md)。

## 一、开通结果是什么

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

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

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

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

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

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

## 三、确认创建结果

创建完成后只需确认：

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

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

启用免登时才增加：

```json
{
  "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` 等业务接口保持原有签名协议与返回语义。

## 六、安全交付三项配置

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

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

交付方式：

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

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

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

公共地址：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 消息。样例见[消息规范](./消息规范.md)。
8. 相同幂等键重复请求不产生第二条消息。
9. 如使用花名，花名册中存在对应 userId 时能发送，找不到时明确返回 `RECIPIENT_ALIAS_NOT_FOUND`。

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

## 八、生产验收和交接记录

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

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

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

## 九、密钥轮换或停用

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

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

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