@DubboReference 调接口
  ↓
@DubboService 的 FacadeImpl 实现
  ↓
@Facade 切面统一处理
  ↓
内部 Service

Vite Proxy：开发环境前端代理，把 /api 请求直接转发到具体后端服务。
Gateway：后端统一 HTTP 入口，生产/统一入口场景下负责路由转发。
Tomcat：普通 Spring Boot MVC 微服务内部默认内嵌的 Web 服务器。
Spring MVC：在具体业务服务里找到 Controller 并执行。
Dubbo：后端微服务之间互相调用 Java 接口。

浏览器
→ Vue / Axios
→ Vite Proxy
→ 某个业务微服务的内嵌 Tomcat
→ Spring MVC / DispatcherServlet
→ Controller
→ AOP 登录切面
→ Service
→ Mapper / Redis / Dubbo / MQ
→ Spring MVC 转 JSON
→ Tomcat 返回 HTTP 响应
→ Vite Proxy
→ 浏览器

浏览器
→ Gateway
→ 具体业务微服务
→ 内嵌 Tomcat
→ Spring MVC
→ Controller
→ Service
→ Mapper / Redis / Dubbo / MQ
→ 返回响应

开发时：Vue → Vite Proxy → 具体微服务 → Tomcat → Spring MVC → Controller
统一入口时：Vue → Gateway → 具体微服务 → Tomcat → Spring MVC → Controller
服务互调时：Service → Dubbo → 另一个微服务的 Facade

/api/v1/auth   -> http://localhost:8090
/api/v1/files  -> http://localhost:8082
/api/v1/shares -> http://localhost:8085
/api/v1/users  -> http://localhost:8086
/api/v1/ai     -> http://localhost:8087

Vue / Axios
→ Vite Proxy
→ 具体后端服务

spring:
  application:
    name: @application.name@
  config:
    import: classpath:base.yml,classpath:cache.yml,classpath:config.yml,classpath:limiter.yml
  cloud:
    gateway:
      # 全局过滤器：去重响应头（解决跨域时的重复Header问题）
      default-filters:
        - DedupeResponseHeader=Access-Control-Allow-Origin, RETAIN_UNIQUE
      globalcors:
        cors-configurations:
          '[/**]':# 对所有路径生效
            allowedHeaders: '*' # 允许所有请求头
            allowedMethods: '*' # 允许所有请求方法
            allowedOrigins: '*' # 允许所有跨域域名
      routes:
        # lb:// = 微服务负载均衡转发
        # 路由1：匹配/auth/** /token/**路径，转发到networkdisk-auth微服务（负载均衡）
        - id: networkdisk-auth
          uri: lb://networkdisk-auth
          predicates:
            - Path=/auth/**,/token/**
        - id: networkdisk-business
          uri: lb://networkdisk-business
          predicates:
            - Path=/trade/**,/order/**,/user/**,/collection/**,/wxPay/**,/box/**
        - id: networkdisk-ai
          uri: lb://networkdisk-ai
          predicates:
            - Path=/api/v1/ai/**
server:
  port: 8081

/api/v1/auth/**  -> lb://networkdisk-auth
/api/v1/token/** -> lb://networkdisk-auth
/api/v1/files/** -> lb://networkdisk-files
/api/v1/shares/** -> lb://networkdisk-share
/api/v1/users/** -> lb://networkdisk-user

networkdisk-auth
networkdisk-business/networkdisk-files
networkdisk-business/networkdisk-share
networkdisk-business/networkdisk-user

@RestController
@RequestMapping("/api/v1/auth")
public class AuthController {

    @PostMapping("/login")
    public Result<String> login(@Valid @RequestBody LoginParamVO loginParam) {
        ...
    }
}

Tomcat
-> DispatcherServlet
-> 根据 @RequestMapping / @PostMapping 找方法
-> 参数绑定：@RequestBody / @RequestParam / @PathVariable
-> 参数校验：@Valid / @Validated
-> 调 Controller 方法
-> 返回 Result<T>
-> 自动转 JSON

networkdisk-common/networkdisk-rpc/src/main/resources/rpc.yml

dubbo:  
  consumer:  
    timeout: 3000  
    check: false  
  protocol:  
    name: dubbo  
    port: -1  
  
  registry:  
#    前缀 nacos:// 表示注册中心类型是 Nacos，后面跟 Nacos 的地址；  
#    服务提供者（比如文件服务、用户服务）启动时，会把自己提供的 RPC 接口注册到 Nacos；  
#    服务消费者（比如分享服务要调用文件服务）启动时，会从 Nacos 拉取可用的服务提供者地址，然后通过 Dubbo 协议发起远程调用。  
    address: nacos://127.0.0.1:8848 #首次启动前务必修改成你自己的  
    parameters:  
      namespace: networkdisk-dev     # 自己到nacos上创建一个给dubbo用的namespce，然后和这里保持一致，首次启动前务必修改成个人的  
      group: networkdisk-dev #首次启动前务必修改为个人的  
  application:  
    name: ${spring.application.name}  
    qos-enable: true  
    qos-accept-foreign-ip: false

@DubboReference(version = "1.0.0")
private UserFacadeService userFacadeService;

@DubboService(version = "1.0.0")
public class UserFacadeServiceImpl implements UserFacadeService {
}

1. Spring Cloud 服务发现 / 配置中心
2. Dubbo 注册中心

spring:  
  cloud:  
#    只要 Nacos 服务启动、地址配置正确、服务正常注册，业务代码主要通过 Dubbo 注解使用它。  
    nacos:  
      #discovery（服务注册与发现）：server-addr 指定 Nacos 服务的地址（本地 8848 端口）。  
#      作用：所有微服务启动后，都会把自己的 IP、端口、服务名注册到 Nacos 里；  
#      同时也能从 Nacos 查到其他微服务的地址，实现服务之间互相调用，不用硬编码对方的 IP 和端口。  
      discovery:  
        server-addr: 127.0.0.1:8848 #首次启动前务必修改成你自己的  
#        config（分布式配置中心）：同样指向同一个 Nacos 地址。  
#        作用：把各个微服务的配置文件（数据库地址、参数开关等）统一放到 Nacos 上管理，  
#        不用每个服务本地写死配置；还支持配置动态刷新，改完配置不用重启服务就能生效  
      config:  
        server-addr: 127.0.0.1:8848 #首次启动前务必修改成你自己的  
        file-extension: properties  
        name: ${spring.application.name}

dubbo:  
  consumer:  
    timeout: 3000  
    check: false  
  protocol:  
    name: dubbo  
    port: -1  
  
  registry:  
#    前缀 nacos:// 表示注册中心类型是 Nacos，后面跟 Nacos 的地址；  
#    服务提供者（比如文件服务、用户服务）启动时，会把自己提供的 RPC 接口注册到 Nacos；  
#    服务消费者（比如分享服务要调用文件服务）启动时，会从 Nacos 拉取可用的服务提供者地址，然后通过 Dubbo 协议发起远程调用。  
    address: nacos://127.0.0.1:8848 #首次启动前务必修改成你自己的  
    parameters:  
      namespace: networkdisk-dev     # 自己到nacos上创建一个给dubbo用的namespce，然后和这里保持一致，首次启动前务必修改成个人的  
      group: networkdisk-dev #首次启动前务必修改为个人的  
  application:  
    name: ${spring.application.name}  
    qos-enable: true  
    qos-accept-foreign-ip: false

spring:
  # Spring Data Redis 基础配置
  data:
    redis:
      host: 127.0.0.1    # Redis 服务端IP地址
      port: 6379         # Redis 服务端口，默认6379
      password: 123456   # Redis 连接密码，无密码可留空
      ssl:
        enabled: false   # 不启用SSL加密连接，本地开发默认关闭
  # Redisson 高级客户端配置

@Service 
public class ShareService { 
	// 直接注入，Spring Boot 自动装配 
	@Autowired  
	private StringRedisTemplate stringRedisTemplate;
}

// 登录：存入Token，Key规则：user:login: + 用户ID
// 调用 opsForValue()，拿到「字符串专属操作对象」
stringRedisTemplate.opsForValue()
	          // 在专属对象上调用 set 命令，执行 Redis 的 SET 指令
		     //Key规则：登录前缀（USER_LOGIN_PREFIX = "user:login:"） + 用户ID，例如：user:login:1001  
			//Value：生成的JWT令牌，Redis中存储的有效期与JWT令牌一致（1天）
    .set(BaseConstant.USER_LOGIN_PREFIX + userInfo.getUserId(), accessToken, 1, TimeUnit.DAYS);

// 鉴权：取出缓存Token与请求头比对
String cacheToken = stringRedisTemplate.opsForValue()
    .get(BaseConstant.USER_LOGIN_PREFIX + userId);

// 登出：删除Token，实现立即下线
stringRedisTemplate.delete(BaseConstant.USER_LOGIN_PREFIX + userId);

// 生成随机唯一Token
String token = UUID.randomUUID().toString();
// 拼接Redis的key：前缀 + 业务场景 + 分隔符 + 随机Token
// 形如：biz:token:create_share:xxxx-xxxx-xxxx
String tokenKey = TOKEN_PREFIX + scene + CACHE_KEY_SEPARATOR + token;
// 存入Redis，30分钟自动过期
redisTemplate.opsForValue().set(tokenKey, token, 30, TimeUnit.MINUTES);

local value = redis.call('GET', KEYS[1])
redis.call('DEL', KEYS[1])
return value

// 获取公共缓存实例
Cache cache = cacheManager.getCache(CacheConstant.CACHE_COMMON_NAME);
// 存入缓存
cache.put(cacheKey, entity);

// 合并完成后，删除对应缓存
getCache().evict(cacheKey);

spring:
  redis:
    redisson:
      config: |
        singleServerConfig:
          address: "redis://127.0.0.1:6379"
          password: "123456"
          database: 0
          connectionPoolSize: 64

@DistributeLock(
    scene = "FILE_CHUNK_UPLOAD",
    keyExpression = "#context.userId + '-' + #context.identifier"
)
public Integer chunkUpload(FileChunkUploadContext context) {
    // 分片上传业务逻辑
}

RLock rLock = redissonClient.getLock(lockKey);
try {
    rLock.lock(); // 加锁
    response = pjp.proceed(); // 执行业务方法
} finally {
    rLock.unlock(); // 释放锁（必须写在finally里，防止异常导致死锁）
}

// 投递延迟任务：任务内容、延迟时长、时间单位、队列名
delayQueueHolder.addJob(
    message,
    delayInMillis,
    TimeUnit.MILLISECONDS,
    ShareConstant.DELETE_SHARE_INFO_DELAY_QUEUE_NAME
);

RBlockingDeque<Object> blockingDeque = redissonClient.getBlockingDeque(queueName);
RDelayedQueue<Object> delayedQueue = redissonClient.getDelayedQueue(blockingDeque);
// 把任务放进延迟队列，到时间自动进入阻塞队列等待消费
delayedQueue.offer(value, delay, timeUnit);

jetcache:  
  statIntervalMinutes: 1          # 缓存统计间隔（分钟），每1分钟输出一次缓存命中统计  
  areaInCacheName: false          # 关闭缓存名里的区域前缀  
  
  # ====== 本地缓存（一级缓存） ======  
  local:  
    default:  
      type: caffeine              # 本地缓存实现：Caffeine（Java高性能本地缓存库）  
      keyConvertor: fastjson2     # Key的序列化转换工具：FastJSON2  
  
  # ====== 远程缓存（二级缓存） ======  
  remote:  
    default:  
      type: redisson              # 远程缓存实现：基于Redisson操作Redis  
      keyConvertor: fastjson2     # Key的序列化转换工具：FastJSON2  
      broadcastChannel: ${spring.application.name} # 本地缓存失效广播通道，服务名区分  
      keyPrefix: ${spring.application.name}        # 远程缓存Key前缀，用服务名隔离  
      valueEncoder: java          # 值编码方式：Java序列化  
      valueDecoder: java          # 值解码方式：Java序列化  
      defaultExpireInMillis: 5000 # 默认过期时间（毫秒），默认5秒过期

local：本地 Caffeine 一级缓存，速度快
remote：Redis/Redisson 二级缓存，多实例共享
cacheType = BOTH：本地缓存 + 远程缓存都用

/**
 * 根据用户ID查询用户信息（标准二级缓存写法）
 */
@Cached(
    name = "user:cached:id:",           // 缓存key前缀：按ID查询的用户信息缓存
    expire = 3000,                      // 缓存过期时间：3000毫秒 = 3秒
    cacheType = CacheType.BOTH,         // 启用二级缓存：本地Caffeine + 远程Redis
    key = "#userId",                    // 缓存唯一key：取方法参数userId的值，最终形如 user:cached:id:1001
    cacheNullValue = true               // 空值也缓存：数据库查不到结果时，也把「空」存进缓存
)
@CacheRefresh(
    refresh = 60,
    timeUnit = TimeUnit.HOURS
)
public UserDO findById(Long userId) {
    return userMapper.findById(userId);
}

/**
 * 根据邮箱查询用户信息
 * ⚠️ 历史遗留问题：方法参数名为 email，但缓存 key 写的是 #telephone
 *    参数名不匹配会导致缓存 key 生成异常，缓存无法正常生效
 */
// 核心缓存注解：声明该方法开启结果缓存
@Cached(
    name = "user:cached:telephone:",  // 缓存 key 的统一前缀，用于业务分类，避免不同功能的 key 冲突
    expire = 3000,                    // 缓存过期时间，单位为毫秒，即 3 秒后缓存自动失效
    cacheType = CacheType.BOTH,       // 缓存类型：BOTH = 同时启用「本地Caffeine缓存 + 远程Redis缓存」两级联动
    key = "#telephone"                // 缓存唯一 key 的 SpEL 表达式：取方法中名为 telephone 的参数值拼接最终 key
                                      // ❌ 错误点：方法形参叫 email，这里写 telephone，框架取不到值，缓存会失效
)
// 缓存刷新注解：后台定时自动刷新缓存，不用等缓存过期、用户请求时再查库
@CacheRefresh(
    refresh = 60,                     // 刷新间隔数值
    timeUnit = TimeUnit.HOURS         // 时间单位：小时，即每 60 小时自动后台刷新一次缓存
)
public UserDO findByEmail(String email) {
    // 方法本体：只负责查数据库，缓存读写逻辑由 AOP 在方法执行前后自动处理
    return userMapper.findByEmail(email);
}

第一次 findById(1001)：查缓存没有 -> 查 MySQL -> 写入本地缓存和 Redis
第二次 findById(1001)：直接走缓存，减少数据库查询

Redis：直接存 key-value，比如登录 token、临时 token、上传状态。
Redisson：用 Redis 做高级并发工具，比如分布式锁、限流、延迟队列。
JetCache：用注解缓存方法结果，减少重复查库。

spring:
  cloud:
    stream:
      rocketmq:
        binder:
          name-server: 127.0.0.1:9876

documentAiInitializer.scheduleInitialize(userId, entity.getId(), filename);

streamProducer.send(
    "aiWarmup-out-0",
    "document-ai-warmup",
    objectMapper.writeValueAsString(message)
);

aiWarmup-out-0：Spring Cloud Stream 的发送 binding 名
ai-document-warmup：RocketMQ topic，在 application.yml 里配置
document-ai-warmup：消息 tag，通过 header "TAGS" 传入

spring:
  cloud:
    stream:
      bindings:
        aiWarmup-out-0:
          destination: ai-document-warmup

spring:
  cloud:
    function:
      definition: aiWarmupConsumer
    stream:
      bindings:
        aiWarmupConsumer-in-0:
          destination: ai-document-warmup
          group: networkdisk-ai
          content-type: application/json

@Bean("aiWarmupConsumer")
public Consumer<Message<?>> aiWarmupConsumer() {
    return message -> {
        AiDocumentWarmupMessage warmupMessage = readWarmupMessage(message);
        aiApplicationService.indexFile(indexRequest);
        aiApplicationService.summarize(summaryRequest);
        aiApplicationService.generateTags(tagRequest);
    };
}

引入 networkdisk-mq
-> import stream.yml
-> 生产者配置 xxx-out-0 destination
-> StreamProducer.send("xxx-out-0", tag, json)
-> 消费者配置 function.definition 和 xxx-in-0
-> 写 @Bean("xxxConsumer") Consumer<Message<?>>

public interface StorageEngine {
    void store(StoreFileContext context);
    void delete(DeleteFileContext context);
    void storeChunk(StoreFileChunkContext context);
    void mergeFile(MergeFileContext context);
    void realFile(ReadFileContext context);
}

store()
-> 校验参数
-> doStore()

storeChunk()
-> 校验参数
-> doStoreChunk()

mergeFile()
-> 校验参数
-> doMergeFile()

LocalStorageEngine：本地磁盘存储，当前 @Primary，默认优先使用
OssStorageEngine：阿里云 OSS，配置 endpoint 后启用
FastDFSStorageEngine：FastDFS，支持普通上传/下载/删除，不支持分片上传

@Primary
@Component
public class LocalStorageEngine extends AbstractStorageEngine {
    protected void doStore(StoreFileContext context) {
        // 写入本地完整文件目录
    }

    protected void doStoreChunk(StoreFileChunkContext context) {
        // 写入本地分片目录：chunks / 文件MD5 / 分片号
    }

    protected void doMergeFile(MergeFileContext context) {
        // 按顺序追加分片，合成完整文件
    }
}

第一次分片：初始化 multipart upload，拿 uploadId
每个分片：uploadPart
全部完成：completeMultipartUpload
中间状态：uploadId/objectKey 缓存在 Redis/CacheManager
并发控制：@DistributeLock 防止重复初始化

protected void doStore(StoreFileContext context) {
    StorePath storePath = fastFileStorageClient.uploadFile(...);
    context.setRealPath(storePath.getFullPath());
}

protected void doStoreChunk(...) {
    throw new SystemException("FastDFS不支持分片上传");
}

com:
  disk:
    ai:
      provider:
        type: openai-compatible
        base-url: https://dashscope.aliyuncs.com/compatible-mode/v1
        chat-path: /chat/completions
        embeddings-path: /embeddings
        chat-model: qwen3.5-plus
        embedding-model: qwen3-vl-embedding
        embedding-dimension: 768

AI 消费 MQ / 前端调用 AI 接口
-> AiApplicationServiceImpl
-> AiSourceFileLoader
-> Dubbo 调 files 服务拿 realPath
-> StorageEngine.realFile() 读取文件字节
-> Apache Tika 解析为纯文本
-> ParagraphTextChunker 切块
-> EmbeddingClient 调模型生成向量
-> pgvector 入库

AutoDetectParser parser = new AutoDetectParser();
BodyContentHandler handler = new BodyContentHandler(-1);
parser.parse(inputStream, handler, metadata, new ParseContext());

String plainText = normalize(handler.toString());

PDF / Word / Excel / PPT / txt / md / html / json 等文件
-> 自动识别格式
-> 提取纯文本
-> 提取 mediaType、metadata

restClient.post()
    .uri(baseUrl + chatPath)
    .headers(headers -> headers.setBearerAuth(apiKey))
    .body(request)
    .retrieve()
    .body(ChatCompletionResponse.class);

request.setModel(properties.getEmbeddingModel());
request.setInput(texts);
request.setDimensions(properties.getEmbeddingDimension());

chat-model：用于摘要、标签、问答
embedding-model：用于生成向量
embedding-dimension：必须和 pgvector.dimension 一致
api-key：真实项目不要写死在仓库里，放环境变量或配置中心

com:
  disk:
    ai:
      pgvector:
        enabled: true
        init-schema: true
        url: jdbc:postgresql://127.0.0.1:5432/networkdisk_ai
        username: postgres
        password: 123456
        dimension: 768

@Bean(name = "pgVectorDataSource")
public DataSource pgVectorDataSource(PgVectorProperties properties) {
    HikariDataSource dataSource = new HikariDataSource();
    dataSource.setDriverClassName("org.postgresql.Driver");
    dataSource.setJdbcUrl(properties.getUrl());
    return dataSource;
}

create extension if not exists vector;

ai_document_index：每个文档的索引摘要信息
ai_document_chunk_vector：每个文本块及其 embedding 向量
ai_document_result：AI 摘要、标签结果缓存

embedding vector(768) not null

vectorStore.replaceDocument(sourceFile, parsedDocument, vectorChunks);

删除旧 chunk
upsert ai_document_index
批量插入 ai_document_chunk_vector

select chunk_text, 1 - (embedding <=> ?) as similarity
from ai_document_chunk_vector
where user_id = ? and user_file_id = ?
order by embedding <=> ?
limit ?

similarity = 1 - distance

用户提问
-> 对问题生成 embedding
-> pgvector 找 topK 相关文本块
-> 把相关文本块拼成上下文
-> 调 chat model 生成回答

文件上传
-> StorageEngine 保存文件
-> files 服务发 RocketMQ 消息
-> AI 服务消费消息
-> Tika 解析文档
-> OpenAI-compatible 生成 embedding / 摘要 / 标签
-> PostgreSQL + pgvector 保存索引和结果
-> 用户问答时从 pgvector 检索相关片段再调用模型回答

@Around("@annotation(com.disk.rpc.facade.Facade)")
public Object facade(ProceedingJoinPoint pjp) throws Exception {
    ...
}

1. 记录方法开始日志
2. 统计方法执行耗时
3. 统一校验请求参数
4. 调用 pjp.proceed() 执行真正的目标方法
5. 如果返回值是 BaseResponse 子类，补全 responseCode
6. 如果目标方法抛异常，统一包装成失败响应
7. 打印结束日志或异常日志

调用方发起 Dubbo 调用
→ 目标服务找到 @DubboService 实现类
→ 目标方法上有 @Facade
→ 先进入 FacadeAspect
→ 参数校验、日志记录
→ pjp.proceed()
→ 真正执行业务方法
→ 返回 BaseResponse 子类
→ FacadeAspect 补全响应信息
→ 返回调用方

{
  "email": "[已隐藏邮箱]",
  "password": "123456",
  "nickName": "小白"
}

user 表保存的是“用户账号本身”。
注册成功后，系统先有了这个用户，后面所有文件、分享、回收站数据都可以通过 user_id 和这个用户关联起来。

filename = 全部文件
parent_id = 0
folder_flag = 1
real_file_id = NULL

user_id = 当前用户ID
parent_id = 0
folder_flag = 1
deleted = 0

user.id        = 用户 ID
user_file.id   = 文件或文件夹 ID
rootFileId     = 当前用户根目录那条 user_file.id

currentFolderId：站在用户视角，我当前正在看的文件夹 ID。
parentId：站在查询视角，要查 parent_id = 当前文件夹 ID 的子文件。

file 表记录真实文件；
user_file 表记录用户在根目录下看到一个叫 a.pdf 的文件；
user_file.real_file_id = file.id，把用户视图和真实文件关联起来。

file 管“真实文件本体的元数据”，user_file 管“用户看到的文件入口”。

USER_LOGIN_{userId}

key   = USER_LOGIN_10001
value = 当前登录签发的 JWT token

{
  "success": true,
  "data": "eyJhbGciOiJIUzI1NiJ9..."
}

Authorization: eyJhbGciOiJIUzI1NiJ9...

1. 从 Authorization 请求头取出 token
2. 解析 JWT，得到 userId
3. 用 userId 拼 Redis key：USER_LOGIN_{userId}
4. 去 Redis 取出服务端保存的 token
5. 比较请求头 token 和 Redis token 是否一致
6. 一致，说明登录有效
7. 把 userId 放入 UserIdUtil
8. 放行 Controller 方法

这个用户当前有效的登录 token 是什么

前端提交邮箱、密码、昵称
→ auth 服务接收注册请求
→ 调 user 服务
→ user 服务插入 user 表
→ auth 服务再调 files 服务
→ files 服务插入 user_file 根目录记录
→ 注册成功

注册 = 创建用户账号 + 创建用户根目录

user 表新增一条用户记录
user_file 表新增一条根目录记录

前端提交邮箱、密码
→ auth 服务查询 user 表
→ 登录成功后生成 JWT
→ 把 JWT 存 Redis
→ 把 JWT 返回给前端

user 表用来确认用户是谁
Redis 用来保存登录态

前端带 token 请求 /api/v1/users/get-user-info
→ 后端切面校验 Redis 登录态
→ 校验通过后得到 userId
→ 查询 user 表拿用户信息
→ 查询 user_file 表拿根目录信息
→ 返回 userInfo 和 rootFileId

Redis 校验是否登录
user 表查用户资料
user_file 表查根目录

user 表：
保存用户账号信息，比如邮箱、昵称、密码哈希、头像、容量等。它回答的是“这个用户是谁”。

user_file 表：
保存用户看到的文件和文件夹目录结构。注册时会自动创建一条根目录记录，后端返回给前端的 rootFileId，本质上就是这条根目录 user_file 记录的加密 ID。它回答的是“这个用户的文件目录从哪里开始”。

Redis：
保存登录态。登录成功后，后端生成 JWT，并以 USER_LOGIN_{userId} 为 key 存到 Redis。之后每次需要登录的请求，后端都会用请求头里的 token 和 Redis 里的 token 做一致性校验。它回答的是“这个请求的用户现在是否还处于登录状态”。

user：用户是谁
user_file：用户有哪些文件夹和文件
Redis：用户现在有没有登录

浏览器 → Vite Proxy → 具体微服务

浏览器 → Vite Proxy → Spring Cloud Gateway → 具体微服务

Register.vue
→ 表单校验
→ userStore.registerAction()
→ api/auth.js 发送 POST /api/v1/auth/register
→ Vite Proxy / Gateway 转发请求
→ networkdisk-auth 的 Tomcat 接收请求
→ Spring MVC 找到 AuthController.register()
→ AuthController 把 RegisterParamVO 转成 RegisterContext
→ AuthServiceImpl.register() 编排注册流程
→ Dubbo 调 networkdisk-user 创建用户
→ Dubbo 调 networkdisk-files 创建用户根目录
→ AuthServiceImpl 返回 userId
→ AuthController 包装 Result 返回前端
→ 前端提示注册成功，跳转登录页

用户自己的网盘首页目录

user_file
├── id：根目录 ID，也就是 rootFileId
├── user_id：归属哪个用户
├── parent_id：顶级父节点 ID
├── filename：根目录名称，例如“全部文件”或“我的网盘”
├── folder_flag：是文件夹
├── real_file_id：为空，因为文件夹没有真实文件内容
├── deleted：未删除

AuthServiceImpl
→ 构造 UserFileOperateRequest
   - name = 用户根目录名称
   - userId = 新注册用户 ID
   - parentId = ROOT_PARENT_ID
→ Dubbo 调 userFileFacadeService.createUserRootFile()
→ files 服务的 Facade 接收请求
→ 转成 CreateFolderContext
→ UserFileServiceImpl.createFolder()
→ assembleUserFolder() 组装 UserFileDO
→ save(UserFileDO) 插入 user_file 表
→ 返回根目录 ID
→ auth 服务确认创建成功
→ 注册流程结束

user 服务：
UserService.register()
→ 插入 user 表
→ 返回 UserDO
→ 转成 UserInfo
→ 包装 UserOperatorResponse<UserInfo>
→ 返回 auth 服务

files 服务：
UserFileServiceImpl.createFolder()
→ 插入 user_file 表
→ 返回 rootFileId
→ 包装 UserFileOperateResponse<Long>
→ 返回 auth 服务

auth 服务：
AuthServiceImpl.register()
→ 确认用户创建成功、根目录创建成功
→ 返回 userId 给 AuthController

Controller：
AuthController.register()
→ IdUtil.encrypt(userId)
→ Result.success(...)
→ Spring MVC 转 JSON
→ Tomcat 返回 HTTP 响应
→ Vite Proxy / Gateway 返回前端

前端：
Axios 响应拦截器处理响应
→ Pinia registerAction 返回 result
→ Register.vue 显示注册成功
→ router.push('/login')

Login.vue
→ 表单校验
→ userStore.loginAction()
→ api/auth.js 发送 POST /api/v1/auth/login
→ Vite Proxy / Gateway 转发请求
→ networkdisk-auth 的 Tomcat 接收请求
→ Spring MVC 找到 AuthController.login()
→ AuthServiceImpl 校验邮箱和密码
→ 校验成功后生成 JWT token
→ Redis 保存登录态
→ token 返回给前端
→ 前端保存 token 到 Pinia / Cookie
→ 前端调用 getUserInfoAction()
→ 请求 user 服务获取用户信息和 rootFileId
→ fileStore.initRoot() 初始化根目录
→ 进入首页

getUserInfoAction()

GET /api/v1/users/get-user-info
Authorization: JWT token字符串

1. AOP 捕获匹配切点的 Controller 方法执行。
2. 判断方法上有没有 @LoginIgnore。
3. 没有 @LoginIgnore，说明需要登录校验。
4. 从请求头 Authorization 或请求参数 authorization 取 token。
5. JWTUtil 解析 token，得到 userId。
6. 根据 USER_LOGIN_PREFIX + userId 去 Redis 查询服务端保存的 token。
7. 比较请求 token 和 Redis token 是否一致。
8. 不一致：返回未登录错误，Controller 不执行。
9. 一致：UserIdUtil.set(userId)，保存当前请求用户 ID。
10. proceedingJoinPoint.proceed() 放行，Controller 正式执行。

Long userId = UserIdUtil.get()

userService.getUserInfo(userId)

1. 根据 userId 查询 user 表，拿到昵称、头像等用户基础信息。
2. 通过 Dubbo 调 files 服务，查询该用户的网盘根目录信息。

UserInfoVO
├── userId
├── nickname
├── profilePhotoUrl
├── rootFileId
└── rootFilename

userId：表示当前用户是谁。
rootFileId：表示这个用户网盘的顶层文件夹是哪一条记录。

parentId = rootFileId

密码哈希：保护密码。
JWT：证明登录身份。
Redis token：保存服务端登录态。
ID 加密：避免直接暴露数据库 ID。
文件 MD5：文件校验和秒传。

Register.vue 表单校验
→ Pinia registerAction
→ Axios POST /api/v1/auth/register
→ auth 服务 AuthController.register
→ RegisterParamVO 转 RegisterContext
→ AuthServiceImpl 编排流程
→ Dubbo 调 user 服务创建用户
→ UserService.register 插入 user 表，密码哈希存入 password_hash
→ Dubbo 调 files 服务创建用户根目录
→ UserFileService.createFolder 插入 user_file 表
→ auth 确认两步成功
→ 返回注册成功
→ 前端跳转登录页

Login.vue 表单校验
→ Pinia loginAction
→ Axios POST /api/v1/auth/login
→ auth 服务校验邮箱和密码
→ 密码正确则生成 JWT token
→ Redis 保存 USER_LOGIN_PREFIX + userId 对应 token
→ token 返回前端
→ 前端保存 token 到 Pinia / Cookie
→ 调 getUserInfoAction
→ 请求 user 服务获取用户信息
→ UserInfoLoginAspect 校验 Authorization token
→ UserService 查询用户表 + Dubbo 查询根目录
→ 返回 userId、昵称、头像、rootFileId、rootFilename
→ fileStore.initRoot 使用 rootFileId 加载首页文件列表

注册负责创建账号和根目录；登录负责校验密码、生成 token、保存登录态；登录后获取用户信息负责拿到 rootFileId，前端再用 rootFileId 加载网盘首页文件。

// 用户输入 el-input
// → el-input 内部触发 change / input / blur 事件  
// → el-form-item 收到这个字段发生了变化或失焦  
// → el-form-item 通过 prop="email" 知道自己管 email 字段  
// → 它去 el-form 的 model 中取 registerForm.email// → 它去 el-form 的 rules 中找 registerRules.email// → 按 trigger 判断哪些规则该执行  
// → 执行 required/type/validator 等校验  
// → 成功就不提示，失败就在表单项下面显示 message

<el-form
  ref="registerFormRef"
  :model="registerForm"
  :rules="registerRules"
>
  <el-form-item prop="email">
    <el-input v-model="registerForm.email" />
  </el-form-item>
</el-form>

// handleRegister()  
// → registerFormRef.value.validate()  
// → el-form 找到自己下面所有 el-form-item// → 每个 el-form-item 根据自己的 prop 找对应字段  
// → email 检查 registerRules.email
// → nickName 检查 registerRules.nickName
// → password 检查 registerRules.password
// → confirmPassword 检查 registerRules.confirmPassword
// → 只要一个失败，validate() 就失败  
// → 全部成功，才继续执行后面的注册请求

用户输入注册信息
→ v-model 同步到 registerForm
→ el-form-item 根据 prop 关联字段和规则
→ 输入框 blur/change 时自动触发局部校验
→ 点击注册按钮
→ handleRegister()
→ registerFormRef.value.validate() 触发整体验证
→ 校验通过后调用 userStore.registerAction({ email, nickName, password })
→ 调用后端注册接口
→ 注册成功后提示并跳转登录页

registerForm.email
registerForm.password

登录 token
当前用户信息
用户根目录 ID
是否已登录

const token = ref(Cookies.get('token') || '')  登录凭证
const userInfo = ref({})  当前用户信息
const rootFileId = ref('')  用户根目录 ID
const isLoggedIn = computed(() => !!token.value)  是否已登录

const loginAction = async (loginData) => { ... }
const registerAction = async (registerData) => { ... }
const getUserInfoAction = async () => { ... }
const logout = () => { ... }

await register(registerForm)

const result = await userStore.registerAction(...)

const userStore = useUserStore()

Register.vue 页面
→ 调 userStore.registerAction()
→ store 内部调 api/auth.js 的 register()
→ axios 请求后端
→ store 把结果整理成 { success, data/message }
→ 页面根据 result 提示成功或失败

页面组件：负责展示 UI、收集输入、提示结果
Pinia store：负责用户相关状态和业务动作
api/auth.js：负责具体 HTTP 请求

