WuYongJie/flnxi-Wu

Fork 0

WuYongJie 90af4a20fc

CI Check / check (push) Has been cancelled

Details

feat: 模板管理整合 - 上传面板模板化、动态字段渲染、分类管理模板化

2025-11-22 18:15:23 +08:00

24 KiB

Raw Blame History

Admin 页面优化建议和问题修复记录

✅ 已完成的修复

1. 类型定义统一化

✅ 创建了 types.ts 统一管理所有类型定义
✅ 移除了 page.tsx 中的重复类型定义（User, Material, Category, Scene, Platform, Invitation, UserTreeNode, DepartmentNode, DepartmentUserGrouping）
✅ 移除了 TemplateManager.tsx 中的重复 ToastFn 定义
✅ 添加了 AdminTab 类型统一管理 Tab 类型
✅ 添加了 DashboardData 接口用于监控仪表板数据
✅ 修复了 TemplateManager.tsx 中 DragHoverState 的类型错误（fallback 对象的 position 属性需要明确类型为 'before' | 'after'）
✅ 修复了 TemplateFieldsEditor.tsx 中 onFieldDragOver 回调签名，添加缺失的 surface 参数
✅ 修复了 UsersTab.tsx 中 showTransferButton 在使用前未定义的问题，将其改为 useMemo 并移到使用前定义

2. UI 样式统一化 - 三层架构重构

✅ 创建了三层架构的样式系统：
- 基础层：lib/ui-styles-base.ts - 包含布局、大小、动画等非颜色样式
- 颜色层：lib/ui-theme-colors-light.ts / dark.ts - 仅包含颜色配置
- 组合层：lib/ui-styles-composer.ts - 自动组合基础样式和颜色主题
- 导出层：lib/ui-styles-light.ts / dark.ts - 最终导出的样式（由组合器生成）
✅ 创建了 lib/hooks/useThemeStyles.ts - 主题感知的样式 Hook
- useThemeStyles() - 根据当前主题自动返回对应的样式配置
- useTheme() - 获取当前主题状态
✅ 保持了向后兼容性：
- 原有的 lib/ui-styles.ts 仍然保留（包含 dark: 前缀的样式）
- 新组件推荐使用 useThemeStyles() Hook
- 旧组件可以继续使用原有导入，逐步迁移

核心优势：

✅ 统一视觉设计：修改布局、大小、动画时，只需修改 ui-styles-base.ts 一处，浅色和深色模式自动同步
✅ 独立颜色适配：颜色配置完全分离，可以独立调整浅色或深色模式的颜色
✅ 易于维护：清晰的职责分离，修改时不会遗漏或出错
✅ 类型安全：TypeScript 类型检查确保配置正确

修改指南：

修改布局/大小/动画 → 修改 lib/ui-styles-base.ts（一处修改，两套主题自动同步）
修改浅色模式颜色 → 修改 lib/ui-theme-colors-light.ts
修改深色模式颜色 → 修改 lib/ui-theme-colors-dark.ts

架构文档： 详见 docs/guides/UI_STYLES_ARCHITECTURE.md

使用示例：

'use client'
import { useThemeStyles } from '@/lib/ui-styles'

export default function MyComponent() {
  const styles = useThemeStyles()
  
  return (
    <div className={styles.cardStyles.base}>
      <button className={styles.buttonStyles.primary}>点击</button>
    </div>
  )
}

迁移进度：

