### UI Development - Install Dependencies and Start Server

Source: https://github.com/go-admin-team/go-admin/blob/master/README.Zh-cn.md

Install frontend dependencies using npm, preferably with a mirror registry to improve speed. Then, start the development server.

```bash
# 安装依赖
npm install

# 建议不要直接使用 cnpm 安装依赖，会有各种诡异的 bug。可以通过如下操作解决 npm 下载速度慢的问题
npm install --registry=https://registry.npmmirror.com

# 启动服务
npm run dev
```

--------------------------------

### Install UI Dependencies and Start Development Server

Source: https://github.com/go-admin-team/go-admin/blob/master/README.md

Installs frontend dependencies using npm or cnpm and starts the UI development server.

```bash
# Installation dependencies
npm install   # or cnpm install

# Start service
npm run dev
```

--------------------------------

### Database Initialization and Server Start - Linux/macOS

Source: https://github.com/go-admin-team/go-admin/blob/master/README.Zh-cn.md

Initialize database resources and start the go-admin server using the provided command. Use the development configuration file for initialization.

```bash
# 首次配置需要初始化数据库资源信息
# macOS or linux 下使用
$ ./go-admin migrate -c config/settings.dev.yml


# 启动项目，也可以用IDE进行调试
# macOS or linux 下使用
$ ./go-admin server -c config/settings.yml
```

--------------------------------

### Initialize go-admin Database and Start Server (Windows)

Source: https://github.com/go-admin-team/go-admin/blob/master/README.md

Initializes the database using the development configuration and starts the go-admin server on Windows. Ensure configuration files are correctly set.

```bash
# The first configuration needs to initialize the database resource information
# Use under windows
$ go-admin.exe migrate -c config/settings.dev.yml

# Start the project, you can also use the IDE for debugging
# Use under windows
$ go-admin.exe server -c config/settings.yml
```

--------------------------------

### Database Initialization and Server Start - Windows

Source: https://github.com/go-admin-team/go-admin/blob/master/README.Zh-cn.md

Initialize database resources and start the go-admin server on Windows. Use the executable file and the development configuration for initialization.

```bash
# ⚠️注意:windows 下使用
$ go-admin.exe migrate -c config/settings.dev.yml


# ⚠️注意:windows 下使用
$ go-admin.exe server -c config/settings.yml
```

--------------------------------

### Start API Server

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Starts the Go-Admin API server. The configuration file path is specified with the -c flag.

```bash
./go-admin server -c config/settings.yml
```

--------------------------------

### Initialize go-admin Database and Start Server (Linux/macOS)

Source: https://github.com/go-admin-team/go-admin/blob/master/README.md

Initializes the database using the development configuration and starts the go-admin server. Ensure configuration files are correctly set.

```bash
# The first configuration needs to initialize the database resource information
# Use under macOS or linux
$ ./go-admin migrate -c config/settings.dev.yml

# Start the project, you can also use the IDE for debugging
# Use under macOS or linux
$ ./go-admin server -c config/settings.yml
```

--------------------------------

### Compile and Start go-admin with Docker

Source: https://github.com/go-admin-team/go-admin/blob/master/README.md

Builds a Docker image for go-admin and starts a container, mapping the configuration file from the host to the container.

```shell
# Compile the image
docker build -t go-admin .


# Start the container, the first go-admin is the container name, and the second go-admin is the image name
# -v Mapping configuration file Local path: container path
docker run --name go-admin -p 8000:8000 -v /config/settings.yml:/config/settings.yml -d go-admin-server
```

--------------------------------

### Get Frontend System Configuration - GET /api/v1/app-config

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Retrieves frontend-facing system configuration keys. This endpoint does not require authentication.

```bash
curl -X GET http://localhost:8000/api/v1/app-config
```

--------------------------------

### List System Configurations - GET /api/v1/sys-config

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Query dynamic system configuration parameters with pagination. Requires authentication.

```bash
curl -X GET "http://localhost:8000/api/v1/sys-config?pageIndex=1&pageSize=10" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Get Menu Tree - GET /api/v1/menu

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Retrieves the complete menu structure as a tree. Can be filtered by menu name.

```bash
curl -X GET "http://localhost:8000/api/v1/menu?menuName=" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Get Authenticated User Info - GET /api/v1/getinfo

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Retrieves information for the currently authenticated user, including their roles and permissions.

```bash
curl -X GET http://localhost:8000/api/v1/getinfo \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Get Real-time Server Metrics - GET /api/v1/server-monitor

Source: https://context7.com/go-admin-team/go-admin/llms.txt

This endpoint provides real-time server metrics including OS information, CPU, memory, swap, disk usage, and network I/O.

```bash
curl -X GET http://localhost:8000/api/v1/server-monitor \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Get App Configurations

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Retrieves frontend-facing system configuration keys. This is a public endpoint and does not require authentication.

