城迹（Folder City）

一个本地文件城市图谱工具。输入或选择一个文件夹后，后端扫描文件元数据，前端把不同类型、大小和修改时间的文件渲染成一座 2.5D 城市。

功能

• 递归扫描本地文件夹，只读取文件元数据，不读取文件内容
• 按文件类型映射建筑：代码=办公楼，图片=画廊，视频=影院，音频=音乐厅，文档=图书馆，压缩包=仓库，其他=住宅
• 文件越大，建筑越高；文件越久未修改，颜色越旧
• 展示文件数量、总大小、类型街区和建筑详情
• 支持路径输入和系统目录选择弹窗

项目结构

folder-city/
├─ backend/        # FastAPI 后端与文件扫描逻辑
├─ frontend/       # Vue + Vite 前端
├─ .gitignore
├─ .python-version
├─ pyproject.toml
├─ README.md
└─ uv.lock

后端启动

在项目根目录运行：

cd D:\Code\Python\Practice\folder-city
uv sync
uv run folder-city

默认后端地址：

http://127.0.0.1:8010

健康检查：

http://127.0.0.1:8010/api/health

如果端口冲突，可以指定端口：

$env:FOLDER_CITY_API_PORT="8020"
uv run folder-city

前端启动

另开一个终端：

cd D:\Code\Python\Practice\folder-city\frontend
npm install
npm run dev

默认前端页面：

http://127.0.0.1:5173

如果后端端口改了，前端代理也要同步指定：

$env:VITE_API_TARGET="http://127.0.0.1:8020"
npm run dev

前端构建

cd D:\Code\Python\Practice\folder-city\frontend
npm run build

frontend/node_modules/、frontend/.npm-cache/ 和 frontend/dist/ 都是可重新生成的目录，不需要提交到 Git。