✅ 基础 UI 组件已迁移：
- LoadingState.tsx - 使用 useThemeStyles() 和 useTheme()
- ErrorState.tsx - 使用 useThemeStyles() 和 useTheme()
- EmptyState.tsx - 使用 useTheme() 根据主题选择文字颜色
✅ Tab 组件迁移（全部完成）：
- MaterialsTab.tsx - 完全迁移到新样式系统，移除了所有 dark: 前缀
- CategoriesTab.tsx - 完全迁移到新样式系统，移除了所有 dark: 前缀
- InvitationsTab.tsx - 完全迁移到新样式系统，移除了所有 dark: 前缀
- DepartmentsTab.tsx - 完全迁移到新样式系统，移除了所有 dark: 前缀
- UsersTab.tsx - 完全迁移到新样式系统，移除了所有 dark: 前缀
- MonitorTab.tsx - 完全迁移到新样式系统，移除了所有 dark: 前缀
✅ 其他组件迁移（已完成）：
- TemplateManager.tsx - 完全迁移到新样式系统，移除了所有 dark: 前缀
- page.tsx - 完全迁移到新样式系统，移除了所有 dark: 前缀
- AppearanceSettingsPanel.tsx - 完全迁移到新样式系统，移除了所有 dark: 前缀

3. UI 样式统一化（历史）

✅ 修复了 card-apple 类名，改为使用 cardStyles.base
✅ 统一了边框颜色：border-gray-* → border-slate-*（与设计系统一致）
✅ Admin 目录中的 text-gray-* / bg-gray-* / border-gray-* 类已全部替换为 slate 系列，浅色与深色模式的视觉基调保持一致

🔍 发现的问题和建议

1. 代码结构问题

问题：`page.tsx` 文件过大（3795 行）

影响：

难以维护和调试
代码复用性差
性能可能受影响（组件过大）

建议：

✅ 已创建 MonitorTab.tsx 组件
✅ 已拆分 UsersTab.tsx（用户管理）
✅ 已拆分 DepartmentsTab.tsx（架构管理）
⏳ 继续拆分其他 Tab 组件：
- ✅ CategoriesTab.tsx - 分类管理
- ✅ InvitationsTab.tsx - 邀请管理
- ✅ MaterialsTab.tsx - 素材管理
- ✅ TemplateManager.tsx：已提取 Header / Built-in Grid / Custom Templates 等 UI 子组件，为后续拆出编辑器面板铺路
- ✅ TemplateManager 编辑弹窗：基础信息、预设选择、JSON 高级配置抽象为 TemplateBasicsForm + TemplateAdvancedConfigPanel，编辑逻辑逐步下沉
- ✅ TemplateManager 字段区、底部操作：TemplateFieldsEditor 承载字段配置 + 拖拽 UI，TemplateEditorFooter 统一处理提示与按钮状态
- ✅ TemplateManager 预览面板：TemplatePreviewPanel 独立封装上传预览 UI 与 DnD 状态，主组件仅处理回调

问题：状态管理分散

当前状态：

每个 Tab 的状态都在主组件中管理
状态之间可能存在不必要的依赖

建议：

✅ UsersTab / DepartmentsTab 已将本地 UI 状态与交互逻辑下沉到各自组件
只保留共享状态在主组件（如 activeTab, toast）

4. UI 统一性问题

问题：部分地方仍使用旧的样式类

发现：

✅ 基础文字/背景/边框色已统一为 slate 系列（含浅色与深色）
✅ 深浅色样式已分离为两套独立配置，解决适配问题
⏳ 部分按钮样式未使用 buttonStyles.*（建议逐步迁移到 useThemeStyles()）
⏳ 部分输入框仍未使用 inputStyles.*（建议逐步迁移到 useThemeStyles()）

建议：