Register.vue = 前台窗口，负责跟用户交互
Pinia userStore = 用户业务办事处，负责注册/登录/保存 token
api/auth.js = 打电话的人，负责真正联系后端接口
后端 = 真正办理业务的系统

Register.vue
→ useUserStore() 拿到用户仓库
→ userStore.registerAction()
→ register(registerData)
→ Axios POST /api/v1/auth/register
→ 后端返回
→ registerAction 整理结果
→ Register.vue 拿到 result

export const useUserStore = defineStore('user', () => {
  ...
  return {
    token,
    userInfo,
    rootFileId,
    isLoggedIn,
    loginAction,
    registerAction,
    getUserInfoAction,
    logout
  }
})

return {
  token,
  userInfo,
  registerAction
}

const userStore = useUserStore()
userStore.registerAction(...)
userStore.token
userStore.userInfo

Pinia store 是 Vue 前端的全局状态仓库。它把多个页面都要用的数据和方法集中管理起来，例如 token、用户信息、登录、注册、退出。页面通过 useUserStore() 拿到这个仓库，再调用里面的方法或读取里面的数据。

'/api/v1/auth': {
  target: 'http://localhost:8090', // 后端认证微服务地址
  changeOrigin: true // 修改请求源标识，避免后端校验Origin拦截请求
}

浏览器
→ Vite 开发服务器 5173
→ Vite Proxy 转发到 networkdisk-auth 8090
→ auth 服务内置 Tomcat
→ Spring MVC
→ AuthController.register()

浏览器
→ Vite 开发服务器 5173
→ Vite Proxy 转发到 Spring Cloud Gateway 8081
→ Gateway 根据 /api/v1/auth 转发到 networkdisk-auth 8090
→ auth 服务内置 Tomcat
→ Spring MVC
→ AuthController.register()

src/main/resources/application.yml

networkdisk-auth
→ Dubbo 调 networkdisk-user 创建用户
→ Dubbo 调 networkdisk-files 创建用户根目录

浏览器 / Vite
-> spring gate way
→ networkdisk-auth 的 Tomcat
→ Spring MVC
→ AuthController.register()
→ AuthServiceImpl.register()
→ Dubbo 调 networkdisk-user 创建用户
→ Dubbo 调 networkdisk-files 创建用户根目录
→ 返回 Result 给前端

Controller 层一般不写复杂业务，它主要负责：
	接收请求
	校验参数
	转换对象
	调用 Service
	包装返回结果

RegisterContext registerContext = authConvertor.registerParamToRegisterContext(registerParam);

RegisterParamVO：跟着前端页面变
RegisterContext：跟着后端业务流程变
UserEntity：跟着数据库表结构变
UserVO：跟着前端展示结果变

RegisterParamVO：前端传什么，我就接什么，属于 Controller 层入参对象。
RegisterContext：注册业务需要什么，我就放什么，属于 Service 层业务上下文。
MapStruct：负责把一个对象的字段复制到另一个对象，避免手写 set。这行代码：把“前端注册表单”转换成“后端注册业务上下文”。

Long userId = authService.register(registerContext);

@DubboReference(version = "1.0.0")
private UserFacadeService userFacadeService;

@DubboReference(version = "1.0.0")
private UserFileFacadeService userFileFacadeService;

userFacadeService.register(userRegisterRequest);

networkdisk-auth
→ Dubbo 网络调用
→ networkdisk-user
→ UserFacadeServiceImpl.register()

1. 调 user 服务创建用户
2. 调 files 服务创建用户根目录
3. 两步都成功后，把 userId 返回给 Controller

AuthController.register()
  ↓
AuthServiceImpl.register()
  ↓ 主动调用
userFacadeService.register(userRegisterRequest)
  ↓ Dubbo 远程调用
UserFacadeServiceImpl.register(...)
  ↓ 因为目标方法上有 @Facade
FacadeAspect.facade(...)
  ↓
pjp.proceed()
  ↓
真正执行 UserFacadeServiceImpl.register(...)

@Facade
@Override
public UserOperatorResponse<UserInfo> register(UserRegisterRequest request) {
    ...
}

1. 接收 auth 服务传来的 UserRegisterRequest
2. 调用 userService.register() 真正创建用户
3. 把 UserDO 转成 UserInfo 返回给 auth 服务

`UserDO：数据库实体，user 服务内部使用`
`UserInfo：远程调用返回 DTO，给 auth 等其他服务使用`

public UserDO register(UserRegisterRequest request) 

public UserDO register(UserRegisterRequest request) {  
    if (request == null || StringUtils.isBlank(request.getEmail()) || StringUtils.isBlank(request.getPassword())) {  
        throw new UserException(USER_OPERATE_FAILED);  
    }  
    if (userMapper.findByEmail(request.getEmail()) != null) {  
        throw new UserException(DUPLICATE_TELEPHONE_NUMBER);  
    }  
  
    String nickName = StringUtils.isBlank(request.getNickname())  
            ? StringUtils.defaultIfBlank(StringUtils.substringBefore(request.getEmail(), "@"), request.getEmail())  
            : request.getNickname();  
  
    UserDO insertDO = new UserDO();  
    insertDO.setEmail(request.getEmail());  
    insertDO.setNickName(nickName);  
    //生成唯一用户ID（雪花算法/Snowflake）  
    //IdUtil.get() 生成一个全局唯一的数字ID，作为用户主键，不依赖数据库自增，适合分布式系统  
    insertDO.setId(IdUtil.get());  
    //密码不能明文存储，用工具类加密后再存  
    //当前项目使用 MD5 把明文密码转换成 password_hash 后入库。
    //真实生产项目更推荐 BCrypt、PBKDF2、Argon2 等带盐哈希算法，单纯 MD5 安全性较弱。
    insertDO.setPasswordHash(PasswordUtil.encryptPassword(request.getPassword()));  
    //置已用存储空间 = 0（新用户还没存任何文件）  
    //0L 表示 long 类型的 0    insertDO.setUseSpace(0L);  
    //设置总可用存储空间 = 初始配额（1GB）  
    //从常量类里读取，方便统一修改  
    insertDO.setTotalSpace(UserConstants.USER_INIT_SPACE);  
    //设置逻辑删除标记 = 未删除（0 或 false）  
    //不会真正删数据，只是打标记，方便数据恢复  
    insertDO.setDeleted(DeleteEnum.NO.getCode());  
    // 这里设置的是 lastLoginTime 字段，字段含义是最后登录时间。
    //当前代码在注册时直接设置为当前时间，可以理解为初始化该字段；真正的创建时间由 gmt_create 字段记录。
    //new Date() 获取当前系统时间  
    insertDO.setLastLoginTime(new Date());  
    //设置默认头像（一个 GitHub 的公共头像地址）  
    //新用户注册时给个默认头像，后续可以自己修改  
    insertDO.setProfilePhotoUrl("https://avatars.githubusercontent.com/u/25891014?v=4");  
    userMapper.insert(insertDO);  
    return insertDO;  
}

1. 判断请求对象是否为空
2. 判断 email/password 是否为空
3. 根据 email 查询数据库，检查用户是否已存在
4. 生成昵称
5. 创建 UserDO 数据库实体
6. 生成用户 ID
7. 加密密码
8. 初始化用户空间
9. 设置默认头像
10. 调用 userMapper.insert() 插入 user 表
11. 返回插入后的 UserDO

userMapper.insert(insertDO);

BaseMapper<UserDO>

insert
deleteById
updateById
selectById
selectList

userMapper.insert(insertDO)

insert into user (
  id,
  nick_name,
  use_space,
  total_space,
  email,
  password_hash,
  last_login_time,
  profile_photo_url,
  deleted
) values (?, ?, ?, ?, ?, ?, ?, ?, ?)

mybatis:
  configuration:
    map-underscore-to-camel-case: true

@TableName("user")// 告诉 MyBatis-Plus：这个类对应数据库里的 user 表

UserService
→ UserMapper
→ MyBatis / MyBatis-Plus
→ Druid 数据库连接池
→ MySQL network_disk.user 表

UserOperatorResponse<UserInfo> response = new UserOperatorResponse<>();

UserOperatorResponse
  ├── success: true
  └── data: UserInfo
        ├── userId
        ├── nickName
        ├── email
        └── profilePhotoUrl

//`register`是数据库查出来的`UserDO`，通过 MapStruct 转换器，
//把数据库实体转换成前端专用的`UserInfo`视图 VO，过滤密码、乐观锁等敏感内部字段
UserInfo userInfoVO = UserConvertor.INSTANCE.mapToVo(register);
response.setSuccess(true);//表示这次注册调用成功
response.setData(userInfoVO);//把真正要返回的数据放进响应对象的 `data` 字段里

// UserFileOperateReqest：入参请求实体（DTO），用来封装创建文件夹需要的全部参数
UserFileOperateReqest userFileOperateReqest = new UserFileOperateReqest();

// 设置文件夹名称：常量统一规定用户根目录名称（比如“我的网盘”）
userFileOperateReqest.setName(BaseConstant.USER_ROOT_FILE);

// 设置当前注册用户ID，标记这个文件夹归属哪个用户
userFileOperateReqest.setUserId(userInfo.getUserId());

// 设置父目录ID：常量ROOT_PARENT_ID代表顶级根节点，说明这是用户第一层根目录
userFileOperateReqest.setParentId(BaseConstant.ROOT_PARENT_ID);

userFileFacadeService.createUserRootFile(userFileOperateReqest);

@Facade
@Override
public UserFileOperateResponse<Long> createUserRootFile(UserFileOperateReqest request) {
    ...
}

AuthServiceImpl.register()
→ userFileFacadeService.createUserRootFile(...)
→ Dubbo 调 files 服务
→ UserFileFacadeImpl.createUserRootFile()
→ @Facade 触发 FacadeAspect
→ pjp.proceed()
→ 真正执行 createUserRootFile()
→ userFileService.createFolder()
→ 插入 user_file 根目录记录
→ 返回 UserFileOperateResponse<Long>

networkdisk-auth
→ Dubbo
→ networkdisk-files
→ UserFileFacadeImpl.createUserRootFile()
→ UserFileServiceImpl.createFolder()
→ 插入 user_file 表

 @Facade//门面注解，分层开发规范注解：标识当前类是门面层 Facade，介于业务注册层和底层文件 userFileService 之间；  
// 入参：UserFileOperateReqest 上层传过来的创建文件夹请求DTO  
    @Override  
    public UserFileOperateResponse<Long> createUserRootFile(UserFileOperateReqest request) {  
        // 1. 创建上下文对象 CreateFolderContext（领域上下文，内部业务传参载体）  
        CreateFolderContext createFolderContext = new CreateFolderContext();  
        // 把外层请求DTO的参数，转存到内部业务上下文  
        createFolderContext.setFolderName(request.getName());  
        createFolderContext.setUserId(request.getUserId());  
        createFolderContext.setParentId(request.getParentId());  
  
        // 2. 调用底层文件核心service，真正执行创建文件夹逻辑，返回新建文件夹ID  
        Long folder = userFileService.createFolder(createFolderContext);  
  
        // 3. 实例化统一包装响应对象（就是前面讲的外层包裹对象）  
        UserFileOperateResponse<Long> response = new UserFileOperateResponse();  
        // 标记接口执行成功  
        response.setSuccess(true);  
        // 将生成的文件夹ID塞入响应的data中  
        response.setData(folder);  
        // 返回包装好的标准响应给上层注册业务  
        return response;  
    }  
  
}

@Override
public Long createFolder(CreateFolderContext context) {
    // 1. 上下文参数 → 组装数据库实体 UserFileDO
    UserFileDO entity = assembleUserFolder(context);
    // 2. MyBatis-Plus 自带 save() 方法，执行insert插入数据库
    if (!save((entity))) {
        // 插入失败（数据库报错/影响行数0），抛出系统自定义异常
        throw new SystemException("保存文件信息失败");
    }
    // 插入成功，返回自生成的文件夹唯一ID，给上层Facade封装进响应data
    return entity.getId();
}

public class UserFileServiceImpl extends ServiceImpl<UserFileMapper, UserFileDO>

save(entity)

insert into user_file (
  id,
  user_id,
  parent_id,
  real_file_id,
  filename,
  folder_flag,
  file_size_desc,
  file_type,
  deleted,
  create_user,
  update_user
) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)

return entity.getId();

private UserFileDO assembleUserFolder(CreateFolderContext context) {
    UserFileDO entity = new UserFileDO();
    // 雪花算法生成全局唯一主键ID（不用数据库自增）
    entity.setId(IdUtil.get());
    // 当前文件夹归属用户ID
    entity.setUserId(context.getUserId());
    // 父级文件夹ID（用户根目录就是顶级父ID）
    entity.setParentId(context.getParentId());
    // 文件夹无真实存储文件，置空
    entity.setRealFileId(null);
    // 文件夹名称（我的网盘）
    entity.setFilename(context.getFolderName());
    // 标记该记录是文件夹类型（区分文件）
    entity.setFolderFlag(FolderFlagEnum.YES.getCode());
    // 文件夹无文件大小，置空
    entity.setFileSizeDesc(null);
    // 文件类型为空（只有文件才有后缀类型）
    entity.setFileType(null);
    // 逻辑删除：0=未删除
    entity.setDeleted(DeleteEnum.NO.getCode());
    // 创建人、修改人都为当前用户
    entity.setCreateUser(context.getUserId());
    entity.setUpdateUser(context.getUserId());

    // 处理同目录下重名文件夹逻辑（防重名校验）
    handleDuplicateFilename(entity);
    return entity;
}

AuthController.register()
→ AuthServiceImpl.register()

第一段：创建用户
→ userFacadeService.register()
→ UserFacadeServiceImpl.register()
→ UserService.register()
→ userMapper.findByEmail()
→ userMapper.insert()
→ UserDO 转 UserInfo
→ UserOperatorResponse<UserInfo> 返回 auth

第二段：创建根目录
→ AuthServiceImpl 取出 UserInfo.userId
→ 构造 UserFileOperateReqest
→ userFileFacadeService.createUserRootFile()
→ UserFileFacadeImpl.createUserRootFile()
→ UserFileServiceImpl.createFolder()
→ assembleUserFolder()
→ save(UserFileDO)
→ 插入 user_file 表
→ UserFileOperateResponse<Long> 返回 auth

第三段：返回前端
→ AuthServiceImpl 返回 userId
→ AuthController 加密 userId
→ Result.success(...)
→ 前端提示注册成功

1. user 服务创建用户，插入 user 表
2. files 服务创建用户根目录，插入 user_file 表

`UserOperatorResponse<UserInfo>`
  ├── success = true
  └── data = UserInfo
        ├── userId
        ├── nickName
        ├── email
        └── profilePhotoUrl

UserFileOperateResponse<Long>
  ├── success = true
  └── data = 根目录ID

user 服务创建用户成功
files 服务创建根目录成功

return userInfo.getUserId();

Long userId = authService.register(registerContext);

AuthServiceImpl.register()
→ 返回 Long 类型 userId
→ AuthController.register() 中的 Long userId 接收

return Result.success(IdUtil.encrypt(userId));

1. IdUtil.encrypt(userId)：把 Long 类型用户 ID 加密成字符串
2. Result.success(...)：把结果包装成统一返回格式

10001

{
  "success": true,
  "code": "SUCCESS",
  "message": "SUCCESS",
  "data": "加密后的用户ID"
}

@RestController

方法返回值不是页面名，而是响应体数据。

Result.success(...)

Result<String>

{
  "code": "SUCCESS",
  "success": true,
  "message": "SUCCESS",
  "data": "加密后的用户ID"
}

HTTP 状态码：200
响应头：Content-Type: application/json
响应体：Result 对象转成的 JSON 字符串

Spring MVC 负责生成响应内容
Tomcat 负责通过网络把响应发回去

浏览器
→ Vite dev server:5173
→ networkdisk-auth:8090

networkdisk-auth:8090
→ Vite dev server:5173
→ 浏览器

response = {
  status: 200,
  headers: {...},
  data: {
    code: 'SUCCESS',
    success: true,
    message: 'SUCCESS',
    data: '加密后的用户ID'
  }
}

instance.interceptors.response.use((response) => {
  if (response.data && response.data.code !== undefined) {
    if (response.data.code === 200 || response.data.success === true) {
      return response.data
    }
  }
})

response.data.success === true

response.data

{
  code: 'SUCCESS',
  success: true,
  message: 'SUCCESS',
  data: '加密后的用户ID'
}

export function register(data) {
  return authRequest({
    url: '/register',
    method: 'post',
    data
  })
}

{
  success: true,
  code: 'SUCCESS',
  message: 'SUCCESS',
  data: '加密后的用户ID'
}

const response = await register(registerData)

response

if (response?.success) {
  return { success: true, data: response.data }
}
return { success: false, message: response?.message || '注册失败' }

{
  success: true,
  data: '加密后的用户ID'
}

const result = await userStore.registerAction({
  email: registerForm.email,
  nickName: registerForm.nickName,
  password: registerForm.password
})

result

if (result.success) {
  ElMessage.success('注册成功，请登录')
  router.push('/login')
} else {
  ElMessage.error(result.message || '注册失败')
}

注册成功：提示成功，跳转登录页
注册失败：提示错误信息

第一段：user 服务创建用户后返回 auth 服务

UserService.register()
→ userMapper.insert(insertDO) 插入 user 表
→ 返回 UserDO insertDO
→ UserFacadeServiceImpl.register() 中的 UserDO register 接收

UserFacadeServiceImpl.register()
→ UserDO 转 UserInfo
→ 包装 UserOperatorResponse<UserInfo>
→ 返回给 auth 服务
→ AuthServiceImpl.register() 中的 register 接收

AuthServiceImpl.register()
→ 校验 register 是否为空、success 是否为 true、data 是否存在
→ register.getData() 取出 UserInfo
→ userInfo.getUserId() 得到新用户 ID


第二段：auth 服务调用 files 服务创建根目录后返回 auth 服务

AuthServiceImpl.register()
→ 构造 UserFileOperateReqest
→ 调用 userFileFacadeService.createUserRootFile()

UserFileFacadeImpl.createUserRootFile()
→ UserFileServiceImpl.createFolder()
→ save(UserFileDO) 插入 user_file 表
→ 返回 Long folder 根目录 ID
→ 包装 UserFileOperateResponse<Long>
→ 返回给 auth 服务
→ AuthServiceImpl.register() 中的 userRootFile 接收

AuthServiceImpl.register()
→ 校验 userRootFile 是否为空、success 是否为 true
→ 确认根目录创建成功


第三段：auth 服务返回给 Controller

AuthServiceImpl.register()
→ 返回 Long userId
→ AuthController.register() 中的 userId 接收

AuthController.register()
→ IdUtil.encrypt(userId) 加密用户 ID
→ Result.success(加密后的 userId)
→ 返回 Result<String>
→ Spring MVC 接收


第四段：Spring MVC / Tomcat 返回 HTTP 响应

Spring MVC
→ 把 Result<String> 转成 JSON
→ 交给 Tomcat

Tomcat
→ 生成 HTTP 响应
→ 返回给 Vite 代理

Vite
→ 把后端响应转发给浏览器


第五段：前端 Axios / Pinia / 页面接收结果

浏览器
→ Axios 接收 HTTP 响应

Axios 响应拦截器
→ 判断 response.data.success === true
→ 返回 response.data

api/auth.js 的 register()
→ 返回给 Pinia 的 registerAction()

Pinia registerAction()
→ const response = await register(registerData)
→ 判断 response.success
→ 返回 { success: true, data: response.data }

Register.vue
→ const result = await userStore.registerAction(...)
→ result 接收 Pinia 返回结果
→ result.success 为 true
→ ElMessage.success('注册成功，请登录')
→ router.push('/login')

注册的返回不是直接从 files 服务回前端，而是先 user 服务返回用户信息给 auth，auth 再调用 files 创建根目录，根目录创建成功后 auth 才把最终注册结果返回给 Controller，最后由 Spring MVC/Tomcat/Vite/Axios 一层层回到页面。

user 服务返回：
UserService → UserFacadeServiceImpl → AuthServiceImpl

files 服务返回：
UserFileServiceImpl → UserFileFacadeImpl → AuthServiceImpl

HTTP 返回：
AuthServiceImpl → AuthController → Spring MVC → Tomcat → Vite → 浏览器 → Axios → Pinia → Register.vue

注册：创建 user + 创建 user_file 根目录
登录：查询 user + 生成 token + 存 Redis + 前端保存 token + 拉取用户信息

Login.vue
→ userStore.loginAction()
→ api/auth.js 的 login()
→ Axios POST /api/v1/auth/login
→ Vite 代理到 networkdisk-auth:8090
→ AuthController.login()
→ AuthServiceImpl.login()
→ Dubbo 调 user 服务查询用户
→ 生成 JWT token
→ token 写入 Redis
→ 返回 token 给前端
→ Pinia 保存 token 到 Cookie
→ 立即请求用户信息
→ 登录成功后跳转首页

const loginForm = reactive({
  email: '',
  password: ''
})

const result = await userStore.loginAction(loginForm)

1. 收集邮箱和密码
2. 使用 Element Plus 表单校验
3. 调用 Pinia 的 loginAction()
4. 根据 result 显示成功/失败提示
5. 登录成功后跳转首页

ElMessage.success('登录成功')
fileStore.initRoot()
router.push('/')

const loginAction = async (loginData) => {
  try {
    const response = await login(loginData)
    if (!response?.success) {
      return { success: false, message: response?.message || '登录失败' }
    }

    const tokenValue = response.data
    if (!tokenValue || typeof tokenValue !== 'string') {
      return { success: false, message: '登录返回token无效' }
    }
	//把后端返回的登录 token 保存到 Pinia 状态和 Cookie 中，后续请求才能携带登录凭证。
    setToken(tokenValue)
    // 等待 Vue 把 `token` 状态更新完成，确保后面立刻发请求时能拿到最新 token。
    await nextTick()
    //用刚保存好的 token 请求后端用户信息接口，获取当前用户资料和根目录 ID。
    await getUserInfoAction()
    return { success: true }
  } catch (error) {
    return { success: false, message: error.message || '登录失败' }
  }
}

1. 调用 login(loginData) 请求后端登录接口
2. 判断后端响应是否成功
3. 从 response.data 中取出 token
4. 调用 setToken(tokenValue) 保存 token
5. 调用 getUserInfoAction() 获取当前用户信息
6. 返回 { success: true } 给 Login.vue

const setToken = (newToken) => {  
  token.value = newToken || ''  
  if (token.value) {  
    Cookies.set('token', token.value, { expires: 7 })  
  } else {  
    Cookies.remove('token')  
  }  
}

const token = ref(Cookies.get('token') || '')

const response = await login(loginData)

export function login(data) {
  return authRequest({
    url: '/login',
    method: 'post',
    data
  })
}

baseURL: '/api/v1/auth'

POST /api/v1/auth/login

http://localhost:8090/api/v1/auth/login

@PostMapping("/login")
public Result<String> login(@Valid @RequestBody LoginParamVO loginParam) {
    LoginContext loginContext = authConvertor.loginParamToLoginContext(loginParam);
    String loginToken = authService.login(loginContext);
    return Result.success(loginToken);
}

1. @RequestBody 把 JSON 转成 LoginParamVO
2. @Valid 校验邮箱、密码格式
3. LoginParamVO 转成 LoginContext
4. 调用 AuthServiceImpl.login()
5. 把 token 包装成 Result 返回前端

@NotBlank
@Email
private String email;

@NotBlank
@Size(min = 6, max = 64)
private String password;

邮箱不能为空
邮箱格式正确
密码不能为空
密码长度 6-64

@Override  
public String login(LoginContext loginContext) {  
    // 1. 构建 用户查询请求对象：基于登录上下文的邮箱，创建"按邮箱查询用户"的请求  
    //从 `loginContext` 里取出邮箱，然后构造一个用户查询请求对象。
    UserQueryRequest userQueryRequest = new UserQueryRequest(loginContext.getEmail());  
  
    // 2. 调用用户服务查询用户信息：通过用户门面服务执行查询，返回包含用户信息的响应对象  
    //    UserQueryResponse<UserInfo>：泛型响应体，Data字段封装具体的用户信息（UserInfo）  
    UserQueryResponse<UserInfo> userQueryResponse = userFacadeService.query(userQueryRequest);  
    // 从响应体中提取核心的用户信息对象（包含用户ID、昵称、邮箱等核心字段）  
    UserInfo userInfo = userQueryResponse.getData();  
  
    // 3. 校验用户是否存在：若用户信息为空（未查询到），抛出"用户不存在"的认证异常  
    //    EmptyUtil.isEmpty：自定义工具类，判断对象是否为空（null/空值）  
    //    AuthException：自定义认证异常，携带错误码（USER_NOT_EXIST）便于前端/日志定位问题  
    if (EmptyUtil.isEmpty(userInfo)) {  
        throw new AuthException(AuthErrorCode.USER_NOT_EXIST);  
    }  
  
    // 4. Sa-Token登录：基于用户ID初始化登录态，框架自动维护会话（如Session/上下文）  
    //    StpUtil：Sa-Token核心工具类，login方法会将用户ID存入当前会话，标记用户为"已登录"  
    StpUtil.login(userInfo.getUserId());  
  
    // 5. 生成JWT令牌：用于前后端分离场景的身份认证，有效期配置为1天  
    //    JWTUtil.generateToken：自定义JWT工具类，参数说明：  
    //    - 第1个参数：用户昵称（JWT载荷自定义字段）  
    //    - 第2个参数：JWT载荷中"用户ID"的key（BaseConstant.LOGIN_USER_ID = "login_user_id"）  
    //    - 第3个参数：用户ID（JWT载荷核心字段，用于后续解析令牌获取用户身份）  
    //    - 第4个参数：令牌有效期（AuthConstant.ONE_DAY_TIME_MILLS = 86400000毫秒，即24小时）  
    String accessToken = JWTUtil.generateToken(  
            userInfo.getNickName(),  
            BaseConstant.LOGIN_USER_ID,  
            userInfo.getUserId(),  
            AuthConstant.ONE_DAY_TIME_MILLS  
    );  
  
    // 6. 将JWT令牌存入Redis：做令牌持久化，便于后续校验令牌有效性、登出时删除令牌  
    //    Key规则：登录前缀（USER_LOGIN_PREFIX = "user:login:"） + 用户ID，例如：user:login:1001  
    //    Value：生成的JWT令牌，Redis中存储的有效期与JWT令牌一致（1天）  
    stringRedisTemplate.opsForValue().set(BaseConstant.USER_LOGIN_PREFIX + userInfo.getUserId(), accessToken);  
  
    // 7. 返回JWT令牌：前端拿到令牌后，需在请求头中携带（如Authorization: Bearer {token}）  
    return accessToken;  
}

1. 根据邮箱创建 UserQueryRequest
2. 通过 Dubbo 调 user 服务查询用户
3. 如果查不到用户，抛出 USER_NOT_EXIST
4. 调用 Sa-Token 记录登录态
5. 生成 JWT token
6. 把 token 存入 Redis
7. 返回 token 给 Controller

@Facade
@Override
public UserQueryResponse<UserInfo> query(UserQueryRequest request) {
    ...
}

AuthServiceImpl.login()
→ userFacadeService.query(userQueryRequest)
→ Dubbo 调 user 服务
→ UserFacadeServiceImpl.query()
→ @Facade 触发 FacadeAspect
→ 参数校验、日志记录
→ pjp.proceed()
→ 真正执行 query()
→ 根据邮箱调用 userService.findByEmail()
→ 查询 user 表
→ 返回 UserQueryResponse<UserInfo>
→ FacadeAspect 补全响应
→ 返回 auth 服务

UserQueryResponse<UserInfo> userQueryResponse =      
		userFacadeService.query(userQueryRequest);

networkdisk-auth    → Dubbo    → networkdisk-user    → UserFacadeServiceImpl.query()

UserFacadeServiceImpl.query(UserQueryRequest request)

UserQueryRequest userQueryRequest =        
		new UserQueryRequest(loginContext.getEmail());

public class UserQueryRequest extends BaseRequest {

    // 查询条件父类型，实际可以保存不同的查询条件子类
    private UserQueryCondition userQueryCondition;

    // 按用户ID查询
    public UserQueryRequest(Long userId) {
		// 实例化ID查询条件实现类
        UserIdQueryCondition userIdQueryCondition = new UserIdQueryCondition();
        // 填充查询参数
        userIdQueryCondition.setUserId(userId);
        // 将具体条件对象赋值给父接口字段（多态），this指代当前UserQueryRequest实例
        this.userQueryCondition = userIdQueryCondition;
    }

    // 按邮箱查询
    public UserQueryRequest(String email) {
         // 实例化邮箱查询条件实现类
        UserEmailQueryCondition userEmailQueryCondition = new UserEmailQueryCondition();
        // 填充查询参数
        userEmailQueryCondition.setEmail(email);
        // 多态赋值：具体实现类存入父接口字段
        this.userQueryCondition = userEmailQueryCondition;
    }
}

new UserQueryRequest(1001L)

UserIdQueryCondition

new UserQueryRequest("[已隐藏邮箱]")

UserEmailQueryCondition

@Facade
@Override
public UserQueryResponse<UserInfo> query(UserQueryRequest request) {

    // 取出请求中的查询条件，根据实际子类类型决定怎么查
    UserDO userDO = switch (request.getUserQueryCondition()) {
		 //判断：刚才拿到的条件对象 是不是 UserIdQueryCondition（按 ID 查询的条件）  
		//如果是：自动把这个对象强制转成 UserIdQueryCondition，起个名字叫 userIdQueryCondition
        // 如果是按用户ID查询，就取出 userId，调用 userService.findById()
        case UserIdQueryCondition condition:
	        // yield：把查到的 UserDO 返回出去，整个 switch 表达式的值就是这个 UserDO
            yield userService.findById(condition.getUserId());

        // 如果是按邮箱查询，就取出 email，调用 userService.findByEmail()
        // 登录流程一般走这个分支
        case UserEmailQueryCondition condition:
            yield userService.findByEmail(condition.getEmail());

        // 如果传入了当前不支持的查询条件，直接抛异常
        default:
            throw new UnsupportedOperationException(
                    request.getUserQueryCondition() + " is not supported"
            );
    };

    // 创建统一响应对象
    UserQueryResponse<UserInfo> response = new UserQueryResponse<>();

    // 数据库实体 UserDO 转成对外传输对象 UserInfo
    // 避免直接暴露数据库实体和 password、salt 等敏感字段
    UserInfo userInfo = UserConvertor.INSTANCE.mapToVo(userDO);

    // 标记本次 RPC 调用成功
    response.setSuccess(true);

    // 把用户信息放入响应 data
    response.setData(userInfo);

    // 返回给 Dubbo 调用方，也就是 auth 服务
    return response;
}

switch (request.getUserQueryCondition())

new UserQueryRequest(loginContext.getEmail())

UserEmailQueryCondition

case UserEmailQueryCondition condition:
    yield userService.findByEmail(condition.getEmail());

case UserEmailQueryCondition condition:
    yield userService.findByEmail(condition.getEmail());

@Cached(
    name = "user:cached:telephone:",
    expire = 3000,
    cacheType = CacheType.BOTH,
    key = "#telephone",
    cacheNullValue = true
)
@CacheRefresh(refresh = 60, timeUnit = TimeUnit.HOURS)
public UserDO findByEmail(String email) {
   return userMapper.findByEmail(email);
}

public UserDO findByEmail(String email)

key = "#telephone"

@Cached(
    name = "user:cached:email:",
    expire = 3000,
    cacheType = CacheType.BOTH,
    key = "#email",
    cacheNullValue = true
)
@CacheRefresh(refresh = 60, timeUnit = TimeUnit.HOURS)
public UserDO findByEmail(String email) {
   return userMapper.findByEmail(email);
}

AuthServiceImpl.login()
-> new UserQueryRequest(email)
-> Dubbo 调 UserFacadeServiceImpl.query()
-> switch 识别 UserEmailQueryCondition
-> userService.findByEmail(email)

-> JetCache AOP 拦截 @Cached
-> 查本地 Caffeine / Redis 缓存
-> miss 才执行 userMapper.findByEmail(email)

-> JetCache 判断缓存中是否有该 email 对应的 UserDO
-> 有：直接返回缓存
-> 没有：查 userMapper.findByEmail(email)，再写入本地 Caffeine + Redis 缓存
-> UserDO 转 UserInfo
-> 返回 auth 服务

BaseConstant.USER_LOGIN_PREFIX = "USER_LOGIN_"

user:login:1001

USER_LOGIN_2016448846836494336

StpUtil.login(userId);     // 标记用户登录
StpUtil.logout(userId);    // 用户登出
StpUtil.isLogin();         // 判断是否登录
StpUtil.getLoginId();      // 获取登录用户 ID

sa-token:
  token-name: satoken
  timeout: 2592000
  active-timeout: -1
  is-concurrent: true
  is-share: true
  token-style: uuid
  is-log: true

token-name：Sa-Token 默认 token 名称
timeout：Sa-Token 登录态有效期，2592000 秒，也就是 30 天
is-concurrent：允许同一账号多端同时登录
is-share：多端登录时复用同一个 token
token-style：生成 uuid 风格 token
is-log：输出 Sa-Token 日志

StpUtil.login(userInfo.getUserId());

告诉 Sa-Token：这个 userId 已经登录

StpUtil.login(userId)
= 在 Sa-Token 框架内部登记登录状态
= 后续理论上可以用 StpUtil.isLogin() 判断是否登录
= 理论上也可以用 StpUtil.getLoginId() 获取登录用户 ID

String accessToken = JWTUtil.generateToken(
        userInfo.getNickName(),
        BaseConstant.LOGIN_USER_ID,
        userInfo.getUserId(),
        AuthConstant.ONE_DAY_TIME_MILLS
);

