2026-08-19 14:38:46 +08:00
|
|
|
|
# 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，默认沿用现有>
|
2026-08-20 10:41:09 +08:00
|
|
|
|
【租户上下文】<本系统为多租户 SaaS，默认行级隔离；AI 生成代码须自动带租户过滤，业务参数不传 tenantId>
|
2026-08-19 14:38:46 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 2.2 AI 侧（开工前必须明确的默认值）
|
|
|
|
|
|
|
|
|
|
|
|
若用户未提供以下任一项，**按下述默认值执行并在交付说明中标注**，不得中断询问：
|
|
|
|
|
|
|
|
|
|
|
|
| 项 | 默认值 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| APP_NAME | 沿用后端 `bootstrap.yml` 现有 `spring.application.name`（老系统内新增功能）；新系统才要求用户确认 |
|
|
|
|
|
|
| 服务别名 | 沿用 `window.frameBaseConfig.backendServices` 中现有别名；新增服务需用户确认映射 |
|
|
|
|
|
|
| 数据库 | MySQL（建表脚本需与 sqlserver.sql 双份同步） |
|
|
|
|
|
|
| 页面归属 | 菜单结构按界面标题推断一级/二级菜单；无法推断时归入现有最近菜单 |
|
2026-08-20 10:41:09 +08:00
|
|
|
|
| 租户隔离 | 默认开启（行级）；AI 生成的数据访问自动叠加 `tenant_id` 过滤；不在 URL / 业务参数中传递 tenantId（来自 token，见 `coding-standards.md §9`） |
|
2026-08-19 14:38:46 +08:00
|
|
|
|
|
|
|
|
|
|
### 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：可引不可增 |
|
2026-08-20 10:41:09 +08:00
|
|
|
|
| 漏写租户过滤 → 跨租户数据泄露 | 数据访问必须带 `tenant_id`（JPA @Filter / Repository 基类 / 原生 SQL `?`），缓存 key 加 `tenant:{id}:` 前缀（§9） |
|
