feat: support dir creation with purpose

[chlsmile]

Pull Request

Description

• support dir creation with purpose

Fixes # (issue)

Type of Change

Please delete options that are not relevant.

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🧹 Code refactoring (no functional changes)
• ⚡ Performance improvement
• 🔧 Configuration change

Component

Please check the components affected by this PR:

• 🔧 API (Backend)
• 🎨 Web (Frontend)
• 🐳 Docker/Infrastructure
• 📖 Documentation
• 🧪 Tests
• 📦 Dependencies

Testing

Please describe the tests that you ran to verify your changes:

• Unit tests pass (npm test / mvn test)
• Integration tests pass
• Manual testing completed
• Docker build successful

Test Configuration:

• OS: [e.g. Ubuntu 20.04]
• Node.js version: [e.g. 20.x]
• Java version: [e.g. 8]

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

Screenshots (if applicable)

Please add screenshots to help explain your changes.

Additional Notes

Add any additional notes, concerns, or questions here.

[Jiakaic]

@claude 检查提交的代码，使用中文回复

[github-actions]

Claude finished @Jiakaic's task —— View job

---

代码审查报告

我已经仔细检查了这次提交的代码变更，以下是详细的审查反馈：

待办任务清单

• 读取仓库配置文件 (CLAUDE.md) - 未找到配置文件
• 分析代码变更内容
• 检查 FileController.java 的修改
• 检查 FileSystemOps.java 的修改
• 检查 FileService.java 的修改
• 检查新增的测试文件 FileControllerMkdirTest.java
• 提供代码审查反馈

🎯 功能概述

此次提交为文件系统API添加了带目的(purpose)的目录创建功能，主要变更包括：

• 在 MkdirOp 协议中新增 purpose 字段
• 在 Controller 和 Service 层实现 purpose 参数支持
• 添加了comprehensive单元测试

✅ 优点

1. 代码结构良好

• 遵循了现有的代码模式和架构设计
• 参数校验逻辑清晰，错误处理完善

2. 测试覆盖全面

• 新增测试文件包含 11 个测试用例，覆盖了各种场景
• 包括成功创建、参数校验失败、边界条件等
• 测试用例命名清晰，易于理解

3. 参数校验严格

• 对目录名进行了全面的校验（长度、特殊字符、格式等）
• 对 purpose 参数进行了白名单验证
• 对 description 长度进行了限制

🔍 需要关注的问题

1. 代码格式问题 (较轻微)

位置: FileController.java:1038-1043

if(op.getPurpose() != null && !FilePurposeClassifier.allowedPurposes().contains(op.getPurpose())) {
	throw new IllegalArgumentException(
		String.format("Unsupported purpose: '%s'. Supported purposes are: %s",
			op.getPurpose(),
			String.join(", ", FilePurposeClassifier.allowedPurposes())));
}

建议: 缩进不一致，建议使用4个空格保持与其他代码一致的缩进风格。

2. 潜在的性能问题 (较轻微)

位置: FileController.java:1038 和 FileController.java:1042

每次校验时都会调用 FilePurposeClassifier.allowedPurposes()，如果这个方法每次都重新计算允许的purposes列表，可能存在性能问题。

建议: 如果 allowedPurposes() 返回的是动态计算的结果，考虑在类级别缓存这个列表。

3. 测试用例中的硬编码问题 (建议优化)

位置: FileControllerMkdirTest.java:368-372

String[] validPurposes = {
    "assistants", "vision", "user_data",
    "pdf", "dom_tree", "datasets_export", 
    "batch", "temp", "fine-tune", "evals", "assistants-chat"
};

问题: 测试中硬编码了所有有效的purpose值，如果系统中允许的purpose发生变化，测试需要同步更新。

建议: 考虑从 FilePurposeClassifier.allowedPurposes() 动态获取有效值列表，使测试更加健壮。

🛡️ 安全性评估

✅ 安全措施良好

• 输入校验完善: 对目录名进行了严格的安全校验，防止路径遍历攻击
• 参数白名单: purpose参数使用白名单验证，防止无效值传入
• 长度限制: 对目录名和描述都设置了合理的长度限制

📝 代码质量评估

✅ 质量良好

• 错误处理: 统一使用 IllegalArgumentException 处理参数错误
• 日志记录: 在适当的地方会有日志记录
• 事务处理: 正确使用了 @Transactional 注解
• 锁机制: 使用文件唯一性锁防止并发问题

🔧 建议改进

1. 代码格式: 修复缩进不一致问题
2. 性能优化: 考虑缓存允许的purpose列表（如果适用）
3. 测试优化: 使用动态获取的purpose列表进行测试

📊 总体评价

这是一个高质量的代码提交：

• ✅ 功能实现完整且正确
• ✅ 测试覆盖全面
• ✅ 安全性考虑周到
• ✅ 遵循现有代码规范
• ⚠️ 有少量格式问题需要修复

推荐状态: 基本可以合并，建议修复格式问题后合并。

---

作业运行链接

[chlsmile]

• 1. 代码格式问题 (较轻微) done
• 2. 潜在的性能问题 (较轻微) 忽略
• 3. 测试用例中的硬编码问题 (建议优化) done