文件操作相关接口

文件相关的接口由 com.basksoft.core.database.manager.file.FileManager 接口提供，所有方法通过单例 FileManager.ins 调用。

1. 核心概念

重要：FileManager 针对「文件」和「目录」的接口是分开的，调用时务必区分。例如修改文件名用 changeFileName，修改目录名必须用 changeDirName，二者不可混用。

2. 快速开始

获取文件 XML 内容：

FileManager.ins.loadContent(1000);

修改文件名：

FileManager.ins.changeFileName(1000, "新文件名", "andy.jia");

修改目录名称（注意与文件接口区分）：

FileManager.ins.changeDirName(1000, "新目录名", "andy.jia");

3. 新增文件与目录

新增文件：

BaskFile baskFile = new BaskFile();
baskFile.setType(FileType.report);
baskFile.setTenantId("basksoft");
baskFile.setName("工作周报");
baskFile.setDesc("金融事业部工作周报");
baskFile.setParentId(1000);
baskFile.setCreateUser("lver.jin");
FileManager.ins.addFile(baskFile, content, false);

新增目录：

BaskFile baskFile = new BaskFile();
baskFile.setDirectory(true);
baskFile.setTenantId("basksoft");
baskFile.setName("工作周报");
baskFile.setDesc("金融事业部工作周报");
baskFile.setParentId(1000);
baskFile.setCreateUser("lver.jin");
FileManager.ins.addDir(baskFile);

4. 接口分类说明

4.1 文件内容读写

4.2 文件属性

4.3 目录操作

目录与文件的操作接口不同，请使用 changeDirXxx / loadDir 等专用方法。

4.4 查询与加载

4.5 删除

4.6 移动

4.7 锁定 / 发布 / 版本

5. 事务说明

FileManager 中很多接口会对多个表进行存取，因此在集成模式下涉及写库操作的方法调用时，建议确保调用处于事务包裹中。

如果 Connection 是由 BaskServer 创建的，可用以下方式解决：

• BaskServer 在初始化时选择 JDBC 类型：

• 通过 ApplicationConfigLoader 使用 JDBC 类型的数据库连接：

  ApplicationConfigLoader

config.setConfigType(ConfigType.jdbc);

满足上述任一条件后，可用如下代码进行事务包裹：

Connection conn = JdbcUtils.getConnection();
boolean autoCommit = true;
try {
    autoCommit = conn.getAutoCommit();
    conn.setAutoCommit(false);
    // 调用具体的方法
    FileManager.ins.xxx();
    conn.commit();
} catch (Exception ex) {
    conn.rollback();
    throw ex;
} finally {
    conn.setAutoCommit(autoCommit);
    JdbcUtils.closeConnection(conn);
}

JdbcUtils 工具类全路径：com.basksoft.core.util.JdbcUtils

6. 完整接口定义（参考）

下面是 FileManager 接口的完整定义，作为精确参考：

import java.util.List;

import com.basksoft.core.database.model.BaskFile;
import com.basksoft.core.database.model.FileStatus;
import com.basksoft.core.database.model.FileType;
import com.basksoft.core.database.manager.file.FileQuery;

public interface FileManager {
    /**
     * FileManager单例，通过 FileManager.ins 调用接口方法
     */
    public static FileManager ins = new FileManagerImpl();

    /**
     * 创建文件查询对象，用于更复杂的查询条件组装
     * 
     * @return 文件查询对象
     */
    FileQuery createQuery();

    /**
     * 获取文件的XML内容
     * 
     * @param id 文件ID
     * @return XML内容
     */
    String loadContent(long id);

    /**
     * 获取文件预览图对应的BASE64数据
     * 
     * @param id 文件ID
     * @return 预览图对应的BASE64数据
     */
    String loadPreviewBase64(long id);

    /**
     * 更改文件状态
     * 
     * @param id     文件ID
     * @param status 文件状态
     * @param userId 修改人
     */
    void changeStatus(long id, FileStatus status, String userId);

