# 目录结构与代码组织
**本文引用的文件**
- [pom.xml](file://pom.xml)
- [ai-electron/package.json](file://ai-electron/package.json)
- [ai-electron/electron/main.ts](file://ai-electron/electron/main.ts)
- [ai-electron/electron/config/windowOptions.ts](file://ai-electron/electron/config/windowOptions.ts)
- [ai-electron/electron/preload/index.ts](file://ai-electron/electron/preload/index.ts)
- [ai-electron/electron/controller/windowCtl.ts](file://ai-electron/electron/controller/windowCtl.ts)
- [ai-electron/frontend/src/main.ts](file://ai-electron/frontend/src/main.ts)
- [ai-electron/frontend/src/App.vue](file://ai-electron/frontend/src/App.vue)
- [ai-gateway/pom.xml](file://ai-gateway/pom.xml)
- [ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java](file://ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java)
- [ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java)
- [ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java)
- [ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java)
- [ai-gateway/src/main/java/com/zsjz/gateway/admin/AdminController.java](file://ai-gateway/src/main/java/com/zsjz/gateway/admin/AdminController.java)
- [ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java)
- [ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeHealthRegistry.java](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeHealthRegistry.java)
- [ai-server/pom.xml](file://ai-server/pom.xml)
- [ai-server/src/main/java/com/zsjz/ai/App.java](file://ai-server/src/main/java/com/zsjz/ai/App.java)
## 目录总览
这个仓库是一个多工程协作系统,顶层 `pom.xml` 把两个 Spring Boot 子项目作为 Maven 模块管理:`ai-server` 是业务后端,`ai-gateway` 是按用户粘性路由的网关;`ai-electron` 是独立的 Electron 桌面客户端,不继承父 POM。
```mermaid
graph TB
Root["仓库根目录
顶层 pom.xml"] --> Gateway["ai-gateway
Spring Cloud Gateway"]
Root --> Server["ai-server
Spring Boot 业务服务"]
Root --> Electron["ai-electron
Electron 桌面客户端"]
Root --> Sql["sql
数据库脚本"]
Root --> Docs["docs
设计文档与测试数据"]
Root --> Deploy["deploy
部署脚本"]
Root --> Cmd["cmd
卸载脚本"]
Root --> Data["data
空 data/files 占位"]
Electron --> EMain["electron/main.ts
主进程入口"]
Electron --> EFrontend["frontend/src/main.ts
Vue 3 渲染进程入口"]
Electron --> EPub["public
静态资源"]
Electron --> EOut["out
打包产物"]
Electron --> ELogs["logs
运行日志"]
Gateway --> GApp["GatewayApplication.java"]
Gateway --> GRoutes["route/*
过滤器与路由选择"]
Gateway --> GAdmin["admin/*
管理接口"]
Gateway --> GReg["registry/*
服务与节点注册"]
Server --> SApp["App.java"]
Server --> SModules["module/*
按业务域划分"]
```
**图表来源**
- [pom.xml:1-23](file://pom.xml#L1-L23)
- [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42)
- [ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java:1-23](file://ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java#L1-L23)
- [ai-server/src/main/java/com/zsjz/ai/App.java:1-49](file://ai-server/src/main/java/com/zsjz/ai/App.java#L1-L49)
| 目录 | 职责 | 新成员定位建议 |
|---|---|---|
| `ai-electron` | Electron 桌面客户端,负责本地窗口、托盘、安全策略、前端加载和与后端交互 | 先看 `package.json` 的入口和 `electron/main.ts` |
| `ai-gateway` | Spring Cloud Gateway 转发层,实现用户粘性路由、登录态处理和管理接口 | 先看 `GatewayApplication.java` 和 `route/*` |
| `ai-server` | 业务服务端,承载案件、线索、Agent、清洗、知识图谱等全部业务 | 从 `module/*` 中找业务域,再查 controller/service/mapper/entity |
| `sql` | 数据库建表、初始化和维护脚本 | 修改结构前先读对应 SQL 文件 |
| `docs` | 设计文档、E2E 测试数据和测试用例 | 需求或架构问题优先查这里 |
| `deploy` | 部署环境脚本 | 运维配置相关 |
| `cmd` | Windows/Linux 卸载脚本 | 安装包卸载逻辑 |
| `data/files` | 空目录占位,用于外部文件或临时数据挂载 | 按需扩展 |
**章节来源**
- [pom.xml:1-23](file://pom.xml#L1-L23)
- [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42)
## ai-electron 子工程结构
`ai-electron` 是一个独立的 npm 工程,不是 Maven 模块。其 `package.json` 声明 `main` 为 `./public/electron/main.js`,即构建后的主进程入口;开发时通过自定义脚本启动。
| 目录或文件 | 职责 |
|---|---|
| `electron/main.ts` | Electron 主进程应用入口,使用 `ee-core` 创建应用、注册生命周期事件并注册 preload |
| `electron/preload/*` | 预加载模块,在主进程和渲染进程之间建立桥接,初始化托盘和安全服务 |
| `electron/controller/*` | 主进程控制器,暴露给渲染进程的 IPC 方法,如窗口控制、系统调用、下载控制 |
| `electron/service/*` | 主进程服务层,按 OS、下载、设置、窗口等能力拆分 |
| `electron/config/*` | 主进程配置,包括默认配置、本地覆盖、生产配置和窗口选项 |
| `frontend/` | Vue 3 渲染进程前端工程,使用 Vite、TypeScript、Ant Design Vue 和 Jeesite 风格基础框架 |
| `frontend/public/` | 前端静态资源,包含测试资源和构建期资源 |
| `public/` | Electron 主进程使用的静态资源,如 preload 脚本、HTML 模板和图片 |
| `out/` | Electron 打包产物目录,包含 Windows 解压包、builder 配置和版本信息 |
| `logs/` | 运行时日志目录 |
| `docs/design/` | 前端界面设计稿 |
### 主进程入口与控制流
主进程入口位于 `electron/main.ts`,它创建一个 `ElectronEgg` 应用实例,注册四个生命周期钩子:`ready`、`electron-app-ready`、`window-ready`、`before-close`,然后注册 preload 并启动应用。preload 在程序启动时加载托盘服务和网络安全服务。
```mermaid
sequenceDiagram
participant Node as "Node/Electron"
participant Main as "main.ts"
participant Lifecycle as "preload/lifecycle.ts"
participant Preload as "preload/index.ts"
participant Tray as "service/os/tray"
participant Security as "service/os/security"
Node->>Main: 加载 main.ts
Main->>Lifecycle: 注册 ready/electron-app-ready/window-ready/before-close
Main->>Preload: 注册 preload
Main->>Main: run()
Preload->>Tray: create()
Preload->>Security: create()
```
**图表来源**
- [ai-electron/electron/main.ts:1-19](file://ai-electron/electron/main.ts#L1-L19)
- [ai-electron/electron/preload/index.ts:1-16](file://ai-electron/electron/preload/index.ts#L1-L16)
窗口配置集中在 `electron/config/windowOptions.ts`,定义共享的 `webPreferences`(关闭上下文隔离、启用 nodeIntegration)、智能工作台窗口尺寸下限以及独立顶层窗口选项。注释说明主窗口和智能工作台必须保持一致的 webPreferences,因为渲染进程依赖直接 require electron 调用 IPC。
**章节来源**
- [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42)
- [ai-electron/electron/main.ts:1-19](file://ai-electron/electron/main.ts#L1-L19)
- [ai-electron/electron/preload/index.ts:1-16](file://ai-electron/electron/preload/index.ts#L1-L16)
- [ai-electron/electron/config/windowOptions.ts:1-41](file://ai-electron/electron/config/windowOptions.ts#L1-L41)
### 控制器与 IPC 通信
`controller/windowCtl.ts` 定义了窗口控制的控制器类,统一处理打开、关闭、聚焦智能工作台窗口,以及跨窗口状态同步。每个方法返回 `{ success, data|message }` 形式,失败不会抛出到 Electron 层。它还提供 `syncState`,把语义事件广播给除发送者之外的所有窗口,由接收方决定如何重读事实源或关闭自己。
```mermaid
flowchart TD
Start(["渲染进程调用 windowCtl"]) --> CheckParams["校验参数"]
CheckParams --> Action{"操作类型"}
Action -->|openSmartWindow| Open["打开或聚焦智能工作台"]
Action -->|closeSmartWindow| Close["关闭智能工作台"]
Action -->|focusMainWindow| Focus["主窗口置顶"]
Action -->|syncState| Broadcast["向其他窗口广播事件"]
Open --> Ok["返回 { success: true }"]
Close --> Ok
Focus --> Ok
Broadcast --> Ok
Ok --> End(["结束"])
```
**图表来源**
- [ai-electron/electron/controller/windowCtl.ts:1-123](file://ai-electron/electron/controller/windowCtl.ts#L1-L123)
**章节来源**
- [ai-electron/electron/controller/windowCtl.ts:1-123](file://ai-electron/electron/controller/windowCtl.ts#L1-L123)
### 前端渲染进程入口
前端工程位于 `ai-electron/frontend`,是独立的前端工作区。`package.json` 中的脚本通过 `ee-bin` 工具链分别执行前端构建、Electron 构建、图标处理和平台打包。前端源码入口是 `src/main.ts`,它负责初始化 UnoCSS、Ant Design Vue、全局组件、国际化、路由、Store、错误处理、水印、会话同步,并在启动时探测后端健康接口,最多重试 10 次、间隔约 3 秒。
`App.vue` 是根组件,提供 Ant Design Vue 的主题、语言、前缀类和应用容器,并在挂载后拉取授权信息、设置页面水印。它根据当前主题切换深色算法和主色,同时监听授权单元变化以动态更新水印。
```mermaid
flowchart TD
FrontendStart["frontend/src/main.ts"] --> InitCore["初始化核心框架"]
InitCore --> HealthCheck["轮询后端健康接口"]
HealthCheck --> BackendReady{"后端就绪?"}
BackendReady -->|是| MountApp["挂载 App.vue"]
BackendReady -->|否| ShowRetry["显示重试和修改地址按钮"]
MountApp --> AppRoot["App.vue 根组件"]
AppRoot --> Theme["设置 Ant Design 主题和语言"]
AppRoot --> Auth["拉取授权信息并设置水印"]
```
**图表来源**
- [ai-electron/frontend/src/main.ts:1-200](file://ai-electron/frontend/src/main.ts#L1-L200)
- [ai-electron/frontend/src/App.vue:1-85](file://ai-electron/frontend/src/App.vue#L1-L85)
**章节来源**
- [ai-electron/frontend/src/main.ts:1-200](file://ai-electron/frontend/src/main.ts#L1-L200)
- [ai-electron/frontend/src/App.vue:1-85](file://ai-electron/frontend/src/App.vue#L1-L85)
### 非源码目录使用规范
| 目录 | 用途 | 注意事项 |
|---|---|---|
| `ai-electron/public` | 主进程静态资源,包括 preload 脚本、HTML 模板和图片 | 不要放前端源码,应放在 `frontend/public` |
| `ai-electron/out` | Electron 打包输出 | 通常加入 `.gitignore`,不应提交构建产物 |
| `ai-electron/logs` | 运行时日志 | 需要持久化时注意磁盘空间 |
| `ai-electron/docs/design` | 前端界面设计稿 | 新增页面设计稿放在这里 |
| `ai-electron/data` | 本地数据,包括 Codex 数据、下载记录和本地设置 | 属于用户级或实例级数据,部署时注意清理或迁移 |
**章节来源**
- [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42)
## ai-gateway 子工程
`ai-gateway` 是 Spring Cloud Gateway 实现的按用户粘性路由转发网关,基于 WebFlux 和 Netty,支持 SSE、multipart 和 Range 下载等流式场景。其 `pom.xml` 明确描述为“按用户粘性路由的转发网关”,依赖 PostgreSQL 持久化路由和用户绑定关系,使用 Redis 缓存 token 解析结果和服务路由缓存,并通过 sa-token-reactor 解析 token。
### Spring Boot 入口
网关入口是 `GatewayApplication.java`,标注 `@SpringBootApplication`、`@EnableScheduling` 和 `@ConfigurationPropertiesScan`。注释强调其职责只有一个:把每个用户的请求固定转发到该用户绑定的 `ai-server` 节点,业务鉴权和案件数据源都在后端,网关不复制后端逻辑。
**章节来源**
- [ai-gateway/pom.xml:1-148](file://ai-gateway/pom.xml#L1-L148)
- [ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java:1-23](file://ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java#L1-L23)
### 路由与过滤器
网关的请求处理围绕三个核心过滤器展开。
| 组件 | 位置 | 职责 |
|---|---|---|
| `LoginRequestFilter` | `route/LoginRequestFilter.java` | 预处理登录请求,缓存请求体并解析 username,将 Accept-Encoding 改为 identity,避免后端 gzip 导致响应无法解析 |
| `StickyRouteFilter` | `route/StickyRouteFilter.java` | 粘性路由核心:按登录用户名或 x-token 解析 userId,选择已绑定节点;未绑定时走候选节点或默认节点;匿名请求轮询健康节点 |
| `LoginResponseFilter` | `route/LoginResponseFilter.java` | 登录成功后把用户绑定到 StickyRouteFilter 选定的节点,并把 token 写入 Redis 缓存 |
```mermaid
sequenceDiagram
participant Client as "客户端"
participant LoginFilter as "LoginRequestFilter"
participant StickyFilter as "StickyRouteFilter"
participant Registry as "GatewayRegistry"
participant Health as "NodeHealthRegistry"
participant Server as "ai-server 节点"
participant RespFilter as "LoginResponseFilter"
Client->>LoginFilter: POST 登录请求
LoginFilter->>LoginFilter: 解析 username
LoginFilter->>StickyFilter: 继续过滤
StickyFilter->>Registry: 查询服务信息
StickyFilter->>Registry: 查找用户绑定节点
StickyFilter->>Health: 检查节点健康
StickyFilter->>Server: 转发请求
Server-->>RespFilter: 返回登录响应
RespFilter->>Registry: 写用户绑定关系
RespFilter->>Registry: 缓存 token
RespFilter-->>Client: 原样返回登录响应
```
**图表来源**
- [ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java:1-120](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L1-L120)
- [ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java:1-180](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L1-L180)
- [ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java:1-176](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L1-L176)
粘性路由规则如下:
| 场景 | 行为 |
|---|---|
| 登录请求且 username 已绑定 | 转发到已绑定节点 |
| 登录请求且 username 未绑定 | 轮询候选节点,但不立即写库,等登录成功后再绑定 |
| 普通请求且 token 有效 | 解析 userId 并转发到绑定节点 |
| 普通请求但用户未绑定 | 尝试绑定默认节点;无默认节点则返回 503 |
| token 过期、被顶掉或伪造 | 按匿名轮询,透传给后端返回 401 |
| 绑定节点停用或 DOWN | 返回 503,不自动切换,因为数据在该节点本地磁盘上 |
| 匿名请求 | 轮询健康节点 |
**章节来源**
- [ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java:1-120](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L1-L120)
- [ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java:1-180](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L1-L180)
- [ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java:1-176](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L1-L176)
### 注册中心与服务发现
`registry/GatewayRegistry.java` 是服务与节点配置的内存快照,事实来源是 PostgreSQL,Redis 和内存只是缓存或快照。启动时如果 `gateway_service` 为空,会从 YAML 配置播种;运行中写库后立即刷新,其他实例每 10 秒对账一次,配置变化时发布 `RefreshRoutesEvent` 刷新路由缓存。
`registry/NodeHealthRegistry.java` 维护每个网关实例自己的节点健康状态,支持 UP、DOWN、UNKNOWN 三种状态。连续失败达到阈值才标记 DOWN,一次成功立即恢复 UP;UNKNOWN 乐观放行,避免刚启动时匿名请求全部 503。
```mermaid
classDiagram
class GatewayRegistry {
-List services
-boolean initialized
+seedFromYamlIfNeeded()
+reload() boolean
+pollForChanges() void
+getService(id) Optional
+findServiceByPath(path) Optional
}
class NodeHealthRegistry {
+isUp(nodeId) boolean
+recordSuccess(nodeId) void
+recordFailure(nodeId, error, threshold) void
+snapshot() Map
}
class ServiceInfo {
+id() string
+enabled() boolean
+defaultNodeId() string
+matchesPath(path) boolean
+findNode(nodeId) Optional
}
class NodeInfo {
+id() string
+baseUrl() string
+enabled() boolean
}
GatewayRegistry --> ServiceInfo : "管理"
NodeHealthRegistry --> NodeInfo : "监控"
```
**图表来源**
- [ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java:1-116](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java#L1-L116)
- [ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeHealthRegistry.java:1-68](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeHealthRegistry.java#L1-L68)
**章节来源**
- [ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java:1-116](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java#L1-L116)
- [ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeHealthRegistry.java:1-68](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeHealthRegistry.java#L1-L68)
### 管理接口
`admin/AdminController.java` 暴露 `/gateway/admin` 下的管理接口,包括服务 CRUD、节点 CRUD、节点健康检查、路由分页、路由绑定、解绑、导入已有绑定和重载配置。所有阻塞 JDBC 操作都通过 `boundedElastic` 调度器执行,避免占用 Netty 事件循环。接口受管理员登录态和可选 IP 白名单保护。
常见操作路径如下:
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | `/gateway/admin/status` | 查看网关状态 |
| GET | `/gateway/admin/services` | 列出服务 |
| POST | `/gateway/admin/services` | 创建服务 |
| PUT | `/gateway/admin/services/{serviceId}` | 更新服务 |
| DELETE | `/gateway/admin/services/{serviceId}` | 删除服务 |
| POST | `/gateway/admin/services/{serviceId}/nodes` | 创建节点 |
| PUT | `/gateway/admin/nodes/{nodeId}` | 更新节点 |
| DELETE | `/gateway/admin/nodes/{nodeId}` | 删除节点 |
| POST | `/gateway/admin/nodes/{nodeId}/check` | 检查节点健康 |
| GET | `/gateway/admin/routes` | 分页查询路由绑定 |
| POST | `/gateway/admin/routes/bind` | 绑定路由 |
| DELETE | `/gateway/admin/routes/{id}` | 解绑路由 |
| POST | `/gateway/admin/reload` | 重载配置 |
**章节来源**
- [ai-gateway/src/main/java/com/zsjz/gateway/admin/AdminController.java:1-153](file://ai-gateway/src/main/java/com/zsjz/gateway/admin/AdminController.java#L1-L153)
## ai-server 子工程
`ai-server` 是 Spring Boot 业务服务,顶层 `pom.xml` 引入 Spring Web、Validation、Redis、AOP、MyBatis-Plus、动态数据源、Sa-Token、PostgreSQL、pgvector、DuckDB、AgentScope、Spring AI、DJL Tokenizers 和 ONNX Runtime。业务模块按 `module/*` 组织,典型结构是 `controller`、`service`、`mapper`、`entity` 四层。
### Spring Boot 入口
`App.java` 是应用启动类,标注 `@SpringBootApplication` 和 `@EnableScheduling`。注释说明定时任务用于两处:SSE 心跳保活和回收用户会话过期但案件数据源仍打开的泄漏。启动时还包含检查工作空间的逻辑,必要时复制原始工作空间并处理锁文件。
**章节来源**
- [ai-server/pom.xml:1-200](file://ai-server/pom.xml#L1-L200)
- [ai-server/src/main/java/com/zsjz/ai/App.java:1-49](file://ai-server/src/main/java/com/zsjz/ai/App.java#L1-L49)
### module/* 业务域划分
`ai-server/src/main/java/com/zsjz/ai/module` 下按业务域划分子模块,每个领域通常包含 controller、service、mapper、entity。根据搜索结果,主要业务域包括:
| 业务域 | 典型职责 | 示例类 |
|---|---|---|
| `plat` | 平台基础能力,包括用户、系统、案例、表结构、塔设备、健康检查等 | `SystemController`、`SysUserService`、`CaseInfoService` |
| `aiclean` | AI 数据清洗,包括模板、规则、字段、同义词、批量作业、智能清洗等 | `AiCleanController`、`AiCleanService`、`AiCleanTemplate` |
| `agent` | Agent 能力,包括聊天、模型、工具包、能力注册、Python 执行、RAG、Insight 等 | `AgentChatController`、`LlmService`、`AgentToolPackEntity` |
| `dm` | 数据管理,包括文件识别、AI 画像、清洗错误日志、边关系等 | `DmController`、`DmService`、`FileInfoMapper` |
| `trans` | 资金交易分析,包括转账、流水、大额、频繁、敏感、卡冻结等 | `TransRecordController`、`TransFundFlowService` |
| `person` | 人员信息,包括基本信息、亲密度、群体、常住人口等 | `PersonBasicInfoController`、`IntimacyService` |
| `call` | 通话记录,包括通话明细、夜间通话、敏感通话、连续通话等 | `CallRecordController`、`CallNightService` |
| `track` | 轨迹追踪,包括同行出行、同住、乘车票、快递、基站等 | `TrackTogetherTravelController`、`ExpressInfoService` |
| `otg` | 其他轨迹类数据,包括时间序列、特殊日期等 | `TimeSeriesController`、`SpecialDateService` |
| `knowledge` | 知识库,包括知识文档、下载日志、知识基座 | `KnowledgeBaseController`、`KnowledgeDoc` |
| `embedding` | 嵌入调试 | `EmbeddingDebugController` |
| `search` | 搜索索引 | `SearchQueryService` |
| `external` | 外部数据映射 | 各类 Mapper |
| `govern` | 治理树、治理配置 | `GovernController`、`GovernTreeService` |
| `graph` | 图谱 | `GraphController`、`GraphService` |
每个业务域通常遵循以下结构:
```mermaid
graph LR
Controller["controller/*Controller.java"] --> Service["service/*Service.java"]
Service --> Mapper["mapper/*Mapper.java"]
Mapper --> Entity["entity/*.java"]
Service --> External["外部系统
数据库/向量库/LLM"]
```
新成员进入某个业务域时,建议顺序:
1. 先看 `controller`,了解对外 API。
2. 再看 `service`,理解业务流程。
3. 接着看 `mapper` 和 `entity`,理解数据模型。
4. 最后对照 `sql` 目录中的建表脚本,确认表结构是否一致。
**章节来源**
- [ai-server/pom.xml:1-200](file://ai-server/pom.xml#L1-L200)
- [ai-server/src/main/java/com/zsjz/ai/App.java:1-49](file://ai-server/src/main/java/com/zsjz/ai/App.java#L1-L49)
## 模块入口总结
| 子系统 | 入口文件 | 说明 |
|---|---|---|
| 顶层 Maven | `pom.xml` | 聚合 `ai-server` 和 `ai-gateway`,打包类型为 pom |
| Electron 主进程 | `ai-electron/electron/main.ts` | 使用 ee-core 创建应用、注册生命周期和 preload |
| Electron 前端 | `ai-electron/frontend/src/main.ts` | 初始化 Vue 3 应用、路由、Store、国际化,并轮询后端健康接口 |
| Electron 根组件 | `ai-electron/frontend/src/App.vue` | 提供 Ant Design 主题、语言和授权水印 |
| 网关 | `ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java` | Spring Boot 入口,启用调度、属性扫描 |
| 业务服务 | `ai-server/src/main/java/com/zsjz/ai/App.java` | Spring Boot 入口,启用调度,处理工作空间初始化 |
**章节来源**
- [pom.xml:1-23](file://pom.xml#L1-L23)
- [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42)
- [ai-electron/electron/main.ts:1-19](file://ai-electron/electron/main.ts#L1-L19)
- [ai-electron/frontend/src/main.ts:1-200](file://ai-electron/frontend/src/main.ts#L1-L200)
- [ai-electron/frontend/src/App.vue:1-85](file://ai-electron/frontend/src/App.vue#L1-L85)
- [ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java:1-23](file://ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java#L1-L23)
- [ai-server/src/main/java/com/zsjz/ai/App.java:1-49](file://ai-server/src/main/java/com/zsjz/ai/App.java#L1-L49)
## 非源码目录使用规范
| 目录 | 推荐用法 |
|---|---|
| `sql` | 存放数据库建表、初始化和维护脚本。网关只复制 `sql/gateway.sql` 到 classpath,业务表结构变更应先写 SQL,再对齐 entity 和 mapper |
| `docs` | 存放设计文档、E2E 测试 fixture、测试用例和设计稿。架构决策优先落盘到这里,例如 `docs/design` 和 `docs/testing` |
| `deploy` | 存放部署相关脚本,如 `env.sh` |
| `cmd` | 存放安装包卸载脚本,如 `uninstall.bat`、`uninstall.sh` |
| `data/files` | 空目录占位,可用于挂载外部文件或临时数据;不要把源码或大型二进制放入此处 |
| `ai-electron/out` | Electron 打包产物,一般不应提交到版本库 |
| `ai-electron/logs` | 运行时日志,部署时应考虑日志轮转和保留策略 |
| `ai-electron/data` | 本地数据,包括 Codex workspace、sessions、skills、downloads.json、local-settings.json 等,属于用户数据,升级时注意兼容 |
**章节来源**
- [ai-gateway/pom.xml:1-148](file://ai-gateway/pom.xml#L1-L148)
## 新成员快速上手路线
1. 先阅读 `readme.md` 和 `AI_AGENT.md`,了解项目整体目标。
2. 如果是前端开发,从 `ai-electron/frontend/src/main.ts` 和 `ai-electron/frontend/src/App.vue` 入手。
3. 如果是桌面功能,从 `ai-electron/electron/main.ts`、`electron/controller` 和 `electron/service` 入手。
4. 如果是网关开发,从 `GatewayApplication.java`、`route/*` 和 `admin/AdminController.java` 入手。
5. 如果是业务开发,从 `ai-server/src/main/java/com/zsjz/ai/module` 中找到对应业务域,再按 controller → service → mapper → entity 顺序阅读。
6. 涉及数据库变更时,先查 `sql` 目录,确认脚本是否幂等,再改代码。
7. 涉及部署时,先看 `deploy/env.sh` 和 `cmd/uninstall.*`。
8. 遇到架构问题,优先查 `docs` 下的设计文档和测试用例。