全局搜索替换 gray- → slate-（在 admin 目录中）
⏳ 确保所有按钮都使用 buttonStyles.*（InvitationsTab、CategoriesTab、MaterialsTab、UsersTab、DepartmentsTab ✅；其它 Tab 持续中）
⏳ 确保所有输入框都使用 inputStyles.*（DepartmentsTab 重命名输入已调整）
✅ 补充 buttonStyles.success 以覆盖绿色状态按钮场景
✅ 新增 buttonModifiers（compact / compactXs / icon / block）辅助类，方便统一尺寸与布局
✅ MaterialsTab 搜索操作、卡片操作按钮已统一到 buttonStyles + buttonModifiers，并将 <img> 替换为 next/image
✅ UsersTab 搜索清空与用户操作按钮统一引用 buttonStyles + buttonModifiers
✅ DepartmentsTab 搜索清空、操作按钮接入 buttonStyles + buttonModifiers; 新增 inputModifiers 并应用到重命名输入
✅ TemplateManager 顶部搜索、预制/自定义模板动作按钮接入设计系统；新增 buttonModifiers.pill
✅ TemplateManager 基础信息 / JSON 配置表单统一使用 inputStyles + inputModifiers，并抽离复用组件
✅ TemplateManager 字段配置 / 底部操作按钮接入设计系统（字段编辑区统一控件样式，弹窗底部按钮使用 buttonStyles.secondary/primary + buttonModifiers.compact）
✅ TemplateManager 预览面板 UI 与拖拽交互抽象为 TemplatePreviewPanel，复用设计系统控件
✅ 清理 TemplatePreviewPanel 与 page.tsx 残留的 gray-* 渐变/分隔线/焦点样式，统一替换为 slate-* 调色
✅ page.tsx 移除历史 Invitations UI、状态与数据请求，统一由 InvitationsTab 自主管理
✅ page.tsx 移除重复的监控仪表板代码，统一使用 MonitorTab 组件

3. 逻辑优化建议

问题：数据获取逻辑重复

当前：

✅ useDataFetch Hook 已抽离 loadUsersData / fetchDepartments / fetchTabData，主页面只关心状态驱动
⏳ 更进一步的缓存（React Query / SWR）尚未落地

建议：

后续可引入 React Query 或 SWR 进行跨 Tab 缓存与自动刷新
或者在各 Tab 内使用独立数据源，减少主页面耦合

问题：权限检查分散

当前：

权限检查在多个地方重复
canManageUser 等函数在主组件中定义

建议：

✅ 已创建 usePermissions Hook，统一 canManageUser / 超管判定等权限逻辑
后续可将其他权限相关逻辑继续提取到工具函数或 Hook 中

4. 性能优化建议

问题：大量 useMemo 和 useCallback

当前：

主组件中有很多 useMemo 和 useCallback
某些计算可能不需要缓存

建议：

✅ 审查了每个 useMemo 和 useCallback 的必要性
- departmentCollator - 使用 useMemo 合理（创建 Intl.Collator 对象）
- userLookup - 使用 useMemo 合理（从数组创建 Map，避免重复计算）
- fetchData, renameDepartment, createDepartment, deleteDepartment, findDepartmentManagers - 使用 useCallback 合理（作为 props 传递给子组件）
✅ 创建了 _utils/api.ts 统一处理 API 错误，减少了重复的错误处理代码
⏳ 将复杂的计算逻辑移到子组件中
✅ 使用 React.memo 优化子组件渲染（UserTree 已实现）

问题：模态框状态管理

当前：

✅ 分类/场景/平台新增、素材编辑相关模态已移交给各自 Tab 组件，page.tsx 清理全部遗留状态与 UI
✅ 新增 useModalState Hook（app/admin/_hooks/useModalState.ts），统一管理用户编辑/转移最高权限模态的开合与状态，移除散落的 showPasswordModal、editingUser 布尔控制
⏳ 用户信息编辑、转移最高权限 UI 仍托管在 page.tsx，可进一步下放到 UsersTab

建议：

为剩余模态编写统一的模态管理 hook
或者继续将模态迁移到对应的 Tab/组件内部

5. 代码质量建议

建议：添加错误边界

✅ 新增 TabErrorBoundary 组件（app/admin/_components/TabErrorBoundary.tsx），并在 page.tsx 为各个 Tab 包裹，提供统一的 fallback + 重试
⏳ 可进一步将 TabErrorBoundary 提炼到全局组件库，或为特定 Tab 定制更详细的错误提示

建议：添加加载状态统一管理

✅ 创建统一的加载状态组件（LoadingState、ErrorState、EmptyState）
✅ 统一错误提示样式，替换所有重复的加载/错误 UI
✅ MonitorTab、MaterialsTab、page.tsx 已统一使用新的状态组件