    /**
     * 加载目录的子对象（包含目录和文件）
     * 
     * @param tenantId 团队ID
     * @param packetId 目录ID
     * @return 文件列表
     */
    List<BaskFile> loadChildren(String tenantId, long packetId);

    /**
     * 加载目录的子对象（包含目录和文件），支持递归展开整棵子树
     * 
     * @param tenantId  团队ID
     * @param packetId  目录ID
     * @param withFile  是否包含文件
     * @param types     文件类型过滤，null 表示全部
     * @param recursive 是否递归加载子目录（目录节点带嵌套 children）
     * @return 文件列表
     */
    List<BaskFile> loadChildren(String tenantId, long packetId, boolean withFile, FileType[] types, boolean recursive);

    /**
     * 修改文件名称
     * 
     * @param id      文件ID
     * @param newName 新的名称
     * @param userId  修改人
     */
    void changeFileName(long id, String newName, String userId);

    /**
     * 修改文件编码
     * 
     * @param id      文件ID
     * @param newCode 新的编码
     * @param userId  修改人
     */
    void changeFileCode(long id, String newCode, String userId);

    /**
     * 修改文件备注
     * 
     * @param id     文件ID
     * @param desc   文件备注
     * @param userId 修改人
     */
    void changeFileDesc(long id, String desc, String userId);

    /**
     * 新增文件,参考代码： 
     * BaskFile baskFile = new BaskFile();
     * baskFile.setType(FileType.report); 
     * baskFile.setTenantId("basksoft");
     * baskFile.setName("工作周报"); 
     * baskFile.setDesc("金融事业部工作周报");
     * baskFile.setParentId(1000); 
     * baskFile.setCreateUser("lver.jin");
     * FileManager.ins.addFile(baskFile, content, false);
     * 
     * @param file    BaskFile对象
     * @param content 文件XML内容
     * @param locked  是否直接锁定文件
     */
    void addFile(BaskFile file, String content, boolean locked);

    /**
     * 更新文件
     * 
     * @param id      文件ID
     * @param content 文件XML内容
     * @param userId  更新者
     */
    void updateFile(long id, String content, String userId);

    /**
     * 更改文件所有者
     * 
     * @param id     文件ID
     * @param userId 更新人
     * @param owner  新的拥有者
     */
    void changeFileOwner(long id, String userId, String owner);

    /**
     * 更改目录所有者
     * 
     * @param id     文件ID
     * @param userId 更新人
     * @param owner  新的拥有者
     */
    void changeDirOwner(long id, String userId, String owner);

    /**
     * 更新文件预览BASE64数据
     * 
     * @param id            文件ID
     * @param previewBase64 预览BASE64数据
     */
    void updatePreviewBase64(long id, String previewBase64);

    /**
     * 添加目录，参考代码:
     * BaskFile baskFile = new BaskFile(); 
     * baskFile.setDirectory(true);
     * baskFile.setTenantId("basksoft"); 
     * baskFile.setName("工作周报");
     * baskFile.setDesc("金融事业部工作周报"); 
     * baskFile.setParentId(1000);
     * baskFile.setCreateUser("lver.jin"); 
     * FileManager.ins.addDir(baskFile);
     * 
     * @param baskFile 目录对象
     */
    void addDir(BaskFile baskFile);

    /**
     * 加载BaskFile文件,不会加载文件的XML内容
     * 
     * @param id 文件ID
     * @return 返回BaskFile对象
     */
    BaskFile loadFile(long id);

    /**
     * 根据团队编号和文件编码加载BaskFile文件
     * 
     * @param tenantId 团队ID
     * @param code     文件编码
     * @return 返回BaskFile对象
     */
    BaskFile loadFile(String tenantId, String code);

    /**
     * 加载目录对象
     * 
     * @param id 文件ID
     * @return 返回目录对象
     */
    BaskFile loadDir(long id);

    /**
     * 根据文件名称获取文件对象，文件导入覆盖时用到
     * 
     * @param tenantId 团队ID
     * @param parentId 父目录ID
     * @param name     文件名称
     * @return 文件对象
     */
    BaskFile getBaskFileByName(String tenantId, long parentId, String name);