```APIDOC
## GET /api/v1/app-config

### Description
Public endpoint (no auth required) returning only frontend-facing config keys.

### Method
GET

### Endpoint
/api/v1/app-config

### Response
#### Success Response (200)
- **data** (object) - An object containing frontend-facing configuration keys and their values.
- **msg** (string) - Success message.
```

--------------------------------

### Get Role Menus for Sidebar - GET /api/v1/menurole

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Fetches the menu structure accessible to the current user's role, typically used for building the left navigation sidebar.

```bash
curl -X GET http://localhost:8000/api/v1/menurole \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Get or Update System Configurations

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Allows reading all configuration values or performing a bulk update of configuration settings.

```APIDOC
## GET /api/v1/set-config (Read) / PUT /api/v1/set-config (Update)

### Description
Read or bulk-update a group of configuration values via the UI settings panel.

### Method
GET (Read) / PUT (Update)

### Endpoint
/api/v1/set-config

### Request Body (for PUT)
- An array of objects, where each object has `configKey` (string) and `configValue` (string).

### Request Example (PUT)
```json
[
  {"configKey": "sys.login.captchaEnabled", "configValue": "false"},
  {"configKey": "sys.index.skinName",        "configValue": "skin-blue"}
]
```

### Response
#### Success Response (200)
- **data** (string) - Typically an empty string on success.
- **msg** (string) - Success message (e.g., "更新成功").
```

--------------------------------

### Get Menu Tree

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Retrieves the full menu tree, with an option to filter by menu name.

```APIDOC
## GET /api/v1/menu

### Description
Retrieve the full menu tree; filter by `menuName`.

### Method
GET

### Endpoint
/api/v1/menu

### Parameters
#### Query Parameters
- **menuName** (string) - Optional - Filter the menu tree by menu name.

### Request Example
```bash
curl -X GET "http://localhost:8000/api/v1/menu?menuName=" \
  -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **code** (integer) - Response status code.
- **data** (array) - The menu tree structure.
  - **menuId** (integer) - Menu item ID.
  - **menuName** (string) - Name of the menu item.
  - **parentId** (integer) - Parent menu item ID.
  - **orderNum** (integer) - Order number for display.
  - **path** (string) - Route path for the menu item.
  - **component** (string) - Component associated with the menu item.
  - **visible** (string) - Visibility status of the menu item.
  - **children** (array) - Nested array for sub-menus.
- **msg** (string) - Response message.

#### Response Example
```json
{
  "code": 200,
  "data": [
    { "menuId": 1, "menuName": "系统管理", "parentId": 0, "orderNum": 1,
      "path": "system", "component": "Layout", "menuType": "M",
      "visible": "0", "children": [ ... ] }
  ],
  "msg": "查询成功"
}
```
```

--------------------------------

### Get Role Menu Tree with Checked Keys - GET /api/v1/roleMenuTreeselect/{roleId}

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Returns the full menu tree along with the IDs of menus already selected for a specific role. Used in the role editing interface.

```bash
curl -X GET http://localhost:8000/api/v1/roleMenuTreeselect/2 \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Automatic API Data Addition

Source: https://github.com/go-admin-team/go-admin/blob/master/README.Zh-cn.md

Start the project with the `-a true` flag to automatically add missing API data to the `sys_api` table.

```bash
./go-admin server -c config/settings.yml -a true
```

--------------------------------

### List Roles with Filtering - GET /api/v1/role

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Lists available roles. Supports filtering by role name, role key, and status. Requires pagination parameters.

```bash
curl -X GET "http://localhost:8000/api/v1/role?pageIndex=1&pageSize=10&status=2" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### List Posts - GET /api/v1/post

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Retrieve a paginated list of all defined positions or posts. Requires authentication and specifies pagination parameters.

```bash
curl -X GET "http://localhost:8000/api/v1/post?pageIndex=1&pageSize=10" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Get Role Menus

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Fetches menus available for the caller's role, typically used to construct the left navigation sidebar.

```APIDOC
## GET /api/v1/menurole

### Description
Fetch menus available for the caller's role — used to build the left navigation sidebar.

### Method
GET

### Endpoint
/api/v1/menurole

### Response
#### Success Response (200)
- **code** (integer) - Response status code.
- **data** (array) - List of menus available for the role.
- **msg** (string) - Response message.

