# AGENTS.md

> 本项目（火炬 VOD 管理器）的代理开发指南。

## 项目背景

一个轻量、开源的阿里云视频点播（VOD）媒体资源管理工具，核心目标是解决阿里云官方 VOD 控制台在查看、批量下载、批量删除大量视频时操作繁琐的问题。

- 名称：火炬 VOD 管理器
- 许可证：MIT
- 用户群体：开发者、内容运营人员
- 部署方式：macOS 原生应用（目标上架 Mac App Store）

## 技术栈

- **客户端**：Swift 6 + SwiftUI + SwiftData
- **阿里云 API**：自实现 POP 签名，直接调用 VOD OpenAPI
- **网络**：URLSession
- **持久化**：SwiftData（SQLite）

> 历史版本（已废弃）：React 18 + Express + SQLite 的 Web 版保留在 `apps/web` 和 `apps/server`，不再维护。

## 目录结构

```
.
├── apps/
│   ├── macos/            # macOS 原生 SwiftUI 应用
│   │   └── VODManager/
│   ├── web/              # React 前端（已废弃，历史参考）
│   └── server/           # Express 后端（已废弃，历史参考）
├── docs/                 # 部署与使用文档
├── PRD.md                # 产品需求文档
├── README.md
└── AGENTS.md             # 本文件
```

## 开发规范

### 代码风格

- 使用 Swift 6，严格并发检查。
- SwiftData 模型类使用 `@Model`，避免在并发任务中直接传递 `@Model` 实例。
- UI 使用 SwiftUI，状态管理使用 `@StateObject` / `@ObservedObject` / `@Query`。
- 阿里云 API 调用统一封装在 `VODClient` actor 中。
- 下载任务使用 `URLSessionDownloadTask`，文件名自动清理非法字符。

### 安全要求

- AccessKey Secret 存储在 SwiftData 中，建议后续接入 Keychain 加密存储。
- 阿里云 API 调用直接从客户端发起，不经过第三方后端。
- 建议用户创建最小权限 RAM 子用户。

### 常用命令

```bash
# 构建 macOS 应用
cd apps/macos/VODManager
swift build

# 运行
cd apps/macos/VODManager
swift run

# 在 Xcode 中打开
open apps/macos/VODManager/Package.swift
```

## App Store 注意事项

- 必须开启 App Sandbox。
- 使用 `com.apple.security.network.client` 访问阿里云 API。
- 使用 `com.apple.security.files.user-selected.read-write` 让用户选择下载目录。
- 默认下载到应用沙盒内部，提供「导出」功能让用户移动到外部目录。

## 数据库模型

- `Account`：阿里云账号配置
- `OperationLog`：操作日志
- `DownloadTask`：下载任务历史

## 贡献注意事项

1. macOS 修改后必须能通过 `swift build`。
2. 提交信息使用中文，描述清晰。
3. 涉及 SwiftData schema 变更时，需考虑现有用户数据迁移。