开发工作流（按真实项目走的完整流程）

本页职责：用你真实项目（科技专题服务系统 = kj-frontend 前端 + SpringBlade_GKX_Base 后端）演示"一个功能从需求到上线该怎么走"，每步给真实路径 + 真实命令 + 可照抄 prompt，照着干即可。话术背后的"为什么"见大佬操作手册。

0 · 先把真实栈记牢（下面所有命令/路径都基于它）

前端 kj-frontend（读源码确认）：

技术：Vue3 + ant-design-vue + Pinia(pinia-plugin-persist) + axios + vue-router；构建 vite，测试 vitest，E2E playwright。
关键目录：页面 src/views/（现有 Home / Login / strategy / system）、接口 src/api/module/*.ts、axios 封装 src/api/http.ts、状态 src/stores/*.ts、路由 src/router/、组件 src/components/。
脚本：pnpm dev（起 :8000）、pnpm type-check（vue-tsc --noEmit）、pnpm test（vitest run）、pnpm e2e（playwright）、pnpm build、pnpm lint。
接口约定（src/api/http.ts）：不设 baseURL，路径自带 /api → vite proxy → Gateway；业务请求头加 Blade-Auth: Bearer <token> + Tenant-Id: 000000；响应统一解 R<T>（code 200 取 data），401/403 清 token 跳登录。
登录已实现：src/api/module/auth.ts（POST /api/blade-auth/token，grantType=password，密码 SM2 加密）+ src/views/Login/index.vue + src/stores/user.ts。

后端 SpringBlade_GKX_Base：

模块：blade-auth（8100）/ blade-gateway（15800）/ blade-service（含 blade-desk/blade-log/blade-system）/ blade-service-api（含 blade-system-api 等）/ blade-common / blade-ops。
中间件：Nacos 8848（namespace c2dfc042-c385-49fa-aae1-b5e37216d204）/ Redis 3379。
科技专题业务模块还没建：要新建 blade-service/blade-kj-<业务> + 配套 blade-service-api/blade-kj-<业务>-api（仿 blade-system 与 blade-system-api 的配对）。

环境分工：Claude 在容器里规划 + 写 + 容器内验证（type-check / compile / 单测）；起 Nacos·Redis·微服务、部署，交 Mac 上的 codex（容器碰不到你的 Mac）。

工具默认：找代码用 serena（别 Read 整文件再 grep）；查第三方库/框架写法用 context7（别信模型记忆）；浏览器验证用 playwright / chrome-devtools；看设计稿用 figma。

通用五步骨架（每个流程都套）：Explore（plan 模式只读）→ Plan（看计划再批）→ Implement（写 + 自验证）→ Verify（分清谁验）→ Commit（不 push）。

一、完整功能开发流程（从需求到上线 · 端到端）

以一个真实会发生的需求为例：新增"专题项目"管理（列表 + 新增/编辑）。换成别的业务，把 <专题项目 / kj-project> 替换即可。

阶段 1 · 需求澄清（大功能先出 SPEC，别直接开干）

text

我要在科技专题系统加"专题项目管理"（增删改查 + 分页 + 按状态筛选）。
用 AskUserQuestion 采访我：字段有哪些、权限/多租户怎么算、和现有 blade-system 用户/部门的关系、
前端要不要导出。别问显而易见的。问完写一份 SPEC.md（含接口契约草案和验收标准）。

确认 SPEC 后新开一个干净会话实现（上下文专注）。依据：手册 A3（采访-1）。

阶段 2 · 后端：新建 blade-kj-project 微服务

Explore（Shift+Tab 进 plan，只读）——拿 blade-system 当范例：

text

先只读不改。@SpringBlade_GKX_Base/AGENTS.md。
参考 blade-service/blade-system 的写法（Controller/Service/ServiceImpl/Entity/Mapper/Wrapper、
继承 BladeController、统一 R<T> 返回、IPage 分页、@PreAuth 鉴权注解），
用 serena 看它一个完整 CRUD（如某 Controller）的结构。
告诉我：新建 blade-service/blade-kj-project + blade-service-api/blade-kj-project-api 要哪些类、
Nacos 注册名怎么取、Gateway 路由怎么加、建表 SQL。先别写。

Plan——让它列模块结构 + 改动清单 + 风险，你批（Ctrl+G 可改）。

Implement——仿 blade-system 实现，容器内验编译：

text

按计划实现 blade-kj-project（实体/Mapper/Service/Controller，CRUD + 分页 + 按状态筛选），
DTO/VO 放 blade-kj-project-api。
写完在容器内跑：mvn -pl blade-service/blade-kj-project -am compile，修到过；
能加单测就加。起服务我交给 codex，你别在这起。

查框架写法别靠记忆：用 context7 查 SpringBlade 4.7 / Spring Boot 3.2 的 <某注解/配置> 怎么写。

Verify（起服务交 codex）：

text

给 codex 的提示词：在 Mac 上把 blade-kj-project 注册到 Nacos(8848, namespace c2dfc042-...)、
在 Gateway(15800) 加路由，起来后用 curl 打一个分页接口确认通。
下面是已在容器内 compile 通过的改动：<贴文件清单/diff>。

怎么算过：容器内 mvn compile + 单测过；codex 回报注册成功、curl 接口通。

阶段 3 · 前端：建页面 + 接口 + 路由

Explore（plan）——拿现有页和接口封装当范例：

text

先只读不改。我要在 kj-frontend 加"专题项目管理"页（ant-design-vue 的 Table + 搜索 + 新增/编辑 Modal）。
参考 @src/views/system/ 现有页怎么写、@src/api/module/ 现有接口模块怎么定义、@src/api/http.ts 的请求/响应拦截器。
给我要新增的文件清单和路由/菜单怎么加。先别写。

Plan——确认要建：src/views/kj-project/（列表 + 表单组件）、src/api/module/kjProject.ts、src/router/ 加路由、菜单项；如需跨页状态再加 src/stores/。

Implement：

text

按计划实现：
- src/api/module/kjProject.ts：仿 src/api/module/auth.ts 的写法，用 http 调 /api/blade-kj-project/...（page/detail/submit/remove）；
- src/views/kj-project/：用 ant-design-vue 的 Table/Form/Modal/分页，按 system 页的风格；
- 路由 + 菜单加上。
写完跑 pnpm type-check（vue-tsc）修到 0 error；给 kjProject.ts 的请求封装补一个 vitest 单测；
列出我要在 :8000 手点的步骤。

Verify：
bash
```
pnpm dev      # :8000，登录后进"专题项目管理"点一遍：列表/分页/筛选/新增/编辑/删除
```
或让它自验：用 playwright 打开 http://localhost:8000，登录后进专题项目管理页，新增一条再截图给我。

怎么算过：type-check 0 error + 你在 :8000 实际增删改查通 + 请求带对了 Blade-Auth/Tenant-Id（F12 Network 看）。

阶段 4 · 前后端联调

text

@kj-frontend/AGENTS.md @SpringBlade_GKX_Base/AGENTS.md
联调专题项目管理：前端按 blade-kj-project 的契约对接，注意：
请求要带 Blade-Auth: Bearer + Tenant-Id: 000000（http.ts 已统一处理），
响应是 R<T>（code 200 取 data），401 会自动跳登录。两边以这两份 AGENTS.md 为准。

真实接口联调（连真实 Gateway）这步在 Mac 上，由 codex 起服务、你在 :8000 点。

阶段 5 · 测试 + 代码审查 + 安全审查

text

1) 前端 pnpm test、后端 mvn -pl blade-service/blade-kj-project test，把结果贴我；
2) 用 /code-review 审这次 git diff，只报影响正确性/契约的问题，给文件:行号 + 证据；
3) 这是新接口、涉及鉴权，跑 /security-review 查权限校验/越权/SQL 注入。

依据：手册 A2（验证-3/4）。

阶段 6 · 提交 + 部署

text

commit，写清楚改了什么（前端 + 后端）；先别 push，我来推。

部署给 codex（附"已验证"证据）：

text

给 codex：前端已 pnpm build 通过、后端 mvn compile + 单测通过。请在 Mac 上：
前端 build 产物部署到 <目标>，后端重启 blade-kj-project，部署后访问 <地址> 确认正常，回我结果。

这就是一个功能的完整闭环。下面是日常更高频的单点场景。

二、日常单点场景（高频，照抄即用）

修 Bug · 前端（UI / 交互）

开局一次给齐"现象 + 怀疑层 + 复现"：

text

现象：<具体现象>。我的怀疑：<哪一层，如某状态没复位/在途请求没取消>。先复现确认，再定位，给根因再改。

让它打日志/抓请求，你触发贴回控制台：

text

在 <解析/发请求/状态切换> 各加一行 console.log，我去 :8000 触发一次把控制台贴回来。

serena 定位：用 serena find_symbol 找 <状态变量/函数>，find_referencing_symbols 看所有引用。
改根因 + 加回归测试；失败 2 次就 /clear 带更尖线索重开，别"还是不行"循环。

坑：UI 渲染容器测不了，必须你贴真实 console/截图。 真实例子：角标"输出完变问号"（该先抓网络请求）、"历史会话切换没反应"（根因是要等推荐问题接口返回）。依据：手册 A1（工作流-先复现 / 团队-排错 / 纠偏-2）。

修 Bug · 后端（接口 / 服务）

text

接口 <path> 报这个错：<贴完整 stack trace>。
用 serena 顺调用链定位到出错的类和方法，先给根因判断，别急着改。

容器内 mvn -pl <模块> test 复现（或写失败用例）→ 改根因（别 try-catch 吞掉）→ 重跑测试。
涉及真实 Nacos/Redis/DB 的环境问题，交 codex 在 Mac 复现。

坑：不给堆栈它只能猜；分清"代码 bug"（容器内修）和"环境问题"（交 codex）。依据：手册 A1（症状-1 / 团队-排错）。

还原设计稿（figma → 前端）

text

用 figma 读 <figma 链接>：get_design_context 拿结构变量、get_screenshot 拿截图。
按它实现 <页面>：组件库 ant-design-vue，主色 <#值>，间距按 <栅格>。先实现别自由发挥。
实现后用 playwright 截图，和设计稿逐项对比差异（间距/颜色/字号/对齐）再修。

坑：别用"高级/眼前一亮"形容词——永远给参照物（figma 源稿 / 原型 URL / 截图）+ 具体色值栅格。 真实例子：你有 design-assets/...fig + figma MCP + netlify 原型站。依据：手册 A4（视觉-1 / 团队-设计）。

重构 / 大改造（如路由重构、换栈）

必走 plan 模式：先只读不改。我要做 <改造>。列影响面 + 可分批的小步迁移清单 + 每步怎么验 + 风险和回滚。我看完再批。
小步 + 每步可测：按第 1 步实现，跑 type-check/测试，绿了停下等我确认再下一步。
风险大的试验用 claude --worktree <分支名> 隔离。

坑：大改最怕盲放行——一句"我同意"曾驱动 151 次改动；先看文件清单/计划再批。 真实例子：kj-frontend 从 Umi 换 Vue3（旧版归档 kj-frontend-umi-bak）、规划中的业务路由重构。依据：手册 A5（计划-1/2 / 工作流-小步重构）。

接手 / 理解陌生代码

text

先只读不改。给我 @<目录，如 kj-frontend/src/views/system/> 的架构总览：
组织方式、状态和请求怎么走、对接哪些接口。再 trace 一条关键链路，用 serena 列文件:函数。先别改。

范围大就 use a subagent to investigate <X>，只回报结论和涉及文件。坑：别"找一下 XX"让它满仓库 Read（真实那次 Read 19 次还没准）——开局 @目录/@文件、用 serena。依据：手册 A6（具体-3 / 委派-隔离）。

部署 / 运维（codex 接力）

容器内先验：pnpm type-check && pnpm build（前端）/ mvn -pl <模块> compile && test（后端）。
给 codex"已验证 + 明确步骤"的提示词，附 diff，别让它拿没验过的代码。
push / 改仓库需你确认。

坑：别把"验证"也外包——容器内能验的先验掉。 真实例子：丹小美腾讯云迁移；"你没改仓库吧"那次——动仓库前先确认。依据：手册 A7（验证-1）。

线上事故 / 安全事件

先止血定范围：线上 <现象>。先判断影响范围、是否还在持续，先别动手改。
喂现场：这是现场 <日志/截图/可疑文件>。定位是什么、怎么进来的、根因在哪。
处置（Mac 部分交 codex）+ 验证已解除 + 写处置记录到 docs/<事件>.md。

真实例子：丹小美 layui.js 被劫持——查文件是否在仓库、属主权限、签名命中，最后写了"安全处置-layui劫持.md"。依据：手册 A1（团队-排错 / 团队-截图）。

三、小场景速查

场景	照抄做法
写测试	`看 @<现有测试> 的框架/断言风格，照它给 <目标> 写 vitest（前端）/ mvn 单测（后端）；再帮我找漏的边界：空值/异常/越权/分页边界`
查框架/库写法	`用 context7 查 Vue 3 / ant-design-vue / SpringBlade 4.7 的 <X>`，别信记忆
找代码	`用 serena find_symbol / find_referencing_symbols 找 <符号>`，别 Read 整文件
文档整改（docs/）	先 `@docs/AGENTS.md` 读规矩；`.bak-` 不动；`docs/scripts/*.py` 不搬出 docs/
依赖/环境炸了	先判"代码 vs 环境"；rollup 二进制缺失用 `/workspace` 全新 pnpm store 重装（已验证可修）
模型选择	见决策指南 · 用哪个模型档位（日常 Sonnet / 架构 opusplan / subagent Haiku）
跨多次接续	`claude --continue` / `--resume`，给会话起名当分支

分享给团队：阶段流程 + 各场景 prompt 都可直接复用；把"专题项目"换成你的业务、把真实例子换成团队自己的即可。配套：话术 → 大佬操作手册；改掉坏习惯 → 学习路径。

开发工作流（按真实项目走的完整流程） ​

0 · 先把真实栈记牢（下面所有命令/路径都基于它） ​

一、完整功能开发流程（从需求到上线 · 端到端） ​

阶段 1 · 需求澄清（大功能先出 SPEC，别直接开干） ​

阶段 2 · 后端：新建 blade-kj-project 微服务 ​

阶段 3 · 前端：建页面 + 接口 + 路由 ​

阶段 4 · 前后端联调 ​

阶段 5 · 测试 + 代码审查 + 安全审查 ​

阶段 6 · 提交 + 部署 ​

二、日常单点场景（高频，照抄即用） ​

修 Bug · 前端（UI / 交互） ​

修 Bug · 后端（接口 / 服务） ​

还原设计稿（figma → 前端） ​

重构 / 大改造（如路由重构、换栈） ​

接手 / 理解陌生代码 ​

部署 / 运维（codex 接力） ​

线上事故 / 安全事件 ​

三、小场景速查 ​

开发工作流（按真实项目走的完整流程）

0 · 先把真实栈记牢（下面所有命令/路径都基于它）

一、完整功能开发流程（从需求到上线 · 端到端）

阶段 1 · 需求澄清（大功能先出 SPEC，别直接开干）

阶段 2 · 后端：新建 blade-kj-project 微服务

阶段 3 · 前端：建页面 + 接口 + 路由

阶段 4 · 前后端联调

阶段 5 · 测试 + 代码审查 + 安全审查

阶段 6 · 提交 + 部署

二、日常单点场景（高频，照抄即用）

修 Bug · 前端（UI / 交互）

修 Bug · 后端（接口 / 服务）

还原设计稿（figma → 前端）

重构 / 大改造（如路由重构、换栈）

接手 / 理解陌生代码

部署 / 运维（codex 接力）

线上事故 / 安全事件

三、小场景速查