# Changelog: 文件管理器 P1 — Composable 拆分 + 目录缓存

**日期**: 2026-06-02  
**类型**: 重构 (Refactor)  
**影响范围**: `frontend/src/pages/FilesPage.vue`、`frontend/src/stores/files.ts`、`frontend/src/composables/files/*`

---

## 变更摘要

按 `docs/design/specs/2026-06-02-files-refactor-design.md` 完成 P1：将 1500+ 行 `FilesPage.vue` 业务逻辑拆分为 Pinia store 与域 composable；页面 script 约 110 行，仅负责装配与模板绑定。

---

## 动机

- 单文件难以维护，三处 `browse()` 入口难追踪
- 为 P2 组件拆分、P3 缓存、P4 REST API 打基础

---

## 主要改动

| 模块 | 说明 |
|------|------|
| `stores/files.ts` | 服务器/路径/列表/权限状态；5s TTL 目录缓存（LRU 50 项） |
| `useFilesBrowse.ts` | 浏览、路由同步、序号与 in-flight 去重 |
| `useFilesNavigation.ts` | 面包屑、初始化、路由 watch、服务器切换 |
| `useFilesPermissions.ts` | capability、权限横幅、一键 sudo |
| `useFilesActions.ts` | 上传/删除/重命名/压缩/剪贴板等 |
| `useFilesEditor.ts` | 预览、Monaco 编辑 |
| `useFilesPage.ts` | 页面级装配入口 |
| `FilesPage.vue` | 模板不变，script 瘦身为 `useFilesPage()` |

---

## 行为变化

- **重复进入同一目录（5s 内）**：命中内存缓存，0 次 `/sync/browse`
- **写操作后**：`invalidateCache` 强制下次 `browse({ force: true })`
- 其余 UX 与 P0 后一致

---

## 是否需迁移 / 重启

- 仅前端重新构建部署
- 后端无变更

---

## 验证方式

1. `cd frontend && npx vite build`
2. 部署后 `prune_frontend_assets.py`
3. 文件管理：切换服务器、进目录、上传/删除/编辑/粘贴/sudo 配置
4. Network：同目录 5s 内二次进入无 browse 请求