### Maven Build Configuration

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Provides Maven commands to build and compile the project with different environment profiles. It includes examples for building specific modules with the 'dev' profile, building all modules with the 'prd' profile, and running a specific service with a profile.

```bash
# Build specific modules with dev profile
mvn clean package -DskipTests=true -Pdev \
  -pl macula-cloud-api,macula-cloud-api/macula-cloud-system-api,macula-cloud-system

# Build all modules with production profile
mvn clean package -DskipTests=true -Pprd

# Available profiles:
# - local (default): Local development
# - dev: Development environment
# - stg: Staging environment
# - pet: Performance testing environment
# - prd: Production environment

# Run specific service
cd macula-cloud-system
mvn spring-boot:run -Pdev

```

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

### OAuth2 Authentication: Get Access Token (Bash)

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Obtains an OAuth2 access token for authentication. This example demonstrates using the password grant type with specified credentials, client ID, and scope.

```bash
curl -X POST "http://localhost:9010/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=password' \
  -d 'username=admin' \
  -d 'password=admin123' \
  -d 'client_id=e4da4a32-592b-46f0-ae1d-784310e88423' \
  -d 'client_secret=secret' \
  -d 'scope=openid profile'
```

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

### Get Menu Routes - API

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Retrieves hierarchical menu structure based on the authenticated user's role permissions. Requires Authorization header.

```bash
curl -X GET "http://localhost:8080/system/api/v1/menus/routes" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

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

### Bound Mini Program Login API

Source: https://github.com/macula-projects/macula-cloud/blob/main/macula-cloud-iam/README.md

Handles login for already bound mini programs using a code. The backend uses `code2session` to get openid/unionid. If not bound, the login will fail.

```HTTP
POST /login/weapp/code
code（后端调用code2session获取openid/unionid,如果没有绑定则调用不成功)
```

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

### Feign Client - Get Menu Routes

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Internal microservice API for retrieving the menu routes for the current user. This is used to dynamically build the frontend navigation based on user roles and permissions.

```APIDOC
## Feign Client: MenuFeignClient.listRoutes

### Description
Internal microservice API for retrieving menu routes for the current user.

### Method
Assumed GET based on Feign client implementation.

### Endpoint
Internal Feign client endpoint (not directly exposed via HTTP).

### Parameters
None (context is derived from the authenticated user).

### Request Example (Conceptual Java)
```java
List<RouteVO> routes = menuFeignClient.listRoutes();
```

### Response
#### Success Response
- **routes** (array of RouteVO) - A hierarchical list of menu routes.
  - **path** (string) - The URL path for the route.
  - **component** (string) - The frontend component path to render.
  - **name** (string) - The name of the route.
  - **meta** (object) - Metadata for the route.
    - **title** (string) - The display title for the route.
    - **icon** (string) - The icon to display for the route.
    - **roles** (array of string) - Roles that can access this route.
  - **children** (array of RouteVO) - Nested child routes.

#### Response Example (Conceptual)
```json
[
  {
    "path": "/dashboard",
    "component": "Layout",
    "name": "Dashboard",
    "meta": {
      "title": "Dashboard",
      "icon": "dashboard"
    },
    "children": []
  },
  {
    "path": "/system",
    "component": "Layout",
    "name": "System",
    "meta": {
      "title": "System",
      "icon": "system"
    },
    "children": [
      {
        "path": "users",
        "component": "/system/user/index",
        "name": "UserManagement",
        "meta": {
          "title": "User Management",
          "roles": ["admin"]
        },
        "children": []
      }
    ]
  }
]
```
```

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

### Get Dictionary Items by Type - API

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Retrieves dictionary items for a specific dictionary type code. Requires Authorization header.

```bash
curl -X GET "http://localhost:8080/system/api/v1/dict/types/gender/items" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

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

### Menu Management - Get Menu Routes

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Retrieves the hierarchical menu structure for the currently authenticated user based on their assigned role permissions.

