AI Skill

0. AI Skill 快速使用

AideAdmin Framework 已封装为 AI Skill，优先给 Codex / Claude Code 这类原生 Skill 软件使用；Cursor、Windsurf、GitHub Copilot 等工具可通过 Rules / Instructions / AGENTS.md 方式接入同一套框架约定。

官网地址：https://aideadmin.com

npm install -g @qianukj/aideadmin-skill
aideadmin-skill install --force

主流工具快速接入

npm install -g @qianukj/aideadmin-skill
aideadmin-skill install --force

aideadmin-skill install --path ~/.claude/skills --force
# 项目共享
aideadmin-skill install --path .claude/skills --force

.cursor/rules/aideadmin.mdc

.windsurf/rules/aideadmin.md

.github/copilot-instructions.md

AGENTS.md

Goal

1. 框架目标

AideAdmin 是一个面向业务系统快速开发的前后端分离管理后台框架，核心目标是：

• 后端使用 Go 提供稳定、清晰、可扩展的 REST API。
• PC 管理后台和 H5 移动端都使用 React + TypeScript + Vite 构建。
• 内置管理员、角色、顶部导航、图标卡片入口、按钮权限、系统配置、字典、文件上传、操作日志、登录日志、定时任务、数据导出等通用能力。
• 内置客服 IM 能力，支持 H5 快速接入、PC 全局浮窗、消息监测、WebSocket 实时消息和常用话术。
• 内置第三方能力接入层，统一封装腾讯云 COS、阿里云 OSS、七牛云对象存储、腾讯云短信、阿里云短信。
• 保持统一接口协议，让前端导航入口、路由、权限、列表和导出都由服务端规则驱动。
• 保持固定开发路径：建表 -> model -> repository -> service -> controller -> route -> nav-entry -> api -> page。

Design Rules

2. 框架设计约定

AideAdmin 的后台系统开发约定：

2.1 后台管理 UE/UX 基线

后台管理端的视觉和交互基线按黑白简约工具界面定义，参考 ChatGPT 官方 UI 的克制、清晰和内容优先表达。AI 生成任何后台页面时必须优先满足以下规则：

Stack

3. 技术栈

Architecture

4. 项目目录

推荐使用 monorepo，把 PC 管理后台、H5 移动端和 Go 后端放在同一个仓库里。

aideadmin/
├── admin/                         # PC 管理后台 React 源码
│   └── src/
│       ├── api/
│       ├── components/
│       ├── hooks/
│       ├── layout/
│       ├── pages/
│       ├── router/
│       ├── stores/
│       ├── styles/
│       ├── utils/
│       └── main.tsx
├── h5/                            # H5 移动端 React 源码
│   └── src/
│       ├── api/
│       ├── components/
│       ├── hooks/
│       ├── pages/
│       ├── router/
│       ├── stores/
│       ├── styles/
│       ├── utils/
│       └── main.tsx
├── server/                        # Go 后端
│   ├── cmd/
│   │   ├── api/
│   │   └── worker/
│   ├── configs/
│   ├── internal/
│   │   ├── admin/
│   │   ├── im/
│   │   ├── common/
│   │   │   ├── sdk/
│   │   │   │   ├── storage/
│   │   │   │   └── sms/
│   │   └── model/
│   ├── migrations/
│   └── storage/
├── docker/
└── docs/

Backend Flow

5. 后端请求生命周期

安全中间件

Recovery
-> Trace
-> CORS
-> SecurityHeader
-> ClientIP
-> RateLimit
-> AntiReplay
-> SqlGuard
-> LoginAuth
-> AdminContext
-> Permission
-> Controller

API Contract

6. 统一接口协议

前端只识别统一响应结构：

{
  "code": 1,
  "show": 0,
  "msg": "success",
  "data": {}
}

分页响应

{
  "code": 1,
  "show": 0,
  "msg": "success",
  "data": {
    "lists": [],
    "count": 0,
    "page_no": 1,
    "page_size": 15,
    "extend": {}
  }
}

Go 响应结构

type Body struct {
    Code int         `json:"code"`
    Show int         `json:"show"`
    Msg  string      `json:"msg"`
    Data interface{} `json:"data"`
}

type PageData struct {
    Lists    interface{} `json:"lists"`
    Count    int64       `json:"count"`
    PageNo   int         `json:"page_no"`
    PageSize int         `json:"page_size"`
    Extend   interface{} `json:"extend,omitempty"`
}

Installation

7. 安装与首次运行流程

