---
title: 管理端 Web 前端
updated: 2026-06-02
status: active
tags: [react, antd, vite, admin, typescript]
---

# 管理端 Web 前端

> 从 [[index]] 导航。关联: [[architecture]] [[erp-diary]]

## 1. 设计决策

### Q: 管理端从哪里来？

从 HMS 基座 (G:\hms/apps/web/) 复制而来，避免重复开发。HMS 已有完整的 React 管理面板（用户/角色/权限/组织/审计等），暖记直接复用。

### Q: 管理端技术栈？

React 19 + Ant Design 6 + Vite 8 + TypeScript + Zustand + Tailwind CSS 4。与基座后端 API 完全对接。

### Q: 为什么不和学生端一起用 Flutter？

管理端面向管理员/老师，Web 浏览器操作更高效。学生端面向小学生，需要触摸友好的移动端体验。

## 2. 关键结构

```
apps/web/
├── src/
│   ├── api/            # API 调用层 (Axios)
│   │   ├── client.ts   #   基础配置, baseURL=/api/v1
│   │   ├── ai/         #   AI 分析 API
│   │   └── health/     #   健康检查 API
│   ├── components/     # 通用组件
│   │   ├── Copilot/    #   AI 助手
│   │   └── MediaPicker/#   媒体选择器
│   ├── hooks/          # 自定义 Hooks
│   ├── layouts/        # 布局组件 (侧边栏+顶栏)
│   ├── pages/          # 页面
│   │   ├── dashboard/  #   仪表盘
│   │   ├── settings/   #   系统配置
│   │   ├── plugins/    #   插件管理
│   │   ├── workflow/   #   工作流
│   │   ├── messages/   #   消息管理
│   │   └── graph/      #   图形编辑器
│   ├── stores/         # Zustand 状态
│   ├── constants/      # 常量定义
│   └── utils/          # 工具函数
├── vite.config.ts      # Vite 配置 (proxy → localhost:3000)
└── package.json        # 依赖管理 (pnpm)
```

## 3. API 代理配置

`vite.config.ts` 已配置开发代理，所有 `/api` 请求转发到后端：

```typescript
proxy: {
  "/api":     { target: "http://localhost:3000", changeOrigin: true },
  "/uploads": { target: "http://localhost:3000", changeOrigin: true },
  "/ws":      { target: "ws://localhost:3000", ws: true },
}
```

无需额外 CORS 配置（同源代理）。

## 4. 功能模块映射

### 已验证的基座功能

| 管理端页面 | 后端 API | 状态 |
|-----------|---------|------|
| 登录 | POST /auth/login | ✅ |
| 仪表盘 | GET /health + 统计 | ✅ 部分数据待适配 |
| 用户管理 | CRUD /users | ✅ |
| 角色权限 | CRUD /roles + /permissions | ✅ |
| 审计日志 | GET /audit-logs | ✅ |
| 系统配置 | CRUD /config/settings | ✅ |
| 菜单管理 | /config/menus | ✅ |
| 数据字典 | /config/dictionaries | ✅ |
| 插件管理 | /admin/plugins | ✅ |
| 消息管理 | /messages | ✅ |

### 待添加的暖记专用功能

| 页面 | 说明 | 优先级 |
|------|------|--------|
| 班级管理 | 查看/创建/管理班级 | HIGH |
| 日记审核 | 查看学生日记 + 点评 | HIGH |
| 贴纸管理 | 上传/管理贴纸包 | MEDIUM |
| 主题管理 | 布置写作主题 | MEDIUM |
| 心情统计 | 全校/班级心情趋势 | LOW |

## 5. 品牌定制清单

管理端目前仍显示 HMS 品牌，需要替换为暖记品牌：

| 位置 | 当前值 | 替换为 |
|------|--------|--------|
| 登录页标题 | "HMS 健康管理平台" | "暖记管理后台" |
| 登录页副标题 | "患者管理·健康监测..." | "班级管理·日记审核·成长追踪" |
| 侧边栏标题 | "HMS 健康管理平台" | "暖记 Nuanji" |
| 底部版权 | "HMS 健康管理平台" | "暖记 Nuanji" |
| 页面 title | index.html | "暖记管理后台" |
| Logo | HMS logo | 暖记 Logo |
| 主题色 | 蓝色系 (Ant Design 默认) | 珊瑚色 (#E07A5F) |
| 不需要的页面 | 健康管理/AI分析 | 隐藏或移除 |

## 6. 启动方式

```bash
# 方式一：统一启动脚本
./scripts/dev.sh admin

# 方式二：手动启动
cd apps/web
pnpm install   # 首次需要安装依赖
pnpm dev       # 启动开发服务器 → http://localhost:5174
```

## 7. 变更记录

| 日期 | 变更 |
|------|------|
| 2026-06-02 | 初始创建 — 从 HMS 基座复制管理端前端 |