feat(admin): add blob share and task admin apis

docs/api-reference.md

@@ -617,3 +617,138 @@
 - 服务重启后，只有 lease 已过期或历史上没有 lease 的 `RUNNING` 任务会在启动完成时被重置回 `QUEUED`，避免多实例下误抢仍在运行的 worker。
 - 创建成功后的任务 state 使用服务端文件信息，至少包含 `fileId`、`path`、`filename`、`directory`、`contentType`、`size`。
 - 桌面端 `Files` 页面会拉取最近 10 条任务、提供 `QUEUED/RUNNING` 取消按钮，并可为当前选中文件创建 `MEDIA_META` 任务；移动端与 archive/extract 的前端入口暂未接入。
+
+## 2026-04-10 Redis Login-State Invalidation
+
+- 新增可选 Redis 基础设施配置：
+  - `spring.data.redis.*`：连接参数。
+  - `app.redis.*`：业务 key prefix、TTL buffer、cache TTL 与命名空间。
+- 当 `app.redis.enabled=true` 时，认证链路会启用 Redis 驱动的登录态失效层：
+  - access token 按 `userId + clientType` 记录“在此时间点之前签发的 token 失效”。
+  - refresh token 按 hash 写入黑名单，TTL 与剩余有效期对齐。
+- `POST /api/auth/login`、`POST /api/auth/register`、`POST /api/auth/dev-login`：如果是同客户端重新签发登录态，旧 access token 会被写入 Redis 失效层，并继续保留原有 `sid` 会话匹配语义。
+- `POST /api/user/password`、管理员封禁/改密/重置密码相关路径：会同时触发 access token Redis 失效标记与数据库 refresh token 撤销。
+- `POST /api/auth/refresh`：旧 refresh token 在数据库撤销之外，还会同步写入 Redis 黑名单；先命中黑名单的 token 会被直接拒绝。
+- 当 Redis 关闭时，系统会自动回退到原有的数据库 refresh token + `sid` 会话校验语义，不影响本地与 dev 启动。
+## 2026-04-10 Redis Files Cache And Upload Runtime
+
+- `GET /api/files/list`
+  - 对外语义不变，仍使用 `path`、`page`、`size` 参数返回当前用户目录分页结果。
+  - 当 `app.redis.enabled=true` 时，后端会把热点目录页写入 Redis `files:list` cache，并通过目录版本号在创建、删除、移动、复制、重命名、恢复、上传完成和导入后做精准失效。
+  - 搜索结果、回收站列表和后台任务列表不复用这套 key，避免不同语义的分页结果互相污染。
+
+- `GET /api/v2/files/upload-sessions/{sessionId}`
+  - 响应体新增 `runtime` 字段；当 Redis 运行态存在时返回实时上传快照，不存在时返回 `null`，不影响原有会话元数据字段。
+  - `runtime` 当前包含 `phase`、`uploadedBytes`、`uploadedPartCount`、`progressPercent`、`lastUpdatedAt`、`expiresAt`。
+  - 该运行态由后端在会话创建、分片记录、代理上传、完成、取消、失败和过期时刷新，属于短生命周期缓存，不替代数据库里的最终状态。
+
+- `POST /api/files/recycle-bin/{fileId}/restore`
+  - 外部接口不变，但 Redis 启用时后端会为同一 `fileId` 的恢复流程加分布式锁，避免多实例或并发请求重复恢复同一批条目。
+
+## 2026-04-10 Redis Lightweight Broker First Landing
+
+- 本批次没有新增对外 HTTP API；用户可见接口仍沿用现有 `/api/files/**` 与 `/api/v2/tasks/**`。
+- 媒体文件通过网盘主链路落库后，后端现在会在事务提交后向轻量 broker 发布一次 `media-metadata-trigger`。这条触发只用于异步创建后台任务，不直接暴露为额外接口。
+- broker 当前只承载“自动补一条 `MEDIA_META` 任务”这一类轻量异步触发，最终执行状态、重试与公开结果仍以 `BackgroundTask` 记录和 `/api/v2/tasks/**` 查询结果为准。
+- `POST /api/v2/tasks/media-metadata`
+  - 用户手动创建任务的接口语义不变。
+  - 与此同时，媒体文件成功落库后也可能由后端自动补一条同类任务；系统会按 `correlationId` 去重，避免同一文件被 broker 重复创建多条自动任务。
+
+## 2026-04-10 Redis Transfer Session Store
+
+- 本批次没有新增快传 HTTP API，`/api/transfer/sessions`、`/api/transfer/sessions/lookup`、`/api/transfer/sessions/{sessionId}/join` 与信令轮询接口的对外协议保持不变。
+- 当 `app.redis.enabled=true` 时，在线快传 session 会写入 Redis `transfer-sessions` 命名空间，而不再只保存在当前 JVM 进程内；这让 `lookup/join/postSignal/pollSignals` 在多实例部署下具备共享同一在线会话状态的基础。
+- session 数据在 Redis 中会同时保存：
+  - `session:{sessionId}`：完整在线快传运行态快照。
+  - `pickup:{pickupCode}`：`pickupCode -> sessionId` 映射。
+- Redis 关闭时，系统会自动回退到原有进程内存 store，本地和 dev 环境不需要额外 Redis 也能继续运行。
+- 离线快传不走这套 Redis store，仍继续使用数据库 `OfflineTransferSession` 持久化模型。
+## 2026-04-10 Redis File Event Pub/Sub
+
+- `GET /api/v2/files/events?path=/`
+  - 对外 SSE 协议不变，仍要求登录并支持 `X-Yoyuzh-Client-Id`。
+  - 首次连接仍先收到 `READY` 事件，订阅路径过滤和同 `clientId` 自抑制语义保持不变。
+  - 当 `app.redis.enabled=true` 时，某个实例在事务提交后写入的文件事件会额外通过 Redis pub/sub 广播到其他实例，因此同一用户连到不同后端实例时也能收到变更通知。
+  - Redis pub/sub 只传播最小事件快照，不传播 `SseEmitter`、不重写 `FileEvent` 表，也不改变 `FileEvent` 作为审计持久化记录的角色。
+  - Redis 关闭时会自动回退为原有单实例本地广播行为。
+## 2026-04-10 Spring Cache Minimal Landing
+
+- `GET /api/admin/storage-policies`
+  - 瀵瑰鍗忚涓嶅彉銆?
+  - 褰?`app.redis.enabled=true` 鏃讹紝鍚庣浼氬皢鏁翠釜瀛樺偍绛栫暐鍒楄〃缂撳瓨鍒?`admin:storage-policies`銆?
+  - 褰?POST/PUT/PATCH` 瀛樺偍绛栫暐绠＄悊鎺ュ彛鍐欏叆鎴愬姛鍚庯紝缂撳瓨浼氱珛鍗宠澶辨晥锛屽悗缁璇锋眰浼氶噸寤烘柊鍒楄〃銆?
+
+- `GET /api/app/android/latest`
+  - 瀵瑰鍗忚涓嶅彉锛屼粛鏄叕寮€鎺ュ彛銆?
+  - 褰?`app.redis.enabled=true` 鏃讹紝鍚庣浼氬皢浠?`android/releases/latest.json` 鏋勫缓鍑虹殑 release metadata 鍝嶅簲缂撳瓨鍒?`android:release`銆?
+  - 杩欎釜缂撳瓨褰撳墠渚濊禆 TTL 鍒锋柊锛屽洜涓?latest metadata 鐨勬洿鏂版潵鑷?Android 鍙戝竷鑴氭湰鍐欏叆瀵硅薄瀛樺偍锛岃€屼笉鏄悗绔唴閮ㄦ煇涓鐞嗗啓鎺ュ彛銆?
+
+- `GET /api/admin/summary`
+  - 褰撳墠鏆備笉鎺ュ叆 Spring Cache銆?
+  - 鍘熷洜鏄繖涓?summary 鍚屾椂鍚湁 request count銆乧aily active users銆乭ourly timeline 绛夐珮棰戠粺璁″€硷紝鐢ㄦ樉寮忓け鏁堝緢闅惧湪褰撳墠鏋舵瀯涓嬩繚鎸佸共鍑€璇箟銆?
+## 2026-04-10 Spring Cache Minimal Landing Clarification
+
+- `GET /api/admin/storage-policies`
+  - Response shape is unchanged.
+  - When `app.redis.enabled=true`, the backend caches the full storage policy list in `admin:storage-policies`.
+  - Successful storage policy create, update, and status-change writes evict that cache immediately.
+
+- `GET /api/app/android/latest`
+  - Response shape is unchanged.
+  - When `app.redis.enabled=true`, the backend caches the metadata response derived from `android/releases/latest.json` in `android:release`.
+  - Refresh is TTL-based because the metadata is updated by the Android release publish script rather than an in-app admin write endpoint.
+
+- `GET /api/admin/summary`
+  - This endpoint is intentionally not cached at the moment.
+  - The response mixes high-churn metrics such as request count, daily active users, and hourly request timeline data, so there is not yet a clean explicit invalidation boundary.
+## 2026-04-10 DogeCloud Temporary S3 Session Clarification
+
+- No HTTP API contract changed in this batch.
+- The decision for Step 11 is architectural: DogeCloud temporary S3 sessions remain cached per backend instance inside `DogeCloudS3SessionProvider`.
+- This does not change upload, download, direct-upload, or multipart endpoint shapes; it only clarifies that cross-instance Redis reuse is intentionally not introduced for these temporary runtime sessions.
+## 2026-04-10 Stage 1 Validation Clarification
+
+- No API response shape changed in Step 12.
+- Validation confirmed that all new Redis-backed integrations added in Stage 1 still preserve the existing no-Redis API startup path when `app.redis.enabled=false`.
+- Local boot also confirmed that the backend now has one explicit non-Redis prerequisite for runtime startup in both default and `dev` profiles: `app.jwt.secret` must be configured via `APP_JWT_SECRET` and cannot be left empty.
+- Cross-instance behavior described by earlier Stage 1 notes remains architecturally valid, but it still needs real-environment verification with Redis plus multiple backend instances before being treated as deployment-proven.
+
+## 2026-04-10 Manual Redis Validation Addendum
+
+- No HTTP endpoint shape changed in this addendum either.
+- The local two-instance Redis validation did confirm these existing API behaviors in a real runtime flow:
+- `POST /api/auth/dev-login` on one instance invalidates the prior access token and refresh token even when the next authenticated read happens on the peer instance.
+- `POST /api/transfer/sessions` plus `GET /api/transfer/sessions/lookup` continue to work across instances for online sessions, including after the creating instance is stopped.
+- `GET /api/v2/files/events` on instance B receives a `CREATED` event after an authenticated media upload to instance A.
+- `GET /api/v2/tasks` on instance B exposes the queued `MEDIA_META` task auto-created by that upload.
+- Three backend fixes were internal and did not change API contracts:
+- Redis cache serialization/deserialization for file list pages;
+- Redis auth revocation cutoff precision;
+- non-null `storage_name` persistence for directory creation and normal file upload metadata.
+
+## 2026-04-11 Admin Backend Surface Addendum
+
+- `GET /api/admin/file-blobs`
+  - Auth: admin only.
+  - Query params: `page`, `size`, `userQuery`, `storagePolicyId`, `objectKey`, `entityType`.
+  - Response items expose `FileEntity`-centric blob inspection fields including `objectKey`, `entityType`, `storagePolicyId`, `referenceCount`, `linkedStoredFileCount`, `linkedOwnerCount`, `sampleOwnerUsername`, `sampleOwnerEmail`, `createdByUserId`, `createdByUsername`, `blobMissing`, `orphanRisk`, and `referenceMismatch`.
+  - This endpoint is for admin diagnostics and migration visibility; it does not replace end-user file reads.
+
+- `GET /api/admin/shares`
+  - Auth: admin only.
+  - Query params: `page`, `size`, `userQuery`, `fileName`, `token`, `passwordProtected`, `expired`.
+  - Response items expose share metadata from `FileShareLink`, plus owner and file summary fields.
+
+- `DELETE /api/admin/shares/{shareId}`
+  - Auth: admin only.
+  - Deletes the target `FileShareLink` immediately.
+  - Intended for operational cleanup and moderation.
+
+- `GET /api/admin/tasks`
+  - Auth: admin only.
+  - Query params: `page`, `size`, `userQuery`, `type`, `status`, `failureCategory`, `leaseState`.
+  - Response items expose task owner identity plus parsed task-state helpers: `failureCategory`, `retryScheduled`, `workerOwner`, and derived `leaseState`.
+
+- `GET /api/admin/tasks/{taskId}`
+  - Auth: admin only.
+  - Returns the same admin task response shape as the list endpoint for a single task.

docs/architecture.md

@@ -514,3 +514,132 @@ Android 壳补充说明：
 - worker 现在会按失败分类和任务类型做自动重试：失败会归到 `UNSUPPORTED_INPUT`、`DATA_STATE`、`TRANSIENT_INFRASTRUCTURE`、`RATE_LIMITED`、`UNKNOWN`；其中 `ARCHIVE` 默认最多 4 次、`EXTRACT` 最多 3 次、`MEDIA_META` 最多 2 次，公开 state 会暴露 `attemptCount/maxAttempts/retryScheduled/nextRetryAt/retryDelaySeconds/lastFailureMessage/lastFailureAt/failureCategory`。
 - 当前仍不包含非 zip 解压格式、缩略图/视频时长任务，以及 archive/extract 的前端入口。
 - 桌面端 `front/src/pages/Files.tsx` 已接入最近 10 条后台任务查看与取消入口，并可为当前选中文件创建 `MEDIA_META` 任务；移动端与 archive/extract 的前端入口仍未接入。
+## 11. UI 视觉系统与主题引擎 (2026-04-10 升级)
+
+### 11.1 设计语言：Stitch Glassmorphism
+
+全站视觉系统已全面转向“Stitch”玻璃拟态 (Glassmorphism) 风格，其核心特征包括：
+
+- **全局背景 (Aurora)**：在 `index.css` 中定义了 `bg-aurora`，结合颜色渐变与动态光晕产生深邃的底色。
+- **玻璃面板 (.glass-panel)**：核心 UI 容器均使用半透明背景 (`bg-white/40` 或 `bg-black/40`)、高饱和背景模糊 (`backdrop-blur-xl`) 和细腻的白色线条边框 (`border-white/20`)。
+- **浮动质感**：通过 `rounded-3xl` 或 `rounded-[2rem]` 的大圆角和外阴影增强层叠感。
+
+### 11.2 主题管理 (Theme Engine)
+
+系统内建了一套完整的主题上下文，主要路径为：
+
+- `front/src/components/ThemeProvider.tsx`：提供 `light | dark | system` 主题状态切换与持久化，通过操作 `html` 根节点的 `class` 实现。
+- `front/src/components/ThemeToggle.tsx`：全局主题切换按钮组件。
+- `front/src/lib/utils.ts`：提供 `cn()` 工具函数，用于处理 Tailwind 类的动态组合与主题适配。
+
+### 11.3 模块适配情况
+
+- **用户侧**：网盘、快传、分享详情、任务列表、回收站均已完成适配。所有表格、卡片和导航栏均已升级为玻璃态。
+- **移动端**：`MobileLayout` 实现了一套悬浮式玻璃顶部标题栏与底部导航栏，并保持与桌面端一致的光晕背景。
+- **管理侧**：Dashboard 大盘指标卡片、用户列表、文件审计列表和存储策略列表均已同步升级。
+
+## 12. Redis Foundation (2026-04-10)
+
+- 后端已引入 Spring Data Redis 与 Spring Cache，但 Redis 仍是可选基础设施：`app.redis.enabled=false` 时，应用会回退到 no-op token 失效服务与 `NoOpCacheManager`，本地与 dev 环境不需要外部 Redis 也能正常启动与测试。
+- Redis 配置拆成两层：
+  - `spring.data.redis.*`：连接参数。
+  - `app.redis.*`：业务 key prefix、TTL buffer、cache TTL 与命名空间。
+- 当前声明的 Redis 命名空间包括：`cache`、`auth`、`transfer-sessions`、`upload-state`、`locks`、`file-events`、`broker`。本轮真正落地使用的是 `auth`，其余属于后续 Stage 1 边界预留。
+- 当前声明的 Spring Cache 名称包括：`files:list`、`admin:summary`、`admin:storage-policies`、`android:release`。本轮只完成了缓存边界与 TTL 骨架，尚未把具体读路径接到这些 cache。
+- 认证链路新增 Redis 失效层：
+  - access token：按 `userId + clientType` 记录“在此时间点之前签发的 token 失效”。
+  - refresh token：按 token hash 写入黑名单，TTL 与剩余有效期对齐。
+- `JwtAuthenticationFilter` 现在会先检查 access token 是否已被 Redis 失效层拒绝，再继续执行原有的 JWT 校验、用户加载与 `sid` 会话匹配。
+- `AuthService` 与 `AdminService` 的同端重登、改密、封禁、管理员重置密码路径，现已统一调用这层服务；`RefreshTokenService` 在轮换、过期拒绝与批量撤销时也会同步刷新 refresh token 黑名单。
+## 12.1 Redis Foundation Batch 2 (2026-04-10)
+
+- `FileService.list(...)` 现已通过 `FileListDirectoryCacheService` 接入可选 Redis 热目录缓存，当前只缓存 `/api/files/list` 的目录分页结果，不混入搜索、回收站或后台任务列表。
+- 热目录缓存使用 `files:list` Spring Cache 命名空间，真实缓存 key 由 `userId + normalized path + page + size + fixed sort context + directory version` 组成；目录版本存放在 Redis KV 中，按目录粒度增量失效，避免全局清空。
+- 目录列表失效点已经覆盖 `mkdir`、上传完成、外部导入、回收站删除、回收站恢复、重命名、移动、复制与默认目录补齐，所有变更最终都归一到 `touchDirectoryListings(...)`。
+- 分布式锁新增 `DistributedLockService` 抽象与 Redis 实现，当前第一批只落在 `FileService.restoreFromRecycleBin(...)`，锁 key 为 `files:recycle-restore:{fileId}`，通过 `SETNX + TTL + owner token` 获取并用 Lua compare-and-delete 释放。
+- 上传会话运行态新增 `UploadSessionRuntimeStateService` 抽象与 Redis 实现，短生命周期状态写入 `upload-state` 命名空间；数据库里的 `UploadSession` 继续承担最终事实，Redis 只承载创建中、上传中、完成中这类运行态快照。
+- `UploadSessionV2Controller` 已把运行态映射到响应体 `runtime` 字段，便于前端轮询时直接读取 phase、已上传字节数、分片数、进度百分比与过期时间，而不需要额外拼装临时状态。
+
+## 12.2 Redis Foundation Batch 3 (2026-04-10)
+
+- 轻量 broker 已新增 `LightweightBrokerService` 抽象：Redis 启用时使用 `RedisLightweightBrokerService` 把消息写入 Redis list；Redis 关闭时回退到 `InMemoryLightweightBrokerService`，继续支持本地单实例开发与测试。
+- 这层 broker 明确只服务“小规模、低成本、可接受保守语义”的异步触发，不承担高可靠消息系统职责；任务最终状态、重试、幂等与用户可见结果仍以数据库 `BackgroundTask` 为准。
+- 当前 broker 使用 `app.redis.namespaces.broker` 命名空间，首个 topic 为 `media-metadata-trigger`，消息体只携带最小触发上下文：`userId`、`fileId`、`correlationId`。
+- `FileService.saveFileMetadata(...)` 现在会在媒体文件元数据落库后通过 `MediaMetadataTaskBrokerPublisher` 做 after-commit 发布；非媒体文件、目录、缺少必要主键信息的条目不会进入 broker。
+- `MediaMetadataTaskBrokerConsumer` 通过定时 drain 方式消费 broker 消息，并调用 `BackgroundTaskService.createQueuedAutoMediaMetadataTask(...)` 创建 `MEDIA_META` 任务；该入口会先按 `correlationId` 去重，再校验文件仍存在、未删除且仍属于媒体文件，避免重复建任务。
+- 这批实现的目标是“让轻量 broker 先承担一类真实异步触发”，而不是替代现有 `BackgroundTask` worker，也不覆盖文件事件跨实例广播；后者仍归 Stage 1 Step 9 处理。
+
+## 12.3 Redis Foundation Batch 4 (2026-04-10)
+
+- 在线快传 session 已从进程内 `ConcurrentHashMap` 提升为可选 Redis 支撑：`TransferSessionStore` 在 Redis 启用时把 session JSON 与 `pickupCode -> sessionId` 映射写入 `transfer-sessions` 命名空间，关闭时自动回退到原有内存模式。
+- Redis key 当前按 `session:{sessionId}` 与 `pickup:{pickupCode}` 组织，TTL 与 session `expiresAt` 对齐并附带 `app.redis.ttlBufferSeconds` 缓冲；因此 Redis 只承载在线快传的短生命周期运行态，不替代离线快传数据库模型。
+- `TransferSession` 新增内部快照序列化形状，用于保留 `receiverJoined`、信令队列、cursor 和文件清单等运行期状态；`joinSession`、`postSignal` 在修改在线 session 后会重新写回 store，避免 Redis 模式下只改内存副本而不持久化。
+- `TransferService.nextPickupCode()` 现在复用 `TransferSessionStore.nextPickupCode()`；Redis 启用时 pickup code 会先在 Redis 映射 key 上做短 TTL 预留，降低多实例并发创建在线快传 session 时的冲突概率。
+- 当前 Step 8 只覆盖在线快传 session 的跨实例 lookup/join 基础能力；离线快传仍继续使用 `OfflineTransferSessionRepository`，文件事件广播也仍留在 Step 9。
+## 12.4 Redis Foundation Batch 5 (2026-04-10)
+
+- 文件事件跨实例分发现在落地在 Redis pub/sub，而不是把 `SseEmitter` 或订阅状态搬进 Redis。每个实例仍只在本地维护 `userId -> subscriptions` 的内存映射，SSE 过滤逻辑继续由 `FileEventService` 负责。
+- `FileEventService.record(...)` 现在仍然先写 `FileEvent` 表；事务提交后会先向本实例订阅者投递，再通过 `FileEventCrossInstancePublisher` 把最小事件快照发布到 `keyPrefix:file-events:pubsub` topic。
+- Redis 开启时，`RedisFileEventPubSubPublisher` 会附带当前实例 `instanceId`；`RedisFileEventPubSubListener` 在收到消息后会忽略同实例回环消息，只把远端事件重建成 `FileEvent` 并交回 `FileEventService.broadcastReplicatedEvent(...)` 做本地 SSE 投递。
+- 这条链路的目标是“跨实例转发已提交的文件事件”，不是高可靠消息系统：它不重放历史事件，不替代 `FileEvent` 表持久化，也不承担断线补偿；真正的事件审计事实源仍然是数据库。
+- Redis 关闭时，`NoOpFileEventCrossInstancePublisher` 会让行为自动回退为原有单实例本地广播，dev 与本地测试环境不需要额外 Redis 也能继续运行。
+## 12.5 Redis Foundation Batch 6 (2026-04-10)
+
+- Spring Cache 鍦ㄨ繖涓€鎵规寮忔帴鍏ヤ簡涓ょ被楂樿浣庡啓璇昏矾寰勶細`AdminService.listStoragePolicies()` 浣跨敤 `admin:storage-policies`锛宍AndroidReleaseService.getLatestRelease()` 浣跨敤 `android:release`銆?
+- 瀛樺偍绛栫暐鍒楄〃鐨勭紦瀛樺け鏁堢偣鏄槑纭殑绠＄悊鍐欒矾寰勶細鍒涘缓銆佺紪杈戙€佸惎鍋滈兘鍦?`AdminService` 涓婄洿鎺?evict锛屼笉鎶婂叾浠栫敤鎴疯矾寰勬垨鏂囦欢璇昏矾寰勬贩杩涘悓涓€ cache銆?
+- Android release metadata 鍒欐槸 TTL 椹卞姩鐨勭紦瀛橈細鏁版嵁婧愪粛鏄璞″瓨鍌ㄧ殑 `android/releases/latest.json`锛屽悗绔彧缂撳瓨鏋勫缓鍚庣殑 `AndroidReleaseResponse`锛屼笉缂撳瓨 APK 鍒嗗彂瀛楄妭娴併€?
+- `admin summary` 缁忚瘎浼板悗鏆備笉鎺ュ叆缂撳瓨锛屽洜涓鸿繖涓?DTO 鍚屾椂缁勫悎浜嗛珮棰戝彉鍖栫殑 request metrics銆佹瘡鏃ユ椿璺冪敤鎴风粺璁″拰閭€璇风爜绛夊€硷紝鐩墠娌℃湁涓€涓共鍑€鐨勬樉寮忓け鏁堣竟鐣岄€傚悎鎶婂畠鏀惧叆 Spring Cache銆?
+## 12.5 Redis Foundation Batch 6 Clarification (2026-04-10)
+
+- Spring Cache is now active on two high-read, low-write backend read paths.
+- `AdminService.listStoragePolicies()` uses cache `admin:storage-policies`.
+- `AndroidReleaseService.getLatestRelease()` uses cache `android:release`.
+- Storage policy cache invalidation is explicit and tied to admin create, update, and status-change writes.
+- Android release metadata uses TTL-based refresh because the source of truth is object storage metadata at `android/releases/latest.json`, updated by the release publish script rather than an in-app write path.
+- APK byte streaming remains uncached; only the metadata response is cached.
+- `admin summary` remains uncached by design because it mixes several high-churn metrics and does not yet have a clean invalidation boundary.
+## 12.6 Redis Foundation Batch 7 Clarification (2026-04-10)
+
+- `DogeCloudS3SessionProvider` intentionally remains a per-instance in-memory cache instead of moving to Redis.
+- The cached object is not just raw temporary credentials; it is a live runtime session containing `S3Client` and `S3Presigner`, both of which have local lifecycle and cleanup semantics.
+- Because of that, a Redis-backed shared cache would either have to cache only raw credential material and rebuild SDK clients locally anyway, or attempt to share values that are not meaningful across JVM instances.
+- The current design keeps refresh ownership local to each backend instance: if cached credentials are still outside the one-minute refresh window, the existing runtime session is reused; once inside that window, the old runtime session is closed and a fresh one is fetched and rebuilt.
+- This leaves some duplicate DogeCloud temporary-token fetches in multi-instance deployments, but the current plan judges that cost lower than the added complexity and secret-handling surface of a Redis shared-credential cache.
+## 12.7 Redis Foundation Batch 8 Clarification (2026-04-10)
+
+- Stage 1 validation closed with two local checks: full backend test regression and a Redis-disabled `dev` boot-path check.
+- The local boot-path check matters because Redis integration is optional by design. With `APP_REDIS_ENABLED=false`, the application still starts as a normal single-instance backend once mandatory base config such as `APP_JWT_SECRET` is present.
+- In the validated local path, the backend started successfully on an alternate port (`18081`) under the `dev` profile, using H2 and no Redis dependency.
+- Therefore the current architecture boundary remains unchanged: Redis augments cache, pub/sub, lock, broker, and short-lived runtime state when enabled, but it is not a required baseline component for local development or single-instance fallback.
+- The architecture still has explicit environment-bound gaps that were not closed in-process: real Redis reliability/TTL observation and cross-instance propagation timing for file events, lightweight broker delivery, upload runtime state, and transfer-session sharing.
+
+## 12.8 Manual Redis Validation Clarification (2026-04-10)
+
+- The later manual validation pass did exercise real local Redis plus two backend instances, so several Stage 1 architecture claims are now locally runtime-validated rather than only unit/integration-tested.
+- Verified runtime behaviors:
+- auth token invalidation survives cross-instance login churn;
+- online transfer runtime state survives loss of the creating instance;
+- file events can cross instances through the SSE path when a real uploaded file triggers a `CREATED` event;
+- the lightweight broker can auto-create a queued `MEDIA_META` task after a media upload and that task is visible from the peer instance.
+- The Redis file list cache architecture also needed one implementation detail clarified: Spring Cache may hand back generic decoded maps from Redis, so `RedisFileListDirectoryCacheService` now treats cache-value reconstruction as an application concern instead of assuming a strongly typed cache provider result.
+- The persistence model also still carries `portal_file.storage_name` as a required column in the live schema, so even after blob/entity migration work the backend must continue writing a non-null legacy storage name for directories and uploaded files until a later schema migration explicitly removes that requirement.
+- One environment gap remains: local `redis-cli` key inspection did not reveal the expected keys during probing even while cross-instance behavior proved shared runtime state was active. That means the current architectural confidence comes from observable runtime behavior, not from direct local key-space inspection.
+
+## Debugging Discipline
+
+- Use short bounded probes first when validating network, dependency, or startup issues. Prefer commands such as `curl --max-time`, `mvn -q`, `mvn dependency:get`, `apt-get update`, and similar narrow checks before launching long-running downloads or full test runs.
+- Do not wait indefinitely on a stalled download or progress indicator. If a command appears stuck, stop and re-check DNS, proxy inheritance, mirror reachability, and direct-vs-proxy routing before retrying.
+- For WSL debugging, verify the proxy path and the direct path separately, then choose the shortest working route. Do not assume a mirror problem until the network path has been isolated.
+- Use domestic mirrors as a delivery optimization, not as a substitute for diagnosis. First determine whether the failure is caused by DNS, proxy configuration, upstream availability, or the mirror itself.
+
+## 12.9 Admin Backend Surface Clarification (2026-04-11)
+
+- The admin module now covers four distinct backend inspection domains:
+- user and summary management;
+- logical file management;
+- storage policy management and migration task creation;
+- operational inspection for file blobs, shares, and background tasks.
+- `GET /api/admin/file-blobs` is architected around `FileEntity` plus `StoredFileEntity` relations instead of around `StoredFile` rows. This keeps the admin surface aligned with the newer object/entity model and lets operators inspect storage-policy ownership, reference counts, and missing-object anomalies before the legacy read path is retired.
+- `GET /api/admin/shares` and `DELETE /api/admin/shares/{shareId}` sit on top of `FileShareLinkRepository` and are intended as operational controls for share hygiene rather than end-user sharing flows.
+- `GET /api/admin/tasks` and `GET /api/admin/tasks/{taskId}` sit on top of `BackgroundTaskRepository` and parse structured fields out of `publicStateJson` so the admin UI can inspect failure category, retry scheduling, worker owner, and lease freshness without re-implementing backend parsing rules.
+- This batch does not change the current production read-path boundary: download, share detail, recycle-bin, and zip flows still read from `StoredFile.blob`, while `FileEntity` and `StoredFile.primaryEntity` continue to carry migration-oriented metadata for newer admin and storage-policy workflows.

