Implement coordinated frontend and backend updates
This commit is contained in:
yoyuzh
141
docs/superpowers/plans/2026-04-12-admin-oss-refactor.md
Normal file
141
docs/superpowers/plans/2026-04-12-admin-oss-refactor.md
Normal file
@@ -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.
|
||||
335
docs/superpowers/plans/2026-04-12-frontend-docs.md
Normal file
335
docs/superpowers/plans/2026-04-12-frontend-docs.md
Normal file
@@ -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"
|
||||
```
|
||||
Reference in New Issue
Block a user