目录结构与代码组织

本文引用的文件

pom.xml
ai-electron/package.json
ai-electron/electron/main.ts
ai-electron/electron/config/windowOptions.ts
ai-electron/electron/preload/index.ts
ai-electron/electron/controller/windowCtl.ts
ai-electron/frontend/src/main.ts
ai-electron/frontend/src/App.vue
ai-gateway/pom.xml
ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java
ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java
ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java
ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java
ai-gateway/src/main/java/com/zsjz/gateway/admin/AdminController.java
ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java
ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeHealthRegistry.java
ai-server/pom.xml
ai-server/src/main/java/com/zsjz/ai/App.java

目录总览

这个仓库是一个多工程协作系统，顶层 pom.xml 把两个 Spring Boot 子项目作为 Maven 模块管理：ai-server 是业务后端，ai-gateway 是按用户粘性路由的网关；ai-electron 是独立的 Electron 桌面客户端，不继承父 POM。

graph TB
    Root["仓库根目录<br/>顶层 pom.xml"] --> Gateway["ai-gateway<br/>Spring Cloud Gateway"]
    Root --> Server["ai-server<br/>Spring Boot 业务服务"]
    Root --> Electron["ai-electron<br/>Electron 桌面客户端"]
    Root --> Sql["sql<br/>数据库脚本"]
    Root --> Docs["docs<br/>设计文档与测试数据"]
    Root --> Deploy["deploy<br/>部署脚本"]
    Root --> Cmd["cmd<br/>卸载脚本"]
    Root --> Data["data<br/>空 data/files 占位"]

    Electron --> EMain["electron/main.ts<br/>主进程入口"]
    Electron --> EFrontend["frontend/src/main.ts<br/>Vue 3 渲染进程入口"]
    Electron --> EPub["public<br/>静态资源"]
    Electron --> EOut["out<br/>打包产物"]
    Electron --> ELogs["logs<br/>运行日志"]

    Gateway --> GApp["GatewayApplication.java"]
    Gateway --> GRoutes["route/*<br/>过滤器与路由选择"]
    Gateway --> GAdmin["admin/*<br/>管理接口"]
    Gateway --> GReg["registry/*<br/>服务与节点注册"]

    Server --> SApp["App.java"]
    Server --> SModules["module/*<br/>按业务域划分"]

图表来源

pom.xml:1-23
ai-electron/package.json:1-42
ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java:1-23
ai-server/src/main/java/com/zsjz/ai/App.java:1-49

目录	职责	新成员定位建议
`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
ai-electron/package.json:1-42

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 在程序启动时加载托盘服务和网络安全服务。

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
ai-electron/electron/preload/index.ts:1-16

窗口配置集中在 electron/config/windowOptions.ts，定义共享的 webPreferences（关闭上下文隔离、启用 nodeIntegration）、智能工作台窗口尺寸下限以及独立顶层窗口选项。注释说明主窗口和智能工作台必须保持一致的 webPreferences，因为渲染进程依赖直接 require electron 调用 IPC。

章节来源

ai-electron/package.json:1-42
ai-electron/electron/main.ts:1-19
ai-electron/electron/preload/index.ts:1-16
ai-electron/electron/config/windowOptions.ts:1-41

控制器与 IPC 通信

controller/windowCtl.ts 定义了窗口控制的控制器类，统一处理打开、关闭、聚焦智能工作台窗口，以及跨窗口状态同步。每个方法返回 { success, data|message } 形式，失败不会抛出到 Electron 层。它还提供 syncState，把语义事件广播给除发送者之外的所有窗口，由接收方决定如何重读事实源或关闭自己。

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

章节来源

ai-electron/electron/controller/windowCtl.ts:1-123

前端渲染进程入口

前端工程位于 ai-electron/frontend，是独立的前端工作区。package.json 中的脚本通过 ee-bin 工具链分别执行前端构建、Electron 构建、图标处理和平台打包。前端源码入口是 src/main.ts，它负责初始化 UnoCSS、Ant Design Vue、全局组件、国际化、路由、Store、错误处理、水印、会话同步，并在启动时探测后端健康接口，最多重试 10 次、间隔约 3 秒。

App.vue 是根组件，提供 Ant Design Vue 的主题、语言、前缀类和应用容器，并在挂载后拉取授权信息、设置页面水印。它根据当前主题切换深色算法和主色，同时监听授权单元变化以动态更新水印。

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
ai-electron/frontend/src/App.vue:1-85

章节来源

ai-electron/frontend/src/main.ts:1-200
ai-electron/frontend/src/App.vue:1-85

非源码目录使用规范

目录	用途	注意事项
`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

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
ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java:1-23

路由与过滤器

网关的请求处理围绕三个核心过滤器展开。