#### Response Example
```json
{ "code": 200, "data": [ { "name": "System", "path": "/system", ... } ], "msg": "" }
```
```

--------------------------------

### Get Role Menu Tree with Checked Keys

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Returns the full menu tree along with the IDs of menus already checked for a specific role. Used in the role edit dialog.

```APIDOC
## GET /api/v1/roleMenuTreeselect/{roleId}

### Description
Returns the full menu tree plus the IDs already checked for a specific role — used in the role edit dialog.

### Method
GET

### Endpoint
/api/v1/roleMenuTreeselect/{roleId}

### Parameters
#### Path Parameters
- **roleId** (integer) - Required - The ID of the role for which to retrieve the menu tree and checked keys.

### Request Example
```bash
curl -X GET http://localhost:8000/api/v1/roleMenuTreeselect/2 \
  -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **code** (integer) - Response status code.
- **data** (object) - Contains the menu tree and checked keys.
  - **menus** (array) - The full menu tree structure.
    - **id** (integer) - Menu ID.
    - **label** (string) - Menu label.
    - **children** (array) - Nested array for sub-menus.
  - **checkedKeys** (array) - List of IDs for menus already checked for the role.
- **msg** (string) - Response message.

#### Response Example
```json
{
  "code": 200,
  "data": {
    "menus": [ { "id": 1, "label": "系统管理", "children": [...] } ],
    "checkedKeys": [1, 10, 11, 12]
  },
  "msg": "获取成功"
}
```
```

--------------------------------

### Scheduled Job Management

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Provides functionality to start or remove scheduled cron jobs using their unique IDs.

```APIDOC
## Scheduled Job – Start / Remove

### Description
Start or remove a scheduled cron job by ID through the jobs module API.

### Start a Job

#### Method
GET

#### Endpoint
/api/v1/job/start/{id}

#### Parameters
##### Path Parameters
- **id** (integer) - Required - The ID of the job to start.

#### Request Example
```bash
curl -X GET http://localhost:8000/api/v1/job/start/3 \
  -H "Authorization: Bearer <token>"
```

### Remove a Job

#### Method
DELETE

#### Endpoint
/api/v1/job

#### Request Body
- **ids** (array of integers) - Required - An array containing the IDs of the jobs to remove.

### Request Example
```bash
curl -X DELETE http://localhost:8000/api/v1/job \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"ids": [3]}'
```

### Response (for both Start and Remove)
#### Success Response (200)
- **code** (integer) - The status code of the response.
- **data** (null) - Typically null for these operations.
- **msg** (string) - A message describing the result of the operation (e.g., "ok").
```

--------------------------------

### Get Authenticated User Info

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Returns the authenticated user's information, including their role list and button-level permissions.

```APIDOC
## GET /api/v1/getinfo

### Description
Return the authenticated user's info, role list, and button-level permissions.

### Method
GET

### Endpoint
/api/v1/getinfo

### Response
#### Success Response (200)
- **code** (integer) - Response status code.
- **data** (object) - User information.
  - **userId** (integer) - User ID.
  - **userName** (string) - Username.
  - **name** (string) - User's full name.
  - **deptId** (integer) - Department ID.
  - **avatar** (string) - URL to the user's avatar.
  - **roles** (array) - List of user roles.
  - **permissions** (array) - List of user permissions.
  - **buttons** (array) - List of user button permissions.
- **msg** (string) - Response message.

#### Response Example
```json
{
  "code": 200,
  "data": {
    "userId": 1, "userName": "admin", "name": "Admin",
    "deptId": 1, "avatar": "https://...",
    "roles": ["admin"],
    "permissions": ["*:*:*"],
    "buttons": ["*:*:*"]
  },
  "msg": ""
}
```
```

--------------------------------

### Query Operation Logs - GET /api/v1/sys-opera-log

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Retrieve paginated operation audit logs. Supports filtering by title, request method, IP address, status, and date range. Requires authentication.

```bash
curl -X GET "http://localhost:8000/api/v1/sys-opera-log?pageIndex=1&pageSize=20&status=0&beginTime=2024-01-01+00:00:00&endTime=2024-12-31+23:59:59" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### List Departments as Tree - GET /api/v1/dept

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Retrieves the department hierarchy as a tree structure. Supports filtering by department name.

```bash
curl -X GET "http://localhost:8000/api/v1/dept?deptName=" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### List Dictionary Types - GET /api/v1/dict/type

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Fetches a paginated list of dictionary types, which are categories for fixed-value enumerations. Requires authentication.

```bash
curl -X GET "http://localhost:8000/api/v1/dict/type?pageIndex=1&pageSize=10" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### List All Dictionary Types (No Pagination) - GET /api/v1/dict/type-option-select

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Retrieves all dictionary types without pagination, typically used for populating dropdowns in code generation. Requires authentication.

```bash
curl -X GET http://localhost:8000/api/v1/dict/type-option-select \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Query Login Audit Logs - GET /api/v1/sys-login-log

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Use this endpoint to retrieve paginated login audit logs. You can filter by username, IP address, login location, status, and a date range.

