前端工程师操作手册

你是谁 / 本手册范围

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

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

前端角色的特殊之处：前端只消费文档（需求 / 合约 / 后台接口），不产出角色侧文档（不生成 docs/{project}/frontend/ 推到 GitLab，frontend 目录下的本地文件属于自用草稿）。因此 .docs.env 里用的是只读 GITLAB_DOCS_READ_TOKEN，不需要也不应该使用 GITLAB_DOCS_WRITE_TOKEN。唯一例外是 /daily-log 追成员日志到 content/manage/members/，那是写 docs-site 仓库自身的路径，用单独的 GITLAB_DOCS_SITE_WRITE_TOKEN，权限范围与项目文档互不冲突。

首次配置

1. 初始化 `.docs.env`

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

# 顶层（monorepo 迁移后统一单 token；前端是只读角色）
GITLAB_BASE_URL=https://gitlab.ironetwork.com
GITLAB_DOCS_BRANCH=main
GITLAB_DOCS_PROJECT_ID=213              # docs-site 仓库，所有项目共用
GITLAB_DOCS_READ_TOKEN=glpat-xxxx       # ⚠️ 只读 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=frontend
SKILLS_COMMON_TOKEN=glpat-xxxx
SKILLS_FRONTEND_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=frontend 会自动拉 skills-common + skills-frontend 两个仓库
完成后按提示重启 Claude Code

3. 自检前端必需字段

前端角色特有的必填项：顶层 GITLAB_DOCS_READ_TOKEN（拉需求 + 合约 ABI + 后台接口三类文档）+ 顶层 GITLAB_DOCS_SITE_WRITE_TOKEN（成员日志 /daily-log 写 content/manage/members/）+ 至少一个项目段的 TELEGRAM_CHAT_ID（部署 / 修 bug 通知）+ LSKY_BASE_URL / LSKY_TOKEN / LSKY_STRATEGY_ID（/bug-update 贴截图）。缺任一项，对应 skill 会在 HARD-GATE 阶段拦下来并指名缺什么。

再次强调：前端不写 docs/{project}/frontend/ 到 GitLab（本地文件自用），所以不需要 GITLAB_DOCS_WRITE_TOKEN；GITLAB_DOCS_READ_TOKEN 足够覆盖 /frontend-docs-pull 的所有拉取需求。若管理员错发了 write token，可直接当 read token 用（权限更宽），但不要反过来用 read token 推文档——/docs-push-gitlab 会 401，这是设计本身，不是 bug。

日常工作流

前端工程师从「接到 PM / 合约 / 后台三方文档」到「部署 + 通知 QA / PM」，下面 6 个场景覆盖 95% 的工作。

场景 A：拉最新需求 + 合约 + 后台接口文档

什么时候用：PM / 合约 / 后台任一角色 @你「文档已更新」，或准备开始新 feature 前。

触发命令：

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

关键输入：多项目时选要拉的项目；对 frontend/ 里「远程已更新」的文件，按编号或 all / skip 选是否覆盖本地。

产出结果：

content/{project}/requirements/ → .docs/{project}/requirements/（全量同步，只读）
content/{project}/contract/ → .docs/{project}/contract/（全量同步，只读，合约工程师维护的 ABI 文档）
content/{project}/backend/ → .docs/{project}/backend/（全量同步，只读，后台工程师维护的接口文档）
content/{project}/frontend/ → docs/{project}/frontend/（差异拉取，保护本地编辑；前端极少用这个目录，通常为空或仅有个人草稿）
输出摘要：📥 新增 N / 🔄 覆盖 M / ⏭️ 跳过 K / 仅本地 J，超过 7 天未更新的需求标 ⚠️⚠️ 提醒跟 PM / 合约 / 后台对齐

场景 B：制定技术计划

什么时候用：新 feature 开工前，先把页面结构、数据流、合约调用点想清楚再写代码。

触发命令：