框架首次运行时不检查业务数据库连接。后端先判断安装状态，未安装时进入安装模式；只有用户在安装向导中写好数据库配置并确认安装后，才创建表、导入初始化数据和生成安装锁。

install:
  installed: false
  lock_file: storage/install.lock

database:
  driver: mysql
  host: 127.0.0.1
  port: 3306
  database: aideadmin
  username: root
  password: ""
  charset: utf8mb4
  timezone: Local
  table_prefix: aide_

{
  "database": {
    "host": "127.0.0.1",
    "port": 3306,
    "database": "aideadmin",
    "username": "root",
    "password": "",
    "table_prefix": "aide_"
  },
  "admin": {
    "username": "admin",
    "password": "admin123456"
  }
}

INSERT INTO {{prefix}}sys_config (`key`, `value`, `name`)
VALUES ('site.name', 'AideAdmin', '站点名称');

Auth

8. 认证与管理员上下文

后台认证模块负责确认请求身份、判断登录态、写入管理员上下文，并在进入 controller 前完成权限校验。

登录流程

提交账号密码
  -> 校验图形验证码 / 短信验证码
  -> 校验账号状态
  -> 校验密码 hash
  -> 生成 token
  -> Redis 写入会话
  -> 更新最后登录时间和 IP
  -> 写登录日志
  -> 返回 token、管理员信息、导航入口、权限字符

登录接口

Token 规则

token: <admin-token>
version: <client-version>
terminal: admin

Redis Key

auth:admin:token:{token}       # token -> admin session
auth:admin:user:{admin_id}     # admin_id -> token set
auth:admin:perm:{admin_id}     # 管理员权限缓存
auth:login:fail:{username}     # 登录失败次数
auth:captcha:{captcha_key}     # 图形验证码
auth:sms:{scene}:{mobile}      # 短信验证码

鉴权中间件顺序

Recovery -> Trace -> CORS -> RequestLog -> LoginAuth -> AdminContext -> Permission -> OperateLog -> Controller

免登录接口只跳过 LoginAuth 和 Permission，不跳过 Trace、RequestLog 和 Recovery。

POST /adminapi/login
GET  /adminapi/captcha
POST /adminapi/sms/send
GET  /adminapi/common/config

管理员上下文

type AdminContext struct {
    AdminID  uint
    RoleIDs  []uint
    Username string
    IsRoot   bool
}

上下文只能由中间件写入，业务代码只读取。repository 不允许读取 HTTP 上下文。

Permission

9. 权限体系

本框架采用 RBAC，但后台 UX 不采用传统权限树菜单。角色绑定的是顶部导航、图标卡片入口、按钮和接口权限，服务端决定入口是否可见，接口仍通过权限字符校验。

入口字段设计

CREATE TABLE sys_menu (
  id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
  parent_id BIGINT UNSIGNED NOT NULL DEFAULT 0,
  type CHAR(1) NOT NULL COMMENT 'M顶部导航 C图标卡片 A按钮',
  name VARCHAR(64) NOT NULL,
  path VARCHAR(128) NOT NULL DEFAULT '',
  component VARCHAR(255) NOT NULL DEFAULT '',
  icon VARCHAR(64) NOT NULL DEFAULT '',
  entry_desc VARCHAR(255) NOT NULL DEFAULT '',
  entry_badge VARCHAR(64) NOT NULL DEFAULT '',
  permission VARCHAR(128) NOT NULL DEFAULT '',
  sort INT NOT NULL DEFAULT 0,
  hidden TINYINT NOT NULL DEFAULT 0,
  keep_alive TINYINT NOT NULL DEFAULT 0,
  active_entry VARCHAR(128) NOT NULL DEFAULT '',
  status TINYINT NOT NULL DEFAULT 1,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  deleted_at DATETIME NULL
);

导航入口字段

{
  "id": 10,
  "parent_id": 0,
  "type": "C",
  "name": "管理员",
  "path": "/permission/admin",
  "component": "permission/admin/index",
  "icon": "UserOutlined",
  "entry_desc": "管理员账号、角色和状态维护",
  "entry_badge": "",
  "permission": "auth.admin/list",
  "meta": {
    "title": "管理员",
    "hidden": false,
    "activeEntry": "",
    "cache": false
  },
  "children": []
}

Routing

10. 路由规范

后台接口统一前缀为 /adminapi。

Data Flow

11-13. DTO、列表与导出

参数校验 DTO

