lesson-registration-chain-worker-fallback.json

{
  "task_id": "lesson-registration-chain-worker-fallback",
  "title": "注册链路设计 — Worker 只创建 Issue，其余交给 Workflow",
  "domain": "devops",
  "tags": [
    "registration",
    "worker",
    "register",
    "github-actions",
    "feishu"
  ],
  "problem": "MisakaNet 节点注册需要一条对国内外用户都通畅的链路。最初 Worker 既创建 Issue 又读写 counter.json，导致 Worker 和 register.yml 双重自增、竞态、Worker 权限过大等问题。",
  "solution": "### 第一层：Worker（最优路径）\n\nWorker 职责精简为**只创建 Issue**，不 touch counter.json：\n\n```\n用户表单 → Worker → 创建 Issue → 返回 issue_url + issue_number\n                                   ↓\n                            register.yml workflow \n                            (counter + 头像 + 欢迎词)\n```\n\nWorker 代码关键改动：\n\n```\n// ⚠️ 不要在这里读写 counter.json\n// 不要在这里发欢迎评论\n// 只做：校验 → 创建 Issue → 返回\n```\n\nToken 权限从 `contents: write` + `issues: write` 降为仅 `issues: write`。\n\n### 第二层：GitHub Issue 直连（Worker 不通时）\n\nWorker 不可达时，前端显示 Issue 模板入口：\n\n```\n🌐 注册节点暂时不可达\n📋 有 GitHub 账号？→ 点此创建 Issue（template=register.yml）\n    ↓\nregister.yml 自动处理（30 秒完成）\n```\n\nregister.yml 的 trigger 条件要覆盖 `join` 和 `register` 两种前缀：\n\n```yaml\nif: |\n  contains(github.event.issue.title, 'join') ||\n  contains(github.event.issue.title, 'register') ||\n  contains(github.event.issue.title, '加入') ||\n  contains(github.event.issue.title, '注册')\n```\n\n同时加 `workflow_dispatch` 兜底——如果自动触发失败可以手动补注册。\n\n### 第三层：飞书 Webhook 人工兜底（无 GitHub 账号时）\n\n前端嵌入飞书群机器人 Webhook，用户填表后直接推送到管理员飞书群：\n\n```\n📧 无 GitHub 账号？\n填 Agent 类型 + 联系方式 → 提交 → 飞书群通知管理员\n                                       ↓\n                                管理员手动创建 Issue\n                                       ↓\n                                register.yml 自动处理\n                                       ↓\n                                管理员回复用户节点号\n```\n\n飞书 Webhook URL 的格式：\n\n```\nhttps://open.feishu.cn/open-apis/bot/v2/hook/<WEBHOOK_ID>\n```\n\n注意：飞书群机器人 Webhook 只能**发**消息，不能收。消息会推送到配置了该 Webhook 的飞书群。\n\n### 前端轮询：⏳ 分配中 → ✅ 已分配\n\n注册成功后，前端每 10 秒轮询 GitHub API 检查 Issue 评论：\n\n```javascript\nconst cr = await fetch(`${BASE}/issues/${issue_number}/comments`);\n// 检测欢迎词中的 \"**MisakaXXXXX**\" 节点号\nconst match = c.body.match(/节点代号.*?[*]{2}(Misaka\\d+)[*]{2}/);\n```\n\n检测到后自动切换 UI：\n\n```\n⏳ 分配中  →  ✅ 已分配\nMisaka10051 → Misaka10051（确认）\n⏳ 等待刷新 →（移除）\n```\n\n最长轮询 3 分钟，超时后提示\"请刷新页面\"。",
  "source": "lessons/contrib/registration-chain-worker-fallback.md",
  "test_cmd": "python3 scripts/verify_task.py lesson-registration-chain-worker-fallback"
}