From 775e07549509ee0fa2a55319e4d121cc69f0d2dc Mon Sep 17 00:00:00 2001 From: zhoulei Date: Wed, 19 Aug 2026 14:38:46 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BB=BA=E7=AB=8B=E5=9B=A2=E9=98=9F?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E4=B8=AD=E5=BF=83=EF=BC=88=E5=89=8D=E5=90=8E?= =?UTF-8?q?=E7=AB=AF=E5=BC=80=E5=8F=91=E7=BA=A6=E6=9D=9F=E8=A7=84=E8=8C=83?= =?UTF-8?q?=E4=B8=8E=E6=9E=B6=E6=9E=84=E6=96=87=E6=A1=A3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 37 ++++ docs/README.md | 32 +++ docs/agent-guide.md | 90 ++++++++ docs/architecture.md | 81 +++++++ docs/coding-standards.md | 460 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 700 insertions(+) create mode 100644 .gitignore create mode 100644 docs/README.md create mode 100644 docs/agent-guide.md create mode 100644 docs/architecture.md create mode 100644 docs/coding-standards.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d1a0075 --- /dev/null +++ b/.gitignore @@ -0,0 +1,37 @@ +# --- WorkBuddy 项目数据（不入库） --- +.workbuddy/ + +# --- Node / Vite 前端 --- +node_modules/ +dist/ +dist-ssr/ +*.local +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# --- Java / Maven 后端 --- +target/ +*.class +*.jar +*.war +!.mvn/wrapper/maven-wrapper.jar +.mvn/timing.properties +maven-wrapper.jar + +# --- IDE --- +.idea/ +*.iml +.vscode/ +*.swp +.settings/ +.classpath +.project + +# --- OS --- +.DS_Store +Thumbs.db + +# --- 构建产物/发布包 --- +*-bin.zip +*.log diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..f9fd7f1 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,32 @@ +# 团队文档中心（docs/） + +> 前后端统一架构、编码标准、接口契约与 agent 协作边界的**单一权威来源**。 +> 对应仓库：`abacus-static-framework`（Vue 前端底座）· `abacus.springboot.example`（Spring Boot 微服务模板） + +## 文档导航 + +| 文档 | 内容 | 读者 | +|---|---|---| +| **coding-standards.md** | ★ 前后端开发约束规范（权威）：架构边界、APP_NAME 四处一致、前端规范、后端规范、接口契约、AI 生成检查清单 | 全体成员 + AI | +| architecture.md | 动静分离架构总览、技术栈、交付链路、治理体系 | 新成员 onboarding | +| agent-guide.md | AI 生成代码工作流（界面→代码提示词协议）、联调纪律、Vibe Coding 协作约定 | 全体成员 + AI | +| README.md（本文件） | 文档中心索引与交叉引用映射表 | 所有人 | + +## 交叉引用映射表（单源化） + +> 共享约束**只允许存在于 docs/**；各仓库 `.project.agents/docs/context/` 只写指针与仓库特有内容，禁止复制正文。维护共享内容时**先改 docs/，再同步各仓库指针**。 + +| 主题 | 权威位置 | 被引用于 | +|---|---|---| +| 前后端共享约束（命名/契约/工作流） | `docs/coding-standards.md` | 前端/后端 `CONVENTIONS.md`、`CLAUDE.md` | +| 动静分离架构链路 | `docs/architecture.md` | 前端/后端 `ARCHITECTURE.md` | +| AI 协作与界面→代码协议 | `docs/agent-guide.md` | 前端/后端 `VIBECODING_GUIDE.md`、`AGENTS.md` | +| 前端特有约定（标准件清单/页面模式） | 前端 `.project.agents/docs/context/CONVENTIONS.md` | 前端开发 | +| 后端特有约定（分层模板/SQL/打包） | 后端 `.project.agents/docs/context/CONVENTIONS.md` | 后端开发 | +| 升级日志 | 后端 `src/main/resources/doc/升级日志.md` | 发布记录 | + +## 快速上手（新成员 / 新任务） + +1. 读 `architecture.md` 了解整体形态。 +2. 开发前通读 `coding-standards.md`（尤其 §3 APP_NAME 与 §6 接口契约）。 +3. 由 AI 生成代码时，按 `agent-guide.md §2` 提供界面与业务说明，AI 遵循 §7 工作流并回附交付说明。 diff --git a/docs/agent-guide.md b/docs/agent-guide.md new file mode 100644 index 0000000..3985ea3 --- /dev/null +++ b/docs/agent-guide.md @@ -0,0 +1,90 @@ +# 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 用户侧（发起开发请求时的最小输入） + +``` +【业务说明】<要做什么，一两句话> +【界面】<原型图 / 截图 / 链接 / 界面文字描述> +【应用名】 +【服务别名】<前端 URL 首段，如 sms> +【数据库】 +【子系统编码】 +``` + +### 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：可引不可增 | diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..9acb0af --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,81 @@ +# 架构总览（abacus 动静分离微服务） + +> 权威来源：`docs/architecture.md` · 编码约束见 `docs/coding-standards.md` · AI 工作流见 `docs/agent-guide.md` + +## 1. 总体形态：前后端分离 + 动静同包发布 + +两个仓库协作，**共享一份 docs/ 文档中心**（本目录）： + +``` +D:\workBuddySpace\member\ +├── docs/ ← 团队文档单一权威（本目录） +├── abacus-static-framework/ ← Vue 3 前端底座（src/framework 只读 / src/subsystem 业务可写） +└── abacus.springboot.example/ ← Spring Boot Maven 微服务模板（业务写在 src/main/java 与 resources/sql） +``` + +交付链路（动静分离）： + +``` +前端源码 ──npm run build:prod──► 产物输出到后端 resources/html/vue/<应用名>/ + │ +后端 mvn package（assembly.xml） │ + ▼ + *-bin.zip = jar + doc + sql + html ← 一个发布单元，一起发版 +``` + +- 前端产物**不打进 jar**，随 zip 的 `html/` 目录部署（Nginx/容器托管静态资源，Java 进程提供 API）。 +- 开发期前端 `vite.config.ts server.proxy` 反代后端，替代 Nginx 联调。 + +## 2. 前端底座（abacus-static-framework） + +| 项 | 选型 | +|---|---| +| 框架 | Vue 3.5 + TypeScript 5 + Vite 6 | +| UI | Element Plus（通用）+ vxe-table（仅表格） | +| 状态 | Pinia | +| 代码生成 | unplugin-auto-import / unplugin-vue-components（自动引入，无需手写常见 import） | + +关键机制： + +- **只读/可写分区**：`src/framework/**` 只读共享；业务只写 `src/subsystem/**`（api / router / views / extend 及自建 components / hooks / store / styles / types / utils）。 +- **请求管线**（`framework/utils/request.ts`）：统一响应体解包、服务别名映射、token 自动刷新、commonParam 审计头——业务无感，详见 `coding-standards.md §6`。 +- **动态菜单权限**：`permissionStore.filterAsyncRoutes` 按 `url === path` 匹配后端菜单与 `subsystem/router/dynamicRouter.ts`，过滤后 `addRoute`。 +- **运行时配置**：`window.frameBaseConfig`（含 `backendServices` 服务别名映射）由宿主注入，`public/data/data.js` 声明当前子系统（`currentSubsystem` / `currentSubsystemName`）。 + +## 3. 后端模板（abacus.springboot.example） + +| 项 | 选型 | +|---|---| +| 构建 | Maven，父工程 `abacus.framework:abacus.springcloud.pom:1.5.0`，artifactId `abacus.springboot.<应用名>` | +| 框架 | Spring Boot + abacus 系列（config 2.1.0 / commons 1.6.5 / fundation 3.4.4 / business.service / asyncTool 1.0.0） | +| 注册/配置中心 | Nacos（bootstrap.yml，extension-configs 引入 abacus-database / discovery / acas / redis / actuator / xxljob 公共配置） | +| 数据库 | MySQL / SQL Server(jtds+mssql) / Oracle / 达梦，Druid + JPA；多数据源由 Nacos `abacus-database.yml` 提供 | +| 定时任务 | XXL-JOB 2.3.0（application-xxljob.yml） | +| 消息队列 | Kafka（配置经 Nacos 公共配置） | +| 接口文档 | springdoc（`springdoc.packages-to-scan`） | +| 监控 | Actuator + Prometheus（base-path `/services/actuator`） | + +分层（包前缀 `abacus.springboot.<应用名>.`）：`api(+api/view) / controller / dao / esb / pi / impl / repository / wsi / config / util / vo`，职责与扫描配置见 `coding-standards.md §5.1`。 + +统一响应体 `{status, message, data, errorCode}` 由 `abacus.commons` 的 `ResultResponseBodyWrapper` 包装（`Application.java` 注册 `@Bean`，`abacus.responseExcludePath` 排除白名单 URI）。 + +## 4. 关键一致性：APP_NAME 四处 + +应用名（APP_NAME）必须同时一致于：① `bootstrap.yml spring.application.name`（Nacos 注册）② `application.yml` 扫描包前缀（`abacus.controllerPackages` / `abacus.entitypackages` / `springdoc.packages-to-scan`）③ 前端 `api/<别名>/*.ts` 的 URL 首段 ④ `vite.config.ts build.outDir` 目录名。漏配任一处将**静默失败**，排查见 `coding-standards.md §3`。 + +## 5. 接口契约速览 + +| 契约项 | 约定 | +|---|---| +| 响应体 | `{status, message, data, errorCode}`；`status===200` 前端自动解包 data | +| 异常码 | 业务首位 `9`、系统首位 `5` | +| URL | 首段=服务别名 → `backendServices` 映射真实服务名 | +| 分页 | 响应 `{data, total}`（vxe-grid 的 result/total） | +| Excel | ArrayBuffer 响应不解包 | +| 鉴权 | Bearer token；<10min 自动刷新 + 并发队列 | + +## 6. 治理体系 + +- 前端仓库：`.project.agents/`（CLAUDE.md / AGENTS.md / SELF_CONSTRAINTS.md / VIBECODING_GUIDE.md / docs/context/{PRD,ARCHITECTURE,ROADMAP,CONVENTIONS,UIUX}.md） +- 后端仓库：`.project.agents/`（同构，无 UIUX.md） +- 单源化：共享约束只存在于 `docs/`，仓库内 CONVENTIONS 用指针引用，禁止复制正文。 diff --git a/docs/coding-standards.md b/docs/coding-standards.md new file mode 100644 index 0000000..682c958 --- /dev/null +++ b/docs/coding-standards.md @@ -0,0 +1,460 @@ +# 前后端开发约束规范（abacus 动静分离微服务） + +> 版本：1.0（2026-08-19） · 权威来源：本文件（`docs/coding-standards.md`） +> 适用范围：基于 `abacus-static-framework`（Vue 前端底座）与 `abacus.springboot.example`（Spring Boot Maven 微服务模板）开展的一切业务开发。 +> 读者：**AI 智能体**（生成代码时强制遵守）与**团队全体成员**（评审与开发时共同遵循）。 + +--- + +## 1. 规范目的与适用范围 + +### 1.1 目的 + +1. **界面 → 代码**：用户可直接提供界面（原型图 / 截图 / 描述），由 AI 依据本规范生成前后端代码，无需逐条追问技术细节。 +2. **统一约束**：团队所有成员在相同约束下开发，代码结构与风格一致，实现可预期的 Vibe Coding 工作流。 + +### 1.2 边界（必须） + +| 端 | 只读共享区（不得修改） | 业务可写区（唯一开发位置） | +|---|---|---| +| 前端 | `abacus-static-framework/src/framework/**` | `abacus-static-framework/src/subsystem/**` | +| 后端 | `abacus.springboot.example` 的 `pom.xml` / `assembly.xml` / `config/{dev,test,prod}/` 基础结构 | `src/main/java/abacus/springboot.<应用名>/**` + `src/main/resources/sql/**` + `doc/升级日志.md` | + +- **禁止**在 `src/framework/**` 内新增或修改代码；业务组件/工具无法复用标准件时，按 §4.6/§4.7 提交框架负责人评审后纳入框架，而非绕过。 +- 前端框架升级不覆盖清单：`public`、`vite.config.ts`、`src/subsystem`。 + +### 1.3 文档层级（单源化） + +- 本规范是**前后端共享约束的唯一权威**；各子项目 `.project.agents/docs/context/CONVENTIONS.md` 只写本仓库特有约定，共享内容一律以 `详见 ../../docs/coding-standards.md §N` 指针引用，**禁止复制正文**（防止文档漂移）。 + +--- + +## 2. 动静分离架构总览 + +``` +[前端] Vue 3 源码 (src/subsystem/**) + │ npm run build:prod + ▼ +vite outDir ──► [后端] 微服务工程 src/main/resources/html/vue/<应用名>/ + │ + │ mvn package（assembly.xml） + ▼ +发布包 *-bin.zip（jar + doc + sql + html）──► 部署（Nginx / 容器托管 html，Java 进程提供 API） +``` + +- 前后端通过 **HTTP 接口**通信；开发期由 `vite.config.ts server.proxy` 反代到后端（代替 Nginx）。 +- 后端通过 Nacos 注册/发现；接口文档 springdoc（OpenAPI）；统一响应体由 abacus.commons 的 `ResultResponseBodyWrapper` 包装（`Application.java` 注册 `@Bean`，`abacus.responseExcludePath` 排除不包装的 URI）。 + +--- + +## 3. APP_NAME 四处一致性（最高优先级，漏配静默失败） + +新系统/新应用开发时，**应用名（APP_NAME）必须在以下四个位置一致**，任一处漏配即静默失败（启动正常但页面 404 / 接口不可达 / 路由不装配）： + +| # | 位置 | 作用 | 示例 | +|---|---|---|---| +| ① | 后端 `bootstrap.yml` → `spring.application.name` | Nacos 注册名（须唯一） | `example` | +| ② | 后端 `application.yml` → `abacus.controllerPackages` / `abacus.entitypackages` / `springdoc.packages-to-scan` 的**包前缀** | 框架装配 Controller / Entity / 接口文档扫描 | `abacus.springboot.example` | +| ③ | 前端 `src/subsystem/api//*.ts` 的 **URL 首段** | 服务别名映射（§6.3） | `/example/xxx` | +| ④ | 前端 `vite.config.ts` → `build.outDir` 的**目录名** | 构建产物输出到后端 html 目录 | `html/vue/example/` | + +包前缀规范：`abacus.springboot.<应用名>.<层>`（分层见 §5.1）。 + +**排查表**（页面/接口异常时按症状定位）： + +| 症状 | 优先检查 | +|---|---| +| 页面 404 / 菜单空白 | ④ outDir 目录名 ≠ 后端 html 实际加载目录；③ URL 首段错误 | +| 接口 404 / 未装配 | ② 扫描包前缀未含新包；① Nacos 未注册 | +| 接口 500 / 服务不可达 | ① 与 ③ 映射不一致（backendServices 找不到别名） | + +**必须**：AI 生成代码完成后执行"APP_NAME 四联检"（见 §7.3 检查清单第 1 项）。 + +--- + +## 4. 前端开发规范（Vue 3 + TS + Vite + Element Plus + vxe-table + Pinia） + +### 4.1 目录结构（`src/subsystem/**` 内） + +``` +src/subsystem/ +├── api/<服务别名>/ # 接口封装：按微服务名分目录，按 Controller 分 ts 文件 +├── router/dynamicRouter.ts # 菜单路由唯一注册点 +├── views/<一级菜单>/<二级菜单>/index.vue # 菜单页面，按一/二级菜单分目录 +├── extend/ # 框架扩展钩子（如初始化定时器、菜单徽章） +├── components/ # （业务需要时自建）子系统内部通用组件 +├── hooks/ # （自建）业务组合式函数 +├── store/ # （自建）业务状态机（Pinia） +├── styles/ # （自建）业务公共 css +├── types/ # （自建）业务公共类型 +└── utils/ # （自建）业务工具函数与常量 +``` + +- 参考实现：`views/log/operationLog/index.vue`（列表页）、`views/document/dataDictionary/index.vue`（客户端分页）、`views/config/business/index.vue`（可编辑表格）、`views/document/interfacedoc/`（容器页 :is 切换 List/Detail）。 +- `unplugin-auto-import` 已配置（vue/vue-router/@vueuse/core + Element Plus resolver）：**禁止**手动 `import { ref, reactive } from 'vue'` 等自动导入项。 + +### 4.2 命名 + +- 组件名：PascalCase，且必须与路由 `name` 一致（``）。 +- 文件/目录：小写 + 短横线（kebab-case）；views 目录用一级/二级菜单中文名或语义名。 +- API 函数：`getXxx` / `saveXxx` / `deleteXxx` / `exportXxx`（动词+名词）。 +- **禁止**语义为空的命名：`Manager` / `Helper` / `Util` / `Common` / `Misc` / `Tools`（工具类需用具体动词命名，如 `useTableQueryReload`）。 + +### 4.3 API 封装（`api/<服务别名>/*.ts`） + +```ts +import request from '@/framework/utils/request'; + +// GET：查询，参数走 params +export function getOperationLogs(params: any = {}) { + return request({ url: '/sms/operationLogs', method: 'get', params }); +} +// POST：表单提交（urlencoded）或 JSON（默认） +export function getAbacusAPIs(data: any = {}) { + return request({ + headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, + url: '/sms/document/abacusAPI/list', method: 'post', data + }); +} +``` + +- **必须**：`url` 首段为服务别名（§6.3 映射）；默认参数 `params/data = {}`。 +- **必须**：`status === 200` 时拦截器已自动解包 `data`，**业务代码禁止再取 `.data`**（直接使用返回值）。 +- **禁止**：在组件内直接 `axios.get` / `fetch`；一律经 `request` 封装（自动携带 token / commonParam / 服务映射 / 错误提示）。 + +### 4.4 页面模式（对应用户给出的界面） + +| 界面形态 | 标准实现 | +|---|---| +| 查询 + 列表 | `AbQueryForm`（fieldConfigs 配置式）+ `vxe-grid`（`gridDefaultProps` + `proxyConfig.ajax.query`） | +| 服务端分页 | `clientPage: false`（默认，配 `pagerConfig`） | +| 客户端分页 | `clientPage: true`（配 `tableDataCache` / `filterNameRef` / `useQueryAndClientPaging`） | +| 新增/编辑表单 | `el-dialog` + `AbForm`（配置式） | +| 详情 | `el-drawer` 或容器页 `:is` 切换 List/Detail 组件 | +| 可编辑表格 | `editConfig: { trigger: 'dblclick', mode: 'row' }` + `editRender: { name: 'input' }` + `@edit-closed` 保存 | +| 表内搜索 | `useInVxeGridSearch` | +| 刷新/查询联动 | `useTableQueryReload` / `useQueryParamsHandle` | + +列表页模板骨架： + +```vue +