```APIDOC
## GET /system/api/v1/menus/routes

### Description
Retrieves hierarchical menu structure for current authenticated user based on their role permissions.

### Method
GET

### Endpoint
/system/api/v1/menus/routes

### Response
#### Success Response (200)
- **code** (string) - Response code, '00000' indicates success.
- **data** (array) - An array of menu objects representing the user's accessible routes.
  - **path** (string) - The route path.
  - **component** (string) - The component associated with the route.
  - **name** (string) - The name of the route.
  - **meta** (object) - Metadata for the route.
    - **title** (string) - The title displayed for the menu item.
    - **icon** (string) - The icon associated with the menu item.
    - **roles** (array of strings) - Roles that can access this menu.
  - **children** (array) - Nested menu items.

#### Response Example
```json
{
  "code": "00000",
  "data": [
    {
      "path": "/system",
      "component": "Layout",
      "name": "System",
      "meta": {
        "title": "System Management",
        "icon": "system",
        "roles": ["ADMIN"]
      },
      "children": [
        {
          "path": "user",
          "component": "system/user/index",
          "name": "User",
          "meta": {
            "title": "User Management",
            "icon": "user"
          }
        }
      ]
    }
  ]
}
```
```

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

### User Management - Get Current User

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

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

```APIDOC
## GET /system/api/v1/users/me

### Description
Retrieves authenticated user information including roles, permissions, and menu access.

### Method
GET

### Endpoint
`/system/api/v1/users/me`

### Response
#### Success Response (200)
- **code** (string) - Response code.
- **data** (object) - Contains user information.
  - **userId** (integer) - The ID of the current user.
  - **username** (string) - The username of the current user.
  - **nickname** (string) - The nickname of the current user.
  - **avatar** (string) - URL to the user's avatar.
  - **roles** (array) - Array of roles assigned to the user.
  - **perms** (array) - Array of permissions granted to the user.
  - **deptId** (integer) - The department ID of the current user.

#### Response Example
```json
{
  "code": "00000",
  "data": {
    "userId": 1,
    "username": "admin",
    "nickname": "Administrator",
    "avatar": "https://cdn.example.com/avatar/admin.jpg",
    "roles": ["ADMIN", "SUPER_ADMIN"],
    "perms": ["system:user:add", "system:user:edit", "system:user:delete"],
    "deptId": 1
  }
}
```
```

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

### Feign Client: Get Menu Routes (Java)

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

An internal microservice API call using a Feign client to fetch menu routes for the current user. The response contains a hierarchical menu structure with details like path, component, and metadata.

```java
import dev.macula.cloud.system.api.MenuFeignClient;
import dev.macula.cloud.system.vo.menu.RouteVO;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.List;

@Service
public class MenuService {

    @Autowired
    private MenuFeignClient menuFeignClient;

    public List<RouteVO> loadUserRoutes() {
        List<RouteVO> routes = menuFeignClient.listRoutes();

        // routes contains hierarchical menu structure
        // each RouteVO includes:
        // - path: URL path
        // - component: Frontend component path
        // - name: Route name
        // - meta: Metadata (title, icon, roles)
        // - children: Nested routes

        return routes;
    }
}
```

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

### User Management - Get Current User Info (API)

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Retrieves the details of the currently authenticated user, including their roles, permissions, and menu access. Requires Bearer token authentication.

```bash
curl -X GET "http://localhost:8080/system/api/v1/users/me" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

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

### Feign Client - Get User Login Information

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Internal microservice API for retrieving user authentication information, including roles and permissions. This is used for user session management and authorization.

```APIDOC
## Feign Client: UserFeignClient.getLoginUserInfo

### Description
Internal microservice API for retrieving user authentication information with roles.

### Method
Assumed POST or GET based on Feign client implementation.

### Endpoint
Internal Feign client endpoint (not directly exposed via HTTP).

### Parameters
#### Request Body (DTO)
- **username** (string) - The username for which to retrieve information.
- **dto** (object) - Contains roles and token ID.
  - **roles** (array of string) - List of user roles.
  - **tokenId** (string) - The ID of the authentication token.

### Request Example (Conceptual Java)
```java
UserTokenRolesDTO dto = new UserTokenRolesDTO();
dto.setRoles(roles);
dto.setTokenId(tokenId);
UserLoginVO userInfo = userFeignClient.getLoginUserInfo(username, dto);
```

### Response
#### Success Response
- **userId** (string) - The user's unique identifier.
- **username** (string) - The user's username.
- **nickname** (string) - The user's nickname.
- **avatar** (string) - URL to the user's avatar.
- **roles** (array of string) - List of role codes assigned to the user.
- **perms** (array of string) - List of permission strings granted to the user.
- **deptId** (string) - The ID of the user's department.