    /**
     * 删除文件对象
     * 
     * @param id 文件ID
     */
    void removeFile(long id);

    /**
     * 删除目录对象，删除目录时会自动删除目录下的所有子目录和文件
     * 
     * @param id 目录ID
     */
    void removeDir(long id);

    /**
     * 根据团队编号删除所有的文件对象
     * 
     * @param tenantId 团队编号
     */
    void removeFileByTenant(String tenantId);

    /**
     * 根据团队编号删除所有的目录对象
     * 
     * @param tenantId 团队编号
     */
    void removeDirByTenant(String tenantId);

    /**
     * 修改目录名称
     * 
     * @param id         目录ID
     * @param newDirName 新的名称
     * @param userId     修改人
     */
    void changeDirName(long id, String newDirName, String userId);

    /**
     * 修改目录备注
     * 
     * @param id     目录ID
     * @param desc   新的备注
     * @param userId 修改人
     */
    void changeDirDesc(long id, String desc, String userId);

    /**
     * 检查文件是否重名，一般情况下新建文件的时候建议避免重名
     * 
     * @param tenantId 团队ID
     * @param parentId 父目录ID
     * @param name     文件名称
     * @return 是否重名
     */
    boolean checkFileExist(String tenantId, long parentId, String name);

    /**
     * 检查目录是否重名，一般情况下新建文件的时候建议避免重名
     * 
     * @param tenantId 团队ID
     * @param parentId 父目录ID
     * @param name     目录名称
     * @return 是否重名
     */
    boolean checkDirExist(String tenantId, long parentId, String name);

    /**
     * 返回文件目录树(包含文件),rootId为0则为获取所有节点
     * 
     * @param tenantId 团队ID
     * @param rootId   根目录
     * @return 返回包含文件的目录树
     */
    BaskFile tree(String tenantId, long rootId);

    /**
     * 返回文件目录树(不包含文件),rootId为0则为获取所有节点
     * 
     * @param tenantId 团队ID
     * @param rootId   根目录
     * @return 返回目录树
     */
    List<BaskFile> dirTree(String tenantId, long rootId);

    /**
     * 修改文件所属目录
     * 
     * @param id       文件ID
     * @param parentId 父目录ID
     */
    void changeFileParent(long id, long parentId);

    /**
     * 移动目录
     * 
     * @param id       目录ID
     * @param parentId 父目录ID
     */
    void changeDirParent(long id, long parentId);

    /**
     * 锁定文件
     * 
     * @param id     文件ID
     * @param userId 账号
     */
    void lock(long id, String userId);

    /**
     * 解锁文件
     * 
     * @param id     文件ID
     * @param userId 账号
     */
    void unlock(long id, String userId);

    /**
     * 更新锁定配置
     * 
     * @param baskFile 资源对象
     */
    void updateFixed(BaskFile baskFile);

    /**
     * 加载已发布的文件
     * 
     * @param tenantId 团队ID
     * @param types    文件类型
     * @return 返回BaskFile对象
     */
    BaskFile loadDeployedFiles(String tenantId, FileType[] types);

    /**
     * 获取虚拟Root目录
     * 
     * @param tenantId 团队ID
     * @return 虚拟Root目录
     */
    BaskFile root(String tenantId);

    /**
     * 恢复文件版本，并将版本号累加1
     * 
     * @param id      文件ID
     * @param version 文件版本
     * @param note    版本说明
     * @param userId  账号
     * @return 新版本号
     */
    String revert(long id, String version, String note, String userId);

    /**
     * 发布文件
     * 
     * @param id      文件ID
     * @param version 文件版本
     * @param note    版本说明
     * @param userId  账号
     */
    void deploy(long id, String version, String note, String userId);

    /**
     * 发布文件
     * 
     * @param id      文件ID
     * @param version 文件版本
     * @param userId  账号
     */
    void deploy(long id, String version, String userId);

}