```bash
curl -X GET "http://localhost:8000/api/v1/sys-login-log?pageIndex=1&pageSize=10&username=admin" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Backend Server Startup - Go

Source: https://github.com/go-admin-team/go-admin/blob/master/README.Zh-cn.md

Navigate to the go-admin backend project, tidy dependencies, build the project, and modify configuration settings. Ensure database information and log paths are correctly set in `config/settings.yml`.

```bash
# 进入 go-admin 后端项目
cd ./go-admin

# 更新整理依赖
go mod tidy

# 编译项目
go build

# 修改配置 
# 文件路径  go-admin/config/settings.yml
vi ./config/settings.yml

# 1. 配置文件中修改数据库信息 
# 注意: settings.database 下对应的配置数据
# 2. 确认log路径
```

--------------------------------

### Control Scheduled Cron Jobs

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Manage scheduled cron jobs by their ID. Supports starting jobs via a GET request and removing them via a DELETE request with a JSON payload.

```bash
# Start a job
curl -X GET http://localhost:8000/api/v1/job/start/3 \
  -H "Authorization: Bearer <token>"
```

```bash
# Remove a job
curl -X DELETE http://localhost:8000/api/v1/job \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"ids": [3]}'
```

--------------------------------

### Prepare go-admin Backend Dependencies and Build

Source: https://github.com/go-admin-team/go-admin/blob/master/README.md

Navigates into the go-admin backend directory, updates dependencies, and compiles the project.

```bash
# Enter the go-admin backend project
cd ./go-admin

# Update dependencies
go mod tidy

# Compile the project
go build
```

--------------------------------

### Initialize/Migrate Database

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Run this command once to set up the database schema. Ensure your config/settings.yml is correctly configured.

```bash
./go-admin migrate -c config/settings.yml
```

--------------------------------

### Docker Build and Run

Source: https://github.com/go-admin-team/go-admin/blob/master/README.Zh-cn.md

Build the go-admin Docker image and run a container, mapping the local configuration file to the container's path.

```shell
# 编译镜像
docker build -t go-admin .

# 启动容器，第一个go-admin是容器名字，第二个go-admin是镜像名称
# -v 映射配置文件 本地路径：容器路径
docker run --name go-admin -p 8000:8000 -v /config/settings.yml:/config/settings.yml -d go-admin-server
```

--------------------------------

### Docker Build and Run

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Builds a Docker image for Go-Admin and runs it as a container. Mounts the configuration file and exposes port 8000.

```bash
docker build -t go-admin .
docker run --name go-admin -p 8000:8000 \
  -v $(pwd)/config/settings.yml:/config/settings.yml \
  -d go-admin
```

--------------------------------

### Build Go-Admin Service

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Use this command to build the Go-Admin service executable. The output binary will be named 'go-admin'.

```bash
go build -o go-admin .
```

--------------------------------

### Create go-admin Development Directory

Source: https://github.com/go-admin-team/go-admin/blob/master/README.md

Creates a new directory for go-admin development and navigates into it.

```bash
mkdir goadmin
cd goadmin
```

--------------------------------

### List System Configurations

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Retrieves a paginated list of dynamic system configuration parameters.

```APIDOC
## GET /api/v1/sys-config

### Description
List dynamic system configuration parameters with pagination.

### Method
GET

### Endpoint
/api/v1/sys-config

### Query Parameters
- **pageIndex** (integer) - Required - The current page number.
- **pageSize** (integer) - Required - The number of items per page.

### Response
#### Success Response (200)
- **data.list** (array) - An array of configuration objects, each containing `configId`, `configName`, `configKey`, `configValue`, `configType`, and `isFrontend`.
- **data.count** (integer) - The total number of configuration items.
- **data.pageIndex** (integer) - The current page index.
- **data.pageSize** (integer) - The number of items per page.
- **msg** (string) - Success message.
```

--------------------------------

### Clone Backend and Frontend Repositories

Source: https://github.com/go-admin-team/go-admin/blob/master/README.Zh-cn.md

Clone the go-admin backend and frontend repositories into the same directory. Ensure both projects are in the same folder.

```bash
# 获取后端代码
git clone https://github.com/go-admin-team/go-admin.git

