# 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：可引不可增 |