#### Response Example (Conceptual)
```json
{
  "userId": "user-123",
  "username": "admin",
  "nickname": "Administrator",
  "avatar": "/avatars/admin.png",
  "roles": ["admin", "editor"],
  "perms": ["user:list", "post:create"],
  "deptId": "dept-abc"
}
```
```

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

### WeChat Mini Program Phone Login API

Source: https://github.com/macula-projects/macula-cloud/blob/main/macula-cloud-iam/README.md

Supports login using WeChat mini program by obtaining the phone number. It has a new version using `code` to get the phone number and an older version using encrypted data. Openid/unionid can be bound.

```HTTP
POST /login/weapp/phone
新版
code（后端通过code获取手机号），再根据手机号查询对应用户
旧版（加密数据，后端用session_key解密得到手机号）
encryptedData
iv
要带上openid/unionid可以绑定
```

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

### Bound Enterprise WeChat Mini Program Login API

Source: https://github.com/macula-projects/macula-cloud/blob/main/macula-cloud-iam/README.md

Handles login for already bound enterprise WeChat mini programs using a code. The backend uses `code2session` to get the user ID. If not bound, the login will fail.

```HTTP
POST /login/qyweapp/code
code（后端调用code2session获取userid，没有绑定登录不成功）
```

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

### OAuth2 Authentication - Get Access Token

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Obtains an OAuth2 access token using various grant types, such as client credentials or password grant. This is the standard way to authenticate and authorize clients.

```APIDOC
## POST /oauth2/token

### Description
Obtains OAuth2 access token using client credentials or password grant.

### Method
POST

### Endpoint
`/oauth2/token`

### Parameters
#### Request Body
- **grant_type** (string) - Required - The grant type being used (e.g., 'password', 'client_credentials').
- **username** (string) - Required if `grant_type` is 'password' - The user's username.
- **password** (string) - Required if `grant_type` is 'password' - The user's password.
- **client_id** (string) - Required - The client application's ID.
- **client_secret** (string) - Required - The client application's secret.
- **scope** (string) - Optional - The scope of the access request.

### Request Example
```bash
curl -X POST "http://localhost:9010/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=password' \
  -d 'username=admin' \
  -d 'password=admin123' \
  -d 'client_id=e4da4a32-592b-46f0-ae1d-784310e88423' \
  -d 'client_secret=secret' \
  -d 'scope=openid profile'
```

### Response
#### Success Response (200)
- **access_token** (string) - The obtained access token.
- **refresh_token** (string) - The refresh token for obtaining new access tokens.
- **token_type** (string) - The type of token (e.g., 'Bearer').
- **expires_in** (integer) - The token's expiration time in seconds.
- **scope** (string) - The granted scope.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile"
}
```
```

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

### Feign Client: Get User Login Information (Java)

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

An internal microservice API call using a Feign client to retrieve user authentication details, including roles. It takes username, roles, and a token ID as input and returns user information.

```java
import dev.macula.cloud.system.api.UserFeignClient;
import dev.macula.cloud.system.dto.UserTokenRolesDTO;
import dev.macula.cloud.system.vo.user.UserLoginVO;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class AuthenticationService {

    @Autowired
    private UserFeignClient userFeignClient;

    public UserLoginVO getUserInfo(String username, List<String> roles, String tokenId) {
        UserTokenRolesDTO dto = new UserTokenRolesDTO();
        dto.setRoles(roles);
        dto.setTokenId(tokenId);

        UserLoginVO userInfo = userFeignClient.getLoginUserInfo(username, dto);

        // userInfo contains:
        // - userId, username, nickname, avatar
        // - roles: List of role codes
        // - perms: List of permission strings
        // - deptId: Department ID

        return userInfo;
    }
}
```

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

### List All Resources - API

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Retrieves a complete list of menu and permission resources, typically used for role assignment. Requires Authorization header.

```bash
curl -X GET "http://localhost:8080/system/api/v1/menus/resources" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

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

### Create New Tenant - API

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Creates a new tenant with specified details including name, code, status, package assignment, expiration time, and contact information. Requires Authorization header and JSON payload.

```bash
curl -X POST "http://localhost:8080/system/api/v1/tenants" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "code": "acme",
    "status": 1,
    "packageId": 2,
    "expireTime": "2025-12-31 23:59:59",
    "contactName": "John Doe",
    "contactPhone": "13800138000",
    "remark": "Enterprise tenant"
  }'
```

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

### Tenant Management - Create New Tenant

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Creates a new tenant with configuration and package assignment. This endpoint is used to onboard new organizations into the multi-tenant system.

```APIDOC
## POST /system/api/v1/tenants

### Description
Creates a new tenant with configuration and package assignment.

### Method
POST