# 获取前端代码
git clone https://github.com/go-admin-team/go-admin-ui.git
```

--------------------------------

### Generate go-admin Documentation

Source: https://github.com/go-admin-team/go-admin/blob/master/README.md

Executes the go generate command to generate documentation for the go-admin project.

```bash
go generate
```

--------------------------------

### Initialize Database with Seed Data

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Call the InitDb function to seed the database with bundled SQL scripts. This function automatically selects the appropriate script based on the database driver configured (e.g., pg.sql for PostgreSQL, db.sql for others).

```go
import (
    "go-admin/app/admin/models"
    "gorm.io/driver/mysql"
    "gorm.io/gorm"
)

func main() {
    dsn := "user:password@tcp(127.0.0.1:3306)/go_admin?charset=utf8mb4&parseTime=True&loc=Local"
    db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{}) 
    if err != nil {
        panic(err)
    }

    if err := models.InitDb(db); err != nil {
        panic("database init failed: " + err.Error())
    }
    // Database now contains all system tables and seed data
}
```

--------------------------------

### Database Initialization

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Seeds the database with bundled SQL scripts, automatically selecting the appropriate script based on the database driver.

```APIDOC
## Database Initialization – `InitDb`

### Description
Seed the database with the bundled SQL scripts. Automatically uses `config/pg.sql` for PostgreSQL and `config/db.sql` for other drivers.

### Usage (Go SDK)

```go
import (
    "go-admin/app/admin/models"
    "gorm.io/driver/mysql"
    "gorm.io/gorm"
)

func main() {
    dsn := "user:password@tcp(127.0.0.1:3306)/go_admin?charset=utf8mb4&parseTime=True&loc=Local"
    db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
    if err != nil {
        panic(err)
    }

    if err := models.InitDb(db); err != nil {
        panic("database init failed: " + err.Error())
    }
    // Database now contains all system tables and seed data
}
```
```

--------------------------------

### Clone go-admin Backend and Frontend Repositories

Source: https://github.com/go-admin-team/go-admin/blob/master/README.md

Clones the go-admin backend and frontend codebases. Ensure both projects are in the same parent folder.

```bash
# Get backend code
git clone https://github.com/go-admin-team/go-admin.git

# Get the front-end code
git clone https://github.com/go-admin-team/go-admin-ui.git
```

--------------------------------

### Create User

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Create a new system user. The password will be automatically bcrypt-hashed via a GORM `BeforeCreate` hook.

```APIDOC
## POST /api/v1/sys-user

### Description
Create a new system user. Password is bcrypt-hashed automatically via a GORM `BeforeCreate` hook.

### Method
POST

### Endpoint
/api/v1/sys-user

### Parameters
#### Request Body
- **username** (string) - Required - The username for the new user.
- **password** (string) - Required - The user's password (will be hashed).
- **nickName** (string) - Optional - The user's nickname.
- **phone** (string) - Optional - The user's phone number.
- **email** (string) - Optional - The user's email address.
- **sex** (string) - Optional - The user's sex (e.g., '1' for male, '2' for female).
- **status** (string) - Optional - The user's status (e.g., '2' for active).
- **deptId** (integer) - Optional - The ID of the department the user belongs to.
- **postId** (integer) - Optional - The ID of the post the user holds.
- **roleId** (integer) - Optional - The ID of the role to assign to the user.
- **remark** (string) - Optional - A remark for the user.

### Request Example
```json
{
  "username": "jdoe",
  "password": "Secret123!",
  "nickName": "John Doe",
  "phone": "13900000001",
  "email": "jdoe@example.com",
  "sex": "1",
  "status": "2",
  "deptId": 2,
  "postId": 1,
  "roleId": 2,
  "remark": "New developer account"
}
```

### Response
#### Success Response (200)
- **code** (integer) - The status code of the response.
- **data** (integer) - The ID of the newly created user.
- **msg** (string) - A message indicating the result of the operation.

### Response Example
```json
{ "code": 200, "data": 42, "msg": "创建成功" }
```
```

--------------------------------

### Cross-Compile go-admin for Different Operating Systems

Source: https://github.com/go-admin-team/go-admin/blob/master/README.md

Builds the go-admin project for Windows or Linux using environment variables to specify the target OS and architecture.

```bash
# windows
env GOOS=windows GOARCH=amd64 go build main.go

# or
# linux
env GOOS=linux GOARCH=amd64 go build main.go
```

--------------------------------

### Manage System Configurations - GET/PUT /api/v1/set-config

Source: https://context7.com/go-admin-team/go-admin/llms.txt

This endpoint allows reading all set-config values or performing bulk updates. Requires authentication for both operations.

```bash
# Read all set-config values
curl -X GET http://localhost:8000/api/v1/set-config \
  -H "Authorization: Bearer <token>"
```

```bash
# Bulk update
curl -X PUT http://localhost:8000/api/v1/set-config \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '[
    {"configKey": "sys.login.captchaEnabled", "configValue": "false"},
    {"configKey": "sys.index.skinName",        "configValue": "skin-blue"}
  ]'