type AdminCreateDTO struct {
    Username string `json:"username" binding:"required,min=4,max=32"`
    Password string `json:"password" binding:"required,min=6,max=32"`
    Nickname string `json:"nickname" binding:"required,max=32"`
    RoleIDs  []uint `json:"role_ids" binding:"required,min=1"`
    Status   int    `json:"status" binding:"oneof=0 1"`
}

Frontend

14. React 前端约定

PC 管理后台和 H5 移动端都使用 React。两端保持一致的工程思想、类型定义、接口协议和权限模型。

admin/src/
├── api/
├── components/
├── hooks/
├── layout/
├── pages/
├── router/
├── stores/
├── styles/
├── utils/
└── main.tsx

h5/src/
├── api/
├── components/
├── hooks/
├── pages/
├── router/
├── stores/
├── styles/
├── utils/
└── main.tsx

样式封装标准

框架必须提供统一样式基座。业务开发、代码生成器、后台页面、H5 页面和安装向导都只能继承或组合框架样式，不允许每个页面散写一套视觉规则。

:root {
  --aide-color-bg: #f7f7f5;
  --aide-color-surface: #ffffff;
  --aide-color-text: #111111;
  --aide-color-muted: #5f5f5b;
  --aide-color-border: #deded9;
  --aide-radius-md: 8px;
  --aide-space-4: 16px;
  --aide-shadow-float: 0 10px 28px rgba(0, 0, 0, 0.05);
}

import { DataPage } from '@aideadmin/ui'

export default function AdminListPage() {
  return (
    <DataPage
      title="管理员"
      description="管理员账号、角色和状态维护"
      permission="auth.admin/list"
      filter={<AdminFilter />}
      actions={<AdminActions />}
      table={<AdminTable />}
      emptyText="暂无管理员"
    />
  )
}

权限组件

import { Button } from 'antd'
import { Permission } from '@/components/Permission'

export function AdminToolbar() {
  return (
    <>
      <Permission value="auth.admin/add">
        <Button type="primary">新增</Button>
      </Permission>
      <Permission anyOf={['auth.admin/edit', 'auth.admin/delete']}>
        <Button>操作</Button>
      </Permission>
    </>
  )
}

请求防抖和重复提交

前端请求封装必须内置防抖、请求去重、写操作幂等键和路由切换取消请求。GET 搜索默认 300ms 防抖，POST / PUT / DELETE 默认 800ms 重复提交锁。

request.post('/auth/admin/add', data, {
  debounceKey: 'auth.admin.add',
  debounceMs: 800,
  idempotent: true,
})

Customer IM

15. 客服 IM 模块

客服 IM 是框架内置的全局能力，不新增独立导航入口。H5 端负责发起咨询，PC 管理后台通过全局浮窗接待会话，并由消息监测机制常驻监听未读、分配、断线重连和新消息提醒。

模块目录

server/internal/im/
├── gateway/
├── service/
├── repository/
├── dto/
└── vo/

admin/src/features/im/
├── ImMonitorProvider.tsx
├── ImFloatingEntry.tsx
├── ImWorkbenchDrawer.tsx
├── hooks/
└── api/

h5/src/pages/im/
└── chat/

WebSocket 连接

GET /adminapi/im/ws?token=<admin-token>&terminal=admin
GET /h5api/im/ws?token=<user-token>&terminal=h5
GET /h5api/im/ws?visitor_id=<visitor-id>&terminal=h5

WebSocket 消息协议

{
  "type": "message.send",
  "request_id": "req_1700000000",
  "data": {
    "session_id": "s_10001",
    "client_msg_id": "cmsg_1700000000",
    "msg_type": "text",
    "content": "你好，我想咨询订单",
    "payload": {}
  }
}

HTTP API

全局浮窗接入

import { ImMonitorProvider } from '@/features/im/ImMonitorProvider'
import { ImFloatingEntry } from '@/features/im/ImFloatingEntry'

export function AdminLayout() {
  return (
    <ImMonitorProvider>
      <MainLayout />
      <ImFloatingEntry />
    </ImMonitorProvider>
  )
}

核心数据表

H5 最小接入

import { useNavigate } from 'react-router'

export function ContactServiceButton({ scene, orderId }: { scene: string; orderId?: number }) {
  const navigate = useNavigate()

  return (
    <button onClick={() => navigate(`/im/chat?scene=${scene}&order_id=${orderId || ''}`)}>
      联系客服
    </button>
  )
}

快速接入步骤

