后台工程师操作手册

你是谁 / 本手册范围

你是后台工程师：接 PM 推过来的后台业务需求 + 合约工程师推过来的 ABI 文档，制定技术方案 → 写服务端代码 → 生成「一接口一文件」的标准接口文档给前端 / QA 用 → 部署到测试服 / 正式服 → 通知团队。本手册只讲后台专属的 skill 流程。全员通用的环境准备、/git-*、/docs-push-gitlab、/notify、/bug-*、/deploy-gen 等请先读 common.md，再回这里看专属流程。

本手册假设你已按 common.md 跑过 /docs-init + /skills-install。

首次配置

1. 初始化 `.docs.env`

跑 /docs-init，把管理员通过安全渠道发给你的配置整段粘贴进 .docs.env。管理员会用 /member-token-gen 为你签发。后台角色必须包含以下字段（完整字段表见 common.md 的「环境准备」章节）：

# 顶层（monorepo 迁移后统一单 token）
GITLAB_BASE_URL=https://gitlab.ironetwork.com
GITLAB_DOCS_BRANCH=main
GITLAB_DOCS_PROJECT_ID=213              # docs-site 仓库，所有项目共用
GITLAB_DOCS_WRITE_TOKEN=glpat-xxxx      # 读 + 写 content/{project}/**（单 token 覆盖全项目）

# daily-log 写 content/manage/** 用
DOCS_SITE_PROJECT_ID=213
GITLAB_DOCS_SITE_WRITE_TOKEN=glpat-xxxx

# 你的身份
MEMBER_NAME=your_name
MEMBER_TG=@your_tg

# Skills 安装用
SKILLS_ROLE=backend
SKILLS_COMMON_TOKEN=glpat-xxxx
SKILLS_BACKEND_TOKEN=glpat-xxxx

# 图床（bug-update 贴截图用）
LSKY_BASE_URL=https://bugs.ironetwork.com
LSKY_TOKEN=xxx

# Telegram（全局一个 bot token；chat id 按项目）
TELEGRAM_BOT_TOKEN=bot123:xxx

# 按项目一段
[pay-fi]
GITLAB_PROJECT_ID=101                   # notify 场景引用
TELEGRAM_CHAT_ID=-100...
LSKY_STRATEGY_ID=1

[fomo-pad]
GITLAB_PROJECT_ID=102
TELEGRAM_CHAT_ID=-100...
LSKY_STRATEGY_ID=2

2. 安装后台角色 skill 包

/skills-install

SKILLS_ROLE=backend 会自动拉 skills-common + skills-backend 两个仓库
完成后按提示重启 Claude Code

3. 自检后台必需字段

后台角色特有的必填项：顶层 GITLAB_DOCS_WRITE_TOKEN（拉需求 + 拉合约 ABI + 推 backend/ 接口文档）+ 至少一个项目段的 TELEGRAM_CHAT_ID（部署 / 修 bug 通知）+ LSKY_BASE_URL / LSKY_TOKEN / LSKY_STRATEGY_ID（/bug-update 贴截图）。缺任一项，对应 skill 会在 HARD-GATE 阶段拦下来并指名缺什么。

日常工作流

后台工程师从「接到 PM 推的需求 + 合约工程师推的 ABI」到「部署 + 通知前端 / QA」，下面 7 个场景覆盖 95% 的工作。

场景 A：拉最新需求 + 合约文档

什么时候用：PM 群里 @你「需求文档已更新」，或合约工程师 @你「合约文档已更新」，或准备开始新 feature 前。

触发命令：

/backend-docs-pull                    # 交互选项目
/backend-docs-pull --project pay-fi   # 指定单项目
/backend-docs-pull --all              # 全量同步所有 [project] 段

关键输入：多项目时选要拉的项目；对 backend/ 里「远程已更新」的文件，按编号或 all / skip 选是否覆盖本地（保护你尚未推送的编辑）。

产出结果：