stringRedisTemplate.opsForValue().set(
        BaseConstant.USER_LOGIN_PREFIX + userInfo.getUserId(),
        accessToken
);

BaseConstant.USER_LOGIN_PREFIX = "USER_LOGIN_"

USER_LOGIN_2016448846836494336 -> JWT token字符串

return accessToken;

前端请求接口
-> 请求头 Authorization 携带 JWT
-> UserInfoLoginAspect 拦截 Controller 方法
-> 从 Authorization 取出 JWT
-> JWTUtil 解析 JWT，得到 userId
-> 根据 userId 拼 Redis key：USER_LOGIN_{userId}
-> 从 Redis 取出服务端保存的 token
-> 比对 Redis token 和请求头 token 是否一致
-> 一致：说明登录有效
-> UserIdUtil.set(userId)
-> Controller / Service 继续执行

String accessToken = request.getHeader("Authorization");

Object userId = JWTUtil.analyzeToken(
        accessToken,
        BaseConstant.LOGIN_USER_ID
);

String cacheToken = stringRedisTemplate.opsForValue().get(
        BaseConstant.USER_LOGIN_PREFIX + userId
);

if (!Objects.equals(accessToken, cacheToken)) {
    return false;
}

UserIdUtil.set(Long.valueOf(String.valueOf(userId)));
return true;

UserInfoLoginAspect + JWT + Redis

stringRedisTemplate.delete(BaseConstant.USER_LOGIN_PREFIX + userId);

StpUtil.logout(userId);

删除 Redis 中的有效 JWT
-> 旧 JWT 立刻失效
-> 同时清理 Sa-Token 登录状态

1. AuthServiceImpl.login()：StpUtil.login(userId)
2. AuthServiceImpl.logout()：StpUtil.logout(userId)
3. TokenController.getToken()：StpUtil.isLogin()

StpUtil.checkLogin()
StpUtil.getLoginId()

UserInfoLoginAspect
JWTUtil
StringRedisTemplate
UserIdUtil

这个项目不是纯 Sa-Token，也不是纯 JWT。

真正跑通普通接口鉴权的是：
JWT + Redis + UserInfoLoginAspect + UserIdUtil。

Sa-Token 当前更像辅助登录态组件：
登录时登记一下，登出时清理一下，但普通接口不是主要靠它校验。

// 5. 生成 JWT 令牌：前端后续请求会携带这个 token 访问接口
// 5. 生成JWT令牌：用于前后端分离场景的身份认证，有效期配置为1天  
//    JWTUtil.generateToken：自定义JWT工具类，参数说明：  
//    - 第1个参数：用户昵称（JWT载荷自定义字段）  
//    - 第2个参数：JWT载荷中"用户ID"的key（BaseConstant.LOGIN_USER_ID = "login_user_id"）  
//    - 第3个参数：用户ID（JWT载荷核心字段，用于后续解析令牌获取用户身份）  
//    - 第4个参数：令牌有效期（AuthConstant.ONE_DAY_TIME_MILLS = 86400000毫秒，即24小时）
String accessToken = JWTUtil.generateToken(
        userInfo.getNickName(),
        BaseConstant.LOGIN_USER_ID,
        userInfo.getUserId(),
        AuthConstant.ONE_DAY_TIME_MILLS
);

Header.Payload.Signature

header：说明 token 类型和签名算法
payload：保存业务数据，比如 userId、过期时间
signature：用密钥对 header + payload 算出来的签名

subject：用户昵称，也就是 userInfo.getNickName()
login_user_id：用户ID，也就是 userInfo.getUserId()
expireTime：过期时间，这里是 1 天

Authorization: token字符串

Authorization: Bearer token字符串

// 6. 将 JWT 令牌存入 Redis
// key：登录前缀 + 用户ID，例如 user:login:1001
// value：JWT token
stringRedisTemplate.opsForValue().set(
        BaseConstant.USER_LOGIN_PREFIX + userInfo.getUserId(),
        accessToken
);

key: user:login:1001
value: JWT token字符串

1. 从请求头 Authorization 中取出 token
2. 解析 JWT，拿到 userId
3. 根据 userId 拼 Redis key
4. 去 Redis 查服务端保存的 token
5. 判断 Redis 中的 token 是否和请求头 token 一致
6. 一致，说明当前 token 仍然有效
7. 不一致或 Redis 中没有，说明未登录或 token 已失效

可以主动控制 token 是否有效

删除 user:login:1001

opsForValue().set(key, value);

stringRedisTemplate.opsForValue().set(
        BaseConstant.USER_LOGIN_PREFIX + userInfo.getUserId(),
        accessToken,
        AuthConstant.ONE_DAY_TIME_MILLS,
        TimeUnit.MILLISECONDS
);

//  返回JWT令牌：前端拿到令牌后，需在请求头中携带（如Authorization: Bearer {token}）
return accessToken;

String loginToken = authService.login(loginContext);
return Result.success(loginToken);

{
  "success": true,
  "code": "SUCCESS",
  "message": "SUCCESS",
  "data": "JWT token字符串"
}

response.data.success === true

response.data

const response = await login(loginData)

response.data

setToken(tokenValue)

Pinia：前端状态管理，页面运行期间使用
Cookie：浏览器本地存储，刷新页面后还能恢复登录态

Pinia 保存当前页面运行时的 token
Cookie 保存可持久化的 token

setToken(tokenValue)

Pinia userStore.token = "JWT token字符串"
Cookie token = "JWT token字符串"

await getUserInfoAction()

const response = await getUserInfo()

GET /api/v1/users/get-user-info

config.headers.Authorization = `${userStore.token}`

GET /api/v1/users/get-user-info
请求头：
Authorization: JWT token字符串

userStore = {
  token: 'JWT token字符串',
  userInfo: {},
  rootFileId: ''
}

浏览器
→ Vite dev server:5173
→ networkdisk-user:8086
→ UserController.getUserInfo()
后端收到请求后，公共登录校验逻辑会执行：

1. 从 Authorization 请求头取出 token
2. 解析 JWT，得到 userId
3. 根据 userId 去 Redis 查 token
4. 判断 Redis 中 token 是否和请求头 token 一致
5. 校验通过后，把 userId 放入 UserIdUtil

Long userId = UserIdUtil.get();// 工具类从请求token中解析当前登录用户ID
UserInfoVO userInfo = userService.getUserInfo(userId);// 调用业务层，根据用户ID查询组装用户展示信息
return Result.success(userInfo);// 封装成功统一响应返回前端

userInfo.value = response.data || {}
rootFileId.value = userInfo.value.rootFileId

用户昵称
头像
用户根目录 ID
根目录名称

浏览器请求
→ Controller 方法
→ Service
→ Mapper / 远程服务

浏览器请求
→ Spring AOP 代理对象
→ UserInfoLoginAspect 先检查登录状态
→ 校验通过
→ Controller 方法
→ Service
→ Mapper / 远程服务

浏览器请求
→ UserInfoLoginAspect
→ 返回未登录错误 Result.error(...)
→ Controller 方法不会执行
→ Service 也不会执行

@Slf4j
@Aspect
@Component
public class UserInfoLoginAspect {
}

@Component：让 Spring 创建这个对象
@Aspect：告诉 Spring 这个对象是切面

private final static String POINT_CUT = "execution(* com.disk.*.controller..*(..))";

@Pointcut(value = POINT_CUT)
public void loginAuth() {
}

execution(* com.disk.*.controller..*(..))

execution：匹配方法执行
第一个 *：任意返回值类型
com.disk.*.controller：匹配 com.disk 下任意一级子包里的 controller 包
..*：controller 包及其子包下的所有类、所有方法
(..)：方法参数任意，0 个、1 个、多个都可以

com.disk.user.controller.UserController.getUserInfo(...)
com.disk.files.controller.FileController.list(...)
com.disk.auth.controller.AuthController.login(...)

@Around("loginAuth()")
public Object loginAuthAround(ProceedingJoinPoint proceedingJoinPoint) throws Throwable {
    if (checkNeedCheckLoginInfo(proceedingJoinPoint)) {
        ...
        if (!checkAndSaveUserId(request)) {
            return Result.error(NOT_LOGIN_ERROR.getCode(), NOT_LOGIN_ERROR.getMessage());
        }
    }
    return proceedingJoinPoint.proceed();
}

请求进入 Controller 前
→ 先进入 loginAuthAround()
→ 判断这个接口是否需要登录
→ 如果不需要登录，直接放行
→ 如果需要登录，就检查 token
→ token 校验失败，直接返回未登录错误
→ token 校验成功，调用 proceedingJoinPoint.proceed()
→ 真正执行原来的 Controller 方法

return proceedingJoinPoint.proceed();

proceedingJoinPoint.getSignature(); // 当前被拦截方法的签名信息，比如方法名、返回值、参数类型
proceedingJoinPoint.getArgs();      // 当前被拦截方法的实参，也就是 Controller 方法原本收到的参数
proceedingJoinPoint.getTarget();    // 当前被代理的目标对象，也就是原始 Controller 对象
proceedingJoinPoint.proceed();      // 继续执行原始 Controller 方法

用户没有调用 loginAuthAround()
Controller 也没有调用 loginAuthAround()
是 Spring AOP 代理对象自动调用 loginAuthAround()

浏览器请求
→ DispatcherServlet 找到 Controller 方法
→ 发现 Controller Bean 被 AOP 代理
→ 先进入 UserInfoLoginAspect.loginAuthAround(proceedingJoinPoint)
→ 校验通过后 proceedingJoinPoint.proceed()
→ 执行真正的 Controller 方法

proceed()

JoinPoint：只能看当前被拦截的方法信息
ProceedingJoinPoint：既能看方法信息，又能调用 proceed() 决定是否继续执行原方法

private boolean checkNeedCheckLoginInfo(ProceedingJoinPoint proceedingJoinPoint) {
    Signature signature = proceedingJoinPoint.getSignature();
    MethodSignature methodSignature = (MethodSignature) signature;
    Method method = methodSignature.getMethod();
    return !method.isAnnotationPresent(LoginIgnore.class);
}

proceedingJoinPoint.getSignature()
→ 获取当前被拦截方法的签名信息

(MethodSignature) signature
→ 转成方法签名对象，方便拿到 Method

methodSignature.getMethod()
→ 拿到 Java 反射里的 Method 对象

method.isAnnotationPresent(LoginIgnore.class)
→ 判断当前方法上有没有 @LoginIgnore 注解

return !method.isAnnotationPresent(LoginIgnore.class);

如果方法上有 @LoginIgnore：
    isAnnotationPresent = true
    !true = false
    不需要登录校验

如果方法上没有 @LoginIgnore：
    isAnnotationPresent = false
    !false = true
    需要登录校验

默认所有被切点匹配到的 Controller 方法都需要登录
只有方法上显式加了 @LoginIgnore，才跳过登录校验

private boolean checkAndSaveUserId(HttpServletRequest request) {
    String accessToken = request.getHeader(LOGIN_AUTH_REQUEST_HEADER_NAME);
    if (StringUtils.isBlank(accessToken)) {
        accessToken = request.getParameter(LOGIN_AUTH_PARAM_NAME);
    }
    if (StringUtils.isBlank(accessToken)) {
        return false;
    }

    Object userId = JWTUtil.analyzeToken(accessToken, BaseConstant.LOGIN_USER_ID);
    if (EmptyUtil.isEmpty(userId)) {
        return false;
    }

    String cacheToken = stringRedisTemplate.opsForValue().get(BaseConstant.USER_LOGIN_PREFIX + userId);

    if (StringUtils.isBlank(cacheToken)) {
        return false;
    }

    if (!Objects.equals(accessToken, cacheToken)) {
        return false;
    }

    UserIdUtil.set(Long.valueOf(String.valueOf(userId)));
    return true;
}

1. 从请求头 Authorization 里取 token
2. 如果请求头没有，就从请求参数 authorization 里取 token
3. 如果 token 为空，说明没登录，返回 false
4. 用 JWTUtil 解析 token，取出 userId
5. 如果 userId 解析失败，返回 false
6. 用 USER_LOGIN_PREFIX + userId 拼 Redis key
7. 从 Redis 中查询服务端保存的 token
8. 如果 Redis 没有 token，说明登录状态不存在或已过期，返回 false
9. 对比请求带来的 token 和 Redis 里的 token
10. 如果不一致，说明 token 无效，返回 false
11. 如果一致，把 userId 存入 UserIdUtil
12. 返回 true，表示登录校验通过

Authorization: xxxxx.yyyyy.zzzzz

String accessToken = request.getHeader("Authorization");

accessToken = request.getParameter("authorization");

方式一：请求头 Authorization，推荐
方式二：请求参数 authorization，兜底

public Result<UserInfoVO> getUserInfo() {
    Long userId = UserIdUtil.get();
    return Result.success(userService.getUserInfo(userId));
}

UserIdUtil.set(Long.valueOf(String.valueOf(userId)));

请求进入
→ 切面解析 token 得到 userId
→ UserIdUtil.set(userId)
→ Controller 通过 UserIdUtil.get() 拿 userId
→ Service 根据 userId 查询用户信息

public UserInfoVO getUserInfo(Long userId) {
    UserDO userDO = this.findById(userId);
    if (EmptyUtil.isEmpty(userDO)) {
        throw new UserException(USER_NOT_EXIST);
    }

    UserFileQueryRequest userFileQueryRequest = new UserFileQueryRequest(userId);
    UserFileQueryResponse<UserFileData> userFileInfo =
            userFileFacadeService.getUserFileInfo(userFileQueryRequest);
    UserFileData data = userFileInfo.getData();

    if (EmptyUtil.isEmpty(data)) {
        throw new UserException(USER_INFO_FAIL);
    }

    UserInfoVO userInfoVO = new UserInfoVO();
    userInfoVO.setNickname(userDO.getNickName());
    userInfoVO.setRootFileId(data.getId());
    userInfoVO.setRootFilename(data.getFilename());
    userInfoVO.setUserId(data.getUserId());
    userInfoVO.setProfilePhotoUrl(userDO.getProfilePhotoUrl());

    return userInfoVO;
}

1. 根据 userId 查询用户表，得到 UserDO
2. 如果用户不存在，抛出 USER_NOT_EXIST
3. 创建 UserFileQueryRequest
4. 通过 Dubbo 调用文件微服务 userFileFacadeService.getUserFileInfo(...)
5. 查询该用户的网盘根目录信息
6. 如果文件服务返回为空，抛出 USER_INFO_FAIL
7. 把用户表信息 + 网盘根目录信息组装成 UserInfoVO
8. 返回给 Controller

前端请求 /user/info
→ 请求头携带 Authorization token
→ Spring MVC 找到对应 Controller 方法
→ Spring AOP 发现该 Controller 方法匹配切点
→ 先执行 UserInfoLoginAspect.loginAuthAround()
→ 判断方法有没有 @LoginIgnore
→ 没有 @LoginIgnore，需要登录校验
→ 从请求头 Authorization 获取 token
→ JWTUtil 解析 token 得到 userId
→ Redis 查询 USER_LOGIN_PREFIX + userId 对应的 token
→ 比对请求 token 和 Redis token
→ 校验失败：返回未登录错误，Controller 不执行
→ 校验成功：UserIdUtil.set(userId)
→ proceedingJoinPoint.proceed() 放行
→ Controller 方法正式执行
→ Controller 从 UserIdUtil 获取 userId
→ Controller 调用 userService.getUserInfo(userId)
→ UserService 查询用户表
→ UserService 远程调用文件服务查询根目录
→ 组装 UserInfoVO
→ 返回前端

UserInfoLoginAspect 负责“你是谁、有没有登录”；
UserService.getUserInfo 负责“根据这个 userId 查用户信息并组装返回数据”。

return proceedingJoinPoint.proceed();

return Result.error(...);

@Before：只能在方法前执行一些逻辑，不能方便地阻止原方法
@After：只能在方法后执行
@Around：可以在方法前后执行，还可以决定是否调用 proceed() 放行

某个 Controller 方法即将执行

1. 拿到当前被拦截的方法
2. 判断方法上有没有 @LoginIgnore
3. 如果有，说明不用登录，直接 proceed() 放行
4. 如果没有，说明需要登录
5. 从当前 HTTP request 里拿 Authorization token
6. 解析 token 得到 userId
7. 去 Redis 校验 token 是否和服务端保存的一致
8. 校验通过，把 userId 存进 UserIdUtil
9. 调用 proceedingJoinPoint.proceed()，继续执行原 Controller 方法
10. 校验失败，直接返回未登录错误，Controller 不执行

@GetMapping("/get-user-info")
public Result<UserInfoVO> getUserInfo() {
    Long userId = UserIdUtil.get();
    UserInfoVO userInfo = userService.getUserInfo(userId);
    return Result.success(userInfo);
}

前端请求 /api/v1/users/get-user-info
→ UserInfoLoginAspect 先执行
→ 校验 token
→ UserIdUtil.set(userId)
→ 放行 Controller
→ UserController.getUserInfo()
→ UserIdUtil.get()
→ userService.getUserInfo(userId)
→ Result.success(userInfo)

Long userId = UserIdUtil.get();

UserIdUtil.set(Long.valueOf(String.valueOf(userId)));

UserIdUtil.get();

UserIdUtil.threadLocal = 2016448846836494336

Long userId = 2016448846836494336

从 Authorization 取 token
解析 JWT
查 Redis
得到 userId

UserInfoVO userInfo = userService.getUserInfo(userId);

用户ID
用户昵称
用户头像
网盘根目录ID
网盘根目录名称

networkdisk-user 服务：
查询 user 表，拿用户昵称、头像等基础信息。

networkdisk-files 服务：
查询 user_file 表，拿用户根目录 ID、根目录名称。

UserService.getUserInfo(userId)
→ this.findById(userId)
→ 查询 user 表，得到 UserDO
→ new UserFileQueryRequest(userId)
→ Dubbo 调 files 服务 getUserFileInfo()
→ files 服务查询 user_file 表，得到 UserFileDO
→ UserFileDO 转 UserFileData
→ 返回给 user 服务
→ user 服务组装 UserInfoVO
→ 返回给 Controller

UserDO userDO = this.findById(userId);
if (EmptyUtil.isEmpty(userDO)) {
    throw new UserException(USER_NOT_EXIST);
}

public UserDO findById(Long userId) {
    UserDO userDO = userMapper.findById(userId);
    return userDO;
}

userMapper.findById(userId)

UserDO

UserDO userDO = {
  id: 2016448846836494336,
  nickName: "testUser",
  email: "[已隐藏邮箱]",
  passwordHash: "加密后的密码",
  useSpace: 0,
  totalSpace: 1073741824,
  profilePhotoUrl: "头像地址",
  deleted: 0,
  gmtCreate: 创建时间,
  gmtModified: 修改时间
}

USER_NOT_EXIST

UserFileQueryRequest userFileQueryRequest = new UserFileQueryRequest(userId);

public UserFileQueryRequest(Long userId) {
    UserRootFolderQueryCondition userRootFolderQueryCondition = new UserRootFolderQueryCondition();
    userRootFolderQueryCondition.setUserId(userId);
    this.queryCondition = userRootFolderQueryCondition;
}

UserRootFolderQueryCondition

UserFileQueryRequest = {
  queryCondition: UserRootFolderQueryCondition {
    userId: 2016448846836494336
  }
}

UserRootFolderQueryCondition：查询用户根文件夹

UserFileIdQueryCondition：按文件ID查
UserParentFolderQueryCondition：按父目录查

@Facade
@Override
public UserFileQueryResponse<UserFileData> getUserFileInfo(UserFileQueryRequest request) {
    ...
}

前端请求 /api/v1/users/get-user-info
→ UserInfoLoginAspect 校验 token
→ UserController.getUserInfo()
→ UserService.getUserInfo(userId)
→ 查询 user 表，拿用户昵称、头像
→ userFileFacadeService.getUserFileInfo(...)
→ Dubbo 调 files 服务
→ UserFileFacadeImpl.getUserFileInfo()
→ @Facade 触发 FacadeAspect
→ pjp.proceed()
→ userFileService.getUserRootInfo()
→ 查询 user_file 表中的根目录
→ 返回 UserFileQueryResponse<UserFileData>
→ UserService 组装 UserInfoVO
→ 返回前端

UserFileQueryResponse<UserFileData> userFileInfo =
    userFileFacadeService.getUserFileInfo(userFileQueryRequest);

networkdisk-user
→ Dubbo
→ networkdisk-files
→ UserFileFacadeImpl.getUserFileInfo()

登录时：
auth 服务 → user 服务

登录后获取用户信息时：
user 服务 → files 服务

@Facade
@Override
public UserFileQueryResponse<UserFileData> getUserFileInfo(UserFileQueryRequest request) {
    UserFileDO userFileDO = switch (request.getQueryCondition()) {
        case UserRootFolderQueryCondition queryCondition:
            yield userFileService.getUserRootInfo(queryCondition.getUserId(), FolderFlagEnum.YES);
        default:
            throw new UnsupportedOperationException(request.getQueryCondition() + "'' is not supported");
    };

    UserFileQueryResponse<UserFileData> response = new UserFileQueryResponse();
    response.setSuccess(true);
    UserFileData userFileData = fileConvertor.userFileDOToUserFileData(userFileDO);
    response.setData(userFileData);
    return response;
}

1. 接收 user 服务传来的 UserFileQueryRequest
2. 判断 request 里的查询条件类型
3. 如果是 UserRootFolderQueryCondition，就查询用户根目录
4. 得到 UserFileDO
5. 把 UserFileDO 转成 UserFileData
6. 包装成 UserFileQueryResponse<UserFileData>
7. 返回给 user 服务

UserFileDO userFileDO = switch (request.getQueryCondition()) {
    case UserRootFolderQueryCondition queryCondition:
        yield userFileService.getUserRootInfo(queryCondition.getUserId(), FolderFlagEnum.YES);
    default:
        throw new UnsupportedOperationException(request.getQueryCondition() + "'' is not supported");
};

根据 queryCondition 的实际类型，决定怎么查询。

UserRootFolderQueryCondition

case UserRootFolderQueryCondition queryCondition:

userId = 当前登录用户ID

yield userFileService.getUserRootInfo(queryCondition.getUserId(), FolderFlagEnum.YES);

UserFileDO userFileDO

UserFileDO userFileDO;
if (request.getQueryCondition() instanceof UserRootFolderQueryCondition queryCondition) {
    userFileDO = userFileService.getUserRootInfo(queryCondition.getUserId(), FolderFlagEnum.YES);
} else {
    throw new UnsupportedOperationException(...);
}

如果查询条件是“用户根目录查询条件”，就去查用户根目录。

public UserFileDO getUserRootInfo(Long userId, FolderFlagEnum folderFlag) {
    QueryFileContext context = new QueryFileContext();
    context.setUserId(userId);
    context.setFileFolderType(folderFlag.getCode());
    context.setParentId(FileConstant.TOP_PARENT_ID);
    UserFileDO userRootInfo = userFileMapper.getUserRootInfo(context);
    return userRootInfo;
}

QueryFileContext

QueryFileContext = {
  userId: 2016448846836494336,
  fileFolderType: 1,
  parentId: 0
}

userId：查哪个用户的文件
fileFolderType：是否文件夹，FolderFlagEnum.YES 表示文件夹
parentId：顶级父目录 ID，这里用 TOP_PARENT_ID

查询这个用户的顶级文件夹，也就是用户根目录。

userFileMapper.getUserRootInfo(context)

<select id="getUserRootInfo" resultType="com.disk.files.domain.entity.UserFileDO">
    SELECT
    id AS id,
    parent_id AS parentId,
    filename AS filename,
    folder_flag AS folderFlag,
    user_id AS userId,
    file_type AS fileType
    FROM
    user_file
    WHERE
    user_id = #{param.userId}
    AND folder_flag = #{param.fileFolderType}
    AND parent_id = #{param.parentId}
    AND deleted = 0
</select>

select id, parent_id, filename, folder_flag, user_id, file_type
from user_file
where user_id = 当前用户ID
  and folder_flag = 1
  and parent_id = 0
  and deleted = 0;

查 user_file 表中：
属于当前用户、
是文件夹、
父目录是顶级父目录、
未删除的那条记录。

UserFileDO

UserFileDO userFileDO = {
  id: 30001,
  userId: 2016448846836494336,
  parentId: 0,
  filename: "全部文件",
  folderFlag: 1,
  fileType: null
}

UserFileData userFileData = fileConvertor.userFileDOToUserFileData(userFileDO);

UserFileDO = {
  id: 30001,
  userId: 2016448846836494336,
  parentId: 0,
  filename: "全部文件",
  folderFlag: 1
}

UserFileData = {
  id: 30001,
  userId: 2016448846836494336,
  parentId: 0,
  filename: "全部文件",
  folderFlag: 1
}

UserFileDO：数据库实体，files 服务内部使用
UserFileData：跨服务传输对象，返回给 user 服务使用

UserFileQueryResponse<UserFileData> response = new UserFileQueryResponse();
response.setSuccess(true);
response.setData(userFileData);
return response;

UserFileQueryResponse<UserFileData> = {
  success: true,
  data: {
    id: 30001,
    userId: 2016448846836494336,
    parentId: 0,
    filename: "全部文件",
    folderFlag: 1
  }
}

success：表示 files 服务查询成功
data：真正的根目录数据

UserFileQueryResponse<UserFileData> userFileInfo =
    userFileFacadeService.getUserFileInfo(userFileQueryRequest);

userFileInfo = files 服务返回的响应对象
userFileInfo.getData() = 用户根目录数据 UserFileData

UserFileData data = userFileInfo.getData();

data = {
  id: 30001,
  userId: 2016448846836494336,
  filename: "全部文件",
  folderFlag: 1
}

throw new UserException(USER_INFO_FAIL);

userDO = {
  id: 2016448846836494336,
  nickName: "testUser",
  profilePhotoUrl: "头像地址"
}

data = {
  id: 30001,
  userId: 2016448846836494336,
  filename: "全部文件"
}

UserInfoVO userInfoVO = new UserInfoVO();
userInfoVO.setNickname(userDO.getNickName());
userInfoVO.setRootFileId(data.getId());
userInfoVO.setRootFilename(data.getFilename());
userInfoVO.setUserId(data.getUserId());
userInfoVO.setProfilePhotoUrl(userDO.getProfilePhotoUrl());
return userInfoVO;

UserInfoVO = {
  userId: 2016448846836494336,
  nickname: "testUser",
  rootFileId: 30001,
  rootFilename: "全部文件",
  profilePhotoUrl: "头像地址"
}

nickname：来自 userDO.nickName
profilePhotoUrl：来自 userDO.profilePhotoUrl
rootFileId：来自 UserFileData.id
rootFilename：来自 UserFileData.filename
userId：来自 UserFileData.userId

UserInfoVO userInfo = userService.getUserInfo(userId);

return Result.success(userInfo);

UserController.getUserInfo()
→ UserIdUtil.get() 得到当前登录用户 ID
→ userService.getUserInfo(userId)

UserService.getUserInfo()
→ this.findById(userId)
→ userMapper.findById(userId)
→ 查询 user 表
→ 得到 UserDO

UserService.getUserInfo()
→ new UserFileQueryRequest(userId)
→ 内部包装 UserRootFolderQueryCondition

UserService.getUserInfo()
→ userFileFacadeService.getUserFileInfo(request)
→ Dubbo 调 networkdisk-files

UserFileFacadeImpl.getUserFileInfo()
→ switch 判断 queryCondition 类型
→ UserRootFolderQueryCondition
→ userFileService.getUserRootInfo(userId, FolderFlagEnum.YES)

UserFileServiceImpl.getUserRootInfo()
→ 构造 QueryFileContext
→ userFileMapper.getUserRootInfo(context)
→ 查询 user_file 表
→ 得到 UserFileDO

UserFileFacadeImpl.getUserFileInfo()
→ UserFileDO 转 UserFileData
→ 包装 UserFileQueryResponse<UserFileData>
→ 返回 user 服务

UserService.getUserInfo()
→ userFileInfo.getData()
→ 得到 UserFileData
→ 结合 UserDO 组装 UserInfoVO
→ 返回 Controller

UserController.getUserInfo()
→ Result.success(UserInfoVO)
→ 返回前端

UserService.getUserInfo 不是单纯查用户表，而是先查 user 表拿用户基础信息，再通过 Dubbo 调 files 服务查 user_file 表中的根目录信息，最后把两部分数据合并成 UserInfoVO 返回给前端。

return Result.success(userInfo);

{
  "success": true,
  "code": "SUCCESS",
  "message": "SUCCESS",
  "data": {
    "userId": "加密后的用户ID",
    "nickname": "testUser",
    "rootFileId": "加密后的根目录ID",
    "rootFilename": "全部文件",
    "profilePhotoUrl": "头像地址"
  }
}

success/code/message：本次接口调用状态
data：真正的业务数据，也就是 UserInfoVO

@JsonSerialize(using = IdEncryptSerializer.class)
private Long userId;

@JsonSerialize(using = IdEncryptSerializer.class)
private Long rootFileId;

Java 内存里 userId/rootFileId 是 Long
返回 JSON 给前端时，会使用 IdEncryptSerializer 转成加密字符串

2016448846836494336

"加密后的ID字符串"

UserIdUtil.threadLocal = 当前登录用户ID

Long userId = UserIdUtil.get();

userId = 2016448846836494336

UserInfoVO userInfo = userService.getUserInfo(userId);

userInfo = {
  userId: 2016448846836494336,
  nickname: "testUser",
  rootFileId: 30001,
  rootFilename: "全部文件",
  profilePhotoUrl: "头像地址"
}

userId: Long → 加密字符串
rootFileId: Long → 加密字符串

Result<UserInfoVO> = {
  success: true,
  code: "SUCCESS",
  message: "SUCCESS",
  data: {
    userId: "加密后的用户ID",
    nickname: "testUser",
    rootFileId: "加密后的根目录ID",
    rootFilename: "全部文件",
    profilePhotoUrl: "头像地址"
  }
}

UserController.getUserInfo()
→ 从 UserIdUtil 取当前登录用户 ID
→ 调用 userService.getUserInfo(userId)
→ 得到 UserInfoVO
→ 用 Result.success(userInfo) 包装
→ 返回给前端

UserController.getUserInfo 本身不解析 token，也不直接查数据库。token 校验和 userId 提取由 UserInfoLoginAspect 完成，Controller 只从 UserIdUtil 取当前用户 ID，然后调用 Service 组装用户信息并返回。

1. user 服务查 user 表，得到 UserDO
2. files 服务查 user_file 表，得到用户根目录 UserFileDO

UserFileDO userFileDO = userFileService.getUserRootInfo(...);

UserFileDO = {
  id: 30001,
  userId: 2016448846836494336,
  parentId: 0,
  filename: "全部文件",
  folderFlag: 1
}

UserFileData userFileData = fileConvertor.userFileDOToUserFileData(userFileDO);

UserFileData = {
  id: 30001,
  userId: 2016448846836494336,
  parentId: 0,
  filename: "全部文件",
  folderFlag: 1
}

UserFileQueryResponse<UserFileData> response = new UserFileQueryResponse();
response.setSuccess(true);
response.setData(userFileData);
return response;

UserFileQueryResponse<UserFileData> = {
  success: true,
  data: {
    id: 30001,
    userId: 2016448846836494336,
    parentId: 0,
    filename: "全部文件",
    folderFlag: 1
  }
}

UserFileQueryResponse<UserFileData> userFileInfo =
    userFileFacadeService.getUserFileInfo(userFileQueryRequest);

UserFileFacadeImpl.getUserFileInfo()
→ 返回 UserFileQueryResponse<UserFileData>
→ UserService.getUserInfo() 中的 userFileInfo 接收

UserFileData data = userFileInfo.getData();

data = {
  id: 30001,
  userId: 2016448846836494336,
  filename: "全部文件",
  folderFlag: 1
}

throw new UserException(USER_INFO_FAIL);

UserDO userDO = {
  id: 2016448846836494336,
  nickName: "testUser",
  profilePhotoUrl: "头像地址"
}

UserFileData data = {
  id: 30001,
  userId: 2016448846836494336,
  filename: "全部文件"
}

UserInfoVO userInfoVO = new UserInfoVO();
userInfoVO.setNickname(userDO.getNickName());
userInfoVO.setRootFileId(data.getId());
userInfoVO.setRootFilename(data.getFilename());
userInfoVO.setUserId(data.getUserId());
userInfoVO.setProfilePhotoUrl(userDO.getProfilePhotoUrl());

return userInfoVO;

UserInfoVO = {
  userId: 2016448846836494336,
  nickname: "testUser",
  rootFileId: 30001,
  rootFilename: "全部文件",
  profilePhotoUrl: "头像地址"
}

UserInfoVO userInfo = userService.getUserInfo(userId);

UserService.getUserInfo()
→ 返回 UserInfoVO
→ UserController.getUserInfo() 中的 userInfo 接收

return Result.success(userInfo);

Result<UserInfoVO> = {
  success: true,
  code: "SUCCESS",
  message: "SUCCESS",
  data: UserInfoVO
}

@JsonSerialize(using = IdEncryptSerializer.class)
private Long userId;

@JsonSerialize(using = IdEncryptSerializer.class)
private Long rootFileId;

userId = 2016448846836494336
rootFileId = 30001

{
  "success": true,
  "code": "SUCCESS",
  "message": "SUCCESS",
  "data": {
    "userId": "加密后的用户ID",
    "nickname": "testUser",
    "rootFileId": "加密后的根目录ID",
    "rootFilename": "全部文件",
    "profilePhotoUrl": "头像地址"
  }
}

UserController.getUserInfo()
→ 返回 Result<UserInfoVO>
→ Spring MVC 接收

Result<UserInfoVO>

HTTP 200
Content-Type: application/json
响应体：JSON 字符串

networkdisk-user:8086
→ Vite dev server:5173
→ 浏览器