### Endpoint
/system/api/v1/tenants

### Parameters
#### Request Body
- **name** (string) - Required - The name of the tenant.
- **code** (string) - Required - A unique code for the tenant.
- **status** (integer) - Required - The initial status of the tenant (e.g., 1 for active).
- **packageId** (integer) - Required - The ID of the package to assign to the tenant.
- **expireTime** (string) - Required - The expiration time for the tenant's service (format: YYYY-MM-DD HH:MM:SS).
- **contactName** (string) - Optional - The name of the tenant's primary contact.
- **contactPhone** (string) - Optional - The phone number of the tenant's primary contact.
- **remark** (string) - Optional - Additional remarks about the tenant.

### Request Example
```json
{
  "name": "Acme Corporation",
  "code": "acme",
  "status": 1,
  "packageId": 2,
  "expireTime": "2025-12-31 23:59:59",
  "contactName": "John Doe",
  "contactPhone": "13800138000",
  "remark": "Enterprise tenant"
}
```

### Response
#### Success Response (200)
- **code** (string) - Response code, '00000' indicates success.
- **data** (boolean) - Indicates if the tenant creation was successful.

#### Response Example
```json
{
  "code": "00000",
  "data": true
}
```
```

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

### JavaScript DOM Element Initialization and Event Handling

Source: https://github.com/macula-projects/macula-cloud/blob/main/macula-cloud-iam/src/main/resources/templates/login.html

Initializes various DOM elements and sets up click event handlers for toggling between different login forms (normal and no-password). It also manages the visual state of buttons and text colors to indicate the active form.

```javascript
var regTop = document.getElementById('reg-top');
var normal = document.getElementById('normal');
var nopw = document.getElementById('nopw');
var rc = document.getElementById('rc');
var lc = document.getElementById('lc');

normal.onclick = function () {
  rc.style.display = "block";
  lc.style.display = "none";
  regTop.style.display = "block";
  nopw.style.borderBottom = "none";
  normal.style.borderBottom = "1px solid rgb(1 114 229) ";
  nopw.style.color = "#666";
  normal.style.color = "rgb(1 114 229) ";
  rcFlag = true;
  lcFlag = false;
}

nopw.onclick = function () {
  rc.style.display = "none";
  lc.style.display = "block";
  regTop.style.display = "block";
  nopw.style.borderBottom = "1px solid rgb(1 114 229) ";
  normal.style.borderBottom = "none";
  nopw.style.color = "rgb(1 114 229) ";
  normal.style.color = "#666";
  rcFlag = false;
  lcFlag = true;
}
```

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

### User Management - Create User

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Creates a new user, allowing assignment of roles and department.

```APIDOC
## POST /system/api/v1/users

### Description
Creates a new user with role assignments and department association.

### Method
POST

### Endpoint
`/system/api/v1/users`

### Request Body
- **username** (string) - Required - The username for the new user.
- **nickname** (string) - Required - The nickname for the new user.
- **mobile** (string) - Required - The mobile number for the new user.
- **email** (string) - Required - The email address for the new user.
- **password** (string) - Required - The password for the new user.
- **status** (integer) - Required - The status of the user (e.g., 1 for active).
- **deptId** (integer) - Required - The department ID for the user.
- **roleIds** (array) - Required - An array of role IDs to assign to the user.

### Request Example
```json
{
  "username": "jane.smith",
  "nickname": "Jane Smith",
  "mobile": "13900139000",
  "email": "jane@example.com",
  "password": "SecurePass123!",
  "status": 1,
  "deptId": 100,
  "roleIds": [2, 3]
}
```

### Response
#### Success Response (200)
- **code** (string) - Response code.
- **data** (boolean) - Indicates if the user creation was successful.
- **msg** (string) - A message indicating the result of the operation.

#### Response Example
```json
{
  "code": "00000",
  "data": true,
  "msg": "Success"
}
```
```

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

### Dictionary Management - Get Dictionary Items by Type

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Retrieves dictionary items for a specific dictionary type code. This endpoint is useful for fetching predefined lists of values, such as statuses or categories.

```APIDOC
## GET /system/api/v1/dict/types/{typeCode}/items

### Description
Retrieves dictionary items for a specific dictionary type code.

### Method
GET

### Endpoint
/system/api/v1/dict/types/{typeCode}/items

### Parameters
#### Path Parameters
- **typeCode** (string) - Required - The code of the dictionary type (e.g., 'gender').