建议：提取公共逻辑

✅ 创建 hooks/useToast.ts 统一管理 Toast（page.tsx 已接入）
✅ 创建 hooks/useDataFetch.ts 统一管理数据获取
✅ 创建 _utils/api.ts 统一处理 API 错误响应和类型安全
- parseErrorResponse() - 安全解析错误响应
- parseSuccessResponse() - 安全解析成功响应
- apiRequest() - 统一的 API 请求函数
- getErrorMessage() - 获取错误消息的辅助函数
✅ 提取表单验证逻辑到工具函数
- 创建了 _utils/validators.ts 统一管理表单验证
- validateNotEmpty() - 验证非空字符串
- validateDepartmentName() - 验证部门名称
- validateEmail() - 验证邮箱格式
- validateFieldKey() - 验证字段键名（标识符规则）
- validateUniqueKeys() - 验证字段键名唯一性
- validateTemplateName() - 验证模板名称
- validatePassword() - 验证密码
- combineValidationResults() - 组合多个验证结果
- page.tsx 和 TemplateManager.tsx 已使用新的验证函数
✅ 创建格式化工具函数
- 创建了 _utils/formatters.ts 统一管理格式化逻辑
- formatDateTime() - 格式化日期时间（完整格式）
- formatDate() - 格式化日期（仅日期部分）
- formatTime() - 格式化时间（仅时间部分）
- formatDateTimeShort() - 格式化日期时间（简短格式）
- formatDateTimeLocale() - 使用本地化格式格式化日期时间
- formatRelativeTime() - 格式化相对时间
- formatFileSize() - 格式化文件大小
- formatNumber() - 格式化数字（添加千位分隔符）
- formatPercent() - 格式化百分比
- MonitorTab.tsx、InvitationsTab.tsx、UserEditModal.tsx、TemplateManager.tsx 已使用新的格式化函数
✅ 提取用户操作逻辑到 Hook
- 创建了 _hooks/useUserOperations.ts 统一管理用户相关操作
- updateUser() - 更新用户信息
- deleteUser() - 删除用户
- toggleDownload() - 切换下载权限
- toggleActive() - 切换激活状态
- setRole() - 设置用户角色
- transferSuperAdmin() - 转移最高权限
- page.tsx 已使用新的 Hook，代码更简洁
✅ 提取部门操作逻辑到 Hook
- 创建了 _hooks/useDepartmentOperations.ts 统一管理部门相关操作
- createDepartment() - 创建部门
- deleteDepartment() - 删除部门
- renameDepartment() - 重命名部门
- page.tsx 已使用新的 Hook，移除了重复的部门操作代码，代码更简洁
- 创建了 _utils/validators.ts 统一管理表单验证
- validateNotEmpty() - 验证非空字符串
- validateDepartmentName() - 验证部门名称
- validateEmail() - 验证邮箱格式
- validateFieldKey() - 验证字段键名（标识符规则）
- validateUniqueKeys() - 验证字段键名唯一性
- validateTemplateName() - 验证模板名称
- validatePassword() - 验证密码
- combineValidationResults() - 组合多个验证结果
- page.tsx 和 TemplateManager.tsx 已使用新的验证函数

6. 类型安全建议

问题：使用 `any` 类型

发现：

session?.user as any 多处使用
dashboardData 使用 any 类型

建议：

✅ 定义完整的 Session 类型（SessionUser 接口）
✅ 使用 DashboardData 类型替代 any（已在 types.ts 中定义）
✅ 添加类型断言函数（getSessionUser）
✅ 定义 API 响应类型（ApiErrorResponse, ApiSuccessResponse）
✅ 移除 page.tsx 中所有 as any 使用
✅ 更新 AppearanceSettingsPanel 使用 SessionUser 类型

7. 可访问性建议

建议：添加 ARIA 标签