/dev-frontend-plan <feature-id>
# 示例：/dev-frontend-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 + frontend.md，列出「业务概念 → ABI 实体」候选映射表，按置信度标 ✅/⚠️/❓，你逐行确认
需求澄清多轮追问：AI 对页面路由 / 数据状态 / 交互细节 / 合约交互 / 兼容性列出模糊点一次性问，你逐条回答或 跳过
进 superpowers:brainstorming（React / Next.js / TypeScript 严格模式 / Tailwind / 组件复用优先 / 链上读取强制走 src/state/multicall/hooks.ts）→ superpowers:writing-plans。financial 类故事若计划缺精度展示或边界值表单校验任务，会触发 Hard Gate 拒写

产出结果：

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

场景 C：按计划实现前端

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

触发命令：

/dev-frontend <feature-id>

关键输入：

HARD-GATE：docs/plans/{FEAT-ID}-frontend-plan.md 存在 + 当前分支是 feature/fe-xxx，任一不满足直接停
skill 把 plan 的每个任务用 TaskCreate 拆成独立 task，无依赖的 2+ 个任务会并行派 subagent（如不同页面的组件、不同模块的 UI）
严格按计划执行，不做计划外改动；后台未就绪时用 mock 数据兜底，写 // TODO: 替换为真实 API 调用 — 等待 BE-{task-id} 完成
每完成一个组件先检查 src/components/ 是否有可复用的 Button / Modal / Form / Input，不重复造轮子
每完成一个子任务立即调 /git-commit 提交（scope 自动识别为 frontend，从分支名提取 Task: FE-001）
Step 6 自测：npx eslint --fix <变更文件> + npx tsc --noEmit 必须全绿
Step 7 并行派 superpowers:code-reviewer 做安全扫描（XSS / dangerouslySetInnerHTML / Token 存储 / 路由鉴权）+ React 最佳实践审查（props 类型完整 / useEffect 依赖 / loading-error 状态），BLOCK 级问题（XSS 漏洞、Token 泄露）必须修完再继续