组件	位置	职责
`LoginRequestFilter`	`route/LoginRequestFilter.java`	预处理登录请求，缓存请求体并解析 username，将 Accept-Encoding 改为 identity，避免后端 gzip 导致响应无法解析
`StickyRouteFilter`	`route/StickyRouteFilter.java`	粘性路由核心：按登录用户名或 x-token 解析 userId，选择已绑定节点；未绑定时走候选节点或默认节点；匿名请求轮询健康节点
`LoginResponseFilter`	`route/LoginResponseFilter.java`	登录成功后把用户绑定到 StickyRouteFilter 选定的节点，并把 token 写入 Redis 缓存

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
ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java:1-180
ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java:1-176

粘性路由规则如下：

场景	行为
登录请求且 username 已绑定	转发到已绑定节点
登录请求且 username 未绑定	轮询候选节点，但不立即写库，等登录成功后再绑定
普通请求且 token 有效	解析 userId 并转发到绑定节点
普通请求但用户未绑定	尝试绑定默认节点；无默认节点则返回 503
token 过期、被顶掉或伪造	按匿名轮询，透传给后端返回 401
绑定节点停用或 DOWN	返回 503，不自动切换，因为数据在该节点本地磁盘上
匿名请求	轮询健康节点

章节来源

ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java:1-120
ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java:1-180
ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java:1-176

注册中心与服务发现

registry/GatewayRegistry.java 是服务与节点配置的内存快照，事实来源是 PostgreSQL，Redis 和内存只是缓存或快照。启动时如果 gateway_service 为空，会从 YAML 配置播种；运行中写库后立即刷新，其他实例每 10 秒对账一次，配置变化时发布 RefreshRoutesEvent 刷新路由缓存。

registry/NodeHealthRegistry.java 维护每个网关实例自己的节点健康状态，支持 UP、DOWN、UNKNOWN 三种状态。连续失败达到阈值才标记 DOWN，一次成功立即恢复 UP；UNKNOWN 乐观放行，避免刚启动时匿名请求全部 503。

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
ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeHealthRegistry.java:1-68

章节来源

ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java:1-116
ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeHealthRegistry.java:1-68

管理接口

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

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
ai-server/src/main/java/com/zsjz/ai/App.java:1-49

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`

每个业务域通常遵循以下结构：

graph LR
    Controller["controller/*Controller.java"] --> Service["service/*Service.java"]
    Service --> Mapper["mapper/*Mapper.java"]
    Mapper --> Entity["entity/*.java"]
    Service --> External["外部系统<br/>数据库/向量库/LLM"]

新成员进入某个业务域时，建议顺序：

先看 controller，了解对外 API。
再看 service，理解业务流程。
接着看 mapper 和 entity，理解数据模型。
最后对照 sql 目录中的建表脚本，确认表结构是否一致。

章节来源

ai-server/pom.xml:1-200
ai-server/src/main/java/com/zsjz/ai/App.java:1-49

模块入口总结

子系统	入口文件	说明
顶层 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
ai-electron/package.json:1-42
ai-electron/electron/main.ts:1-19
ai-electron/frontend/src/main.ts:1-200
ai-electron/frontend/src/App.vue:1-85
ai-gateway/src/main/java/com/zsjz/gateway/GatewayApplication.java:1-23
ai-server/src/main/java/com/zsjz/ai/App.java:1-49

非源码目录使用规范

目录	推荐用法
`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

新成员快速上手路线

先阅读 readme.md 和 AI_AGENT.md，了解项目整体目标。
如果是前端开发，从 ai-electron/frontend/src/main.ts 和 ai-electron/frontend/src/App.vue 入手。
如果是桌面功能，从 ai-electron/electron/main.ts、electron/controller 和 electron/service 入手。
如果是网关开发，从 GatewayApplication.java、route/* 和 admin/AdminController.java 入手。
如果是业务开发，从 ai-server/src/main/java/com/zsjz/ai/module 中找到对应业务域，再按 controller → service → mapper → entity 顺序阅读。
涉及数据库变更时，先查 sql 目录，确认脚本是否幂等，再改代码。
涉及部署时，先看 deploy/env.sh 和 cmd/uninstall.*。
遇到架构问题，优先查 docs 下的设计文档和测试用例。

目录结构与代码组织.md 26 KB Histórico Raw

目录结构与代码组织

目录总览

ai-electron 子工程结构

主进程入口与控制流

控制器与 IPC 通信

前端渲染进程入口

非源码目录使用规范

ai-gateway 子工程

Spring Boot 入口

路由与过滤器

注册中心与服务发现

管理接口

ai-server 子工程

Spring Boot 入口

module/* 业务域划分

模块入口总结

非源码目录使用规范

新成员快速上手路线

目录结构与代码组织.md 26 KB

Histórico Raw