✅ 为 Tab 导航添加了完整的 ARIA 标签（role="tablist", role="tab", role="tabpanel"）
✅ 为所有 Tab 按钮添加了 aria-selected, aria-controls, id 属性
✅ 为返回主页按钮和关闭 Toast 按钮添加了 aria-label
✅ 为 Toast 通知添加了 role="status" 和 aria-live="polite"
✅ 添加了键盘导航支持（Enter 和 Space 键）
✅ 添加了焦点样式（focus:outline-none focus:ring-2）
⏳ 继续为其他交互元素添加 ARIA 标签和键盘支持

8. 测试建议

建议：添加单元测试

为工具函数添加测试
为权限检查逻辑添加测试
为数据转换逻辑添加测试

📋 下一步行动计划

注意：详细的优化计划和优先级已移至 优化计划与优先级.md，请参考该文档进行后续开发。

当前阶段：基础组件与UI统一

优先级 1：基础组件与UI统一（核心基础设施）

✅ 创建统一弹窗组件（components/ui/Modal.tsx）
- ✅ 使用三层架构设计（基础层、颜色层、组合层）
- ✅ 提供 useModal Hook（hooks/useModal.ts）
- ✅ 支持多种尺寸（small, medium, large, xlarge, fullscreen）
- ✅ 支持ESC键关闭、点击遮罩关闭
- ✅ 完整的ARIA标签和键盘导航支持
- ✅ 替换所有浏览器原生弹窗（confirm/alert/prompt）
- ✅ 创建了 ConfirmDialog、AlertDialog、PromptDialog 组件
- ✅ 创建了 DialogProvider 和 useDialog Hook
- ✅ 替换了所有 admin 组件、首页、分享页面中的原生弹窗
✅ 素材预览面板统一
- ✅ 创建了 MaterialPreviewModal 组件
- ✅ 使用统一弹窗组件
- ✅ 统一退出逻辑（ESC键、点击遮罩、关闭按钮）
- ✅ 使用三层架构样式系统
✅ 首页素材展示响应式优化
- ✅ 修复卡片比例固定问题（使用 aspect-[3/4] 替代固定高度 h-[400px]）
- ✅ 添加容器边距（px-4 sm:px-6 lg:px-8）避免卡片贴到浏览器边界
- ✅ 使用三层架构样式系统（useThemeStyles() 和 cardStyles.base）
- ✅ 优化图片 sizes 属性，提升响应式性能
- ✅ 统一使用 slate 系列颜色，确保深浅色模式适配
✅ 首页UI统一到三层架构（完全完成）
- ✅ 迁移了主要按钮样式（上传按钮、筛选按钮）
- ✅ 迁移了搜索输入框样式
- ✅ 迁移了筛选弹窗中的所有按钮样式
- ✅ 迁移了筛选弹窗容器样式
- ✅ 迁移了筛选弹窗关闭按钮样式
- ✅ 将所有 gray 系列替换为 slate 系列
- ✅ 统一文本颜色（text-gray-* → text-slate-*）
- ✅ 统一背景颜色（bg-gray-* → bg-slate-*）
- ✅ 统一边框颜色（border-gray-* → border-slate-*）
- ✅ 统一分页按钮样式
- ✅ 统一分享弹窗样式
- ✅ 使用 Tag 组件替换原有的标签样式
✅ 通用组件库创建
- ✅ 创建了 Badge 组件（components/ui/Badge.tsx）
  - 支持多种变体（primary、success、warning、danger）
  - 支持多种尺寸（sm、md、lg）
  - 使用三层架构样式系统
- ✅ 创建了 Tag 组件（components/ui/Tag.tsx）
  - 支持多种颜色（blue、green、orange、purple、indigo、pink、cyan）
  - 支持多种尺寸（sm、md、lg）
  - 支持点击事件
  - 已在首页素材卡片中应用
- ✅ 创建了 Button 组件（components/ui/Button.tsx）
  - 支持多种变体（primary、secondary、ghost、danger、success）
  - 支持多种尺寸（sm、md、lg）
  - 支持加载状态（loading）
  - 支持全宽（fullWidth）
  - 使用 forwardRef 支持 ref 传递