### Response
#### Success Response (200)
- **code** (string) - Response code, '00000' indicates success.
- **data** (array) - An array of dictionary item objects.
  - **value** (string) - The value of the dictionary item.
  - **label** (string) - The display label of the dictionary item.

#### Response Example
```json
{
  "code": "00000",
  "data": [
    {
      "value": "1",
      "label": "Male"
    },
    {
      "value": "2",
      "label": "Female"
    },
    {
      "value": "0",
      "label": "Unknown"
    }
  ]
}
```
```

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

### Create New Menu - API

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Creates a new menu item with details like parent ID, name, type, path, component, permissions, visibility, sort order, icon, and redirect. Requires Authorization header and JSON payload.

```bash
curl -X POST "http://localhost:8080/system/api/v1/menus" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "parentId": 1,
    "name": "Product Management",
    "type": 1,
    "path": "/product",
    "component": "product/index",
    "perm": "system:product:view",
    "visible": 1,
    "sort": 5,
    "icon": "product",
    "redirect": ""
  }'
```

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

### Compile Macula Cloud Modules with Maven

Source: https://github.com/macula-projects/macula-cloud/blob/main/README.md

This command demonstrates how to compile specific modules of the Macula Cloud project using Maven. It includes options to skip tests, specify a profile (e.g., 'dev'), and select modules for compilation using the '-pl' flag. The 'api' module is mandatory.

```shell
mvn clean package -DskipTests=true -Pdev -pl macula-cloud-api,macula-cloud-api/macula-cloud-system-api,macula-cloud-system
```

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

### Bound Mini Program Login

Source: https://github.com/macula-projects/macula-cloud/blob/main/macula-cloud-iam/README.md

Handles login for already bound mini programs using a WeChat code. Verifies if the mini program is bound.

```APIDOC
## POST /login/weapp/code

### Description
Handles login for mini programs that are already bound to the system. Uses a WeChat code to obtain openid/unionid and verifies the binding.

### Method
POST

### Endpoint
/login/weapp/code

### Parameters
#### Request Body
- **code** (string) - Required - WeChat code obtained from the mini program client

### Request Example
```json
{
  "code": "wechat_mini_program_code"
}
```

### Response
#### Success Response (200)
- **token** (string) - Authentication token

#### Response Example
```json
{
  "token": "generated_auth_token"
}
```
```

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

### List Tenants - API

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Retrieves a paginated list of tenants in a multi-tenant environment. Supports pagination parameters like pageNum and pageSize. Requires Authorization header.

```bash
curl -X GET "http://localhost:8080/system/api/v1/tenants?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

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

### TinyID Service - Get Segment ID

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Retrieves a complete ID segment for local ID generation without requiring network calls for each ID. This optimizes performance for high-throughput ID generation.

```APIDOC
## GET /api/v1/id/nextSegmentId

### Description
Retrieves a complete ID segment for local ID generation without network calls.

### Method
GET

### Endpoint
`/api/v1/id/nextSegmentId`

### Parameters
#### Query Parameters
- **bizType** (string) - Required - The business type for which to generate an ID segment.
- **token** (string) - Required - Authentication token.

### Request Example
```bash
curl -X GET "http://localhost:8080/api/v1/id/nextSegmentId?bizType=order&token=your_token_here"
```

### Response
#### Success Response (200)
- **code** (string) - Response code, "00000" indicates success.
- **data** (object) - Contains information about the ID segment.
  - **currentId** (long) - The starting ID of the current segment.
  - **loadingId** (long) - The ID at which a new segment should be loaded.
  - **maxId** (long) - The maximum ID in the current segment.
  - **delta** (long) - The size of the ID segment.
  - **remainder** (long) - The remaining IDs in the current segment.

#### Response Example
```json
{
  "code": "00000",
  "data": {
    "currentId": 1000000,
    "loadingId": 1050000,
    "maxId": 1100000,
    "delta": 100000,
    "remainder": 0
  }
}
```
```

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

### User Management - Create User (API)

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Creates a new user, allowing for the assignment of roles and association with a department. Requires Bearer token authentication and a JSON payload with user details.

```bash
curl -X POST "http://localhost:8080/system/api/v1/users" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jane.smith",
    "nickname": "Jane Smith",
    "mobile": "13900139000",
    "email": "jane@example.com",
    "password": "SecurePass123!",
    "status": 1,
    "deptId": 100,
    "roleIds": [2, 3]
  }'
```

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

### Layui Form Submission for Account Login

