# Mokee Gateway 系统接入完整指南

> 版本：2026-06-13 | 适用于所有需要通过 Mokee Gateway 统一登录的业务系统

---

## 目录

1. [架构概览](#一架构概览)
2. [接入流程](#二接入流程)
3. [前端接入（完整代码）](#三前端接入完整代码)
4. [后端接入（完整代码）](#四后端接入完整代码)
5. [API 接口参考（完整请求/响应结构）](#五api-接口参考)
6. [数据库初始化](#六数据库初始化)
7. [创建管理员账号](#七创建网关管理员账号)
8. [创建管理员账号](#七创建网关管理员账号)
9. [UserChip Widget 一键接入](#八usership-widget-一键接入)
10. [对接测试清单](#九对接测试清单)

---

## 一、架构概览

```
┌──────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  业务前端      │────▶│  Mokee Gateway    │────▶│  业务后端         │
│  (Vue/React)   │     │  gw.server.zgitm.com    │     │  (任意语言)       │
│               │     │                  │     │                  │
│  携带 Token    │     │  验证 Token       │     │  从请求头读取:    │
│  + X-System-Code    │  识别系统编码      │     │  X-User-Id       │
│               │     │  转发请求         │     │  X-User-Name     │
│               │     │  注入用户信息头    │     │  X-System-Code   │
└──────────────┘     └──────────────────┘     └──────────────────┘
```

### 流程

1. 用户访问业务前端 → 无 Token → 跳转统一登录页
2. 登录成功 → 获得 JWT Token → 回跳到业务前端
3. 业务前端所有 API 请求 → 网关 (携带 Authorization + X-System-Code)
4. 网关验证 Token → 注入用户信息请求头 → 转发到业务后端
5. 业务后端从请求头读取用户信息 → 执行业务逻辑

### 三条关键规则

**规则一：前端只调网关** — 业务前端 baseURL 配置为网关地址，不能直接调业务后端。

**规则二：后端必须开跨域 (CORS)** — 业务后端需要允许来自网关域名的跨域请求。

**规则三：业务后端不再做登录/鉴权** — Token 验证由网关完成，业务后端只需从请求头读取用户信息。

---

## 二、接入流程

1. 在网关管理后台注册业务系统 → 获得 `systemCode` 和 `docToken`
2. 在网关数据库执行初始化 SQL → 创建菜单和角色
3. 前端接入：配置 Axios 实例 + 路由守卫
4. 后端接入：配置 CORS + UserContext 中间件
5. 创建管理员账号 → 登录管理后台维护本系统数据
6. 对接测试 → 完成验收

---

## 三、前端接入（完整代码）

### 3.1 安装依赖

```bash
npm install axios
```

### 3.2 环境变量

```env
VITE_GATEWAY_URL = https://gw.server.zgitm.com
VITE_LOGIN_URL   = https://web.gw.zgitm.com/login
VITE_SYSTEM_CODE = YOUR_SYSTEM_CODE
```

| 变量 | 说明 | 从哪里获取 |
|------|------|-----------|
| `VITE_GATEWAY_URL` | 网关 API 地址 | 固定值，见附录地址表 |
| `VITE_LOGIN_URL` | 统一登录页地址 | 固定值，见附录地址表 |
| `VITE_SYSTEM_CODE` | 你的业务系统编码 | 在网关管理后台注册系统后获得（联系平台管理员） |

### 3.3 Axios 实例 (src/utils/request.ts)

```typescript
import axios from 'axios'
import { ElMessage } from 'element-plus'

const SYSTEM_CODE = import.meta.env.VITE_SYSTEM_CODE

const request = axios.create({
  baseURL: import.meta.env.VITE_GATEWAY_URL,
  timeout: 30000,
})

// 从 Cookie 读取 Token（登录后网关写入的跨域 Cookie）
function getToken(): string | null {
  const match = document.cookie.match(/(?:^|;\s*)token=([^;]*)/)
  return match ? decodeURIComponent(match[1]) : null
}

// 请求拦截器：携带 Token 和系统编码
request.interceptors.request.use(config => {
  const token = getToken()
  if (token) {
    config.headers.Authorization = `Bearer ${token}`
  }
  // 关键：网关根据此头识别业务系统
  config.headers['X-System-Code'] = SYSTEM_CODE
  return config
})

// 响应拦截器：401 自动跳转登录
request.interceptors.response.use(
  res => res.data.code === 200 ? res.data : Promise.reject(res.data),
  err => {
    if (err.response?.status === 401) {
      window.location.href = `${import.meta.env.VITE_LOGIN_URL}?systemCode=${SYSTEM_CODE}`
    }
    return Promise.reject(err)
  }
)

export default request
```

### 3.4 路由守卫 (src/router/index.ts)

```typescript
import { createRouter, createWebHistory } from 'vue-router'

const SYSTEM_CODE = import.meta.env.VITE_SYSTEM_CODE
const LOGIN_URL  = import.meta.env.VITE_LOGIN_URL

const router = createRouter({
  history: createWebHistory(),
  routes: [ /* 你的路由 */ ],
})

router.beforeEach((to, _from, next) => {
  const token = document.cookie.match(/(?:^|;\s*)token=([^;]*)/)?.[1]
  if (!token && to.path !== '/login') {
    // 无 Token → 跳统一登录页
    window.location.href = `${LOGIN_URL}?systemCode=${SYSTEM_CODE}`
    return
  }
  next()
})

export default router
```

### 3.5 登录成功回调处理

用户在统一登录页登录成功后，网关将 Token 写入 **Cookie**（domain: `.zgitm.com`，跨子域共享），然后跳回系统注册时填写的 `frontUrl`（即你的业务前端首页地址）。业务前端无需自行实现登录接口，只需从 Cookie 中读取 Token 即可。

```typescript
// 从 Cookie 读取 Token
function getToken(): string | null {
  const match = document.cookie.match(/(?:^|;\s*)token=([^;]*)/)
  return match ? decodeURIComponent(match[1]) : null
}

// App.vue onMounted 或 main.ts
const token = getToken()
if (token) {
  // 用户已登录，正常渲染应用
  // 如需获取用户信息，调用网关 API：
  const res = await request.get('/zgapi/v1/auth/user/info')
  console.log('当前用户:', res.data)
} else {
  // 无 Token → 跳统一登录页
  window.location.href = `${import.meta.env.VITE_LOGIN_URL}?systemCode=${SYSTEM_CODE}`
}
```

#### 多系统场景说明

一个用户可能绑定了多个业务系统。跳转登录页时在 URL 中带上 `systemCode` 参数，登录页会自动选择对应系统：

```
https://web.gw.zgitm.com/login?systemCode=YOUR_SYSTEM_CODE
```

这就是为什么路由守卫和 Axios 拦截器中跳转登录时都要拼 `?systemCode=${SYSTEM_CODE}`——网关登录页根据这个参数知道用户要从哪个系统登录，登录成功后直接回跳到该系统的 `frontUrl`。

> **💡 Token 存储说明**：Token 存在 Cookie 中（而非 localStorage），因为 Cookie 支持跨子域共享（`.zgitm.com`），统一登录、管理后台、文件服务等不同子站都能读取到同一个 Token。Cookie 有效期 2 小时，与 Token 过期时间一致。

### 3.6 按钮权限控制（v-permission 指令）

用户信息接口（`/zgapi/v1/auth/user/info`）会返回 `permissions` 字段（按钮权限标识列表），前端据此控制按钮的显示/隐藏。你需要注册一个 `v-permission` 自定义指令：

**src/directives/permission.ts：**

```typescript
import type { Directive } from 'vue'

// 从 Cookie 读取 Token，解析出 payload 中的 permissions
// 或从 Vuex/Pinia store 中读取（取决于你的状态管理方案）
function getPermissions(): string[] {
  const token = document.cookie.match(/(?:^|;\s*)token=([^;]*)/)?.[1]
  if (!token) return []
  try {
    // JWT payload 在中间那段（Base64）
    const payload = JSON.parse(atob(token.split('.')[1]))
    return payload.permissions ?? []
  } catch {
    return []
  }
}

export const permission: Directive = {
  mounted(el, binding) {
    const permissions = getPermissions()
    const required = binding.value as string
    // 如果用户没有该权限，隐藏按钮
    if (!permissions.includes(required)) {
      el.parentNode?.removeChild(el)
    }
  },
}
```

**src/main.ts 中全局注册：**

```typescript
import { createApp } from 'vue'
import App from './App.vue'
import { permission } from './directives/permission'

const app = createApp(App)
app.directive('permission', permission)
app.mount('#app')
```

**业务代码中使用：**

```html
<template>
  <!-- 只有拥有 system:user:add 权限的用户才能看到"新增"按钮 -->
  <el-button type="primary" v-permission="'system:user:add'">新增用户</el-button>
  <el-button v-permission="'system:user:edit'">编辑</el-button>
  <el-button type="danger" v-permission="'system:user:delete'">删除</el-button>
</template>
```

> **原理**：后端返回的 `permissions` 就是你在 `sys_menu` 表里配置的 `permission` 字段值（menu_type=3 的按钮记录）。它们通过角色绑定到用户，登录时返回。前端 `v-permission` 指令检查当前用户是否有该权限，没有就从 DOM 中移除元素。

---

## 四、后端接入（完整代码）

### 4.1 网关转发时注入的请求头

| 请求头名称 | 数据类型 | 说明 |
|-----------|---------|------|
| `X-User-Id` | String | 当前登录用户的唯一ID |
| `X-User-Name` | String | 用户真实姓名 |
| `X-User-Account` | String | 用户登录账号 |
| `X-User-Email` | String | 用户邮箱 |
| `X-User-Post` | String | 用户岗位 |
| `X-User-Roles` | JSON | 用户角色列表 `[{roleId, roleName, roleCode}]` |
| `X-System-Id` | String | 当前业务系统的数据库ID |
| `X-System-Code` | String | 当前业务系统的唯一编码 |
| `X-System-Name` | String | 当前业务系统的显示名称 |

> **重要**：这些请求头由网关自动注入，业务后端可以信任这些值。不需要再验证 Token 或查询用户信息。

### 4.2 Java — UserContext 工具类

```java
// ====== UserContext.java ======
import java.util.*;

public class UserContext {
    private static final ThreadLocal<Map<String, String>> CTX = new ThreadLocal<>();

    public static void set(Map<String, String> user)  { CTX.set(user); }
    public static Map<String, String> get()            { return CTX.get(); }
    public static void clear()                          { CTX.remove(); }

    // 快捷方法
    public static String getUserId()     { return get().get("X-User-Id"); }
    public static String getUserName()   { return get().get("X-User-Name"); }
    public static String getUserAccount(){ return get().get("X-User-Account"); }
    public static String getSystemCode() { return get().get("X-System-Code"); }
    public static String getSystemId()   { return get().get("X-System-Id"); }
}

// ====== UserContextFilter.java ======
import jakarta.servlet.*;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.stereotype.Component;
import java.io.IOException;
import java.util.*;

@Component
public class UserContextFilter implements Filter {
    private static final String[] HEADERS = {
        "X-User-Id", "X-User-Name", "X-User-Account",
        "X-User-Email", "X-User-Post", "X-User-Roles",
        "X-System-Id", "X-System-Code", "X-System-Name"
    };

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws IOException, ServletException {
        HttpServletRequest request = (HttpServletRequest) req;
        Map<String, String> user = new HashMap<>();
        for (String h : HEADERS) {
            String v = request.getHeader(h);
            if (v != null) user.put(h, v);
        }
        UserContext.set(user);
        try {
            chain.doFilter(req, res);
        } finally {
            UserContext.clear();
        }
    }
}

// ====== 业务代码中使用 ======
@RestController
public class OrderController {

    @GetMapping("/api/orders")
    public List<Order> list() {
        String userId     = UserContext.getUserId();      // "123"
        String userName   = UserContext.getUserName();    // "张三"
        String systemCode = UserContext.getSystemCode();  // "msg"
        return orderService.findByUser(userId, systemCode);
    }
}
```

### 4.3 Python — Flask 中间件

```python
# ====== middleware.py ======
from flask import request, g

USER_HEADERS = [
    'X-User-Id', 'X-User-Name', 'X-User-Account',
    'X-User-Email', 'X-User-Post', 'X-User-Roles',
    'X-System-Id', 'X-System-Code', 'X-System-Name',
]

def user_context_middleware():
    """将网关注入的用户信息存到 Flask g 对象"""
    for h in USER_HEADERS:
        val = request.headers.get(h)
        if val:
            setattr(g, h.replace('-', '_').lower(), val)

# 注册到 app
# app.before_request(user_context_middleware)

# ====== 业务代码中使用 ======
from flask import g

@app.route('/api/orders')
def list_orders():
    user_id     = g.x_user_id       # "123"
    user_name   = g.x_user_name     # "张三"
    system_code = g.x_system_code   # "msg"
    return order_service.query(user_id, system_code)
```

### 4.4 Go — 中间件

```go
// ====== middleware.go ======
package middleware

import (
    "context"
    "net/http"
)

type contextKey string

func UserContext(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()
        for _, h := range []string{
            "X-User-Id", "X-User-Name", "X-User-Account",
            "X-User-Email", "X-User-Roles",
            "X-System-Id", "X-System-Code",
        } {
            if v := r.Header.Get(h); v != "" {
                ctx = context.WithValue(ctx, contextKey(h), v)
            }
        }
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// 快捷函数
func GetUserID(ctx context.Context) string {
    return ctx.Value(contextKey("X-User-Id")).(string)
}
func GetSystemCode(ctx context.Context) string {
    return ctx.Value(contextKey("X-System-Code")).(string)
}

// ====== main.go: 注册中间件 ======
// http.Handle("/api/", middleware.UserContext(yourHandler))

// ====== 业务代码 ======
func listOrders(w http.ResponseWriter, r *http.Request) {
    userID     := middleware.GetUserID(r.Context())     // "123"
    systemCode := middleware.GetSystemCode(r.Context()) // "msg"
    // ...
}
```

### 4.5 Java CORS 配置

```java
@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
            .allowedOriginPatterns("*")
            .allowedMethods("*")
            .allowedHeaders("*")
            .allowCredentials(true);
    }
}
```

> **注意**：`permissions` 字段**仅在当前系统为网关（gateway）时返回**。业务系统调用此接口时 `permissions` 为 `null`，业务系统应通过 §5.2 菜单路由接口获取自身系统的权限列表。

---

## 五、API 接口参考

> 所有接口统一通过网关地址访问：`https://gw.server.zgitm.com`

### 统一响应格式 `Result<T>`

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {},
  "timestamp": 1718294400000
}
```

| code 值 | 含义 | HTTP 状态码 | 说明 |
|---------|------|------------|------|
| `200` | 成功 | 200 | 业务正常返回 |
| `401` | 未登录/Token 过期 | 401 | 前端自动跳转登录页 |
| `403` | 无权限 | 403 | Token 有效但用户无此接口权限 |
| `500` | 服务器错误 | 500 | 后端异常，查看网关日志 |

> **💡 注意**：`code` 和 HTTP 状态码是**两套独立的值**。通常它们保持一致，但判断业务结果应看响应体的 `code` 字段而不是 HTTP status code。响应拦截器里 `res.data.code === 200` 判断成功就是这个道理。

### 接口速查表

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/zgapi/v1/auth/user/info` | 获取当前登录用户信息 |
| GET | `/zgapi/v1/auth/menu/router?systemCode=xxx` | 获取树形菜单路由 + 系统所有权限标识 |
| GET | `/zgapi/v1/auth/system/list` | 获取可切换的业务系统列表 |
| PUT | `/zgapi/v1/auth/password/update?oldPwd=xxx&newPwd=xxx` | 修改当前用户密码 |

---

### 5.1 获取当前用户信息

```
GET /zgapi/v1/auth/user/info
Authorization: Bearer {token}
```

**响应 data (UserInfoVO)：**

```json
{
  "userId": "a1b2c3d4e5f6789012345678",
  "username": "zhangsan",
  "realName": "张三",
  "email": "zhangsan@example.com",
  "phone": "13800138000",
  "avatar": "https://file.wg.zgitm.com/api/download/xxx?token=...",
  "post": "高级工程师",
  "createdAt": "2025-01-15T10:30:00",
  "lastLoginTime": "2026-06-13T09:15:30"
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `userId` | String | 用户UUID |
| `username` | String | 用户名 |
| `realName` | String | 真实姓名 |
| `email` | String | 邮箱 |
| `phone` | String | 手机号 |
| `avatar` | String | 头像URL（可能来自文件服务，每次都需刷新 Token） |
| `post` | String | 岗位 |
| `createdAt` | String | 注册时间 (ISO 8601) |
| `lastLoginTime` | String | 最后登录时间 |

---

### 5.2 获取系统菜单路由

```
GET /zgapi/v1/auth/menu/router?systemCode=YOUR_CODE
Authorization: Bearer {token}
```

**响应 data (MenuRouterResponse)：**

```json
{
  "menu": [
    {
      "id": "menu-001",
      "menuName": "系统管理",
      "menuType": 1,
      "icon": "Setting",
      "permission": null,
      "path": null,
      "name": "系统管理",
      "component": "Layout",
      "sortOrder": 1,
      "status": 1,
      "meta": { "title": "系统管理", "icon": "Setting" },
      "children": [
        {
          "id": "menu-002",
          "menuName": "用户管理",
          "menuType": 2,
          "icon": "User",
          "permission": "system:user:list",
          "path": "/system/user",
          "name": "用户管理",
          "component": "system/user/index",
          "sortOrder": 1,
          "status": 1,
          "meta": { "title": "用户管理", "icon": "User" },
          "children": null
        },
        {
          "id": "menu-003",
          "menuName": "角色管理",
          "menuType": 2,
          "icon": "Avatar",
          "permission": "system:role:list",
          "path": "/system/role",
          "name": "角色管理",
          "component": "system/role/index",
          "sortOrder": 2,
          "status": 1,
          "meta": { "title": "角色管理", "icon": "Avatar" },
          "children": null
        }
      ]
    }
  ],
  "permission": [
    "system:user:list",
    "system:user:add",
    "system:user:edit",
    "system:user:delete",
    "system:role:list",
    "system:role:add",
    "system:role:edit",
    "system:role:delete"
  ]
}
```

| 顶层字段 | 类型 | 说明 |
|------|------|------|
| `menu` | List\<MenuRouterVO\> | 树形菜单路由列表（结构见下表） |
| `permission` | List\<String\> | 该系统所有权限标识（用于前端 v-permission 指令控制按钮显隐） |

**menu[] 中每个菜单节点的字段说明：**
|------|------|------|
| `id` | String | 菜单ID |
| `menuName` | String | 菜单显示名称 |
| `menuType` | Integer | **1=目录**（折叠分组，path=null，component="Layout"）<br>**2=菜单**（页面，有path和component）<br>**3=按钮**（权限点，不在菜单显示） |
| `icon` | String | 图标名称 |
| `permission` | String | 权限标识（如 `system:user:list`） |
| `path` | String | 前端路由路径（目录为 null） |
| `name` | String | 路由名称 |
| `component` | String | Vue 组件路径 |
| `sortOrder` | Integer | 排序号（越小越靠前） |
| `status` | Integer | 0=隐藏, 1=显示 |
| `meta` | Object | `{title, icon}` 路由元数据 |
| `children` | List | 子菜单（叶子节点为 **null**） |

> **注意**：菜单按用户角色过滤，不同角色看到的菜单不同。叶子节点 `children` 为 `null`（非空数组），前端据此判断是否显示展开箭头。

---

### 5.3 获取可切换系统列表

```
GET /zgapi/v1/auth/system/list
Authorization: Bearer {token}
```

**响应 data (List\<SystemVO\>)：**

```json
[
  {
    "systemId": "sys-001",
    "systemCode": "erp",
    "systemName": "ERP系统",
    "frontUrl": "https://erp.example.com",
    "icon": "el-icon-s-shop",
    "description": "企业资源计划管理系统"
  }
]
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `systemId` | String | 系统UUID |
| `systemCode` | String | 系统编码 |
| `systemName` | String | 系统名称 |
| `frontUrl` | String | 前端入口地址 |
| `icon` | String | 系统图标 |
| `description` | String | 系统描述 |

> 列表中不包含网关系统本身（systemCode="gateway"），用户无绑定系统时返回空数组 `[]`。

---

### 5.4 修改当前用户密码

```
PUT /zgapi/v1/auth/password/update?oldPwd={旧密码}&newPwd={新密码}
Authorization: Bearer {token}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `oldPwd` | String | 是 | 旧密码（Query参数） |
| `newPwd` | String | 是 | 新密码（Query参数，至少6位） |

响应：`{"code":200,"msg":"密码修改成功","data":null}`。

需验证旧密码正确后才能修改，修改后需重新登录。

---

## 六、数据库初始化

在网关数据库执行以下 SQL，为你的业务系统创建默认菜单和角色。

### 6.1 涉及的表

#### sys_menu（菜单/权限表）

菜单采用**三级结构**：目录 → 页面菜单 → 按钮权限。后端返回菜单树时按角色过滤，用户只能看到自己角色绑定的菜单。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | VARCHAR(64) | 是 | UUID 主键，用 `REPLACE(UUID(),'-','')` 生成 |
| `system_id` | VARCHAR(64) | 是 | 所属业务系统的 ID，从 `sys_system` 表查出 |
| `parent_id` | VARCHAR(64) | 是 | 父菜单 ID，顶级菜单填 `'0'`，子菜单填父菜单的 ID |
| `menu_name` | VARCHAR(64) | 是 | 菜单显示名称（如"用户管理"、"新增用户"） |
| `menu_path` | VARCHAR(256) | 否 | 前端路由路径。**目录**填 `/xxx`，**页面菜单**填 `/xxx/yyy`，**按钮**填 `NULL` |
| `component` | VARCHAR(256) | 否 | Vue 组件路径。**目录**固定填 `'Layout'`，**页面菜单**填 `'xxx/yyy/index'`，**按钮**填 `NULL` |
| `icon` | VARCHAR(128) | 否 | 图标名称（Element Plus 图标）。**目录/菜单**填写，**按钮**填空串 `''` |
| `menu_type` | TINYINT | 是 | **1=目录**（侧边栏折叠分组，不对应具体页面）<br>**2=页面菜单**（具体页面，可点击跳转）<br>**3=按钮**（页面内的操作按钮，不显示在菜单树上，仅用于后端权限校验） |
| `permission` | VARCHAR(128) | 否 | 权限标识符，命名规范：`{模块}:{资源}:{操作}`。**目录**填 `NULL`，**页面菜单**填 `xxx:yyy:list`，**按钮**填 `xxx:yyy:add/edit/delete` 等 |
| `sort_order` | INT | 是 | 排序号，数字越小越靠前。同级菜单按此字段升序排列 |
| `status` | TINYINT | 是 | 0=隐藏（不在菜单树中返回），1=显示 |

**permission 命名规范示例**：

| 资源 | 页面菜单 (list) | 新增按钮 (add) | 编辑按钮 (edit) | 删除按钮 (delete) |
|------|----------------|---------------|----------------|----------------|
| 用户 | `system:user:list` | `system:user:add` | `system:user:edit` | `system:user:delete` |
| 角色 | `system:role:list` | `system:role:add` | `system:role:edit` | `system:role:delete` |
| 订单 | `biz:order:list` | `biz:order:add` | `biz:order:edit` | `biz:order:delete` |

> 接入方可以自定义 permission 标识，只要和前端 `v-permission` 指令、后端 `@RequirePermission` 注解保持一致即可。

#### sys_role（角色表）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | VARCHAR(64) | 是 | UUID 主键 |
| `system_id` | VARCHAR(64) | 是 | 所属业务系统 ID |
| `role_name` | VARCHAR(64) | 是 | 角色显示名称（如"管理员"、"普通用户"） |
| `role_code` | VARCHAR(64) | 是 | 角色编码（唯一标识，如 `admin`、`user`），同一系统内不可重复 |
| `description` | VARCHAR(256) | 否 | 角色描述 |
| `status` | TINYINT | 是 | 0=禁用，1=启用 |

#### sys_role_menu（角色菜单关联表）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | VARCHAR(64) | 是 | UUID 主键 |
| `role_id` | VARCHAR(64) | 是 | 角色 ID |
| `menu_id` | VARCHAR(64) | 是 | 菜单 ID（含按钮权限） |

> 一条 `sys_role_menu` 记录表示：该角色拥有该菜单/按钮的权限。菜单接口返回时会根据当前用户的角色自动过滤。

### 6.2 初始化 SQL

```sql
-- ============================================
-- {系统名称} 菜单 & 角色初始化 SQL
-- 系统编码: {systemCode}
-- ============================================

-- 0. 获取系统 ID
SET @system_id = (SELECT id FROM sys_system WHERE system_code = '{systemCode}' LIMIT 1);

-- 1. 创建顶级菜单目录（menu_type=1，permission 为 NULL）
--    用变量持有父菜单 UUID，后续子菜单直接引用变量名，无需手动查 ID
--    目录仅作为侧边栏折叠分组，不绑定具体页面，不需要权限标识
SET @menu_sys = REPLACE(UUID(),'-','');
SET @menu_biz = REPLACE(UUID(),'-','');

INSERT INTO sys_menu (id, system_id, parent_id, menu_name, menu_path, component, icon, menu_type, sort_order, status, permission) VALUES
(@menu_sys, @system_id, '0', '系统管理', '/system', 'Layout', 'Setting', 1, 1, 1, NULL),
(@menu_biz, @system_id, '0', '业务管理', '/biz', 'Layout', 'Document', 1, 2, 1, NULL);

-- 2. 创建页面菜单（menu_type=2，permission 为页面访问权限标识）
--    parent_id 直接用上面定义的变量，MySQL 变量在同一个会话内全局可见
--    命名规范：{模块}:{资源}:list
INSERT INTO sys_menu (id, system_id, parent_id, menu_name, menu_path, component, icon, menu_type, sort_order, status, permission) VALUES
(REPLACE(UUID(),'-',''), @system_id, @menu_sys, '用户管理', '/system/user', 'system/user/index', 'User', 2, 1, 1, 'system:user:list'),
(REPLACE(UUID(),'-',''), @system_id, @menu_sys, '角色管理', '/system/role', 'system/role/index', 'Avatar', 2, 2, 1, 'system:role:list'),
(REPLACE(UUID(),'-',''), @system_id, @menu_biz, '订单管理', '/biz/order', 'biz/order/index', 'Tickets', 2, 1, 1, 'biz:order:list');

-- 3. 创建按钮权限（menu_type=3，permission 为按钮操作权限标识）
--    按钮的 parent_id 统一挂在对应页面的父菜单目录下（@menu_sys 或 @menu_biz）
--    按钮不显示在菜单树中，仅用于后端权限校验，path/component/icon 均为 NULL/空串
--    命名规范：{模块}:{资源}:{操作}（add/edit/delete）
INSERT INTO sys_menu (id, system_id, parent_id, menu_name, menu_path, component, icon, menu_type, sort_order, status, permission) VALUES
-- 用户管理按钮
(REPLACE(UUID(),'-',''), @system_id, @menu_sys, '新增用户', NULL, NULL, '', 3, 1, 1, 'system:user:add'),
(REPLACE(UUID(),'-',''), @system_id, @menu_sys, '编辑用户', NULL, NULL, '', 3, 2, 1, 'system:user:edit'),
(REPLACE(UUID(),'-',''), @system_id, @menu_sys, '删除用户', NULL, NULL, '', 3, 3, 1, 'system:user:delete'),
-- 角色管理按钮
(REPLACE(UUID(),'-',''), @system_id, @menu_sys, '新增角色', NULL, NULL, '', 3, 1, 1, 'system:role:add'),
(REPLACE(UUID(),'-',''), @system_id, @menu_sys, '编辑角色', NULL, NULL, '', 3, 2, 1, 'system:role:edit'),
(REPLACE(UUID(),'-',''), @system_id, @menu_sys, '删除角色', NULL, NULL, '', 3, 3, 1, 'system:role:delete'),
-- 订单管理按钮
(REPLACE(UUID(),'-',''), @system_id, @menu_biz, '新增订单', NULL, NULL, '', 3, 1, 1, 'biz:order:add'),
(REPLACE(UUID(),'-',''), @system_id, @menu_biz, '编辑订单', NULL, NULL, '', 3, 2, 1, 'biz:order:edit'),
(REPLACE(UUID(),'-',''), @system_id, @menu_biz, '删除订单', NULL, NULL, '', 3, 3, 1, 'biz:order:delete');

-- 4. 创建角色（用变量持有角色 UUID，供后续步骤 5 分配用户时引用）
SET @role_admin = REPLACE(UUID(),'-','');
SET @role_user  = REPLACE(UUID(),'-','');

INSERT INTO sys_role (id, system_id, role_name, role_code, description, status) VALUES
(@role_admin, @system_id, '管理员', 'admin', '拥有全部权限', 1),
(@role_user,  @system_id, '普通用户', 'user', '拥有基本权限', 1);

-- 5. 将本系统所有菜单（含按钮权限）分配给管理员角色
INSERT INTO sys_role_menu (id, role_id, menu_id)
SELECT REPLACE(UUID(),'-',''), @role_admin, m.id
FROM sys_menu m WHERE m.system_id = @system_id;

-- 6. （可选）为普通用户分配菜单——根据实际需求手动给 user 角色分配菜单
-- INSERT INTO sys_role_menu (id, role_id, menu_id)
-- SELECT REPLACE(UUID(),'-',''), @role_user, m.id
-- FROM sys_menu m WHERE m.system_id = @system_id
--   AND m.menu_type != 3;  -- 普通用户只分配页面菜单，不给按钮权限
```

> **💡 普通用户 (user) 角色**：初始化 SQL 只给管理员分配了菜单，普通用户角色默认<b>没有任何菜单权限</b>。这是因为不同系统对普通用户的权限要求不同，无法预置。接入后请登录管理后台，在「角色管理」中手动为 `user` 角色分配菜单。或者取消上面第 6 步的注释，给普通用户分配所有页面菜单（不含按钮）。

---

## 七、创建网关管理员账号

执行以下 SQL 创建一个应用系统管理员账号，该管理员只能看到自己绑定系统的数据：

```sql
-- ============================================
-- 创建应用系统管理员账号
-- 角色编码: gateway-app-admin (只能看到自己绑定系统的数据)
-- ============================================

-- 1. 创建管理员用户（密码 'admin123' 的 BCrypt 密文，建议自行生成替换）
INSERT INTO sys_user (id, username, password, real_name, email, phone, status, is_deleted)
SELECT REPLACE(UUID(),'-',''), 'admin_{systemCode}',
       '$2a$10$N.zmdr9k7uOCQb376NoUnuTJ8iAt6Z5EHsM8lE9lBOsl7iKTVKIUi',
       '{系统名称}管理员', 'admin@{systemCode}.com', NULL, 1, 0
FROM DUAL
WHERE NOT EXISTS (SELECT 1 FROM sys_user WHERE username = 'admin_{systemCode}');

-- 2. 绑定管理员到网关系统 (gateway，用于登录管理后台)
INSERT INTO sys_user_system (id, user_id, system_id)
SELECT REPLACE(UUID(),'-',''), u.id, s.id
FROM sys_user u, sys_system s
WHERE u.username = 'admin_{systemCode}'
  AND s.system_code = 'gateway'
  AND NOT EXISTS (
    SELECT 1 FROM sys_user_system us
    WHERE us.user_id = u.id AND us.system_id = s.id
  );

-- 3. 分配 gateway-app-admin 角色（管理后台权限，只能看到自己绑定系统的数据）
INSERT INTO sys_user_role (id, user_id, role_id)
SELECT REPLACE(UUID(),'-',''), u.id, r.id
FROM sys_user u, sys_role r, sys_system s
WHERE u.username = 'admin_{systemCode}'
  AND r.role_code = 'gateway-app-admin'
  AND r.system_id = s.id
  AND s.system_code = 'gateway'
  AND NOT EXISTS (
    SELECT 1 FROM sys_user_role ur
    WHERE ur.user_id = u.id AND ur.role_id = r.id
  );

-- 4. 绑定管理员到自己的业务系统（用于操作本系统的用户/角色/菜单）
INSERT INTO sys_user_system (id, user_id, system_id)
SELECT REPLACE(UUID(),'-',''), u.id, s.id
FROM sys_user u, sys_system s
WHERE u.username = 'admin_{systemCode}'
  AND s.system_code = '{systemCode}'
  AND NOT EXISTS (
    SELECT 1 FROM sys_user_system us
    WHERE us.user_id = u.id AND us.system_id = s.id
  );

-- 5. 分配本系统的管理员角色（admin，拥有本系统全部菜单权限）
INSERT INTO sys_user_role (id, user_id, role_id)
SELECT REPLACE(UUID(),'-',''), u.id, r.id
FROM sys_user u, sys_role r, sys_system s
WHERE u.username = 'admin_{systemCode}'
  AND r.role_code = 'admin'
  AND r.system_id = s.id
  AND s.system_code = '{systemCode}'
  AND NOT EXISTS (
    SELECT 1 FROM sys_user_role ur
    WHERE ur.user_id = u.id AND ur.role_id = r.id
  );
```

> ⚠️ **如何生成 BCrypt 密文**：
>
> **Python（最方便）**：
> ```bash
> python -c "import bcrypt; print(bcrypt.hashpw(b'your_password', bcrypt.gensalt()).decode())"
> ```
> 如果没装 bcrypt 库：`pip install bcrypt`（Windows 用 `pip install bcrypt`，Linux 用 `pip3 install bcrypt`）。
>
> **Java**：
> ```java
> String hash = BCrypt.hashpw("your_password", BCrypt.gensalt());
> ```
>
> **在线工具**（仅测试环境）：https://www.bcryptcalculator.com
>
> 如果已创建过用户，跳过步骤 1，只执行步骤 2-5。

---

## 八、UserChip Widget 一键接入

在页面右上角添加用户头像和下拉菜单，引入网关提供的 UserChip Widget，按以下三步操作。

> 🚫 **常见错误：`process is not defined`**
> 直接在 `index.html` 中写 `<script src="...user-chip.js">` 会报这个错。原因是 Widget 脚本内部打包了 Vue 3.x，引用了 `process.env.NODE_ENV`，浏览器没有 Node.js 的 `process` 全局变量。正确做法是下面的三步接入。

### 步骤 1：在 index.html 中引入 Widget 样式

```html
<!-- index.html -->
<head>
  <link rel="stylesheet" href="https://web.gw.zgitm.com/widgets/user-chip.css" />
</head>
```

> ⚠️ **注意**：不要在这里引入 JS 脚本，不要在 body 中放占位 div。

### 步骤 2：在 TopBar 组件中放置占位 div

```vue
<!-- src/layouts/components/TopBar.vue -->
<template>
  <header class="topbar">
    <div class="topbar-left">...</div>
    <div class="topbar-right">
      <!-- Mokee Gateway UserChip Widget 占位 -->
      <div id="mokee-user-chip"
           data-api-base="https://gw.server.zgitm.com"
           data-cookie-domain=".zgitm.com"></div>
    </div>
  </header>
</template>

<style scoped>
#mokee-user-chip { flex-shrink: 0; }
</style>
```

> ⚠️ 占位 div 必须在 Vue 组件模板中，这样 Vue mount 后 DOM 中才存在该元素。放在 `index.html` 的 `<body>` 中无效。

### 步骤 3：在 main.js 中挂载后动态加载 Widget 脚本

```javascript
// src/main.js
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

const app = createApp(App)
app.use(router)
app.mount('#app')

// ⚠️ 关键：必须在 mount 之后加载，且需要 process polyfill
window.process = { env: {} }
const widgetScript = document.createElement('script')
widgetScript.src = 'https://web.gw.zgitm.com/widgets/user-chip.js'
document.body.appendChild(widgetScript)
```

### 加载原理

```
index.html 加载
    ↓
<link rel="stylesheet" href="user-chip.css">  ← 样式就绪
    ↓
<script type="module" src="main.js">         ← Vue 入口
    ↓
createApp → mount('#app')                     ← Vue 渲染 TopBar，#mokee-user-chip 出现在 DOM
    ↓
window.process = { env: {} }                  ← polyfill（防止 process is not defined）
    ↓
appendChild(<script src="user-chip.js">)      ← Widget 脚本执行，找到 #mokee-user-chip 并渲染
```

### 组件功能

- 未登录时显示「🔑 登录」按钮，点击跳转统一登录页
- 已登录时显示用户头像 + 用户名，点击弹出下拉菜单

### 下拉菜单（仅两项）

| 菜单项 | 行为 |
|--------|------|
| 🔄 切换系统 | 跳转到系统选择页 |
| 🚪 退出登录 | 清除 Token 并跳转登录页 |

### 配置属性

| 属性 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `data-api-base` | 是 | 无 | 网关 API 地址，生产环境为 `https://gw.server.zgitm.com` |
| `data-login-url` | 否 | 自动推断 | 统一登录页地址，无需配置 |
| `data-select-url` | 否 | 自动推断 | 切换系统页地址，无需配置 |
| `data-cookie-domain` | 否 | 空（仅当前域名） | Cookie 跨域共享域名，跨子域时填 `.zgitm.com` |

### 跨子域共享 Token

如果外部系统和网关在不同子域（如 `app.zgitm.com` 和 `web.gw.zgitm.com`），需配置 Cookie domain：
```html
<div id="mokee-user-chip" data-cookie-domain=".zgitm.com" ...></div>
```

### 排查清单

| 问题 | 检查项 |
|------|--------|
| Widget 不显示 | `#mokee-user-chip` 是否在 Vue 模板中（非 index.html） |
| `process is not defined` | `window.process = { env: {} }` 是否在 Widget 脚本加载前执行 |
| 登录状态不识别 | `data-cookie-domain=".zgitm.com"` 是否配置 |
| 样式错乱 | `user-chip.css` 是否在 index.html 中正确引入 |

### CDN 资源地址

- 样式：`https://web.gw.zgitm.com/widgets/user-chip.css`
- 脚本：`https://web.gw.zgitm.com/widgets/user-chip.js`

---

## 九、对接测试清单

- [ ] 访问业务前端首页 → 自动跳转到统一登录页
- [ ] 使用测试账号登录 → 成功进入业务前端
- [ ] 调用 `GET /zgapi/v1/auth/user/info` → 返回用户信息
- [ ] 调用 `GET /zgapi/v1/auth/menu/router?systemCode=xxx` → 返回菜单树 + 权限列表
- [ ] 业务后端 Controller 中 UserContext.getUserId() 能获取到用户ID
- [ ] 退出登录后访问业务页面 → 重新跳转登录页
- [ ] Widget 组件正常显示头像 + 下拉菜单

---

## 附录：相关地址

| 服务 | 地址 |
|------|------|
| 统一登录页 | `https://web.gw.zgitm.com/login` |
| 系统选择页 | `https://web.gw.zgitm.com/select` |
| API 网关 | `https://gw.server.zgitm.com` |
| 管理后台 | `https://web.gw.zgitm.com/admin` |
| 文件服务 | `https://file.wg.zgitm.com` |
| Widget JS | `https://web.gw.zgitm.com/widgets/user-chip.js` |
| Widget CSS | `https://web.gw.zgitm.com/widgets/user-chip.css` |