- ✅ 创建了 Input 组件（components/ui/Input.tsx）
  - 支持错误状态（error）
  - 支持多种尺寸（sm、md、lg）
  - 支持全宽（fullWidth）
  - 使用 forwardRef 支持 ref 传递
- ✅ 创建了 Card 组件（components/ui/Card.tsx）
  - 支持多种变体（base、hover、large、flat、rainbow、glass、neon）
  - 支持自定义padding
  - 使用三层架构样式系统
- ✅ 创建了 Avatar 组件（components/ui/Avatar.tsx）
  - 支持图片头像和文字头像（显示用户名首字母）
  - 支持多种尺寸（xs、sm、md、lg、xl）
  - 支持点击事件和键盘导航
  - 使用三层架构样式系统
⏳ 深浅色主题适配优化（1.6）- 进行中
- ✅ 为所有新创建和重构的文件添加了文件头注释
  - Tab组件：UsersTab、DepartmentsTab、CategoriesTab、InvitationsTab、MaterialsTab、MonitorTab
  - Hook文件：usePermissions、useDashboardData、useModalState、useToast、useDataFetch、useUserOperations、useDepartmentOperations
  - 工具函数：api.ts、formatters.ts、departmentTree.ts
  - UI组件：Modal、ConfirmDialog、AlertDialog、PromptDialog、DialogProvider、Button、Input、Card、Avatar、Badge、Tag
- ✅ Header组件迁移到三层架构
  - 使用 useThemeStyles() Hook
  - 使用统一的 Avatar 组件替换自定义头像实现
  - 下拉菜单使用 cardStyles.base 统一样式
  - 移除了所有 dark:bg-gray 等直接样式
  - 移除了不再使用的 getInitials 函数
- ✅ ChangePasswordModal迁移到统一组件
  - 使用统一的 Modal 组件替换自定义弹窗实现
  - 使用统一的 Input 组件替换原生input
  - 使用统一的 Button 组件替换原生button
  - 使用三层架构样式系统
  - 添加了文件头注释
- ✅ DanmakuWidget迁移到三层架构
  - 使用统一的 Input 和 Button 组件
  - 使用 useThemeStyles() Hook
  - 优化样式（gray → slate）
  - 添加文件头注释
- ✅ AIChatWidget优化
  - 添加文件头注释
  - 优化关键样式（gray → slate）
  - 使用 useThemeStyles() Hook
- ✅ RankingPanel迁移到三层架构
  - 添加文件头注释
  - 使用 useThemeStyles() Hook
  - 优化样式（gray → slate）
- ✅ 分享页面和编辑页面优化
  - app/share/[id]/page.tsx 添加文件头注释，优化样式（gray → slate）
  - app/edit/[id]/page.tsx 添加文件头注释，优化样式（gray → slate）
  - 使用 useThemeStyles() Hook 和 cardStyles.base
- ✅ UploadModal基础样式优化
  - 添加文件头注释
  - 导入 useThemeStyles 和统一组件
  - 所有 gray 系列替换为 slate 系列
  - 主要容器使用 cardStyles.base
  - 注意：由于后续会进行模板管理整合（需求14），暂不做深度重构
- ✅ 低饱和度炫彩元素设计（1.7）
  - 在颜色层添加了 accent 配置（pink、purple、blue、cyan、emerald、orange、rainbow）
  - 每个颜色包含 bg、text、border、hover 四个属性
  - 浅色模式使用低饱和度背景（如 bg-pink-50）
  - 深色模式使用低透明度背景（如 bg-pink-900/20）
  - 在组合器中添加 accentStyles 导出
  - 更新 Tag 组件使用新的 accentStyles，所有颜色都使用低饱和度炫彩元素

优先级 2：数据一致性与核心功能 5. ✅ 用户信息修改后同步素材信息

