Local Smart Gallery 是一个本地智能媒体库，旨在为您混乱的本地照片和视频文件夹带来秩序。它会自动扫描指定目录下的媒体文件，提取元数据，并将它们统一按时间顺序呈现在一个美观、高效的网页界面中。

无论是您用相机拍摄的照片，还是手机录制的视频，此应用都会将它们无缝地融合在同一个时间轴上，重现您在特定事件（如漫展、旅行）中的完整回忆。

• 统一时间线: 将照片 (.jpg, .png, .heic) 和视频 (.mp4, .mov, .avi) 混合排序在同一个视图中。
• 视频支持:
  • 自动生成缩略图: 后端在扫描时使用 OpenCV 截取视频第一帧作为预览，避免前端加载大文件。
  • 流式播放 (Streaming): 支持 HTTP Range Requests，即使是几百兆的大视频也能流畅拖动进度条，无需等待完整下载。
  • 元数据提取: 自动读取视频的创建时间和时长。
• 高效浏览:
  • 网格视图: 瀑布流式展示所有媒体，视频文件会以 ▶️ 图标和时长角标进行区分。
  • 详情视图 (Lightbox): 点击任意文件可进入大图/播放器模式，支持键盘左右键切换上一个/下一个。
  • 地图聚合: 地图页面会随缩放级别自动聚合/拆分地点标记，便于像 Apple Photos 一样浏览。
  • 地点详情页: 点击地图 pin 可进入地点详情页，按时间线样式查看该地点全部照片。
• 简单的扫描机制: 通过一个 API 请求即可启动对媒体文件夹的扫描和索引。

• 后端 (Backend):
  • 框架: Python & FastAPI
  • 数据库: SQLite & SQLAlchemy
  • 视频处理: OpenCV (cv2)
  • Web 服务器: Uvicorn
• 前端 (Frontend):
  • 框架: React (via Create React App)
  • HTTP 请求: axios
  • 视频播放: 原生 HTML5 <video> 标签

• Python (3.8 或更高版本)
• Node.js 和 npm (16.x 或更高版本)
• (可选) Git

1. 克隆仓库 (Clone the repository):

   git clone <your-repository-url>
   cd local-smart-gallery

2. 设置后端 (Setup Backend):

   # 1. 创建并激活 Python 虚拟环境
   python3 -m venv backend/venv
   source backend/venv/bin/activate
   
   # 2. 安装后端依赖
   pip install -r requirements.txt
   # (注意: 如果没有 requirements.txt, 请根据 AGENTS.md 手动安装)
   # pip install fastapi "uvicorn[standard]" sqlalchemy aiosqlite opencv-python

3. 设置前端 (Setup Frontend):

   # 1. 进入前端目录并安装依赖
   cd frontend
   npm install
   cd ..

4. 放置您的媒体文件 (Place your media files):

   • 在项目根目录下有一个 media/ 文件夹。
   • 将您想要展示的照片和视频文件复制到这里。

5. 启动应用 (Run the Application):

   • 启动后端服务器: 打开一个终端窗口

     source backend/venv/bin/activate
     or source backend/venv/Scripts/activate
     uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload
     
     

     服务器将在 http://localhost:8000 运行。

   • 启动前端开发服务器（局域网可访问）: 打开一个新的终端窗口

     cd frontend
     HOST=0.0.0.0 npm start

     应用将在 http://localhost:3000 自动打开，并可通过同一局域网 IP（如 http://192.168.x.x:3000）访问。

     Windows PowerShell 可用：$env:HOST="0.0.0.0"; npm start

6. 开始使用 (Start Using):

   • 打开浏览器，访问 http://localhost:3000。
   • 打开页面顶部的 "Settings" 页面，配置扫描目录、自动扫描开关与扫描策略。
   • 在 Settings 页可看到“局域网访问（iPad 扫码）”二维码，iPad 用相机扫码即可打开网页。
   • 在 Settings 页面点击 Scan All（或单目录 Scan），后端将开始索引媒体文件。
   • 扫描完成后，您的照片和视频画廊将呈现在页面上。享受吧！

• 禁止编写会导致卡片在 hover 时发生几何位移的动效（例如 transform: translateY(...)、scale(...)）。
• hover/focus 反馈仅允许使用不改变布局位置的样式（如颜色、边框、阴影、透明度）。
• 未来若 AI 生成代码违反本规范，必须在评审时拒绝并改回。

当出现地名异常（例如默认坐标导致的错误地名）时，可以使用该脚本批量刷新数据库中的地名。

# 预览（不写入数据库）
python backend/scripts/refresh_locations.py --dry-run

# 全量刷新（写入数据库）
python backend/scripts/refresh_locations.py

# 仅刷新某个目录下的媒体
python backend/scripts/refresh_locations.py --directory "D:/Git/MyOwnPhotoView/media"

当前使用 reverse_geocoder 离线反向地理编码，聚合格式为：

国家 + 省/州 + 城市

中文显示来自本地映射文件：

• backend/data/location_zh_map.json（国家/省/城市 英文→中文）
• backend/data/location_alias_zh.json（别名聚合，如 Shanghai Shi/Pujiang → 上海）

你可以在这两个文件中持续扩展映射与别名规则；未命中的项将保留英文。

下面是下次复用的标准打包流程（前端 build + 后端 exe）：

在项目根目录执行：

npm --prefix frontend install
npm --prefix frontend run build

成功后会生成：

• frontend/build/

python -m pip install pyinstaller

在项目根目录执行：

python -m PyInstaller --noconfirm --clean --onefile --name LocalSmartGallery --add-data "frontend/build;frontend/build" --add-data "backend/data/location_alias_zh.json;backend/data" --add-data "backend/data/location_zh_map.json;backend/data" backend/main.py

成功后会生成：

• dist/LocalSmartGallery.exe

发布目录需包含：

• dist/LocalSmartGallery.exe
• dist/start.bat

用户双击 start.bat 即可启动并自动打开：

• http://127.0.0.1:8000

直接把 dist/ 整个目录打包发出去即可（zip/7z 都行）。

• 首次运行会在 exe 同目录生成运行数据（如 gallery.db、backend/cache/、backend/data/）。
• 视频封面/时长依赖系统中的 ffmpeg / ffprobe；目标机器建议提前安装并加入 PATH。
• 若 8000 端口占用，可设置环境变量后启动：
  • set PORT=9000 && LocalSmartGallery.exe