247 lines
8.4 KiB
Markdown
247 lines
8.4 KiB
Markdown
# CLAUDE.md
|
||
|
||
本文件为 Claude Code 在此代码仓库中工作时提供指导。
|
||
|
||
## 重要规定
|
||
|
||
**所有回复必须使用中文。**
|
||
|
||
**架构边界规则:** 实现功能前必须遵循 `.claude/rules/architecture-boundaries.md`。
|
||
|
||
**需要操作数据库时使用 MCP 工具。**
|
||
|
||
## 项目概述
|
||
|
||
GPU Guard 是 AI 驱动的智能管理审核平台，采用 Monorepo 架构。后端基于 Midway.js + Cool Admin 框架，前端基于 Vue 3 + Element Plus，AI 引擎采用自研 NetaClaw（ReAct 循环 + WebSocket 实时通信）。
|
||
|
||
**核心架构:**
|
||
- **Monorepo**: pnpm workspace 管理多个包
|
||
- **后端**: Midway.js 3.20 + Cool Admin 8.x，端口 8003
|
||
- **前端**: Vue 3.5 + Vite 5.4 + Element Plus 2.9，端口 9001
|
||
- **AI 引擎**: NetaClaw (ReAct + TypeBox Schema + Socket.IO)
|
||
- **数据库**: MySQL 8.0+ (`cpu_guard`)
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
GPU_GUARD_MONOREPO/
|
||
├── packages/
|
||
│ ├── backend/ # Midway.js 后端 (Cool Admin 框架)
|
||
│ ├── frontend/ # Vue 3 前端 (Cool Admin UI)
|
||
│ └── shared/ # 共享 TypeScript 类型
|
||
├── docs/superpowers/ # 设计文档与实施计划
|
||
└── package.json
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
pnpm install # 安装依赖
|
||
pnpm dev # 同时启动后端+前端
|
||
pnpm --filter @gpu-guard/backend dev # 单独启动后端 (8003)
|
||
pnpm --filter @gpu-guard/frontend dev # 单独启动前端 (9001)
|
||
pnpm build # 构建所有包
|
||
pnpm lint # 代码检查
|
||
```
|
||
|
||
## Cool Admin 框架规范
|
||
|
||
本项目基于 Cool Admin 开源框架二次开发，**必须遵循以下约定**。
|
||
|
||
### 后端 CRUD 模式 (@CoolController)
|
||
|
||
`@CoolController` 装饰器自动生成标准 CRUD 接口：
|
||
|
||
```typescript
|
||
@CoolController({
|
||
api: ['add', 'delete', 'update', 'info', 'list', 'page'],
|
||
entity: ProjectInfoEntity,
|
||
service: ProjectInfoService,
|
||
pageQueryOp: {
|
||
keyWordLikeFields: ['name'], // 模糊搜索字段
|
||
fieldEq: ['status'], // 精确匹配字段
|
||
addOrderBy: { createTime: 'DESC' }, // 默认排序
|
||
},
|
||
})
|
||
export class AdminProjectInfoController extends BaseController {}
|
||
```
|
||
|
||
**自动生成的接口:**
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/admin/{module}/{entity}/add` | 新增 |
|
||
| POST | `/admin/{module}/{entity}/delete` | 删除 (body: {ids: [1,2]}) |
|
||
| POST | `/admin/{module}/{entity}/update` | 更新 |
|
||
| GET | `/admin/{module}/{entity}/info` | 详情 (query: id) |
|
||
| POST | `/admin/{module}/{entity}/list` | 列表 |
|
||
| POST | `/admin/{module}/{entity}/page` | 分页 (body: {page, size, keyWord, ...}) |
|
||
|
||
**自定义接口:** 在 Controller 类中用 `@Get`/`@Post` 装饰器添加：
|
||
```typescript
|
||
@Get('/ganttData', { summary: '甘特图数据' })
|
||
async ganttData(@Query('projectId') projectId: number) {
|
||
return this.ok(await this.service.ganttData(projectId));
|
||
}
|
||
```
|
||
<!-- PLACEHOLDER_CLAUDE_CONTINUE -->
|
||
|
||
### BaseEntity 提供的字段
|
||
|
||
所有 Entity 继承 `BaseEntity`（来自 `../../base/entity/base.ts`），自动拥有：
|
||
- `id`: 自增主键
|
||
- `createTime`: 创建时间（自动填充）
|
||
- `updateTime`: 更新时间（自动更新）
|
||
- `tenantId`: 租户ID（多租户支持，nullable）
|
||
|
||
**创建 Entity 示例:**
|
||
```typescript
|
||
import { BaseEntity } from '../../base/entity/base.js';
|
||
import { Column, Entity } from 'typeorm';
|
||
|
||
@Entity('project_info')
|
||
export class ProjectInfoEntity extends BaseEntity {
|
||
@Column({ comment: '项目名称' })
|
||
name: string;
|
||
|
||
@Column({ comment: '状态 0未开始 1进行中 2已完成', default: 0 })
|
||
status: number;
|
||
|
||
@Column({ comment: '开始日期', type: 'date', nullable: true })
|
||
startDate: string;
|
||
}
|
||
```
|
||
|
||
### 前端 Service 代理
|
||
|
||
Cool Admin 根据后端 Controller 文件名自动生成 service 代理对象：
|
||
|
||
```typescript
|
||
const { service } = useCool();
|
||
|
||
// Controller 文件: modules/project/controller/admin/info.ts
|
||
// → service.project.info.page({...})
|
||
// → service.project.info.add({...})
|
||
// → service.project.info.update({...})
|
||
// → service.project.info.delete({ ids: [1] })
|
||
// → service.project.info.info({ id: 1 })
|
||
|
||
// Controller 文件: modules/project/controller/admin/task.ts
|
||
// → service.project.task.page({...})
|
||
|
||
// 自定义接口需要用 request:
|
||
// service.request({ url: '/admin/project/task/ganttData', params: { projectId: 1 } })
|
||
```
|
||
|
||
**重要:** service 路径由文件名决定，下划线文件名如 `time_log.ts` 对应 `service.project.time_log`（不是 timeLog）。
|
||
|
||
### 前端模块配置 (ModuleConfig)
|
||
|
||
每个前端模块必须有 `config.ts`：
|
||
|
||
```typescript
|
||
export default (): ModuleConfig => {
|
||
return {
|
||
name: 'project',
|
||
label: '项目管理',
|
||
order: 50,
|
||
views: [
|
||
{
|
||
path: '/project/list',
|
||
meta: { label: '项目列表' },
|
||
component: () => import('./views/list.vue')
|
||
},
|
||
]
|
||
};
|
||
};
|
||
```
|
||
## 菜单与权限系统
|
||
|
||
### 菜单配置 (base_sys_menu 表)
|
||
|
||
菜单通过数据库 `base_sys_menu` 表配置，**不在前端硬编码**。
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `parentId` | 父菜单ID（顶级为 null） |
|
||
| `name` | 菜单名称 |
|
||
| `router` | 路由路径（如 `/project/list`） |
|
||
| `viewPath` | Vue 组件路径（如 `modules/project/views/list.vue`） |
|
||
| `icon` | 图标 |
|
||
| `orderNum` | 排序号 |
|
||
| `type` | 0=目录, 1=菜单页面, 2=按钮权限 |
|
||
| `isShow` | 是否在侧边栏显示 |
|
||
| `keepAlive` | 是否缓存页面 |
|
||
| `perms` | 权限标识（按钮级，如 `project:info:add`） |
|
||
|
||
**新增菜单标准流程:**
|
||
```sql
|
||
-- 1. 新增目录
|
||
INSERT INTO base_sys_menu (parentId, name, icon, orderNum, type, isShow, createTime, updateTime)
|
||
VALUES (null, '项目管理', 'icon-project', 3, 0, 1, NOW(), NOW());
|
||
-- 记录返回的 id，假设为 158
|
||
|
||
-- 2. 新增菜单页面
|
||
INSERT INTO base_sys_menu (parentId, name, router, viewPath, orderNum, type, isShow, createTime, updateTime)
|
||
VALUES (158, '项目列表', '/project/list', 'modules/project/views/list.vue', 1, 1, 1, NOW(), NOW());
|
||
|
||
-- 3. 隐藏页面（详情页等）
|
||
INSERT INTO base_sys_menu (parentId, name, router, viewPath, orderNum, type, isShow, createTime, updateTime)
|
||
VALUES (158, '项目详情', '/project/detail', 'modules/project/views/detail.vue', 2, 1, 0, NOW(), NOW());
|
||
```
|
||
|
||
### 权限机制
|
||
|
||
- **admin 用户** 自动拥有所有权限，无需配置 role_menu 映射
|
||
- 普通用户通过 `base_sys_role_menu` 关联角色和菜单
|
||
- 权限中间件: JWT Token → 解析 userId → 查询权限列表 → 匹配请求 URL
|
||
- `/admin/*/comm/` 路径对所有登录用户开放
|
||
|
||
## 后端模块
|
||
|
||
| 模块 | 路径 | 用途 | 关键 Entity |
|
||
|------|------|------|------------|
|
||
| **base** | `modules/base/` | 用户、角色、菜单、权限 | BaseSysUser, BaseSysRole, BaseSysMenu |
|
||
| **netaclaw** | `modules/netaclaw/` | AI Agent 引擎 | NetaClawAgent, NetaClawSession, NetaClawMessage, NetaClawSkill, NetaClawModelChannel |
|
||
| **audit** | `modules/audit/` | 审核管理 | AuditConfig, AuditOrder, AuditResult |
|
||
| **dict** | `modules/dict/` | 字典管理 | DictType, DictInfo |
|
||
| **task** | `modules/task/` | 定时任务 | TaskInfo, TaskLog |
|
||
| **space** | `modules/space/` | 文件空间 | SpaceInfo, SpaceType |
|
||
| **user** | `modules/user/` | 应用用户 | UserInfo, UserWx |
|
||
| **notification** | `modules/notification/` | 通知服务 | NotificationMessageLog |
|
||
| **plugin** | `modules/plugin/` | 插件系统 | PluginInfo |
|
||
| **recycle** | `modules/recycle/` | 回收站 | RecycleData |
|
||
| **demo** | `modules/demo/` | 演示 | DemoGoods |
|
||
| **swagger** | `modules/swagger/` | API 文档 | - |
|
||
|
||
## 前端模块
|
||
|
||
| 模块 | 路由前缀 | 用途 |
|
||
|------|---------|------|
|
||
| **base** | `/` | 登录(Canvas星河动画)、用户、角色、菜单、部门 |
|
||
| **agent** | `/agent/*` | 智能体对话(WebSocket)、技能管理、模型渠道管理 |
|
||
| **audit** | `/audit/*` | 审核订单管理 |
|
||
| **dict** | `/dict/*` | 字典管理 |
|
||
| **task** | `/task/*` | 定时任务 |
|
||
| **space** | `/space/*` | 文件空间 |
|
||
| **user** | `/user/*` | 应用用户 |
|
||
|
||
## 开发规范
|
||
|
||
- **后端文件名**: 下划线法 (`model_channel.ts`)
|
||
- **Entity 字段**: 驼峰法 (`modelConfig`)
|
||
- **注释**: 中文
|
||
- **Entity**: 继承 BaseEntity，不使用外键
|
||
- **Controller**: 使用 `@CoolController` 自动生成 CRUD
|
||
- **包管理器**: 必须使用 pnpm
|
||
- **数据库**: 开发环境 `synchronize: true` 自动建表，生产环境禁止
|
||
|
||
## 环境变量
|
||
|
||
```env
|
||
NODE_ENV=development
|
||
BACKEND_PORT=8003
|
||
DB_HOST=120.48.5.80
|
||
DB_PORT=3306
|
||
DB_DATABASE=cpu_guard
|
||
```
|