✅ API 端已实现：当用户名变化时，使用事务同步更新该用户所有素材的 authorName
✅ 前端已处理：useUserOperations.updateUser 处理 materialsUpdated 返回值并显示提示
✅ 使用事务确保数据一致性
✅ 错误处理和回滚机制已实现

✅ 模板管理整合到上传和分类
- ✅ 创建公共 API 端点 /api/upload-templates 获取启用的模板列表（不需要管理员权限）
- ✅ 修改 UploadModal：将"素材类型"改为"素材模板"，从 API 拉取模板列表
- ✅ 实现动态字段渲染：选择模板后根据模板字段动态生成表单（支持 text、textarea、number、select、checkbox、radio、date 等类型）
- ✅ 根据字段的 layoutWidth 属性支持半行/整行布局
- ✅ 修改上传逻辑：提交模板ID和字段值到数据库（存储在 metadata 和 templateId 字段）
- ✅ 创建模板分类 API /api/template-categories：从模板管理中提取所有 visibleOnHomeFilter=true 且 type='select' 的字段选项
- ✅ 修改分类管理界面：显示从模板中提取的分类选项，保留原有分类管理用于向后兼容
- ⏳ 模板管理面板逻辑检查（待后续完善）
- 将模板系统串起前后端

详细计划：请查看 优化计划与优先级.md

📝 代码规范建议

命名规范

组件文件：PascalCase（如 UsersTab.tsx）
Hook 文件：camelCase with use prefix（如 usePermissions.ts）
工具函数：camelCase（如 formatDate.ts）
类型文件：types.ts 或 types/index.ts

文件组织

app/admin/
├── _components/
│   ├── types.ts              # 类型定义
│   ├── MonitorTab.tsx        # 监控仪表板
│   ├── UsersTab.tsx          # 用户管理
│   ├── DepartmentsTab.tsx    # 架构管理
│   ├── CategoriesTab.tsx     # 分类管理
│   ├── InvitationsTab.tsx    # 邀请管理
│   ├── MaterialsTab.tsx      # 素材管理
│   ├── TemplateManager.tsx   # 模板管理
│   └── AppearanceSettingsPanel.tsx
├── _hooks/                   # 自定义 hooks
│   ├── useToast.ts
│   ├── usePermissions.ts
│   └── useDataFetch.ts
├── _utils/                   # 工具函数
│   ├── validators.ts
│   └── formatters.ts
└── page.tsx                  # 主页面（简化后）

🎯 最终目标

代码可维护性：每个组件职责单一，易于理解和修改
代码复用性：公共逻辑提取到 hooks 和工具函数
类型安全：完整的 TypeScript 类型定义，减少运行时错误
UI 一致性：统一使用设计系统，确保视觉一致性
性能优化：减少不必要的渲染，优化数据获取
用户体验：流畅的交互，清晰的错误提示

24 KiB Raw Blame History Unescape Escape

Admin 页面优化建议和问题修复记录

✅ 已完成的修复

1. 类型定义统一化

2. UI 样式统一化 - 三层架构重构

3. UI 样式统一化（历史）

🔍 发现的问题和建议

1. 代码结构问题

问题：page.tsx 文件过大（3795 行）

问题：状态管理分散

4. UI 统一性问题

问题：部分地方仍使用旧的样式类

3. 逻辑优化建议

问题：数据获取逻辑重复

问题：权限检查分散

4. 性能优化建议

问题：大量 useMemo 和 useCallback

问题：模态框状态管理

5. 代码质量建议

建议：添加错误边界

建议：添加加载状态统一管理

建议：提取公共逻辑

6. 类型安全建议

问题：使用 any 类型

7. 可访问性建议

建议：添加 ARIA 标签

8. 测试建议

建议：添加单元测试

📋 下一步行动计划

当前阶段：基础组件与UI统一

📝 代码规范建议

命名规范

文件组织

🎯 最终目标

24 KiB

Raw Blame History

问题：`page.tsx` 文件过大（3795 行）

问题：使用 `any` 类型