# tags-java

**Repository Path**: chiying/tags-java

## Basic Information

- **Project Name**: tags-java
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-23
- **Last Updated**: 2026-01-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MyTagStudio

纯本地、跨平台的文件管理软件，100% 零云端依赖。

## 核心特性

- **标签继承系统**：支持标签的层级继承，实现标签的灵活分类和管理
- **DSL 搜索语法**：支持复杂的搜索查询，如 `tag:编程 AND filetype:java`
- **文件系统监控**：实时监控文件变化，自动更新索引和数据库
- **跨平台支持**：支持 Windows、macOS 和 Linux 系统
- **纯本地存储**：所有数据存储在用户本地设备，SQLite 嵌入式数据库 + 文件系统直接访问
- **全文搜索**：基于 Apache Lucene 的高效全文搜索
- **高性能**：优化的数据库查询、缓存机制和虚拟滚动，支持处理 10 万+ 文件

## 技术栈

- **运行环境**：Java 17 LTS
- **桌面框架**：JavaFX 21
- **依赖管理**：Maven 3.9+
- **ORM 框架**：Hibernate 6.x（通过 Spring Data JPA）
- **数据库**：SQLite（通过 xerial/sqlite-jdbc 驱动）
- **全文搜索**：Apache Lucene 9.x
- **文件监控**：Apache Commons IO（FileAlterationMonitor）
- **依赖注入**：Spring Boot 3.x
- **UI 组件库**：ControlsFX
- **测试框架**：JUnit 5 + AssertJ
- **打包工具**：Maven Shade Plugin + jpackage

## 目录结构

```
my-tagstudio/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── mytagstudio/
│   │   │           ├── MyTagStudioApplication.java     # Spring Boot 主类（含 JavaFX 启动）
│   │   │           ├── config/                         # 配置类
│   │   │           │   ├── DatabaseConfig.java         # Hibernate + SQLite 配置
│   │   │           │   ├── JavaFxConfig.java           # JavaFX 初始化
│   │   │           │   └── LuceneConfig.java           # Lucene 索引配置
│   │   │           ├── controller/                     # 控制器层
│   │   │           │   ├── LibraryController.java      # 库管理控制器
│   │   │           │   ├── TagController.java          # 标签管理控制器
│   │   │           │   ├── EntryController.java         # 条目管理控制器
│   │   │           │   └── SearchController.java       # 搜索控制器
│   │   │           ├── service/                        # 服务层
│   │   │           │   ├── TagEngine.java              # 标签继承引擎
│   │   │           │   ├── SearchEngine.java           # 搜索引擎（DSL + Lucene）
│   │   │           │   └── LibraryManager.java         # 库扫描与文件监控
│   │   │           ├── repository/                     # 仓库层
│   │   │           │   ├── LibraryRepository.java
│   │   │           │   ├── EntryRepository.java
│   │   │           │   ├── TagRepository.java
│   │   │           │   └── EntryTagRepository.java
│   │   │           ├── entity/                         # 实体类
│   │   │           │   ├── Library.java
│   │   │           │   ├── Entry.java
│   │   │           │   ├── Tag.java
│   │   │           │   ├── EntryTag.java
│   │   │           │   ├── Field.java
│   │   │           │   └── FieldType.java              # 枚举
│   │   │           ├── dto/                            # 数据传输对象
│   │   │           │   ├── SearchQuery.java            # DSL 查询 DTO
│   │   │           │   ├── SearchResult.java           # 搜索结果 DTO
│   │   │           │   ├── TagNode.java                # 标签树节点 DTO
│   │   │           │   └── LibraryScanResult.java      # 库扫描结果 DTO
│   │   │           ├── ui/                             # UI 层
│   │   │           │   ├── MainView.java               # 主窗口
│   │   │           │   ├── LibraryView.java             # 库视图（表格/卡片切换）
│   │   │           │   ├── SettingsView.java           # 设置页面
│   │   │           │   └── components/                 # UI 组件
│   │   │           │       ├── EntryCell.java          # 条目单元格
│   │   │           │       ├── TagChip.java            # 标签芯片
│   │   │           │       └── SearchBar.java          # 搜索框（支持 DSL）
│   │   │           └── util/                           # 工具类
│   │   │               ├── PathUtil.java               # 路径处理工具
│   │   │               └── DatabaseUtil.java           # 数据库工具
│   │   └── resources/                                  # 资源文件
│   │       ├── application.properties                  # Spring Boot 配置
│   │       └── lucene/                                 # Lucene 索引目录（运行时生成）
│   └── test/                                           # 测试代码
│       └── java/
│           └── com/
│               └── mytagstudio/
│                   ├── service/
│                   │   ├── TagEngineTest.java
│                   │   ├── SearchEngineTest.java
│                   │   └── LibraryManagerTest.java
│                   └── repository/
│                       ├── TagRepositoryTest.java
│                       └── EntryRepositoryTest.java
├── pom.xml                                              # Maven 配置文件
└── README.md                                             # 项目说明文档
```

