82 lines
4.8 KiB
Markdown
82 lines
4.8 KiB
Markdown
# 架构总览（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 用指针引用，禁止复制正文。
|