Source: https://github.com/macula-projects/macula-cloud/blob/main/macula-cloud-iam/src/main/resources/templates/login.html

Handles the submission of the account/password login form using layui. It displays a loading indicator, sends an AJAX POST request to the '/login' endpoint, and processes the server response to either redirect the user on success or show an error message.

```javascript
layui.use(['form', 'layer', 'button', 'jquery', 'popup'], function () {
  let form = layui.form;
  let layer = layui.layer;
  let $ = layui.jquery;
  let button = layui.button;
  let popup = layui.popup;

  form.on('submit(do-login)', function (data) {
    let loader = layer.load();
    let btn = button.load({elem: '.login'});

    $.ajax({
      url: '/login',
      data: data.field,
      type: "post",
      dataType: 'json',
      success: function (result) {
        layer.close(loader);
        btn.stop(function () {
          if (result.success) {
            popup.success(result.msg, function () {
              location.href = result.data.targetUrl;
            })
          } else if (result.code === "401") {
            popup.failure(result.msg);
          }
        })
      }
    });
    return false;
  });
  // ... rest of the code
});
```

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

### Create New Role - API

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Creates a new role with specified name, code, and permissions. Requires Authorization header and JSON payload.

```bash
curl -X POST "http://localhost:8080/system/api/v1/roles" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Department Manager",
    "code": "DEPT_MANAGER",
    "sort": 3,
    "status": 1,
    "dataScope": 2,
    "remark": "Department level management role"
  }'
```

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

### TinyID Service: Generate Single ID (Bash)

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Generates a single unique distributed ID for a specified business type using a GET request to the TinyID service. Requires a business type and an optional batch size.

```bash
curl -X GET "http://localhost:8080/api/v1/id/nextId?bizType=order&batchSize=1&token=your_token_here"
```

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

### TinyID Service: Get Segment ID (Bash)

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Retrieves a complete ID segment for local ID generation, allowing for offline ID creation without direct network calls for each ID. This is useful for optimizing performance.

```bash
curl -X GET "http://localhost:8080/api/v1/id/nextSegmentId?bizType=order&token=your_token_here"
```

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

### Menu Management - List All Resources

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Retrieves a complete list of menu and permission resources. This is typically used for role assignment interfaces to provide available options.

```APIDOC
## GET /system/api/v1/menus/resources

### Description
Retrieves complete list of menu and permission resources for role assignment.

### Method
GET

### Endpoint
/system/api/v1/menus/resources

### Response
#### Success Response (200)
- **code** (string) - Response code, '00000' indicates success.
- **data** (array) - An array of resource objects, potentially nested.
  - **value** (integer) - The ID of the resource.
  - **label** (string) - The display name of the resource.
  - **children** (array) - Nested resources, if any.

#### Response Example
```json
{
  "code": "00000",
  "data": [
    {
      "value": 1,
      "label": "System Management",
      "children": [
        {
          "value": 10,
          "label": "User Management"
        },
        {
          "value": 11,
          "label": "Role Management"
        }
      ]
    }
  ]
}
```
```

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

### Create Dictionary Type - API

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Creates a new dictionary type for storing key-value configuration data. Requires Authorization header and JSON payload.

```bash
curl -X POST "http://localhost:8080/system/api/v1/dict/types" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Status",
    "code": "order_status",
    "status": 1,
    "remark": "Dictionary for order status values"
  }'
```

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

### Menu Management - Create New Menu

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Creates a new menu item with associated permissions. This endpoint allows administrators to add new navigation entries to the system.

```APIDOC
## POST /system/api/v1/menus

### Description
Creates a new menu item with associated permissions.

### Method
POST

### Endpoint
/system/api/v1/menus

### Parameters
#### Request Body
- **parentId** (integer) - Optional - The ID of the parent menu, if this is a sub-menu.
- **name** (string) - Required - The name of the menu.
- **type** (integer) - Required - The type of the menu (e.g., 1 for main menu).
- **path** (string) - Required - The path for the menu route.
- **component** (string) - Required - The component associated with the menu.
- **perm** (string) - Optional - The permission string for this menu.
- **visible** (integer) - Optional - Visibility status (e.g., 1 for visible).
- **sort** (integer) - Optional - The sort order for the menu.
- **icon** (string) - Optional - The icon for the menu.
- **redirect** (string) - Optional - Redirect path if applicable.

### Request Example
```json
{
  "parentId": 1,
  "name": "Product Management",
  "type": 1,
  "path": "/product",
  "component": "product/index",
  "perm": "system:product:view",
  "visible": 1,
  "sort": 5,
  "icon": "product",
  "redirect": ""
}
```

### Response
#### Success Response (200)
- **code** (string) - Response code, '00000' indicates success.
- **data** (boolean) - Indicates if the menu creation was successful.

#### Response Example
```json
{
  "code": "00000",
  "data": true
}
```
```

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

