zsjz-ai/.qoder/repowiki/knowledge/zh/AI 多模块聚合工程根/build_system.md

1. 整体方案

仓库采用双轨构建：

• Java 后端（ai-server、ai-gateway）由根 pom.xml 以 Maven 聚合工程统一编排，继承 spring-boot-starter-parent:3.5.16。
• 桌面客户端（ai-electron）基于 Electron + Vue/TS 前端，通过 ee-bin（Electron 封装工具）+ electron-builder 完成多平台打包。

根 POM (pom.xml) 仅声明 <packaging>pom</packaging> 与两个子模块，版本为 1.0；Spring Boot 依赖版本由父 POM 托管。Java 子模块各自在 pom.xml 中配置 spring-boot-maven-plugin 与 maven-compiler-plugin（含 Lombok annotation processor），没有统一的 pluginManagement，因此各模块自行管理插件版本。

2. Java 后端构建约定

• 可运行产物：spring-boot-maven-plugin 默认生成 fat jar（含所有依赖），可直接 java -jar 启动。
• 瘦包（thin jar）：ai-server/pom.xml 额外通过 maven-jar-plugin 的 <execution id="thin-jar"> 输出带 classifier=thin 的 ai-server-{version}-thin.jar，Manifest 中写入 Main-Class: com.zsjz.ai.App 及 Class-Path: lib/；配合 maven-dependency-plugin 将 runtime 依赖拷贝到 target/lib/，形成“瘦包 + lib 目录”的可分部署形态。
• 工作目录固定：ai-server 的 spring-boot-maven-plugin 显式设置 <workingDirectory>${project.parent.basedir}</workingDirectory>，强制运行时 CWD 指向仓库根，使 PathConst 能正确解析 QingJian/ 资产与 ./data/files，避免产物与附件被写进 ai-server/QingJian。
• DDL 单点维护：ai-gateway 通过 maven-resources-plugin 在 generate-resources 阶段把根 sql/gateway.sql 复制到 src/main/resources/db/gateway.sql，供 Spring SQL Init 幂等建表。
• 测试：ai-server 使用 spring-boot-starter-test + JUnit；ai-gateway 额外引入 reactor-test；ai-electron 使用 vitest（见 vitest.config.mts）。

3. Electron 桌面端构建

• 入口：ai-electron/package.json 定义脚本 build → npm run build-frontend && npm run build-electron && ee-bin encrypt，先编译前端再打包 Electron。
• 前端构建：ai-electron/frontend/bin/build.sh 只是 cd .. && pnpm build && cd bin，实际由 Vite（vite.config.ts）驱动；pnpm 锁文件 pnpm-lock.yaml 锁定依赖。
• Electron 打包：ee-bin 根据命令参数选择目标（win64/win_e/mac_arm64/mac/linux），底层调用 electron-builder；平台配置集中在 ai-electron/cmd/builder.json（以及 builder-linux.json、builder-mac.json、builder-mac-arm64.json），定义产物名 ${productName}-${os}-${version}-${arch}.${ext}、NSIS Windows 安装包、Linux deb 包、asar 归档、多语言（en-US/zh-CN）。
• 输出位置：directories.output = "out"，已存在的 ai-electron/out/win-unpacked/、latest.yml、builder-effective-config.yaml 即为历史产物。
• 自动更新：依赖 electron-updater，builder.json 中 publish.provider = "generic"，url 为空占位，需外部配置 CDN。

4. CI / Docker / 发布流程

• 无仓库级 CI：根目录未发现 .github/workflows、.gitlab-ci.yml、Jenkinsfile 等流水线文件；也未发现仓库根级别的 Dockerfile。ai-electron/frontend/node_modules/.pnpm/comlink@.../Dockerfile 仅为第三方依赖自带，非本项目产物。
• 卸载脚本：根 cmd/uninstall.bat 与 cmd/uninstall.sh 提供安装后的卸载能力。
• 版本策略：Java 模块版本号由根 POM 的 <version>1.0</version> 统一管理；Electron 客户端版本号位于 ai-electron/package.json 的 "version": "200.0.0"，二者独立。

5. 约束与规则

• Java 模块必须继承 spring-boot-starter-parent:3.5.16（根 POM 强制）。
• ai-server 运行时必须以仓库根为 CWD（由 spring-boot-maven-plugin.workingDirectory 强制），否则资源路径与数据目录会错乱。
• ai-server 的 thin jar 与 target/lib/ 必须同目录放置才能被 Main-Class 正确加载（由 Manifest 的 classpathPrefix=lib/ 强制）。
• ai-gateway 的 DDL 只允许放在仓库根 sql/gateway.sql，由 Maven 复制至 classpath（由 maven-resources-plugin 的 include 规则强制）。
• Electron 客户端打包产物命名遵循 ${productName}-${os}-${version}-${arch}.${ext} 模板（由 builder.json 的 artifactName 字段强制）。
• 前端依赖通过 pnpm 锁定（pnpm-lock.yaml），构建应使用 pnpm 而非 npm/yarn。