本地文件访问 API（Local File API）产品系统Vibe Coding

随着本地化部署、隐私计算与端侧内容应用增多，前端与业务服务对「安全访问本地磁盘」的需求持续上升：多根目录统一管理、图片/视频流式访问、文本读写与文件变更实时感知，已成为阅读器、内容采集、本地知识库与运维工具链中的基础能力。以轻量 API 中间件形式封装文件系统，可降低前端直连磁盘的安全风险，并便于与数据源、版本控制、应用部署等周边系统集成，具备明确的工程化落地价值与持续迭代空间。

1. **数据源管理**
将本地根目录注册为数据源（昵称、basePath、描述），支持创建、更新、删除与分页/模糊查询，后续文件操作均通过「数据源 + 相对路径」访问，限定安全边界、避免路径穿越。

2. **文件与图片访问**
按数据源或路径获取任意类型文件；图片支持质量、宽高等参数压缩与预览，便于阅读器展示与带宽控制。

3. **视频流式播放**
支持 HTTP Range 请求，兼容进度拖拽、快进快退等流式播放能力。

4. **文本读写与文件管理**
支持文本读取/写入（覆盖或追加、指定编码）、文件上传、重命名/移动、存在性检查、元信息查询及文本类型检测。

5. **目录浏览**
列出数据源下目录内容，支持递归、类型过滤、排序与分页，便于前端导航与资源浏览。

6. **文件变更监控**
通过文件监控配置与 WebSocket 推送 change/rename/delete 等事件，监控配置可持久化并在服务重启后自动恢复，替代轮询。

7. **运维与文档**
提供健康检查、Winston 日志、Makefile 启停运维，以及 Swagger/OpenAPI 对接文档，便于集成与部署。

### 负责任务

作为本项目的主要开发者，负责从设计到落地的完整后端实现，主要包括：

1. **需求与设计**：梳理阅读器等调用方对本地文件访问的诉求，输出详细设计、迭代设计与 API 对接文档（OpenAPI / 用户指南）。
2. **核心业务开发**：实现数据源管理、文件/图片/视频访问、文本读写、上传重命名、目录浏览、文件变更监控等 REST 接口与业务逻辑。
3. **实时能力**：基于 WebSocket 实现文件监控订阅与变更推送，并完成监控配置的持久化与服务重启后自动恢复。
4. **数据与集成**：对接 Model Data Server 完成数据源、监控等元数据的存储与查询；维护产品能力注册与版本迭代相关脚本/文档。
5. **工程化与运维**：搭建 TypeScript 工程、Winston 日志、环境配置、Makefile 启停/日志/构建流程，以及健康检查与统一错误处理。

### 技术栈

| 类别 | 技术 |
|------|------|
| 语言与运行时 | TypeScript、Node.js |
| Web 框架 | Express |
| 图片处理 | Sharp |
| 实时通信 | WebSocket（`ws`） |
| 文件上传 | Multer |
| 日志 | Winston |
| 配置 | dotenv |
| 元数据存储 | Model Data Server（MySQL） |
| 文档 | OpenAPI 3.0 / Swagger UI |
| 工程工具 | Makefile、Jest、ESLint、Prettier |

### 架构

采用经典 **MVC 三层架构**，职责清晰、便于按模块扩展：

- **Controller**：参数校验、HTTP/OpenAPI 响应、Range 等协议细节处理。