# 模块01：项目初始化与基础配置

---

## 🎨 UI设计系统概览

> **完整设计系统文档请参考：** `UI设计系统.md`

### 核心设计原则
- **现代简约**：界面清晰，层次分明
- **专业高效**：减少操作步骤，提升工作效率
- **一致性**：统一的视觉语言和交互模式
- **可访问性**：符合WCAG 2.1 AA标准

### 关键设计令牌

**颜色系统：**
- 主色：`#0d6efd`（操作按钮、选中状态）
- 成功：`#198754`（连接成功状态）
- 危险：`#dc3545`（删除操作、错误提示）
- 深灰：`#212529`（导航栏背景）
- 浅灰：`#e9ecef`（工具栏背景）

**字体系统：**
- 字体族：系统字体栈（-apple-system, Segoe UI, Roboto等）
- 正文：14px，行高1.5
- 标题：20-32px，行高1.2-1.4
- 小号文字：12px（文件大小、日期等）

**间距系统：**
- 基础单位：8px
- 标准间距：16px（1rem）
- 组件内边距：8px-16px

**组件规范：**
- 导航栏：高度48px，深色背景
- 工具栏：浅灰背景，按钮间距8px
- 文件项：最小高度44px，悬停效果150ms
- 按钮：圆角4px，过渡150ms

**交互规范：**
- 悬停效果：150ms过渡
- 触摸目标：最小44x44px
- 键盘导航：Tab、Enter、Delete、F2、F5、Esc
- 焦点状态：2px蓝色轮廓

**响应式断点：**
- 移动端：< 768px（双面板垂直排列）
- 平板：768px - 1024px
- 桌面：> 1024px（标准布局）

---

## 1.1 项目结构创建

```
sftp-manager/
├── README.md                      # 项目说明文档
├── pom.xml                        # Maven配置文件
└── src/
    ├── main/
    │   ├── java/com/sftp/manager/
    │   │   ├── SftpManagerApplication.java      # Spring Boot主类
    │   │   ├── config/
    │   │   │   └── WebConfig.java               # Web配置（CORS等）
    │   │   ├── controller/
    │   │   │   ├── FileController.java          # 文件操作API
    │   │   │   └── ConnectionController.java    # 连接管理API
    │   │   ├── service/
    │   │   │   ├── SftpService.java             # SFTP操作服务
    │   │   │   ├── LocalFileService.java       # 本地文件操作服务
    │   │   │   └── ConnectionService.java      # 连接配置服务
    │   │   ├── model/
    │   │   │   ├── Connection.java              # 连接实体类
    │   │   │   └── FileInfo.java                # 文件信息实体类
    │   │   └── dto/
    │   │       ├── ConnectionRequest.java       # 连接请求DTO
    │   │       ├── FileOperationRequest.java    # 文件操作请求DTO
    │   │       └── ApiResponse.java             # API统一响应DTO
    │   └── resources/
    │       ├── application.yml                  # 应用配置文件
    │       ├── static/
    │       │   ├── css/
    │       │   │   └── style.css                # 自定义样式
    │       │   └── js/
    │       │       └── app.js                   # 前端业务逻辑
    │       └── templates/
    │           └── index.html                  # 主页面（双面板UI）
    └── test/                                    # 测试代码
```

## 1.2 Maven依赖配置（pom.xml）

### 核心依赖

```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.18</version>
        <relativePath/>
    </parent>

    <groupId>com.sftp</groupId>
    <artifactId>sftp-manager</artifactId>
    <version>1.0.0</version>
    <name>SFTP Manager</name>
    <description>SFTP文件管理系统</description>

    <properties>
        <java.version>1.8</java.version>
        <jsch.version>0.1.55</jsch.version>
        <h2.version>2.1.214</h2.version>
        <lombok.version>1.18.30</lombok.version>
    </properties>

    <dependencies>
        <!-- Spring Boot Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- JSch for SFTP -->
        <dependency>
            <groupId>com.jcraft</groupId>
            <artifactId>jsch</artifactId>
            <version>${jsch.version}</version>
        </dependency>

        <!-- H2 Database (嵌入式数据库) -->
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <version>${h2.version}</version>
            <scope>runtime</scope>
        </dependency>

        <!-- JPA for Data Persistence -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>

        <!-- Lombok (简化实体类代码) -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${lombok.version}</version>
            <optional>true</optional>
        </dependency>

        <!-- Spring Boot DevTools (热部署) -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>

        <!-- Spring Boot Test -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
```