### Load Configuration Script with Cache Busting (JavaScript)

Source: https://github.com/macula-projects/macula-cloud/blob/main/macula-cloud-admin/index.html

This snippet dynamically loads the 'config.js' file using document.write. It appends a timestamp to the URL to prevent browser caching, ensuring the latest configuration is always fetched. This is a common technique for managing application configurations.

```javascript
document.write("<script src='config.js?"+new Date().getTime()+"'><\/script>");
```

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

### Application Configuration (application.yml)

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Defines the Spring Cloud Nacos discovery, gateway CORS configurations, security settings with OAuth2 opaque token introspection, Redis connection details, Macula gateway security features, server port, and logging levels. This file is central to the application's behavior and integration with other services.

```yaml
spring:
  cloud:
    nacos:
      discovery:
        enabled: true
        server-addr: localhost:8848
        namespace: dev
    gateway:
      globalcors:
        cors-configurations:
          '[/**]':
            allowed-origin-patterns: "*"
            allowed-methods: "*"
            allowed-headers: "*"
            allow-credentials: true
            max-age: 1800
      routes:
        - id: macula-cloud-system
          uri: lb://macula-cloud-system
          predicates:
            - Path=/system/**
          filters:
            - StripPrefix=1
  security:
    oauth2:
      resourceserver:
        opaquetoken:
          client-id: e4da4a32-592b-46f0-ae1d-784310e88423
          client-secret: secret
          introspection-uri: http://localhost:9010/oauth2/introspect
  redis:
    database: 0
    host: localhost
    port: 6379

macula:
  gateway:
    sign-switch: true          # Enable API signature verification
    force-sign: false          # Force signature check for specific URLs
    crypto-switch: true        # Enable API encryption/decryption
    force-crypto: false        # Force encryption for specific URLs
    protect-urls:
      crypto:
        - /system/api/v1/app
      sign:
        - /system/api/v1/app
    security:
      ignore-urls:
        - /system/api/token

server:
  port: 9999

logging:
  level:
    root: info
    dev.macula.cloud: debug

```

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

### Spring Boot System Service Configuration

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

YAML configuration for the Spring Boot system management microservice. Defines database connection (MySQL with Druid), Redis settings, OAuth2 JWT configuration, Nacos discovery, and server port. Includes custom mybatis-plus type handlers and ignored URLs for security.

```yaml
# application.yml
spring:
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/macula-system?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
    username: root
    password: your_password
  redis:
    database: 0
    host: localhost
    port: 6379
  security:
    oauth2:
      resourceserver:
        jwt:
          jwk-set-uri: http://localhost:9010/oauth2/jwks
  cloud:
    nacos:
      discovery:
        enabled: true
        server-addr: localhost:8848
        namespace: dev

macula:
  security:
    ignore-urls:
      - /api/token
      - /swagger-ui/index.html

mybatis-plus:
  type-handlers-package: dev.macula.boot.starter.mp.handler

server:
  port: 8080

logging:
  level:
    root: info
    dev.macula.cloud: debug
```

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

### Tenant Management - List Tenants

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Retrieves a paginated list of tenants in a multi-tenant environment. Allows filtering and pagination of tenant records.

```APIDOC
## GET /system/api/v1/tenants

### Description
Retrieves paginated list of tenants in multi-tenant environment.

### Method
GET

### Endpoint
/system/api/v1/tenants

### Parameters
#### Query Parameters
- **pageNum** (integer) - Optional - The page number to retrieve.
- **pageSize** (integer) - Optional - The number of records per page.

### Response
#### Success Response (200)
- **code** (string) - Response code, '00000' indicates success.
- **data** (object) - Contains tenant list information.
  - **total** (integer) - The total number of tenants.
  - **records** (array) - An array of tenant objects.
    - **id** (integer) - The tenant ID.
    - **name** (string) - The tenant name.
    - **code** (string) - The tenant code.
    - **status** (integer) - The tenant status.
    - **packageId** (integer) - The ID of the assigned package.
    - **expireTime** (string) - The expiration time of the tenant's service.
    - **createTime** (string) - The creation timestamp of the tenant.

#### Response Example
```json
{
  "code": "00000",
  "data": {
    "total": 10,
    "records": [
      {
        "id": 1,
        "name": "Default Tenant",
        "code": "default",
        "status": 1,
        "packageId": 1,
        "expireTime": "2025-12-31 23:59:59",
        "createTime": "2024-01-01 00:00:00"
      }
    ]
  }
}
```
```

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

