wangdl/startup-plan
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
startup-plan/工作日志/2026-05-21.md
WangDL b4e1173063 docs: 补录 2026-05-21 工作日志 — Agent View 实验/废弃、devops-projects、Hermes Agent 部署 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-21 17:14:06 +08:00

6.8 KiB
Raw Blame History

工作日志 — 2026-05-21

Admin Starter 全栈搭建

概览

从空壳脚手架搭建完整的知习 Admin 企业后台管理系统，前后端总计 7 个阶段。

前端（admin-projects）— 7 阶段

Stage 1：基础设施

  • 安装 dayjs、echarts、echarts-for-react
  • 新建 src/types/admin.ts — AdminUser, DashboardStats, AuditLog, TrendPoint 类型
  • 新建 src/types/api.ts — PaginatedResult, PaginationParams, ApiError
  • 新建 src/constants/roles.ts — 角色名映射、层级判断 hasRole()
  • 新建 src/services/token-store.ts — localStorage 读写
  • 新建 src/services/http-client.ts — Fetch 封装（401 自动刷新队列）
  • 新建 src/services/admin-api.ts — 类型化 API 函数（login/logout/dashboard/users/audit）
  • 新建 src/services/mock-data.ts — DEV 模式 Dashboard / 审计日志 mock 数据
  • 配置 @/ 路径别名（vite.config.ts + tsconfig.app.json）

Stage 2：认证体系重构

  • 新建 src/hooks/use-auth-query.ts — useAdminUserQuery / useLoginMutation / useLogoutMutation
  • 重构 AuthContext — 改为消费 React Query hooks，新增 hasPermission(role)

Stage 3：布局与路由

  • 新建 PageLoading — 路由懒加载 Spin
  • 新建 PermissionGuard — 角色不足重定向 /403
  • 新建 config/menu.tsx — 集中式菜单树，带角色过滤 filterMenuByRole()
  • 新建 routes/index.tsx — 路由配置 + React.lazy 懒加载
  • 新建 AdminLayout — 环境标识 Tag、角色过滤菜单、面包屑、用户下拉（含角色显示）
  • 新建错误页：403 / 404 / 500（antd Result）
  • 重构 App.tsx — 懒加载 + PermissionGuard + Suspense + 404 catch-all
  • 删除旧 MainLayout.tsx

Stage 4：共享组件库（7 个）

组件 说明
StatusTag 彩色状态标签，支持自定义 statusMap
EmptyState 空状态占位，带可选操作按钮
DetailDrawer 侧滑详情抽屉（560px，loading 态）
ConfirmDangerModal 高危确认弹窗（需输入名称二次确认）
EChartsChartContainer 图表容器（Card + loading/empty 态）
MetricCard 指标卡（数值 + 趋势箭头 + loading）
AuditLogTable 审计日志 ProTable（预设列 + 详情抽屉）

Stage 5：页面

  • Dashboard — 4 MetricCard + 2 ECharts（日活/AI 调用趋势）+ AuditLogTable
  • UserManagement — ProTable（搜索/筛选/详情抽屉/删除确认）
  • Login — 左右分栏设计（浅蓝渐变品牌面板 + 白色表单区）

Stage 6：后端 API

新建 3 个 NestJS 模块：

  • AdminDashboardModule — GET /admin-api/dashboard/stats（聚合统计 + 30 天趋势）
  • AdminUsersModule — CRUD /admin-api/admin-users（分页/搜索/角色筛选，SUPER_ADMIN 守卫）
  • AdminAuditLogModule — GET /admin-api/audit-logs（分页/用户/操作/日期筛选）

Prisma Schema：AdminAuditLog 新增 adminUser 反向关系。

Stage 7：收尾

  • index.html title → "知习 Admin"
  • index.css 替换为 admin 最小重置
  • 删除 Vite 模板遗留资源（hero.png, react.svg, vite.svg）
  • 修复 TS 6 baseUrl deprecation
  • 更新 README.md（技术栈/目录结构/认证流程/角色体系）
  • 新增 CHANGELOG.md

Bug 修复

