Implement coordinated frontend and backend updates

2026-04-12 11:36:13 +08:00
parent 9af2d38e37
commit 820e055d22
26 changed files with 7410 additions and 420 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1161,4 +1161,3 @@
 - 未拆开工作空间与内容资产前，不收口分享和快传
 - 未收口上传与存储治理前，不把内容资产域视为稳定
 - 未稳定后端领域边界前，不开始前端大规模域化重组
-
--- a/docs/frontend-component-guide.md
+++ b/docs/frontend-component-guide.md
@@ -0,0 +1,304 @@
+# 前端组件选型与替换指南
+
+## 1. 文档目标
+
+这份文档用于回答两个问题：
+
+1. 当前 `front/` 已经有哪些前端基础组件与页面壳
+2. 哪些“不完善但不承载业务规则”的前端组件适合用成熟开源组件替换
+
+本文只讨论前端组件、交互容器、表现层能力与替换边界，不改变 `docs/architecture.md` 里已经确定的领域边界。
+
+---
+
+## 2. 组件替换原则
+
+### 2.1 可以放心引入开源组件的范围
+
+- 纯展示层组件
+- 纯交互壳组件
+- 表格、图表、树、分栏、拖拽、上传入口、媒体播放器 UI
+- 不负责权限判断、不负责业务规则决策的基础组件
+
+### 2.2 不应交给开源组件决定的范围
+
+- 权限与身份判断
+- 上传模式选择：`PROXY / DIRECT_SINGLE / DIRECT_MULTIPART`
+- 分享是否可访问、可下载、可导入
+- 工作空间路径合法性、同级重名规则、回收站恢复规则
+- 任务是否可重试、是否可取消、状态机如何流转
+
+结论：
+
+- 开源组件负责“怎么展示、怎么交互”
+- 业务代码负责“能不能做、规则是什么、最终状态如何判定”
+
+---
+
+## 3. 当前项目已有的核心基础组件
+
+### 3.1 应用外壳
+
+- `front/src/components/layout/Layout.tsx`
+  - 桌面端主壳
+  - 包含左侧导航、主题切换、任务摘要、退出按钮、`UploadCenter`
+- `front/src/mobile-components/MobileLayout.tsx`
+  - 移动端主壳
+  - 包含顶部浮层、底部导航、主题切换、任务摘要、退出按钮、`UploadCenter`
+- `front/src/admin/AdminLayout.tsx`
+  - 管理台二级导航壳
+  - 负责后台子页面切换，不承载业务规则
+
+### 3.2 全局状态与共用组件
+
+- `front/src/components/ThemeProvider.tsx`
+  - 亮暗主题上下文
+- `front/src/components/ThemeToggle.tsx`
+  - 主题切换按钮
+- `front/src/components/upload/UploadCenter.tsx`
+  - 全局上传队列浮层
+  - 展示任务数量、展开/收起、清理已完成任务
+- `front/src/components/tasks/TaskSummaryPanel.tsx`
+  - 导航栏里的活动任务摘要
+- `front/src/components/media/FileThumbnail.tsx`
+  - 文件缩略图/类型图标组件
+
+### 3.3 现有组件短板
+
+- 表格几乎全是页面内手写 `<table>`
+- 文件树和文件详情面板仍是页面级拼装
+- 上传入口是“按钮 + 隐藏 input”模式，拖拽能力弱
+- 快传页面没有二维码、批量选择、可视化发送步骤
+- 媒体预览/播放器能力基本空缺
+- 管理台多个页面仍是占位页
+
+---
+
+## 4. 推荐引入的开源组件
+
+以下推荐按“适合当前项目”优先，而不是单纯按星标排序。
+
+### 4.1 `@tanstack/react-table`
+
+- GitHub: <https://github.com/TanStack/table>
+- 适合替换：
+- `front/src/admin/users-list.tsx`
+- `front/src/admin/files-list.tsx`
+- `front/src/admin/fileblobs.tsx`
+- `front/src/admin/shares.tsx`
+- `front/src/admin/tasks.tsx`
+- `front/src/pages/Shares.tsx`
+- `front/src/pages/Tasks.tsx`
+- 后续审计日志页
+- 后续管理台所有表格页
+- 适配原因：
+  - Headless，不会破坏当前玻璃拟态视觉
+  - 支持排序、筛选、分页、列配置、行操作
+  - 特别适合你这种“业务规则自写，视觉样式自定”的项目
+- 替换边界：
+  - 仅替换表格渲染和交互
+  - 用户角色、封禁、删除、任务取消等操作仍调用现有业务 API
+
+### 4.2 `@tanstack/react-virtual`
+
+- GitHub: <https://github.com/TanStack/virtual>
+- 适合替换：
+  - 网盘文件列表
+  - 管理台用户表
+  - 管理台文件审计表
+  - 任务列表与后续审计日志列表
+- 适配原因：
+  - 大列表性能提升明显
+  - 与 `TanStack Table` 搭配自然
+- 替换边界：
+  - 只负责渲染性能
+  - 不负责分页规则和数据源决策
+
+### 4.3 `react-dropzone`
+
+- GitHub: <https://github.com/react-dropzone/react-dropzone>
+- 适合替换：
+  - `front/src/pages/files/FilesPage.tsx` 的上传文件入口
+  - `front/src/transfer/pages/TransferPage.tsx` 的发送文件区域
+- 适配原因：
+  - 现有上传入口过于基础
+  - 拖拽体验、选中文件反馈、目录导入体验都能更好
+- 替换边界：
+  - 只负责文件选择与拖拽
+  - 上传策略仍由后端 `storage-governance` 决定
+
+### 4.4 `react-arborist`
+
+- GitHub: <https://github.com/brimdata/react-arborist>
+- 适合替换：
+  - `front/src/pages/files/FilesPage.tsx` 的左侧目录树
+- 适配原因：
+  - 当前目录树是递归按钮结构，功能够用但扩展性弱
+  - 后续若需要键盘导航、虚拟化、拖拽移动、懒加载，`react-arborist` 很合适
+- 替换边界：
+  - 只负责树控件交互
+  - 路径合法性、移动规则、同名冲突仍由后端判定
+
+### 4.5 `dnd-kit`
+
+- GitHub: <https://github.com/clauderic/dnd-kit>
+- 适合替换：
+  - 文件移动的可视化拖拽
+  - 上传队列排序
+  - 后续管理台面板编排
+- 适配原因：
+  - 你当前项目前端自定义程度高，`dnd-kit` 比重型集成组件更灵活
+- 替换边界：
+  - 只负责拖拽行为
+  - 最终 move/copy 仍走现有 API
+
+### 4.6 `react-resizable-panels`
+
+- GitHub: <https://github.com/bvaughn/react-resizable-panels>
+- 适合替换：
+  - 网盘页面三栏布局：目录树 / 文件表 / 文件详情
+  - 后续管理台多面板布局
+- 适配原因：
+  - 当前 `FilesPage` 三栏是固定宽度，不利于高密度工作流
+  - 可调面板更符合“桌面工作台”气质
+
+### 4.7 `recharts`
+
+- GitHub: <https://github.com/recharts/recharts>
+- 适合替换：
+  - `front/src/admin/dashboard.tsx` 的遥测图表区域
+  - 后续请求趋势、活跃用户、存储分布图
+- 适配原因：
+  - 当前后台总览以统计卡为主，图表层很薄
+  - `Recharts` 接入简单，适合当前 React 栈
+- 替换边界：
+  - 只负责可视化
+  - 指标口径仍由后端 summary 接口定义
+
+### 4.8 `vidstack`
+
+- GitHub: <https://github.com/vidstack/player>
+- 适合替换：
+  - 后续文件预览页里的音视频播放器
+  - 分享页的音视频预览层
+- 适配原因：
+  - 当前项目几乎没有完整播放器能力
+  - `vidstack` 的 React 组合式设计很适合保留你的视觉系统
+- 替换边界：
+  - 只负责播放 UI 与控制条
+  - 下载授权、预览授权、签名地址获取仍由业务接口负责
+
+### 4.9 `hls.js`
+
+- GitHub: <https://github.com/video-dev/hls.js>
+- 适合替换：
+  - 后续若引入 `m3u8` / 分片视频播放
+- 适配原因：
+  - 这是 HLS 底层能力，不建议自己实现
+- 替换边界：
+  - 作为播放器底层能力
+  - 不承载任何业务权限逻辑
+
+---
+
+## 5. 当前项目不建议优先引入的组件
+
+### 5.1 `ag-grid`
+
+- 功能很强
+- 但对当前项目来说偏重
+- 会明显抬高管理台复杂度和定制成本
+- 只有在后台表格演进成“数据平台级界面”时才值得引入
+
+### 5.2 重型文件管理器整包
+
+- 不建议直接引入“整套 file manager UI”
+- 原因是你的业务语义已经明显超出通用文件管理器：
+  - 分享
+  - 快传
+  - 异步任务
+  - 存储策略
+  - 管理治理
+- 更适合按能力拆分引入单点组件，而不是整体换壳
+
+---
+
+## 6. 推荐替换优先级
+
+### P1：立刻有价值
+
+1. `@tanstack/react-table`
+2. `react-dropzone`
+3. `react-resizable-panels`
+4. `recharts`
+
+### P2：网盘工作区增强
+
+1. `react-arborist`
+2. `@tanstack/react-virtual`
+3. `dnd-kit`
+
+### P3：媒体预览体系建设
+
+1. `vidstack`
+2. `hls.js`
+
+---
+
+## 7. 页面与推荐组件映射
+
+| 页面 | 当前问题 | 推荐组件 | 替换范围 |
+| --- | --- | --- | --- |
+| `/files` | 文件树、文件表、上传入口都较原始 | `react-arborist` + `TanStack Table` + `react-dropzone` + `react-resizable-panels` | 目录树、文件表、上传选择、三栏布局 |
+| `/tasks` | 列表为手写表格 | `TanStack Table` | 列表渲染与排序/筛选 |
+| `/shares` | 列表信息密度一般 | `TanStack Table` | 分享表格与列配置 |
+| `/transfer` | 文件选择、状态展示、历史记录卡片较基础 | `react-dropzone` | 文件选择与拖拽体验 |
+| `/admin/dashboard` | 图表能力偏弱 | `recharts` | 指标趋势和分布图 |
+| `/admin/users` | 表格操作多但结构不稳定 | `TanStack Table` | 用户管理表格 |
+| `/admin/files` | 审计表格可扩展性弱 | `TanStack Table` + `TanStack Virtual` | 文件审计表格和大列表性能 |
+| `/admin/file-blobs` | 风险巡检列表尚未实现 | `TanStack Table` + `TanStack Virtual` | 对象实体列表、筛选、风险标签 |
+| `/admin/shares` | 分享治理页尚未实现 | `TanStack Table` | 分享治理列表和筛选栏 |
+| `/admin/tasks` | 全站任务监控尚未实现 | `TanStack Table` | 任务监控表格与详情侧栏 |
+| `/admin/audits` | 审计日志前端未接线 | `TanStack Table` | 审计日志表格与筛选栏 |
+| 媒体预览页（待建） | 目前无播放器体系 | `vidstack` + `hls.js` | 播放器和流媒体底层 |
+
+---
+
+## 8. 建议保留自研的部分
+
+这些部分不建议被开源组件接管：
+
+- `front/src/lib/upload-session.ts`
+- `front/src/lib/upload-runtime.ts`
+- `front/src/lib/background-tasks.ts`
+- `front/src/lib/shares-v2.ts`
+- `front/src/lib/files.ts`
+- `front/src/transfer/api/transfer.ts`
+- 页面内所有调用业务 API 的 action handler
+
+原因：
+
+- 它们直接对应项目自己的领域模型和 API 语义
+- 它们才是“项目资产”，而不是 UI 可替换件
+
+---
+
+## 9. 最推荐的一组组合
+
+如果只做一轮最稳、最值的升级，建议组合如下：
+
+- 表格：`@tanstack/react-table`
+- 大列表：`@tanstack/react-virtual`
+- 上传入口：`react-dropzone`
+- 目录树：`react-arborist`
+- 分栏布局：`react-resizable-panels`
+- 图表：`recharts`
+- 播放器：`vidstack`
+- HLS 底层：`hls.js`
+
+这组组合和当前项目的契合点在于：
+
+- 不会抢走业务规则所有权
+- 能显著改善工作台体验
+- 能让管理台和网盘页更专业
+- 不会把前端重构成另一个不可控的大系统
--- a/docs/frontend-page-orchestration.md
+++ b/docs/frontend-page-orchestration.md
--- a/docs/superpowers/plans/2026-04-12-admin-oss-refactor.md
+++ b/docs/superpowers/plans/2026-04-12-admin-oss-refactor.md
@@ -0,0 +1,141 @@
+# Admin OSS Refactor Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the most error-prone hand-rolled admin UI primitives with mature OSS components, starting with configuration forms.
+
+**Architecture:** Do the replacement in two batches. Batch 1 replaces form state and validation on configuration-heavy pages with `react-hook-form`. Batch 2 replaces hand-built table state/rendering on admin resource lists with `@tanstack/react-table`. Keep backend contracts unchanged and preserve the existing visual system.
+
+**Tech Stack:** React 19, TypeScript, Vite 6, Tailwind CSS v4, `react-hook-form`, `@tanstack/react-table`
+
+---
+
+### Task 1: Replace Configuration Forms With `react-hook-form`
+
+**Files:**
+- Modify: `front/package.json`
+- Modify: `front/package-lock.json`
+- Modify: `front/src/admin/settings.tsx`
+- Modify: `front/src/admin/users-list.tsx`
+
+- [x] **Step 1: Add `react-hook-form` to the frontend**
+
+Run:
+
+```bash
+cd front && npm install react-hook-form
+```
+
+Expected: `front/package.json` and `front/package-lock.json` include `react-hook-form`.
+
+- [x] **Step 2: Migrate `系统设置` editable sections to `react-hook-form`**
+
+Target:
+
+```text
+- invite code form
+- offline transfer limit form
+- validation and submit lifecycle
+```
+
+Expected: remove page-local draft state for editable settings where `react-hook-form` can own the fields.
+
+- [x] **Step 3: Migrate `用户策略` editor panel to `react-hook-form`**
+
+Target:
+
+```text
+- role
+- storageQuotaBytes
+- maxUploadSizeBytes
+- manualPassword
+```
+
+Expected: replace manual draft state and ad hoc validation with form-driven state and explicit submit handlers.
+
+- [x] **Step 4: Verify Batch 1**
+
+Run:
+
+```bash
+cd front && npm run lint
+cd front && npm run build
+```
+
+Expected: both commands pass.
+
+### Task 2: Replace Admin List Tables With `@tanstack/react-table`
+
+**Files:**
+- Modify: `front/package.json`
+- Modify: `front/package-lock.json`
+- Modify: `front/src/admin/users-list.tsx`
+- Modify: `front/src/admin/storage-policies-list.tsx`
+
+- [x] **Step 1: Add `@tanstack/react-table` to the frontend**
+
+Run:
+
+```bash
+cd front && npm install @tanstack/react-table
+```
+
+Expected: `front/package.json` and `front/package-lock.json` include `@tanstack/react-table`.
+
+- [x] **Step 2: Migrate `用户策略` table rendering to TanStack**
+
+Expected:
+
+```text
+- columns defined declaratively
+- row rendering stays visually consistent
+- action cells preserve current behavior
+```
+
+- [x] **Step 3: Migrate `存储策略` table rendering to TanStack**
+
+Expected:
+
+```text
+- existing columns preserved
+- no backend contract changes
+- current modal / action flows preserved
+```
+
+- [x] **Step 4: Verify Batch 2**
+
+Run:
+
+```bash
+cd front && npm run lint
+cd front && npm run build
+```
+
+Expected: both commands pass.
+
+### Task 3: Extend TanStack Table To Share Governance
+
+**Files:**
+- Modify: `front/src/admin/shares.tsx`
+
+- [x] **Step 1: Migrate `分享治理` table rendering to TanStack**
+
+Expected:
+
+```text
+- existing columns preserved
+- no backend contract changes
+- copy / open / delete actions preserved
+- filter form and empty state preserved
+```
+
+- [x] **Step 2: Verify Batch 3**
+
+Run:
+
+```bash
+cd front && npm run lint
+cd front && npm run build
+```
+
+Expected: both commands pass.
--- a/docs/superpowers/plans/2026-04-12-frontend-docs.md
+++ b/docs/superpowers/plans/2026-04-12-frontend-docs.md
@@ -0,0 +1,335 @@
+# Frontend Documentation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Write two repo-aligned frontend docs: one component selection guide tailored to this project and one page orchestration guide that enumerates every current page, buttons, and admin settings item.
+
+**Architecture:** Read the live frontend routes, shared shells, admin pages, and supporting API shapes first, then write the docs directly from code so the output reflects the real UI instead of intentions. Keep the component guide opinionated about which OSS components fit the project while keeping the page orchestration guide strictly descriptive about what exists today.
+
+**Tech Stack:** Markdown, Vite 6, React 19, TypeScript, repo docs under `docs/`
+
+---
+
+### Task 1: Inventory Current Frontend Routes And Admin Surfaces
+
+**Files:**
+- Modify: `docs/superpowers/plans/2026-04-12-frontend-docs.md`
+- Read: `front/src/App.tsx`
+- Read: `front/src/components/layout/Layout.tsx`
+- Read: `front/src/mobile-components/MobileLayout.tsx`
+- Read: `front/src/admin/*.tsx`
+- Read: `front/src/pages/**/*.tsx`
+- Read: `front/src/transfer/pages/TransferPage.tsx`
+- Read: `front/src/lib/admin*.ts`
+
+- [ ] **Step 1: Capture the route and admin page inventory**
+
+```text
+Public routes:
+- /login
+- /share/:token
+
+App routes:
+- /overview
+- /files
+- /tasks
+- /shares
+- /recycle-bin
+- /transfer
+
+Admin routes:
+- /admin/dashboard
+- /admin/settings
+- /admin/filesystem
+- /admin/storage-policies
+- /admin/users
+- /admin/files
+- /admin/file-blobs
+- /admin/shares
+- /admin/tasks
+- /admin/oauth-apps
+```
+
+- [ ] **Step 2: Verify the route inventory against the code**
+
+Run:
+
+```bash
+sed -n '1,220p' front/src/App.tsx
+```
+
+Expected: route declarations matching the list above.
+
+- [ ] **Step 3: Capture the implemented admin settings and placeholder pages**
+
+```text
+Implemented admin pages:
+- dashboard
+- storage-policies
+- users
+- files
+
+Placeholder admin pages:
+- settings
+- filesystem
+- file-blobs
+- shares
+- tasks
+- oauth-apps
+```
+
+- [ ] **Step 4: Verify the admin page status directly**
+
+Run:
+
+```bash
+sed -n '1,340p' front/src/admin/settings.tsx
+sed -n '1,340p' front/src/admin/filesystem.tsx
+sed -n '1,340p' front/src/admin/fileblobs.tsx
+sed -n '1,340p' front/src/admin/shares.tsx
+sed -n '1,340p' front/src/admin/tasks.tsx
+sed -n '1,340p' front/src/admin/oauthapps.tsx
+```
+
+Expected: simple placeholder components with only a title and no real controls.
+
+- [ ] **Step 5: Commit the inventory checkpoint**
+
+```bash
+git add docs/superpowers/plans/2026-04-12-frontend-docs.md
+git commit -m "docs: add frontend docs planning inventory"
+```
+
+### Task 2: Write The Frontend Component Selection Guide
+
+**Files:**
+- Create: `docs/frontend-component-guide.md`
+- Read: `front/src/components/layout/Layout.tsx`
+- Read: `front/src/mobile-components/MobileLayout.tsx`
+- Read: `front/src/components/upload/UploadCenter.tsx`
+- Read: `front/src/components/tasks/TaskSummaryPanel.tsx`
+- Read: `front/src/pages/files/FilesPage.tsx`
+- Read: `front/src/admin/storage-policies-list.tsx`
+
+- [ ] **Step 1: Write the document header and replacement principles**
+
+```md
+# 前端组件选型与替换指南
+
+## 1. 文档目标
+
+这份文档用于回答两个问题：
+
+1. 当前 `front/` 已经有哪些前端基础组件与页面壳
+2. 哪些“不完善但不承载业务规则”的前端组件适合用成熟开源组件替换
+```
+
+- [ ] **Step 2: Add the current in-repo component baseline**
+
+```md
+## 3. 当前项目已有的核心基础组件
+
+### 3.1 应用外壳
+
+- `front/src/components/layout/Layout.tsx`
+- `front/src/mobile-components/MobileLayout.tsx`
+- `front/src/admin/AdminLayout.tsx`
+
+### 3.2 全局状态与共用组件
+
+- `front/src/components/ThemeProvider.tsx`
+- `front/src/components/ThemeToggle.tsx`
+- `front/src/components/upload/UploadCenter.tsx`
+- `front/src/components/tasks/TaskSummaryPanel.tsx`
+- `front/src/components/media/FileThumbnail.tsx`
+```
+
+- [ ] **Step 3: Add the recommended OSS component matrix**
+
+```md
+### 4.1 `@tanstack/react-table`
+- 适合替换管理台和列表型页面表格
+
+### 4.3 `react-dropzone`
+- 适合替换网盘和快传的文件选择入口
+
+### 4.4 `react-arborist`
+- 适合替换网盘目录树
+
+### 4.7 `recharts`
+- 适合替换后台总览图表层
+
+### 4.8 `vidstack`
+- 适合后续文件预览里的音视频播放器
+```
+
+- [ ] **Step 4: Save the component guide**
+
+Run:
+
+```bash
+sed -n '1,260p' docs/frontend-component-guide.md
+```
+
+Expected: the document contains the current component baseline, replacement principles, recommended libraries, and adoption priorities.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add docs/frontend-component-guide.md
+git commit -m "docs: add frontend component selection guide"
+```
+
+### Task 3: Write The Frontend Page Orchestration Guide
+
+**Files:**
+- Create: `docs/frontend-page-orchestration.md`
+- Read: `front/src/pages/Login.tsx`
+- Read: `front/src/pages/Overview.tsx`
+- Read: `front/src/pages/files/FilesPage.tsx`
+- Read: `front/src/pages/Tasks.tsx`
+- Read: `front/src/pages/Shares.tsx`
+- Read: `front/src/pages/RecycleBin.tsx`
+- Read: `front/src/transfer/pages/TransferPage.tsx`
+- Read: `front/src/pages/FileShare.tsx`
+- Read: `front/src/admin/*.tsx`
+- Read: `front/src/lib/admin-users.ts`
+- Read: `front/src/lib/admin-storage-policies.ts`
+
+- [ ] **Step 1: Write the route inventory and shell sections**
+
+```md
+# 前端页面编排文档
+
+## 2. 路由总表
+
+### 2.1 公共页面
+- `/login`
+- `/share/:token`
+
+### 2.2 主应用页面
+- `/overview`
+- `/files`
+- `/tasks`
+- `/shares`
+- `/recycle-bin`
+- `/transfer`
+```
+
+- [ ] **Step 2: Add every user-facing page with regions and buttons**
+
+```md
+## 6.2 网盘页 `/files`
+
+### 顶部工具区按钮
+- `上传文件`
+- `新建文件夹`
+- `刷新`
+
+### 右侧文件详情栏按钮
+- `下载`
+- `创建分享`
+- `重命名`
+- `移动`
+- `删除`
+```
+
+- [ ] **Step 3: Add every admin page and enumerate every current setting item**
+
+```md
+## 7.4 存储策略 `/admin/storage-policies`
+
+### 弹窗表单字段
+- `策略名称`
+- `驱动协议`
+- `端点地址`
+- `桶名称`
+- `对象大小上限（字节）`
+
+### 布尔设置项
+- `私有桶`
+- `启用`
+- `直传`
+- `分片上传`
+- `签名下载`
+- `代理下载`
+- `需要 CORS`
+- `内网端点`
+```
+
+- [ ] **Step 4: Explicitly call out placeholder admin pages and API-backed but unexposed settings**
+
+```md
+### 当前前端未暴露但 API 已存在的管理项
+- `updateUserMaxUploadSize`
+- `resetUserPassword`
+```
+
+- [ ] **Step 5: Save the page orchestration guide**
+
+Run:
+
+```bash
+sed -n '1,320p' docs/frontend-page-orchestration.md
+```
+
+Expected: the document lists every current page, every visible button, and every current admin setting item, while marking placeholder admin pages clearly.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add docs/frontend-page-orchestration.md
+git commit -m "docs: add frontend page orchestration guide"
+```
+
+### Task 4: Self-Review And Repo Validation
+
+**Files:**
+- Modify: `docs/frontend-component-guide.md`
+- Modify: `docs/frontend-page-orchestration.md`
+- Modify: `docs/superpowers/plans/2026-04-12-frontend-docs.md`
+
+- [ ] **Step 1: Verify the docs mention real files and only real commands**
+
+Run:
+
+```bash
+rg -n "npm test|npm typecheck|TODO|TBD|implement later" docs/frontend-component-guide.md docs/frontend-page-orchestration.md docs/superpowers/plans/2026-04-12-frontend-docs.md
+```
+
+Expected: no matches.
+
+- [ ] **Step 2: Verify admin settings coverage against the real code**
+
+Run:
+
+```bash
+sed -n '1,420p' front/src/admin/storage-policies-list.tsx
+sed -n '1,360p' front/src/admin/users-list.tsx
+sed -n '1,360p' front/src/admin/files-list.tsx
+```
+
+Expected: every visible control in those files is represented in `docs/frontend-page-orchestration.md`.
+
+- [ ] **Step 3: Verify git sees the new docs**
+
+Run:
+
+```bash
+git status --short
+```
+
+Expected:
+
+```text
+A  docs/frontend-component-guide.md
+A  docs/frontend-page-orchestration.md
+A  docs/superpowers/plans/2026-04-12-frontend-docs.md
+```
+
+- [ ] **Step 4: Commit the final docs set**
+
+```bash
+git add docs/frontend-component-guide.md docs/frontend-page-orchestration.md docs/superpowers/plans/2026-04-12-frontend-docs.md
+git commit -m "docs: add frontend documentation set"
+```