Skip to content

Commit 8b40afc

Browse files
thedavidwengthedavidweng
committed
feat: align command structure with CONTEXT.md decisions
- Add 7 new command groups: favorites, galleries, groups, comments, contacts, stats, urls - Remove backup and files command groups (backup will merge into photos download) - Create CONTEXT.md with domain glossary and design decisions - Create ADR-0002 for Piwigo migration approach
1 parent c3b6c52 commit 8b40afc

14 files changed

Lines changed: 1040 additions & 710 deletions

‎CONTEXT.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# flickr-cli 领域术语表
2+
3+
## 核心守则
4+
5+
**flickr-cli 是 Flickr 网页版的替代品**，额外提供自动化便利和 agent 友好。能参照 Flickr 官方做法的自行决定，只询问 UX 相关的决策。
6+
7+
## 核心概念
8+
9+
**flickr-cli** — 个人 Flickr 管理 CLI 工具，用于管理自己的照片、相册、备份和迁移。
10+
11+
## 用户
12+
13+
**用户** — 希望用命令行替代网页版 Flickr 的人。一个人可能有多个账户（个人、公司、小号），通过 profile 管理。
14+
15+
**Profile** — 用户的 Flickr 账户凭证集合（API key + OAuth token）。默认 profile 是用户添加的第一个账户，可切换到其他 profile 操作不同账户。
16+
17+
## 命令设计决策
18+
19+
**下载/备份合并** — 将 `backup albums`、`backup user`、`backup id-dirs` 和 `photos download` 合并为统一的 `photos download` 命令，通过 flag 区分行为：
20+
- `--album` / `--album-id` — 从指定相册下载
21+
- `--all` — 下载所有照片
22+
- `--dest` — 目标目录
23+
- `--layout` — 目录布局（flat、album、id-dirs）
24+
- `--resume` — 断点续传
25+
- `--metadata` — 元数据格式（json、csv、both）
26+
27+
**安全门控** — 三级安全机制：
28+
- `--read-only` — 全局开关，阻止所有远程修改（适合脚本/Agent）
29+
- `--dry-run` — 操作级，只预览不执行（优先级高于 --confirm）
30+
- `--confirm` — 操作级，确认高风险操作（删除操作必须）
31+
32+
**缓存** — 自动管理的本地 SQLite 缓存，用于去重和加速查询。用户无需手动管理。
33+
34+
**Piwigo 迁移** — 只实现 Piwigo→Flickr 方向。通过 Piwigo REST API（ws.php）读取数据，密码通过 flag 传递（不持久化）。Flickr→Piwigo 方向已有官方 Flickr2Piwigo 插件，不需要实现。
35+
36+
**输出格式** — 三级输出：
37+
- 默认 — 简洁关键信息（ID + 标题）
38+
- `--full` — 完整信息
39+
- `--json` — 自动化/Agent 用
40+
41+
**进度报告** — 默认显示简洁进度（当前/总数 + 文件名），`--quiet` 关闭，`--events` 给 Agent 用。不显示 ETA。
42+
43+
**确认提示** — 删除等危险操作默认弹出交互确认（`Are you sure? [y/N]`），`--confirm` 跳过提示（Agent 用）。
44+
45+
**错误展示** — 人类模式显示友好消息 + 建议操作，`--debug` 显示技术细节。`--json` 模式下错误包含完整结构化信息（code、message、details）。
46+
47+
**API 覆盖范围** — CLI 应覆盖 Flickr API 的所有方法。`api call` 作为兜底入口，用于 Flickr 新增方法但 CLI 尚未适配的场景。
48+
49+
**命令结构** — 按资源类型分组，每个组下放 CRUD 操作，与 Flickr API 方法名对应：
50+
- `auth` — 认证
51+
- `photos` — 照片管理（含 download，合并自 backup）
52+
- `albums` — 相册管理
53+
- `favorites` — 收藏
54+
- `galleries` — 画廊
55+
- `groups` — 群组
56+
- `comments` — 评论
57+
- `contacts` — 联系人
58+
- `stats` — 统计
59+
- `urls` — URL 查找
60+
- `checksums` — 校验和
61+
- `cache` — 缓存
62+
- `piwigo` — 迁移
63+
- `api` — 原始 API 调用
64+
- `doctor` — 诊断
65+
- `version` — 版本

‎docs/adr/0002-piwigo-migration.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# ADR 0002: Piwigo 迁移功能
2+
3+
## Status
4+
5+
Accepted
6+
7+
## Context
8+
9+
用户希望将 Piwigo 照片库迁移到 Flickr。Piwigo 是一个自托管的开源照片管理系统。
10+
11+
经过调研，Piwigo 提供完整的 REST API（`ws.php`），支持：
12+
- `pwg.categories.getList` — 获取所有相册及层级
13+
- `pwg.categories.getImages` — 获取相册中的照片
14+
- `pwg.images.getInfo` — 获取照片详细元数据
15+
- `pwg.tags.getList` — 获取所有标签
16+
- `pwg.images.exist` — 通过 md5sum 检查照片是否已存在
17+
- `pwg.session.login` — 认证
18+
19+
## Decision
20+
21+
使用 Piwigo REST API 实现 Piwigo→Flickr 迁移功能，不再直接连接 MySQL。
22+
23+
Piwigo 已有官方 Flickr2Piwigo 插件（`Piwigo/Flickr2Piwigo`）支持 Flickr→Piwigo 方向，因此 flickr-cli 只实现 Piwigo→Flickr 单向迁移。
24+
25+
迁移流程：
26+
1. 通过 `pwg.session.login` 认证
27+
2. 通过 `pwg.categories.getList` 获取相册层级
28+
3. 通过 `pwg.categories.getImages` 遍历每个相册的照片
29+
4. 通过 `pwg.images.getInfo` 获取每张照片的元数据
30+
5. 通过 `pwg.images.exist` 检查 md5sum 实现去重
31+
6. 下载照片文件（通过 API 返回的 URL）
32+
7. 上传到 Flickr 并创建对应相册
33+
34+
命令设计：
35+
```bash
36+
flickr piwigo import --url https://photos.example.com --user admin --password secret
37+
flickr piwigo import --url ... --user ... --password ... --album "Vacation"
38+
flickr piwigo import --url ... --user ... --password ... --album-prefix "Piwigo/"
39+
```
40+
41+
密码通过 flag 传递（一次性迁移，不持久化 Piwigo 凭证）。
42+
43+
## Consequences
44+
45+
### Positive
46+
47+
- 不需要 MySQL 驱动依赖
48+
- 不需要用户开放数据库端口
49+
- 只需要 Piwigo URL + 用户名密码
50+
- 复用 Piwigo 已有的查询能力
51+
- 更安全（通过 HTTP 认证，而非数据库直连）
52+
53+
### Negative
54+
55+
- 需要 Piwigo 实例可访问
56+
- 大量照片时 API 调用次数多（但支持分页）

0 commit comments

Comments
 (0)