saas-mbr/docs/agent-guide.md

AI 生成代码工作流与 Vibe Coding 协作指南

权威来源：docs/agent-guide.md · 编码约束详见 docs/coding-standards.md（本文件只讲"怎么协作"，不重复约束）

1. 适用场景

• 用户给界面 → AI 出代码：用户提供界面原型（图片/截图/链接/文字描述）与业务说明，AI 按 coding-standards.md §7 的步骤序列（S1~S10）生成前后端代码。
• 团队 Vibe Coding：所有成员（人 + AI）在统一约束下开发，产出可互审、可合并、可交付。

2. "界面 → 代码"提示词协议

2.1 用户侧（发起开发请求时的最小输入）

【业务说明】<要做什么，一两句话>
【界面】<原型图 / 截图 / 链接 / 界面文字描述>
【应用名】<APP_NAME，如 example>
【服务别名】<前端 URL 首段，如 sms>
【数据库】<MySQL / SQL Server，默认 MySQL>
【子系统编码】<public/data/data.js 的 currentSubsystem，默认沿用现有>

2.2 AI 侧（开工前必须明确的默认值）

若用户未提供以下任一项，按下述默认值执行并在交付说明中标注，不得中断询问：

项	默认值
APP_NAME	沿用后端 bootstrap.yml 现有 spring.application.name（老系统内新增功能）；新系统才要求用户确认
服务别名	沿用 window.frameBaseConfig.backendServices 中现有别名；新增服务需用户确认映射
数据库	MySQL（建表脚本需与 sqlserver.sql 双份同步）
页面归属	菜单结构按界面标题推断一级/二级菜单；无法推断时归入现有最近菜单

2.3 交付说明模板（AI 每次交付代码时附带）

## 本次交付
- 新增/修改文件清单（路径）
- 界面元素 → 实现映射（查询区/表格列/表单字段/操作按钮分别落在哪些代码位置）
- 接口清单（方法 + URL + 响应结构）
- SQL 变更（表/升级版本号）
## 已执行检查
- APP_NAME 四联检（①~④ 一致？）
- 统一响应体/异常码/分页契约/Excel 分支
- 未触碰 src/framework、pom、assembly
## 待办/风险
- 需后端菜单数据注册才能在前端菜单可见
- 需真机验证项（多数据源/定时任务/消息队列等）

3. 联调与验证纪律

• Mock 证据不足：多数据源路由、Kafka 消费、XXL-JOB 调度、Nacos 配置拉取、真实数据库迁移等必须真机验证，不得以 mock/静态检查作为完成依据。
• 前端 npm run dev + 后端启动的冒烟清单见 coding-standards.md §7.4。
• 交付前由 AI 执行 coding-standards.md §7.3 必须/禁止清单自检。

4. 团队协作约定

4.1 提交

• 遵循 Conventional Commits：type(scope): subject（feat/fix/docs/refactor/chore/test）。
• 提交粒度：一个功能/一个修复一个提交；先 git add 相关文件再提交，禁止 git add -A 夹带无关改动。
• 工作区单一 git 仓库（D:\workBuddySpace\member），docs/ 与两项目统一管理；发布以后端 *-bin.zip 为单元。

4.2 评审

• 评审重点：coding-standards.md §7.3 清单项、分层依赖方向（§5.1）、SQL 双份同步、命名规范。
• PR 描述按「变更内容 / 验证方式 / 影响范围」三段。

4.3 文档维护（单源化纪律）

• 共享约束只改 docs/coding-standards.md；仓库内 .project.agents 的 CONVENTIONS 只允许写指针 + 本仓库特有内容，禁止复制正文。
• 功能更新同步后端 src/main/resources/doc/升级日志.md。

4.4 框架演进

• 业务自研组件/工具泛用性高 → 提交框架负责人评审后纳入 src/framework/**，再在新业务中复用；不得长期只存在于业务内。
• 框架升级：不覆盖 public、vite.config.ts、src/subsystem。

5. 常见坑（高频返工点）

坑	规避
前端再取 .data（已自动解包）	编码时直接使用返回值
URL 首段与后端 context-path/Controller 路径不符 → 404	生成后端接口后回填前端 ts，路径逐字对齐
原生 SQL 字符串拼接 → 注入/报错	一律 ? 占位参数化
只改 mysql.sql 忘 sqlserver.sql	建表双份同步作为 S7 固定动作
新页面菜单不可见	后端菜单数据（sql/data/）注册 + dynamicRouter 匹配 url===path
手动拼主键/UUID	一律 DaoIdGenerator
新增 Util/Helper 类	遵循 §8.4：可引不可增