产出结果：src/pages/** + src/components/** + 每任务 commit + 计划 frontmatter status: completed。

场景 D：生成部署脚本

什么时候用：首次把前端构建产物部署到测试服 / 正式服前，生成标准化 scripts/deploy.sh。每个环境生成一次。

触发命令：

/deploy-gen

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

产出结果：scripts/deploy.sh（已 chmod +x），含备份到 /data/prod_backup_{timestamp} → 拷贝新版本 → 重载 nginx → Telegram 发送「开始 / 成功 / 失败」三种状态通知。后续部署先跑 npm run build 出产物，再 bash scripts/deploy.sh。scripts/ 建议加 .gitignore（BOT_TOKEN / CHAT_ID 是明文，见 common.md 与 backend.md FAQ 同款处理）。

场景 E：部署完成后通知

什么时候用：部署到测试服 / 正式服后，告知 QA 可以进场测试、PM 可以看到最新效果。

触发命令：

/notify
# 选场景 7「前端已部署」

关键输入：选环境（测试服 / 正式服）、填访问 URL、简要说明本次部署内容（新页面 / 样式调整 / 合约接入变更）。

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

场景 F：修 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                                  # 选场景 10「前端 Bug 已修复」

注意：/docs-push-gitlab 写 bugs.md 是前端唯一需要写 GitLab 项目文档的场合，这里走的仍然是 GITLAB_DOCS_WRITE_TOKEN——但如果你是只读账号，管理员会在签发 token 时预留 bugs/ 路径的写权限（/bug-update 场景特例）。若推 bugs 时 401，联系管理员检查 token 路径 scope。

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

状态追踪你这边能做什么：`/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，前端本地最常用三个：

命令	前端的典型使用场景
`/frontend-docs-pull`	每天开工先跑一次；PM / 合约 / 后台任一角色 TG 群通知后也跑一次。三类跨角色文档全量同步，确保本地 `.docs/` 是最新
`/notify`	部署完选场景 7「前端已部署」；修完 bug 选场景 10。不发 `/notify` 也会自动追日志，但 QA / PM 看不到更新
`/git-branch` + `/git-commit`	`/dev-frontend-plan` 已自动建 `feature/fe-*` 分支，小改动可再手动 `/git-branch` 起新分支；每个子任务后 `/git-commit` 预览 Conventional Commits 信息

常见问题 / 故障排查

Q1：/frontend-docs-pull 冲突怎么办（本地 docs/{project}/frontend/ 有改动）？

frontend/ 是同角色差异拉取：skill 比对本地 mtime 和远程 committed_date，远程更新时才问你覆盖。前端极少在 frontend/ 里放东西（那是历史约定位置，通常空着），如果你的确在里面写了个人草稿，按编号选择性覆盖（如 1,3）或输入 skip 全部跳过。另外三类目录（requirements/ / contract/ / backend/）是全量同步只读的，不存在冲突，直接覆盖本地 .docs/ 即可——本来就不应该手动编辑 .docs/ 下的任何文件。

Q2：只读 token 能拉不能推，是不是配置错了？

不是。前端角色设计上就是只读消费者：拉需求 / 合约 / 后台接口做开发，不产出跨角色文档。如果 /docs-push-gitlab 报 401，先看你要推的路径——若推的是 bugs/（bug 相关），让管理员给你的 token 补 bugs/* 写权限；若推的是 frontend/（想把本地 frontend 文档推上去），这是不被支持的操作，本地草稿保留本地即可，或者把有价值的内容贴给 PM 由 PM 走 requirements/ 路径补充。不要反过来跟管理员要 full GITLAB_DOCS_WRITE_TOKEN——那会破坏角色边界。

Q3：联调时发现合约 ABI 和本地 .docs/ 不一致（方法签名对不上 / 事件参数变了）？

一定是合约工程师更新了 ABI 但你没重拉。流程：

跑 /frontend-docs-pull 刷新 .docs/{project}/contract/（全量同步会覆盖本地旧版本）
看 .docs/{project}/contract/更新说明.md 顶部条目，确认本次变更了什么
对照 plan 文档「合约接口引用」章节，若签名 / 参数变了，改 dev-frontend-plan 重新生成（少量变更直接在代码里改即可）
若合约工程师还没把最新 ABI 推 GitLab，让他跑 /contract-abi-docs + /docs-push-gitlab 选 2. contract，再 /notify 场景 3 通知你

Q4：部署成功但打开 URL 还是老版本，CDN 缓存没刷？

两种原因：一、scripts/deploy.sh 没带缓存清理步骤（nginx 只重载配置，静态资源默认浏览器会拿本地缓存）——强制刷新用 cmd+shift+R；二、Cloudflare / CDN 层没刷，登录 CF 控制台手动 purge 或在 deploy.sh 里加 curl -X POST ...purge_cache。长期方案：构建产物文件名带 hash（Next.js 默认就带），HTML 不带 hash 但设 Cache-Control: no-cache，静态 JS / CSS 设 max-age=31536000, immutable。

Q5：多项目切换时 .docs/ 混乱（昨天跑 pay-fi，今天跑 fomo-pad）？

.docs/ 按项目分目录（.docs/pay-fi/ vs .docs/fomo-pad/），互不影响。切换项目时：

/frontend-docs-pull --project fomo-pad 把 fomo-pad 的文档拉到 .docs/fomo-pad/（不会动 pay-fi）
/dev-frontend-plan FEAT-xxx 会根据当前 .docs.env 里的 [project] 段询问你要哪个项目，选 fomo-pad
仓库层面保持各项目独立 git repo，feature/fe-* 序号按仓库独立递增

若懒得每次指定，日常直接 /frontend-docs-pull --all 一次全量拉，代价是几秒钟网络请求，换来不用记住项目名。

前端工程师操作手册

前端工程师操作手册

你是谁 / 本手册范围

首次配置

1. 初始化 .docs.env

2. 安装前端角色 skill 包

3. 自检前端必需字段

日常工作流

场景 A：拉最新需求 + 合约 + 后台接口文档

场景 B：制定技术计划

场景 C：按计划实现前端

场景 D：生成部署脚本

场景 E：部署完成后通知

场景 F：修 bug 并通知

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

通用 skill 速查

常见问题 / 故障排查

相关文档链接

1. 初始化 `.docs.env`

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