# 目录结构与代码组织 **本文引用的文件** - [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` 下的设计文档和测试用例。