一、 本周工作概述

本周是项目实训的第一周，核心目标并非实现具体的业务功能，而是进行顶层设计与地基建设。基于《智契通》项目需求，我们确立了“Spring Boot 3 + Vue 3 + AI”的技术路线。

主要工作分为两个维度：

1. 架构设计：完成了从需求分析到系统分层、技术选型的总体设计，明确了微服务演进方向。
2. 环境搭建：完成了前后端工程的初始化，重点实现了后端通用异常处理体系、响应封装及前端请求拦截器，为后续AI能力接入打下基础。

二、 项目总体架构设计

在编码开始前，我们首先制定了详细的《智契通项目总体架构设计》。一个清晰的架构是应对复杂业务（如合同生成、风险审查）的前提。

1. 技术选型策略
我们采用前后端分离架构，兼顾开发效率与系统扩展性：

• 后端（Java Spring Boot 3.x）：利用其强大的生态和稳定性，集成Spring Security进行权限控制，使用Redis做缓存，MySQL存储核心数据。
• 前端（Vue 3 + TypeScript）：采用Vite构建工具，Pinia状态管理，Element Plus组件库，确保现代化的交互体验。
• AI能力层：预留OpenAI、通义千问等大模型接口，通过适配器模式支持多模型切换。

2. 系统分层设计
为了保证代码的可维护性，我们严格遵循分层架构：

• 表现层：Vue前端，负责合同展示、编辑与可视化对比。
• 接入层：统一API网关（初期由Spring Boot统一处理），负责JWT鉴权与限流。
• 业务层：核心业务逻辑，包括合同模板、生成、审查、摘要、对比等模块。
• AI服务层：独立的模型调用与Prompt编排服务，隔离大模型的不稳定性。
• 数据层：MySQL + Redis + 对象存储（MinIO），支持海量合同存储。

3. 模块化规划
考虑到项目初期采用单体架构，我们预先规划了模块目录，以便未来拆分为微服务：

• contract-user (用户权限)
• contract-core (合同核心数据)
• contract-ai (AI模型调用)
• contract-risk (风险识别)

三、 后端基础环境搭建与核心配置

环境搭建不仅仅是引入依赖，更重要的是建立一套规范的代码契约。本周后端工作重点在于“通用能力”的封装。

1. 项目结构规范
基于Maven构建，我们规范了标准的包结构，确保团队成员代码风格统一：

src/
├── main/
│   ├── java/
│   │   └── com.zhiqitong/
│   │       ├── config/       # 配置类 (如WebConfig, RedisConfig)
│   │       ├── controller/   # 接口层
│   │       ├── exception/    # 异常处理体系
│   │       ├── service/      # 业务逻辑层
│   │       ├── util/         # 通用工具类 (Hutool扩展)
│   │       └── Application.java
│   └── resources/
└── test/

2. 核心依赖整合

• Hutool工具库：引入Hutool以简化Java开发。例如，使用IdUtil.getSnowflake()生成分布式唯一ID，避免数据库主键冲突，这在处理大量合同文档时至关重要。
• Knife4j接口文档：集成Swagger增强版，实现无注解零配置的接口文档生成，极大方便了前后端联调。

3. 通用异常与响应封装（核心亮点）
为了提升系统的健壮性和前端交互的友好度，我设计了一套完善的异常处理机制。

• 自定义错误码枚举：
  我们定义了标准的错误码体系，与HTTP状态码语义保持一致，便于前端统一处理。

  @Getter
  public enum ErrorCode {
      SUCCESS(0, "成功"),
      PARAMS_ERROR(40000, "请求参数错误"),
      NOT_LOGIN_ERROR(40100, "未登录"),
      NO_AUTH_ERROR(40101, "无权限"),
      SYSTEM_ERROR(50000, "系统内部异常");
  
      private final int code;
      private final String message;
      
      // 构造方法...
  }

• 全局异常处理器 (GlobalExceptionHandler)：
  利用 @RestControllerAdvice 捕获所有未处理的异常。无论是业务逻辑抛出的 BusinessException，还是系统底层的 RuntimeException，都会被统一拦截，记录日志并返回标准格式，避免系统崩溃。

  @RestControllerAdvice
  @Slf4j
  public class GlobalExceptionHandler {
      
      @ExceptionHandler(BusinessException.class)
      public BaseResponse<?> handleBusinessException(BusinessException e) {
          log.error("BusinessException: ", e);
          return ResultUtils.error(e.getCode(), e.getMessage());
      }
  
      @ExceptionHandler(Exception.class)
      public BaseResponse<?> handleException(Exception e) {
          log.error("System Error: ", e);
          return ResultUtils.error(ErrorCode.SYSTEM_ERROR);
      }
  }

• 统一响应包装类 (BaseResponse)：
  规范所有接口的返回结构（code, data, message），前端只需一套逻辑即可解析所有接口数据。

四、 前端工程化配置与全局设计

前端的任务是打通与后端的通信桥梁，并提供一致的用户体验。

1. Vue 3 工程化架构
采用 Vite 作为构建工具，TypeScript 作为开发语言，Pinia 替代 Vuex 进行状态管理。目录结构清晰分离了 views（页面）、components（组件）、api（接口请求）和 router（路由）。

2. 全局通用布局 (Layout)
参考Ant Design Pro的设计理念，我们设计了 BasicLayout。页面采用经典的“上-中-下”结构：

• Header：包含Logo、导航菜单及用户头像下拉菜单（集成登录状态检测）。
• Content：通过 <router-view> 动态加载子路由，适配不同屏幕尺寸。
• Footer：固定底部的版权信息。

3. 请求层封装与拦截器
为了应对复杂的API调用（特别是后续调用AI接口时的鉴权），我们封装了 Axios 实例：

• 请求拦截器：统一注入 Token（JWT），处理 Loading 状态。
• 响应拦截器：核心在于错误统一处理。在拦截器中直接判断后端返回的 code：
  • 若为 40100（未登录），则自动跳转至登录页，无需每个页面单独判断。
  • 若为业务错误（如参数错误），则通过 Message 组件统一弹出提示，极大减少了业务代码中的冗余判断逻辑。

五、 遇到的问题与解决方案

1. Spring Boot 3 的 Jakarta 包冲突

   • 问题：Spring Boot 3 默认使用 jakarta.servlet，而部分旧版依赖（如Swagger早期版本）使用 javax.servlet，导致启动报错。
   • 解决：升级Swagger为Knife4j的Spring Boot 3适配版本，并检查依赖树，排除冲突的旧包。

2. 跨域 (CORS) 与 Credentials 配置

   • 问题：前端开发服务器（localhost:5173）访问后端（localhost:8080）时，Cookie无法携带，导致登录态丢失。
   • 解决：在后端配置 @CrossOrigin 或自定义 CorsConfiguration，并设置 allowCredentials 为 true，同时前端 Axios 配置 withCredentials: true。