content/{project}/requirements/ → .docs/{project}/requirements/（全量同步，只读，本地有远端没有的自动删除）
content/{project}/contract/ → .docs/{project}/contract/（全量同步，只读，合约工程师维护的 ABI 文档）
content/{project}/backend/ → docs/{project}/backend/（差异拉取，本地新建未推的保留不动，远程更新会逐文件询问覆盖）
输出摘要：📥 新增 N / 🔄 覆盖 M / ⏭️ 跳过 K / 仅本地 J，超过 7 天未更新的需求标 ⚠️⚠️ 提醒跟 PM / 合约工程师对齐

场景 B：制定技术计划

什么时候用：新 feature 开工前，先把数据模型、接口设计、合约联动想清楚再动代码。

触发命令：

/dev-backend-plan <feature-id>
# 示例：/dev-backend-plan FEAT-001-remove-tier-system

关键输入：

Harness 约束继承：skill 先扫该 FEAT 下的 story-*.md，读 formula_type / harness_gates_passed / 公式 / 边界值 / 业务异常。若 harness_gates_passed: false 直接拦下，回去让 PM 跑 /req-split 补审阅
跨文档术语对齐：若业务语义涉及合约（监听事件 / 调方法），skill 自动扫 .docs/{PROJECT}/contract/ + story.md + backend.md，列出「需求描述 → ABI 实体」候选映射表，按置信度标 ✅/⚠️/❓，你逐行确认
技术栈自动检测：识别 pom.xml / go.mod / composer.json / package.json / requirements.txt，确认 Java Spring Boot / Go / PHP / Node / Python
需求澄清多轮追问：AI 对数据模型、业务逻辑、接口设计、权限、合约联动列出模糊点一次性问，你逐条回答或 跳过
进 superpowers:brainstorming → superpowers:writing-plans，financial 类故事若计划缺精度处理或边界值校验任务，会触发 Hard Gate 拒写

产出结果：

docs/plans/{FEAT-ID}-backend-plan.md     # frontmatter 含 role/status/branch，含「合约接口引用」章节
feature/be-{seq}-{desc}                  # 从 develop 切出的分支，已 push -u origin

场景 C：按计划实现后台

什么时候用：/dev-backend-plan 已落地，准备写代码。

触发命令：

/dev-backend <feature-id>

关键输入：

HARD-GATE：docs/plans/{FEAT-ID}-backend-plan.md 存在 + 当前分支是 feature/be-xxx，任一不满足直接停
skill 把 plan 的每个任务用 TaskCreate 拆成独立 task，无依赖的 2+ 个任务会并行派 subagent
严格按计划执行，不做计划外改动；依赖合约接口未就绪时用 mock 兜底，写 // TODO: 替换为实际合约调用
错误码格式 1_100_xxx_xxx，msg 为 i18n 识别码
每完成一个子任务立即调 /git-commit 提交（scope 自动识别为 backend，从分支名提取 Task: BE-001）
Step 6 自测：按技术栈跑编译 + 测试（Java Maven → mvn clean compile -q + mvn test -q；Go → go build ./... + go test ./...；Node → npm run build + npm test；PHP → composer install + php artisan test）
Step 7 并行派 superpowers:code-reviewer 做安全审查（SQL 注入 / 认证绕过 / 敏感数据泄露 / 输入校验）+ 按语言做代码审查，BLOCK 级问题必须修完再继续

产出结果：服务端代码文件 + 每任务 commit + 计划 frontmatter status: completed。

场景 D：生成接口文档

什么时候用：接口实现完成，通过自测后，生成「一接口一文件」的标准文档供前端 / QA 用。

触发命令：

/backend-docs-gen

关键输入：