response = {
  status: 200,
  data: {
    success: true,
    code: 'SUCCESS',
    message: 'SUCCESS',
    data: {
      userId: '加密后的用户ID',
      nickname: 'testUser',
      rootFileId: '加密后的根目录ID',
      rootFilename: '全部文件',
      profilePhotoUrl: '头像地址'
    }
  }
}

if (response.data.code === 200 || response.data.success === true) {
  return response.data
}

{
  success: true,
  code: 'SUCCESS',
  message: 'SUCCESS',
  data: {
    userId: '加密后的用户ID',
    nickname: 'testUser',
    rootFileId: '加密后的根目录ID',
    rootFilename: '全部文件',
    profilePhotoUrl: '头像地址'
  }
}

const response = await getUserInfo()

response = {
  success: true,
  code: 'SUCCESS',
  message: 'SUCCESS',
  data: {
    userId: '加密后的用户ID',
    nickname: 'testUser',
    rootFileId: '加密后的根目录ID',
    rootFilename: '全部文件',
    profilePhotoUrl: '头像地址'
  }
}

// 将接口返回的用户信息赋值给页面响应式变量  
userInfo.value = response.data || {}  
// 如果用户存在根目录ID，同步赋值给全局根文件ID变量  
if (userInfo.value.rootFileId) {  
  rootFileId.value = userInfo.value.rootFileId  
}

userStore = {
  token: 'JWT token字符串',
  userInfo: {
    userId: '加密后的用户ID',
    nickname: 'testUser',
    rootFileId: '加密后的根目录ID',
    rootFilename: '全部文件',
    profilePhotoUrl: '头像地址'
  },
  rootFileId: '加密后的根目录ID'
}

fileStore.initRoot()

userInfo.value = response.data || {}
rootFileId.value = userInfo.value.rootFileId

userStore = {
  token: 'JWT token字符串',
  userInfo: {
    userId: '加密后的用户ID',
    nickname: 'testUser',
    rootFileId: '加密后的根目录ID',
    rootFilename: '全部文件',
    profilePhotoUrl: '头像地址'
  },
  rootFileId: '加密后的根目录ID'
}

async function initRoot() {
  const userStore = useUserStore()
  if (userStore.rootFileId) {
    parentId.value = userStore.rootFileId
    currentFolderId.value = userStore.rootFileId
    fileTypes.value = '-1'
    await loadFiles(userStore.rootFileId, '-1')
  }
}

1. 通过 useUserStore() 拿到用户仓库
2. 判断 userStore.rootFileId 是否存在
3. 把 fileStore.parentId 设置成 rootFileId
4. 把 fileStore.currentFolderId 设置成 rootFileId
5. 把 fileTypes 设置成 -1，表示查询全部类型
6. 调用 loadFiles(rootFileId, '-1') 加载根目录文件列表

parentId：当前正在查看的文件夹 ID
currentFolderId：当前文件夹 ID，上传文件时会用
fileTypes：文件类型筛选，-1 表示全部
files：当前目录下的文件列表
breadcrumbs：当前目录的面包屑路径

fileStore = {
  parentId: '加密后的根目录ID',
  currentFolderId: '加密后的根目录ID',
  fileTypes: '-1',
  files: [],
  breadcrumbs: []
}

await loadFiles(userStore.rootFileId, '-1')

async function loadFiles(newParentId, newFileTypes) {  
  // 自增当前请求序列号，标记本次加载请求  
  const currentSeq = ++latestLoadSeq.value  
  
  // 如果传入了文件类型筛选参数，更新全局筛选条件  
  if (typeof newFileTypes !== 'undefined') fileTypes.value = newFileTypes  
  
  // 如果传入了父文件夹ID，更新当前目录ID  
  //你点击某个文件夹时，就会把这个文件夹的 ID 传进函数里，更新全局的「当前目录 ID」
  //后面拉文件列表、拉面包屑路径，都是基于这个 ID 去查询的。
  if (typeof newParentId !== 'undefined') {  
    parentId.value = newParentId  
    currentFolderId.value = newParentId  
  }  
  
  // 调用后端接口，查询当前目录下的文件列表  
  const res = await getFileList({  
    parentId: parentId.value,  
    fileTypes: fileTypes.value  
  })  
  
  // 关键防抖逻辑：如果后续又发起了新加载请求，本次旧请求结果直接丢弃，不渲染  
  if (currentSeq !== latestLoadSeq.value) return  
  
  // 赋值文件列表到页面响应式数据  
  files.value = res.data || []  
  
  // 存在父目录，需要查询面包屑导航路径  
  
  if (parentId.value) {  
    // 请求获取当前文件夹的层级面包屑  
      //后端会从这个文件夹开始，**一层层往上找它的父级、父级的父级…… 一直找到根目录**，最后返回一个完整的路径数组。
    const bcRes = await getBreadcrumbs({ fileId: parentId.value })  
    // 再次校验序列号，防止旧请求覆盖最新数据  
    if (currentSeq !== latestLoadSeq.value) return  
    breadcrumbs.value = bcRes.data || []  
  } else {  
    // 根目录，清空面包屑  
    breadcrumbs.value = []  
  }  
}

1. 请求当前目录下的文件列表
2. 请求当前目录的面包屑路径

const currentSeq = ++latestLoadSeq.value

第一次请求 A 目录
第二次请求 B 目录
B 请求先返回
A 请求后返回

每次 loadFiles 都生成一个新的 currentSeq
请求返回后，判断 currentSeq 是否还是最新
不是最新就直接 return，不更新页面

只接受最后一次 loadFiles 的结果，旧请求返回了也丢弃。

const res = await getFileList({
  parentId: parentId.value,
  fileTypes: fileTypes.value
})

export function getFileList(params) {
  return fileRequest({
    url: '/folders-files',
    method: 'get',
    params
  })
}

baseURL: '/api/v1/files'

GET /api/v1/files/folders-files?parentId=加密后的根目录ID&fileTypes=-1

http://localhost:8082/api/v1/files/folders-files

Authorization: JWT token字符串

@GetMapping("/folders-files")
public Result<List<UserFileVO>> list(
    @RequestParam(value = "parentId", required = false) String parentId,
    @RequestParam(value = "fileTypes", required = false, defaultValue = FileConstant.ALL_FILE_TYPE) String fileTypes
) {
    Long realParentId = -1L;
    if (!Objects.equals(FileConstant.ALL_FILE_TYPE, parentId)) {
        realParentId = IdUtil.decrypt(parentId);
    }

    List<Integer> fileTypeArray = null;
    if (!Objects.equals(FileConstant.ALL_FILE_TYPE, fileTypes)) {
        fileTypeArray = Arrays.stream(fileTypes.split(BaseConstant.COMMA))
                              .map(Integer::valueOf)
                              .collect(Collectors.toList());
    }

    QueryFileContext request = new QueryFileContext();
    request.setParentId(realParentId);
    request.setFileTypeArray(fileTypeArray);
    request.setUserId(UserIdUtil.get());
    request.setDeleted(DeleteEnum.NO.getCode());

    List<UserFileDO> result = userFileService.getUserFileList(request);
    List<UserFileVO> userFileVOList = fileConvertor.mapToVo(result);
    return Result.success(userFileVOList);
}

解析 Authorization token
→ Redis 校验 token
→ UserIdUtil.set(userId)
→ 放行 Controller

request.setUserId(UserIdUtil.get());

parentId = 加密后的根目录ID

realParentId = IdUtil.decrypt(parentId);

前端加密 rootFileId 字符串
→ 后端 IdUtil.decrypt()
→ 真实 Long 类型 rootFileId

parentId = "加密字符串"
realParentId = 30001

parent_id = 30001

QueryFileContext request = new QueryFileContext();
request.setParentId(realParentId);
request.setFileTypeArray(fileTypeArray);
request.setUserId(UserIdUtil.get());
request.setDeleted(DeleteEnum.NO.getCode());

QueryFileContext = {
  parentId: 30001,
  fileTypeArray: null,
  userId: 2016448846836494336,
  deleted: 0
}

查询当前用户 userId 下，
父目录是 parentId 的文件和文件夹，
只查未删除数据，
fileTypeArray 为 null 表示不限制文件类型。

List<UserFileDO> result = userFileService.getUserFileList(request);

return baseMapper.listUserFiles(context);

<select id="listUserFiles" resultType="com.disk.files.domain.entity.UserFileDO">
    SELECT
    id,
    parent_id AS parentId,
    filename AS filename,
    file_size_desc AS fileSizeDesc,
    folder_flag AS folderFlag,
    file_type AS fileType,
    gmt_modified AS gmtModified
    FROM user_file
    WHERE user_id = #{param.userId}

    <if test="param.parentId != null and param.parentId != -1">
        AND parent_id = #{param.parentId}
    </if>

    <if test="param.fileTypeArray != null">
        AND file_type IN (...)
    </if>

    AND deleted = #{param.deleted}
</select>

select id, parent_id, filename, file_size_desc, folder_flag, file_type, gmt_modified
from user_file
where user_id = 当前用户ID
  and parent_id = 当前根目录ID
  and deleted = 0;

查询当前用户根目录下面的所有文件和文件夹。

List<UserFileDO>

[
  {
    id: 40001,
    parentId: 30001,
    filename: "学习资料",
    folderFlag: 1,
    fileSizeDesc: null,
    fileType: null
  },
  {
    id: 40002,
    parentId: 30001,
    filename: "简历.pdf",
    folderFlag: 0,
    fileSizeDesc: "120KB",
    fileType: 5
  }
]

[]

List<UserFileVO> userFileVOList = fileConvertor.mapToVo(result);

public class UserFileVO {
    private Long id;
    private Long parentId;
    private String filename;
    private String fileSizeDesc;
    private Integer folderFlag;
    private Integer fileType;
    private Date updateTime;
}

@JsonSerialize(using = IdEncryptSerializer.class)
private Long id;

@JsonSerialize(using = IdEncryptSerializer.class)
private Long parentId;

List<UserFileVO> = [
  {
    id: "加密后的文件ID",
    parentId: "加密后的根目录ID",
    filename: "学习资料",
    folderFlag: 1,
    fileSizeDesc: null,
    fileType: null,
    updateTime: "2026-06-28 ..."
  }
]

return Result.success(userFileVOList);

files.value = res.data || []

fileStore.files = [
  {
    id: '加密后的文件ID',
    parentId: '加密后的根目录ID',
    filename: '学习资料',
    folderFlag: 1,
    fileSizeDesc: null,
    fileType: null,
    updateTime: '2026-06-28 ...'
  }
]

fileStore.files = []

const bcRes = await getBreadcrumbs({ fileId: parentId.value })
breadcrumbs.value = bcRes.data || []

GET /api/v1/files/file/breadcrumbs?fileId=加密后的根目录ID

全部文件 / 学习资料 / Java

全部文件

fileStore.breadcrumbs

Login.vue 登录成功
→ getUserInfoAction() 已经拿到 rootFileId
→ fileStore.initRoot()

fileStore.initRoot()
→ 从 userStore 读取 rootFileId
→ parentId = rootFileId
→ currentFolderId = rootFileId
→ fileTypes = -1
→ loadFiles(rootFileId, -1)

loadFiles()
→ getFileList({ parentId: rootFileId, fileTypes: -1 })
→ GET /api/v1/files/folders-files
→ Vite 转发到 networkdisk-files:8082

后端 files：
UserInfoLoginAspect 校验 token
→ UserFileController.list()
→ 解密 parentId
→ UserIdUtil.get() 获取当前用户 ID
→ 组装 QueryFileContext
→ userFileService.getUserFileList()
→ UserFileMapper.listUserFiles()
→ 查询 user_file 表
→ UserFileDO 转 UserFileVO
→ Result.success(List<UserFileVO>)

前端：
Axios 响应拦截器返回 response.data
→ loadFiles() 中 files.value = res.data || []
→ 继续 getBreadcrumbs()
→ breadcrumbs.value = bcRes.data || []
→ 首页渲染文件列表和路径

fileStore.initRoot 是登录成功后的文件模块初始化操作。它使用登录后获取到的 rootFileId 作为当前目录 ID，请求 files 服务查询该根目录下的文件列表和面包屑，并把结果保存到 fileStore.files 和 fileStore.breadcrumbs，供首页文件列表渲染。

main.js
→ App.vue
→ router/index.js

<router-view />

当前 URL 匹配哪个路由，就显示哪个页面组件。

/login       → 显示 Login.vue
/register    → 显示 Register.vue
/            → 显示 Layout.vue，里面默认显示 Home.vue
/files       → 显示 Layout.vue，里面显示 Files.vue
/shares      → 显示 Layout.vue，里面显示 Shares.vue
/recycle     → 显示 Layout.vue，里面显示 Recycle.vue

{
  path: '/',
  name: 'Layout',
  component: () => import('@/views/Layout.vue'),
  meta: { requiresAuth: true },
  children: [
    {
      path: '',
      name: 'Home',
      component: () => import('@/views/Home.vue')
    }
  ]
}

http://localhost:5173/

Layout.vue + Home.vue

meta: { requiresAuth: true }

if (to.meta.requiresAuth && !isLoggedIn.value) {
  next('/login')
}

/login

/
→ Layout.vue
→ Home.vue

<pan-header />
<pan-navbar />
<pan-app-main />

pan-header：顶部栏
pan-navbar：左侧菜单
pan-app-main：中间页面内容

<pan-user-info />

components/user-info/index.vue

<el-dropdown-item divided command="logout">
  退出登录
</el-dropdown-item>

已经登录
→ 进入 Layout.vue
→ 顶部 Header 显示
→ Header 里显示 UserInfo 下拉菜单
→ 下拉菜单里有退出登录

case 'logout':
  await ElMessageBox.confirm('确定要退出登录吗？', '提示', ...)
  userStore.logout()
  router.push('/login')

弹确认框
→ 清空前端 token/userInfo/rootFileId
→ 跳转登录页

<el-dropdown-item divided command="logout">
  <el-icon><SwitchButton /></el-icon>
  退出登录
</el-dropdown-item>

case 'logout':
  await ElMessageBox.confirm('确定要退出登录吗？', '提示', ...)
  userStore.logout()
  router.push('/login')

弹确认框
→ userStore.logout()
→ 跳转 /login

const logout = () => {
  clearToken()
}

setToken('')
userInfo.value = {}
rootFileId.value = ''

Cookies.remove('token')

清空 Pinia token
删除 Cookie token
清空 userInfo
清空 rootFileId
跳转登录页

@PostMapping("/logout")
public Result<Boolean> logout() {
    authService.logout();
    return Result.success(true);
}

export function logout() {
  return authRequest({
    url: '/logout',
    method: 'post'
  })
}

public void logout() {
    Long userId = IdUtil.get();
    stringRedisTemplate.delete(BaseConstant.USER_LOGIN_PREFIX + userId);
    StpUtil.logout(userId);
}

IdUtil.get()

USER_LOGIN_随机ID

USER_LOGIN_当前用户ID

watch([() => route.query.type, () => userStore.rootFileId], ...)

fileStore.loadFiles(rootFileId, fileTypes)

baseURL: '/api/v1/files'

@RequestMapping("/api/v1/files")

@GetMapping("/folders-files")

{
  path: 'files',
  name: 'Files',
  component: () => import('@/views/Files.vue')
}

/files
/files?type=image
/files?type=document
/files?type=video
/files?type=music

// TODO 路由驱动数据加载（整个页面的灵魂）  
// 监听两个依赖：路由上的 type 筛选参数、用户根目录ID  
// 点击侧边栏「图片」 → handleChange 跳转路由 /files?type=image// → 这里 watch 监听到 type 变化 → 调用仓库加载图片类型文件 → 表格自动渲染新数据 → 侧边栏同步高亮。  
// watch(  
//     要监听的数据,     // 第1个参数：侦听源  
//     回调函数,         // 第2个参数：变化时执行的操作  
//     配置选项          // 第3个参数：额外配置  
// )  
watch(  
    //     用数组包裹多个侦听源  
//     每个元素都是箭头函数 () => xxx，这叫 getter 函数  
// Vue 会自动追踪这些函数返回的响应式数据  
// 当 route.query.type 或 userStore.rootFileId 任一发生变化，就会触发回调  
//     / 侦听源数组：2个源，顺序是 [type参数, 根目录ID]  
    [() => route.query.type, () => userStore.rootFileId],  
    // 回调参数数组：2个值，顺序和上面严格对应  
//     第 1 个侦听源是 route.query.type → 回调数组第 1 位 newType 就是它的最新值  
// 第 2 个侦听源是 userStore.rootFileId → 回调数组第 2 位 rootFileId 就是它的最新值  
    async ([newType, rootFileId]) => {  
      // 根目录ID还没拿到（用户未登录/登录信息未加载），直接退出  
      if (!rootFileId) return  
  
      // 切换分类/目录时，先重置搜索状态，避免搜索结果和新目录混淆  
      isSearchMode.value = false  
      searchKeyword.value = ''  
      loading.value = true  
  
      try {  
        // 先判断 newType 有没有值（地址栏有没有带 type 参数）；  
        // 有值：去 typeMap 映射表里查对应的后端编码，比如 'image' → '7'；  
        // 后面加 || '-1' 是兜底：如果用户手动改地址栏输入了非法值（比如 ?type=abc），typeMap[newType] 会是 undefined，这时候兜底为 '-1'（全部文件），防止接口参数报错；  
        // 没值：直接取 typeMap.all（值也是 -1，代表全部类型）。  
        // 根据路由 type，从映射表拿到后端需要的文件类型编码  
        const fileTypes = newType ? typeMap[newType] || '-1' : typeMap.all  
        // 调用仓库的统一加载方法，拉取文件列表，同时更新面包屑  
        await fileStore.loadFiles(rootFileId, fileTypes)  
        // 切换目录后清空选中，防止带着上一页的选中做批量操作  
        selectedFiles.value = []  
      } finally {  
        // 无论成功失败，都关闭加载遮罩，避免页面卡死  
        loading.value = false  
      }  
    },  
    { immediate: true }  
    // immediate: 页面一创建就立刻执行一次  
    // 作用：刷新页面、外链跳转进来，都能自动加载对应数据，不用等手动点击  
)

const typeMap = {
  all: '-1',
  image: '7',
  document: '3,4,5,6,10,11,12',
  video: '9',
  music: '8',
  other: '1,2'
}

/files              -> fileTypes = -1
/files?type=image   -> fileTypes = 7
/files?type=music   -> fileTypes = 8

const parentId = ref('')
const currentFolderId = ref('')
const fileTypes = ref('-1')
const files = ref([])
const breadcrumbs = ref([])
const latestLoadSeq = ref(0)

async function loadFiles(newParentId, newFileTypes) {
  const currentSeq = ++latestLoadSeq.value

  if (typeof newFileTypes !== 'undefined') {
    fileTypes.value = newFileTypes
  }
  if (typeof newParentId !== 'undefined') {
    parentId.value = newParentId
    currentFolderId.value = newParentId
  }

  const res = await getFileList({
    parentId: parentId.value,
    fileTypes: fileTypes.value
  })

  if (currentSeq !== latestLoadSeq.value) return

  files.value = res.data || []

  if (parentId.value) {
    const bcRes = await getBreadcrumbs({ fileId: parentId.value })
    if (currentSeq !== latestLoadSeq.value) return
    breadcrumbs.value = bcRes.data || []
  } else {
    breadcrumbs.value = []
  }
}

请求 A：进入目录 1
请求 B：进入目录 2

@GetMapping("/folders-files")
public Result<List<UserFileVO>> list(
    @RequestParam(value = "parentId", required = false) String parentId,
    @RequestParam(value = "fileTypes", required = false, defaultValue = FileConstant.ALL_FILE_TYPE) String fileTypes
) {
    、、、
    return Result.success(userFileVOList);
}

<el-table-column label="文件名" prop="filename" />
<el-table-column prop="fileSizeDesc" label="大小" />
<el-table-column prop="updateTime" label="修改日期" />

function getFileFontElement(fileType) {
  const fileTypeMap = {
    0: 'fa fa-folder-o',
    5: 'fa fa-file-pdf-o',
    7: 'fa fa-file-image-o',
    8: 'fa fa-file-audio-o',
    9: 'fa fa-file-video-o'
  }
  return fileTypeMap[fileType] || 'fa fa-file'
}

@GetMapping("/file/breadcrumbs")
public Result<List<BreadcrumbVO>> getBreadcrumbs(String fileId)

<el-breadcrumb>
  <el-breadcrumb-item @click="navigateToFolder('')">
    根目录
  </el-breadcrumb-item>

  <el-breadcrumb-item
    v-for="item in fileStore.breadcrumbs"
    @click="navigateToFolder(item.id)"
  >
    {{ item.name }}
  </el-breadcrumb-item>
</el-breadcrumb>

function clickFilename(file) {
  if (file?.folderFlag) {
    openFolder(file)
    return
  }

  if (supportsAi(file)) {
    openAiDrawer(file, 'insight')
    return
  }

  continueFileAction(file)
}

async function openFolder(folder) {
  const folderId = getFileId(folder)

  await fileStore.loadFiles(folderId, fileStore.fileTypes)
}

把当前目录 ID 改成被点击文件夹的 ID
-> 重新请求这个目录下的文件列表
-> 更新 fileStore.files
-> Vue 自动重新渲染表格

async function loadFiles(newParentId, newFileTypes) {
  const currentSeq = ++latestLoadSeq.value
  if (typeof newFileTypes !== 'undefined') {
    fileTypes.value = newFileTypes
  }
  if (typeof newParentId !== 'undefined') {
    parentId.value = newParentId
    currentFolderId.value = newParentId
  }
  const res = await getFileList({
    parentId: parentId.value,
    fileTypes: fileTypes.value
  })
  files.value = res.data || []
  const bcRes = await getBreadcrumbs({ fileId: parentId.value })
  breadcrumbs.value = bcRes.data || []
}

getFileList({
  parentId: folderId,
  fileTypes: fileStore.fileTypes
})

<el-table :data="fileStore.files">

不是 openFolder 主动把新文件一行行塞进表格
而是 openFolder 改变数据源 fileStore.files
表格一直盯着这个数据源
数据源变了，表格自然重新显示

<div class="file-name-content" @click="clickFilename(row)">

function clickFilename(file) {
  if (file?.folderFlag) {
    openFolder(file)
    return
  }
}

点击文件夹名称
-> clickFilename(row)
-> 判断 row.folderFlag 是 true
-> openFolder(row)
-> 取出 row.id
-> fileStore.loadFiles(row.id, 当前 fileTypes)
-> 后端查询 parent_id = row.id 的文件
-> 返回子文件列表
-> fileStore.files = 新列表
-> el-table 因为 :data="fileStore.files" 自动重渲染

openFolder
-> fileStore.loadFiles(folderId, fileTypes)
-> GET /api/v1/files/folders-files?parentId=folderId&fileTypes=...
-> 后端解密 parentId
-> 查询该目录下文件
-> 返回 UserFileVO
-> files 更新
-> 表格刷新
-> breadcrumbs 更新
-> 面包屑刷新

function supportsAi(file) {
  return !file?.folderFlag && AI_SUPPORTED_FILE_TYPES.has(Number(file?.fileType))
}

new Set([3, 4, 5, 6, 10, 11, 12])

openAiDrawer(file, 'insight')

function continueFileAction(file) {
  if (canInlinePreview(file?.fileType)) {
    previewFile(file)
    return
  }
  downloadFile(file)
}

[5, 6, 7, 8, 9, 11, 12]

<el-button class="create-folder-btn" @click="createFolder">
  新建文件夹
</el-button>