```

--------------------------------

### Create System User

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Create a new system user. The password field will be automatically bcrypt-hashed by a GORM `BeforeCreate` hook.

```bash
curl -X POST http://localhost:8000/api/v1/sys-user \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ \
    "username": "jdoe", \
    "password": "Secret123!", \
    "nickName": "John Doe", \
    "phone": "13900000001", \
    "email": "jdoe@example.com", \
    "sex": "1", \
    "status": "2", \
    "deptId": 2, \
    "postId": 1, \
    "roleId": 2, \
    "remark": "New developer account" \
  }'
```

```json
# Expected response
# { "code": 200, "data": 42, "msg": "创建成功" }
```

--------------------------------

### List Users with Pagination and Filtering

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Retrieve a list of system users with support for pagination and filtering by username. The response respects the caller's data-scope permissions.

```bash
# List users – page 1, 10 per page
curl -X GET "http://localhost:8000/api/v1/sys-user?pageIndex=1&pageSize=10&username=admin" \
  -H "Authorization: Bearer <token>"
```

```json
# Expected response
# {
#   "code": 200,
#   "data": {
#     "list": [
#       { "userId": 1, "username": "admin", "nickName": "Admin", "phone": "18888888888",
#         "email": "admin@example.com", "sex": "1", "status": "2",
#         "deptId": 1, "postId": 1, "roleId": 1 }
#     ],
#     "count": 1,
#     "pageIndex": 1,
#     "pageSize": 10
#   },
#   "msg": "查询成功"
# }
```

--------------------------------

### Create New Role - POST /api/v1/role

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Creates a new role with specified details and immediately synchronizes Casbin policies. Requires role name, key, status, data scope, menu IDs, and an optional remark.

```bash
curl -X POST http://localhost:8000/api/v1/role \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "roleName": "Editor",
    "roleKey": "editor",
    "status": "2",
    "dataScope": "5",
    "menuIds": [1, 2, 10, 11],
    "remark": "Content editor role"
  }'
```

--------------------------------

### Application and Database Configuration

Source: https://github.com/go-admin-team/go-admin/wiki/系统配置

This YAML snippet defines essential application and database settings. Adjust these parameters to match your deployment environment, including project environment, host, ports, database credentials, and JWT secret.

```yaml
settings:
  application:
    # 项目启动环境            
    env: dev  
    # 当 env:demo 时，GET以外的请求操作提示
    envmsg: "谢谢您的参与，但为了大家更好的体验，所以本次提交就算了吧！" 
    # 主机ip 或者域名，默认0.0.0.0
    host: 0.0.0.0 
    # 是否需要初始化数据库结构以及基本数据；true：需要；false：不需要 
    isinit: false  
    # JWT加密字符串
    jwtsecret: 123abc  
    # log存放路径
    logpath: temp/logs/log.log   
    # 服务名称
    name: go-admin   
    # 服务端口
    port: 8000   
    readtimeout: 1   
    writertimeout: 2 
  database:
    # 数据库名称
    database: dbname 
    # 数据库类型
    dbtype: mysql    
    # 数据库地址
    host: 127.0.0.1  
    # 数据库密码
    password: password  
    # 数据库端口
    port: 3306       
    # 数据库用户名
    username: root     

```

--------------------------------

### Cross-compile for Linux

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Compiles the Go-Admin application for Linux (amd64 architecture) from a macOS or Windows environment. The output binary is named go-admin-linux.

```bash
env GOOS=linux GOARCH=amd64 go build -o go-admin-linux .
```

--------------------------------

### Create Role

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Creates a new role and immediately syncs Casbin policies.

```APIDOC
## POST /api/v1/role

### Description
Create a new role and sync Casbin policies immediately.

### Method
POST

### Endpoint
/api/v1/role

### Parameters
#### Request Body
- **roleName** (string) - Required - The name of the role.
- **roleKey** (string) - Required - The key identifier for the role.
- **status** (string) - Required - The status of the role (e.g., "2").
- **dataScope** (string) - Required - The data scope for the role (e.g., "5").
- **menuIds** (array) - Required - A list of menu IDs associated with the role.
- **remark** (string) - Optional - A remark or description for the role.

### Request Example
```bash
curl -X POST http://localhost:8000/api/v1/role \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ 
    "roleName": "Editor",
    "roleKey": "editor",
    "status": "2",
    "dataScope": "5",
    "menuIds": [1, 2, 10, 11],
    "remark": "Content editor role" 
  }'
```

### Response
#### Success Response (200)
- **code** (integer) - Response status code.
- **data** (integer) - The ID of the newly created role.
- **msg** (string) - Success message.