## 1.3 应用配置文件（application.yml）

### 配置项说明

```yaml
server:
  port: 8080                    # 服务端口
  servlet:
    context-path: /sftp-manager # 应用上下文路径

spring:
  application:
    name: sftp-manager

  # H2数据库配置
  h2:
    console:
      enabled: true             # 启用H2控制台
      path: /h2-console         # 控制台访问路径
  datasource:
    url: jdbc:h2:file:./data/sftp-manager  # 数据库文件路径
    driver-class-name: org.h2.Driver
    username: sa
    password:

  # JPA配置
  jpa:
    hibernate:
      ddl-auto: update          # 自动更新表结构
    show-sql: true              # 显示SQL语句
    properties:
      hibernate:
        format_sql: true        # 格式化SQL输出

  # 文件上传配置
  servlet:
    multipart:
      enabled: true
      max-file-size: 100MB      # 单文件最大100MB
      max-request-size: 500MB   # 总请求最大500MB

# 自定义配置
app:
  sftp:
    session-timeout: 30000      # SFTP会话超时时间(ms)
    connection-timeout: 10000   # 连接超时时间(ms)
    max-retries: 3              # 连接失败重试次数

logging:
  level:
    com.sftp.manager: DEBUG
    org.hibernate.SQL: DEBUG
    org.hibernate.type.descriptor.sql.BasicBinder: TRACE
```

## 1.4 主类配置（SftpManagerApplication.java）

### 配置要点

```java
package com.sftp.manager;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;

@SpringBootApplication
@EnableJpaRepositories
public class SftpManagerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SftpManagerApplication.class, args);
    }
}
```

**说明：**
- `@SpringBootApplication`：包含自动配置、组件扫描、配置类定义
- `@EnableJpaRepositories`：启用JPA仓库支持

## 1.5 Web配置（WebConfig.java）

### 配置内容

```java
package com.sftp.manager.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("*")
                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                .allowedHeaders("*")
                .maxAge(3600);
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
    }
}
```

**配置说明：**
1. **CORS跨域配置**：允许前端访问API
   - 允许所有源（*）
   - 允许常用HTTP方法
   - 允许所有请求头
   - 预检请求缓存3600秒

2. **静态资源映射**：配置静态资源访问路径
   - 映射 `/**` 到 `classpath:/static/`
   - 支持HTML、CSS、JS等静态文件

3. **响应编码**：Spring Boot默认使用UTF-8，无需额外配置

## 实施步骤

1. **创建项目目录结构**
   ```
   mkdir -p sftp-manager/src/main/java/com/sftp/manager/{config,controller,service,model,dto}
   mkdir -p sftp-manager/src/main/resources/{static/{css,js},templates}
   ```

2. **创建pom.xml文件**：复制上面的依赖配置

3. **创建application.yml文件**：复制上面的配置内容

4. **创建SftpManagerApplication.java**：在 `src/main/java/com/sftp/manager/` 目录下

5. **创建WebConfig.java**：在 `src/main/java/com/sftp/manager/config/` 目录下

6. **验证项目结构**
   ```
   tree sftp-manager
   ```

7. **测试启动**
   ```
   mvn spring-boot:run
   ```

## 注意事项

1. **JDK版本**：确保使用JDK 8或更高版本
2. **Maven版本**：建议使用Maven 3.6+
3. **端口占用**：确认8080端口未被占用，可在application.yml中修改
4. **数据库文件**：H2数据库文件会创建在项目根目录的data文件夹下
5. **IDE配置**：如果使用IDEA，需启用Lombok插件

## 下一步

完成模块01后，继续模块02：数据模型设计