docs/superpowers/plans/2026-04-10-cloudreve-gap-next-phase-upgrade.md

@@ -0,0 +1,712 @@
+# Cloudreve Gap Next-Phase Upgrade Plan
+
+> **For agentic workers:** REQUIRED: Use `superpowers:executing-plans` or `superpowers:subagent-driven-development` when implementing this plan. Keep the checkbox state updated as work lands.
+
+**Goal:** 在不偏离当前产品方向的前提下，把项目中“对比 Cloudreve 仍明显缺失”的能力拆成可执行的后续升级阶段，优先补齐最能提升网盘完成度和平台化能力的部分，而不是盲目追平 Cloudreve 的全部生态。
+
+**Repository:** `C:\Users\yoyuz\Documents\code\my_site`
+
+**Decision:** 当前项目已经完成 v2 上传会话、存储策略、分享二期、搜索骨架、SSE 文件事件、后台任务骨架、回收站、Android 壳和前后端视觉重构。后续计划只覆盖“尚未完成且仍值得做”的能力，不重复规划已经落地的阶段。
+
+## 1. Current Baseline
+
+下列能力已完成，不应重新当作“待做”：
+
+- v2 upload session 已支持 `PROXY` / `DIRECT_SINGLE` / `DIRECT_MULTIPART`
+- 存储策略管理、迁移任务和策略能力声明已落地
+- 分享二期、文件搜索、文件事件 SSE、后台任务框架已落地
+- 回收站、媒体元数据任务、桌面端任务面板已落地
+- 前后端 UI 已完成一次系统性重构
+
+当前仍明确未完成或仅完成一半的点：
+
+- 后端尚未接入 Redis；当前没有 Spring Cache，也没有跨实例缓存/会话总线
+- 移动端文件搜索未接入
+- `ARCHIVE` / `EXTRACT` 前端入口未接入，移动端任务入口也未接入
+- 旧下载/分享详情/ZIP/回收站读取路径仍依赖 `StoredFile.blob`，尚未切到 `primaryEntity`
+- 仅有媒体元数据提取，没有缩略图、视频时长、预览资源管线
+- 没有 WebDAV
+- 没有远程离线下载器能力
+- 没有 OIDC / OAuth scope / 桌面同步客户端协议
+- 不建议当前阶段直接做完整 WOPI / Office 在线协作
+
+## 2. Scope And Priority
+
+### P0: 先补齐现有平台里的断点
+
+这部分不做新产品线，只把已经有骨架但没闭环的能力补完整：
+
+1. Redis 基础接入与缓存边界落地
+2. 移动端搜索接入
+3. `ARCHIVE` / `EXTRACT` 前端入口
+4. 移动端任务入口
+5. 旧读取路径从 `StoredFile.blob` 迁到 `primaryEntity`
+
+### Admin Console Alignment
+
+参考成熟项目的后台目录，当前项目后续管理台不应只停留在 `dashboard / users / files / storage-policies` 四类资源，而应逐步演进为以下信息架构：
+
+1. 面板首页
+2. 参数设置
+3. 文件系统
+4. 存储策略
+5. 节点
+6. 用户组
+7. 用户
+8. 文件
+9. 文件 Blob
+10. 分享
+11. 后台任务
+12. 订单
+13. 事件
+14. 滥用举报
+15. OAuth 应用
+
+其中适合当前项目近期推进的只有：
+
+- 参数设置
+- 文件系统
+- 存储策略
+- 用户
+- 文件
+- 文件 Blob
+- 分享
+- 后台任务
+- OAuth 应用（先预留，不急于完整实现）
+
+当前阶段明确延后：
+
+- 节点
+- 用户组
+- 订单
+- 事件独立审计中心
+- 滥用举报
+
+### P1: 预览与媒体管线
+
+这是最值得补的 Cloudreve 差距：
+
+1. 图片缩略图
+2. 视频 poster / 时长
+3. 文件列表与详情中的预览消费
+4. 失败状态与 metadata 持久化
+
+### P2: WebDAV 最小可用版
+
+只做单用户私有网盘最小读写，不提前做复杂共享挂载、锁协商和第三方 scope。
+
+### P3: 生态扩展 backlog
+
+这部分先保留为后续阶段，不在最近一轮升级中直接开工：
+
+1. 远程离线下载
+2. OIDC / OAuth scope
+3. 桌面同步客户端协议
+4. WOPI / Office 在线协作
+
+## 3. Non-Goals
+
+- 不把项目改造成 Cloudreve 克隆
+- 不新增与当前业务方向不一致的组织/团队协作大系统
+- 不在当前阶段接入完整 WOPI
+- 不为了“对齐功能表”而重做现有快传业务
+- 不引入仓库中不存在的验证命令
+
+---
+
+## 4. Stage 1: Redis Cache Foundation
+
+**Goal:** 为后端引入 Redis，先解决真正适合走缓存或跨实例共享的状态，不把所有内存结构机械搬过去。
+
+**Why now:**
+
+- 当前后端没有 `spring-boot-starter-data-redis`
+- `TransferSessionStore` 仍是进程内 `ConcurrentHashMap`
+- `FileEventService` 的订阅和广播只在单实例内有效
+- `DogeCloudS3SessionProvider` 只有本机进程内临时会话缓存
+- 你已经明确希望 Redis 承担登录态 / token 黑名单、热门目录缓存、分布式锁、上传状态缓存和小规模队列 broker
+
+**Files likely involved:**
+
+- `backend/pom.xml`
+- `backend/src/main/resources/application.yml`
+- `backend/src/main/resources/application-dev.yml`
+- `backend/src/main/java/com/yoyuzh/config/*`
+- `backend/src/main/java/com/yoyuzh/transfer/*`
+- `backend/src/main/java/com/yoyuzh/files/events/*`
+- `backend/src/main/java/com/yoyuzh/files/storage/*`
+- `backend/src/test/java/com/yoyuzh/**`
+- `docs/architecture.md`
+- `docs/api-reference.md`
+- `memory.md`
+
+- [x] **Step 1: 接入 Spring Data Redis 与配置骨架**
+  - 新增 Redis 依赖
+  - 在 `application.yml` / `application-dev.yml` 加入 `spring.data.redis.*` 与 `app.redis.*`
+  - Redis 必须允许关闭，不强制 dev 环境依赖外部服务
+
+- [x] **Step 2: 明确缓存分层，不做一锅炖**
+  - `Spring Cache`：用于热门目录和热点只读查询
+  - `Redis KV`：用于登录态派生状态、token 黑名单、快传会话、上传状态
+  - `Redis Lock`：用于分布式锁
+  - `Redis Pub/Sub`：用于多实例文件事件分发
+  - `Redis List/Stream` 或轻量队列表：用于小规模 broker
+  - 不把 JPA 实体直接无脑全量缓存
+
+- [x] **Step 3: 接入登录态 / token 黑名单**
+  - 保持当前 JWT + refresh token 主模型不变
+  - 新增 access token / refresh token 撤销或踢下线后的 Redis 黑名单能力
+  - 黑名单 TTL 与 token 剩余有效期对齐，避免永久堆积
+  - 用户改密、封禁、管理员重置密码、同端挤下线等场景统一走这套失效机制
+
+- [x] **Step 4: 接入热门目录缓存**
+  - 优先缓存 `/api/files/list` 的热点目录页结果，而不是所有目录
+  - 缓存 key 至少包含 `userId + path + page + size + sort context`
+  - 文件创建、删除、移动、重命名、恢复、导入、上传完成后精准失效相关目录
+  - 不让搜索结果、回收站列表和任务列表混进同一套 key
+
+- [x] **Step 5: 接入分布式锁**
+  - 先覆盖会发生并发冲突或重复执行风险的路径
+  - 优先考虑上传完成、存储策略迁移、后台任务 claim / retry、回收站恢复、目录批量导入
+  - 锁必须带 TTL 和 owner 标识，避免死锁
+  - 不用 Redis 锁去替代数据库事务
+
+- [x] **Step 6: 接入上传状态缓存**
+  - 用于保存上传中的短生命周期状态，而不是取代数据库中的最终事实
+  - 适合承载 chunk 进度、最近心跳、瞬时速度、前端轮询状态
+  - `UploadSession` 仍保留数据库持久化和最终完成语义
+  - Redis 状态过期后不应影响已完成或已失败的最终结果判断
+
+- [x] **Step 7: 引入小规模队列 broker**
+  - 目标不是替代当前数据库任务系统，而是给轻量异步链路和跨实例触发提供 broker
+  - 优先承载文件事件转发、缩略图触发、媒体处理触发、低成本异步通知
+  - 当前规模下可接受 Redis broker，但要明确“不是高可靠消息系统”
+  - 大任务最终状态仍以数据库 `BackgroundTask` 为准
+  - 2026-04-10 首批落地先收敛到“媒体文件落库后的 `MEDIA_META` 自动触发”，文件事件跨实例广播仍留给 Step 9 的 Redis pub/sub
+
+- [x] **Step 8: 把 `TransferSessionStore` 改成 Redis 支撑的 session store**
+  - 替换当前本地 `ConcurrentHashMap`
+  - 保持过期清理和 pickup code 查询语义不变
+  - 让在线快传在多实例下仍可 lookup/join
+  - 2026-04-10 当前实现为“Redis 启用时在线快传 session 走 Redis KV，关闭时自动回退到进程内存”，离线快传仍继续走数据库持久化链路
+
+- [x] **Step 9: 接入文件事件跨实例分发**
+  - 保留当前单实例 emitter 管理
+  - 新增 Redis pub/sub，把事务提交后的文件事件广播到其他实例
+  - 避免把 `SseEmitter` 本身存进 Redis
+
+- [x] **Step 10: 评估并最小落地 Spring Cache**
+  - 优先考虑热门目录、`admin summary`、存储策略列表、Android 最新发布元数据等高读低写接口
+  - 每个缓存都要有明确失效策略，不能只加 `@Cacheable`
+
+- [x] **Step 11: 审慎处理 DogeCloud 临时 S3 会话缓存**
+  - 若多实例下重复拉临时 token 成本可接受，则保留本地内存缓存
+  - 若需要跨实例复用，再单独加 Redis 缓存，不与业务缓存混用
+
+- [x] **Step 12: 验证**
+  - `cd backend && mvn test`
+  - 手动验证无 Redis 时应用仍可启动
+  - 手动验证启用 Redis 后快传在线会话可创建、lookup、join、过期
+  - 手动验证踢下线 / 改密后旧 token 失效
+  - 手动验证热门目录缓存命中与目录变更后失效
+  - 手动验证多实例下文件事件能跨实例到达
+  - 手动验证任务重复 claim 不会发生明显并发冲突
+
+**Exit criteria:**
+
+- Redis 成为可选但可用的基础设施
+- 登录态 / token 黑名单已接入 Redis
+- 至少一个真实热点目录查询接入 Redis/Spring Cache
+- 至少一个高风险并发路径接入分布式锁
+- 上传中的短生命周期状态已进入 Redis
+- 小规模 broker 已承担至少一类轻量异步触发
+- 在线快传会话不再依赖单进程内存
+- 文件事件具备跨实例扩展边界
+
+---
+
+## Admin Track: Backend Management Surface
+
+**Goal:** 按更成熟的后台目录，把当前项目后端管理能力补成“资源可观测、可管理、可扩展”的体系，而不是继续把所有管理功能堆进单一 summary 页面。
+
+### Admin-B1: Parameter Settings
+
+**Goal:** 新增“参数设置”资源，集中管理当前散落在配置和管理台中的系统开关。
+
+**Recommended internal sections:**
+
+1. 站点信息
+2. 用户会话
+3. 验证码
+4. 媒体处理
+5. 增值服务
+6. 邮件
+7. 队列
+8. 外观
+9. 事件
+10. 服务器
+
+**Current-project recommendation:**
+
+- 近期应实现：
+  - 站点信息
+  - 用户会话
+  - 媒体处理
+  - 队列
+  - 外观
+  - 服务器
+- 可先留空壳或只读：
+  - 验证码
+  - 邮件
+  - 事件
+- 当前不建议投入：
+  - 增值服务
+
+**Suggested scope:**
+
+- 注册与邀请策略
+- 离线快传总上限
+- 默认上传大小限制
+- 站点显示参数
+- 媒体处理开关
+- Redis / runtime 只读状态
+
+- [ ] **Step 1: 设计参数设置 DTO 与权限边界**
+- [ ] **Step 2: 先拆站点信息子分组**
+  - 站点名称
+  - 站点描述
+  - 主站点 URL
+  - 备用站点 URL
+  - 页脚代码
+  - 登录公告 / 站点公告
+  - 使用条款 / 隐私政策链接
+- [ ] **Step 3: 设计用户会话子分组**
+  - access / refresh 生命周期
+  - 同端挤下线策略
+  - token 黑名单开关与 TTL 策略
+  - 登录安全相关策略
+- [ ] **Step 4: 设计媒体处理子分组**
+  - 媒体元数据提取开关
+  - 缩略图开关
+  - 视频 poster / 时长提取策略
+  - 第三方依赖状态只读信息
+- [ ] **Step 5: 设计队列子分组**
+  - broker 类型
+  - worker 并发
+  - 失败重试预算
+  - 队列健康状态只读信息
+- [ ] **Step 6: 设计外观与服务器子分组**
+  - 前端品牌化字段
+  - CDN / 静态资源缓存参数
+  - 服务器运行信息、Redis 状态、存储后端状态
+- [ ] **Step 2: 暴露管理员参数读取与更新接口**
+- [ ] **Step 3: 只允许修改当前可安全热更新的参数**
+- [ ] **Step 4: 文档化哪些配置仍需环境变量或重启**
+
+### Admin-B2: File System
+
+**Goal:** 把“文件系统”作为独立后台资源，而不是只在文件列表里做删除。
+
+**Recommended internal sections:**
+
+1. 参数设置
+2. 全文搜索
+3. 文件图标
+4. 文件浏览应用
+5. 自定义属性
+
+**Current-project recommendation:**
+
+- 近期应实现：
+  - 参数设置
+  - 文件图标
+  - 自定义属性
+- 可先做只读骨架：
+  - 文件浏览应用
+- 当前延后：
+  - 全文搜索
+
+**Suggested scope:**
+
+- 默认存储后端概览
+- 上传模式能力矩阵
+- 媒体处理能力状态
+- 热门目录 / 缓存状态概览
+- WebDAV 预留状态
+
+- [ ] **Step 1: 设计文件系统只读总览接口**
+- [ ] **Step 2: 设计文件系统参数设置子分组**
+  - 文档在线编辑最大大小
+  - 回收站扫描间隔
+  - 文件 Blob 回收间隔
+  - 静态资源缓存 TTL
+  - 文件列表分页方式
+  - 最大分页大小
+  - 最大批量操作数量
+  - 最大递归搜索数量
+  - 地图提供商
+- [ ] **Step 3: 设计文件图标子分组**
+  - 扩展名到图标的映射策略
+  - 前端图标主题扩展点
+  - 自定义 mime/icon 映射入口
+- [ ] **Step 4: 设计文件浏览应用子分组**
+  - 当前阶段只读显示已接入的浏览/预览能力
+  - 后续为 WOPI / Office / 媒体浏览器预留入口
+- [ ] **Step 5: 设计自定义属性子分组**
+  - 标签 schema
+  - metadata key 命名约束
+  - 可搜索属性白名单
+- [ ] **Step 6: 暴露上传模式、缓存、媒体处理、WebDAV 状态**
+- [ ] **Step 7: 管理台可按模块查看文件系统运行态**
+
+### Admin-B3: File Blob
+
+**Goal:** 既然项目已经有 `FileBlob` / `FileEntity`，后台必须能查看物理对象层，而不是只看逻辑文件。
+
+**Suggested scope:**
+
+- Blob / Entity 基本信息
+- object key
+- storage policy
+- reference count
+- orphan 风险
+- 派生实体类型：`VERSION` / `THUMBNAIL` / `TRANSCODE`
+
+- [ ] **Step 1: 增加管理员 Blob/Entity 列表接口**
+- [ ] **Step 2: 支持按用户、策略、对象 key、实体类型过滤**
+- [ ] **Step 3: 标注高风险条目，如引用异常、迁移失败残留**
+
+### Admin-B4: Share
+
+**Goal:** 分享需要成为独立后台资源，便于管理滥用和过期内容。
+
+- [ ] **Step 1: 管理员分享列表接口**
+- [ ] **Step 2: 支持按用户、文件名、token、是否密码保护、是否过期过滤**
+- [ ] **Step 3: 支持管理员撤销分享**
+
+### Admin-B5: Background Tasks
+
+**Goal:** 后台任务不能只在用户视角可见，管理员也要能看全局任务池。
+
+- [ ] **Step 1: 增加管理员任务列表与详情接口**
+- [ ] **Step 2: 支持按任务类型、状态、失败分类、租约状态过滤**
+- [ ] **Step 3: 支持查看任务归属用户、重试信息、锁/worker 信息**
+
+### Admin-B6: OAuth Apps
+
+**Goal:** 为未来 WebDAV / 第三方客户端 / OIDC 留出后台资源位。
+
+- [ ] **Step 1: 当前阶段只预留数据模型与只读列表边界**
+- [ ] **Step 2: 不急于完整实现授权流程**
+- [ ] **Step 3: 在文档中明确这是后续阶段入口**
+
+---
+
+## 5. Stage 2: Close Existing v2 Gaps
+
+**Goal:** 把现有架构中的“半完成状态”补成真正可用的闭环，优先提升当前产品完成度。
+
+**Files likely involved:**
+
+- `front/src/pages/Files.tsx`
+- `front/src/mobile-pages/MobileFiles.tsx`
+- `front/src/lib/file-search.ts`
+- `front/src/lib/file-events.ts`
+- `front/src/lib/upload-session.ts`
+- `front/src/lib/api.ts`
+- `front/src/mobile-components/*`
+- `backend/src/main/java/com/yoyuzh/files/core/*`
+- `backend/src/main/java/com/yoyuzh/files/tasks/*`
+- `backend/src/main/java/com/yoyuzh/files/search/*`
+- `backend/src/test/java/com/yoyuzh/files/**`
+- `front/src/**/*.test.ts`
+
+- [ ] **Step 1: 移动端接入 v2 文件搜索**
+  - 复用现有 `front/src/lib/file-search.ts`
+  - 保持与桌面端相同的查询参数和空态行为
+  - 不把搜索结果写回目录缓存
+
+- [ ] **Step 2: 桌面端补齐 `ARCHIVE` / `EXTRACT` 入口**
+  - 从当前选中文件直接创建任务
+  - 在任务面板中区分 `ARCHIVE`、`EXTRACT`、`MEDIA_META`
+  - 错误态展示后端返回的任务失败原因
+
+- [ ] **Step 3: 移动端补齐任务入口**
+  - 至少支持查看最近任务
+  - 支持取消 `QUEUED` / `RUNNING`
+  - 支持为选中文件创建 `MEDIA_META`
+  - 如交互成本可控，再接 `ARCHIVE` / `EXTRACT`
+
+- [ ] **Step 4: 把旧读取路径从 `StoredFile.blob` 迁到 `primaryEntity`**
+  - 覆盖下载、ZIP、分享详情、回收站、媒体元数据读取等旧路径
+  - 保留兼容 fallback，直到历史数据回填验证完成
+  - 明确哪些 API 已完全不依赖 `blob`
+
+- [ ] **Step 5: 更新相关测试**
+  - 后端补读取路径切换和任务入口相关测试
+  - 前端补移动端搜索和任务面板交互测试
+
+- [ ] **Step 6: 验证**
+  - `cd backend && mvn test`
+  - `cd front && npm run test`
+  - `cd front && npm run lint`
+  - `cd front && npm run build`
+
+**Exit criteria:**
+
+- 桌面与移动端都能搜索
+- 桌面端能直接发起 archive/extract
+- 移动端至少能消费任务能力
+- 旧读取链路完成 `primaryEntity` 主读切换
+
+---
+
+## 6. Stage 3: Thumbnail And Rich Media Pipeline
+
+**Goal:** 把后台任务骨架扩展成真正可感知的媒体处理系统，这是当前项目相对 Cloudreve 最有价值的缺口。
+
+**Files likely involved:**
+
+- `backend/src/main/java/com/yoyuzh/files/tasks/*`
+- `backend/src/main/java/com/yoyuzh/files/storage/*`
+- `backend/src/main/java/com/yoyuzh/files/core/*`
+- `backend/src/main/java/com/yoyuzh/files/policy/*`
+- `backend/src/main/java/com/yoyuzh/files/**/FileMetadata*.java`
+- `front/src/pages/Files.tsx`
+- `front/src/mobile-pages/MobileFiles.tsx`
+- `front/src/lib/types.ts`
+- `front/src/components/**/*`
+- `backend/src/test/java/com/yoyuzh/files/**`
+
+- [ ] **Step 1: 增加 `THUMBNAIL` 任务类型与派生实体写入**
+  - 使用 `FileEntity` 挂接缩略图实体，不再把缩略图视作普通文件
+  - 失败时写入可辨识 metadata，避免前端无限重试
+
+- [ ] **Step 2: 图片缩略图生成**
+  - 为常见图片格式生成小尺寸预览
+  - 支持本地存储和当前 S3 兼容策略
+
+- [ ] **Step 3: 视频 poster 和时长提取**
+  - 至少落地视频时长
+  - poster 可以先做单帧封面，不要求完整 HLS
+
+- [ ] **Step 4: 前端列表和详情接入缩略图**
+  - 图片和视频列表显示缩略图
+  - 详情侧栏显示时长、尺寸、编码等已有 metadata
+  - 缩略图不可用时回退到文件图标
+
+- [ ] **Step 5: 能力与策略对齐**
+  - 明确哪些策略支持原生缩略图、哪些需要代理生成
+  - 管理台可查看缩略图相关 capability 和任务状态
+
+- [ ] **Step 6: 验证**
+  - `cd backend && mvn test`
+  - `cd front && npm run test`
+  - `cd front && npm run lint`
+  - `cd front && npm run build`
+
+**Exit criteria:**
+
+- 上传图片后可自动生成缩略图
+- 上传视频后可得到最小媒体信息和 poster/时长
+- 文件列表和详情可真实消费这些资源
+
+---
+
+## 7. Stage 4: Metadata, Labels, And Search Expansion
+
+**Goal:** 让 `FileMetadata` 不再只是骨架，真正承担标签、预览状态和搜索过滤。
+
+**Files likely involved:**
+
+- `backend/src/main/java/com/yoyuzh/files/search/*`
+- `backend/src/main/java/com/yoyuzh/files/core/*`
+- `backend/src/main/java/com/yoyuzh/files/**/FileMetadata*.java`
+- `backend/src/test/java/com/yoyuzh/files/search/*`
+- `front/src/lib/file-search.ts`
+- `front/src/pages/Files.tsx`
+- `front/src/mobile-pages/MobileFiles.tsx`
+
+- [ ] **Step 1: 明确 metadata key 规范**
+  - `media:*`
+  - `thumb:*`
+  - `tag:*`
+  - `sys:*`
+
+- [ ] **Step 2: 扩展 v2 搜索过滤能力**
+  - 标签过滤
+  - 媒体类型过滤
+  - 缩略图/预览状态过滤
+
+- [ ] **Step 3: 前端增加高级搜索入口**
+  - 桌面端先做
+  - 移动端至少支持基础筛选
+
+- [ ] **Step 4: 为后续 `shared_with_me` / `trash` 风格视图保留统一查询边界**
+  - 当前不必完全复制 Cloudreve File URI
+  - 但内部查询层应避免继续散落在多套 service 方法里
+
+- [ ] **Step 5: 验证**
+  - `cd backend && mvn test`
+  - `cd front && npm run test`
+  - `cd front && npm run lint`
+
+**Exit criteria:**
+
+- `FileMetadata` 真正进入用户能力层
+- 搜索不再只停留在文件名和固定字段
+
+---
+
+## 8. Stage 5: WebDAV Minimum Viable Support
+
+**Goal:** 提供最小可用的 WebDAV 能力，优先服务系统文件管理器挂载和简单同步场景。
+
+**Files likely involved:**
+
+- `backend/src/main/java/com/yoyuzh/config/*`
+- `backend/src/main/java/com/yoyuzh/files/core/*`
+- `backend/src/main/java/com/yoyuzh/files/upload/*`
+- `backend/src/main/java/com/yoyuzh/auth/*`
+- `backend/src/test/java/com/yoyuzh/**`
+- `docs/api-reference.md`
+- `docs/architecture.md`
+
+- [ ] **Step 1: 设计 WebDAV 路径边界**
+  - 首阶段只暴露当前登录用户自己的网盘根目录
+  - 不做共享目录挂载
+
+- [ ] **Step 2: 实现最小方法集**
+  - `PROPFIND`
+  - `GET`
+  - `PUT`
+  - `DELETE`
+  - `MKCOL`
+  - `MOVE`
+
+- [ ] **Step 3: 复用现有文件服务和上传会话**
+  - WebDAV `PUT` 不绕过容量检查、权限检查和存储策略
+  - 避免做一套独立写入链路
+
+- [ ] **Step 4: 明确认证方式**
+  - 首阶段优先 Basic + token/应用密码式接入，避免直接复用浏览器 JWT 语义
+  - 认证模型必须先文档化，再写实现
+
+- [ ] **Step 5: 验证**
+  - `cd backend && mvn test`
+  - 手动验证 Windows 或 macOS WebDAV 客户端的列目录、上传小文件、下载、创建目录、删除
+
+**Exit criteria:**
+
+- 常见 WebDAV 客户端能完成最小读写
+- 不引入绕过现有业务规则的旁路实现
+
+---
+
+## 9. Deferred Backlog
+
+这些项目保留到 Stage 4 之后重新评估，不在当前一轮升级中直接实现：
+
+- [ ] **Remote Download**
+  - 目标：类似 Cloudreve 的离线下载器
+  - 前置：后台任务、存储策略、文件实体、容量模型稳定
+
+- [ ] **OIDC / OAuth Scope**
+  - 目标：第三方客户端和更细粒度授权
+  - 前置：WebDAV 或开放客户端需求真实存在[text](app://-/index.html?hostId%3Dlocal)
+
+- [ ] **Desktop Sync Protocol**
+  - 目标：桌面同步客户端
+  - 前置：文件事件、Redis 跨实例广播、冲突策略、WebDAV 或专有同步协议边界明确
+
+- [ ] **WOPI / Office Online**
+  - 目标：在线 Office 协作
+  - 前置：权限、锁、预览、第三方接入边界成熟
+
+## 10. Recommended Execution Order
+
+1. Stage 1: 先接 Redis 基础设施
+2. Stage 2: 再补现有闭环断点
+3. Stage 3: 再做缩略图和 richer media
+4. Stage 4: 让 metadata/search 真正变成平台能力
+5. Stage 5: 最后接 WebDAV
+5. Deferred backlog: 仅在真实需求出现后再启动
+
+## 11. Documentation Follow-Up
+
+每完成一个阶段，都必须同步更新：
+
+- `memory.md`
+- `docs/architecture.md`
+- `docs/api-reference.md`
+
+更新内容至少包括：
+
+- 新增能力边界
+- 已废弃或迁移的旧路径
+- 验证命令与已知限制
+- 任何新的部署或运行时前置条件
+## 2026-04-10 Stage 1 Step 9 Landing Note
+
+- 已落地 `FileEventCrossInstancePublisher` + Redis pub/sub listener/publisher：本实例继续维护本地 `SseEmitter` 集合，提交后先做本地广播，再向 `app.redis.namespaces.file-events` 对应 topic 发布事件。
+- 远端实例收到消息后只做本地 SSE 投递，不重复写 `FileEvent` 表；同实例消息按 `instanceId` 忽略，避免本机回环重复推送。
+- Redis 关闭时自动回退为原有单实例本地广播语义。
+## 2026-04-10 Stage 1 Step 10 Landing Note
+
+- 宸插皢 `AdminService.listStoragePolicies()` 鎺ュ叆 `admin:storage-policies` Spring Cache锛屽苟鍦?`createStoragePolicy/updateStoragePolicy/updateStoragePolicyStatus` 涓夋潯绠＄悊鍐欒矾寰勪笂鍋?all-entries eviction锛岀‘淇濆悗鍙板瓨鍌ㄧ瓥鐣ュ垪琛ㄥ懡涓紦瀛樺悗浠嶈兘鍦ㄧ畝鍗曞啓鎿嶄綔鍚庣珛鍗虫仮澶嶄负鏂版暟鎹€?
+- 宸插皢 `AndroidReleaseService.getLatestRelease()` 鎺ュ叆 `android:release` Spring Cache锛屽綋鍓嶉噰鐢?TTL 鍨嬪け鏁堢瓥鐣ワ紝鍥犱负 release metadata 鏇存柊鏉ヨ嚜瀵硅薄瀛樺偍澶栭儴鍙戝竷鑴氭湰锛屼粨搴撳唴娌℃湁鍚屾簮鍐欏叆璺緞銆?
+- `admin summary` 缁忚瘎浼板悗鏆備笉鎺ュ叆 Spring Cache锛屽洜涓哄叾鍚屾椂鍖呭惈 request count銆乨aily active users銆乭ourly timeline 绛夐珮棰戠粺璁★紝鍋氭樉寮忓け鏁堝緢闅句繚璇佽涔夊共鍑€锛屽洜姝ゅ湪杩欎竴姝ユ槑纭帓闄ゃ€?
+## 2026-04-10 Stage 1 Step 10 Clarification
+
+- `AdminService.listStoragePolicies()` now uses Spring Cache `admin:storage-policies`.
+- Successful storage policy create, update, and status-change writes evict that cache explicitly.
+- `AndroidReleaseService.getLatestRelease()` now uses Spring Cache `android:release`.
+- Android release metadata refresh is TTL-based because `android/releases/latest.json` is updated by the external release publish script.
+- `admin summary` was evaluated and intentionally left uncached because it includes high-churn metrics without a clean explicit invalidation boundary.
+## 2026-04-10 Stage 1 Step 11 Clarification
+
+- `DogeCloudS3SessionProvider` remains an in-process runtime cache and is not moved into Redis.
+- The cached value is a live `S3FileRuntimeSession` containing `S3Client` and `S3Presigner`, so cross-instance Redis reuse would add serialization and lifecycle complexity without clear payoff.
+- Current semantics remain: each backend instance refreshes its own temporary session only when the cached credentials enter the one-minute refresh window.
+- This means multi-instance deployments may fetch duplicate temporary credentials, but the current cost was judged acceptable relative to the extra complexity of a Redis-backed shared credential cache.
+- Tests now explicitly cover cache reuse plus refresh-time and close-time resource cleanup in `DogeCloudS3SessionProviderTest`.
+## 2026-04-10 Stage 1 Step 12 Clarification
+
+- Stage 1 validation is complete for the current local environment.
+- Full backend verification passed with `cd backend && mvn test`, for a total of 294 passing tests.
+- A no-Redis boot-path check also passed under the `dev` profile when the required `APP_JWT_SECRET` environment variable was supplied and `APP_REDIS_ENABLED=false`.
+- The local boot verification was captured by starting the backend on port `18081`, confirming that Tomcat started and the application reached the `Started PortalBackendApplication` log line.
+- Two earlier local startup failures were confirmed as environment issues rather than Redis regressions: one missing `APP_JWT_SECRET`, and one unrelated port `8080` conflict caused by another local Java process.
+- Remaining validation still requires external environment support: a real Redis instance for cache/pubsub/broker/session end-to-end checks, and at least two backend instances for cross-instance event/session propagation checks.
+
+## 2026-04-10 Stage 1 Step 12 Manual Redis Validation Addendum
+
+- Stage 1 manual validation was continued in a real local Redis plus dual-backend setup (`dev` profile, ports `18081` and `18082`) after the initial closeout note.
+- The backend suite is now green at 301 passing tests after fixing four real Redis/manual-integration regressions discovered during that validation.
+- Fix 1: `RedisFileEventPubSubPublisher` and `RedisFileEventPubSubListener` now mark the intended constructor for Spring injection, which unblocked Redis-enabled startup.
+- Fix 2: `AuthTokenInvalidationService` now stores and compares access-token revocation cutoffs in epoch seconds, with compatibility handling for earlier millisecond values.
+- Fix 3: Redis-backed file list cache now uses the application `ObjectMapper` for Java time serialization and converts generic cache payload maps back into `CachedFileListPage` on cache reads.
+- Fix 4: `portal_file.storage_name` is now populated for both directory creation and normal file upload metadata writes, which unblocked real upload/manual event flows against the current schema.
+- Manual verification that succeeded in the real Redis plus two-instance setup:
+- Re-login invalidates the previous access token and refresh token across instances, while the newest token remains valid.
+- Online transfer sessions remain discoverable from the second instance even after the first instance is stopped, which confirms shared runtime state rather than same-process false positives.
+- Uploading `image/png` on instance A emits `CREATED` SSE on instance B and auto-creates a queued `MEDIA_META` task visible from instance B.
+- Directory list behavior was rechecked through real APIs: repeated `GET /api/files/list` remained stable after the cache fixes, and a subsequent directory mutation was immediately reflected by a fresh list response.
+- One environment observation remains open: direct `redis-cli --scan` inspection did not surface the expected Redis keys during local probing, even though cross-instance runtime behavior proved that Redis-backed sharing was active. Treat the runtime behavior checks as the stronger validation result for now.
+
+## 2026-04-11 Admin Next-Phase Backend Landing Note
+
+- The next backend-phase admin batch is now landed.
+- Implemented admin operational APIs:
+- `GET /api/admin/file-blobs`
+- `GET /api/admin/shares`
+- `DELETE /api/admin/shares/{shareId}`
+- `GET /api/admin/tasks`
+- `GET /api/admin/tasks/{taskId}`
+- The blob admin endpoint is intentionally `FileEntity`-centric and adds operator-facing anomaly signals: `blobMissing`, `orphanRisk`, and `referenceMismatch`.
+- The task admin endpoint adds backend-owned parsing for `failureCategory`, `retryScheduled`, `workerOwner`, and `leaseState` so the frontend does not need to infer them from raw JSON.
+- Integration and service coverage were expanded in `AdminControllerIntegrationTest` and `AdminServiceTest`, and the storage-policy cache test was kept aligned with the current constructor/dependency graph.
+- Verification passed with targeted admin tests and full backend regression:
+- `cd backend && mvn -Dtest=AdminControllerIntegrationTest,AdminServiceTest,AdminServiceStoragePolicyCacheTest test`
+- `cd backend && mvn test`
+- Full backend result after this landing note: 304 tests passed.