diff --git a/_backup_20260613/FileController.java b/_backup_20260613/FileController.java
new file mode 100644
index 0000000..6994f85
--- /dev/null
+++ b/_backup_20260613/FileController.java
@@ -0,0 +1,176 @@
+package com.mokee.admin.controller;
+
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.mokee.admin.service.FileService;
+import com.mokee.common.Result;
+import com.mokee.common.annotation.OperationLog;
+import com.mokee.common.entity.SysFile;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.HttpHeaders;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+
+import java.io.IOException;
+import java.net.URLDecoder;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+
+/**
+ * 文件管理控制器
+ *
+ * 文件二进制数据存储于本地磁盘，数据库仅保存元信息。
+ * 向下兼容存量 BLOB 数据（file_data 非空时优先读磁盘，磁盘无文件则回退 DB BLOB）。
+ *
+ * 请求路径前缀：{@code /zgapi/v1/admin/file}
+ *
+ * @author mokee
+ */
+@RestController
+@RequestMapping("/zgapi/v1/admin/file")
+@RequiredArgsConstructor
+public class FileController {
+ private final FileService fileService;
+
+ /**
+ * 上传文件（管理后台）
+ *
+ * 上传者显示名从请求头 X-User-Name 获取（由网关 HeaderInjectFilter 注入，已 URL 解码）。
+ */
+ @OperationLog(module = "文件管理", action = "上传")
+ @PostMapping("/upload")
+ public Result upload(@RequestParam("file") MultipartFile file,
+ @RequestParam(defaultValue = "other") String fileType,
+ @RequestParam(required = false) String systemId,
+ HttpServletRequest request) throws IOException {
+ String userId = request.getHeader("X-User-Id");
+ // X-User-Name 经网关 URL 编码（防 HTTP 转发中文损坏），需解码
+ String userName = decodeHeader(request.getHeader("X-User-Name"));
+ if (userName == null || userName.isEmpty()) {
+ userName = request.getHeader("X-User-Account");
+ }
+ SysFile sf = fileService.upload(file, fileType, systemId, userId, userName);
+ sf.setFileData(null); // 不返回二进制数据
+ return Result.ok(sf);
+ }
+
+ /**
+ * 分页查询文件列表（不含 file_data）
+ */
+ @PostMapping("/page")
+ public Result> page(@RequestBody java.util.Map params) {
+ Integer page = params.get("page") != null ? ((Number) params.get("page")).intValue() : 1;
+ Integer size = params.get("pageSize") != null ? ((Number) params.get("pageSize")).intValue() : 10;
+ String fileType = (String) params.get("fileType");
+ String fileName = (String) params.get("fileName");
+ String uploadUserName = (String) params.get("uploadUserName");
+ String systemId = params.get("systemId") != null ? params.get("systemId").toString() : null;
+ return Result.ok(fileService.page(page, size, fileType, fileName, uploadUserName, systemId));
+ }
+
+ /**
+ * 文件列表查询（不分页，不含 file_data）
+ */
+ @GetMapping("/list")
+ public Result> list(@RequestParam(required = false) String fileType,
+ @RequestParam(required = false) String systemId) {
+ return Result.ok(fileService.list(fileType, systemId));
+ }
+
+ /**
+ * 获取文件元信息（不含二进制数据）
+ */
+ @GetMapping("/{id}")
+ public Result getById(@PathVariable String id) {
+ return Result.ok(fileService.getMetaById(id));
+ }
+
+ /**
+ * 预览文件 — 直接输出文件流
+ *
+ * 优先读磁盘文件；磁盘文件不存在时回退到 DB BLOB（存量兼容）。
+ * 设置 CORS 和缓存头，支持被 img 标签跨域引用。
+ */
+ @GetMapping("/{id}/view")
+ public void view(@PathVariable String id, HttpServletResponse response) throws IOException {
+ SysFile sf = fileService.getById(id);
+ if (sf == null) { response.setStatus(404); return; }
+
+ Path diskPath = fileService.getDiskPath(sf);
+ if (!Files.exists(diskPath)) {
+ response.setStatus(404);
+ response.getWriter().write("File not found");
+ return;
+ }
+
+ byte[] data = Files.readAllBytes(diskPath);
+ response.setHeader(HttpHeaders.ACCESS_CONTROL_ALLOW_ORIGIN, "*");
+ String mimeType = sf.getMimeType() != null ? sf.getMimeType() : "application/octet-stream";
+ response.setContentType(mimeType);
+ response.setHeader(HttpHeaders.CACHE_CONTROL, "public, max-age=86400");
+ response.setContentLengthLong(data.length);
+ response.getOutputStream().write(data);
+ response.getOutputStream().flush();
+ }
+
+ /**
+ * 下载文件 — 触发浏览器下载
+ *
+ * 与 view 逻辑相同，额外设置 Content-Disposition: attachment 头。
+ */
+ @GetMapping("/{id}/download")
+ public void download(@PathVariable String id, HttpServletResponse response) throws IOException {
+ SysFile sf = fileService.getById(id);
+ if (sf == null) { response.setStatus(404); return; }
+
+ Path diskPath = fileService.getDiskPath(sf);
+ if (!Files.exists(diskPath)) {
+ response.setStatus(404);
+ response.getWriter().write("File not found");
+ return;
+ }
+
+ byte[] data = Files.readAllBytes(diskPath);
+ // Content-Disposition: filename=ASCII兜底, filename*=UTF-8编码的原始文件名
+ String safeName = "download" + ext(sf.getFileName());
+ String encodedName = URLEncoder.encode(sf.getFileName(), StandardCharsets.UTF_8)
+ .replace("+", "%20");
+ response.setContentType("application/octet-stream");
+ response.setHeader(HttpHeaders.CONTENT_DISPOSITION,
+ "attachment; filename=\"" + safeName + "\"; filename*=UTF-8''" + encodedName);
+ response.setContentLengthLong(data.length);
+ response.getOutputStream().write(data);
+ response.getOutputStream().flush();
+ }
+
+ /** 从文件名提取扩展名（含点） */
+ private static String ext(String name) {
+ if (name == null) return "";
+ int i = name.lastIndexOf('.');
+ return i > 0 ? name.substring(i) : "";
+ }
+
+ /**
+ * 删除文件 — 删磁盘文件 + DB 记录
+ */
+ @OperationLog(module = "文件管理", action = "删除")
+ @DeleteMapping("/{id}")
+ public Result delete(@PathVariable String id) throws IOException {
+ fileService.delete(id);
+ return Result.ok();
+ }
+
+ /** URL 解码 HTTP 头值（网关对中文值做了 URL 编码） */
+ private String decodeHeader(String value) {
+ if (value == null) return null;
+ try {
+ return URLDecoder.decode(value, StandardCharsets.UTF_8);
+ } catch (Exception e) {
+ return value;
+ }
+ }
+}
diff --git a/_backup_20260613/FileList.vue b/_backup_20260613/FileList.vue
new file mode 100644
index 0000000..40c137d
--- /dev/null
+++ b/_backup_20260613/FileList.vue
@@ -0,0 +1,738 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 搜索
+
+ 重置
+
+
+
+
+ 上传文件
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
将文件拖拽到此处
+
或点击此区域选择文件（支持多选）
+
+
+
+
+
+
+
+
+
+
+
{{ f.file.name }}
+
+ {{ formatSize(f.file.size) }}
+
+
+
+
+
+
+
+
+
+
完成
+
失败
+
+
+
+
+
+
+
+
+
+
+
+
+
![]()
+
{{ row.storageFileName || '-' }}
+
+
+
+
+
+
+
+ {{ fileTypeLabel(row.fileType) }}
+
+
+
+
+
+
+
+ {{ formatSize(row.fileSize) }}
+
+
+
+
+
+
+ {{ row.uploadUserName || '-' }}
+
+
+
+
+
+
+ {{ row.createdAt ? new Date(row.createdAt).toLocaleString('zh-CN') : '-' }}
+
+
+
+
+
+
+
+
+ 下载
+
+
+ 复制链接
+
+
+
+
+ 删除
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ![]()
+
+
+
+
+
+
+
+ * 文件二进制数据存储于本地磁盘，数据库仅保存元信息。
+ *
+ * @author mokee
+ */
+public interface FileService {
+
+ /**
+ * 上传文件 — 写入磁盘 + 存元信息到 DB
+ *
+ * @param file 上传的文件
+ * @param fileType 文件类型
+ * @param systemId 所属系统ID（可选）
+ * @param userId 上传用户ID（可选，管理后台上传时传入）
+ * @param uploadUserName 上传者显示名（用户姓名或系统名称）
+ */
+ SysFile upload(MultipartFile file, String fileType, String systemId,
+ String userId, String uploadUserName) throws IOException;
+
+ /** 分页查询（不含 file_data），支持 fileName/uploadUserName 模糊搜索 */
+ IPage page(Integer page, Integer size, String fileType, String fileName, String uploadUserName, String systemId);
+
+ /** 列表查询（不含 file_data） */
+ List list(String fileType, String systemId);
+
+ /** 查询完整记录（含 file_data 兜底，用于下载/预览） */
+ SysFile getById(String id);
+
+ /** 查询元信息（不含 file_data） */
+ SysFile getMetaById(String id);
+
+ /** 获取文件在磁盘上的存储路径 */
+ Path getDiskPath(SysFile sf);
+
+ /** 删除文件 — 删磁盘文件 + DB 记录 */
+ void delete(String id) throws IOException;
+}
diff --git a/_backup_20260613/FileServiceImpl.java b/_backup_20260613/FileServiceImpl.java
new file mode 100644
index 0000000..3ab3f83
--- /dev/null
+++ b/_backup_20260613/FileServiceImpl.java
@@ -0,0 +1,178 @@
+package com.mokee.admin.service.impl;
+
+import cn.hutool.crypto.digest.MD5;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.mokee.admin.mapper.SysFileMapper;
+import com.mokee.admin.service.ConfigService;
+import com.mokee.admin.service.FileService;
+import com.mokee.common.entity.SysFile;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.web.multipart.MultipartFile;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.util.List;
+
+/**
+ * 文件服务实现 — 文件二进制数据存储于本地磁盘
+ *
+ * 磁盘路径结构：{basePath}/{yyyy-MM}/{storageFileName}
+ * 例：/data/mokee/gw/file/2026-06/a1b2c3d4e5f6.png
+ *
+ * 向下兼容：存量 BLOB 数据（file_data 不为空）仍可正常读取。
+ *
+ * @author mokee
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class FileServiceImpl implements FileService {
+
+ private final SysFileMapper sysFileMapper;
+ private final ConfigService configService;
+
+ private static final DateTimeFormatter YYYY_MM = DateTimeFormatter.ofPattern("yyyy-MM");
+ private static final String DEFAULT_BASE_PATH = "/data/mokee/gw/file";
+
+ /** 获取配置的存储根目录 */
+ private String getBasePath() {
+ return configService.getValue("file.storage.disk.path", DEFAULT_BASE_PATH);
+ }
+
+ /**
+ * 从原始文件名提取扩展名
+ */
+ private String ext(String fileName) {
+ if (fileName == null) return "";
+ int i = fileName.lastIndexOf('.');
+ return i > 0 ? fileName.substring(i) : "";
+ }
+
+ @Override
+ public SysFile upload(MultipartFile file, String fileType, String systemId,
+ String userId, String uploadUserName) throws IOException {
+ byte[] data = file.getBytes();
+
+ // 计算 MD5
+ String md5 = MD5.create().digestHex(data);
+
+ // 构建实体（先生成 ID 用于存储文件名）
+ String fileId = cn.hutool.core.lang.UUID.randomUUID().toString().replace("-", "");
+ String storageFileName = fileId + ext(file.getOriginalFilename());
+ LocalDateTime now = LocalDateTime.now();
+
+ SysFile sf = SysFile.builder()
+ .id(fileId)
+ .systemId(systemId)
+ .fileName(file.getOriginalFilename())
+ .storageFileName(storageFileName)
+ .fileType(fileType != null ? fileType : "other")
+ .fileSize(file.getSize())
+ .mimeType(file.getContentType())
+ .md5(md5)
+ .uploadUserId(userId)
+ .uploadUserName(uploadUserName)
+ .fileData(null) // 新文件不写入 BLOB
+ .createdAt(now)
+ .build();
+
+ // 写入磁盘
+ String basePath = getBasePath();
+ Path dir = Paths.get(basePath, now.format(YYYY_MM));
+ try {
+ Files.createDirectories(dir);
+ } catch (IOException e) {
+ log.error("创建存储目录失败: {} — 请检查磁盘权限和路径配置", dir);
+ throw new IOException("存储目录创建失败: " + dir + " (请检查磁盘权限和路径配置)", e);
+ }
+ Path filePath = dir.resolve(storageFileName);
+ try {
+ Files.write(filePath, data);
+ } catch (IOException e) {
+ log.error("写入文件失败: {} — 可能磁盘空间不足或权限不足", filePath);
+ throw new IOException("文件写入失败: " + filePath + " (可能磁盘空间不足或权限不足)", e);
+ }
+
+ log.info("文件已写入磁盘: {} ({} bytes, md5={})", filePath, file.getSize(), md5);
+
+ // 存元信息到 DB
+ sysFileMapper.insert(sf);
+
+ return sf;
+ }
+
+ @Override
+ public IPage page(Integer page, Integer size, String fileType,
+ String fileName, String uploadUserName, String systemId) {
+ LambdaQueryWrapper w = new LambdaQueryWrapper<>();
+ if (fileType != null && !fileType.isEmpty()) w.eq(SysFile::getFileType, fileType);
+ if (fileName != null && !fileName.isEmpty()) w.like(SysFile::getFileName, fileName);
+ if (uploadUserName != null && !uploadUserName.isEmpty()) w.like(SysFile::getUploadUserName, uploadUserName);
+ if (systemId != null) w.eq(SysFile::getSystemId, systemId);
+ w.orderByDesc(SysFile::getCreatedAt);
+ w.select(SysFile.class, f -> !"file_data".equals(f.getColumn()));
+ return sysFileMapper.selectPage(new Page<>(page, size), w);
+ }
+
+ @Override
+ public List list(String fileType, String systemId) {
+ LambdaQueryWrapper w = new LambdaQueryWrapper<>();
+ if (fileType != null && !fileType.isEmpty()) w.eq(SysFile::getFileType, fileType);
+ if (systemId != null) w.eq(SysFile::getSystemId, systemId);
+ w.orderByDesc(SysFile::getCreatedAt);
+ w.select(SysFile.class, f -> !"file_data".equals(f.getColumn()));
+ return sysFileMapper.selectList(w);
+ }
+
+ @Override
+ public SysFile getById(String id) {
+ return sysFileMapper.selectById(id);
+ }
+
+ @Override
+ public SysFile getMetaById(String id) {
+ LambdaQueryWrapper w = new LambdaQueryWrapper<>();
+ w.eq(SysFile::getId, id);
+ w.select(SysFile.class, f -> !"file_data".equals(f.getColumn()));
+ return sysFileMapper.selectOne(w);
+ }
+
+ @Override
+ public Path getDiskPath(SysFile sf) {
+ String basePath = getBasePath();
+ // 存量兼容：旧文件 storageFileName 为空时，用 id + 扩展名兜底
+ String storageName = sf.getStorageFileName();
+ if (storageName == null || storageName.isEmpty()) {
+ storageName = sf.getId() + ext(sf.getFileName());
+ }
+ return Paths.get(basePath, sf.getCreatedAt().format(YYYY_MM), storageName);
+ }
+
+ @Override
+ public void delete(String id) throws IOException {
+ SysFile sf = sysFileMapper.selectById(id);
+ if (sf == null) return;
+
+ // 删除磁盘文件（失败不阻断 DB 删除）
+ try {
+ Path path = getDiskPath(sf);
+ if (Files.exists(path)) {
+ Files.delete(path);
+ log.info("磁盘文件已删除: {}", path);
+ }
+ } catch (Exception e) {
+ log.warn("删除磁盘文件失败（继续删DB记录） - id: {}, error: {}", id, e.getMessage());
+ }
+
+ // 删除 DB 记录
+ sysFileMapper.deleteById(id);
+ }
+}
diff --git a/_backup_20260613/IntegrationDoc.vue b/_backup_20260613/IntegrationDoc.vue
new file mode 100644
index 0000000..748930d
--- /dev/null
+++ b/_backup_20260613/IntegrationDoc.vue
@@ -0,0 +1,936 @@
+
+
+
+
+
+
+
+
+
+ 1当前系统配置
+
+ {{ sys?.systemCode }}
+ {{ sys?.systemName }}
+ {{ sys?.frontUrl }}
+ {{ sys?.backendUrl }}
+ {{ sys?.description || '-' }}
+
+
+
+
+
+ 2架构概览
+
+
┌──────────────┐ ┌──────────────────┐ ┌──────────────────┐
+│ 业务前端 │────▶│ Mokee Gateway │────▶│ 业务后端 │
+│ (Vue/React) │ │ gw.server.zgitm.com │ │ (任意语言) │
+│ │ │ │ │ │
+│ 携带 Token │ │ 验证 Token │ │ 从请求头读取: │
+│ + SystemCode │ │ 识别系统编码 │ │ X-User-Id │
+│ │ │ 转发请求 │ │ X-User-Name │
+│ │ │ 注入用户信息头 │ │ X-System-Code │
+└──────────────┘ └──────────────────┘ └──────────────────┘
+
+
① 用户访问业务前端 → 无 Token → 跳转统一登录页
+
② 登录成功 → 获得 JWT Token → 回跳到业务前端
+
③ 业务前端所有 API 请求 → 网关 (携带 Authorization + X-System-Code)
+
④ 网关验证 Token → 注入用户信息请求头 → 转发到业务后端
+
⑤ 业务后端从请求头读取用户信息 → 执行业务逻辑
+
+
+
🔴 关键规则一：前端只调网关
+
业务前端的 baseURL 必须配置为 网关地址（如 {{ gatewayUrl }}），绝对不能直接调用业务后端。网关根据请求头 X-System-Code 自动识别并转发到对应后端。
+
+
+
🔴 关键规则二：后端必须开跨域 (CORS)
+
业务后端需要允许来自网关域名的跨域请求。网关转发请求时 origin 是浏览器地址，不是网关地址。
+
Java Spring Boot 配置：
+
@Configuration
+public class CorsConfig implements WebMvcConfigurer {
+ @Override
+ public void addCorsMappings(CorsRegistry registry) {
+ registry.addMapping("/**")
+ .allowedOriginPatterns("*")
+ .allowedMethods("*")
+ .allowedHeaders("*")
+ .allowCredentials(true);
+ }
+}
+
+
+
🔴 关键规则三：业务后端不再做登录/鉴权
+
Token 验证由网关完成。业务后端只需从请求头读取用户信息，不需要再验证 Token、不需要查询用户表。
+
+
+
+
+
+ 3前端接入 (完整代码)
+
+ 3.1 安装依赖
+
+
Shell
+
npm install axios
+
3.2 环境变量 (.env)
+
+
.env
+
VITE_GATEWAY_URL = {{ gatewayUrl }}
+VITE_LOGIN_URL = {{ loginUrl }}
+VITE_SYSTEM_CODE = {{ sys?.systemCode || 'YOUR_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,
+})
+
+// 请求拦截器：携带 Token 和系统编码
+request.interceptors.request.use(config => {
+ const token = localStorage.getItem('token')
+ 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) {
+ localStorage.removeItem('token')
+ 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 = localStorage.getItem('token')
+ if (!token && to.path !== '/login') {
+ // 无 Token → 跳统一登录页
+ window.location.href = `${LOGIN_URL}?systemCode=${SYSTEM_CODE}`
+ return
+ }
+ next()
+})
+
+export default router
+
3.5 登录成功回调处理
+ 统一登录成功后，网关会将 Token 写入 localStorage 并跳回业务前端。业务前端无需处理登录请求，只需从 localStorage 读取 Token。
+
+
TypeScript
+
// main.ts 或 App.vue onMounted
+const token = localStorage.getItem('token')
+if (token) {
+ // 用户已登录，正常渲染应用
+ // 如需获取用户信息，调用网关 API：
+ const res = await request.get('/zgapi/v1/auth/user/info')
+ console.log('当前用户:', res.data)
+}
+
+
+
+
+ 4后端接入 (完整代码)
+
+ 4.1 网关转发到后端时注入的请求头
+
+
+
+
+
+ 重要：这些请求头由网关注入，业务后端可以信任这些值。不需要再验证 Token 或查询用户信息。
+
+ 4.2 Java — UserContext 工具类
+ 用 ThreadLocal 缓存请求头，业务代码零侵入获取用户信息。
+
+
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 (Flask)
+# 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"
+ // ...
+}
+
+
+
+
+ 5API 接口参考
+
+ 5.1 获取当前用户信息
+
+
GET
+
/zgapi/v1/auth/user/info
+
+
+
响应：
+
{
+ "code": 200,
+ "data": {
+ "userId": 1,
+ "username": "admin",
+ "realName": "管理员",
+ "email": "admin@zgitm.com",
+ "phone": "13800000000",
+ "avatar": null,
+ "post": "管理员"
+ }
+}
+
+
5.2 获取系统菜单路由
+
+
GET
+
/zgapi/v1/auth/menu/router?systemCode={{ sys?.systemCode || 'YOUR_CODE' }}
+
+
+ 响应：树形菜单结构，包含 path / name / component / children / meta(含 title, icon)
+
+
5.3 退出登录
+
+
POST
+
/zgapi/v1/auth/logout
+
+
+
+
+
+ 6数据库初始化
+ 在网关平台的数据库执行以下 SQL，为「{{ sys?.systemName }}」创建默认菜单和角色。
+
+
+
+
+
+ 7创建网关管理员账号
+
+ 业务系统接入后，系统管理员需要登录网关管理后台维护本系统的菜单和角色。
+ 执行以下 SQL 创建一个应用系统管理员账号（角色编码 gateway-app-admin），该管理员只能看到自己绑定系统的数据。
+
+
+
SQL — 创建应用系统管理员
+
{{ adminSql }}
+
+
⚠️ 注意
+
密码需用 BCrypt 加密。可使用在线工具或 Java BCrypt.hashpw("your_password", BCrypt.gensalt()) 生成密文。
+ 如果已创建过用户，跳过步骤 1，只执行步骤 2 和 3 绑定系统和角色即可。
+
+
+
+
+ 8对接测试清单
+
+
+
+ {{ item.text }}
+
+
+
+
+
+ 9开放 API — 文件上传 / 下载
+
+ 对外开放 API 使用一次性 Token 认证，可用于外部系统上传文件到文件对象存储、或从存储中下载文件。
+ 每个 Token 12 小时内有效，只能使用一次（调用任意接口即消费）。
+
+
+ 9.1 获取一次性 Token
+
+
POST
+
/zgapi/v1/open/token
+
+
请求体：
+
{
+ "systemCode": "{{ sys?.systemCode || 'YOUR_CODE' }}"
+}
+
响应：
+
{
+ "code": 200,
+ "data": {
+ "token": "eyJhbGciOiJIUzM4NCJ9...",
+ "expiresIn": 43200,
+ "systemName": "业务系统名称",
+ "usageNote": "此 Token 只能消费一次，消费后立即失效"
+ }
+}
+
9.2 校验 Token（不消费）
+
+
POST
+
/zgapi/v1/open/token/validate
+
+
请求体：
+
{
+ "token": "eyJhbGciOiJIUzM4NCJ9..."
+}
+
成功响应（Token 有效，未被消费）：
+
{
+ "code": 200,
+ "data": {
+ "valid": true,
+ "systemCode": "gateway",
+ "msg": "Token 有效，未被消费"
+ }
+}
+
⚠ 此接口不会消费 Token，校验通过后 Token 仍可用于后续操作。
+
9.3 标记 Token 已消费
+
+
POST
+
/zgapi/v1/open/token/consume
+
+
请求体：
+
{
+ "token": "eyJhbGciOiJIUzM4NCJ9...",
+ "action": "上传文件"
+}
+
参数说明：
+
+
+
+
+
+
+
成功响应：
+
{
+ "code": 200,
+ "data": {
+ "tokenConsumed": true,
+ "action": "上传文件",
+ "msg": "Token 已标记为已消费"
+ }
+}
+
+ 适用场景：外部系统在自己的业务中消费了 Token（如上传到自有存储），调用此接口告知网关防止重复使用。
+
+
9.4 上传文件
+
+
POST
+
/zgapi/v1/open/file/upload
+
+
+
+
+
+
+
+
curl 示例：
+
# 获取 Token
+TOKEN=$(curl -s -X POST "{{ gatewayUrl }}/zgapi/v1/open/token" \
+ -H "Content-Type: application/json" \
+ -d '{"systemCode":"{{ sys?.systemCode || 'YOUR_CODE' }}"}' | grep -o '"token":"[^"]*"' | cut -d'"' -f4)
+
+# 上传文件（Token 作为 form 字段）
+curl -X POST "{{ gatewayUrl }}/zgapi/v1/open/file/upload" \
+ -F "file=@/path/to/file.png" \
+ -F "token=$TOKEN" \
+ -F "fileType=other"
+
成功响应（Token 已消费）：
+
{
+ "code": 200,
+ "data": {
+ "fileId": "a1b2c3d4e5f6",
+ "fileName": "file.png",
+ "storageFileName": "a1b2c3d4e5f6.png",
+ "fileSize": 51200,
+ "tokenConsumed": true
+ }
+}
+
9.5 下载文件
+
+
GET
+
/zgapi/v1/open/file/{id}/download?token={token}
+
+
curl 示例：
+
# 下载文件（Token 通过 query 参数传递）
+curl -o downloaded.png \
+ "{{ gatewayUrl }}/zgapi/v1/open/file/a1b2c3d4e5f6/download?token=$TOKEN"
+
成功响应：直接返回文件二进制流，Content-Disposition: attachment 触发浏览器下载。
+
错误响应：
+
+
+
+
+
9.6 发送邮件
+
+
POST
+
/zgapi/v1/open/email/send
+
+
请求体：
+
{
+ "to": "user@example.com",
+ "subject": "邮件主题",
+ "content": "<h1>邮件内容</h1>",
+ "contentType": "html"
+}
+
curl 示例：
+
curl -X POST "{{ gatewayUrl }}/zgapi/v1/open/email/send" \
+ -H "Authorization: Bearer $TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{"to":"user@example.com","subject":"通知","content":"<h1>你好</h1>","contentType":"html"}'
+
成功响应：
+
{
+ "code": 200,
+ "data": {
+ "msg": "发送成功",
+ "tokenConsumed": true
+ }
+}
+
+
⚠️ 注意事项
+
1. 每个 Token 只能使用一次，调用任意开放接口（上传/下载/发邮件）即消费。
+ 2. 调用失败不消费 Token，可重试（如邮件发送失败、文件写入失败）。
+ 3. 文件上传大小限制为 2GB，超时时间 12 小时。
+ 4. 下载链接中的 Token 通过 URL 明文传递，请勿在公开页面中暴露。
+ 5. 上传成功后返回 fileId，请妥善保存用于后续下载。
+
+
+
+ * Token 一次消费：每个 token 只能用一次，消费后立即失效
+ * API 文档地址：http://服务地址:9002/doc.html → "对外开放API" 分组
+ */
+@Slf4j
+@RestController
+@RequestMapping("/zgapi/v1/open")
+@RequiredArgsConstructor
+@Tag(name = "对外开放API", description = "使用 systemCode 获取一次性 Token，Token 消费后立即失效。文档: /doc.html")
+public class OpenApiController {
+
+ private final SysSystemMapper sysSystemMapper;
+ private final EmailService emailService;
+ private final FileService fileService;
+ private final SysEmailLogMapper emailLogMapper;
+ private final SysOpenTokenLogMapper openTokenLogMapper;
+ private final JwtUtil jwtUtil;
+ private final RedisUtil redisUtil;
+
+ private static final int OPEN_TOKEN_TTL_MINUTES = 720; // 12小时
+
+ // ==================== Token 获取 ====================
+
+ /**
+ * 获取一次性 API Token
+ *
+ * 每个 Token 只能消费一次（调用任意 /zgapi/v1/open/* 接口即为消费），消费后立即失效。
+ * Token 有效期 2 小时，过期未消费也会失效。
+ */
+ @PostMapping("/token")
+ @Operation(summary = "获取一次性API Token",
+ description = "传入 systemCode 换取 JWT Token。Token 有效期2小时，只能消费一次，消费后立即失效。")
+ public Result> getToken(HttpServletRequest request) {
+ Map body;
+ try { body = readJsonBody(request); } catch (Exception e) { return Result.fail(400, "JSON解析失败"); }
+ String systemCode = body.get("systemCode");
+ if (systemCode == null || systemCode.isEmpty()) {
+ return Result.fail(400, "缺少 systemCode");
+ }
+
+ SysSystem system = sysSystemMapper.selectOne(
+ new LambdaQueryWrapper()
+ .eq(SysSystem::getSystemCode, systemCode)
+ .eq(SysSystem::getStatus, 1)
+ );
+ if (system == null) {
+ return Result.fail(401, "systemCode 无效或系统已停用");
+ }
+
+ String tokenId = UUID.randomUUID().toString();
+ String token = jwtUtil.generateOpenToken(system.getId(), system.getSystemCode(), tokenId, OPEN_TOKEN_TTL_MINUTES * 60L);
+
+ // 缓存到 Redis
+ Map tokenInfo = Map.of(
+ "systemId", system.getId(),
+ "systemCode", system.getSystemCode(),
+ "systemName", system.getSystemName(),
+ "tokenId", tokenId,
+ "type", "open_api"
+ );
+ redisUtil.set("open:token:" + tokenId, JSONUtil.toJsonStr(tokenInfo), OPEN_TOKEN_TTL_MINUTES, TimeUnit.MINUTES);
+
+ // 记录获取日志
+ SysOpenTokenLog log = SysOpenTokenLog.builder()
+ .systemId(system.getId())
+ .systemCode(system.getSystemCode())
+ .tokenId(tokenId)
+ .tokenPreview(token.substring(0, 20) + "..." + token.substring(token.length() - 10))
+ .acquiredAt(LocalDateTime.now())
+ .consumed(0)
+ .build();
+ openTokenLogMapper.insert(log);
+
+ return Result.ok(Map.of(
+ "token", token,
+ "expiresIn", OPEN_TOKEN_TTL_MINUTES * 60,
+ "systemName", system.getSystemName(),
+ "usageNote", "此 Token 只能消费一次，消费后立即失效"
+ ));
+ }
+
+ // ==================== Token 校验（不消费） ====================
+
+ /**
+ * 校验 Token 是否有效（不消费）
+ *
+ * 仅检查 Token 是否存在且未被消费，不做消费标记。
+ * 用于调用方在实际调用前预先确认 Token 可用。
+ */
+ @PostMapping("/token/validate")
+ @Operation(summary = "校验Token是否有效（不消费）",
+ description = "传入 token 检查是否存在且未被消费。注意：此接口不会消费 Token，仅做状态查询。")
+ public Result> validateToken(HttpServletRequest request) {
+ Map body;
+ try { body = readJsonBody(request); } catch (Exception e) { return Result.fail(400, "JSON解析失败"); }
+ String token = body.get("token");
+ if (token == null || token.isEmpty()) {
+ return Result.fail(400, "缺少 token 参数");
+ }
+
+ String tokenId;
+ try {
+ io.jsonwebtoken.Claims claims = jwtUtil.validateToken(token);
+ String type = claims.get("type", String.class);
+ if (!"open_api".equals(type)) {
+ return Result.fail(401, "Token 类型错误，非开放 API Token");
+ }
+ tokenId = jwtUtil.getTokenId(claims);
+ if (tokenId == null) {
+ return Result.fail(401, "Token 无效");
+ }
+ } catch (Exception e) {
+ return Result.fail(401, "Token 无效或已过期");
+ }
+
+ // 检查 Redis 中是否存在
+ if (!redisUtil.exists("open:token:" + tokenId)) {
+ return Result.fail(401, "Token 不存在或已过期");
+ }
+
+ // 检查是否已消费
+ if (redisUtil.exists("open:token:" + tokenId + ":consumed")) {
+ return Result.fail(401, "Token 已被消费");
+ }
+
+ // 从 Redis 获取 Token 信息
+ String redisJson = redisUtil.get("open:token:" + tokenId);
+ String systemCode = "";
+ if (redisJson != null) {
+ cn.hutool.json.JSONObject info = cn.hutool.json.JSONUtil.parseObj(redisJson);
+ systemCode = info.getStr("systemCode", "");
+ }
+
+ return Result.ok(Map.of(
+ "valid", true,
+ "systemCode", systemCode,
+ "msg", "Token 有效，未被消费"
+ ));
+ }
+
+ // ==================== 标记 Token 已消费 ====================
+
+ /**
+ * 标记 Token 为已消费（供外部系统回调）
+ *
+ * 外部系统在自己的业务中消费了 Token 后，调用此接口告知网关标记已消费，
+ * 防止该 Token 被重复使用。
+ */
+ @PostMapping("/token/consume")
+ @Operation(summary = "标记Token已消费",
+ description = "外部系统调用此接口主动标记 Token 已消费。Token 被标记后不可再使用。")
+ public Result> markConsumed(HttpServletRequest request) {
+ Map body;
+ try { body = readJsonBody(request); } catch (Exception e) { return Result.fail(400, "JSON解析失败"); }
+ String token = body.get("token");
+ String action = body.get("action");
+ if (token == null || token.isEmpty()) return Result.fail(400, "缺少 token 参数");
+ if (action == null || action.isEmpty()) return Result.fail(400, "缺少 action 参数（如：发送邮件/上传文件/下载文件）");
+
+ // 验证 Token
+ String tokenId;
+ try {
+ io.jsonwebtoken.Claims claims = jwtUtil.validateToken(token);
+ String type = claims.get("type", String.class);
+ if (!"open_api".equals(type)) return Result.fail(401, "Token 类型错误");
+ tokenId = jwtUtil.getTokenId(claims);
+ if (tokenId == null) return Result.fail(401, "Token 无效");
+ } catch (Exception e) {
+ return Result.fail(401, "Token 无效或已过期");
+ }
+
+ if (!redisUtil.exists("open:token:" + tokenId)) {
+ return Result.fail(401, "Token 不存在或已过期");
+ }
+ if (redisUtil.exists("open:token:" + tokenId + ":consumed")) {
+ return Result.fail(401, "Token 已被消费");
+ }
+
+ // 标记已消费
+ consumeToken(tokenId);
+ recordConsumption(tokenId, request, action);
+
+ return Result.ok(Map.of(
+ "tokenConsumed", true,
+ "action", action,
+ "msg", "Token 已标记为已消费"
+ ));
+ }
+
+ // ==================== 邮件发送（消费 Token） ====================
+
+ /**
+ * 发送邮件 — 消费 Token
+ *
+ * 只有邮件发送成功后才消费 Token，发送失败不消费允许重试。
+ */
+ @PostMapping("/email/send")
+ @Operation(summary = "发送邮件（消费Token）",
+ description = "调用此接口将消费 Token，Token 只能用一次。邮件发送成功后 Token 立即失效，发送失败不消费 Token。")
+ public Result sendEmail(HttpServletRequest request) {
+ // 第1步：验证 Token（不消费，只校验有效性）
+ String tokenId = validateOpenToken(request);
+ if (tokenId == null) {
+ return Result.fail(401, "Token 无效或已消费");
+ }
+
+ // 第2步：读取请求体，兼容 UTF-8/GBK 编码
+ Map body;
+ try {
+ body = readJsonBody(request);
+ } catch (Exception e) {
+ return Result.fail(400, "请求体 JSON 解析失败: " + e.getMessage());
+ }
+
+ String to = body.get("to");
+ String subject = body.get("subject");
+ String content = body.get("content");
+ String contentType = body.getOrDefault("contentType", "html");
+
+ if (to == null || subject == null || content == null) {
+ return Result.fail(400, "缺少必填参数: to, subject, content");
+ }
+
+ // 第3步：先发邮件，成功后再消费 Token
+ SysEmailLog log = SysEmailLog.builder()
+ .toAddress(to)
+ .subject(subject)
+ .content(content)
+ .contentType(contentType)
+ .createdAt(LocalDateTime.now())
+ .build();
+
+ try {
+ if ("html".equals(contentType)) {
+ emailService.sendHtml(to, subject, content);
+ } else {
+ emailService.sendText(to, subject, content);
+ }
+ log.setStatus(1);
+ emailLogMapper.insert(log);
+
+ // 发邮件成功 → 消费 Token（标记已用，不可重试）
+ consumeToken(tokenId);
+ recordConsumption(tokenId, request, "/zgapi/v1/open/email/send");
+
+ return Result.ok(Map.of("msg", "发送成功", "tokenConsumed", true));
+ } catch (Exception e) {
+ log.setStatus(0);
+ log.setErrorMsg(e.getMessage());
+ emailLogMapper.insert(log);
+ // 发送失败不消费 token，允许重试
+ return Result.fail(500, "发送失败: " + e.getMessage());
+ }
+ }
+
+
+ // ==================== 文件上传/下载（消费 Token） ====================
+
+ /**
+ * 开放 API 文件上传 — 消费 Token
+ *
+ * Token 通过 multipart form 字段传递。上传成功后消费 Token。
+ */
+ @PostMapping("/file/upload")
+ @Operation(summary = "上传文件（消费Token）",
+ description = "上传文件到文件对象存储。Token 作为 form 字段传递，上传成功后立即消费 Token。")
+ public Result> uploadFile(
+ @RequestParam("file") MultipartFile file,
+ @RequestParam("token") String token,
+ @RequestParam(defaultValue = "other") String fileType,
+ HttpServletRequest request) {
+
+ // 1. 验证 Token
+ String tokenId = validateOpenTokenFromValue(token);
+ if (tokenId == null) {
+ return Result.fail(401, "Token 无效或已消费");
+ }
+
+ // 2. 从 Redis 获取系统信息
+ String systemId = null;
+ String systemName = null;
+ String redisJson = redisUtil.get("open:token:" + tokenId);
+ if (redisJson != null) {
+ cn.hutool.json.JSONObject info = JSONUtil.parseObj(redisJson);
+ systemId = info.getStr("systemId");
+ systemName = info.getStr("systemName");
+ }
+
+ // 3. 执行上传（上传者显示系统名称）
+ try {
+ SysFile sf = fileService.upload(file, fileType, systemId, null, systemName);
+
+ // 4. 上传成功 → 消费 Token
+ consumeToken(tokenId);
+ recordConsumption(tokenId, request, "/zgapi/v1/open/file/upload");
+
+ return Result.ok(Map.of(
+ "fileId", sf.getId(),
+ "fileName", sf.getFileName(),
+ "storageFileName", sf.getStorageFileName(),
+ "fileSize", sf.getFileSize(),
+ "tokenConsumed", true
+ ));
+ } catch (IOException e) {
+ log.error("开放 API 文件上传失败: {}", e.getMessage());
+ // 上传失败不消费 token
+ return Result.fail(500, "文件上传失败: " + e.getMessage());
+ }
+ }
+
+ /**
+ * 开放 API 文件下载 — 消费 Token
+ *
+ * Token 通过 query 参数传递。下载成功后消费 Token。
+ * 直接输出文件二进制流，设置 Content-Disposition 触发浏览器下载。
+ */
+ @GetMapping("/file/{id}/download")
+ @Operation(summary = "下载文件（消费Token）",
+ description = "下载文件对象存储中的文件。Token 通过 ?token=xxx 参数传递，下载成功后立即消费 Token。")
+ public void downloadFile(@PathVariable String id,
+ @RequestParam("token") String token,
+ HttpServletRequest request,
+ HttpServletResponse response) throws IOException {
+
+ // 1. 验证 Token
+ String tokenId = validateOpenTokenFromValue(token);
+ if (tokenId == null) {
+ response.setContentType("application/json;charset=UTF-8");
+ response.setStatus(401);
+ response.getWriter().write(JSONUtil.toJsonStr(Result.fail(401, "Token 无效或已消费")));
+ return;
+ }
+
+ // 2. 查询文件
+ SysFile sf = fileService.getById(id);
+ if (sf == null) {
+ response.setContentType("application/json;charset=UTF-8");
+ response.setStatus(404);
+ response.getWriter().write(JSONUtil.toJsonStr(Result.fail(404, "文件不存在")));
+ return;
+ }
+
+ // 3. 读取磁盘文件
+ java.nio.file.Path diskPath = fileService.getDiskPath(sf);
+ if (!java.nio.file.Files.exists(diskPath)) {
+ response.setContentType("application/json;charset=UTF-8");
+ response.setStatus(404);
+ response.getWriter().write(JSONUtil.toJsonStr(Result.fail(404, "文件不存在")));
+ return;
+ }
+ byte[] data = java.nio.file.Files.readAllBytes(diskPath);
+
+ // 4. 下载成功 → 消费 Token
+ consumeToken(tokenId);
+ recordConsumption(tokenId, request, "/zgapi/v1/open/file/" + id + "/download");
+
+ // 5. 输出文件流
+ String safeName = "download" + ext(sf.getFileName());
+ String encodedName = URLEncoder.encode(sf.getFileName(), StandardCharsets.UTF_8)
+ .replace("+", "%20");
+ response.setContentType("application/octet-stream");
+ response.setHeader(HttpHeaders.CONTENT_DISPOSITION,
+ "attachment; filename=\"" + safeName + "\"; filename*=UTF-8''" + encodedName);
+ response.setContentLengthLong(data.length);
+ response.getOutputStream().write(data);
+ response.getOutputStream().flush();
+ }
+
+ private static String ext(String name) {
+ if (name == null) return "";
+ int i = name.lastIndexOf('.');
+ return i > 0 ? name.substring(i) : "";
+ }
+
+ // ==================== 私有方法 ====================
+
+ /**
+ * 验证 Open API Token 有效性（不消费）
+ *
仅校验 JWT 合法性 + Redis 中存在且未被消费，不做消费标记
+ */
+ private String validateOpenToken(HttpServletRequest request) {
+ String authHeader = request.getHeader("Authorization");
+ if (authHeader == null || !authHeader.startsWith("Bearer ")) return null;
+ String token = authHeader.substring(7);
+ try {
+ io.jsonwebtoken.Claims claims = jwtUtil.validateToken(token);
+ String tokenId = jwtUtil.getTokenId(claims);
+ if (tokenId == null) return null;
+
+ // 检查 Redis 中 token 是否存在
+ if (!redisUtil.exists("open:token:" + tokenId)) return null;
+
+ // 检查是否已消费
+ String consumedKey = "open:token:" + tokenId + ":consumed";
+ if (redisUtil.exists(consumedKey)) return null;
+
+ return tokenId;
+ } catch (Exception e) {
+ return null;
+ }
+ }
+
+ /**
+ * 消费 Token（标记为已消费，业务操作成功后调用）
+ */
+ private void consumeToken(String tokenId) {
+ redisUtil.set("open:token:" + tokenId + ":consumed", "1", OPEN_TOKEN_TTL_MINUTES, TimeUnit.MINUTES);
+ }
+
+ /**
+ * 记录 Token 消费日志
+ */
+ private void recordConsumption(String tokenId, HttpServletRequest request, String api) {
+ try {
+ SysOpenTokenLog log = new SysOpenTokenLog();
+ log.setTokenId(tokenId);
+ log.setConsumed(1);
+ log.setConsumedAt(LocalDateTime.now());
+ log.setConsumeApi(api);
+ log.setConsumeIp(IpUtil.getClientIp(request));
+
+ // 根据 tokenId 更新记录
+ LambdaQueryWrapper w = new LambdaQueryWrapper<>();
+ w.eq(SysOpenTokenLog::getTokenId, tokenId);
+ openTokenLogMapper.update(log, w);
+ } catch (Exception ignored) {}
+ }
+
+ /**
+ * 验证 Open API Token 有效性（不消费），从原始 token 字符串直接验证
+ * 用于 token 不在 Authorization 头的场景（如 form 字段、query 参数）
+ */
+ private String validateOpenTokenFromValue(String token) {
+ if (token == null || token.isEmpty()) return null;
+ try {
+ io.jsonwebtoken.Claims claims = jwtUtil.validateToken(token);
+ String type = claims.get("type", String.class);
+ if (!"open_api".equals(type)) return null;
+ String tokenId = jwtUtil.getTokenId(claims);
+ if (tokenId == null) return null;
+
+ // 检查 Redis 中 token 是否存在且未被消费
+ if (!redisUtil.exists("open:token:" + tokenId)) return null;
+ if (redisUtil.exists("open:token:" + tokenId + ":consumed")) return null;
+
+ return tokenId;
+ } catch (Exception e) {
+ return null;
+ }
+ }
+
+ /**
+ * 从 HttpServletRequest 读取 JSON 请求体，自动检测 UTF-8/GBK 编码
+ */
+ @SuppressWarnings("unchecked")
+ private Map readJsonBody(HttpServletRequest request) throws java.io.IOException {
+ byte[] bytes = IoUtil.readBytes(request.getInputStream());
+ if (bytes == null || bytes.length == 0) return java.util.Collections.emptyMap();
+
+ String json = new String(bytes, java.nio.charset.StandardCharsets.UTF_8);
+ if (json.indexOf('�') >= 0) {
+ json = new String(bytes, java.nio.charset.Charset.forName("GBK"));
+ }
+ return JSONUtil.toBean(json, Map.class);
+ }
+}
diff --git a/_backup_20260613/SystemConfig.vue b/_backup_20260613/SystemConfig.vue
new file mode 100644
index 0000000..a411c98
--- /dev/null
+++ b/_backup_20260613/SystemConfig.vue
@@ -0,0 +1,85 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 保存配置
+
+
+
+
+
+
+
+
+
+
diff --git a/_backup_20260613/open-api-doc.md b/_backup_20260613/open-api-doc.md
new file mode 100644
index 0000000..72ceb8a
--- /dev/null
+++ b/_backup_20260613/open-api-doc.md
@@ -0,0 +1,449 @@
+# Mokee Gateway 对外开放 API 文档
+
+**网关地址**: `https://gw.server.zgitm.com`
+**版本**: v1
+**更新时间**: 2026-06-13
+
+---
+
+## 1. 概述
+
+对外开放 API 用于外部业务系统接入 Mokee 网关平台，支持获取一次性 Token 并调用邮件发送等功能。
+
+> ⚠️ **编码要求**：所有请求和响应均使用 **UTF-8** 编码。`Content-Type` 必须指定 `charset=UTF-8`，否则中文会出现乱码或解析错误。
+
+### 认证流程
+
+```
+外部系统 ──POST /zgapi/v1/open/token──▶ 获取一次性 Token
+外部系统 ──POST /zgapi/v1/open/token/validate──▶ 校验 Token（不消费）
+外部系统 ──POST /zgapi/v1/open/token/consume──▶ 标记 Token 已消费
+外部系统 ──POST /zgapi/v1/open/email/send──▶ 发送邮件（消费 Token）
+外部系统 ──POST /zgapi/v1/open/file/upload──▶ 上传文件（消费 Token）
+外部系统 ──GET /zgapi/v1/open/file/{id}/download──▶ 下载文件（消费 Token）
+```
+
+### Token 规则
+
+| 规则 | 说明 |
+|------|------|
+| 获取方式 | 传入 `systemCode` 即可获取，无需密钥 |
+| 有效期 | 获取后 **12 小时**内有效 |
+| 消费限制 | 每个 Token **只能使用一次**，调用任意接口即消费 |
+| 消费失败 | 接口调用失败（如邮件发送失败）**不消费** Token，可重试 |
+
+---
+
+## 2. 获取 Token
+
+传入系统编码，获取一次性 JWT Token。
+
+**请求**
+
+```
+POST /zgapi/v1/open/token
+Content-Type: application/json; charset=UTF-8
+```
+
+> **重要**：所有请求 Body 必须使用 **UTF-8** 编码。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:--:|------|
+| systemCode | string | 是 | 系统编码，需在网关平台已注册且启用 |
+
+**请求示例**
+
+```bash
+curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token" \
+ -H "Content-Type: application/json" \
+ -d '{"systemCode": "gateway"}'
+```
+
+**响应**
+
+```json
+{
+ "code": 200,
+ "data": {
+ "token": "eyJhbGciOiJIUzM4NCJ9.eyJzdWIiOi...",
+ "expiresIn": 43200,
+ "systemName": "网关管理平台",
+ "usageNote": "此 Token 只能消费一次，消费后立即失效"
+ }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| code | int | 200=成功 |
+| data.token | string | JWT Token，后续请求放入 Authorization 头 |
+| data.expiresIn | int | 有效时间（秒），43200 = 12小时 |
+| data.systemName | string | 系统名称 |
+| data.usageNote | string | 使用提示 |
+
+**错误响应**
+
+| code | 说明 |
+|:----:|------|
+| 400 | 缺少 `systemCode` 参数 |
+| 401 | `systemCode` 无效或系统已停用 |
+
+---
+
+## 3. 校验 Token（不消费）
+
+检查 Token 是否有效（存在且未被消费）。**此接口不会消费 Token**，仅做状态查询。调用方可在实际操作前预先确认 Token 可用。
+
+**请求**
+
+```
+POST /zgapi/v1/open/token/validate
+Content-Type: application/json; charset=UTF-8
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:--:|------|
+| token | string | 是 | 需要校验的 JWT Token |
+
+**请求示例**
+
+```bash
+curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token/validate" \
+ -H "Content-Type: application/json" \
+ -d '{"token": "eyJhbGciOiJIUzM4NCJ9..."}'
+```
+
+**成功响应（Token 有效，未被消费）**
+
+```json
+{
+ "code": 200,
+ "data": {
+ "valid": true,
+ "systemCode": "gateway",
+ "msg": "Token 有效，未被消费"
+ }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.valid | bool | true = Token 有效可用 |
+| data.systemCode | string | Token 所属的系统编码 |
+| data.msg | string | 状态描述 |
+
+**错误响应**
+
+| code | 说明 |
+|:----:|------|
+| 400 | 缺少 `token` 参数 |
+| 401 | Token 无效、已过期、已被消费、或类型错误 |
+
+> **关键：此接口不会消费 Token。** 校验通过后 Token 仍可用于后续操作。
+
+---
+
+## 4. 标记 Token 已消费
+
+外部系统在自己的业务逻辑中消费了 Token 后（如上传文件到自己的存储），调用此接口告知网关标记 Token 已消费，防止被重复使用。
+
+**请求**
+
+```
+POST /zgapi/v1/open/token/consume
+Content-Type: application/json; charset=UTF-8
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:--:|------|
+| token | string | 是 | 需要标记已消费的 JWT Token |
+| action | string | 是 | 消费动作描述，如 `发送邮件` / `上传文件` / `下载文件` |
+
+**请求示例**
+
+```bash
+curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token/consume" \
+ -H "Content-Type: application/json" \
+ -d '{"token": "eyJhbGciOiJIUzM4NCJ9...", "action": "上传文件"}'
+```
+
+**成功响应**
+
+```json
+{
+ "code": 200,
+ "data": {
+ "tokenConsumed": true,
+ "action": "上传文件",
+ "msg": "Token 已标记为已消费"
+ }
+}
+```
+
+**错误响应**
+
+| code | 说明 |
+|:----:|------|
+| 400 | 缺少 `token` 或 `action` 参数 |
+| 401 | Token 无效、已过期、或已被消费 |
+
+---
+
+## 5. 发送邮件
+
+使用 Token 认证后发送邮件。**调用此接口将消费当前 Token。**
+
+**请求**
+
+```
+POST /zgapi/v1/open/email/send
+Content-Type: application/json; charset=UTF-8
+Authorization: Bearer
+```
+
+> **重要**：请求 Body 必须使用 **UTF-8** 编码。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:--:|------|
+| to | string | 是 | 收件人邮箱地址 |
+| subject | string | 是 | 邮件主题 |
+| content | string | 是 | 邮件内容 |
+| contentType | string | 否 | `html`（默认）或 `text` |
+
+**请求示例**
+
+```bash
+# 先获取 Token
+TOKEN=$(curl -s -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token" \
+ -H "Content-Type: application/json" \
+ -d '{"systemCode":"gateway"}' | sed 's/.*"token":"\([^"]*\)".*/\1/')
+
+# 发送 HTML 邮件
+curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/email/send" \
+ -H "Content-Type: application/json" \
+ -H "Authorization: Bearer $TOKEN" \
+ -d '{
+ "to": "user@example.com",
+ "subject": "通知标题",
+ "content": "您好
这是邮件内容
",
+ "contentType": "html"
+ }'
+```
+
+**成功响应**
+
+```json
+{
+ "code": 200,
+ "data": {
+ "msg": "发送成功",
+ "tokenConsumed": true
+ }
+}
+```
+
+**错误响应**
+
+| code | 说明 |
+|:----:|------|
+| 400 | 缺少必填参数 `to` / `subject` / `content` |
+| 401 | Token 无效、已过期或已消费 |
+| 500 | 邮件发送失败（Token 未消费，可重试） |
+
+---
+
+## 6. 上传文件
+
+使用 Token 认证后上传文件到文件对象存储。**调用此接口将消费当前 Token。**
+
+> 上传成功后返回文件 ID，可用于后续下载。
+
+**请求**
+
+```
+POST /zgapi/v1/open/file/upload
+Content-Type: multipart/form-data
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:--:|------|
+| file | file | 是 | 上传的文件 |
+| token | string | 是 | 开放 API Token（作为 form 字段传递） |
+| fileType | string | 否 | 文件类型: `avatar`/`icon`/`doc`/`other`（默认 `other`） |
+
+**请求示例**
+
+```bash
+# 先获取 Token
+TOKEN=$(curl -s -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token" \
+ -H "Content-Type: application/json" \
+ -d '{"systemCode":"gateway"}' | sed 's/.*"token":"\([^"]*\)".*/\1/')
+
+# 上传文件
+curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/file/upload" \
+ -F "file=@/path/to/avatar.png" \
+ -F "token=$TOKEN" \
+ -F "fileType=avatar"
+```
+
+**成功响应**
+
+```json
+{
+ "code": 200,
+ "data": {
+ "fileId": "a1b2c3d4e5f6",
+ "fileName": "avatar.png",
+ "storageFileName": "a1b2c3d4e5f6.png",
+ "fileSize": 51200,
+ "tokenConsumed": true
+ }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.fileId | string | 文件唯一 ID，用于下载 |
+| data.fileName | string | 原始文件名 |
+| data.storageFileName | string | 磁盘存储的实际文件名 |
+| data.fileSize | long | 文件大小（字节） |
+| data.tokenConsumed | bool | Token 已消费 |
+
+**错误响应**
+
+| code | 说明 |
+|:----:|------|
+| 400 | 缺少 `file` 或 `token` 参数 |
+| 401 | Token 无效、已过期或已消费 |
+| 500 | 文件上传失败（Token 未消费，可重试） |
+
+---
+
+## 7. 下载文件
+
+使用 Token 认证后下载文件。**调用此接口将消费当前 Token。**
+Token 通过 URL query 参数传递。
+
+> **注意**: 每个下载链接的 Token 只能使用一次。如需多次下载，需每次获取新 Token。
+
+**请求**
+
+```
+GET /zgapi/v1/open/file/{id}/download?token=
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:--:|------|
+| id | string | 是 | 文件 ID（路径参数） |
+| token | string | 是 | 开放 API Token（query 参数） |
+
+**请求示例**
+
+```bash
+# 先获取 Token
+TOKEN=$(curl -s -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token" \
+ -H "Content-Type: application/json" \
+ -d '{"systemCode":"gateway"}' | sed 's/.*"token":"\([^"]*\)".*/\1/')
+
+# 下载文件（保存到本地）
+curl -o downloaded.png \
+ "https://gw.server.zgitm.com/zgapi/v1/open/file/a1b2c3d4e5f6/download?token=$TOKEN"
+```
+
+**成功响应**: 直接返回文件二进制流，`Content-Type: application/octet-stream`，`Content-Disposition: attachment`。
+
+**错误响应**
+
+| HTTP 状态码 | code | 说明 |
+|:----------:|:----:|------|
+| 401 | 401 | Token 无效、已过期或已消费 |
+| 404 | 404 | 文件不存在或文件数据丢失 |
+
+---
+
+## 8. Java 调用示例
+
+使用 Hutool 或 OkHttp 均可，以下为 Hutool 示例：
+
+```java
+import cn.hutool.http.HttpRequest;
+import cn.hutool.http.HttpResponse;
+import cn.hutool.json.JSONObject;
+import cn.hutool.json.JSONUtil;
+
+public class OpenApiDemo {
+
+ private static final String BASE = "https://gw.server.zgitm.com";
+
+ public static void main(String[] args) {
+ // 1. 获取 Token
+ JSONObject tokenReq = JSONUtil.createObj().set("systemCode", "gateway");
+ String tokenResp = HttpRequest.post(BASE + "/zgapi/v1/open/token")
+ .header("Content-Type", "application/json; charset=UTF-8")
+ .body(tokenReq.toString())
+ .execute()
+ .body();
+
+ JSONObject tokenJson = JSONUtil.parseObj(tokenResp);
+ String token = tokenJson.getJSONObject("data").getStr("token");
+ System.out.println("Token: " + token.substring(0, 30) + "...");
+
+ // 2. 上传文件
+ JSONObject uploadResp = HttpRequest.post(BASE + "/zgapi/v1/open/file/upload")
+ .form("file", new java.io.File("./avatar.png"))
+ .form("token", token)
+ .form("fileType", "avatar")
+ .execute()
+ .body();
+ System.out.println("上传结果: " + uploadResp);
+
+ // 3. 发送邮件
+ JSONObject emailReq = JSONUtil.createObj()
+ .set("to", "user@example.com")
+ .set("subject", "测试邮件")
+ .set("content", "Hello
这是一封测试邮件
")
+ .set("contentType", "html");
+
+ String emailResp = HttpRequest.post(BASE + "/zgapi/v1/open/email/send")
+ .header("Authorization", "Bearer " + token)
+ .body(emailReq.toString())
+ .execute()
+ .body();
+
+ System.out.println(emailResp);
+ }
+}
+```
+
+### Maven 依赖
+
+```xml
+
+ cn.hutool
+ hutool-all
+ 5.8.28
+
+```
+
+---
+
+## 9. 附录
+
+### 可用系统编码
+
+请联系管理员获取已注册的系统编码，或登录网关管理平台查看。
+
+### 错误码汇总
+
+| HTTP 状态码 | code | 说明 |
+|:----------:|:----:|------|
+| 200 | 200 | 成功 |
+| 200 | 400 | 参数错误 |
+| 200 | 401 | 认证失败 |
+| 200 | 500 | 服务内部错误 |
+
+> **注意**：所有响应 HTTP 状态码均为 200，实际结果通过响应体中的 `code` 字段判断。
+
+### 联系支持
+
+如有问题请联系 Mokee Gateway 管理员。
diff --git a/add_doc_token.sql b/add_doc_token.sql
new file mode 100644
index 0000000..120879c
--- /dev/null
+++ b/add_doc_token.sql
@@ -0,0 +1,5 @@
+-- 系统表新增文档令牌字段
+ALTER TABLE sys_system ADD COLUMN IF NOT EXISTS doc_token VARCHAR(64) DEFAULT NULL COMMENT '文档访问令牌(UUID)';
+
+-- 为已有系统生成随机令牌（16位 hex）
+UPDATE sys_system SET doc_token = SUBSTRING(MD5(UUID()), 1, 16) WHERE doc_token IS NULL;
diff --git a/check_docker.py b/check_docker.py
new file mode 100644
index 0000000..5d3ddb7
--- /dev/null
+++ b/check_docker.py
@@ -0,0 +1,29 @@
+import paramiko
+
+HOST = '10.1.1.170'
+USER = 'root'
+PASS = 'mokee.'
+
+c = paramiko.SSHClient()
+c.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+c.connect(HOST, username=USER, password=PASS, timeout=15)
+
+# 列出所有运行中的 Docker 容器
+_, stdout, _ = c.exec_command('docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}" 2>&1')
+out = stdout.read().decode()
+print('=== Docker 容器列表 ===')
+print(out)
+
+# 也检查一下 /opt/mokee 目录结构
+_, stdout2, _ = c.exec_command('ls -la /opt/mokee/ 2>&1')
+out2 = stdout2.read().decode()
+print('=== /opt/mokee 目录 ===')
+print(out2)
+
+# 查找与 mokee 相关的所有容器
+_, stdout3, _ = c.exec_command('docker ps -a --format "table {{.Names}}\t{{.Image}}\t{{.Status}}" --filter name=mokee 2>&1')
+out3 = stdout3.read().decode()
+print('=== mokee 相关容器 ===')
+print(out3)
+
+c.close()
diff --git a/docs/integration-guide.md b/docs/integration-guide.md
new file mode 100644
index 0000000..935eff3
--- /dev/null
+++ b/docs/integration-guide.md
@@ -0,0 +1,1014 @@
+# 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
+
+
+ 新增用户
+ 编辑
+ 删除
+
+```
+
+> **原理**：后端返回的 `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> CTX = new ThreadLocal<>();
+
+ public static void set(Map user) { CTX.set(user); }
+ public static Map 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 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 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`
+
+```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\ | 树形菜单路由列表（结构见下表） |
+| `permission` | List\ | 该系统所有权限标识（用于前端 v-permission 指令控制按钮显隐） |
+
+**menu[] 中每个菜单节点的字段说明：**
+|------|------|------|
+| `id` | String | 菜单ID |
+| `menuName` | String | 菜单显示名称 |
+| `menuType` | Integer | **1=目录**（折叠分组，path=null，component="Layout"）
**2=菜单**（页面，有path和component）
**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\)：**
+
+```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=目录**（侧边栏折叠分组，不对应具体页面）
**2=页面菜单**（具体页面，可点击跳转）
**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 只给管理员分配了菜单，普通用户角色默认没有任何菜单权限。这是因为不同系统对普通用户的权限要求不同，无法预置。接入后请登录管理后台，在「角色管理」中手动为 `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` 中写 `
+```
+
+---
+
+## 二、文件结构
+
+### 新建文件
+
+```
+mokee-gateway-web/
+├── src/widgets/user-chip/ ← 新建目录
+│ ├── main.ts ← 入口：自动初始化，扫描 #mokee-user-chip 并挂载 Vue
+│ ├── UserChip.vue ← 核心组件（~120行，模板 + 逻辑 + 样式）
+│ ├── api.ts ← API 调用层（3个函数）
+│ └── cookie.ts ← Cookie 工具（从 request.ts/auth.ts 提取复用）
+├── vite.widget.config.ts ← 新建：Widget 专用 Vite 构建配置
+└── public/demo-widget.html ← 新建：接入演示页面
+```
+
+### 修改文件
+
+| 文件 | 改动 |
+|------|------|
+| `package.json` | 新增 `build:widget` 脚本 |
+
+### 文件职责划分
+
+```
+┌─ main.ts ──────────────────────────────────────┐
+│ 职责：DOM 就绪后扫描 #mokee-user-chip， │
+│ 读取 data-* 配置，创建并挂载 Vue 应用 │
+│ 依赖：UserChip.vue │
+│ 输出：立即执行，无 export │
+└─────────────────────────────────────────────────┘
+ │ 创建 Vue app，传入 props
+ ▼
+┌─ UserChip.vue ──────────────────────────────────┐
+│ 职责：渲染头像 + 用户名 + 下拉菜单 │
+│ 依赖：api.ts, cookie.ts, element-plus 组件 │
+│ 状态：loading / userInfo / 错误静默降级 │
+│ Props：apiBase, loginUrl, selectUrl │
+│ Emits：无（通过 window.location.href 跳转） │
+└─────────────────────────────────────────────────┘
+ │ 调用
+ ▼
+┌─ api.ts ────────────────────────────────────────┐
+│ 职责：封装 3 个 API 调用 │
+│ - fetchUserInfo(apiBase): UserInfo | null │
+│ - logout(apiBase): void │
+│ - refreshFileServiceUrl(apiBase, url): string │
+│ 依赖：cookie.ts │
+└─────────────────────────────────────────────────┘
+ │ 调用
+ ▼
+┌─ cookie.ts ─────────────────────────────────────┐
+│ 职责：Token 的 Cookie 读写 │
+│ - getToken(): string | null │
+│ - removeToken(): void │
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+## 三、API 依赖分析
+
+### 全部复用现有接口，后端零改动
+
+| API | 方法 | 用途 | 调用时机 |
+|-----|------|------|----------|
+| `GET /zgapi/v1/auth/user/info` | GET | 获取当前用户信息 | 组件挂载时 |
+| `POST /zgapi/v1/auth/logout` | POST | 通知服务端销毁 session | 点"退出登录"时 |
+| `POST /zgapi/v1/open/token` | POST | 获取文件服务下载 Token | 用户头像 URL 指向文件服务时 |
+
+### API 调用细节
+
+#### 1. 获取用户信息
+
+```
+请求：GET {apiBase}/zgapi/v1/auth/user/info
+请求头：Authorization: Bearer {token} （token 从 Cookie 读取）
+ Content-Type: application/json
+响应：{
+ "code": 200,
+ "data": {
+ "userId": "a1b2c3d4...",
+ "username": "zhangsan",
+ "realName": "张三",
+ "email": "zhangsan@zgitm.com",
+ "phone": "13800000000",
+ "avatar": null | "https://file.wg.zgitm.com/api/download/xxx",
+ "post": "工程师"
+ }
+}
+```
+
+#### 2. 退出登录
+
+```
+请求：POST {apiBase}/zgapi/v1/auth/logout
+请求头：Authorization: Bearer {token}
+```
+
+#### 3. 获取文件服务下载 Token（仅在 avatar URL 指向文件服务时调用）
+
+```
+请求：POST {apiBase}/zgapi/v1/open/token
+请求体：{ "systemCode": "gateway" }
+响应：{ "code": 200, "data": { "token": "eyJ..." } }
+```
+
+拼接：`{avatarBaseUrl}?token={新Token}`
+
+---
+
+## 四、配置与数据流
+
+### 4.1 外部系统可配置项
+
+通过占位元素的 `data-*` 属性配置：
+
+```html
+
+ data-login-url="https://web.gw.zgitm.com"
+ data-select-url="https://web.gw.zgitm.com/select"
+>
+```
+
+| 属性 | 默认值 | 说明 |
+|------|--------|------|
+| `data-api-base` | `window.location.origin` | 网关 API 地址 |
+| `data-login-url` | `window.location.origin + '/login'` | 登录页完整 URL |
+| `data-select-url` | `window.location.origin + '/select'` | 切换系统页完整 URL |
+
+### 4.2 运行时数据流
+
+```
+页面加载
+ │
+ ▼
+widgets/user-chip/main.ts 立即执行（IIFE）
+ │
+ ├─ 1. document.querySelectorAll('#mokee-user-chip')
+ │ └─ 找到所有占位元素（支持同一页面多个实例）
+ │
+ ├─ 2. 对每个占位元素：
+ │ ├─ 读取 data-api-base / data-login-url / data-select-url
+ │ ├─ 创建 Vue 3 app，以 UserChip 为根组件
+ │ ├─ 将配置作为 props 传入
+ │ └─ app.mount(container) ← 挂载到占位元素内部
+ │
+ ▼
+UserChip.vue mounted()
+ │
+ ├─ 3. 从 Cookie 读取 token（cookie.getToken()）
+ │
+ ├─ 4. 调用 fetchUserInfo(apiBase)
+ │ ├─ 成功 → userInfo.value = 响应数据
+ │ │ └─ 若 avatar URL 指向文件服务 → refreshFileServiceUrl()
+ │ │ 获取新 Token 拼接完整下载 URL
+ │ └─ 失败（401 / 网络异常）→ userInfo.value = null（显示"登录"按钮）
+ │
+ └─ 5. 渲染：
+ ├─ loading = true → 骨架屏
+ ├─ userInfo = null → "登录" 按钮
+ └─ userInfo 有值 → 头像 + 用户名 + ▼（可点开下拉）
+```
+
+### 4.3 退出登录流程
+
+```
+用户点击"退出登录"
+ │
+ ├─ 1. POST {apiBase}/zgapi/v1/auth/logout （fire-and-forget，失败不阻塞）
+ │
+ ├─ 2. cookie.removeToken()
+ │ └─ document.cookie = "token=;path=/;max-age=0;domain=.zgitm.com"
+ │
+ └─ 3. window.location.href = loginUrl
+ └─ 完整页面跳转，清空所有内存状态
+```
+
+---
+
+## 五、样式隔离方案
+
+### 策略：BEM 命名空间 + 独立 CSS 变量
+
+不使用 Shadow DOM（因为 Element Plus 的 `el-dropdown` 弹出层通过 Teleport 渲染到 `document.body`，Shadow DOM 会阻止弹出层正常工作）。
+
+```
+所有类名： .mokee-uc-{Block}__{Element}--{Modifier}
+所有 CSS 变量： --mokee-uc-{name}
+```
+
+### 根容器结构
+
+```html
+ ← Vue 挂载点（替换 #mokee-user-chip 的内部）
+
← 用户条（头像 + 名字 + 箭头）
+ ...
+
+
+
+
+
+
+
+
+ 登录
+
+
+
+
+
+
+ {{ userInitial }}
+
+
{{ displayName }}
+
+
+
+