1. 后端建立 server/internal/im 模块，创建 IM 数据库表。
2. 注册 /adminapi/im/ws、/h5api/im/ws 和 HTTP API。
3. 实现 WebSocket 鉴权、心跳、连接管理、消息落库和推送。
4. PC 在主布局挂载 ImMonitorProvider、ImFloatingEntry 和 ImWorkbenchDrawer 抽屉式接待面板。
5. H5 新增 h5/src/pages/im/chat/index.tsx 聊天页。
6. 不给客服 IM 创建独立导航入口，仅给客服角色分配会话、消息、监测和话术权限。

Integrations

16. 第三方能力接入

第三方能力统一放在 server/internal/common/sdk 下，业务模块只依赖框架接口，不直接调用腾讯云、阿里云或七牛云 SDK。

支持驱动

后端目录

server/internal/common/sdk/
├── storage/
│   ├── driver.go
│   ├── local.go
│   ├── tencent_cos.go
│   ├── aliyun_oss.go
│   └── qiniu_kodo.go
└── sms/
    ├── driver.go
    ├── tencent_sms.go
    └── aliyun_sms.go

type StorageDriver interface {
    Put(ctx context.Context, objectKey string, reader io.Reader, size int64, contentType string) (*FileObject, error)
    Fetch(ctx context.Context, url string, objectKey string) (*FileObject, error)
    Delete(ctx context.Context, objectKey string) error
    PublicURL(objectKey string) string
}

type SmsDriver interface {
    Send(ctx context.Context, req SmsSendRequest) (*SmsSendResult, error)
}

type SmsSendRequest struct {
    Mobile     string
    TemplateID string
    Params     map[string]string
    Scene      string
}

配置示例

storage:
  default: local
  allowed_ext:
    image: [jpg, jpeg, png, gif, webp]
    file: [pdf, doc, docx, xls, xlsx, zip]
  max_size_mb: 50
  tencent_cos:
    enabled: false
    secret_id: ${TENCENT_COS_SECRET_ID}
    secret_key: ${TENCENT_COS_SECRET_KEY}
    region: ap-guangzhou
    bucket: ""
  aliyun_oss:
    enabled: false
    access_key_id: ${ALIYUN_OSS_ACCESS_KEY_ID}
    access_key_secret: ${ALIYUN_OSS_ACCESS_KEY_SECRET}
    endpoint: oss-cn-hangzhou.aliyuncs.com
    bucket: ""
  qiniu_kodo:
    enabled: false
    access_key: ${QINIU_ACCESS_KEY}
    secret_key: ${QINIU_SECRET_KEY}
    bucket: ""

sms:
  default: tencent_sms
  code_ttl_seconds: 300
  send_interval_seconds: 60
  daily_limit: 20
  tencent_sms:
    enabled: false
    secret_id: ${TENCENT_SMS_SECRET_ID}
    secret_key: ${TENCENT_SMS_SECRET_KEY}
    region: ap-guangzhou
    app_id: ""
    sign: ""
  aliyun_sms:
    enabled: false
    access_key_id: ${ALIYUN_SMS_ACCESS_KEY_ID}
    access_key_secret: ${ALIYUN_SMS_ACCESS_KEY_SECRET}
    region: cn-hangzhou
    sign: ""

上传与短信 API

安全规则

Database

17. 数据库基础表

数据库表名由安装前缀和逻辑表名组成。安装前缀由安装页面提交的 database.table_prefix 决定，后端校验后写入配置，安装执行器再根据该值生成最终物理表名。文档中的 sys_、im_、cms_ 都只是逻辑表命名空间，不是最终物理表前缀。

physical_table = database.table_prefix + logical_table

第一阶段至少实现以下逻辑表，安装时按 database.table_prefix 生成物理表：

id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
created_at DATETIME NOT NULL,
updated_at DATETIME NOT NULL,
deleted_at DATETIME NULL

Operations

18-21. 日志、配置、定时任务与错误处理

app:
  name: aideadmin
  env: local
  port: 8080
  url_prefix: adminapi

database:
  driver: mysql
  host: 127.0.0.1
  port: 3306
  database: aideadmin
  username: root
  password: password
  charset: utf8mb4
  timezone: Local
  table_prefix: aide_
  dsn: root:password@tcp(127.0.0.1:3306)/aideadmin?charset=utf8mb4&parseTime=True&loc=Local

redis:
  addr: 127.0.0.1:6379
  password: ""
  db: 0

storage:
  default: local
  local:
    root: storage/upload
    public_url: /uploads

sms:
  default: tencent_sms
  code_ttl_seconds: 300
  send_interval_seconds: 60