### Role Management - List Roles (API)

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Retrieves a paginated list of roles, with support for filtering by role name or code. Requires Bearer token authentication.

```bash
curl -X GET "http://localhost:8080/system/api/v1/roles/pages?pageNum=1&pageSize=10&keywords=admin" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

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

### Bound Enterprise WeChat Mini Program Login

Source: https://github.com/macula-projects/macula-cloud/blob/main/macula-cloud-iam/README.md

Handles login for already bound enterprise WeChat mini programs using a WeChat code. Verifies if the mini program is bound and retrieves the user ID.

```APIDOC
## POST /login/qyweapp/code

### Description
Handles login for enterprise WeChat mini programs that are already bound to the system. Uses a WeChat code to obtain the user ID and verifies the binding.

### Method
POST

### Endpoint
/login/qyweapp/code

### Parameters
#### Request Body
- **code** (string) - Required - WeChat code obtained from the enterprise mini program client

### Request Example
```json
{
  "code": "wechat_enterprise_mini_program_code"
}
```

### Response
#### Success Response (200)
- **token** (string) - Authentication token

#### Response Example
```json
{
  "token": "generated_auth_token"
}
```
```

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

### Assign Menu Permissions to Role - API

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Assigns menu and permission resources to a specific role using its ID. Requires Authorization header and a JSON array of resource IDs.

```bash
curl -X PUT "http://localhost:8080/system/api/v1/roles/2/menus" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '[1, 2, 5, 10, 15, 20]'
```

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

### User Management - List Users (API)

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Retrieves a paginated list of users with options for filtering by username, mobile, status, and department. Requires Bearer token authentication.

```bash
curl -X GET "http://localhost:8080/system/api/v1/users?pageNum=1&pageSize=10&keywords=john&status=1&deptId=100" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"
```

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

### Dictionary Management - Create Dictionary Type

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Creates a new dictionary type for storing key-value configuration data. This allows for dynamic management of application-specific lists.

```APIDOC
## POST /system/api/v1/dict/types

### Description
Creates a new dictionary type for storing key-value configuration data.

### Method
POST

### Endpoint
/system/api/v1/dict/types

### Parameters
#### Request Body
- **name** (string) - Required - The name of the dictionary type.
- **code** (string) - Required - A unique code for the dictionary type.
- **status** (integer) - Optional - The status of the dictionary type (e.g., 1 for active).
- **remark** (string) - Optional - A description for the dictionary type.

### Request Example
```json
{
  "name": "Order Status",
  "code": "order_status",
  "status": 1,
  "remark": "Dictionary for order status values"
}
```

### Response
#### Success Response (200)
- **code** (string) - Response code, '00000' indicates success.
- **data** (boolean) - Indicates if the dictionary type creation was successful.

#### Response Example
```json
{
  "code": "00000",
  "data": true
}
```
```

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

### Role Management - Create New Role

Source: https://context7.com/macula-projects/macula-cloud/llms.txt

Creates a new role with specific permissions. This endpoint allows for the definition of roles by name, code, sort order, status, and data scope.

```APIDOC
## POST /system/api/v1/roles

### Description
Creates a new role with specific permissions.

### Method
POST

### Endpoint
/system/api/v1/roles

### Parameters
#### Request Body
- **name** (string) - Required - The name of the role.
- **code** (string) - Required - A unique code for the role.
- **sort** (integer) - Optional - The sort order for the role.
- **status** (integer) - Optional - The status of the role (e.g., 1 for active).
- **dataScope** (integer) - Optional - The data scope associated with the role.
- **remark** (string) - Optional - A description for the role.

### Request Example
```json
{
  "name": "Department Manager",
  "code": "DEPT_MANAGER",
  "sort": 3,
  "status": 1,
  "dataScope": 2,
  "remark": "Department level management role"
}
```

### Response
#### Success Response (200)
- **code** (string) - Response code, '00000' indicates success.
- **data** (boolean) - Indicates if the role creation was successful.

#### Response Example
```json
{
  "code": "00000",
  "data": true
}
```
```