async function createFolder() {
  const { value: folderName } = await ElMessageBox.prompt('请输入文件夹名称', '新建文件夹', {
    inputValidator: (value) => {
      if (!value) return '文件夹名称不能为空'
      if (value.length > 255) return '文件夹名称不能超过 255 个字符'
      if (/[<>:"/\\|?*]/.test(value)) {
        return '文件夹名称不能包含以下字符: < > : " / \\ | ? *'
      }
      return true
    }
  })

  await createFolderAPI({
    parentId: fileStore.parentId,
    folderName
  })

  ElMessage.success('文件夹创建成功')
  await refreshCurrentFolder()
}

export function createFolder(data) {
  return fileRequest({
    url: '/folder',
    method: 'post',
    data
  })
}

POST /api/v1/files/folder
Content-Type: application/json

{
  "parentId": "当前目录加密ID",
  "folderName": "新建文件夹"
}

@PostMapping("/folder")  
// @Validated    开启 VO 参数校验。  
//在 CreateFolderParamVO 实体类上的注解（@NotBlank、长度校验、非法字符校验）会生效，  
// 如果校验不通过直接抛出异常，不会往下执行业务代码，返回错误信息给前端。  
public Result<String> createFolder(@Validated @RequestBody CreateFolderParamVO createFolder) {  
//     CreateFolderParamVO createFolder  VO（视图层对象），专门用来接收前端的 JSON 参数，内部属性：  
//    parentId：父文件夹 id//    folderName：文件夹名字  
    CreateFolderContext context = fileConvertor.createFolderParamToCreateFolderContext(createFolder);  
    Long fileId = userFileService.createFolder(context);  
//    IdUtil.encrypt(fileId)：对数据库原生 Long 型 id 做加密。  
//    数据库存明文数字 id；  
//    前后端交互一律使用加密后的字符串 ID，避免 id 泄露被爬虫遍历、越权访问。  
//    包装成统一返回体 Result.success，返回给前端。  
    return Result.success(IdUtil.encrypt(fileId));  
}

@PostMapping("/folder")
public Result<String> createFolder(@Validated @RequestBody CreateFolderParamVO createFolder) {
    CreateFolderContext context = fileConvertor.createFolderParamToCreateFolderContext(createFolder);
    Long fileId = userFileService.createFolder(context);
    return Result.success(IdUtil.encrypt(fileId));
}

@NotBlank
private String parentId;

@NotBlank
private String folderName;

@Mapping(target = "parentId", expression = "java(IdUtil.decrypt(createFolderParam.getParentId()))")
@Mapping(target = "userId", expression = "java(UserIdUtil.get())")
CreateFolderContext createFolderParamToCreateFolderContext(...)

加密 parentId -> 解密成数据库 Long
当前登录用户 -> 填入 userId

    @Override  
    public Long createFolder(CreateFolderContext context) {  
        // 1. 上下文参数 → 组装数据库实体 UserFileDO        UserFileDO entity = assembleUserFolder(context);  
        // 2. MyBatis-Plus 自带 save() 方法，执行insert插入数据库  
        if (!save((entity))) {  
            // 插入失败（数据库报错/影响行数0），抛出系统自定义异常  
            throw new SystemException("保存文件信息失败");  
        }  
        // 插入成功，返回自生成的文件夹唯一ID，给上层Facade封装进响应data  
//        插入数据库后 MyBatis‑Plus 会把主键回填到 entity 的 id 属性，controller 拿到 id 后再进行 ID 加密，返回前端。  
        return entity.getId();  
    }

private UserFileDO assembleUserFolder(CreateFolderContext context) {  
    // 新建数据库实体对象，对应user_file数据表的一条记录  
    UserFileDO entity = new UserFileDO();  
  
    entity.setId(IdUtil.get()); // 生成雪花ID/自定义ID，作为这条文件夹记录的主键  
    entity.setUserId(context.getUserId()); // 当前操作人用户ID，归属人ID  
    entity.setParentId(context.getParentId()); // 父文件夹ID，标记该文件夹挂载在哪个目录下  
    entity.setRealFileId(null); // realFileId为实际文件存储记录ID；文件夹不存在实际文件，赋值null  
    entity.setFilename(context.getFolderName()); // 文件夹名称，对应前端传入的folderName  
    entity.setFolderFlag(FolderFlagEnum.YES.getCode()); // 标记该条记录是文件夹（区分普通文件）  
    entity.setFileSizeDesc(null); // 文件夹无文件大小，置空，只有文件才会记录大小  
    entity.setFileType(null); // 文件类型只针对文档、图片等文件，文件夹不需要文件类型  
    entity.setDeleted(DeleteEnum.NO.getCode()); // 逻辑删除标识：0‑未删除、1‑已删除，默认不删除  
    entity.setCreateUser(context.getUserId()); // 创建人id  
    entity.setUpdateUser(context.getUserId()); // 修改人id，新建时创建人和修改人为同一人  
  
    // 核心方法：处理同级目录下文件夹重名问题（自动重命名或者直接抛异常）  
    handleDuplicateFilename(entity);  
    return entity;  
}

id             新文件夹自己的 ID
user_id        当前用户 ID
parent_id      当前目录 ID
real_file_id   null，文件夹没有真实物理文件
filename       文件夹名
folder_flag    1，表示文件夹
file_size_desc null，文件夹没有文件大小
file_type      null，文件夹没有文件类型
deleted        0，正常状态

await refreshCurrentFolder()

async function refreshCurrentFolder() {
  const targetFolderId = fileStore.parentId || userStore.rootFileId
  await fileStore.loadFiles(targetFolderId, fileStore.fileTypes)
  selectedFiles.value = []
}

重新请求当前目录文件列表
-> 后端查 user_file
-> 刚插入的新文件夹也被查出来
-> fileStore.files = 最新列表
-> el-table 自动重新渲染

private void handleDuplicateFilename(UserFileDO entity) {
}

创建文件夹
普通上传完成后保存 user_file
秒传命中后保存 user_file
分片合并完成后保存 user_file
文件转移
文件复制

handleDuplicateFilename(entity);

saveUserFile(...)

handleDuplicateFilename(entity);

record.setParentId(context.getTargetParentId());
handleDuplicateFilename(record);

record.setParentId(targetParentId);
record.setId(newFileId);
handleDuplicateFilename(record);

private void handleDuplicateFilename(UserFileDO entity) {  
    // 取出原始名称  
    String filename = entity.getFilename();  
    // 定义变量：不带后缀的文件名、文件的后缀/扩展名  
    String newFilenameWithoutSuffix, newFilenameSuffix;  
  
    // 查找最后一个小数点 "." 的下标，用来分割文件名和后缀（例：test.txt，小数点用来拆分 test 和 .txt）  
    int newFilenamePointPosition = filename.lastIndexOf(BaseConstant.POINT_STR);  
  
    // -1：代表字符串里不存在小数点，说明是文件夹或者无后缀文件  
    if (newFilenamePointPosition == BaseConstant.MINUS_ONE_INT) {  
        newFilenameWithoutSuffix = filename; // 主名称 = 原名称  
        newFilenameSuffix = StringUtils.EMPTY; // 后缀为空  
    } else {  
        // 存在小数点：截取小数点前面的文字作为主名称  
        newFilenameWithoutSuffix = filename.substring(BaseConstant.ZERO_INT, newFilenamePointPosition);  
        // 后缀就是小数点及后面的内容，如 .txt、.png  
        newFilenameSuffix = filename.replace(newFilenameWithoutSuffix, StringUtils.EMPTY);  
    }  
  
    // 查询：同一父目录、同一用户下，所有以该主名称开头的已存在记录  
    List<UserFileDO> existRecords = getDuplicateFilename(entity, newFilenameWithoutSuffix);  
  
    // 该目录下没有重名文件/文件夹，直接结束方法，名称保持原样  
    if (CollectionUtils.isEmpty(existRecords)) {  
        return;  
    }  
  
    // 将数据库查出来的记录，只提取文件名称，转为字符串集合，方便后续比对  
    List<String> existFilenames = existRecords.stream()  
            .map(UserFileDO::getFilename)  
            .collect(Collectors.toList());  
  
    int count = 1;  
    String newFilename;  
  
    // do‑while循环：不断拼接新名称，只要名称已存在就继续自增count  
    do {  
        // 拼接成：主名称+(数字)+后缀，示例：文档(1)  
        newFilename = assembleNewFilename(newFilenameWithoutSuffix, count, newFilenameSuffix);  
        count++;  
    } while (existFilenames.contains(newFilename));  
  
    // 将最终不重复的新名称回写到DO实体，后续插入数据库用新名字  
    entity.setFilename(newFilename);  
}

文档.pdf
-> 主体：文档
-> 后缀：.pdf

queryWrapper.eq("parent_id", entity.getParentId());
queryWrapper.eq("folder_flag", entity.getFolderFlag());
queryWrapper.eq("user_id", entity.getUserId());
queryWrapper.eq("deleted", 0);
queryWrapper.likeRight("filename", newFilenameWithoutSuffix);

private String assembleNewFilename(String name, int count, String suffix) {
    return name + "（" + count + "）" + suffix;
}

新建：资料
已有：资料
结果：资料（1）

上传：文档.pdf
已有：文档.pdf
结果：文档（1）.pdf

再上传：文档.pdf
已有：文档.pdf、文档（1）.pdf
结果：文档（2）.pdf

<el-button icon="Edit" @click.stop="renameFile(row)" />

async function renameFile(file) {
  const { value: newName } = await ElMessageBox.prompt('请输入新的文件名', '重命名', {
    inputValue: file?.filename || '',
    inputValidator: (value) => {
      if (!value) return '文件名不能为空'
      if (value.length > 255) return '文件名不能超过 255 个字符'
      return true
    }
  })

  await renameFileAPI({
    fileId: String(getFileId(file)),
    newFilename: newName
  })

  ElMessage.success('文件重命名成功')
  await refreshCurrentFolder()
}

export function renameFile(data) {
  return fileRequest({
    url: '/file',
    method: 'put',
    data
  })
}

PUT /api/v1/files/file
Content-Type: application/json

{
  "fileId": "当前文件加密ID",
  "newFilename": "新的文件名"
}

@PutMapping("/file")
public Result updateFilename(@Validated @RequestBody UpdateFilenameParamVO updateFilenameParam) {
    UpdateFilenameContext context = fileConvertor.updateFilenameParamToUpdateFilenameContext(updateFilenameParam);
    userFileService.updateFilename(context);
    return Result.success();
}

@NotBlank
private String fileId;

@NotBlank
private String newFilename;

fileId 解密成 Long
userId 从登录上下文获取

public void updateFilename(UpdateFilenameContext context) {
    checkUpdateFilenameCondition(context);

    UserFileDO entity = context.getEntity();
    entity.setFilename(context.getNewFilename());

    if (!updateById(entity)) {
        throw new FileException(FILE_RENAME_ERROR);
    }
}

    private void checkUpdateFilenameCondition(UpdateFilenameContext context) {  
    //entity：从数据库查出来的旧数据（文件原本的信息：原来的名字、归属人、父目录）  
    //context：本次前端提交的新操作信息（解密后的文件 ID、当前登录用户、用户输入的新文件名）  
//        context 里的 fileId：前端传加密 ID，后端解密得到，代表用户想要修改哪一个文件  
//        拿着这个 ID 去数据库查询，得到 entity：这个文件在数据库里真实存在的一行数据  
        // 获取待修改文件ID（解密后的明文主键id）  
        Long fileId = context.getFileId();  
        // 根据ID查询数据库文件记录  
        UserFileDO entity = getById(fileId);  
  
        // 校验1：文件不存在  
        if (EmptyUtil.isEmpty(entity)) {  
            throw new FileException(FILE_NOT_EXIT);  
        }  
  
        // 校验2：越权校验，只能修改自己上传/创建的文件  
        if (!Objects.equals(entity.getUserId(), context.getUserId())) {  
            throw new FileException("abc", FILE_NOT_CUR_USER);  
        }  
  
        // 校验3：新名称和原有名称完全一样，无需修改，直接报错  
        if (Objects.equals(entity.getFilename(), context.getNewFilename())) {  
            throw new FileException(FILE_NEW_NAME_EQUALS);  
        }  
  
        // 校验4：同级目录下不能存在同名文件/文件夹  
//        查询逻辑：在同一个父目录下，有没有其他文件叫这个新名字  
        QueryWrapper queryWrapper = new QueryWrapper<>();  
        // 同一父目录 entity.getParentId ()：从数据库实体拿到当前文件所在的文件夹 ID（它现在在哪一级目录）  
        queryWrapper.eq("parent_id", entity.getParentId());  
        // 精准匹配新文件名  
        queryWrapper.eq("filename", context.getNewFilename());  
        // 统计满足条件的记录数量  
        long count = count(queryWrapper);  
  
        // 存在同名记录，抛出名称已存在异常  
        if (count > 0) {  
            throw new FileException(FILE_NEW_NAME_EXIST);  
        }  
  
        // 把查询出来的原始文件实体存入上下文，供上层更新使用  
        context.setEntity(entity);  
    }

文件不存在 -> FILE_NOT_EXIT
不是当前用户文件 -> FILE_NOT_CUR_USER
新旧名称相同 -> FILE_NEW_NAME_EQUALS
同目录已有同名 -> FILE_NEW_NAME_EXIST

user_file.filename

file.filename
file.real_path
物理存储文件名

file 表：真实物理文件/存储记录
user_file 表：用户网盘目录视图

<!-- 删除按钮 -->  
<el-tooltip effect="light" content="删除" placement="top">  
  <el-button icon="Delete" type="danger" size="small" circle @click.stop="deleteFile(row)" />  
</el-tooltip>

async function deleteFile(file) {
  await ElMessageBox.confirm(`确定删除 "${file.filename}" 吗？`, '提示')

  await deleteFilesAPI({
    fileIds: [String(getFileId(file))]
  })

  ElMessage.success('文件删除成功')
  await refreshCurrentFolder()
}

<!-- v-if 搜索模式才显示清空搜索按钮，退出搜索恢复全部文件，选中文件数量大于0才显示 -->  
<el-button v-if="isSearchMode" @click="clearSearch">清空搜索</el-button>  
<!-- 批量删除按钮：选中文件数量大于0才显示 -->  
<el-button  
  v-if="selectedFiles.length > 0"  
  type="danger"  
  @click="batchDelete"  
>  
  <el-icon><Delete /></el-icon>  批量删除  
</el-button>

async function batchDelete() {  
  // selectedFiles.value：页面勾选的文件数组  
  // 校验：如果数组长度为0，代表没有勾选任何文件  
  if (!selectedFiles.value.length) {  
    ElMessage.warning('请选择要删除的文件')  
    return // 终止函数，不执行删除逻辑  
  }  
  
  try {  
    // ElementPlus 确认弹窗，二次确认防止误操作  
    await ElMessageBox.confirm(  
        // 弹窗提示文案：展示勾选数量  
        `确定删除选中的 ${selectedFiles.value.length} 个文件吗？`,  
        '提示', // 弹窗标题  
        {  
          confirmButtonText: '确定',  
          cancelButtonText: '取消',  
          type: 'warning' // 警告样式弹窗  
        }  
    )  
  
    // map遍历选中文件列表，提取每个文件加密ID，转字符串组成数组传给后端  
    // 最终得到 ["id1","id2","id3"] 数组，一次性传给后端批量接口。  
  
    //  .map((file) => ...)    JavaScript 数组的 map 方法  
    // 遍历数组中的每一个元素，对每个元素执行回调函数  
    // 返回一个新数组，长度与原数组相同  
    const idList = selectedFiles.value.map((file) => String(getFileId(file)))  
    // 调用批量删除接口，一次性传递全部id，只发起一次网络请求（批量接口优势，不用循环逐个删）  
    await deleteFilesAPI({  
      fileIds: idList  
    })  
  
    // 接口无异常，弹出成功提示  
    ElMessage.success('文件批量删除成功')  
    // 刷新当前目录，重新拉取文件列表，删除的条目消失  
    await refreshCurrentFolder()  
  } catch (error) {  
    // 弹窗点取消会抛出固定字符串 cancel，这种情况不提示错误  
    if (error !== 'cancel') {  
      // 网络错误、后端业务异常（权限不足、文件不存在）弹出错误信息  
      ElMessage.error(error?.message || '文件批量删除失败')  
    }  
  }  
}

export function deleteFiles(data) {
  return fileRequest({
    url: '/file',
    method: 'delete',
    data
  })
}

DELETE /api/v1/files/file

{
  "fileIds": ["加密文件ID1", "加密文件ID2"]
}

refreshCurrentFolder()

@DeleteMapping("/file")
public Result deleteFile(@Validated @RequestBody DeleteFileParamVO deleteFileParam) {  
    // 1. 对象转换器：前端VO → 业务上下文DeleteUserFileContext，基础封装参数、注入登录用户等信息  
    DeleteUserFileContext context = fileConvertor.deleteFileParamToDeleteFileContext(deleteFileParam);  
  
    // 2. Stream流式处理：对前端传来的加密ID数组做解密、去重  
    List<Long> fileIdList = deleteFileParam.getFileIds()  
            // 遍历每一个加密ID字符串  
            .stream()  
            // 调用工具解密：加密字符串 → 数据库明文Long主键  
            .map(IdUtil::decrypt)  
            // 去重：防止前端重复传同一个ID，避免重复删除  
            .distinct()  
            // 收集处理后的明文ID，转为Long集合  
            .collect(Collectors.toList());  
  
    // 3. 将解密、去重后的明文ID列表存入上下文，供Service层使用  
    context.setFileIdList(fileIdList);  
  
    // 4. 调用业务层执行批量删除核心逻辑  
    userFileService.deleteFile(context);  
  
    // 5. 全部逻辑执行完成，返回统一成功响应  
    return Result.success();  
}

@Override  
public void deleteFile(DeleteUserFileContext context) {  
    // 从上下文取出待删除的明文文件ID列表（已解密、去重）  
    List<Long> fileIdList = context.getFileIdList();  
  
    // MyBatis-Plus 批量根据主键ID查询多条记录  
    // 查询出所有待删除文件完整数据库实体 UserFileDO    List<UserFileDO> userFiles = listByIds(fileIdList);  
  
    // 流式处理：提取所有文件的归属用户ID，放入Set自动去重  
    Set<Long> userIdSet = userFiles.stream()  
            .map(UserFileDO::getUserId) // 遍历每条文件，取出归属人userId  
            .collect(Collectors.toSet()); // Set特性：自动剔除重复userId  
  
    // 校验1：选中的所有文件必须全部属于同一个用户  
    // 如果Set长度不等于1，说明勾选的文件分属多个不同用户，禁止删除  
    if (userIdSet.size() != 1) {  
        throw new FileException(FILE_DELETE_ERROR);  
    }  
  
    // 获取唯一的文件归属用户ID（Set只有一个元素）  
    Long creatUser = userIdSet.stream().findFirst().get();  
  
    // 校验2：校验当前登录人 == 文件归属人，防止越权删除别人文件  
    if (!Objects.equals(creatUser, context.getUserId())) {  
        throw new FileException(FILE_DELETE_ERROR);  
    }  
  
    // 校验全部通过，执行真正的批量删除逻辑  
    doDeleteFile(context);  
  
    // TODO 后续可扩展：发布文件删除事件，用于日志、消息通知、对象存储清理等  
}

当前删除的是 user_file 目录视图记录，不是 file 表里的真实物理文件。

当前 doDeleteFile(...) 只处理传入记录本身，没有在这个删除流程里递归删除文件夹全部子孙节点。

<el-button icon="View" @click.stop="previewFile(row)" />
<el-button icon="Download" @click.stop="downloadFile(row)" />

async function previewFile(file) {
  if (file?.folderFlag) {
    ElMessage.warning('文件夹暂不支持预览')
    return
  }

  await previewSingleFile(file)
}

async function downloadFile(file) {
  if (file?.folderFlag) {
    ElMessage.warning('文件夹暂不支持下载')
    return
  }

  await downloadSingleFile(file)
  ElMessage.success('文件下载已开始')
}

async function batchDownload() {
  const targetFiles = selectedFiles.value.filter((file) => !file.folderFlag)

  for (const file of targetFiles) {
    await downloadSingleFile(file)
  }
}

// 文件下载.md  
export function downloadFile(params) {  
  return fileRequest({  
    url: '/file/download',  
    method: 'get',  
    params,  
    responseType: 'blob'  
  })  
}  
  
// 文件预览  
export function previewFile(params) {  
  return fileRequest({  
    url: '/file/preview',  
    method: 'get',  
    params,  
    // responseType: 'blob' 是前端请求后端时，告诉浏览器以二进制大对象（Blob）格式接收响应数据。  
    responseType: 'blob'  
  })  
}

GET /api/v1/files/file/download?fileId=xxx
GET /api/v1/files/file/preview?fileId=xxx

@Override  
public void download(FileDownloadContext context) {  
    // 1. 根据解密后的文件主键ID，查询数据库该文件完整记录  
    UserFileDO record = getById(context.getFileId());  
    // 2. 权限校验：校验当前登录用户是否有权限操作该文件（文件是否存在、是否属于本人、是否已删除）  
    checkOperatePermission(record, context.getUserId());  
    // 3. 判断当前记录是否为文件夹，文件夹不支持单独下载，直接抛出异常  
    if (isFolder(record)) {  
        throw new FileException(FOLDER_NOT_DOWNLOAD);  
    }  
    // 4. 执行真实下载逻辑：读取OSS文件流、设置下载响应头、流式输出二进制到前端浏览器  
    doDownload(record, context.getResponse());  
}

public class FileDownloadContext {  
    /**  
     * 文件ID  
     */    private Long fileId;  
  
    /**  
     * 请求响应对象  
     */  
    private HttpServletResponse response;  
  
    /**  
     * 当前登录的用户ID  
     */    private Long userId;  
}

@GetMapping("/file/preview")  
public void preview(  
        // 参数校验：fileId不能为空，为空直接抛出参数异常  
        @NotBlank(message = "文件ID不能为空")  
        @RequestParam(value = "fileId", required = false)  
        String fileId,  
        // 注入原生HttpServletResponse，用于输出文件字节流到前端  
        HttpServletResponse response  
) {  
    // 构建预览业务上下文载体  
    FilePreviewContext context = new FilePreviewContext();  
    // 1. 解密加密文件ID，转为数据库明文Long主键  
    context.setFileId(IdUtil.decrypt(fileId));  
    // 2. 把响应对象存入上下文，service层用来写二进制流、设置header  
    // 图片 image/png、视频 video/mp4、文本 text/plain    context.setResponse(response);  
    // 3. 工具类从登录上下文获取当前操作用户ID，用于权限校验  
    context.setUserId(UserIdUtil.get());  
    // 调用业务层执行预览逻辑：权限校验、读取文件二进制、输出到response  
    userFileService.preview(context);  
}

public class FilePreviewContext {  
  
    /**  
     * 文件ID  
     */    private Long fileId;  
  
    /**  
     * 请求响应对象  
     */  
    private HttpServletResponse response;  
  
    /**  
     * 当前登录的用户ID  
     */    private Long userId;  
  
}

状态码：200 / 404 / 500
响应头：Content-Type、Content-Disposition 等
响应体：JSON 字符串 / 图片二进制 / PDF 二进制 / 视频二进制

response.setContentType("application/pdf");
response.setHeader("Content-Disposition", "inline");
response.getOutputStream().write(bytes);

把 Result 对象转成 JSON
设置 Content-Type: application/json
写入 response 输出流

返回的是图片还是 PDF？
是浏览器打开还是下载？
文件内容从哪里读？
怎么写到浏览器？

{
  "data": "一张图片"
}

10MB 图片
200MB 视频
2GB 压缩包

磁盘里的文件  ->  输入流/读取过程  ->  后端  ->  输出流  ->  浏览器

private void realFile2OutputStream(String realPath, HttpServletResponse response) {
    ReadFileContext context = new ReadFileContext();
    context.setRealPath(realPath);
    context.setOutputStream(response.getOutputStream());
    storageEngine.realFile(context);
}

realPath：文件在服务器磁盘/对象存储里的地址
response.getOutputStream()：通向浏览器的水管
storageEngine.realFile(...)：把文件内容倒进水管

前端传 fileId
  ↓
后端 IdUtil.decrypt(fileId)
  ↓
查询 user_file 表
  ↓
校验文件存在、属于当前用户、不是文件夹
  ↓
通过 user_file.real_file_id 查询 file 表
  ↓
拿到 file.real_path
  ↓
设置响应头
  ↓
storageEngine.realFile(...)
  ↓
写入 response.getOutputStream()
  ↓
前端用 Blob 接收

    private void doPreview(UserFileDO record, HttpServletResponse response) {  
        // 1. 根据用户文件记录中的realFileId，查询底层真实文件存储记录  
        FileDO realFileRecord = fileService.getById(record.getRealFileId());  
  
        // 校验：底层物理文件记录丢失，无法预览  
        if (EmptyUtil.isEmpty(realFileRecord)) {  
            throw new SystemException("当前的文件记录不存在");  
        }  
  
        // 2. 获取预览专用MIME类型，为空则兜底通用二进制流  
        String previewContentType = StringUtils.defaultIfBlank(//第一个参数能用就用，不能用就用第二个凑数，保证永远不会返回 null 或空字符串。  
                // 优先取数据库预存的预览MIME（image/png / application/pdf / text/plain等）  
//文件上传时，系统就识别好文件的真实 MIME 类型（比如 image/png、application/pdf、video/mp4），提前存进数据库；  
//预览时直接取出来用，是最准确的类型，浏览器拿到后就能直接渲染显示图片、播放视频、打开 PDF。  
                realFileRecord.getFilePreviewContentType(),  
                // 兜底：二进制通用类型  
                MediaType.APPLICATION_OCTET_STREAM_VALUE  
        );  
  
        // 3. 设置通用响应头：跨域、重置响应、绑定文件MIME类型  
        addCommonResponseHeader(response, previewContentType);  
  
        // 4. 根据文件真实存储路径，流式读取文件并输出到前端浏览器  
        realFile2OutputStream(realFileRecord.getRealPath(), response);  
    }

addCommonResponseHeader(response, previewContentType);
private void addCommonResponseHeader(HttpServletResponse response, String contentTypeValue) {  
    // 清空response原有内容、状态码、旧头部，避免前面逻辑残留数据干扰文件输出  
    response.reset();  
    // 添加跨域允许头部，解决前端浏览器跨域请求报错  
    HttpUtil.addCorsResponseHeaders(response);  
    // 手动追加Content-Type响应头  
    response.addHeader(FileConstant.CONTENT_TYPE_STR, contentTypeValue);  
    // 设置response主体内容类型，标准写法，和addHeader配套使用  
    response.setContentType(contentTypeValue);  
}

PDF -> application/pdf
图片 -> image/jpeg
文本 -> text/plain
视频 -> video/mp4

realFile2OutputStream(realFileRecord.getRealPath(), response);

可能是 PDF
可能是 PNG
可能是 MP4
可能是 TXT

realFileRecord.getFilePreviewContentType()

application/octet-stream

我不知道具体是什么文件，就当通用二进制流处理。

后端返回了一坨文件二进制
浏览器用 Blob 把这坨二进制包起来
前端再决定是打开它，还是下载它

    private void realFile2OutputStream(String realPath, HttpServletResponse response) {  
        try {  
            // 构建文件读取上下文载体  
            ReadFileContext context = new ReadFileContext();  
            // 设置文件真实存储路径，存储引擎通过该路径定位文件  
            context.setRealPath(realPath);  
            // 获取response底层输出流，存入上下文；存储引擎读取文件后直接写入该流  
//            response.getOutputStream()  
//            获取 HTTP 原生二进制输出流，所有文件字节会直接写入这个流，一路传递到前端浏览器。  
//            全程流式读写：读取一块文件，立刻写出一块，不会把整个大文件加载到服务器内存，避免内存溢出 OOM。  
            context.setOutputStream(response.getOutputStream());  
  
            // 调用统一存储引擎，执行文件读取+流式输出逻辑  
//            项目分层设计，统一封装文件读取逻辑，屏蔽底层存储差异：  
//            如果是本地磁盘存储：引擎内部打开本地文件输入流，循环拷贝到 outputStream；  
//            如果是对象存储 OSS（阿里云 / 腾讯云）：引擎调用 OSS SDK 流式拉取文件，边拉边输出；  
            storageEngine.realFile(context);  
        } catch (IOException e) {  
            // 打印IO异常堆栈日志，方便排查文件读取、网络流错误  
            e.printStackTrace();  
            // 封装系统自定义异常，交给全局异常处理器返回前端提示  
            throw new SystemException("文件下载失败");  
        }  
    }

Content-Type: application/octet-stream
Content-Disposition: attachment

Content-Type: image/png / application/pdf / video/mp4 / text/plain

async function previewSingleFile(file) {  
  // 1. 提取文件唯一加密ID  
  const fileId = getFileId(file)  
  // ID为空直接抛出错误，上层catch捕获提示用户  
  if (!fileId) {  
    throw new Error('文件 ID 无效')  
  }  
  
  // 2. 打开空白新标签页 _blank  const previewWindow = window.open('', '_blank')  
  // 浏览器弹窗拦截判断：window.open返回null代表被拦截  
  if (!previewWindow) {  
    throw new Error('浏览器拦截了预览窗口，请允许弹窗后重试')  
  }  
  
  try {  
    // 3. 请求后端预览接口，传入文件加密ID，后端返回文件二进制流（Blob）  
    const response = await previewFileAPI({ fileId: String(fileId) })  
    // 解析响应，提取二进制Blob对象；解析失败抛出统一提示文案  
    const rawBlob = await extractBlobFromResponse(response, '文件预览失败')  
  
    // 分支1：文本类文件（txt、md、代码等）自定义页面渲染，不用浏览器原生  
    if (isTextPreviewType(file?.fileType)) {  
      // 将二进制Blob转成可读文本（处理中文编码）  
      const decodedText = await decodeTextBlob(rawBlob)  
      // 往空白新窗口写入自定义HTML，展示文本内容、文件名  
      renderTextPreview(previewWindow, decodedText, file?.filename)  
      // 文本预览逻辑执行完毕，终止函数，不走下方图片/PDF逻辑  
      return  
    }  
  
// 分支2：图片/视频/PDF 浏览器原生预览逻辑  
// 1. 确定文件标准MIME类型  
// 优先用后端流自带的文件类型；为空就根据文件类型码手动匹配对应格式  
    const previewType = rawBlob.type || getPreviewMimeType(file?.fileType)  
  // 2. 补全Blob的MIME标识，浏览器才能识别怎么渲染  
  // 原有Blob自带type就直接复用；没有则包一层新Blob并绑定刚才算出的type  
    const previewBlob = rawBlob.type ? rawBlob : new Blob([rawBlob], { type: previewType })  
// 3. 把内存里的二进制Blob生成浏览器临时本地URL（仅当前页面可用）  
    const previewUrl = window.URL.createObjectURL(previewBlob)  
// 4. 空白预览窗口跳转这个临时链接，浏览器自动用自带工具渲染图片/PDF/视频  
    previewWindow.location.href = previewUrl  
    // 定时器1分钟后释放临时Blob内存，避免内存泄漏  
    setTimeout(() => window.URL.revokeObjectURL(previewUrl), 60000)  
  } catch (error) {  
    // 任何接口/解析/渲染异常：关闭空白预览窗口，再把错误抛出给外层捕获提示  
    previewWindow.close()  
    throw error  
  }  
}

用户点击预览
-> 立刻打开空白窗口
-> 再异步请求后端文件流
-> 文件流回来后，把空白窗口改成预览页面

if (!previewWindow) {
  throw new Error('浏览器拦截了预览窗口，请允许弹窗后重试')
}

const rawBlob = await extractBlobFromResponse(response, '文件预览失败')

const blob = response?.data instanceof Blob ? response.data : response

{
  "success": false,
  "message": "文件不存在"
}

if (blob.type?.includes('application/json')) {
  const text = await blob.text()
  const result = JSON.parse(text)
  throw new Error(result?.message || defaultErrorMessage)
}

正常文件流 -> 继续预览
错误 JSON -> 解析错误信息，弹出提示

function isTextPreviewType(fileType) {
  return [6, 11, 12].includes(Number(fileType))
}

const decodedText = await decodeTextBlob(rawBlob)
renderTextPreview(previewWindow, decodedText, file?.filename)
return

async function decodeTextBlob(blob) {
  const bytes = await blob.arrayBuffer()

  try {
    return new TextDecoder('utf-8', { fatal: true }).decode(bytes)
  } catch (_) {
    try {
      return new TextDecoder('gb18030').decode(bytes)
    } catch (_) {
      return new TextDecoder().decode(bytes)
    }
  }
}

UTF-8
-> GB18030
-> 浏览器默认解码

renderTextPreview(previewWindow, decodedText, file?.filename)

previewWindow.document.open()
previewWindow.document.write(`完整 HTML`)
previewWindow.document.close()

function escapeHtml(rawText = '') {
  return rawText
    .replace(/&/g, '&')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;')
}

<script>alert(1)</script>

Blob 二进制
-> ArrayBuffer
-> TextDecoder 解码成字符串
-> HTML 转义
-> document.write 写入新窗口

const previewType = rawBlob.type || getPreviewMimeType(file?.fileType)
const previewBlob = rawBlob.type ? rawBlob : new Blob([rawBlob], { type: previewType })
const previewUrl = window.URL.createObjectURL(previewBlob)
previewWindow.location.href = previewUrl
setTimeout(() => window.URL.revokeObjectURL(previewUrl), 60000)

const previewType = rawBlob.type || getPreviewMimeType(file?.fileType)

function getPreviewMimeType(fileType) {
  const normalized = Number(fileType)

  if (normalized === 5) return 'application/pdf'
  if ([6, 11, 12].includes(normalized)) return 'text/plain;charset=utf-8'
  if (normalized === 7) return 'image/*'
  if (normalized === 8) return 'audio/*'
  if (normalized === 9) return 'video/*'

  return 'application/octet-stream'
}

const previewBlob = rawBlob.type
  ? rawBlob
  : new Blob([rawBlob], { type: previewType })

const previewUrl = window.URL.createObjectURL(previewBlob)

blob:http://localhost:5173/xxxx-xxxx-xxxx

previewWindow.location.href = previewUrl

application/pdf -> 浏览器 PDF 阅读器
image/png       -> 图片预览
video/mp4       -> 视频播放器
audio/mpeg      -> 音频播放器

setTimeout(() => window.URL.revokeObjectURL(previewUrl), 60000)

    private void doDownload(UserFileDO record, HttpServletResponse response) {  
        // 1. 根据用户文件记录里的realFileId，查询底层真实文件存储记录  
        // realFileId 对应真实文件表，存文件物理路径、大小、存储桶等OSS/本地存储信息  
        FileDO fileRecord = fileService.getById(record.getRealFileId());  
  
        // 校验：底层真实文件存储记录不存在（源文件丢失、已清理）  
        if (EmptyUtil.isEmpty(fileRecord)) {  
            throw new FileException(FILE_NOT_EXIT);  
        }  
  
        // 2. 添加通用基础响应头  
        // 默认二进制流类型，浏览器识别为可下载文件  
//        通用公共响应头工具方法，内部一般设置：  
//        跨域头 Access-Control//        缓存策略  
//        Content-Type = application/octet-stream 二进制流，通用下载类型  
        addCommonResponseHeader(response, MediaType.APPLICATION_OCTET_STREAM_VALUE);  
  
        // 3. 添加下载专属头部：文件名、编码、文件长度等，触发浏览器下载弹窗  
        addDownloadAttribute(response, record, fileRecord);  
  
        // 4. 根据文件真实存储路径，读取文件并流式写入response输出流给到前端  
        realFile2OutputStream(fileRecord.getRealPath(), response);  
    }

通过 user_file.real_file_id 找到 file 表真实文件记录
设置 Content-Type = application/octet-stream
设置 Content-Disposition = attachment，告诉浏览器这是下载
根据 file.real_path 读取真实文件
把文件内容写入 response.getOutputStream()

private void addDownloadAttribute(HttpServletResponse response, UserFileDO record, FileDO realFileRecord) {  
    // 1. 对中文文件名做URL编码，解决Chrome、Edge、Firefox多浏览器中文乱码问题  
    String encodedFilename = URLEncoder.encode(record.getFilename(), StandardCharsets.UTF_8)  
            // URLEncoder会把空格转为+，浏览器识别空格需要替换为标准URL空格编码%20  
            .replace("+", "%20");  
  
    // 2. 设置核心下载头 Content-Disposition   
     // attachment：强制浏览器下载，不在页面内直接打开  `attachment` 的意思是：浏览器不要直接打开，作为附件下载保存。
    // filename：兼容旧浏览器，带编码文件名  
    // filename*：新标准UTF-8文件名，兼容现代浏览器  
    response.setHeader(  
            FileConstant.CONTENT_DISPOSITION_STR,  
            "attachment;filename=\"" + encodedFilename + "\";filename*=UTF-8''" + encodedFilename  
    );  
  
    // 3. 设置文件总字节长度，浏览器可显示下载进度条  
    response.setContentLengthLong(Long.parseLong(realFileRecord.getFileSize()));  
}

Content-Type: application/octet-stream
Content-Disposition: attachment;filename="xxx"

realFile2OutputStream(fileRecord.getRealPath(), response)

private void realFile2OutputStream(String realPath, HttpServletResponse response) {
    ReadFileContext context = new ReadFileContext();
    context.setRealPath(realPath);
    context.setOutputStream(response.getOutputStream());

    storageEngine.realFile(context);
}

file.real_path 是服务器里真实文件位置
response.getOutputStream() 是通向浏览器的输出流
storageEngine.realFile(...) 把真实文件内容写进这个输出流

const blob = await extractBlobFromResponse(response, '文件下载失败')

正常文件流 -> 返回 Blob
后端错误 JSON -> 解析 message 并抛错

function saveBlobToLocal(blob, filename) {
  const url = window.URL.createObjectURL(blob)

  const link = document.createElement('a')
  link.href = url
  link.download = filename

  document.body.appendChild(link)
  link.click()
  document.body.removeChild(link)

  window.URL.revokeObjectURL(url)
}

Blob 是浏览器内存里的文件对象
createObjectURL 把 Blob 转成临时 URL
a.download 指定下载文件名
link.click() 模拟点击下载
revokeObjectURL 释放临时 URL

收到后端文件流
-> axios 按 Blob 接收
-> 校验是不是错误 JSON
-> 生成 blob 临时 URL
-> 创建 a 标签
-> 设置 download 文件名
-> 模拟点击
-> 浏览器保存文件
-> 释放临时 URL

saveBlobToLocal(blob, filename)

Blob 二进制对象
  ↓
URL.createObjectURL(blob)
  ↓
创建隐藏 a 标签
  ↓
设置 a.download = filename
  ↓
模拟点击 a.click()
  ↓
浏览器开始保存文件
  ↓
URL.revokeObjectURL(...) 释放内存

个人空间单文件下载：已实现
个人空间文件预览：已实现
分享页单文件下载：已实现
前端批量下载普通文件：已实现，本质是循环单文件下载
后端多文件 zip 打包下载：未实现
文件夹下载：未实现

我的资料
Java
前端
SpringBoot
图片

我的资料
├── Java
│   └── SpringBoot
└── 前端

图片

[
  {
    "id": "1",
    "parentId": "0",
    "name": "我的资料",
    "children": [
      {
        "id": "2",
        "parentId": "1",
        "name": "Java",
        "children": [
          {
            "id": "4",
            "parentId": "2",
            "name": "SpringBoot",
            "children": []
          }
        ]
      },
      {
        "id": "3",
        "parentId": "1",
        "name": "前端",
        "children": []
      }
    ]
  },
  {
    "id": "5",
    "parentId": "0",
    "name": "图片",
    "children": []
  }
]

GET /api/v1/files/file/folder/tree

@GetMapping("/file/folder/tree")
public Result<List<FolderTreeNodeVO>> getFolderTree() {
    QueryFolderTreeContext context = new QueryFolderTreeContext();
    context.setUserId(UserIdUtil.get());

    List<FolderTreeNodeVO> result = userFileService.getFolderTree(context);
    return Result.success(result);
}

获取当前登录用户 userId
-> 封装 QueryFolderTreeContext
-> 调用 userFileService.getFolderTree(...)
-> 返回树形节点列表

public List<FolderTreeNodeVO> getFolderTree(QueryFolderTreeContext context) {
    List<UserFileDO> folderRecords = queryFolderRecords(context.getUserId());
    return assembleFolderTreeNodeVOList(folderRecords);
}

1. 查询当前用户所有有效文件夹
2. 在内存中组装成 children 树

//    从数据库查出当前用户所有的、未删除的文件夹记录，为后续内存组装路径提供全量数据。  
    private List<UserFileDO> queryFolderRecords(Long userId) {  
//   这是 MyBatis-Plus 的条件构造器，用来动态拼接 SQL 查询条件，不用手写 XML 里的 SQL 片段。  
        QueryWrapper queryWrapper = Wrappers.query();  
//用户数据隔离：只查当前登录用户的文件记录，和之前 Controller、XML 里的逻辑完全一致，保证数据安全。  
        queryWrapper.eq("user_id", userId);  
//  只筛选「文件夹」类型的记录。面包屑是目录层级路径，只有文件夹才有上下级关系，普通文件不需要参与路径组装。这里用枚举类代替硬编码数字，是规范的工程写法。  
        queryWrapper.eq("folder_flag", FolderFlagEnum.YES.getCode());  
//        逻辑删除过滤：只查未被删除的文件夹，回收站里的文件夹不会出现在正常路径里。  
        queryWrapper.eq("deleted", DeleteEnum.NO.getCode());  
//        调用 MyBatis-Plus 内置的 list 方法，执行查询并返回 UserFileDO 列表。DO = Data Object，和数据库表一一对应，是数据库层的实体对象。  
        return list(queryWrapper);  
    }

    private List<FolderTreeNodeVO> assembleFolderTreeNodeVOList(List<UserFileDO> folderRecords) {  
        // 1. 判空：无文件夹数据直接返回空集合  
        if (CollectionUtils.isEmpty(folderRecords)) {  
            return Lists.newArrayList();  
        }  
  
        // 2. DO转VO：把数据库实体UserFileDO 批量转换为前端树形节点VO  
        //执行完这一步：我们得到装满树形对象的一维列表，每个对象的children都是空集合。  
        List<FolderTreeNodeVO> mappedFolderTreeNodeVOList =  
                // 把文件夹列表转为流，开启流式操作；  
                folderRecords.stream()  
                // 循环每一条UserFileDO，调用MapStruct转换方法  
                .map(fileConvertor::userFile2FolderTreeNodeVO)  
                // 把转换后的所有VO收集成一个List  
                .toList();  
  
        // 3. 分组：以父ID为key，把所有子文件夹归类，Map<父ID, 该父下所有子节点>  
        Map<Long, List<FolderTreeNodeVO>> mappedFolderTreeNodeVOMap = mappedFolderTreeNodeVOList.stream()  
            //groupingBy 核心作用（重点）  
            //以每条 VO 的parentId作为 Map 的 key，把同一个父文件夹下的所有子文件夹分到一组。key=1  → [id=2, id=3]  
                .collect(Collectors.groupingBy(FolderTreeNodeVO::getParentId));  
  
        // 4. 遍历全部节点，把子节点挂载到父节点的children属性，生成嵌套树  
//        mappedFolderTreeNodeVOList 是全局的原始 VO 集合，循环里只是原地修改每个对象内部的 children 字段；  
//        所有父子嵌套关系全部绑定在原有对象上，不需要生成、返回新节点；  
//        循环走完后，这个 list 里的所有 VO 已经自带完整树形嵌套关系，直接拿来过滤顶层节点即可。  
        for (FolderTreeNodeVO node : mappedFolderTreeNodeVOList) {  
            // node.getId() = 当前文件夹的ID，用这个ID去分组Map查：哪些文件夹的parentId等于我  
            List<FolderTreeNodeVO> children = mappedFolderTreeNodeVOMap.get(node.getId());  
            // 判断是否存在子文件夹  
            if (CollectionUtils.isNotEmpty(children)) {  
                // 把查到的子文件夹全部放进当前节点的children列表，形成嵌套  
                node.getChildren().addAll(children);  
            }  
        }

先把所有文件夹转成 VO
-> 按 parentId 分组
-> 遍历每个节点，把 parentId = 当前节点 id 的节点挂到 children
-> 最后只返回顶层节点

FileConstant.TOP_PARENT_ID = 0L

parentId = 0 的文件夹是顶层目录

POST /api/v1/files/file/transfer

{
  "fileIds": ["加密ID1", "加密ID2"],
  "targetParentId": "目标文件夹加密ID"
}

    @PostMapping("/file/transfer")  
    public Result transfer(@Validated @RequestBody TransferFileParamVO transferFileParam) {  
        // 1. 前端传加密后的文件ID数组，循环解密转为真实Long主键  
//        IdUtil.decrypt 前后端分离安全设计，前端不直接传数据库真实 ID，全部加密传输，后端解密拿到真实主键；  
        List<Long> fileIdList = transferFileParam.getFileIds()  
                .stream()  
                .map(IdUtil::decrypt)  
                .collect(Collectors.toList());  
  
        // 2. 获取目标文件夹加密ID  
        String targetParentId = transferFileParam.getTargetParentId();  
  
        // 3. 封装转移上下文载体，统一存放本次操作全部参数  
        TransferFileContext context = new TransferFileContext();  
        context.setFileIdList(fileIdList);  
        // 解密目标文件夹ID  
        context.setTargetParentId(IdUtil.decrypt(targetParentId));  
        // 获取当前登录用户ID  
        context.setUserId(UserIdUtil.get());  
  
        // 4. 调用业务层执行文件移动逻辑  
        userFileService.transfer(context);  
        // 5. 无返回数据，返回成功提示  
        return Result.success("");  
    }

public class TransferFileParamVO {  
  
    /**  
     * 要转移的文件ID集合，多个使用公用分隔符隔开  
     */  
    @NotEmpty(message = "请选择要转移的文件")  
    private List<String> fileIds;  
  
    /**  
     * 要转移到的目标文件夹的ID  
     */    @NotBlank(message = "请选择要转移到哪个文件夹下面")  
    private String targetParentId;  
  
}
@Getter  
@Setter  
public class TransferFileContext {  
  
    /**  
     * 要转移的文件ID集合  
     */  
    private List<Long> fileIdList;  
  
    /**  
     * 目标文件夹ID  
     */    private Long targetParentId;  
  
    /**  
     * 当前登录的用户ID  
     */    private Long userId;  
  
    /**  
     * 要转移的文件列表  
     */  
    private List<UserFileDO> prepareRecords;  
}

fileIds：加密字符串列表 -> Long 列表
targetParentId：加密字符串 -> Long
userId：从登录上下文获取

@Override  
public void transfer(TransferFileContext context) {  
    // 第一步：前置校验（权限校验、不能移动到自身子目录、目标文件夹是否存在等）  
    checkTransferCondition(context);  
    // 根据文件ID批量查询本次要移动的所有文件/文件夹记录（上下文内部封装查询逻辑）  
    List<UserFileDO> prepareRecords = context.getPrepareRecords();  
  
    // 遍历每一条待移动文件记录，修改归属信息  
    prepareRecords.forEach(record -> {  
        // 修改父文件夹ID：核心逻辑，移动就是改parentId  
        record.setParentId(context.getTargetParentId());  
        // 归属用户ID（网盘多用户隔离）  
        record.setUserId(context.getUserId());  
        // 创建人、更新人改为当前操作者  
        record.setCreateUser(context.getUserId());  
        record.setUpdateUser(context.getUserId());  
        // 处理重名：目标文件夹存在同名文件时，自动重命名（xxx(1)、xxx(2)）  
        handleDuplicateFilename(record);  
    });  
  
    // 批量更新数据库所有修改后的记录  
    if (!updateBatchById(prepareRecords)) {  
        // 数据库更新行数为0，抛出异常提示转移失败  
        throw new SystemException("文件转移失败");  
    }  
}

private void checkTransferCondition(TransferFileContext context) {  
    // 从上下文中取出本次移动的目标位置ID（也就是要把文件移到哪个文件夹下面）  
    Long targetParentId = context.getTargetParentId();  
  
    // ========== 校验1：目标位置必须是文件夹，不能是普通文件 ==========    // 先根据目标ID查询数据库记录，再判断这条记录是不是文件夹类型  
    // 业务规则：文件/文件夹只能存放在文件夹（容器）里，不能移动到一个普通文件的“内部”  
    if (!isFolder(getById(targetParentId))) {  
        // 目标不是文件夹，直接抛出「目标文件夹类型错误」的业务异常，终止流程  
        throw new FileException(TARGET_FOLDER_TYPE_ERROR);  
    }  
  
    // ========== 预加载：批量查出所有待移动的文件记录 ==========    // 根据前端传的文件ID列表，一次性查出全部待移动的文件/文件夹实体  
    // 这里提前查出来，后面的子目录校验、主方法里的属性修改都能直接用，不用重复查数据库  
    List<UserFileDO> prepareRecords = listByIds(context.getFileIdList());  
    // 把查到的记录存入上下文对象，实现「一次查询、多处复用」  
    context.setPrepareRecords(prepareRecords);  
  
    // ========== 校验2：禁止把文件夹移动到它自己的子目录里 ==========    // 这是树形目录的核心边界校验：防止出现「A文件夹包含B文件夹，B文件夹又包含A文件夹」的循环嵌套  
    // 内部逻辑：从目标文件夹开始，一层层向上找父级，检查目标文件夹是不是待移动文件夹的子孙级  
    // 如果不拦截，后续查询面包屑、遍历文件夹时会陷入无限递归，直接导致系统卡死  
    if (checkIsChildFolder(prepareRecords, targetParentId, context.getUserId())) {  
        throw new FileException(FILE_NOT_EXIT);  
    }  
}

A
└── B

A -> B -> A -> B ...

record.setParentId(context.getTargetParentId());

修改 user_file.parent_id

file 表
真实物理文件
real_file_id

handleDuplicateFilename(record);

文档.pdf -> 文档（1）.pdf

文件转移不是移动物理文件，而是把 user_file 记录的 parent_id 改成目标文件夹 ID；如果同名则自动改名。

POST /api/v1/files/file/copy

{
  "fileIds": "加密ID1,加密ID2",
  "targetParentId": "目标文件夹加密ID"
}

@PostMapping("/file/copy")  
public Result copy(@Validated @RequestBody CopyFileParamVO copyFilePO) {  
    // 前端传逗号分隔的加密ID字符串，不是数组  
    String fileIds = copyFilePO.getFileIds();  
    // 目标文件夹加密ID  
    String targetParentId = copyFilePO.getTargetParentId();  
  
    // 1. 按分隔符切割字符串 → 字符串列表 → 循环解密为真实Long主键  
    List<Long> fileIdList = Splitter.on(BaseConstant.COMMON_SEPARATOR)  
            .splitToList(fileIds)  
            .stream()  
            .map(IdUtil::decrypt)  
            .collect(Collectors.toList());  
  
    // 2. 封装复制操作上下文，统一承载所有参数  
    CopyFileContext context = new CopyFileContext();  
    context.setFileIdList(fileIdList);  
    context.setTargetParentId(IdUtil.decrypt(targetParentId));  
    context.setUserId(UserIdUtil.get()); // 当前登录用户  
  
    // 3. 调用业务层执行复制逻辑  
    userFileService.copy(context);  
    return Result.success("");  
}

把 "id1,id2,id3" 拆成列表
-> 每个 ID 解密
-> 解密 targetParentId
-> 补充当前 userId
-> 调用复制服务

@Override  
public void copy(CopyFileContext context) {  
    // 前置校验：目标是否文件夹、不能复制到子目录、权限校验等  
    checkCopyCondition(context);  
    // 上下文中取出待复制的原文件/文件夹数据库记录（校验阶段已批量查询存入）  
    List<UserFileDO> prepareRecords = context.getPrepareRecords();  
  
    // 没有选中文件直接结束方法  
    if (EmptyUtil.isEmpty(prepareRecords)) {  
        return;  
    }  
  
    // 存放所有要新增的复制副本记录（包括文件夹下所有子文件、子文件夹）  
    List<UserFileDO> allRecords = Lists.newArrayList();  
  
    // 遍历每一个选中的源文件/文件夹，递归生成副本记录存入allRecords  
    prepareRecords.forEach(record ->  
            assembleCopyChildRecord(allRecords, record, context.getTargetParentId(), context.getUserId())  
    );  
  
    // 批量插入所有副本到数据库  
    if (!saveBatch(allRecords)) {  
        throw new SystemException("文件复制失败");  
    }  
}

目标必须是文件夹
目标不能是被复制文件夹本身或其子文件夹

    private void assembleCopyChildRecord(List<UserFileDO> allRecords, UserFileDO record, Long targetParentId, Long userId) {  
        // 生成全新唯一主键，作为复制后文件的新id  
        Long newFileId = IdUtil.get();  
        // 保存原始文件id，后面查它的子文件夹要用  
        Long oldFileId = record.getId();  
  
        // 1. 修改当前这条副本的属性  
        record.setParentId(targetParentId); // 副本放到指定父目录  
        record.setId(newFileId);             // 覆盖id，变成全新文件记录  
        record.setUserId(userId);            // 文件归属当前操作人  
        record.setCreateUser(userId);  
        record.setUpdateUser(userId);  
        handleDuplicateFilename(record);     // 重名自动加后缀，避免同目录重名冲突  
  
        // 把处理好的新文件记录加入待插入列表  
        allRecords.add(record);  
  
        // 2. 如果当前复制的是文件夹，需要递归复制它所有子文件、子文件夹  
        if (isFolder(record)) {  
            // 根据原始文件夹id，查询它所有直接子级  
//            给一个文件夹 ID，去数据库查出它所有直接下级（文件、子文件夹），只拿没删除的数据。  
//            只查一级子项，不会递归查孙子、曾孙。  
            List<UserFileDO> childRecords = findChildRecords(oldFileId);  
            // 没有子内容直接终止递归  
            if (CollectionUtils.isEmpty(childRecords)) {  
                return;  
            }  
            // 遍历每一个子项，递归复制  
            // 注意第二个参数newFileId：子文件的父目录是刚复制出来的新文件夹id  
//            查询原文件夹所有一级子内容，逐个递归复制，并且让复制后的子内容挂载到新复制出来的父文件夹下，完整复刻整套目录树。  
            childRecords.forEach(childRecord -> assembleCopyChildRecord(allRecords, childRecord, newFileId, userId));  
        }  
    }

生成新的 user_file.id
parent_id 改成目标目录 ID
real_file_id 保持不变
保存为一条新的 user_file 记录

先复制文件夹本身
-> 生成新文件夹 ID
-> 查询原文件夹的子节点
-> 子节点 parent_id 指向新文件夹 ID
-> 递归复制整棵 user_file 树

复制的是 user_file 目录视图，不复制 file 物理文件。

原文件 user_file.real_file_id = 100
复制后 user_file.real_file_id = 100

只复制数据库目录记录，不复制真实文件内容。

文件复制会递归复制 user_file 树，为每条新记录生成新 id，但普通文件仍复用原来的 real_file_id，不会复制物理文件。

const showFolderTreeDialog = ref(false)
const folderTree = ref([])
const targetParentId = ref('')
const operationMode = ref('transfer') // transfer / copy
const operationFiles = ref([])

async function openFolderDialog(mode, files) {
  operationMode.value = mode
  operationFiles.value = files
  targetParentId.value = ''

  const response = await getFolderTree()
  folderTree.value = response.data || []

  showFolderTreeDialog.value = true
}

async function confirmFolderOperation() {
  if (!targetParentId.value) {
    ElMessage.warning('请选择目标文件夹')
    return
  }

  const ids = operationFiles.value.map(file => String(getFileId(file)))

  if (operationMode.value === 'transfer') {
    await transferFiles({
      fileIds: ids,
      targetParentId: targetParentId.value
    })
    ElMessage.success('移动成功')
  } else {
    await copyFiles({
      fileIds: ids.join(','),
      targetParentId: targetParentId.value
    })
    ElMessage.success('复制成功')
  }

  showFolderTreeDialog.value = false
  await refreshCurrentFolder()
}

<el-dialog v-model="showFolderTreeDialog" title="选择目标文件夹">
  <el-tree
    :data="folderTree"
    node-key="id"
    :props="{ label: 'name', children: 'children' }"
    highlight-current
    @node-click="node => targetParentId = node.id"
  />

  <template #footer>
    <el-button @click="showFolderTreeDialog = false">取消</el-button>
    <el-button type="primary" @click="confirmFolderOperation">确定</el-button>
  </template>
</el-dialog>

user_file 管“用户看到的目录结构和文件名”。

file 管“真实文件存在哪里、大小多少、怎么预览”。

user_file = 用户网盘视图
file = 真实物理文件元数据

file 像仓库里的真实货物
user_file 像用户货架上的标签和摆放位置
复制、移动、重命名，大多是在改货架标签；
上传、预览、下载，才会真正碰到仓库里的货物。

GET /api/v1/files/file/folder/tree

@GetMapping("/file/folder/tree")
public Result<List<FolderTreeNodeVO>> getFolderTree() {
    QueryFolderTreeContext context = new QueryFolderTreeContext();
    context.setUserId(UserIdUtil.get());

    List<FolderTreeNodeVO> result = userFileService.getFolderTree(context);
    return Result.success(result);
}

public List<FolderTreeNodeVO> getFolderTree(QueryFolderTreeContext context) {
    List<UserFileDO> folderRecords = queryFolderRecords(context.getUserId());
    return assembleFolderTreeNodeVOList(folderRecords);
}

private List<UserFileDO> queryFolderRecords(Long userId) {
    QueryWrapper queryWrapper = Wrappers.query();
    queryWrapper.eq("user_id", userId);
    queryWrapper.eq("folder_flag", FolderFlagEnum.YES.getCode());
    queryWrapper.eq("deleted", DeleteEnum.NO.getCode());

    return list(queryWrapper);
}

private List<FolderTreeNodeVO> assembleFolderTreeNodeVOList(List<UserFileDO> folderRecords) {
    List<FolderTreeNodeVO> nodes = folderRecords.stream()
            .map(fileConvertor::userFile2FolderTreeNodeVO)
            .toList();

    Map<Long, List<FolderTreeNodeVO>> map = nodes.stream()
            .collect(Collectors.groupingBy(FolderTreeNodeVO::getParentId));

    for (FolderTreeNodeVO node : nodes) {
        List<FolderTreeNodeVO> children = map.get(node.getId());
        if (CollectionUtils.isNotEmpty(children)) {
            node.getChildren().addAll(children);
        }
    }

    return nodes.stream()
            .filter(node -> Objects.equals(node.getParentId(), FileConstant.TOP_PARENT_ID))
            .collect(Collectors.toList());
}

FileConstant.TOP_PARENT_ID = 0L

parentId = 0

id
parentId
name
children

POST /api/v1/files/file/transfer

{
  "fileIds": ["加密ID1", "加密ID2"],
  "targetParentId": "目标文件夹加密ID"
}

@PostMapping("/file/transfer")
public Result transfer(@Validated @RequestBody TransferFileParamVO transferFileParam) {
    List<Long> fileIdList = transferFileParam.getFileIds()
            .stream()
            .map(IdUtil::decrypt)
            .collect(Collectors.toList());

    TransferFileContext context = new TransferFileContext();
    context.setFileIdList(fileIdList);
    context.setTargetParentId(IdUtil.decrypt(transferFileParam.getTargetParentId()));
    context.setUserId(UserIdUtil.get());

    userFileService.transfer(context);
    return Result.success("");
}

public void transfer(TransferFileContext context) {
    checkTransferCondition(context);

    List<UserFileDO> prepareRecords = context.getPrepareRecords();

    prepareRecords.forEach(record -> {
        record.setParentId(context.getTargetParentId());
        record.setUserId(context.getUserId());
        record.setCreateUser(context.getUserId());
        record.setUpdateUser(context.getUserId());
        handleDuplicateFilename(record);
    });

    if (!updateBatchById(prepareRecords)) {
        throw new SystemException("文件转移失败");
    }
}

private void checkTransferCondition(TransferFileContext context) {
    Long targetParentId = context.getTargetParentId();

    if (!isFolder(getById(targetParentId))) {
        throw new FileException(TARGET_FOLDER_TYPE_ERROR);
    }

    List<UserFileDO> prepareRecords = listByIds(context.getFileIdList());
    context.setPrepareRecords(prepareRecords);

    if (checkIsChildFolder(prepareRecords, targetParentId, context.getUserId())) {
        throw new FileException(FILE_NOT_EXIT);
    }
}

把 user_file.parent_id 从原目录 ID 改成目标目录 ID。

POST /api/v1/files/file/copy

{
  "fileIds": "加密ID1,加密ID2",
  "targetParentId": "目标文件夹加密ID"
}

@PostMapping("/file/copy")
public Result copy(@Validated @RequestBody CopyFileParamVO copyFilePO) {
    String fileIds = copyFilePO.getFileIds();

    List<Long> fileIdList = Splitter.on(BaseConstant.COMMON_SEPARATOR)
            .splitToList(fileIds)
            .stream()
            .map(IdUtil::decrypt)
            .collect(Collectors.toList());

    CopyFileContext context = new CopyFileContext();
    context.setFileIdList(fileIdList);
    context.setTargetParentId(IdUtil.decrypt(copyFilePO.getTargetParentId()));
    context.setUserId(UserIdUtil.get());

    userFileService.copy(context);
    return Result.success("");
}

public void copy(CopyFileContext context) {
    checkCopyCondition(context);

    List<UserFileDO> prepareRecords = context.getPrepareRecords();
    if (EmptyUtil.isEmpty(prepareRecords)) {
        return;
    }

    List<UserFileDO> allRecords = Lists.newArrayList();

    prepareRecords.forEach(record ->
        assembleCopyChildRecord(allRecords, record, context.getTargetParentId(), context.getUserId())
    );

    if (!saveBatch(allRecords)) {
        throw new SystemException("文件复制失败");
    }
}

private void assembleCopyChildRecord(List<UserFileDO> allRecords, UserFileDO record, Long targetParentId, Long userId) {
    Long newFileId = IdUtil.get();
    Long oldFileId = record.getId();

    record.setParentId(targetParentId);
    record.setId(newFileId);
    record.setUserId(userId);
    record.setCreateUser(userId);
    record.setUpdateUser(userId);

    handleDuplicateFilename(record);

    allRecords.add(record);

    if (isFolder(record)) {
        List<UserFileDO> childRecords = findChildRecords(oldFileId);

        childRecords.forEach(childRecord ->
            assembleCopyChildRecord(allRecords, childRecord, newFileId, userId)
        );
    }
}

复制 user_file 目录视图树，不复制 file 物理文件。

用户点击上传 / 拖拽文件
-> UploadButton.vue 把文件加入 simple-uploader 队列
-> 前端暂停上传，先计算 MD5
-> 调用秒传接口 /file/sec-upload
-> 秒传命中：后端直接新增 user_file，前端刷新列表
-> 秒传未命中：前端恢复上传，开始分片上传
-> simple-uploader 上传每个分片到 /file/chunk-upload
-> 后端保存分片物理文件和 file_chunk 记录
-> 后端返回 mergeFlag，表示是否可以合并
-> 前端发现 mergeFlag = READY 后调用 /file/merge
-> 后端合并分片，保存 file 表，再保存 user_file 表
-> 前端刷新当前目录文件列表，移除上传任务

用户点击 / 拖拽选择文件
  ↓
uploader.addFiles(files)
  ↓
文件加入 simple-uploader 队列
  ↓
触发 filesAdded 回调
  ↓
f.pause() 先暂停自动上传
  ↓
前端计算文件 MD5
  ↓
请求秒传接口 /file/sec-upload
  ↓
如果秒传成功：
    后端复用已有 file 记录
    新增 user_file 记录
    前端取消当前上传任务
    前端刷新文件列表
  ↓
如果秒传失败：
    f.resume() 恢复上传
  ↓
simple-uploader 根据 fileOptions 自动切片并上传
  ↓
POST /api/v1/files/file/chunk-upload
  ↓
每个分片成功后触发 fileUploaded
  ↓
fileUploaded 判断所有分片是否上传完成
  ↓
全部完成后调用 doMerge(file)
  ↓
请求 merge 合并接口 /file/merge
  ↓
后端合并分片
  ↓
后端生成 file 记录
  ↓
后端生成 user_file 记录
  ↓
前端刷新文件列表

	2. 执行 `<script setup>` 自上而下代码：
	    - 导入所有依赖、定义 props、实例化 pinia 仓库
	    - 定义全部响应式变量：`uploadDialogVisible、uploader、assignFlag、fileInput、isAlive`
	    - 定义配置 `fileOptions`、所有方法函数（此时只是声明，不执行）

onMounted(() => { initUploader() })

const initUploader = () => {  
  // 1. 清空全局上传任务列表，防止上次上传残留进度  
  taskStore.clear()  
  // 2. 创建上传实例，把上面一大段fileOptions配置传给上传库  
  uploader = new Uploader(fileOptions)  
  // 3. 判断浏览器是否支持分片上传，不支持直接弹窗提示  
  if (!uploader.support) {  
    alert('本浏览器不支持simple-uploader，请更换浏览器重试')  
    return  
  }  
  // 4. 给上传实例绑定【上传库自己的生命周期事件】  
  // uploader.on("事件名", 自己写的回调函数)  
  uploader.on("filesAdded", filesAdded)        // 用户选中/拖拽文件后触发  
  uploader.on("fileProgress", uploadProgress)   // 文件分片上传时，持续返回进度  
  uploader.on("fileSuccess", fileUploaded)      // 某一个分片上传请求成功  
  uploader.on("complete", uploadComplete)       // 所有文件全部上传结束（预留）  
  uploader.on("fileError", uploadError)         // 某个分片上传失败  
}

/** * 点击上传按钮，唤起上传弹窗 */
 const openDialog = () => {
  // 防止重复弹窗：弹窗已经显示就直接退出函数，不执行后面逻辑 
  if (uploadDialogVisible.value) { return } 
  // 重置绑定标记，代表当前还没有给DOM绑定拖拽/点击监听 
  assignFlag.value = false 
  // 控制弹窗显示：响应式变量修改，Vue会触发DOM更新 
  uploadDialogVisible.value = true 
  /** * nextTick 作用： * 修改 uploadDialogVisible 只是告诉Vue要更新页面，
  DOM不会立刻生成 * nextTick 内部回调会等待Vue完成DOM渲染、页面刷新后再执行 
  这里必须等弹窗#upload-content盒子真实存在，才能执行绑定拖拽 */ 
  //等 DOM 渲染完成后，把上传器绑定到上传区域
  nextTick(() => { rebindUploader() }) }

const rebindUploader = () => {
  if (uploader && !uploader.support) return alert('浏览器不支持')
  // 仅未绑定时执行，避免重复绑定
  if (uploader && !assignFlag.value) {
    const uploadContent = document.getElementById('upload-content')
    if (uploadContent) {
      // 先解绑历史残留DOM监听，防止点击多次弹窗、重复上传
      uploader.unAssignBrowse()
      uploader.unAssignDrop()
      // 绑定当前弹窗DOM原生事件
      uploader.assignBrowse(uploadContent) // 绑定click，点击唤起文件选择框
      uploader.assignDrop(uploadContent)    // 绑定drag系列拖拽事件
      assignFlag.value = true // 标记已绑定，不再重复执行
    }
  }
}

<div class="drag-content" 
@click="triggerFileSelect" 
@dragover.prevent
@drop.prevent="handleDrop"
>
将文件拖到此处，或点击上传
</div>

const triggerFileSelect = () => fileInput.value.click()
const handleFileSelect = (event) => {
  const files = Array.from(event.target.files)
  if (uploader) uploader.addFiles(files) // 核心：交给上传库处理文件
  event.target.value = '' // 清空input，支持重复选择同一文件
}

const handleFileSelect = (event) => {
  // 把 FileList 转成数组
  const files = Array.from(event.target.files)
  if (files.length > 0 && uploader) {
    // 把文件交给 simple-uploader 管理
     // 加入上传队列
    uploader.addFiles(files)
    // 清空 input，允许下次选择同名文件也能触发 change
    event.target.value = ''
  }
}

<input 
  ref="fileInput" 
  type="file" 
  multiple 
  style="display: none;" 
  @change="handleFileSelect"
/>

const handleDrop = (event) => {
  // 阻止浏览器默认打开文件行为
  event.preventDefault()
  // 从拖拽事件中取出文件
  const files = Array.from(event.dataTransfer.files)
  if (files.length > 0 && uploader) {
    // 加入上传队列
    uploader.addFiles(files)
  }
}

const fileOptions = {  
  // target：动态定义上传请求的后端接口地址  
  // 开启分片上传 → 请求分片上传接口；否则普通单文件上传接口  
  // file：当前正在上传的完整文件对象  
  // chunk：当前正在传输的分片对象（不分片时为 null）  
  target: function (file, chunk) {  
    if (panUtil.getChunkUploadSwitch()) {  
      return '/api/v1/files/file/chunk-upload'  
    }  
    return '/api/v1/files/file/upload'  
  },  
  
  singleFile: false, // false=支持一次性多选多个文件上传  
  chunkSize: panUtil.getChunkSize(), // 单块分片大小，比如5MB、10MB，大文件自动切成多块  
  testChunks: panUtil.getChunkUploadSwitch(),  
  
  // true开启分片校验：上传前先询问后端哪些分片已经传完，实现断点续传  
  forceChunkSize: false, // 最后一块文件允许小于分片大小，不用强制补齐  
  simultaneousUploads: 3, // 同时并发3个分片请求，控制上传并发，防止请求太多卡死  
  fileParameterName: 'file',  
  
  // 每次上传请求自动拼接 URL 查询参数（?parentId=xxx）  
  // 业务含义：parentId 文件上传到哪个文件夹，后端根据这个 ID 存入对应目录  
  // query：每一次上传请求，自动携带额外GET参数  
  query: function (file, chunk) {  
    return {  
      parentId: fileStore.currentFolderId || '0'  
      // parentId = 文件要上传到哪个文件夹，传给后端做目录存储  
    }  
  },  
  
  // headers：每次上传请求携带请求头，用于登录鉴权  
  // 后端拦截器读取 Authorization 校验登录状态，没 token 直接返回 401 无权限  
  headers: function () {  
    return {  
      Authorization: `${userStore.token}`  
      // token凭证，后端校验当前登录用户是否有权限上传  
    }  
  },  
  
  // 断点续传核心：后端返回已上传分片，判断当前分片是否不需要重复上传  
  // chunk：当前待上传分片对象，chunk.offset = 当前分片序号（从 0 开始）  
  // message：后端分片预校验接口返回的原始字符串  
  // 解析后端返回的 JSON；解析失败直接判定分片不存在，需要上传  
  // 后端返回 uploadedChunks: [1,2,3] 代表 1、2、3 号分片已上传  
  // chunk.offset 是 0 开始，所以 + 1 和后端分片编号对齐  
  // 找到当前分片编号 → return true，库自动跳过本次分片上传；找不到则正常上传  
  // true：分片已存在，跳过不上传  
  // false：分片缺失，正常发起上传请求  
  checkChunkUploadedByResponse: function (chunk, message) {  
    let objMessage = {}  
    try {  
      objMessage = JSON.parse(message)  
    } catch (e) {  
      // 后端返回不是标准JSON，代表没有已上传分片  
    }  
    // 后端返回数组 uploadedChunks，存着已经上传完成的分片编号  
    if (objMessage.data) {  
      // 当前分片编号是否存在数组里，存在=true 跳过上传  
      return (objMessage.data.uploadedChunks || []).indexOf(chunk.offset + 1) >= 0  
    }  
    return false  
  },  
  
  maxChunkRetries: 0, // 分片上传失败，不自动重试  
  chunkRetryInterval: null,  
  progressCallbacksInterval: 500,  
  // 进度更新节流，每500毫秒才执行一次进度回调，避免频繁刷新页面DOM造成卡顿  
  successStatuses: [200, 201, 202],  
  // HTTP状态码是这三个，代表本次分片请求成功  
  permanentErrors: [404, 415, 500, 501],  
  // 遇到这些错误码，判定永久失败，不再重复上传分片  
  initialPaused: false // 文件添加后自动开始上传，不会暂停  
}

getChunkSize() {
  // 当前开启分片上传，所以每片 1MB
  if (this.getChunkUploadSwitch()) {
    return 1024 * 1024 * 1
  }
  // 如果不开分片，就把最大文件大小作为整文件大小
  return this.getMaxFileSize()
},

getMaxFileSize() {
  // 前端单文件最大 3GB
  return 1024 * 1024 * 1024 * 3
},
getChunkUploadSwitch() {
  // 当前固定开启分片上传
  return true
}

1. 暂停上传
2. 校验文件大小
3. 创建前端上传任务，显示进度面板
4. 计算文件 MD5
5. 请求秒传接口
6. 秒传成功就不上传内容
7. 秒传失败才恢复切片上传

 * @param {Array} files 当前本次新增的文件实例数组（库封装的File对象）  
 * @param {Array} fileList 上传器全部文件队列  
 * @param {Event} event 原生拖拽/文件选择事件对象  
 * @returns {boolean} 返回true代表允许加入上传队列，false拒绝加入  
 */  
const filesAdded = (files, fileList, event) => {  
  // 防护判断：组件已经被销毁、上传实例不存在，直接终止逻辑，防止控制台报错、内存泄漏  
  if (!isAlive || !uploader) return false  
  // 选中文件后自动关闭上传弹窗，不需要停留在弹窗页面  
  uploadDialogVisible.value = false  
  
  try {  
    // 循环处理每一个选中的文件  
    files.forEach((f) => {  
      // 1. 先暂停自动上传，阻塞分片传输  
      // 原因：需要先算MD5、调用秒传接口，确认没有云端相同文件再开启上传  
      f.pause()  
  
      // 2. 文件大小校验，超出系统限制直接抛异常拦截全部上传  
      if (f.size > panUtil.getMaxFileSize()) {  
        throw new Error('文件：' + f.name + '大小超过了最大上传文件的限制（' + panUtil.translateFileSize(panUtil.getMaxFileSize()) + '）')  
      }  
  
      // 3. 组装上传任务对象，存入全局任务仓库，底部上传面板读取该数据展示进度  
      let taskItem = {  
        target: f,                          // 当前文件上传实例，用于暂停/取消上传  
        filename: f.name,                   // 文件名称  
        fileSize: panUtil.translateFileSize(f.size), // 总大小，字节转成易读单位（MB/GB）  
        uploadedSize: panUtil.translateFileSize(0), // 已上传大小，初始0  
        status: panUtil.fileStatus.PARSING.code,      // 任务状态：正在解析MD5  
        statusText: panUtil.fileStatus.PARSING.text,  
        timeRemaining: panUtil.translateTime(Number.POSITIVE_INFINITY), // 剩余时间初始无穷大  
        speed: panUtil.translateSpeed(f.averageSpeed), // 上传速度  
        percentage: 0,                      // 上传进度百分比初始0  
        parentId: String(fileStore.currentFolderId || '0') // 目标上传文件夹ID  
      }  
  
      // 将当前文件任务添加到全局上传任务列表  
      taskStore.add(taskItem)  
      // 自动展开页面底部上传任务面板，展示所有上传进度  
      taskStore.updateViewFlag(true)  
  
      // 4. 读取本地文件二进制，计算MD5哈希值（文件唯一指纹）  
      MD5(f.file, (e, md5) => {  
        // 将MD5赋值给文件内置唯一标识，用于分片断点续传、后端秒传匹配  
        f['uniqueIdentifier'] = md5  
  
        // 5. 请求后端秒传接口，校验云端是否存在相同MD5文件  
        //         只要函数返回 Promise，就能链式调用 .then()、.catch()。  
// secUpload 发网络请求是异步，不会阻塞代码，请求成功后自动执行 .then 里的回调函数。
        secUpload({  
          filename: f.name,  
          identifier: md5,  
          // 如果为空 /undefined，兜底默认根目录 '0'。
          parentId: fileStore.currentFolderId || '0'  
        }).then(res => {  
          // 后端返回成功，代表服务器已存在一模一样的文件，直接秒传完成  
          if (res.code === 0 || res.success === true) {  
            f.cancel() // 取消当前文件分片上传队列，无需发起HTTP请求  
            taskStore.remove(f.name) // 从底部任务列表移除该任务  
            fileStore.loadFileList() // 刷新当前文件夹文件列表，秒传文件立刻展示  
  
            // 判断上传队列是否已无待上传文件，关闭底部上传面板  
            if (uploader && Array.isArray(uploader.files) && uploader.files.length === 0) {  
              taskStore.updateViewFlag(false)  
            }  
          } else {  
            // 云端无匹配文件，需要正常分片上传  
            f.resume() // 恢复文件上传，库自动切割分片并发请求  
            // 更新任务状态为等待上传  
            taskStore.updateStatus({  
              filename: f.name,  
              status: panUtil.fileStatus.WAITING.code,  
              statusText: panUtil.fileStatus.WAITING.text  
            })  
          }  
        }).catch(err => {  
          // 秒传接口网络/服务异常，放弃秒传逻辑，正常执行分片上传  
          f.resume()  
          taskStore.updateStatus({  
            filename: f.name,  
            status: panUtil.fileStatus.WAITING.code,  
            statusText: panUtil.fileStatus.WAITING.text  
          })  
        })  
      })  
    })  
  } catch (e) {  
    // 捕获文件大小超限抛出的异常  
    alert(e.message)  
    // 终止所有正在进行的上传请求  
    if (uploader && typeof uploader.cancel === 'function') {  
      try { uploader.cancel() } catch (err) {}  
    }  
    // 清空全部上传任务  
    taskStore.clear()  
    // 返回false，拒绝文件加入上传队列  
    return false  
  }  
  
  // 确保底部上传面板保持展开  
  taskStore.updateViewFlag(true)  
  // 返回true，允许文件加入上传队列  
  return true  
}

export function MD5(file, callback) {  
    // 分片读取大小：2MB = 2 * 1024 * 1024 = 2097152 字节  
    const chunkSize = 2097152  
    // 计算文件一共要拆分成多少块读取  
    const chunks = Math.ceil(file.size / chunkSize)  
    // SparkMD5：专门用来计算ArrayBuffer二进制数据MD5的工具实例  
    const spark = new SparkMD5.ArrayBuffer()  
    // 浏览器内置文件读取对象，异步读取本地文件二进制  
    const fileReader = new FileReader()  
    // 当前读到第几块分片，初始0  
    let currentChunk = 0  
  
    // 文件单块读取成功完成的回调  
    fileReader.onload = function (e) {  
        // 将本次读取到的二进制数据追加到MD5计算器中  
        spark.append(e.target.result)  
        // 读完一块，块计数+1  
        currentChunk++  
  
        // 判断是否还有剩余分片没读  
        if (currentChunk < chunks) {  
            // 还有分片，继续读取下一块  
            loadNext()  
        } else {  
            // 所有分片读取完毕，算出最终MD5  
            // 第一个参数null=无错误，第二个是md5结果字符串，传给外部回调  
            callback(null, spark.end())  
        }  
    }  
  
    // 文件读取发生错误（文件损坏、权限不足等）  
    fileReader.onerror = function (e) {  
        // 直接把错误对象传给外部回调，只传一个参数  
        callback(e)  
    }  
    //读取下一块文件分片的内部函数  
    function loadNext() {  
        // 计算本次分片起始字节位置  
        const start = currentChunk * chunkSize  
        // 结束位置，防止超出文件总大小  
        const end = Math.min(start + chunkSize, file.size)  
        // file.slice：截取文件指定区间二进制分片  
        // readAsArrayBuffer：以二进制数组形式读取分片  
    //     FileReader 是浏览器自带读取文件的 API，读取文件是异步操作：  
//     // 调用 fileReader.readAsArrayBuffer(分片) 只是告诉浏览器 “去读这块文件”，代码不会卡住等待读取完成；  
//         浏览器读完二进制分片后，会自动触发 onload 事件；  
// 你提前给 onload 赋值一个函数，浏览器读完后自动执行这个函数，把读取结果通过参数 e 传给你；  
// 参数 e 是浏览器原生事件对象，e.target.result 就是本次读取到的文件二进制数组。  
        fileReader.readAsArrayBuffer(file.slice(start, end))  
    }  
  
    // 函数入口，直接启动读取第一块分片  
    loadNext()  
}

第 1 块
第 2 块
第 3 块
...

上传百分比
上传速度
已上传大小
剩余时间
上传状态

const uploadProgress = (rootFile, file, chunk) => {
  if (!isAlive) return
  const task = taskStore.getUploadTask(file.name)
  if (file.isUploading()) {
    // 更新任务状态为上传中
    taskStore.updateStatus({status:上传中})
    // 更新进度、速度、已上传大小、剩余时间存入全局任务仓库
    taskStore.updateProcess({percentage, speed, uploadedSize, timeRemaining})
  }
}

* 作用：解析后端返回结果，判断是否全部分片上传完成，需要调用合并分片接口  
* @param rootFile 顶层文件封装对象（多文件队列顶层容器，业务基本不用）  
* @param file 当前完整文件实例（整个大文件对象，包含所有分片信息）  
* @param message 后端分片上传接口返回的原始响应文本字符串  
* @param chunk 当前刚上传完成的单个分片对象  
*/
const fileUploaded = (rootFile, file, message, chunk) => {  
  // 防护拦截：组件已经销毁，直接终止，防止页面卸载后回调报错  
  if (!isAlive) return  
  
  // 初始化接收后端返回数据的对象  
  let res = {}  
  try {  
    // 将后端返回的字符串转成JSON对象，方便读取code、data等字段  
    res = JSON.parse(message)  
  } catch (e) {  
    // 转换失败：后端返回不是标准JSON，直接跳过后续判断  
  }  
  
  // 判断后端返回业务成功（code=0 / success=true 代表本次分片上传成功）  
  if (res.code === 0 || res.success === true) {  
    // 后端有返回data字段，代表开启了分片上传逻辑  
    if (res.data) {  
      // 两种条件满足任意一种，说明所有分片已经上传完毕，需要后端拼接文件  
      // 条件1：后端主动标记需要合并文件 mergeFlag=true      
      if (res.data.mergeFlag) {  
        doMerge(file)  
      }  
      // 条件2：后端返回已上传分片列表长度 = 文件总分片数量，代表全部传完  
      else if (res.data.uploadedChunks && res.data.uploadedChunks.length === file.chunks.length) {  
        doMerge(file)  
      }  
    } else {  
      // 无data数据 = 未开启分片，小文件一次性上传完成，无需合并  
      // 从上传队列移除当前文件  
      if (uploader && typeof uploader.removeFile === 'function') {  
        uploader.removeFile(file)  
      }  
      // 刷新当前目录文件列表，新文件立刻展示在页面  
      fileStore.loadFileList()  
      // 修改任务状态为上传成功  
      taskStore.updateStatus({  
        filename: file.name,  
        status: panUtil.fileStatus.SUCCESS.code,  
        statusText: panUtil.fileStatus.SUCCESS.text  
      })  
      // 从全局上传任务列表删除本条任务  
      taskStore.remove(file.name)  
      // 如果上传队列没有剩余文件，自动关闭底部上传任务面板  
      if (uploader && Array.isArray(uploader.files) && uploader.files.length === 0) {  
        taskStore.updateViewFlag(false)  
      }  
    }  
  } else {  
    // 后端返回业务失败（比如参数错误、存储失败等）  
    file.pause() // 暂停该文件所有分片上传  
    // 更新任务状态为上传失败  
    taskStore.updateStatus({  
      filename: file.name,  
      status: panUtil.fileStatus.FAIL.code,  
      statusText: panUtil.fileStatus.FAIL.text  
    })  
  }  
}

/**  
 * 所有分片上传完成后，调用后端接口合并分片  
 * 触发时机：fileUploaded 判断全部分片上传完毕时调用  
 * @param {File} file simple-uploader封装的当前完整文件实例  
 */  
const doMerge = (file) => {  
  // 组件已销毁直接退出，防止异步回调执行时报错、操作已销毁的页面仓库  
  if (!isAlive) return  
  
  // 根据文件名从全局Pinia任务仓库取出这条文件的上传任务  
  let uploadTaskItem = taskStore.getUploadTask(file.name)  
  
  // 更新上传任务状态：变更为【分片中】  
  taskStore.updateStatus({  
    filename: file.name,  
    status: panUtil.fileStatus.MERGE.code,  
    statusText: panUtil.fileStatus.MERGE.text  
  })  
  // 更新进度面板数值：固定99%，代表分片全部传完正在后台拼接  
  taskStore.updateProcess({  
    filename: file.name,  
    speed: panUtil.translateSpeed(file.averageSpeed),  
    percentage: 99,  
    uploadedSize: panUtil.translateFileSize(file.sizeUploaded()),  
    timeRemaining: panUtil.translateTime(file.timeRemaining())  
  })  
  
  // 调用后端分片合并接口，传递拼接需要的全部参数  
  mergeChunks({  
    filename: uploadTaskItem.filename,        // 文件原始名称  
    identifier: uploadTaskItem.target.uniqueIdentifier, // 文件MD5标识，后端匹配分片  
    parentId: uploadTaskItem.parentId,        // 文件存放目标文件夹ID  
    totalSize: uploadTaskItem.target.size     // 文件完整总字节大小  
  }).then(res => {  
    // 后端合并分片业务成功  
    if (res.code === 0 || res.success === true) {  
      // 从上传器队列移除该文件，不再占用上传队列  
      if (uploader && typeof uploader.removeFile === 'function') {  
        uploader.removeFile(file)  
      }  
      // 刷新当前目录文件列表，展示刚上传完成的文件  
      fileStore.loadFileList()  
      // 修改任务状态为上传成功  
      taskStore.updateStatus({  
        filename: file.name,  
        status: panUtil.fileStatus.SUCCESS.code,  
        statusText: panUtil.fileStatus.SUCCESS.text  
      })  
      // 从底部上传任务面板删除本条任务  
      taskStore.remove(file.name)  
      // 如果上传队列没有剩余文件，自动收起底部上传面板  
      if (uploader && Array.isArray(uploader.files) && uploader.files.length === 0) {  
        taskStore.updateViewFlag(false)  
      }  
    } else {  
      // 后端返回业务失败（分片缺失、拼接异常等）  
      file.pause() // 暂停该文件所有上传流程  
      taskStore.updateStatus({  
        filename: file.name,  
        status: panUtil.fileStatus.FAIL.code,  
        statusText: panUtil.fileStatus.FAIL.text  
      })  
    }  
  }).catch(err => {  
    // 合并接口网络异常、500、404等网络层面错误  
    file.pause()  
    taskStore.updateStatus({  
      filename: file.name,  
      status: panUtil.fileStatus.FAIL.code,  
      statusText: panUtil.fileStatus.FAIL.text  
    })  
  })  
}

target: function (file, chunk) { 
	if (panUtil.getChunkUploadSwitch()) { 
		return '/api/v1/files/file/chunk-upload' // 分片上传接口 
		} 
		return '/api/v1/files/file/upload' // 普通整文件上传接口 
}

const closeDialog = () => {
  uploadDialogVisible.value = false
  assignFlag.value = false
  // 解绑DOM拖拽、点击监听
  uploader.unAssignBrowse()
  uploader.unAssignDrop()
}

export function secUpload(data) {
  return fileRequest({
    url: '/file/sec-upload',
    method: 'post',
    data
  })
}

{
  "filename": "a.pdf",
  "identifier": "文件MD5",
  "parentId": "当前目录ID"
}

@PostMapping("/file/sec-upload")
public Result secUpload(@Validated @RequestBody SecUploadFileParamVO secUploadFileParam) {
    // 前端参数转换成业务上下文，同时会解密 parentId、补充当前 userId
    SecUploadFileContext context = fileConvertor.secUploadFileParamToSecUploadFileContext(secUploadFileParam);
    // 调用业务层判断是否能秒传
    boolean result = userFileService.secUpload(context);

    if (!result) {
        // 秒传未命中，返回 FILE_NOT_EXIT，前端把它当成正常分支继续上传
        return Result.error(FILE_NOT_EXIT.getCode(), FILE_NOT_EXIT.getMessage());
    }
    // 秒传命中
    return Result.success("");
}

    /**  
     * 秒传核心业务方法  
     * @Override 重写上层接口定义的secUpload方法  
     * @param context 秒传请求上下文对象，封装前端传参：文件名、md5(identifier)、目标文件夹parentId、当前登录userId  
     * @return boolean true=秒传成功，false=无匹配文件，需要前端走分片上传  
     */  
    @Override  
    public boolean secUpload(SecUploadFileContext context) {  
        // 1. 校验登录用户ID不能为空，无用户直接抛业务异常  
        if (Objects.isNull(context.getUserId())) {  
            throw new SystemException("秒传失败：用户ID不能为空");  
        }  
  
        // 2. 根据 用户ID + 文件MD5标识 查询物理文件表FileDO  
        // 查询：当前系统内有没有已经上传过的一模一样的文件  
        List<FileDO> fileList = getFilesByUserIdAndIdentifier(context.getUserId(), context.getIdentifier());  
  
        // 3. 查询结果为空 → 不存在相同文件，返回false，前端需要正常分片上传  
        if (EmptyUtil.isEmpty(fileList)) {  
            return false;  
        }  
  
        // 4. 存在相同MD5文件，取第一条物理文件记录  
//        正常设计里同一个 MD5 只会对应一条物理文件记录，  
//        即便因为历史原因出现多条，它们指向的文件二进制也完全相同，不影响秒传结果，因此直接取下标 0 的第一条即可，不需要额外排序筛选。  
        FileDO record = fileList.get(BaseConstant.ZERO_INT);  
  
        // 5. 新增用户网盘目录记录 user_file（核心秒传逻辑，不用传文件）  
        // 不用接收二进制分片，直接复制已有物理文件记录到目标文件夹  
//        不是创建数据表，是往已经存在的 user_file（用户文件目录表）里插入一行新数据。  
//        它的作用是：给当前登录用户的目标文件夹，挂上一份已经存在的物理文件引用 ——//        用户在网盘里能看到这个文件，但服务器不需要重复存储文件内容，这就是 “秒传” 的核心：只写数据库，不传文件二进制。  
        saveUserFile(  
                context.getParentId(),                          // 文件上传到哪个文件夹ID  
                context.getFilename(),                          // 前端上传的文件原名  
                FolderFlagEnum.NO,                               // 是否文件夹：NO=普通文件  
                FileTypeEnum.getFileTypeCode(FileUtil.getFileSuffix(context.getFilename())), // 根据后缀获取文件类型编码  
                record.getId(),                                  // 已有物理文件主键ID（关联底层文件）  
                context.getUserId(),                             // 当前登录用户ID  
                record.getFileSizeDesc()                         // 文件大小展示文本  
        );  
  
        // 6. 秒传完成，返回true，前端收到后直接取消上传、刷新文件列表  
        return true;  
    }

不上传文件内容
-> 复用已有 file 记录
-> 新增一条 user_file

同一用户 + 相同 identifier

前端选择文件
  ↓
计算 MD5
  ↓
秒传失败
  ↓
进入分片上传
  ↓
每个分片单独 POST 到后端
  ↓
后端保存临时分片文件 + file_chunk 分片记录
  ↓
所有分片上传完成
  ↓
前端调用 merge 接口
  ↓
后端合并分片，生成真实文件
  ↓
保存 file 表
  ↓
保存 user_file 表
  ↓
前端刷新文件列表

chunk-upload：只保存某一个分片，不代表完整文件上传完成。
merge：把所有分片拼成完整文件，才是真正上传完成。

export function getUploadedChunks(params) {
  return fileRequest({
    url: '/file/chunk-upload',
    method: 'get',
    params
  })
}

{
  "success": true,
  "data": {
    "uploadedChunks": [1, 2, 3]
  }
}

@GetMapping("/file/chunk-upload")  
public Result<UploadedChunkListVO> getUploadedChunks(@Validated QueryUploadedChunkListParamVO queryUploadedChunkListParam) {  
    // 参数转换，前端查询参数转业务上下文  
    QueryUploadedChunksContext context = fileConvertor.queryUploadedChunksParam2QueryUploadedChunksContext(queryUploadedChunkListParam);  
    // 业务层查询数据库，拿到已上传分片编号集合  
    List<Integer> uploadedChunkList = userFileService.getUploadedChunkList(context);  
    // 封装返回给前端  
    UploadedChunkListVO uploadedChunkListVO = new UploadedChunkListVO();  
    uploadedChunkListVO.setUploadedChunks(uploadedChunkList);  
    return Result.success(uploadedChunkListVO);  
}

@Override  
public List<Integer> getUploadedChunkList(QueryUploadedChunksContext context) {  
    // 1. 创建通用查询条件构造器  
    QueryWrapper queryWrapper = Wrappers.query();  
    // 只查询数据库chunk_number分片编号字段，减少数据传输  
    queryWrapper.select("chunk_number");  
    // 条件1：匹配文件MD5唯一标识，区分不同文件分片  
    queryWrapper.eq("identifier", context.getIdentifier());  
    // 条件2：匹配当前登录用户，只查自己上传的分片，隔离多用户数据  
    queryWrapper.eq("create_user", context.getUserId());  
    // 条件3：分片有效期大于当前时间，过滤已过期清理的临时分片  
    queryWrapper.gt("expiration_time", new Date());  
  
    // 执行查询，只取出chunk_number字段并强转为Integer分片编号  
    List<Integer> uploadedChunks = fileChunkService.listObjs(queryWrapper, value -> (Integer) value);  
    return uploadedChunks;  
}

{
  "success": true,
  "data": {
    "uploadedChunks": [1, 2, 3]
  }
}

return (objMessage.data.uploadedChunks || []).indexOf(chunk.offset + 1) >= 0

如果后端说第 1、2、3 片已经有了，前端本次就跳过这些分片，只传缺失的分片。

POST /api/v1/files/file/chunk-upload

1. 把前端参数转换成业务上下文
2. 调用 UserFileServiceImpl.chunkUpload(...)
3. 返回 mergeFlag，告诉前端是否可以合并

@PostMapping("/file/chunk-upload")
public Result<FileChunkUploadVO> chunkUpload(
        @Validated FileChunkUploadParamVO fileChunkUploadParam
) {
    // 参数转换为业务上下文，补充 userId 等信息
    FileChunkUploadContext context =
        fileConvertor.fileChunkUploadParamToFileChunkUploadContext(fileChunkUploadParam);

    // 保存当前分片，并判断是否可以合并
    Integer code = userFileService.chunkUpload(context);

    // 返回 mergeFlag 给前端
    FileChunkUploadVO vo = new FileChunkUploadVO();
    vo.setMergeFlag(code);

    return Result.success(vo);
}

0 = 当前还不能合并
1 = 所有分片已上传完成，可以调用 merge 接口

/**  
 * 接收前端单块分片上传，保存临时分片记录  
 * @DistributeLock 分布式锁注解，防止并发重复上传同一块分片  
 * @param context 分片上传上下文：用户ID、文件MD5、分片序号、分片二进制等  
 * @return 数字标记mergeFlag，告诉前端是否所有分片已上传完成  
 */  
// 分布式锁：场景标识FILE_CHUNK_UPLOAD  
// 锁key = 当前用户ID + "-" + 文件MD5，同一个用户同一个文件互斥  
@DistributeLock(scene = "FILE_CHUNK_UPLOAD", keyExpression = "#context.userId + '-' + #context.identifier")  
@Override  
public Integer chunkUpload(FileChunkUploadContext context) {  
    // 转换器：把接口入参上下文转为分片存储专用上下文  
    FileChunkSaveContext fileChunkSaveContext = fileConvertor.fileChunkUploadContextToFileChunkSaveContext(context);  
    // 业务层：保存当前这块分片（存文件二进制 + 插入file_chunk分片表记录）  
    fileChunkService.saveChunkFile(fileChunkSaveContext);  
    // 返回是否需要合并分片的标识给前端  
    return fileChunkSaveContext.getMergeFlagEnum().getCode();  
}

/**  
 * 接收前端单块分片上传，保存临时分片记录  
 * @DistributeLock 分布式锁注解，防止并发重复上传同一块分片  
 * @param context 分片上传上下文：用户ID、文件MD5、分片序号、分片二进制等  
 * @return 数字标记mergeFlag，告诉前端是否所有分片已上传完成  
 */  
// 分布式锁：场景标识FILE_CHUNK_UPLOAD  
// 锁key = 当前用户ID + "-" + 文件MD5，同一个用户同一个文件互斥  
@DistributeLock(scene = "FILE_CHUNK_UPLOAD", keyExpression = "#context.userId + '-' + #context.identifier")  
@Override  
public Integer chunkUpload(FileChunkUploadContext context) {  
    // 转换器：把接口入参上下文转为分片存储专用上下文  
    FileChunkSaveContext fileChunkSaveContext = fileConvertor.fileChunkUploadContextToFileChunkSaveContext(context);  
    // 业务层：保存当前这块分片（存文件二进制 + 插入file_chunk分片表记录）  
    fileChunkService.saveChunkFile(fileChunkSaveContext);  
    // 返回是否需要合并分片的标识给前端  
    return fileChunkSaveContext.getMergeFlagEnum().getCode();  
}

@Around("@annotation(com.disk.lock.DistributeLock)")
public Object process(ProceedingJoinPoint pjp) throws Exception {
    // 1. 拿到当前被拦截的方法，比如 chunkUpload(...)
    Method method = ((MethodSignature) pjp.getSignature()).getMethod();

    // 2. 读取方法上的 @DistributeLock 注解
    DistributeLock distributeLock = method.getAnnotation(DistributeLock.class);

    // 3. 先取固定 key；如果没写固定 key，就解析 keyExpression
    String key = distributeLock.key();

    if (DistributeLockConstant.NONE_KEY.equals(key)) {
        // 4. 解析 SpEL 表达式，例如：
        // #context.userId + '-' + #context.identifier
        SpelExpressionParser parser = new SpelExpressionParser();
        Expression expression = parser.parseExpression(distributeLock.keyExpression());

        // 5. 创建表达式上下文，用来存放方法参数
        EvaluationContext context = new StandardEvaluationContext();

        // 6. 获取方法实参，比如 chunkUpload(FileChunkUploadContext context)
        Object[] args = pjp.getArgs();

        // 7. 获取方法参数名，比如 ["context"]
        StandardReflectionParameterNameDiscoverer discoverer =
                new StandardReflectionParameterNameDiscoverer();
        String[] parameterNames = discoverer.getParameterNames(method);

        // 8. 把参数名和参数值绑定到 SpEL 上下文中
        // 这样 SpEL 才能识别 #context.userId
        if (parameterNames != null) {
            for (int i = 0; i < parameterNames.length; i++) {
                context.setVariable(parameterNames[i], args[i]);
            }
        }

        // 9. 执行表达式，得到真正的业务 key
        // 例如：10001-abcxxxmd5
        key = String.valueOf(expression.getValue(context));
    }

    // 10. 拼接最终锁 key
    // 例如：FILE_CHUNK_UPLOAD#10001-abcxxxmd5
    String lockKey = distributeLock.scene() + "#" + key;

    // 11. 从 Redisson 中获取一把分布式锁
    RLock rLock = redissonClient.getLock(lockKey);

    // 12. 加锁；当前项目默认是 lock()，拿不到锁会等待
    rLock.lock();

    try {
        // 13. 真正执行原来的业务方法，也就是 chunkUpload(...)
        return pjp.proceed();
    } finally {
        // 14. 无论业务成功还是失败，最后都释放锁
        rLock.unlock();
    }
}

请求调用 chunkUpload
  ↓
AOP 发现方法上有 @DistributeLock
  ↓
读取注解里的 scene 和 keyExpression
  ↓
解析 SpEL，拿到 userId 和 identifier
  ↓
拼出 lockKey
  ↓
通过 Redisson 获取 Redis 分布式锁
  ↓
拿到锁后，执行真正的 chunkUpload 方法
  ↓
方法执行完，无论成功还是异常，都在 finally 中释放锁

清理无效旧记录
  ↓
判断当前分片是否已经上传
  ↓
如果已上传：不重复保存，只判断是否可以合并
  ↓
如果未上传：保存物理分片，再插入 file_chunk 记录
  ↓
统计有效分片数量，判断是否全部上传完成

@Override  
public void saveChunkFile(FileChunkSaveContext context) {  
    // 第一步：清理当前文件对应的无效/过期分片记录（比如传了一半放弃、超时过期的分片）  
    clearInvalidChunkRecord(context);  
  
    // 第二步：检查当前这个分片，是不是已经上传过了（断点续传：避免重复上传同一个分片）  
    if (checkChunkUploaded(context)) {  
        // 分片已经存在 → 不用重复存文件，直接判断是否所有分片都传完了  
        doJudgeMergeFile(context);  
        return; // 直接结束，不执行后面的存文件逻辑  
    }  
  
    // 第三步：分片没传过 → 真正保存这个分片  
    // 包含两步：1. 把分片的二进制文件存到磁盘/云存储；2. 往数据库插一条分片记录  
    doSaveChunkFile(context);  
  
    // 第四步：保存完当前分片后，再次判断：所有分片是不是都传齐了？要不要合并？  
    doJudgeMergeFile(context);  
}

/**  
 * 检查【当前这个分片】是否已经上传过了  
 * 核心作用：实现断点续传——同一个分片不用重复传，节省时间  
 * @return true=已经传过了；false=还没传  
 */  
private boolean checkChunkUploaded(FileChunkSaveContext context) {  
    // MyBatis-Plus 条件构造器：拼接查询SQL的条件  
    QueryWrapper<FileChunkDO> queryWrapper = Wrappers.query();  
    // 条件1：同一个文件（MD5标识相同，就是同一个文件的分片）  
    queryWrapper.eq("identifier", context.getIdentifier());  
    // 条件2：同一个分片号（比如第3块）  
    queryWrapper.eq("chunk_number", context.getChunkNumber());  
    // 条件3：同一个用户上传的  
    queryWrapper.eq("create_user", context.getUserId());  
    // 条件4：分片记录还没过期（过期的分片是无效的，不算）  
    queryWrapper.gt("expiration_time", new Date());  
  
    // 统计符合条件的记录数，大于0就说明这个分片已经传过了  
    return count(queryWrapper) > 0L;  
}


/**  
 * 判断：当前文件的所有分片是不是都传完了？要不要触发合并？  
 * 逻辑：数一下有效分片总数 = 前端传的总分片数吗？相等就说明传齐了  
 */  
private void doJudgeMergeFile(FileChunkSaveContext context) {  
    QueryWrapper<FileChunkDO> queryWrapper = Wrappers.query();  
    // 同一个文件（同一个MD5标识）  
    queryWrapper.eq("identifier", context.getIdentifier());  
    // 同一个用户  
    queryWrapper.eq("create_user", context.getUserId());  
    // 只统计没过期的有效分片  
    queryWrapper.gt("expiration_time", new Date());  
  
    // 查询当前文件一共已经传了多少个有效分片  
    long count = count(queryWrapper);  
  
    // 如果已传分片数 = 文件总分片数 → 说明全传完了，标记为「可以合并」  
    // 前端收到这个标记，就会调用合并接口  
    if (count == context.getTotalChunks().longValue()) {  
        context.setMergeFlagEnum(MergeFlagEnum.READY);  
    }  
}

/**  
 * 保存分片的总调度：先存文件到磁盘，再存记录到数据库  
 */  
private void doSaveChunkFile(FileChunkSaveContext context) {  
    // 1. 把分片的二进制文件，真正存到磁盘/云存储里  
    doStoreFileChunk(context);  
    // 2. 往数据库的分片记录表，插一条记录，标记「这个分片存好了、存在哪」  
    doSaveRecord(context);  
}

private void doStoreFileChunk(FileChunkSaveContext context) {  
        try {  
            // 类型转换：把分片上传上下文，转成存储引擎需要的上下文对象  
            StoreFileChunkContext storeFileChunkContext = fileConvertor.fileChunkSaveContext2StoreFileChunkContext(context);  
            // 把分片的文件输入流（前端传过来的二进制数据）放进上下文  
//            .getInputStream()MultipartFile 提供的方法，生成文件输入流 InputStream。  
//            作用：以流式读取分片的二进制数据，不会一次性把整个分片加载进内存，适合大分片，避免 OOM 内存溢出。  
//            storeFileChunkContext.setInputStream(输入流)  
//            把上面拿到的分片二进制输入流，赋值给存储上下文对象的流字段。  
//            后面底层保存分片的方法会读取这个 inputStream，循环读字节写入服务器本地临时文件。  
            storeFileChunkContext.setInputStream(context.getFile().getInputStream());  
  
            // 调用存储引擎，把分片写入磁盘/云存储  
            // 和之前下载的 storageEngine 是同一个，支持本地、OSS等多种存储方式  
            storageEngine.storeChunk(storeFileChunkContext);  
  
            // 存储完成后，把分片的真实存储路径，放回上下文，后面存数据库要用  
            context.setRealPath(storeFileChunkContext.getRealPath());  
  
        } catch (IOException e) {  
            // 文件读写异常，打印日志并抛出业务异常  
            e.printStackTrace();  
            throw new SystemException("文件分片上传失败");  
        }  
    }
    
    

    /**  
 * 存储引擎层：保存分片的入口  
 * 模板方法模式：先校验参数，再由具体子类实现真正的存储逻辑  
 */  
@Override  
public void storeChunk(StoreFileChunkContext context) throws IOException {  
    // 先校验参数：路径、输入流不能为空  
    checkStoreFileChunkContext(context);  
    // 真正写文件：由子类实现（本地存储/阿里云OSS/MinIO等不同存储方式）  
    doStoreChunk(context);  
}
//`doStoreChunk` 具体会执行哪个实现，取决于 `storageEngine` 在运行时实际注入的是哪个 `StorageEngine` Bean。  
// 当前项目中，`LocalStorageEngine` 类上同时标注了 `@Component` 和 `@Primary`，  
// 因此当 Spring 容器中存在多个 `StorageEngine` 实现类时，会优先选择 `LocalStorageEngine` 注入到 `storageEngine` 字段中。  
// 所以在默认情况下，调用 `storageEngine.storeChunk(...)` 最终会走到 `LocalStorageEngine#doStoreChunk(...)`。  
    protected abstract void doStoreChunk(StoreFileChunkContext context) throws IOException;

/**  
 * 本地存储引擎：真正把分片文件写入服务器硬盘  
 * 这是父类抽象方法 doStoreChunk 的具体实现（模板方法模式）  
 * @param context 存储分片的上下文，包含分片输入流、MD5标识、分片号、总大小等信息  
 */  
@Override  
protected void doStoreChunk(StoreFileChunkContext context) throws IOException {  
    // 1. 从配置里读取：分片文件的根目录（所有分片都存在这个总文件夹下面）  
    String basePath = config.getRootFileChunkPath();  
  
    // 2. 生成当前分片的完整存储路径  
    // 规则：根目录 / 文件MD5值 / 分片编号  
    // 好处：同一个文件的所有分片都放在同一个MD5文件夹里，后续合并文件时好找  
    String realFilePath = FileUtil.generateStoreFileChunkRealPath(  
            basePath,  
            context.getIdentifier(),  // 文件MD5唯一标识  
            context.getChunkNumber()  // 当前是第几号分片  
    );  
  
    // 3. 核心动作：把前端传过来的分片输入流（二进制数据），写入到硬盘的目标文件里  
    FileUtil.writeStreamToFile(  
            context.getInputStream(),  // 分片的二进制输入流（从前端请求里拿到的）  
            new File(realFilePath),    // 要写入的目标文件（硬盘上的位置）  
            context.getTotalSize()     // 分片总大小（工具内部用来控制读写缓冲区）  
    );  
  
    // 4. 把生成好的真实存储路径放回上下文，后面存数据库分片记录要用  
    context.setRealPath(realFilePath);  
}

@Data  
@Component  
//ConfigurationProperties：Spring Boot 的注解，自动从配置文件里读参数。  
// 比如你在 application.yml 里写 com.disk.file.storage.engine.local.rootFileChunkPath = /data/chunks，它就会用你配置的路径，不写就用默认值。  
@ConfigurationProperties("com.disk.file.storage.engine.local")  
public class LocalStorageEngineConfig {  
  
    /**  
     /**     * 完整文件的存储根路径（合并后的完整文件存在这）  
     * 不配置的话，用工具类生成的默认路径  
     */  
    private String rootFilePath = FileUtil.generateDefaultStoreFileRealPath();  
  
    /**  
     * 分片文件的存储根路径（所有分片都存在这个总目录下）  
     * 不配置的话，默认存在 用户主目录/coder-pan/chunks  
     */    private String rootFileChunkPath = FileUtil.generateDefaultStoreFileChunkRealPath();  
  
}

    /**  
     * 生成默认的文件分片的存储路径前缀  
     *默认位置：系统用户主目录 / coder-pan / chunks  
     * @return  
     */  
    public static String generateDefaultStoreFileChunkRealPath() {  
//        System.getProperty("user.home")  获取当前操作系统的用户主目录  
        return new StringBuffer(System.getProperty("user.home"))  
                .append(File.separator) // 系统文件分隔符（Windows是\，Linux是/，自动适配）  
                .append("coder-pan")// 项目总文件夹  
                .append(File.separator)  
                .append("chunks") // 分片专属文件夹  
                .toString();  
    }

private void doSaveRecord(FileChunkSaveContext context) {
    FileChunkDO record = new FileChunkDO();

    // 分片记录主键
    record.setId(IdUtil.get());

    // 文件唯一标识
    record.setIdentifier(context.getIdentifier());

    // 分片真实存储路径
    record.setRealPath(context.getRealPath());

    // 分片编号
    record.setChunkNumber(context.getChunkNumber());

    // 分片过期时间，默认 1 天
    record.setExpirationTime(
        DateUtil.offsetDay(new Date(), config.getChunkFileExpirationDays())
    );

    // 创建人/更新人
    record.setCreateUser(context.getUserId());
    record.setUpdateUser(context.getUserId());

    // 插入 file_chunk 表
    if (!save(record)) {
        throw new SystemException("文件分片上传失败");
    }
}

POST /api/v1/files/file/merge

/file/chunk-upload：保存单个分片，只负责“攒分片”
/file/merge：合并所有分片，生成完整文件，并保存用户文件记录

前端所有分片上传完成
  ↓
前端调用 /file/merge
  ↓
Controller 接收 filename、identifier、parentId、totalSize 等参数
  ↓
UserFileService.mergeFile(...)
  ↓
FileService 查询 file_chunk 表，拿到所有分片路径
  ↓
按 chunkNumber 排序
  ↓
调用 StorageEngine.mergeFile(...)
  ↓
本地存储引擎按顺序拼接分片，生成完整文件
  ↓
保存 file 表，记录真实物理文件
  ↓
保存 user_file 表，让文件出现在用户目录
  ↓
删除 file_chunk 临时分片记录

/**
 * 文件分片合并
 */
@PostMapping("/file/merge")
public Result mergeFile(@Validated @RequestBody FileChunkMergeParamVO fileChunkMergeParam) {
    // 1. 前端请求参数转换成后端业务上下文
    FileChunkMergeContext context =
            fileConvertor.fileChunkMergeParamVOToFileChunkMergeContext(fileChunkMergeParam);

    // 2. 调用业务层执行合并
    userFileService.mergeFile(context);

    // 3. 合并成功，返回统一成功响应
    return Result.success("");
}

filename：原始文件名
identifier：文件 MD5
parentId：上传到哪个目录
totalSize：完整文件大小

@Override
public void mergeFile(FileChunkMergeContext context) {
    // 1. 合并物理分片，并保存 file 表记录
    mergeFileChunkAndSaveFile(context);

    // 2. 保存 user_file 表记录，让文件出现在用户目录中
    saveUserFile(
            context.getParentId(),
            context.getFilename(),
            FolderFlagEnum.NO,
            FileTypeEnum.getFileTypeCode(FileUtil.getFileSuffix(context.getFilename())),
            context.getRecord().getId(),
            context.getUserId(),
            context.getRecord().getFileSizeDesc()
    );
}

第一件事：生成真实文件，并保存 file 表
第二件事：保存 user_file 表，让用户目录能看到这个文件

file 表：记录真实物理文件，比如 real_path、size、MD5、后缀
user_file 表：记录用户目录中的文件，比如 user_id、parent_id、filename、real_file_id

/**  
 * 合并分片主入口方法  
 * @param context 合并分片请求上下文，包含文件MD5、用户ID、文件名、总大小等  
 */  
private void mergeFileChunkAndSaveFile(FileChunkMergeContext context) {  
    // 转换器：对外合并参数实体 → 内部合并存储专用上下文  
    FileChunkMergeAndSaveContext fileChunkMergeAndSaveContext = fileConvertor.fileChunkMergeContextToSaveContext(context);  
    // 执行分片合并+物理文件入库完整逻辑  
    fileService.mergeFileChunkAndSaveFile(fileChunkMergeAndSaveContext);  
    // 将生成的物理文件记录回写给上层上下文，供外层创建user_file目录记录使用  
    context.setRecord(fileChunkMergeAndSaveContext.getRecord());  
}

user_file.real_file_id = file.id

@Override
public void mergeFileChunkAndSaveFile(FileChunkMergeAndSaveContext context) {
    // 1. 查询分片并合并成完整文件
    doMergeFileChunk(context);

    // 2. 保存完整文件的 file 表记录
    FileDO record = doSaveFile(
            context.getFilename(),
            context.getRealPath(),
            context.getTotalSize(),
            context.getIdentifier(),
            context.getUserId()
    );

    // 3. 回写 file 表记录
    context.setRecord(record);
}

/**  
 * 1. 查询当前用户该文件所有有效分片  
 * 2. 按分片序号排序，拿到所有分片磁盘路径  
 * 3. 调用存储引擎按顺序拼接成分整文件  
 * 4. 拼接成功后物理删除所有临时分片文件 + 删除数据库分片记录  
 * @param context 分片合并上下文  
 */  
private void doMergeFileChunk(FileChunkMergeAndSaveContext context) {  
    // 构建分片查询条件  
    QueryWrapper<FileChunkDO> queryWrapper = Wrappers.query();  
    // 匹配文件唯一MD5标识  
    queryWrapper.eq("identifier", context.getIdentifier());  
    // 匹配当前登录用户，隔离他人分片  
    queryWrapper.eq("create_user", context.getUserId());  
    // 只查未过期分片，过期分片失效不参与合并  
    queryWrapper.ge("expiration_time", new Date());  
    // 查询该文件全部分片数据库记录  
    List<FileChunkDO> chunkRecoredList = fileChunkService.list(queryWrapper);  
  
    // 没有分片直接抛异常，无法合并  
    if (CollectionUtils.isEmpty(chunkRecoredList)) {  
        throw new SystemException("该文件未找到分片记录");  
    }  
  
    // 流式处理：按分片编号升序排序 → 提取每个分片的磁盘真实路径  
    List<String> realPathList = chunkRecoredList.stream()  
            .sorted(Comparator.comparing(FileChunkDO::getChunkNumber)) // 分片从小到大排序，顺序不能乱  
            .map(FileChunkDO::getRealPath) // 取出每个分片存在服务器的文件路径  
            .collect(Collectors.toList());  
  
    try {  
        // 组装存储引擎合并文件入参  
        MergeFileContext mergeFileContext = new MergeFileContext();  
        mergeFileContext.setFilename(context.getFilename());  
        mergeFileContext.setIdentifier(context.getIdentifier());  
        mergeFileContext.setUserId(context.getUserId());  
        mergeFileContext.setRealPathList(realPathList); // 有序分片路径集合  
  
        // 调用底层存储引擎，按顺序读取所有分片，拼接生成完整大文件  
        storageEngine.mergeFile(mergeFileContext);  
        // 将合并完成后的完整文件磁盘路径回填上下文，后续入库使用  
        context.setRealPath(mergeFileContext.getRealPath());  
    } catch (IOException e) {  
        e.printStackTrace();  
        // IO异常：磁盘读写失败、分片缺失、权限不足等，抛出业务异常给前端  
        throw new SystemException("文件分片合并失败");  
    }  
  
    // 收集所有分片数据库主键ID  
    List<Long> fileChunkRecordIdList = chunkRecoredList.stream()  
            .map(FileChunkDO::getId)  
            .collect(Collectors.toList());  
    // 物理删除临时分片文件 + 删除file_chunk表分片记录，释放磁盘与数据库空间  
    fileChunkService.removeChunkRecordsPhysically(fileChunkRecordIdList);  
}

.sorted(Comparator.comparing(FileChunkDO::getChunkNumber))

第 1 片内容 + 第 2 片内容 + 第 3 片内容 + ... = 完整文件

@Override  
protected void doMergeFile(MergeFileContext context) throws IOException {  
    // 1. 读取配置：文件存储根目录（服务器统一文件存放根路径）  
    String basePath = config.getRootFilePath();  
    // 2. 根据根目录+原始文件名，生成合并后完整文件的最终磁盘绝对路径  
    String realFilePath = FileUtil.generateStoreFileRealPath(basePath, context.getFilename());  
    // 3. 在磁盘创建空白完整文件，准备后续追加写入分片内容  
    FileUtil.createFile(new File(realFilePath));  
  
    // 4. 获取排好序的所有分片磁盘路径（已按chunkNumber从小到大排序，顺序不能乱）  
    List<String> chunkPaths = context.getRealPathList();  
    // 5. 循环每一块分片，依次把分片二进制追加写入完整文件末尾  
    for (String chunkPath : chunkPaths) {  
        // 把当前分片文件内容，追加到目标完整文件尾部  
        FileUtil.appendWrite(Paths.get(realFilePath), new File(chunkPath).toPath());  
    }  
  
    // 6. 全部分片拼接完成，批量删除磁盘上所有临时分片文件，释放磁盘空间  
    FileUtil.deleteFiles(chunkPaths);  
    // 7. 将合并后完整文件的磁盘路径回填上下文，供上层入库FileDO表使用  
    context.setRealPath(realFilePath);  
}

FileUtil.deleteFiles(chunkPaths)：删除磁盘上的临时分片文件
removeChunkRecordsPhysically(...)：删除数据库 file_chunk 表里的临时记录

private FileDO doSaveFile(
        String filename,
        String realPath,
        Long totalSize,
        String identifier,
        Long userId
) {
    // 1. 组装 file 表实体
    FileDO record = assembleFileDO(
            filename,
            realPath,
            totalSize,
            identifier,
            userId
    );

    // 2. 插入 file 表
    if (!save(record)) {
        // 这里项目预留了失败后删除物理文件、记录日志的处理
    }

    return record;
}

id：物理文件 ID
filename：文件名
real_path：完整文件真实存储路径
file_size：文件大小
file_size_desc：格式化后的文件大小
file_suffix：文件后缀
file_preview_content_type：预览类型
identifier：文件 MD5
create_user：创建人

private Long saveUserFile(
        Long parentId,
        String filename,
        FolderFlagEnum folderFlagEnum,
        Integer fileType,
        Long realFileId,
        Long userId,
        String fileSizeDesc
) {
    UserFileDO entity = new UserFileDO();

    entity.setId(IdUtil.get());
    entity.setUserId(userId);
    entity.setParentId(parentId);
    entity.setRealFileId(realFileId);
    entity.setFilename(filename);
    entity.setFolderFlag(folderFlagEnum.getCode());
    entity.setFileSizeDesc(fileSizeDesc);
    entity.setFileType(fileType);
    entity.setDeleted(DeleteEnum.NO.getCode());
    entity.setCreateUser(userId);
    entity.setUpdateUser(userId);

    // 处理同目录重名文件
    handleDuplicateFilename(entity);

    if (!save(entity)) {
        throw new SystemException("保存文件信息失败");
    }

    return entity.getId();
}

user_id：这个文件属于哪个用户
parent_id：这个文件在哪个目录下
real_file_id：关联 file 表的真实物理文件 ID
filename：用户看到的文件名
folder_flag：是否文件夹
file_type：文件类型
deleted：是否删除

完整文件已经合并
  ↓
file 表保存了真实物理文件
  ↓
user_file 表保存了用户目录记录
  ↓
前端刷新文件列表
  ↓
列表接口查到 user_file
  ↓
页面展示新文件

// 4. 判断：如果当前不是文件夹，是普通文件，触发AI文档初始化任务  
// 文件夹不需要AI解析，只有文档类文件需要向量化、智能检索预处理  
if (FolderFlagEnum.NO.equals(folderFlagEnum)) {  
    // 异步调度AI初始化任务：用户ID、文件ID、文件名称  
    documentAiInitializer.scheduleInitialize(userId, entity.getId(), filename);  
}

普通上传 / 秒传 / 分片合并
  -> saveUserFile(...)
  -> 插入 user_file
  -> 如果是普通文件
  -> documentAiInitializer.scheduleInitialize(userId, userFileId, filename)
  -> 判断后缀是否支持 AI
  -> 事务提交后发送 AI 预热 MQ
  -> networkdisk-ai 消费消息
  -> 建索引
  -> 生成默认摘要
  -> 生成默认标签

private Long saveUserFile(...) {
    UserFileDO entity = new UserFileDO();
    entity.setId(IdUtil.get());
    entity.setUserId(userId);
    entity.setParentId(parentId);
    entity.setRealFileId(realFileId);
    entity.setFilename(filename);
    entity.setFolderFlag(folderFlagEnum.getCode());
    entity.setFileType(fileType);
    ...
  
	// 2. 核心：处理同一父目录下重名文件  
	// 逻辑：查询当前用户+当前parentId下是否存在同名文件，存在则自动重命名（xxx(1).txt）  
	handleDuplicateFilename(entity);  
	  
	// 3. 执行数据库插入，save返回布尔值标识是否插入成功  
	if (!save((entity))) {  
	    // 插入失败，抛全局系统异常，上层统一捕获返回前端错误提示  
	    throw new SystemException("保存文件信息失败");  
	}  
	  
	// 4. 判断：如果当前不是文件夹，是普通文件，触发AI文档初始化任务  
	// 文件夹不需要AI解析，只有文档类文件需要向量化、智能检索预处理  
	if (FolderFlagEnum.NO.equals(folderFlagEnum)) {  
	    // 异步调度AI初始化任务：用户ID、文件ID、文件名称  
	    documentAiInitializer.scheduleInitialize(userId, entity.getId(), filename);  
	}  
	  
	// 返回新增记录主键  
	return entity.getId();
}

upload 里写一次 AI 预热
secUpload 里写一次 AI 预热
mergeFile 里写一次 AI 预热

    public void scheduleInitialize(Long userId, Long userFileId, String filename) {  
        // 1. 参数校验 + 文件格式过滤  
        // 用户ID、文件ID为空 或 文件后缀不支持AI解析，直接终止，不发送MQ消息  
        if (userId == null || userFileId == null || !supports(filename)) {  
            return;  
        }  
  
        // 2. 判断当前线程是否存在活跃数据库事务  
        // 原因是：saveUserFile(...) 刚插入 user_file，如果事务还没提交，  
        // AI 服务立刻消费 MQ 去读这个文件，可能查不到 user_file 记录。  
        if (TransactionSynchronizationManager.isActualTransactionActive()) {  
            // 注册事务同步回调，等待事务执行完成  
            TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {  
                /**  
                 * 事务成功提交后执行  
                 * 只有数据库数据真正落库，才发送AI解析消息  
                 */  
//                等 user_file 真正提交成功。再发送 AI 预热消息  
                @Override  
                public void afterCommit() {  
                    publishWarmupMessage(userId, userFileId, filename);  
                }  
            });  
            // 注册完回调直接返回，不再往下执行同步发消息逻辑  
            return;  
        }  
        // 3. 当前无事务环境，文件记录已持久化，直接发送MQ消息触发AI预热  
        publishWarmupMessage(userId, userFileId, filename);  
    }

if (TransactionSynchronizationManager.isActualTransactionActive()) {
    // 当前方法正在一个 Spring 事务里面
    // 不能立刻发 MQ，要等数据库事务提交成功后再发
    register afterCommit 回调
    return;
}

// 当前没有 Spring 事务
// 数据库操作一般已经自动提交了，可以直接发 MQ
publishWarmupMessage(...)

@Transactional(rollbackFor = Exception.class)
public void upload(UploadFileContext context) {
    saveFile(context);
    saveUserFile(...);
}

开始事务
  -> saveFile 插入 file 表
  -> saveUserFile 插入 user_file 表
  -> 方法正常结束
提交事务

事务还没提交
AI 服务查不到这条 user_file

saveUserFile 插入 user_file
  -> 注册 afterCommit 回调
  -> 等事务提交成功
  -> 再发 MQ

public boolean secUpload(SecUploadFileContext context) {
    ...
    saveUserFile(...);
}

public void mergeFile(FileChunkMergeContext context) {
    mergeFileChunkAndSaveFile(context);
    saveUserFile(...);
}

查询已有 file
  -> 插入 user_file
  -> 插入成功后，这条 user_file 已经提交了
  -> 可以直接发 MQ

publishWarmupMessage(userId, userFileId, filename);

org.springframework.transaction.support.TransactionSynchronizationManager

Spring 当前线程事务状态的管理工具

当前线程有没有事务？
当前事务绑定了哪些数据库连接？
有没有注册事务提交后的回调？
事务提交后要执行哪些动作？

TransactionSynchronizationManager.isActualTransactionActive()

@Transactional
public void xxx() {
    ...
}

TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {
    @Override
    public void afterCommit() {
        publishWarmupMessage(userId, userFileId, filename);
    }
});

