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

4.8 KiB Raw Blame History Unescape Escape