## 构建和运行

### 构建项目

```bash
# 编译项目
mvn clean compile

# 运行测试
mvn test

# 打包成 JAR 文件
mvn clean package

# 使用 jpackage 生成安装包
mvn clean jpackage:jpackage
```

### 运行应用

```bash
# 使用 Spring Boot 插件运行
mvn spring-boot:run

# 直接运行 JAR 文件
java -jar target/mytagstudio-1.0.0-SNAPSHOT.jar

# 运行 jpackage 生成的应用
# Windows: target/jpackage/MyTagStudio.exe
# macOS: target/jpackage/MyTagStudio.app
# Linux: target/jpackage/MyTagStudio
```

## 配置文件

应用配置文件位于 `~/.mytagstudio/application.properties`，包含以下配置项：

```properties
# SQLite 数据库配置
spring.datasource.url=jdbc:sqlite:~/.mytagstudio/tagstudio.db
spring.datasource.driver-class-name=org.sqlite.JDBC
spring.datasource.hikari.maximum-pool-size=1

# JPA 配置
spring.jpa.database-platform=org.hibernate.community.dialect.SQLiteDialect
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=false
spring.jpa.properties.hibernate.jdbc.batch_size=50
spring.jpa.properties.hibernate.order_inserts=true
spring.jpa.properties.hibernate.order_updates=true

# Lucene 索引配置
lucene.index.path=~/.mytagstudio/lucene

# 文件监控配置
file.monitor.interval=1000
file.monitor.thread-pool.size=10

# 日志配置
logging.level.com.mytagstudio=INFO
logging.level.org.hibernate.SQL=WARN
```

## 搜索语法

MyTagStudio 支持以下 DSL 搜索语法：

- `tag:<name>`：搜索包含指定标签的文件（支持标签继承）
- `filetype:<type>`：按文件类型筛选
- `path:<pattern>`：按路径模式筛选
- `AND`/`OR`/`NOT`：布尔运算

### 示例

- 搜索包含标签 "编程" 且文件类型为 "java" 的文件：
  ```
  tag:编程 AND filetype:java
  ```

- 搜索文件名包含 "report" 或 "document" 的 PDF 文件：
  ```
  (report OR document) AND filetype:pdf
  ```

- 搜索不包含标签 "草稿" 的文件：
  ```
  NOT tag:草稿
  ```

## 性能优化

1. **数据库层**：
   - 实体类上定义了索引
   - 使用批量插入（saveAll）避免 N+1 查询
   - 使用 LAZY 加载策略
   - 查询时使用 EntityGraph 避免 N+1 问题

2. **搜索层**：
   - 使用 Lucene 的 RAMDirectory（内存索引）提升搜索速度
   - 实现增量索引更新
   - 使用 Caffeine 缓存搜索结果

3. **UI 层**：
   - 使用 JavaFX 的 TableView 虚拟滚动
   - 使用 CellFactory 自定义单元格渲染
   - 使用 Platform.runLater() 在后台线程更新 UI

4. **文件监控层**：
   - 使用线程池处理文件事件
   - 实现事件去重（debounce 机制，500ms）
   - 限制并发处理数（最多 10 个文件同时处理）

## 隐私安全

- 所有数据存储在用户本地，绝对无网络请求
- 数据库文件存储在 `~/.mytagstudio/tagstudio.db`
- Lucene 索引存储在 `~/.mytagstudio/lucene`
- 配置文件存储在 `~/.mytagstudio/application.properties`
- 日志默认关闭，可选开启

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！