给当前事务注册一个回调
等事务提交成功后
Spring 自动调用 afterCommit()

@Transactional 方法开始
  -> Spring 开启事务
  -> 插入 user_file
  -> registerSynchronization 注册 afterCommit
  -> 方法结束
  -> Spring 提交事务
  -> 提交成功
  -> Spring 调用 afterCommit()
  -> 发送 AI 预热 MQ

插入失败 / 抛异常
  -> Spring 回滚事务
  -> afterCommit 不会执行
  -> 不会发送 AI 预热 MQ

saveUserFile 插入 user_file
  -> 事务还没提交
  -> 立刻发 MQ
  -> AI 服务消费消息
  -> AI 服务通过 userFileId 查询文件
  -> 查不到，因为事务未提交

if (TransactionSynchronizationManager.isActualTransactionActive()) {
    // 有事务，等提交后发
} else {
    // 没事务，直接发
}

upload(...)

@Transactional(rollbackFor = Exception.class)
public void upload(...)

secUpload
mergeFile

有事务：afterCommit 后发 MQ
没事务：直接发 MQ

spring.cloud.stream.rocketmq.bindings.aiWarmup-out-0: destination: ai-document-warmup # 真实RocketMQ主题名

    /**  
     * 推送AI文档预热消息  
     * 场景：文件上传后发送预热通知，AI服务提前加载文档做解析/向量缓存  
     * @param userId 用户ID  
     * @param userFileId 文件原始主键ID  
     * @param filename 文件名称  
     */  
    private void publishWarmupMessage(Long userId, Long userFileId, String filename) {  
        try {  
            // 封装轻量预热消息：仅携带AI服务必需的定位字段，减少消息体积  
            AiDocumentWarmupMessage message = new AiDocumentWarmupMessage();  
            message.setUserId(userId);  
            message.setUserFileId(userFileId);  
            // 对外统一使用加密fileId，和前端/AI接口参数格式保持一致，避免ID泄露  
            message.setFileId(IdUtil.encrypt(userFileId));  
            message.setFilename(filename);  
  
            // StreamBridge发送消息，binding绑定输出通道aiWarmup-out-0，映射RocketMQ主题ai-document-warmup  
            // 参数1：绑定通道名；参数2：消息TAG；参数3：消息实体序列化JSON字符串  
//            通道（binding）是 Stream 的抽象管道 xxx-out-0，通过配置映射真实 RocketMQ Topic，作用是解耦主题、屏蔽中间件差异。  
            boolean sent = streamProducer.send(  
                    AI_WARMUP_BINDING,  
                    AI_WARMUP_TAG,  
                    objectMapper.writeValueAsString(message)  
            );  
            // send返回false代表投递未成功，打印告警日志便于排查  
            if (!sent) {  
                log.warn("publish document ai warmup message returned false, userId={}, userFileId={}", userId, userFileId);  
            }  
        } catch (Exception e) {  
            // 序列化/网络/中间件异常捕获，仅告警不阻断主流程，可搭配监控告警  
            log.warn("publish document ai warmup message failed, userId={}, userFileId={}", userId, userFileId, e);  
        }  
    }

