GPU_GUARD_MONOREPO/CLAUDE.md

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

常用命令

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 接口：

@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 装饰器添加：

@Get('/ganttData', { summary: '甘特图数据' })
async ganttData(@Query('projectId') projectId: number) {
  return this.ok(await this.service.ganttData(projectId));
}

BaseEntity 提供的字段

所有 Entity 继承 BaseEntity（来自 ../../base/entity/base.ts），自动拥有：

• id: 自增主键
• createTime: 创建时间（自动填充）
• updateTime: 更新时间（自动更新）
• tenantId: 租户ID（多租户支持，nullable）

创建 Entity 示例:

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 代理对象：

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：

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）

新增菜单标准流程:

-- 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 自动建表，生产环境禁止

环境变量

NODE_ENV=development
BACKEND_PORT=8003
DB_HOST=120.48.5.80
DB_PORT=3306
DB_DATABASE=cpu_guard