多项目时先选目标项目
接口类型二选一：1. 后端接口（管理员侧，X-Admin-Token 鉴权） / 2. 前端接口（用户侧，X-Token 或无需鉴权）
子模块名称必须纯中文（如 认证 / 管理员账号 / 代币管理 / 经纪商认证），不允许混 broker 这类英文
接口来源二选一：1. 描述模式（你口述字段，AI 辅助生成） / 2. 代码粘贴模式（贴 api/v1/*.go 的 Req/Res + internal/cmd/cmd.go 的路由注册，AI 按 GoFrame 规则解析完整路径）
基础路径前缀（如 /api/admin）必须确认；路由解析完 AI 会列表让你逐条确认 方法 / 完整路径 / 鉴权

产出结果：

docs/backend/
├── 后端接口/{子模块（中文）}/{接口名}（{路由标识}）.md
├── 前端接口/{子模块（中文）}/{接口名}（{路由标识}）.md
└── 更新说明.md                          # 项目级版本清单，新条目插文件头

每个接口 md 文件含 6 个必填区块：标题 → 方法 + 路径 + 鉴权标签 → 描述 + 触发场景 → 📥 请求参数（含位置列）→ 📤 响应字段（嵌套展开为 data.xxx.yyy）→ ⚠️ 失败说明 → <details> 完整示例 → 📋 版本历史。完成后接 /docs-push-gitlab 选 3. backend → 推到 docs-site content/{project}/backend/。

场景 E：生成部署脚本

什么时候用：首次把服务部署到测试服 / 正式服前，生成标准化的 scripts/deploy.sh（含备份旧版、通知 Telegram、重载服务）。每个环境生成一次。

触发命令：

/deploy-gen

关键输入：填 5 个变量 — SERVICE（服务名，如 eni-api-test） / BOT_TOKEN（Telegram Bot Token） / CHAT_ID（目标群 chat id） / REMOTE_PATH（部署目标路径，如 /data/prod/api） / DEPLOYMENT_DIR（构建产物路径，默认 /tmp/deployment_build）。

产出结果：scripts/deploy.sh（已 chmod +x），含备份到 /data/prod_backup_{timestamp} → 拷贝新版本 → Telegram 发送「开始 / 成功 / 失败」三种状态通知。后续部署用 bash scripts/deploy.sh 即可。敏感字段（BOT_TOKEN / CHAT_ID）直接写在脚本里，scripts/ 必须加 .gitignore 或用环境变量读取（见 FAQ Q3）。

场景 F：部署完成后通知

什么时候用：部署到测试服 / 正式服后，告知前端和 QA 接口可以联调了。

触发命令：

/notify
# 选场景 6「后台已部署」

关键输入：选环境（测试服 / 正式服）、填服务访问地址、简要说明本次部署内容（接口变更 / 数据库迁移 / 配置调整）。

产出结果：Telegram 通知自动 @mention frontend / qa，消息结尾附 @hi_sam1369 兜底；同时在 content/manage/members/{MEMBER_NAME}/{YYYY-MM-DD}.md 追加日志条目。

场景 G：修 bug 并通知

什么时候用：QA / PM 报了后台 bug，你修完并重新部署后走标准三步。

触发命令：

/bug-update BUG-XXX status=in-progress   # 接单
# ... 改代码、跑测试、重部署 ...
/bug-update BUG-XXX status=fixed         # 自动填 fixer=MEMBER_NAME
/docs-push-gitlab                        # 选 5. bugs
/notify                                  # 选场景 9「后台 Bug 已修复」

产出结果：content/{project}/bugs/bugs.md 按严重度 + 状态重排，stats.md 刷新个人贡献，Telegram 通知 @mention frontend / qa。

状态追踪你这边能做什么：`/story-status`

/story-status FEAT-002 US-01           # 单个
/story-status FEAT-002 US-01,US-03     # 多个（同一 FEAT）
/story-status FEAT-002 all             # 该 FEAT 涉及你的所有 story

你（后台）的权限： 推进自己的「后台」列 未开始 → 已完成（写完代码、跑完测试、commit 完即可推）。仅前进、不回退、不旁路。 改错了找管理员通过 GitLab Web UI 修。详细列结构和首次启用说明见 common.md 状态追踪节。

查看进度： team-docs.pages.dev/{project}/status

通用 skill 速查

全员通用 skill 的详细规则看 common.md，后台本地最常用三个：

命令	后台的典型使用场景
`/docs-push-gitlab`	生成完接口文档推 `3. backend`；修完 bug 推 `5. bugs`。并发冲突检测会提示 72h 内他人修改，逐文件 y/n
`/notify`	推完 `backend/` 选场景 2「接口文档已更新」；部署完选场景 6；修完 bug 选场景 9。不发 `/notify` 也会自动追日志，但前端 / QA 看不到更新
`/git-branch` + `/git-commit`	`/dev-backend-plan` 已自动建 `feature/be-*` 分支，小改动可再手动 `/git-branch` 起新分支；每个子任务后 `/git-commit` 预览 Conventional Commits 信息

常见问题 / 故障排查

Q1：/backend-docs-pull 提示 backend/ 里有冲突文件，不敢覆盖？

backend/ 是同角色差异拉取：skill 比对本地 mtime 和远程 committed_date，远程更新时才问你覆盖。你可以按编号选择性覆盖（如 1,3），或输入 skip 全部跳过。跳过的文件不会丢，依然在远程；本地继续编辑 → /docs-push-gitlab 时并发冲突检查会再拦一次让你决定。若确实是多人同时改同一个接口文档，建议先 skip 看 diff，整合后再推。

Q2：接口文档命名冲突怎么避免（一接口一文件）？

命名规则固定：{接口名}（{路由标识}）.md，路由标识取完整路径去掉 /api/ 和模块前缀（/admin/ / /broker/）、省略路径参数后 / 换成 -。例如 /api/admin/account/list → account-list → 管理员账号列表（account-list）.md。冲突典型场景：两个子模块都有 list 接口（如 用户列表 和 订单列表）— 不会冲突，因为子模块目录不同（用户管理/用户列表（list）.md vs 订单管理/订单列表（list）.md）。同一子模块内 list 重复才会冲突，这时接口名要加业务定语区分（如 在售项目列表 vs 历史项目列表）。

Q3：/deploy-gen 生成的脚本里 BOT_TOKEN / CHAT_ID 是明文，怎么管理敏感字段？

两种做法任选：一、把 scripts/deploy.sh 加进 .gitignore（简单粗暴，但新机器上要重跑 /deploy-gen）；二、改成从环境变量读（BOT_TOKEN="${BOT_TOKEN:-}" + REMOTE_PATH="${REMOTE_PATH:-}"），.env 留在服务器不进 git，脚本 source ./.env 启动。团队惯例走方式一：scripts/deploy.sh 不进仓库，每台部署机单独跑 /deploy-gen。

Q4：本地 mvn test / go test / npm test 通过，但 CI 挂？

三个常见原因：一、CI 里 JDK / Go / Node 版本跟本地不一致（本地 Node 22，CI 跑 node:18-alpine，Astro 6 要 >= 22）；二、CI 没配数据库 / Redis 服务容器，本地有现成依赖；三、.env 没提交（敏感值走 CI 变量而不是 .env），本地 application-dev.yml 能读 CI 读不到。先在 Docker 里复现 CI 镜像干净跑一遍排除环境污染。Bug 修复流程：把缺失的依赖补到 .gitlab-ci.yml services / variables，commit 后触发 pipeline 重跑。

Q5：合约工程师更新了合约地址 / ABI，后台怎么同步？

合约工程师推完 ABI 文档会发 /notify 场景 3「合约文档已更新」。你收到通知后：

跑 /backend-docs-pull 拉最新 .docs/{project}/contract/（全量同步覆盖本地）
看 .docs/{project}/contract/更新说明.md 顶部条目，确认本次变更（新增方法 / 事件参数变了 / 合约地址变了）
若只是地址变更，改项目的合约地址配置（application.yml 或 config.yaml），重启服务即可；若是 ABI 签名变更，需要改 Decoder / 调用代码，按「修改已有功能」起一条 feature/be-{seq}-update-{contract}-abi 分支走完整流程
验证完推 /docs-push-gitlab + /notify 场景 6 告知前端 / QA

后台工程师操作手册

后台工程师操作手册

你是谁 / 本手册范围

首次配置

1. 初始化 .docs.env

2. 安装后台角色 skill 包

3. 自检后台必需字段

日常工作流

场景 A：拉最新需求 + 合约文档

场景 B：制定技术计划

场景 C：按计划实现后台

场景 D：生成接口文档

场景 E：生成部署脚本

场景 F：部署完成后通知

场景 G：修 bug 并通知

状态追踪你这边能做什么：/story-status

通用 skill 速查

常见问题 / 故障排查

相关文档链接

1. 初始化 `.docs.env`

状态追踪你这边能做什么：`/story-status`