public boolean send(String bingingName, String tag, String msg) {  
    // 统一外层包装MessageBody载体  
    MessageBody message = new MessageBody()  
            .setIdentifier(UUID.randomUUID().toString()) // 全局唯一消息流水ID，链路追踪  
            .setBody(msg); // 存放真实业务JSON字符串  
    logger.info("send message : {} , {}", bingingName, JSON.toJSONString(message));  
  
    // Spring标准消息构建器  
    // withPayload：外层统一载体MessageBody  
    // setHeader("TAGS", tag)：RocketMQ识别TAG头，用于消息过滤  
    boolean result = streamBridge.send(  
            bingingName,  
            MessageBuilder.withPayload(message)  
                    .setHeader("TAGS", tag)  
                    .build()  
    );  
    logger.info("send result : {} , {}", bingingName, result);  
    return result;  
}

@Bean("aiWarmupConsumer")
public Consumer<Message<?>> aiWarmupConsumer() {
    return message -> {
        AiDocumentWarmupMessage warmupMessage = readWarmupMessage(message);

        ...

        aiApplicationService.indexFile(indexRequest);
        aiApplicationService.summarize(summaryRequest);
        aiApplicationService.generateTags(tagRequest);
    };
}

spring:  
  # 当前 Spring Boot 服务名，@application.name@ 通常由 Maven/构建配置替换  
  application:  
    name: @application.name@  
  # 额外加载公共配置文件：数据库、缓存、RPC、消息流  
  config:  
    import: classpath:datasource.yml,classpath:cache.yml,classpath:rpc.yml,classpath:stream.yml  
  # Spring Cloud 相关配置  
  cloud:  
    # 声明当前服务里的消息消费函数名  
    function:  
      definition: aiWarmupConsumer  
    # 消息队列/事件流绑定配置  
    stream:  
      bindings:  
        # aiWarmupConsumer 函数的输入通道  
        aiWarmupConsumer-in-0:  
          # 消费的消息主题，用于接收文档 AI 预热任务  
          destination: ai-document-warmup  
          # 消费组，同一组内多个实例会分摊消费  
          group: networkdisk-ai  
          # 消息内容格式  
          content-type: application/json

