# 工作日志 — 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 所有者