adspecs 0.1.12

package/references/antd-front-demo/src/utils/request.ts

@@ -0,0 +1,165 @@
+import axios from 'axios';
+import { getAccessToken, getRefreshToken, getExpiresTime, setToken, removeToken } from './token';
+import { useAuthStore } from '@/stores/useAuthStore';
+import { getMessageApi } from './messageHolder';
+
+const request = axios.create({
+  baseURL: import.meta.env.VITE_BASE_URL + import.meta.env.VITE_API_BASE_URL,
+  timeout: 30000,
+});
+
+let isRefreshing = false;
+let refreshSubscribers: Array<(token: string) => void> = [];
+
+function onRefreshed(token: string) {
+  refreshSubscribers.forEach((cb) => cb(token));
+  refreshSubscribers = [];
+}
+
+function addRefreshSubscriber(cb: (token: string) => void) {
+  refreshSubscribers.push(cb);
+}
+
+function isRemembered(): boolean {
+  return localStorage.getItem('ACCESS_TOKEN') !== null;
+}
+
+let proactiveRefreshTimer: ReturnType<typeof setTimeout> | null = null;
+
+export function scheduleProactiveRefresh() {
+  if (proactiveRefreshTimer) {
+    clearTimeout(proactiveRefreshTimer);
+    proactiveRefreshTimer = null;
+  }
+  const expiresTime = getExpiresTime();
+  if (!expiresTime) return;
+  const delay = Math.max(expiresTime - Date.now() - 5 * 60 * 1000, 10_000);
+  proactiveRefreshTimer = setTimeout(() => {
+    refreshAccessToken().catch(() => {});
+  }, delay);
+}
+
+export function clearProactiveRefresh() {
+  if (proactiveRefreshTimer) {
+    clearTimeout(proactiveRefreshTimer);
+    proactiveRefreshTimer = null;
+  }
+}
+
+export async function refreshAccessToken(): Promise<string | null> {
+  const refreshToken = getRefreshToken();
+  if (!refreshToken || isRefreshing) return null;
+
+  isRefreshing = true;
+  try {
+    const resp = await axios.post(
+      `${import.meta.env.VITE_BASE_URL}${import.meta.env.VITE_API_BASE_URL}/system/auth/refresh-token?refreshToken=${refreshToken}`,
+      null,
+    );
+    const newAccessToken = resp.data?.data?.accessToken;
+    const newRefreshToken = resp.data?.data?.refreshToken;
+    if (newAccessToken) {
+      const remember = isRemembered();
+      const expiresTime = resp.data?.data?.expiresTime;
+      setToken(newAccessToken, newRefreshToken || refreshToken, remember, expiresTime);
+      useAuthStore.setState({ token: newAccessToken });
+      onRefreshed(newAccessToken);
+      if (expiresTime) scheduleProactiveRefresh();
+      return newAccessToken;
+    }
+    return null;
+  } catch {
+    return null;
+  } finally {
+    isRefreshing = false;
+  }
+}
+
+request.interceptors.request.use((config) => {
+  const token = getAccessToken();
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`;
+  }
+  return config;
+});
+
+request.interceptors.response.use(
+  (response) => {
+    if (response.config.responseType === 'blob') return response;
+    const { data } = response;
+    if (data.code == 401) {
+      const err = Object.assign(new Error(data.msg || 'Unauthorized'), {
+        config: response.config,
+        response: { status: 401 },
+      });
+      window.location.href = '/login';
+      return Promise.reject(err);
+    } else if (data.code !== 0) {
+      getMessageApi().error(data.msg || 'Request failed');
+      return Promise.reject(new Error(data.msg || 'Request failed'));
+    }
+    return data;
+  },
+  async (error) => {
+    const originalRequest = error.config;
+    if (error.response?.status === 401 && !originalRequest?._retry) {
+      const refreshToken = getRefreshToken();
+      if (refreshToken) {
+        if (isRefreshing) {
+          return new Promise((resolve) => {
+            addRefreshSubscriber((token: string) => {
+              originalRequest.headers.Authorization = `Bearer ${token}`;
+              resolve(request(originalRequest));
+            });
+          });
+        }
+        originalRequest._retry = true;
+        const newToken = await refreshAccessToken();
+        if (newToken) {
+          originalRequest.headers.Authorization = `Bearer ${newToken}`;
+          return request(originalRequest);
+        }
+      }
+      removeToken();
+      useAuthStore.getState().reset();
+      window.location.href = '/login';
+      return Promise.reject(error);
+    }
+    // Show error message for non-401 HTTP errors
+    const msg = error.response?.data?.message || error.response?.data?.msg || error.message || 'Request failed';
+    try { getMessageApi().error(msg); } catch { /* ignore */ }
+    return Promise.reject(error);
+  },
+);
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function download(url: string, params?: any) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return request.get(url, { params, responseType: 'blob' }).then((resp: any) => {
+    const blob = new Blob([resp.data]);
+    const contentDisposition = resp.headers?.['content-disposition'];
+    let fileName = 'download';
+    if (contentDisposition) {
+      const match = contentDisposition.match(/filename\*?=(?:UTF-8'')?([^;\s]+)/i);
+      if (match) fileName = decodeURIComponent(match[1]);
+    }
+    const link = document.createElement('a');
+    link.href = URL.createObjectURL(blob);
+    link.download = fileName;
+    link.click();
+    URL.revokeObjectURL(link.href);
+  });
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function upload(url: string, data: Record<string, any>) {
+  const formData = new FormData();
+  Object.entries(data).forEach(([key, value]) => {
+    formData.append(key, value);
+  });
+  return request.post(url, formData, {
+    headers: { 'Content-Type': 'multipart/form-data' },
+  });
+}
+
+export default request;

package/references/antd-front-demo/src/utils/token.ts

@@ -0,0 +1,91 @@
+const ACCESS_TOKEN_KEY = 'ACCESS_TOKEN';
+const REFRESH_TOKEN_KEY = 'REFRESH_TOKEN';
+const EXPIRES_TIME_KEY = 'EXPIRES_TIME';
+const LOGIN_FORM_KEY = 'LOGIN_FORM';
+
+export function getAccessToken(): string | null {
+  return localStorage.getItem(ACCESS_TOKEN_KEY) || sessionStorage.getItem(ACCESS_TOKEN_KEY);
+}
+
+export function getRefreshToken(): string | null {
+  return localStorage.getItem(REFRESH_TOKEN_KEY) || sessionStorage.getItem(REFRESH_TOKEN_KEY);
+}
+
+export function getExpiresTime(): number | null {
+  const val = localStorage.getItem(EXPIRES_TIME_KEY) || sessionStorage.getItem(EXPIRES_TIME_KEY);
+  return val ? Number(val) : null;
+}
+
+export function setToken(accessToken: string, refreshToken: string, remember = true, expiresTime?: number) {
+  const storage = remember ? localStorage : sessionStorage;
+  storage.setItem(ACCESS_TOKEN_KEY, accessToken);
+  storage.setItem(REFRESH_TOKEN_KEY, refreshToken);
+  if (expiresTime) {
+    storage.setItem(EXPIRES_TIME_KEY, String(expiresTime));
+  }
+}
+
+export function removeToken() {
+  localStorage.removeItem(ACCESS_TOKEN_KEY);
+  localStorage.removeItem(REFRESH_TOKEN_KEY);
+  localStorage.removeItem(EXPIRES_TIME_KEY);
+  sessionStorage.removeItem(ACCESS_TOKEN_KEY);
+  sessionStorage.removeItem(REFRESH_TOKEN_KEY);
+  sessionStorage.removeItem(EXPIRES_TIME_KEY);
+}
+
+export interface LoginFormCache {
+  username: string;
+  password: string;
+  rememberMe: boolean;
+}
+
+// Simple XOR obfuscation to avoid storing plaintext passwords in localStorage.
+const OBFUSCATE_KEY = 0x5a;
+
+function obfuscate(text: string): string {
+  return Array.from(text)
+    .map((c) => String.fromCharCode(c.charCodeAt(0) ^ OBFUSCATE_KEY))
+    .map((c) => c.charCodeAt(0).toString(16).padStart(2, '0'))
+    .join('');
+}
+
+function deobfuscate(hex: string): string {
+  const bytes: number[] = [];
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes.push(parseInt(hex.slice(i, i + 2), 16));
+  }
+  return String.fromCharCode(...bytes.map((b) => b ^ OBFUSCATE_KEY));
+}
+
+export function getLoginForm(): LoginFormCache | null {
+  const raw = localStorage.getItem(LOGIN_FORM_KEY);
+  if (raw) {
+    try {
+      const parsed = JSON.parse(raw) as { u: string; p: string; r: boolean };
+      return {
+        username: deobfuscate(parsed.u),
+        password: deobfuscate(parsed.p),
+        rememberMe: parsed.r,
+      };
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+export function setLoginForm(form: LoginFormCache) {
+  localStorage.setItem(
+    LOGIN_FORM_KEY,
+    JSON.stringify({
+      u: obfuscate(form.username),
+      p: obfuscate(form.password),
+      r: form.rememberMe,
+    }),
+  );
+}
+
+export function removeLoginForm() {
+  localStorage.removeItem(LOGIN_FORM_KEY);
+}

package/references/antd-front-demo/tsconfig.app.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "esnext",
+    "types": ["vite/client", "vitest/globals"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    },
+    "ignoreDeprecations": "6.0"
+  },
+  "include": ["src"]
+}

package/references/antd-front-demo/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

package/references/antd-front-demo/tsconfig.node.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023"],
+    "module": "esnext",
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["vite.config.ts"]
+}

package/references/antd-front-demo/vite.config.ts

@@ -0,0 +1,30 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'node:path';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default defineConfig((_: any) => ({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, 'src'),
+    },
+  },
+  server: {
+    port: 3000,
+    open: true,
+  },
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: './src/setupTests.ts',
+    include: ['src/**/*.test.{ts,tsx}'],
+    pool: 'threads',
+    testTimeout: 10000,
+    env: {
+      VITE_BASE_URL: '',
+      VITE_API_BASE_URL: '/admin-api',
+      VITE_MOCK_ENABLED: 'true',
+    },
+  }
+}));

package/references/ecp-end-standard/ES/344/275/277/347/224/250/350/247/204/350/214/203.md

@@ -0,0 +1,231 @@
+# ES 使用规范
+
+> 基于 `sieiot-es-plus-starter`（ES 8.x），使用静态链式 API 操作 Elasticsearch。
+
+---
+
+## 一、静态链式 API
+通过 `Es.chain*` 无需注入 Service 直接操作 ES，适用于所有业务场景。
+
+### 实体类定义 （可不定义）
+```java
+@Data
+@EsIndex(index = "sys_user")
+public class SysUser {
+    @EsId
+    private Long id;
+
+    @EsField(type = EsFieldType.KEYWORD)
+    private String username;
+
+    private String nickName;
+    private Integer lockState;
+
+    @EsField(type = EsFieldType.NESTED)
+    private SysRole sysRole;
+}
+```
+### 不定义实体类时或者实体类无@EsIndex(index = "sys_user")时
+当实体对象xxx不存在索引注解时，所有的查询都需要手动指定索引。
+
+```java
+Es.chainLambdaQuery(Map.class).index("xxxx")
+Es.chainLambdaUpdate(Map.class).index("xxxx")
+```
+
+
+### 查询
+
+```java
+// 精确查询
+EsResponse<SysUser> resp = Es.chainLambdaQuery(SysUser.class)
+    .must()
+    .term(SysUser::getUsername, "admin")
+    .ge(SysUser::getAge, 18)
+    .list();
+List<SysUser> list = resp.getList();
+
+// 全文检索 + 排序 + 分页（≤10000 条场景）
+EsResponse<SysUser> resp = Es.chainLambdaQuery(SysUser.class)
+    .must()
+    .match(SysUser::getContent, "关键词")
+    .sortByDesc(SysUser::getCreateTime)
+    .searchPage(1, 10);
+
+// 布尔组合查询：(age>=18) AND (username=admin OR username=hzh) AND (deleted!=true)
+EsResponse<SysUser> resp = Es.chainLambdaQuery(SysUser.class)
+    .must()
+    .ge(SysUser::getAge, 18)
+    .must(w -> w.should()
+        .term(SysUser::getUsername, "admin")
+        .term(SysUser::getUsername, "hzh"))
+    .must(w -> w.mustNot()
+        .term(SysUser::getDeleted, true))
+    .list();
+
+// 动态条件（参数为 null 时忽略该条件）
+EsResponse<SysUser> resp = Es.chainLambdaQuery(SysUser.class)
+    .must()
+    .term(username != null, SysUser::getUsername, username)
+    .ge(minAge != null, SysUser::getAge, minAge)
+    .searchPage(1, 10);
+
+// 嵌套查询
+EsResponse<SysUser> resp = Es.chainLambdaQuery(SysUser.class)
+    .must()
+    .nestedQuery(SysUser::getRoles, SysRole.class, w ->
+        w.must().term(SysRole::getState, true))
+    .list();
+
+// 指定自定义索引
+EsResponse<SysUser> resp = Es.chainLambdaQuery(SysUser.class)
+    .index("sys_user_2024")
+    .term(SysUser::getUsername, "admin")
+    .list();
+
+// 按 ID 查询
+SysUser user = Es.chainLambdaQuery(SysUser.class)
+    ._id("123")
+    .search()
+    .getOne();
+```
+
+### 聚合
+
+```java
+EsResponse<SysUser> resp = Es.chainLambdaQuery(SysUser.class)
+    .must()
+    .terms(SysUser::getStatus, 1, 2)
+    .esLambdaAggWrapper()
+    .terms(SysUser::getUsername, a -> a.size(1000))
+    .subAggregation(t -> t.count(SysUser::getId))
+    .subAggregation(t -> t.avg(SysUser::getAge))
+    .search();
+
+EsAggregationsResponse<SysUser> agg = resp.getEsAggregationsResponse();
+Map<String, Long> termsMap = agg.getTermsAsMap(SysUser::getUsername);
+```
+
+### 写入 / 更新 / 删除
+
+```java
+// 保存（有实体类）
+Es.chainLambdaUpdate(SysUser.class).save(user);
+
+// 批量保存
+Es.chainLambdaUpdate(SysUser.class).saveBatch(userList);
+
+// 条件删除
+Es.chainLambdaUpdate(SysUser.class)
+    .term(SysUser::getUsername, "admin")
+    .remove();
+
+// 无实体类，直接操作 Map
+Map<String, Object> data = new HashMap<>();
+data.put("id", "123");
+data.put("username", "admin");
+Es.chainUpdate(Map.class).index("sys_user").save(data);
+```
+
+
+
+---
+
+## 二、深分页（`EsPaginationUtil`）
+
+ES 默认 `from + size` 分页有 `search-size`（默认 5000）上限。**超过 5000 条的分页必须使用 `EsPaginationUtil`**，其基于 `search_after` 游标实现无限深分页。
+
+> **原理**：首页/下一页/上一页/末页四种操作通过游标（`sortValues`）定位，前端需保存并回传 `prevSortValues` / `nextSortValues`。
+
+### 使用方式
+
+```java
+@Autowired
+private EsPaginationUtil esPaginationUtil;
+
+public EsPaginationVo<Map<String, Object>> queryPage(EsPaginationPo<?> po, Query query) throws Exception {
+    // 排序字段（必须包含唯一性字段，如 id，否则游标会不稳定）
+    List<EsOrderBean> orderBeans = new ArrayList<>();
+    EsOrderBean order1 = new EsOrderBean();
+    order1.setField("createTime");
+    order1.setSort(SortOrder.Desc);
+    orderBeans.add(order1);
+    EsOrderBean order2 = new EsOrderBean();   // 唯一性保障
+    order2.setField("id");
+    order2.setSort(SortOrder.Asc);
+    orderBeans.add(order2);
+
+    return esPaginationUtil.searchPageDataWithAfter(
+        po.getPageAction(),   // HOME / NEXT / PREV / LAST
+        "sys_user",           // 索引名
+        query,                // ES Query 对象（用原生 API 构建）
+        po.getFields(),       // 返回字段，逗号分隔，null 返回全部
+        po.getPageIndex(),    // 当前页码
+        po.getPageRows(),     // 每页条数
+        orderBeans,
+        po.getNextSort(),     // 下一页游标（前端回传）
+        po.getPrevSort()      // 上一页游标（前端回传）
+    );
+}
+```
+
+### 请求参数（`EsPaginationPo`）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `pageAction` | `EsPageAction` | 操作类型：`HOME`首页、`NEXT`下一页、`PREV`上一页、`LAST`末页 |
+| `pageIndex` | `Integer` | 当前页码（默认 1） |
+| `pageRows` | `Integer` | 每页条数（默认 10） |
+| `fields` | `String` | 返回字段，逗号分隔，null 返回全部 |
+| `nextSort` | `List<Object>` | 下一页游标，前端从上次响应的 `nextSortValues` 回传 |
+| `prevSort` | `List<Object>` | 上一页游标，前端从上次响应的 `prevSortValues` 回传 |
+
+### 响应结果（`EsPaginationVo`）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `curIndex` | `Integer` | 当前页码 |
+| `pageSize` | `Integer` | 每页大小 |
+| `pagesCount` | `Integer` | 总页数 |
+| `count` | `Long` | 总记录数 |
+| `data` | `List<T>` | 当前页数据 |
+| `nextSortValues` | `List<Object>` | 下一页游标（前端翻页时回传） |
+| `prevSortValues` | `List<Object>` | 上一页游标（前端翻页时回传） |
+
+### 交互流程
+
+```
+首次请求：pageAction=HOME，nextSort=null，prevSort=null
+↓ 响应返回 nextSortValues=[v1,v2]，prevSortValues=[v3,v4]
+
+下一页：pageAction=NEXT，nextSort=[v1,v2]（上次的 nextSortValues）
+上一页：pageAction=PREV，prevSort=[v3,v4]（上次的 prevSortValues）
+末页：  pageAction=LAST，nextSort=null，prevSort=null
+```
+
+---
+
+## 三、常用查询方法速查
+
+| 方法 | 含义 | 适用类型 |
+|------|------|------|
+| `term(field, value)` | 精确匹配 | KEYWORD、数值、布尔 |
+| `terms(field, v1, v2...)` | 多值匹配（IN） | KEYWORD |
+| `match(field, value)` | 全文检索 | TEXT |
+| `ge/le/gt/lt(field, value)` | 范围查询 | 数值、日期 |
+| `between(field, from, to)` | 区间查询 | 数值、日期 |
+| `_id(id)` | 按文档 ID 查询 | - |
+| `sortByDesc/sortByAsc(field)` | 排序 | - |
+| `searchPage(page, size)` | 分页（≤5000） | - |
+| `list()` | 查询全部（≤5000） | - |
+| `count()` | 统计数量 | - |
+
+---
+
+## 四、禁止事项
+
+- **禁止**对 `TEXT` 类型字段使用 `term` 精确查询（应使用 `match`）
+- **禁止**在循环中单条调用 `save()`，批量操作必须用 `saveBatch()`
+- **禁止**不加任何查询条件执行 `remove()`（全量删除）
+- **禁止**数据量超过 5000 时使用 `searchPage()` 或 `list()`，必须改用 `EsPaginationUtil`
+- **禁止**深分页排序字段不包含唯一性字段（如 `id`），否则游标不稳定导致数据重复或遗漏