# Skill: 业务模块全流程交付 触发方式当用户说开发 XX 模块、实现 XX 功能、交付 XX 时按此流程推进。 --- ## 总体原则 - 每步有明确产出物编译或验证通过再进下一步 - 关键设计决策必须等用户确认不自行拍板 - 先咨询后实现先后端后前端 --- ## Step 1 — 咨询与设计不写代码 **目标**对齐需求边界和数据模型避免返工。 **产出物** - 候选方案对比表2-3 个方案标明取舍 - 数据模型草稿表名、核心字段、关联关系 - 接口清单Method Path 简要说明 **流程** 1. 分析业务需求列出候选技术方案 2. 给出推荐方案及理由 3. 提出需要用户决策的问题如是否需要软删除JSON 字段还是关联表 ⚠️ **等待用户确认**数据模型和接口设计确认后再进入 Step 2 **注意事项** - JSON 字段如 auth_config需要用 TableName(autoResultMap true) JacksonTypeHandler否则反序列化为 null - 高频写入的表如 health 记录不要继承 BaseEntity避免逻辑删除和审计字段的写放大 - 敏感字段如 api_key不能出现在任何响应 DTO 中用 authConfigured: boolean 代替 --- ## Step 2 — 更新 schema.sql **目标**数据库 DDL 与设计对齐。 **产出物** - hify-app/src/main/resources/db/schema.sql 新增表 DDL - hify-app/src/main/resources/db/schema-h2.sql H2 兼容版本JSON → CLOB **验证** bash # 用 mock profile 启动H2 会自动执行 schema-h2.sql java -jar hify-app/target/hify-app-0.0.1-SNAPSHOT.jar --spring.profiles.activemock # 访问 H2 控制台确认表已创建 open http://localhost:8080/h2-console **注意事项** - H2 不支持 JSON 类型必须用 CLOB 替代且两个 schema 文件都要维护 - 索引命名规范idx_{表名}_{字段名} - 所有外键在应用层维护不建数据库级外键约束 --- ## Step 3 — Entity Mapper **目标**ORM 层与数据库表对齐。 **产出物** - entity/XxxEntity.java继承 BaseEntity 或独立 - mapper/XxxMapper.java继承 BaseMapper复杂查询加 Select **验证** bash mvn clean install -DskipTests -pl hify-{module} -am **注意事项** - 有 JSON 字段的 Entity 必须加 TableName(autoResultMap true)字段上加 TableField(typeHandler JacksonTypeHandler.class) - MyBatis-Plus 3.5.9 分页插件在独立模块 mybatis-plus-jsqlparser缺少会导致 PaginationInnerInterceptor 找不到 - 自定义查询方法返回 OptionalT 时用 Select default 方法封装 --- ## Step 4 — DTO **目标**定义请求/响应对象隔离内部实体。 **产出物** - dto/XxxCreateRequest.javaValid 校验注解 - dto/XxxUpdateRequest.java - dto/XxxQueryRequest.java分页参数继承或包含 page/pageSize - dto/XxxDetailResponse.java静态工厂方法 from(entity, ...) **注意事项** - 响应 DTO 不能暴露 authConfig / password 等敏感字段 - 分页响应统一用 PageResult.of(list, total, page, pageSize)返回 ResultPageResultT - ⚠️ 不要让 PageResult 继承 Result否则序列化后 data 字段是数组total 在外层前端拦截器解包后丢失 total - PageResult 正确结构{ data: { list: [...], total: N, page: 1, pageSize: 20 } } --- ## Step 5 — Service业务逻辑 **目标**实现核心业务接口与实现分离。 **产出物** - service/XxxService.java接口 - service/impl/XxxServiceImpl.java实现 **流程** 1. CRUD 基础逻辑含唯一性校验、级联查询 2. 特殊业务逻辑如连通性测试、健康检查 3. 缓存注解Cacheable / CacheEvict **验证** bash mvn clean install -DskipTests -pl hify-{module} -am **注意事项** - 跨模块调用走 Service 接口不直接引用其他模块的 Mapper 或 Entity - 外部 HTTP 调用如 LLM API 连通性测试必须设超时用 LlmHttpClient 的 get(url, headers, testClient) - 健康检查定时任务加 ConditionalOnProperty(name hify.health-check.enabled, havingValue true, matchIfMissing true)mock profile 设为 false - 使用 Qualifier(llmExecutor) 注入线程池禁止 new Thread() 或默认线程池 --- ## Step 6 — Controller **目标**暴露 REST 接口只做参数校验和 Service 调用。 **产出物** - controller/XxxController.java **验证** bash mvn clean install -DskipTests java -jar hify-app/target/hify-app-0.0.1-SNAPSHOT.jar --spring.profiles.activemock 逐条跑 curl bash # 创建 curl -s -X POST http://localhost:8080/api/v1/{resource} \ -H Content-Type: application/json \ -d {...} | jq . # 列表 curl -s http://localhost:8080/api/v1/{resource}?page1pageSize10 | jq . # 详情 curl -s http://localhost:8080/api/v1/{resource}/1 | jq . # 更新 curl -s -X PUT http://localhost:8080/api/v1/{resource}/1 \ -H Content-Type: application/json \ -d {...} | jq . # 删除 curl -s -X DELETE http://localhost:8080/api/v1/{resource}/1 | jq . ⚠️ **等待用户确认**所有 curl 返回预期结果后再进入前端对接 **注意事项** - Spring Boot 3.2 必须在 maven-compiler-plugin 加 parameterstrue/parameters否则 PathVariable Long id 参数名无法识别导致 400 错误 - Controller 只调用 Service不写业务逻辑不直接操作 Mapper --- ## Step 7 — 前端 API 文件 **目标**封装后端接口定义 TypeScript 类型。 **产出物** - hify-web/src/api/{module}.ts **内容** - 请求/响应类型定义与后端 DTO 字段对齐 - 导出各接口方法使用 request.ts 的 get/post/put/del **注意事项** - 前端 request.ts 拦截器会自动解包 response.data.dataAPI 方法的返回类型直接写业务数据类型不需要包 ResultT - 列表接口返回类型写 PageResultT包含 list/total/page/pageSize对应后端解包后的 data 字段 --- ## Step 8 — 前端页面对接 **目标**替换 mock 数据接入真实 API。 **产出物** - 更新 views/{module}/XxxList.vue **流程** 1. 把 HifyTable 的 api prop 换成真实 API 方法 2. 表单提交换成 create/update API 3. 删除换成 delete API useConfirm 4. 按需添加操作按钮如测试连接 5. 按需添加状态列健康状态、关联数量等 **验证** bash # 确保后端已启动 java -jar hify-app/target/hify-app-0.0.1-SNAPSHOT.jar --spring.profiles.activemock # 启动前端 cd hify-web npm run dev 在浏览器 DevTools → Network 确认 - 请求打到了后端状态码 200非 ERR_CONNECTION_REFUSED - 响应 data.list 是数组data.total 是数字 - 表格有数据渲染或显示暂无数据而非一直转圈 ⚠️ 如果页面一直转圈先看 Network 标签确认请求状态码再排查后端是否启动 **注意事项** - Vite 代理/api → http://localhost:8080前端 baseURL 设为 /api后端路径 /api/v1/xxx 完整保留 - 前端 env.d.ts 不要写 declare module *.vue { ... }会覆盖 Volar 的真实类型推断导致组件 ref 的 expose 方法找不到 --- ## 常见坑速查 | 现象 | 原因 | 修复 | |------|------|------| | 页面一直转圈 | 后端未启动 / 请求 pending | 先看 Network 状态码 | | 列表有数据但 total0 不显示分页 | PageResult 继承 Result 导致 data 是数组total 在外层被拦截器丢弃 | PageResult 改为普通 POJOdata 包含 {list,total} | | PathVariable 400 错误 | 缺少 -parameters 编译参数 | pom.xml compiler plugin 加 parameterstrue/parameters | | JSON 字段反序列化 null | 缺少 autoResultMaptrue 或 JacksonTypeHandler | Entity 加注解 | | mock profile 启动失败 Bean 冲突 | RedisConfig 未排除 | 加 Profile(!mock) | | H2 启动报 SQL 错误 | schema.sql 用了 MySQL 专属语法如 JSON 类型 | 维护独立 schema-h2.sqlJSON→CLOB | | hify-common 改动后运行旧代码 | spring-boot:run 用了旧 jar | 改 hify-common 后必须先 mvn install |Claude Code 生成第一版再review 重点1、产出物是否明确不是“做需求分析”就完了而是“产出需求分析文档包含功能范围、数据模型 DDL、设计决策及理由”。Claude Code 需要知道做到什么程度算完。2、决策点是否标注数据模型设计完、后端做完准备做前端之前——这些是你要拍板的地方Skill 里要写“等待用户确认后再进入下一步”。3、踩过的坑有没有写进去比如Entity 的 JSON 字段必须用 TypeHandler、schema.sql 要同步更新、前端对接时要更新路由配置。这些是 13 讲实际踩过的写进 Skill 下次就不会重复踩。