my_site/docs/superpowers/plans/2026-04-12-admin-oss-refactor.md

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

• Step 1: Add react-hook-form to the frontend

Run:

cd front && npm install react-hook-form

Expected: front/package.json and front/package-lock.json include react-hook-form.

• Step 2: Migrate 系统设置 editable sections to react-hook-form

Target:

- 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.

• Step 3: Migrate 用户策略 editor panel to react-hook-form

Target:

- role
- storageQuotaBytes
- maxUploadSizeBytes
- manualPassword

Expected: replace manual draft state and ad hoc validation with form-driven state and explicit submit handlers.

• Step 4: Verify Batch 1

Run:

cd front && npm run lint
cd front && npm run build

Expected: both commands pass.

Task 9: Replace Hand-Styled Admin Search And Filter Inputs

Files:

• Modify: front/src/admin/users-list.tsx

• Modify: front/src/admin/files-list.tsx

• Modify: front/src/admin/shares.tsx

• Modify: front/src/admin/fileblobs.tsx

• Modify: front/src/admin/tasks.tsx

• Modify: front/src/admin/audits.tsx

• Step 1: Replace search and filter inputs with the shared admin input

Target:

- 用户策略: 搜索框
- 文件治理: 文件名 / 所属用户
- 分享治理: 用户 / 文件名 / Token
- 对象治理: 用户 / 策略 ID / 对象键
- 任务监控: 多个筛选输入
- 审计日志: actor / action / targetType / targetId

• Step 2: Verify Batch 9

Run:

cd front && npm run lint
cd front && npm run build

Expected: both commands pass.

Task 8: Replace Hand-Styled Admin Text And Number Inputs

Files:

• Add: front/src/components/admin/AdminInput.tsx
• Modify: front/src/admin/users-list.tsx

Current execution scope for this batch is limited to users-list.tsx.

• Step 1: Add reusable admin input primitives

Expected:

- expose shared admin text/number input styling
- support form registration and controlled usage
- keep current focus, disabled, and validation affordances

• Step 2: Replace editable inputs in configuration-heavy pages

Target:

- 用户策略: 存储配额 / 最大上传限制 / 手动密码

• Step 3: Verify Batch 8

Run:

cd front && npm run lint
cd front && npm run build

Expected: both commands pass.

Task 6: Replace Hand-Rolled Admin Select Controls

Files:

• Modify: front/package.json

• Modify: front/package-lock.json

• Add: front/src/components/admin/AdminSelect.tsx

• Modify: front/src/admin/shares.tsx

• Modify: front/src/admin/fileblobs.tsx

• Modify: front/src/admin/tasks.tsx

• Modify: front/src/admin/storage-policies-list.tsx

• Step 1: Add a reusable admin select wrapper based on Radix Select

Expected:

- install an OSS select dependency
- expose a shared admin-styled select wrapper
- support placeholder, controlled value, and option groups used by admin pages

• Step 2: Replace filter selects in governance pages

Target:

- 分享治理: 密码保护 / 过期状态
- 对象治理: 实体类型
- 任务监控: 每页条数

• Step 3: Replace modal selects in storage policies

Target:

- 新建 / 编辑策略: 驱动协议
- 发起迁移: 目标策略选择

• Step 4: Verify Batch 6

Run:

cd front && npm run lint
cd front && npm run build

Expected: both commands pass.

Task 7: Replace The Remaining Admin Form Select

Files:

• Modify: front/src/admin/users-list.tsx

• Step 1: Replace the user role field with the shared admin select

Target:

- 用户策略: role 字段
- 保持 react-hook-form 校验和提交逻辑不变

• Step 2: Verify Batch 7

Run:

cd front && npm run lint
cd front && npm run build

Expected: both commands pass.

Task 5: Replace Hand-Rolled Admin Modal Shells

Files:

• Modify: front/package.json

• Modify: front/package-lock.json

• Add: front/src/components/admin/AdminDialog.tsx

• Modify: front/src/admin/storage-policies-list.tsx

• Modify: front/src/admin/users-list.tsx

• Step 1: Add a reusable admin dialog wrapper based on Radix Dialog

Expected:

- install an OSS dialog dependency
- expose a shared admin-styled modal/sheet wrapper
- support centered modal and right-side panel layouts

• Step 2: Replace storage policy form and migration overlays

Target:

- 新建 / 编辑策略弹层
- 发起迁移弹层

• Step 3: Replace the user strategy editor shell

Target:

- 用对话框 / 侧栏承载用户策略编辑
- 保留当前表单与快捷操作逻辑

• Step 4: Verify Batch 5

Run:

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

• Step 1: Add @tanstack/react-table to the frontend

Run:

cd front && npm install @tanstack/react-table

Expected: front/package.json and front/package-lock.json include @tanstack/react-table.

• Step 2: Migrate 用户策略 table rendering to TanStack

Expected:

- columns defined declaratively
- row rendering stays visually consistent
- action cells preserve current behavior

• Step 3: Migrate 存储策略 table rendering to TanStack

Expected:

- existing columns preserved
- no backend contract changes
- current modal / action flows preserved

• Step 4: Verify Batch 2

Run:

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

• Step 1: Migrate 分享治理 table rendering to TanStack

Expected:

- existing columns preserved
- no backend contract changes
- copy / open / delete actions preserved
- filter form and empty state preserved

• Step 2: Verify Batch 3

Run:

cd front && npm run lint
cd front && npm run build

Expected: both commands pass.

Task 4: Replace Native Admin Alerts And Confirms

Files:

• Modify: front/package.json

• Modify: front/package-lock.json

• Add: front/src/components/admin/AdminAlertDialog.tsx

• Modify: front/src/admin/settings.tsx

• Modify: front/src/admin/shares.tsx

• Modify: front/src/admin/files-list.tsx

• Modify: front/src/admin/filesystem.tsx

• Modify: front/src/admin/fileblobs.tsx

• Modify: front/src/admin/audits.tsx

• Step 1: Add a reusable admin alert dialog wrapper

Expected:

- install an OSS dialog dependency
- expose a shared admin-styled alert dialog wrapper
- keep current Tailwind visual system intact

• Step 2: Replace destructive confirm actions with in-app dialogs

Target:

- 系统设置: 轮换邀请码
- 分享治理: 删除分享
- 文件治理: 彻底删除

• Step 3: Replace remaining admin alert feedback with page-level notices

Target:

- 文件系统: 复制失败
- 对象实体: 复制失败
- 审计日志: 复制失败
- 分享治理: 复制成功 / 失败

• Step 4: Verify Batch 4

Run:

cd front && npm run lint
cd front && npm run build

Expected: both commands pass.