#### Response Example
```json
{ "code": 200, "data": 5, "msg": "创建成功" }
```
```

--------------------------------

### Go-Admin Configuration File Reference

Source: https://context7.com/go-admin-team/go-admin/llms.txt

This YAML file serves as the central configuration for the Go-Admin application, controlling settings for the application mode, server host/port, logging, JWT, database connection, and more.

```yaml
settings:
  application:
    mode: dev          # dev | test | prod
    host: 0.0.0.0
    name: go-admin
    port: 8000
    readtimeout: 1
    writertimeout: 2
    enabledp: true     # enable data-scope permission

  logger:
    path: temp/logs
    stdout: ''         # '' = file only; 'default' = console only
    level: info        # trace|debug|info|warn|error|fatal
    enableddb: false

  jwt:
    secret: change-me-in-prod
    timeout: 3600      # seconds

  database:
    driver: mysql      # mysql | sqlite3 | postgres | sqlserver
    source: user:password@tcp(127.0.0.1:3306)/go_admin?charset=utf8&parseTime=True&loc=Local

  gen:
    dbname: go_admin
    frontpath: ../go-admin-ui/src

  cache:
    memory: ''         # use in-memory cache; comment out and use redis block for Redis

  queue:
    memory:
      poolSize: 100

  locker:
    redis:
      addr: 127.0.0.1:6379
      password: ''
      db: 0
```

--------------------------------

### Server Monitor

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Retrieves real-time server metrics including OS information, CPU, memory, swap, disk, and network I/O.

```APIDOC
## GET /api/v1/server-monitor

### Description
Return real-time server metrics: OS info, CPU, memory, swap, disk, and network I/O.

### Method
GET

### Endpoint
/api/v1/server-monitor

### Request Example
```bash
curl -X GET http://localhost:8000/api/v1/server-monitor \
  -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **code** (integer) - The status code of the response.
- **os** (object) - Operating system information.
  - **goOs** (string) - The operating system name (e.g., "linux").
  - **arch** (string) - The system architecture (e.g., "amd64").
  - **version** (string) - The OS version.
  - **numGoroutine** (integer) - The number of active goroutines.
  - **ip** (string) - The server's IP address.
  - **hostName** (string) - The hostname of the server.
  - **time** (string) - The current server time.
- **cpu** (object) - CPU utilization information.
  - **cpuNum** (integer) - The number of CPU cores.
  - **percent** (number) - The current CPU utilization percentage.
  - **cpuInfo** (array) - Detailed CPU information (content varies).
- **mem** (object) - Memory utilization information.
  - **used** (integer) - Used memory in MB.
  - **total** (integer) - Total memory in MB.
  - **percent** (number) - The current memory utilization percentage.
- **disk** (object) - Disk utilization information.
  - **used** (integer) - Used disk space in GB.
  - **total** (integer) - Total disk space in GB.
  - **percent** (number) - The current disk utilization percentage.
- **net** (object) - Network I/O statistics.
  - **in** (number) - Network traffic received in MB/s.
  - **out** (number) - Network traffic sent in MB/s.
- **bootTime** (integer) - The server's boot time in seconds since epoch.
```

--------------------------------

### List Roles

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Lists roles with optional filtering by `roleName`, `roleKey`, and `status`. Supports pagination.

```APIDOC
## GET /api/v1/role

### Description
List roles with optional filtering by `roleName`, `roleKey`, and `status`.

### Method
GET

### Endpoint
/api/v1/role

### Parameters
#### Query Parameters
- **pageIndex** (integer) - Optional - The page number for pagination.
- **pageSize** (integer) - Optional - The number of items per page.
- **roleName** (string) - Optional - Filter by role name.
- **roleKey** (string) - Optional - Filter by role key.
- **status** (string) - Optional - Filter by role status (e.g., "2").

### Request Example
```bash
curl -X GET "http://localhost:8000/api/v1/role?pageIndex=1&pageSize=10&status=2" \
  -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **code** (integer) - Response status code.
- **data** (object) - Role data.
  - **list** (array) - List of roles.
    - **roleId** (integer) - Role ID.
    - **roleName** (string) - Role name.
    - **roleKey** (string) - Role key.
    - **status** (string) - Role status.
    - **dataScope** (string) - Data scope of the role.
  - **count** (integer) - Total number of roles.
  - **pageIndex** (integer) - Current page index.
  - **pageSize** (integer) - Number of items per page.
- **msg** (string) - Response message.