security:
  trusted_proxies:
    - 127.0.0.1
  rate_limit:
    enabled: true
    driver: redis
    default:
      capacity: 120
      refill_rate: 60
      window_seconds: 60
    routes:
      - pattern: /adminapi/login
        capacity: 10
        window_seconds: 60
        dimensions: [ip, account]
      - pattern: /adminapi/sms/send
        capacity: 1
        window_seconds: 60
        dimensions: [ip, mobile, scene]
      - pattern: /adminapi/*/export
        capacity: 3
        window_seconds: 60
        dimensions: [admin_id, route]
  anti_replay:
    enabled: true
    nonce_ttl_seconds: 300
    idempotency_ttl_seconds: 600
  sql_guard:
    enabled: true
    log_only: false

Workflow

22. 开发一个业务模块的标准流程

1. 建表 cms_article，补齐通用字段。
2. 新建 model：internal/model/cms_article.go。
3. 新建 DTO：internal/admin/dto/article_dto.go。
4. 新建 VO：internal/admin/vo/article_vo.go。
5. 新建 repository：封装列表、详情、创建、更新、删除。
6. 新建 service：处理业务规则和事务。
7. 新建 controller：绑定参数，调用 service。
8. 在 route 中注册接口。
9. PC 管理后台新增 admin/src/api/cms/article.ts 和 admin/src/pages/cms/article/index.tsx。
10. 如 H5 需要该业务，新增 h5/src/api/cms/article.ts 和 h5/src/pages/cms/article/index.tsx。
11. 后台导航入口中新增顶部导航、图标卡片和按钮权限。
12. 给角色分配权限并补充测试。

Generator

23. 代码生成器规划

第二阶段实现代码生成器，根据数据表和模块配置生成 Go 后端与 React 前端骨架。

Roadmap

24. 第一阶段实现里程碑

Standard

25-26. 命名规范与安全要求

安全防护能力

CDN / WAF / Cloud Anti-DDoS
  -> Load Balancer
  -> Nginx rate_limit / body limit
  -> Go RateLimitMiddleware
  -> Controller

Delivery

27-30. 本地运行、三端打包与 Docker

框架按三端组织运行和交付：Go 后端 server、PC 管理后台 admin、H5 移动端 h5。三端都必须具备本地开发命令、生产打包命令和 Docker 镜像构建方式。

本地开发运行

cd server
cp configs/config.example.yaml configs/config.local.yaml
go mod tidy
go run ./cmd/api

cd admin
pnpm install
cp .env.example .env.local
pnpm dev --host 0.0.0.0 --port 5173

cd h5
pnpm install
cp .env.example .env.local
pnpm dev --host 0.0.0.0 --port 5174

三端生产打包

cd server
go test ./...
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o ../dist/server/aideadmin-api ./cmd/api
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o ../dist/server/aideadmin-worker ./cmd/worker

cd admin
pnpm install --frozen-lockfile
pnpm lint
pnpm build

cd ../h5
pnpm install --frozen-lockfile
pnpm lint
pnpm build

Docker 打包

docker build -f docker/api.Dockerfile -t aideadmin-api:latest .
docker build -f docker/worker.Dockerfile -t aideadmin-worker:latest .
docker build -f docker/admin.Dockerfile -t aideadmin-web:latest .
docker build -f docker/h5.Dockerfile -t aideadmin-h5-web:latest .

Docker 运行

docker run -d --name aideadmin-api \
  -p 8080:8080 \
  -v ./server/configs/config.local.yaml:/app/configs/config.local.yaml \
  -v ./server/storage:/app/storage \
  aideadmin-api:latest

docker run -d --name aideadmin-web -p 8081:80 aideadmin-web:latest
docker run -d --name aideadmin-h5-web -p 8082:80 aideadmin-h5-web:latest

Compose 编排

docker compose -f docker/compose.yaml up -d
docker compose -f docker/compose.yaml logs -f api
docker compose -f docker/compose.yaml down

License

31. 开源许可

AideAdmin Framework 遵循 MIT License，允许免费商用、二次开发、私有化部署、修改源码、复制、分发和再授权。

Documentation

32. 后续文档拆分建议

docs/
├── architecture.md          # 架构设计
├── api-contract.md          # 接口协议
├── rbac.md                  # 权限设计
├── frontend.md              # 前端开发规范
├── backend.md               # 后端开发规范
├── database.md              # 数据库规范
├── im.md                    # 客服 IM 接入文档
├── third-party.md           # 第三方存储和短信接入文档
├── generator.md             # 代码生成器设计
└── deployment.md            # 部署文档