185 lines
6.8 KiB
Markdown
185 lines
6.8 KiB
Markdown
# 工作日志 — 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 所有者
|