# file-sys

**Repository Path**: dbquery/file-sys

## Basic Information

- **Project Name**: file-sys
- **Description**: 个人文件管理系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-11
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# file-sys

本地文件管理系统。**导入即拷贝**：把散落在各处的文件统一导入到一个中央库（默认 `~/FileVault/YYYY/MM/DD/Type/`），在库里完成浏览、搜索、分类、打标签、去重。

源文件默认保留在原位；导入时可勾选"完成后移到回收站"。

## ✨ 功能

- 📥 **导入**：粘贴路径 → 预览（文件数/大小/分类分布）→ 确认 → 实时进度
- 🗂️ **库浏览**：网格视图，按导入时间倒序，可按分类筛选
- 🔍 **全文搜索**：FTS5 引擎，文件名/扩展名/分类/源路径都可搜，支持前缀匹配和高亮
- 🏷️ **标签**：自由打标签，颜色标记，多标签过滤
- 🔄 **去重**：基于 SHA-256 自动检测重复组，按"浪费字节"排序，逐组选择保留
- 🗑️ **安全删除**：所有删除走系统回收站，永不 `rm -rf`

## 🛠️ 技术栈

- 后端：Node.js ≥ 20 + Fastify 5 + better-sqlite3 (WAL + FTS5)
- 前端：React 18 + Vite + React Router + TanStack Query + zustand
- 存储：SQLite 单文件数据库，文件本体在文件系统
- 工程：npm workspaces（`server/` / `client/` / `shared/`）

## 🚀 快速开始

```bash
# 1. 安装依赖
npm install

# 2. 配置环境变量
cp server/.env.example server/.env
# 编辑 VAULT_PATH（默认 ~/FileVault）

# 3. 初始化数据库（建表 + FTS5 触发器）
npm run db:migrate

# 4. 启动开发（server :3001 + client :5173 并行）
npm run dev

# 浏览器打开 http://localhost:5173
```

## 📁 项目结构

```
file-sys/
├── server/                # Fastify 后端
│   ├── src/
│   │   ├── app.js         # Fastify factory
│   │   ├── config.js      # 环境变量 + vault 路径
│   │   ├── db/            # SQLite + migrations + repository
│   │   ├── services/      # 业务逻辑（importer/scanner/vault/...）
│   │   ├── routes/        # REST API 端点
│   │   └── utils/         # 路径安全、logger
│   └── .env.example
├── client/                # React 前端
│   └── src/
│       ├── pages/         # 7 个路由页面
│       ├── components/    # 共享组件
│       ├── api/           # fetch wrappers
│       └── styles/        # CSS
├── shared/                # 跨端常量
│   └── src/constants.js
└── tests/                 # 单元测试（node:test）
    └── unit/
```

## 📡 REST API 概览

| 资源 | 关键端点 |
|---|---|
| Files | `GET/DELETE /api/files[/:id]` |
| Imports | `POST /api/imports/preview`, `POST /api/imports`, `GET/POST /api/imports/:id[/cancel\|errors]` |
| Tags | `GET/POST/PATCH/DELETE /api/tags`, `POST/GET /api/files/:id/tags` |
| Search | `GET /api/search?q&category&ext`, `GET /api/search/suggest` |
| Duplicates | `GET /api/duplicates`, `POST /api/duplicates/resolve` |
| Settings | `GET/PUT /api/settings`, `GET /api/settings/vault` |
| Health | `GET /api/health` |

## 🔐 安全原则

1. **永不调用 `fs.rm`**：所有删除走 `safeDelete.moveToTrash`
2. **路径越权防御**：所有 vault 写入路径经 `vault.safeJoin` 校验
3. **默认保留源文件**：`postImportAction=keep` 为默认值
4. **拷贝即哈希**：单 pass `copyAndHash` 验证拷贝完整性，失败不入库
5. **本地访问**：server 默认 `127.0.0.1:3001`，不暴露到外网

## 🧪 测试

```bash
npm test                              # 全部
npm --workspace server run test       # 仅 server
```

覆盖：classifier（分类逻辑）、hasher（流式 SHA-256）、vault（路径越权防御）。

## 🛣️ 路线图

| Phase | 状态 | 内容 |
|---|---|---|
| 0 | ✅ | git init + 工程骨架 |
| 1 | ✅ | Fastify + Vite + 健康检查 |
| 2 | ✅ | 导入流水线 + 库浏览 |
| 3 | ✅ | 搜索 + 标签 + 去重 |
| 4 | ✅ | 设置页 + 库容量 + 单元测试 |

后续计划（待办）：缩略图（sharp + ffmpeg）、智能文件夹、批量操作、Toast 系统、Windows 回收站支持、orphans 清理工具。

## 📝 约定

- commit 粒度：每个逻辑功能点完成后立即 commit（一次 commit = 一个可独立验证的功能单元）
- commit message：Conventional Commits（`feat:` / `fix:` / `chore:` / `refactor:` / `docs:` / `test:`）
- 错误响应统一 `{ ok: false, error: { code, message } }`