1. structuredClone React 19 兼容性

  • 现象：/audit 等页面白屏
  • 根因：AdminLayout 对包含 React 元素的菜单数据使用 structuredClone，React 19 内部 Symbol 无法被结构化克隆：DataCloneError: Symbol(react.transitional.element) could not be cloned
  • 修复：filterMenuByRole 内部用 spread 创建新对象，不需要 deep clone，直接移除 structuredClone 调用

2. echarts-for-react CJS/ESM 互操作

  • 现象：Dashboard 报错 Element type is invalid: expected a string but got: object
  • 根因：echarts-for-react/lib/core 是 CJS 产物，default export 在 Vite ESM 环境下解析失败
  • 修复：改用 echarts-for-react/esm/core

3. Login 页面样式优化

  • 左侧面板从深蓝黑渐变 #001529 → 改为浅蓝色 #e6f4ff → #bae0ff → primary
  • 去掉 DEV 环境标签
  • 去掉装饰性统计数字
  • 副标题改为"企业知识管理中台"

4. MetricCard 高度不一致

  • 修复：Card 加 height: '100%' 配合 Row flex 等高
  • 恢复 antd 默认紧凑 padding
  • 趋势区不强制占位

5. AuditLogTable 分页边距

  • 去掉 cardProps: { bodyStyle: { padding: 0 } }
  • 标题改用 ProTable headerTitle 属性
  • 恢复 ProTable Card 默认内边距

6. 杂项

  • AuthGuard Spin tip 属性警告 → 移除
  • useRef<ActionType> 需要初始值 → 改为 useRef<ActionType>(undefined)
  • AdminRoles 装饰器参数需用 enum 值而非字符串字面量

当前状态

前端

  • TypeScript 编译 ✅
  • Vite 生产构建 ✅
  • 所有路由可访问，权限守卫生效
  • Mock 数据在 DEV 模式下正常回退（Dashboard + AuditLog）

后端

  • NestJS 编译 ✅
  • Prisma 模型就绪（AdminUser + AdminSession + AdminAuditLog 含关系）
  • 3 个新模块已注册到 app.module.ts
  • 待部署到生产并跑 migration

待做

  • Admin API 部署到 8核32G 生产服务器
  • Prisma migrate（AdminAuditLog 新增 adminUser 关系）
  • 前后端联调验证
  • Dashboard 真实数据验证
  • 管理员 CRUD 端到端测试

Agent View 工作流配置（实验 → 废弃）

创建

  • 根目录 CLAUDE.md + .claude/agents/ 下 6 个 Agent 配置
  • 5 个子项目各创建 CLAUDE.md + AI_xxx_WORKSPACE.md
  • startup-plan/agent-config/ 备份目录
  • 设计完整工作流：任务分级、文件所有权、Review 触发、错误回滚、提交后归档

问题

  • Agent View 实测无法使用
  • 文档冗余：README.md + CLAUDE.md + WORKSPACE 三层重叠

清理

  • 删除所有 Agent 配置、CLAUDE.md、AI_WORKSPACE.md
  • 删除 startup-plan/agent-config/
  • 还原各 README 中 "For AI Agents" 章节
  • 推送所有仓库

devops-projects 仓库

  • 新建 devops-projects/ 目录
  • 从 startup-plan/凭据配置/ 迁移服务器凭据
  • 创建 devops-projects/README.md
  • 推送到 wangdl/devops-projects

Hermes Agent 部署（4核4G 轻量云）

项目 值
镜像 nousresearch/hermes-agent:latest
模型 deepseek-v4-flash
Provider DeepSeek 官方 API
Thinking reasoning_effort: max
内网地址 http://10.2.0.7:9119
持久化 sleep infinity 保活 + --restart unless-stopped

踩坑记录

  • 容器交互模式无 TTY 立即退出 → sleep infinity 保活
  • Dashboard 需 HERMES_DASHBOARD=true 开启
  • 内网访问需同时开 Lighthouse 防火墙 + iptables（lo 回环规则不覆盖 eth0）
  • Gitea push 需用 ssh://git@git.longde.cloud:2222 格式认证为 repo 所有者