RocketMQ 收到 ai-document-warmup 消息
  -> Spring Cloud Stream RocketMQ Binder 拉取消息
  -> 根据配置找到 aiWarmupConsumer-in-0
  -> 根据 function.definition 找到 Bean：aiWarmupConsumer
  -> 自动调用 Consumer<Message<?>> 的 accept(message)
  -> 执行 return message -> { ... } 里面的代码

aiWarmup-out-0:
  destination: ai-document-warmup

aiWarmupConsumer-in-0:
  destination: ai-document-warmup

files 服务
  aiWarmup-out-0
    -> ai-document-warmup topic

ai 服务
  aiWarmupConsumer-in-0
    <- ai-document-warmup topic

AiDocumentWarmupMessage warmupMessage = readWarmupMessage(message);
readWarmupMessage(...) 做两步：

第一步，把外层 payload 转成 MessageBody：

MessageBody messageBody = objectMapper.convertValue(message.getPayload(), MessageBody.class);

第二步，把 messageBody.getBody() 里的 JSON 字符串转成真正业务对象：

return objectMapper.readValue(messageBody.getBody(), AiDocumentWarmupMessage.class);

Message<?> 
  -> payload
  -> MessageBody
  -> body 字符串
  -> AiDocumentWarmupMessage

DocumentAiInitializer.publishWarmupMessage
  -> streamProducer.send("aiWarmup-out-0", "document-ai-warmup", json)
  -> StreamBridge
  -> RocketMQ topic: ai-document-warmup
  -> AiWarmupStreamConfiguration.aiWarmupConsumer
  -> readWarmupMessage
  -> aiApplicationService.indexFile
  -> aiApplicationService.summarize
  -> aiApplicationService.generateTags

if (res.code === 0 || res.success === true) {
  f.cancel()
  taskStore.remove(f.name)
  fileStore.loadFileList()
}

if (res.code === 0 || res.success === true) {
  uploader.removeFile(file)
  fileStore.loadFileList()

  taskStore.updateStatus({
    filename: file.name,
    status: panUtil.fileStatus.SUCCESS.code,
    statusText: panUtil.fileStatus.SUCCESS.text
  })

  taskStore.remove(file.name)
}

分片全部上传完成
  ↓
fileUploaded(...) 判断需要合并
  ↓
doMerge(file)
  ↓
POST /file/merge
  ↓
后端合并分片 + 保存 file + 保存 user_file
  ↓
前端 fileStore.loadFileList()
  ↓
GET /api/v1/files/folders-files
  ↓
页面重新渲染文件列表

后端创建了 user_file 记录
  ↓
前端刷新当前目录
  ↓
列表接口查到 user_file
  ↓
表格重新渲染

if (res.data.mergeFlag) {
  doMerge(file)
}

0：分片还没齐，不需要合并
1：分片已齐，可以调用 /file/merge

const taskList = ref([])
const viewFlag = ref(false)

add(...)：加入上传任务
updateStatus(...)：更新等待中、上传中、合并中、成功、失败等状态
updateProcess(...)：更新速度、百分比、已上传大小、剩余时间
pause(...)：调用 simple-uploader 的 pause()
resume(...)：调用 simple-uploader 的 resume()
cancel(...)：调用 cancel() 并从 taskList 移除

断点续传能力：依赖后端 file_chunk 表 + uploadedChunks 查询
任务面板恢复：当前没有持久化，刷新页面后不会恢复

                 StorageEngine 接口
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
LocalStorageEngine  FastDFSStorageEngine  OssStorageEngine
本机磁盘              FastDFS 集群          阿里云 OSS

identifier       文件 MD5
create_user      当前用户
chunk_number     分片编号
expiration_time  分片是否过期

同一用户
同一文件内容 MD5
同一分片编号
分片未过期

1. 前端主链路默认走分片上传，秒传命中时才取消真实上传。
2. /file/upload 单文件上传接口存在，但当前页面主上传链路主要走分片上传。
3. 秒传按当前用户 + identifier 查询 file 表，不是全站共享秒传。
4. 分片记录有过期时间，默认 1 天，过期后不能继续复用。
5. chunk-upload 成功只代表某个分片保存成功，不代表文件已上传完成。
6. mergeFlag 只代表“可以合并”，真正合并必须再调用 /file/merge。
7. 文件出现在列表里的前提是后端成功保存 user_file。
8. 上传任务面板是前端内存状态，不是后端持久化任务。
9. 前端上传完成后通过 loadFileList() 重新查询列表，不是本地手动追加文件。

1. 秒传是否命中
2. chunk-upload 是否成功
3. file_chunk 是否插入分片记录
4. 最后一个分片后 mergeFlag 是否为 1
5. 前端是否调用 /file/merge
6. file 表是否保存完整文件记录
7. user_file 表是否保存目录记录
8. 前端是否调用 loadFileList()

id                         物理文件 ID
filename                   文件名
real_path                  真实存储路径
file_size                  文件大小
file_size_desc             文件大小展示文本
file_suffix                文件后缀
file_preview_content_type  预览类型
identifier                 文件 MD5
create_user                创建人

1. merge 成功后，保存完整文件记录
2. 秒传时，根据 create_user + identifier 查询是否已有相同文件

create_user = 当前用户
identifier = 文件 MD5

id              用户文件记录 ID
user_id         所属用户
parent_id       所在目录
real_file_id    关联 file.id
filename        页面展示文件名
folder_flag     是否文件夹
file_size_desc  文件大小展示
file_type       文件类型
deleted         是否删除

file：文件真实存在
user_file：用户目录里能看到这个文件

identifier       文件 MD5
real_path        分片真实路径
chunk_number     分片编号
expiration_time  分片过期时间
create_user      上传用户

uk_identifier_chunk_number_create_user

file_chunk：上传过程中的临时分片
file：合并后的真实物理文件
user_file：用户目录中展示的文件

上传分片
  ↓
写入 file_chunk
  ↓
调用 merge
  ↓
分片合并成完整文件
  ↓
写入 file
  ↓
写入 user_file
  ↓
删除 file_chunk 临时记录
  ↓
前端刷新文件列表

上传链路：
分片 -> file_chunk -> merge -> file -> user_file

下载链路：
user_file -> file -> real_path -> response 输出流 -> 前端 Blob

user_file：用户视图文件，决定当前用户能不能看到、能不能下载这个文件
file：真实物理文件，保存 real_path、size、identifier 等真实文件信息

个人空间单文件下载：已实现
个人空间文件预览：已实现
分享页单文件下载：已实现
前端批量下载普通文件：已实现，本质是循环单文件下载
后端多文件 zip 打包下载：未实现
文件夹下载：未实现

GET /api/v1/files/file/download?fileId=xxx

前端点击下载
  ↓
调用 downloadFileAPI，responseType = blob
  ↓
后端解密 fileId
  ↓
查询 user_file
  ↓
校验文件存在、属于当前用户、不是文件夹
  ↓
通过 real_file_id 查询 file
  ↓
拿到 file.real_path
  ↓
设置下载响应头
  ↓
storageEngine.realFile(...)
  ↓
把文件写入 response.getOutputStream()
  ↓
前端拿到 Blob
  ↓
saveBlobToLocal(blob, filename)

Content-Type: application/octet-stream
Content-Disposition: attachment;filename="xxx"
Content-Length: 文件大小

<a href="/api/v1/files/file/download?fileId=xxx">下载</a>

window.location.href = '/api/v1/files/file/download?fileId=xxx'

Content-Disposition: attachment; filename="a.txt"
Content-Type: application/octet-stream

const response = await downloadFileAPI({ fileId })

后端返回文件二进制
  ↓
axios 接收成 Blob
  ↓
前端把 Blob 变成临时 URL
  ↓
前端创建 a 标签
  ↓
模拟点击 a 标签
  ↓
浏览器才开始保存文件

Blob { size: 102400, type: "application/pdf" }

const url = window.URL.createObjectURL(blob)

blob:http://localhost:5173/xxxx-xxxx

function saveBlobToLocal(blob, filename) {
  const url = window.URL.createObjectURL(blob)

  const link = document.createElement('a')
  link.href = url
  link.download = filename

  document.body.appendChild(link)
  link.click()
  document.body.removeChild(link)

  window.URL.revokeObjectURL(url)
}

创建一个隐藏下载链接
  ↓
链接地址指向 Blob 临时 URL
  ↓
download 属性指定保存文件名
  ↓
用 JS 模拟用户点击
  ↓
浏览器执行下载
  ↓
删掉临时链接，释放 Blob URL

如果用普通 a 标签直接访问下载接口，浏览器会根据后端 Content-Disposition 自动下载。
但当前项目用 axios 请求文件流，响应会先进入 JS，不会自动触发下载。
因此前端必须把 Blob 转成 ObjectURL，再创建 a 标签并模拟点击，才能让浏览器保存文件。

解密 fileId
查询 user_file
校验权限
查询 file
读取 file.real_path
写入 response 输出流

Content-Type: application/octet-stream
Content-Disposition: attachment
前端：Blob -> a.download -> 保存

Content-Type: image/png / application/pdf / video/mp4 / text/plain
前端：Blob -> ObjectURL -> 新窗口打开

file.real_path
  ↓
StorageEngine.realFile(...)
  ↓
response.getOutputStream()

服务器磁盘文件 -> 输入流/Channel -> HTTP 输出流 -> 浏览器

文件 A
文件 B
文件夹 C

download.zip
  ├── 文件A.txt
  ├── 文件B.jpg
  └── 文件夹C/
      ├── c1.pdf
      └── c2.png

磁盘文件 -> InputStream -> Java 程序 -> OutputStream -> 磁盘 / 网络 / 浏览器

@Test
public void readSmallFile() throws Exception {
    // 1. 创建文件字节输入流，绑定磁盘上指定文件，用于读取文件二进制
    FileInputStream input = new FileInputStream("/home/data/test.txt");

    // 2. input.available() 返回当前流可读总字节，新建等大byte数组
    // 致命缺陷：文件多大，数组就占多大堆内存，大文件直接OOM内存溢出
    // 仅适合KB级小文本，网盘分片/大文件绝对不能用这种写法
    byte[] bytes = new byte[input.available()];

    // 3. 一次性将全部文件字节读取进byte数组
    input.read(bytes);

    // 4. 将二进制字节数组以UTF-8编码转为可读字符串
    String text = new String(bytes, "UTF-8");

    System.out.println(text);

    // 5. 手动关闭输入流，释放操作系统文件句柄，不关闭会导致文件占用
    input.close();
}

FileInputStream：从磁盘读文件
byte[]：内存中的字节数组
new String(bytes)：把字节转成文本

@Test
public void copyFileByBuffer() throws Exception {
    // try-with-resources 语法：实现AutoCloseable接口的流，代码块结束自动关闭，不用手动close()
    try (
        // 源文件输入流：读取原文件
        FileInputStream input = new FileInputStream("/home/data/test.txt");
        // 目标文件输出流：写入复制后的新文件，文件不存在自动创建
        FileOutputStream output = new FileOutputStream("/home/data/copy.txt")
    ) {
        // 自定义8KB缓冲区，每次只加载8KB字节到内存，内存占用恒定，适配大文件
        byte[] buffer = new byte[8192];
        // len：存储每次read实际读到的字节数量
        int len;

        // 循环读取：input.read(buffer)
        // 有数据返回>0，读到文件末尾返回-1，循环终止
        while ((len = input.read(buffer)) != -1) {
            // write(buffer, 0, len)：只写入本次读取到的有效字节，避免末尾缓冲区脏数据
            output.write(buffer, 0, len);
        }

        // 强制刷新输出流缓冲区，把内存中残留字节全部刷入磁盘
        output.flush();
    }
    // 出try代码块自动关闭input、output，无需手动调用close
}

读一小块 -> 写一小块 -> 再读一小块 -> 再写一小块

@Test
public void copyFileByBufferedStream() throws Exception {
    try (
        // BufferedInputStream：装饰器模式，包装原始FileInputStream，内置默认8KB缓冲区
        // 减少频繁磁盘IO系统调用，提升读取性能
        BufferedInputStream input =
                new BufferedInputStream(new FileInputStream("/home/data/test.txt"));
        // BufferedOutputStream：包装输出流，内置缓冲区，减少频繁磁盘写入操作
        BufferedOutputStream output =
                new BufferedOutputStream(new FileOutputStream("/home/data/copy.txt"))
    ) {
        // 自定义缓冲区数组，可和内置缓冲配合使用
        byte[] buffer = new byte[8192];
        int len;

        // 分段循环读取写入逻辑和原生流完全一致
        while ((len = input.read(buffer)) != -1) {
            output.write(buffer, 0, len);
        }

        // 刷新缓冲，将缓冲区残留数据落地磁盘
        output.flush();
    }
}

FileInputStream：直接从磁盘一口一口读
BufferedInputStream：先用缓冲区攒一批，再给程序读

/**
 * NIO FileChannel零拷贝传输文件，适合大文件下载、文件转发
 * @param fileInputStream 本地文件输入流
 * @param outputStream 输出流（如HTTP响应输出流，返回文件给前端下载）
 * @param length 需要传输的文件总字节长度
 */
public static void writeFileToOutputStream(
        FileInputStream fileInputStream,
        OutputStream outputStream,
        long length
) throws IOException {
    // 1. 从文件输入流获取NIO文件通道FileChannel，负责读取磁盘文件
    FileChannel fileChannel = fileInputStream.getChannel();

    // 2. 将普通OutputStream包装成NIO可写字节通道WritableByteChannel
    WritableByteChannel targetChannel = Channels.newChannel(outputStream);

    // 3. 核心零拷贝方法 transferTo
    // 内核态直接把磁盘文件数据传输到目标通道，不经过应用堆内存，极大减少内存开销、CPU消耗
    // 参数：起始偏移0、传输总长度、目标通道
    fileChannel.transferTo(0, length, targetChannel);

    // 4. 刷新输出流，确保所有数据全部输出
    outputStream.flush();

    // 5. 手动关闭全部IO资源，释放文件句柄、网络连接
    fileInputStream.close();
    outputStream.close();
    fileChannel.close();
    targetChannel.close();
}

服务器磁盘文件
  ↓
FileChannel
  ↓
HTTP response 输出流
  ↓
浏览器