#### Response Example
```json
{
  "code": 200,
  "data": {
    "list": [
      { "roleId": 1, "roleName": "超级管理员", "roleKey": "admin",
        "status": "2", "dataScope": "1" }
    ],
    "count": 1, "pageIndex": 1, "pageSize": 10
  },
  "msg": "查询成功"
}
```
```

--------------------------------

### List Posts

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Retrieves a paginated list of all defined positions or posts.

```APIDOC
## GET /api/v1/post

### Description
List all defined positions/posts with pagination.

### Method
GET

### Endpoint
/api/v1/post

### Query Parameters
- **pageIndex** (integer) - Required - The current page number.
- **pageSize** (integer) - Required - The number of items per page.

### Response
#### Success Response (200)
- **data.list** (array) - An array of post objects, each containing `postId`, `postName`, `postCode`, and `status`.
- **data.count** (integer) - The total number of posts.
- **data.pageIndex** (integer) - The current page index.
- **data.pageSize** (integer) - The number of items per page.
- **msg** (string) - Success message.
```

--------------------------------

### List Users

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Retrieve a list of system users with pagination support. Filtering by username is available, and results respect the caller's data-scope permissions.

```APIDOC
## GET /api/v1/sys-user

### Description
List users with pagination; supports filtering by `username`. Respects the caller's data-scope permission.

### Method
GET

### Endpoint
/api/v1/sys-user

### Parameters
#### Query Parameters
- **pageIndex** (integer) - Required - The index of the page to retrieve.
- **pageSize** (integer) - Required - The number of items per page.
- **username** (string) - Optional - Filters the list of users by username.

### Response
#### Success Response (200)
- **code** (integer) - The status code of the response.
- **data** (object) - Contains the list of users and pagination details.
  - **list** (array) - An array of user objects.
    - **userId** (integer) - The unique identifier for the user.
    - **username** (string) - The user's login name.
    - **nickName** (string) - The user's nickname.
    - **phone** (string) - The user's phone number.
    - **email** (string) - The user's email address.
    - **sex** (string) - The user's sex (e.g., '1' for male, '2' for female).
    - **status** (string) - The user's status (e.g., '2' for active).
    - **deptId** (integer) - The ID of the department the user belongs to.
    - **postId** (integer) - The ID of the post the user holds.
    - **roleId** (integer) - The ID of the role assigned to the user.
  - **count** (integer) - The total number of users matching the criteria.
  - **pageIndex** (integer) - The current page index.
  - **pageSize** (integer) - The number of items per page.
- **msg** (string) - A message indicating the result of the operation.

### Response Example
```json
{
  "code": 200,
  "data": {
    "list": [
      { "userId": 1, "username": "admin", "nickName": "Admin", "phone": "18888888888",
        "email": "admin@example.com", "sex": "1", "status": "2",
        "deptId": 1, "postId": 1, "roleId": 1 }
    ],
    "count": 1,
    "pageIndex": 1,
    "pageSize": 10
  },
  "msg": "查询成功"
}
```
```

--------------------------------

### Login

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Authenticate with username and password to obtain a JWT Bearer token. This token is required for all subsequent authenticated requests.

```APIDOC
## POST /api/v1/login

### Description
Authenticate with username and password; returns a JWT Bearer token used in all subsequent requests.

### Method
POST

### Endpoint
/api/v1/login

### Parameters
#### Request Body
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.

### Request Example
```json
{
  "username": "admin",
  "password": "123456"
}
```

### Response
#### Success Response (200)
- **code** (integer) - The status code of the response.
- **data** (object) - Contains the authentication token and its expiry.
  - **token** (string) - The JWT Bearer token.
  - **expire** (string) - The expiration timestamp of the token.
- **msg** (string) - A message indicating the result of the operation.

### Response Example
```json
{
  "code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expire": "2024-01-01T12:00:00+08:00"
  },
  "msg": "登录成功"
}
```
```

--------------------------------

### Login and Obtain JWT Token

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Authenticate with username and password to receive a JWT Bearer token. This token is required for subsequent authenticated requests.

```bash
curl -X POST http://localhost:8000/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "123456"}'
```

```json
# Expected response
# {
#   "code": 200,
#   "data": {
#     "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
#     "expire": "2024-01-01T12:00:00+08:00"
#   },
#   "msg": "登录成功"
# }
```

--------------------------------

### Add Department - POST /api/v1/dept

Source: https://context7.com/go-admin-team/go-admin/llms.txt

Use this endpoint to add a new department to the organizational hierarchy. Requires authentication and a JSON payload with department details.

```bash
curl -X POST http://localhost:8000/api/v1/dept \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "parentId": 1,
    "deptName": "QA部门",
    "orderNum": 3,
    "leader": "Jane",
    "phone": "02100000000",
    "email": "qa@example.com",
    "status": "1"
  }'
```