ch3chi-commons-vue 1.2.0 → 1.8.1

package/src/model/QueryParameter.ts

@@ -0,0 +1,310 @@
+import _ from 'lodash';
+import {ApiResponse} from "../api/ApiService";
+
+export type SortDirection = 'ASC' | 'asc' | 'DESC' | 'desc';
+
+/**
+ * QuerySort 定義了查詢的排序條件
+ */
+export interface QuerySort {
+  field: string; // 排序欄位
+  direction: SortDirection; // 排序方向，'asc' 或 'desc'
+}
+
+/**
+ * IQueryPage 定義了查詢的分頁資訊
+ */
+export interface IQueryPage {
+  pageIndex: number; // 當前頁碼，從 0 開始
+  pageSize: number; // 每頁顯示的項目數量
+  totalPage: number; // 總頁數
+  totalCount: number; // 總項目數量
+}
+
+/**
+ * QueryPage 實現了 IQueryPage 接口，提供分頁資訊的管理
+ */
+export class QueryPage implements IQueryPage {
+  pageIndex: number = 0; // 當前頁碼，從 0 開始
+  pageSize: number = 10; // 每頁顯示的項目數量
+  totalPage: number = 0; // 總頁數
+  private _totalCount: number = 0; // 總項目數量
+  pageRangeDisplayed: number = 2; // 當前頁面前後要顯示的 n 個頁碼
+
+  // ~ ----------------------------------------------------------
+
+  constructor(data: Partial<QueryPage> = {}) {
+    Object.assign(this, data);
+  }
+
+  get totalCount(): number {
+    return this._totalCount;
+  }
+
+  set totalCount(value: number) {
+    this._totalCount = Math.max(value, 0); // 確保總數量不小於 0
+    // 計算總頁數
+    this.calcTotalPage();
+  }
+
+  get offset(): number {
+    return this.pageIndex * this.pageSize;
+  }
+
+  // ~ ----------------------------------------------------------
+
+
+  /**
+   * 計算總頁數
+   */
+  calcTotalPage() {
+    if (this.pageSize > 0) {
+      this.totalPage = Math.ceil(this._totalCount / this.pageSize);
+    } else {
+      this.totalPage = 0;
+    }
+  }
+
+  // 檢查是否有上一頁
+  hasPreviousPage(): boolean {
+    return this.pageIndex > 0;
+  }
+
+  // 檢查是否有下一頁
+  hasNextPage(): boolean {
+    return this.pageIndex < (this.totalPage - 1);
+  }
+
+  // 確保不小於 0
+  previous(): void {
+    this.pageIndex = Math.max(this.pageIndex - 1, 0);
+  }
+
+  // 確保不超過總頁數
+  next(): void {
+    this.pageIndex = Math.min(this.pageIndex + 1, this.totalPage - 1);
+  }
+
+  // 檢查是否可以顯示第一頁
+  isShowFirstPage(): boolean {
+    return this.pageIndex > 0;
+  }
+
+  // 檢查是否可以顯示最後一頁
+  isShowLastPage(): boolean {
+    return this.pageIndex < (this.totalPage - 1);
+  }
+
+  usePageItemArray(): number[] {
+    const rs = [];
+    for(let i = 0; i < this.totalPage; i++) {
+      rs.push(i);
+    }
+    return rs;
+  }
+
+  /**
+   * 生成分頁的顯示範圍，項目為從 0 開始的頁碼陣列
+   *
+   * @returns {number[]} 返回一個包含顯示頁碼的陣列
+   */
+  pageRange(): number[] {
+    const range: number[] = [];
+    if(this.totalPage == 0) {
+      return [];
+    }
+    if(_.isNil(this.pageRangeDisplayed) || this.pageRangeDisplayed <= 0) {
+      this.pageRangeDisplayed = 2; // 預設使用 2 個頁碼
+    }
+    // 計算顯示範圍的限制
+    const limit = (this.pageRangeDisplayed * 2) + 3;
+    // 如果總頁數小於或等於顯示範圍，則顯示所有頁碼
+    if(this.totalPage <= limit) {
+      for (let i = 0; i < this.totalPage; i++) {
+        range.push(i);
+      }
+      return range;
+    }
+
+    // 根據當下的 pageIndex 計算顯示的頁碼範圍
+    const start = Math.max(0, this.pageIndex - this.pageRangeDisplayed);
+    const end = Math.min(this.totalPage - 1, this.pageIndex + this.pageRangeDisplayed);
+    const startOffset = Math.abs((this.pageIndex - this.pageRangeDisplayed) - start);
+    const endOffset = Math.abs((this.pageIndex + this.pageRangeDisplayed) - end);
+
+    // 首頁會顯示
+    range.push(0);
+
+    // 如果有 endOffset 的情況，表示開頭需要補上通等數量的 頁碼
+    if(endOffset > 0) {
+      // 添加 startOffset 個頁碼到 range 中
+      for (let i = 1; i <= endOffset; i++) {
+        range.push(i);
+      }
+    }
+
+    // 添加省略號：偵測 start 是否大於等於 pageRangeDisplayed
+    const isStartConsecutive = start >= this.pageRangeDisplayed;
+    if(isStartConsecutive) {
+      // 如果 start - 1 大於等於 pageRangeDisplayed，則添加一個省略號
+      range.push(-1); // 使用 -1 代表省略號
+    }
+
+    // 添加 start 到 pageIndex 之間的頁碼
+    for (let i = start; i < this.pageIndex; i++) {
+      if(i == 0) {
+        continue;
+      }
+      range.push(i);
+    }
+
+    // 添加 pageIndex 當前頁碼
+    if(this.pageIndex > 0) {
+      range.push(this.pageIndex);
+    }
+
+    // 添加 pageIndex 到 end 之間的頁碼
+    for (let i = this.pageIndex + 1; i <= end; i++) {
+      // 最後一頁跳過，不在這邊添加
+      if(i == this.totalPage - 1) {
+        continue;
+      }
+      range.push(i);
+    }
+
+    // 添加省略號：偵測 end 是否小於等於 (totalPage-1) - pageRangeDisplayed
+    const isEndConsecutive = (end + 1) < (this.totalPage - 1) - this.pageRangeDisplayed;
+    if(isEndConsecutive) {
+      // 如果 end + 1 小於等於 (totalPage-1) - pageRangeDisplayed，則添加一個省略號
+      range.push(-2); // 使用 -2 代表省略號
+    }
+
+    // 如果有 startOffset 的情況，表示結尾需要補上通等數量的 頁碼
+    if(startOffset > 0) {
+      // 添加 startOffset 個頁碼到 range 中
+      for(let i = startOffset; i > 0; i--) {
+        range.push(this.totalPage - 1 - i);
+      }
+    }
+
+    // 最後一頁會顯示
+    if(this.pageIndex < (this.totalPage - 1)) {
+      range.push(this.totalPage - 1);
+    }
+
+    return range;
+  }
+
+  // ~ ----------------------------------------------------------
+}
+
+export interface QueryParameter {
+  keyword?: string | null; // 關鍵字搜尋
+  page?: QueryPage; // 分頁資訊
+  sort?: QuerySort[]; // 排序條件，陣列形式
+}
+
+export class QueryParameter implements QueryParameter {
+  keyword?: string | null = null;
+  page?: QueryPage = new QueryPage();
+  sort?: QuerySort[] = [];
+
+  // ~ ----------------------------------------------------------
+
+  constructor(data: Partial<QueryParameter> = {}) {
+    Object.assign(this, {
+      keyword: null,
+      page: new QueryPage(),
+      sort: []
+    }, data);
+    if (data.page) {
+      this.page = new QueryPage(data.page);
+    }else {
+      this.page = new QueryPage(); // 確保 page 有一個默認值
+    }
+  }
+
+  /**
+   * 載入查詢參數資料
+   * @param data 部分或全部的查詢參數
+   */
+  load(data: Partial<QueryParameter> = {}) {
+    _.merge(this, data);
+  }
+
+  /**
+   * 載入 API 回應資料
+   * @param response
+   */
+  loadResponse(response: ApiResponse) {
+    this.page!.totalCount = response.paging?.total || 0; // 確保 totalCount 有值
+  }
+
+  /**
+   * 產生 API 使用的 payload
+   * @returns {Record<string, any>} 返回一個包含查詢參數的物件
+   */
+  toPayload(): Record<string, any> {
+    const payload: Record<string, any> = {};
+
+    // 針對物件基本屬性進行處理
+    const skipProperties = ['page', 'sort'];
+    for (const key in this) {
+      // 忽略 page 和 sort 等屬性，因為它們已經在之前處理
+      if( skipProperties.includes(key)) {
+        continue; // 跳過不需要的屬性
+      }
+      if (!Object.prototype.hasOwnProperty.call(this, key)) {
+        continue;
+      }
+      payload[key] = _.get(this, key);
+    }
+    return payload;
+  }
+
+  /**
+   * 產生 URL 查詢參數
+   */
+  toQueryStringParam() : Record<string, any> {
+    const params: Record<string, any> = {};
+    if (this.page) {
+      params.limit = this.page.pageSize;
+      params.offset = this.page.offset;
+    }
+    return params;
+  }
+
+  /**
+   * 清除查詢參數
+   */
+  clear() {
+    // 清除查詢參數
+    this.keyword = '';
+    this.sort = [];
+  }
+
+  // ~ ----------------------------------------------------------
+}
+
+
+// ~ ----------------------------------------------------------
+
+/**
+ * 適用於 Date Range 的查詢參數
+ */
+export class DateRangeParam extends QueryParameter {
+  startsAt?: Date | null = null;
+  endsAt?: Date | null = null;
+
+  clear() {
+    super.clear();
+    this.startsAt = null;
+    this.endsAt = null;
+  }
+}
+
+
+// 防止 Vite/rollup tree-shake 掉 type export
+export const __QueryParameterDefine__ = null as unknown as
+  SortDirection;
+

package/src/model/SessionUser.ts

@@ -0,0 +1,110 @@
+import _ from 'lodash';
+
+/**
+ * Role model
+ */
+export class Role {
+  uid?: string;
+  name?: string;
+  type?: string;
+}
+
+
+/**
+ * 用來描述操作人員的物件
+ * 用來保存已登入的使用者資訊
+ */
+export class SessionUser {
+
+  userUid?: string; // 使用者唯一識別碼
+  iat?: number; // 簽發的時間戳
+  account?: string; // 使用者帳號
+  name?: string; // 使用者名稱
+  email?: string; // 使用者電子郵件
+  roleCode?: string; // 使用者角色代碼
+  roleName?: string; // 使用者角色名稱
+  permissions?: string[]; // 使用者權限列表
+
+  constructor(data?: Partial<SessionUser>) {
+    if(data) {
+      Object.assign(this, data);
+    }
+  }
+
+  /**
+   * 載入資料
+   * @param data
+   */
+  load(data: Record<string, any>): this {
+    data = this.process(data);
+    this.userUid = data.userUid || '';
+    this.iat = data.iat || 0;
+    this.account = data.account || '';
+    this.name = data.name || '';
+    this.email = data.email || '';
+    this.roleCode = data.roleCode || '';
+    this.roleName = data.roleName || '';
+    this.permissions = data.permissions || [];
+    return this;
+  }
+
+  /**
+   * 從驗證會話資料載入
+   * @param data
+   */
+  loadFromValidateSession(data: any): this {
+    data = this.process(data);
+    _.assignWith(this, data, (objValue, srcValue) => {
+      // 如果來源值為 null，保留原值不覆蓋
+      return srcValue === null ? objValue : srcValue;
+    });
+    return this;
+  }
+
+  /**
+   * 合併資料
+   * @param data
+   */
+  merge(data: Partial<SessionUser>): SessionUser {
+    data = this.process(data);
+    this.load(data);
+    return this;
+  }
+
+  /**
+   * 對載入的資料進行預處理
+   * @param data
+   */
+  process(data: Record<string, any>): Record<string, any> {
+    // 在這裡可以對資料進行預處理，例如轉換日期格式等
+    return data;
+  }
+
+  toJSON(): Record<string, any> {
+    return {
+      userUid: this.userUid,
+      iat: this.iat,
+      account: this.account,
+      name: this.name,
+      email: this.email,
+      roleCode: this.roleCode,
+      roleName: this.roleName,
+      permissions: this.permissions
+    }
+  }
+
+  loadJSON(data: Record<string, any>): this {
+    _.assign(this, _.pick(data, [
+      "userUid",
+      "iat",
+      "account",
+      "name",
+      "email",
+      "roleCode",
+      "roleName",
+      "permissions"
+    ]));
+    return this;
+  }
+
+}

package/src/model/ShowMessageDataModel.ts

@@ -0,0 +1,69 @@
+import {COptionItem, DataCategory} from "./FormOptions";
+
+/**
+ * ShowMessage 訊息類型列舉
+ */
+export enum ShowMessageType {
+  /** 忘記密碼郵件已發送 */
+  FORGOT_PASSWORD_SENT = 'FP_SENT',
+  /** 重置密碼成功 */
+  RESET_PASSWORD_SUCCESS = 'RP_OK',
+  /** 認證過期 */
+  AUTH_EXPIRED = 'AUTH_EXP'
+}
+
+/**
+ * ShowMessage 頁面訊息資料模型
+ * 用於定義系統各種訊息的標題、內容、狀態碼等資訊
+ */
+
+export interface IShowMessageData {
+  title: string;
+  message: string;
+  code?: string;
+  showLoginButton?: boolean;
+  showHomeButton?: boolean;
+}
+
+/**
+ * ShowMessage 訊息定義
+ */
+export class ShowMessageDataModel {
+
+  private static _messageMap: Record<ShowMessageType, IShowMessageData>;
+
+  static set messageMap(map: Record<ShowMessageType, IShowMessageData>) {
+    this._messageMap = map;
+  }
+
+  /**
+   * 根據訊息類型取得訊息資料
+   */
+  static getMessageData(type: ShowMessageType): IShowMessageData {
+    return ShowMessageDataModel._messageMap?.[type];
+  }
+
+  /**
+   * 根據 key 字串取得訊息資料（用於從 query string 解析）
+   */
+  static getMessageDataByKey(key: string): IShowMessageData | null {
+    const type = key as ShowMessageType;
+    if (type in ShowMessageDataModel._messageMap) {
+      return ShowMessageDataModel._messageMap[type];
+    }
+    return null;
+  }
+
+  /**
+   * 將訊息類型轉換為路由參數（path params）
+   */
+  static toRouteParams(type: ShowMessageType): { type: string } {
+    return {
+      type: type
+    };
+  }
+}
+
+export const __ShowMessageDataModelDefine__ =  null as unknown as
+  ShowMessageType &
+  IShowMessageData;

package/src/model/TokenUser.ts

@@ -0,0 +1,157 @@
+import {SessionUser} from "./SessionUser";
+import dayjs from "dayjs";
+import _ from "lodash";
+import {string} from "yup";
+
+/**
+ * 存放存取權杖相關資訊
+ */
+export class AccessToken {
+  tokenType?: string;
+  accessToken?: string
+  accessTokenExpiresAt?: string;
+  refreshToken?: string;
+  refreshTokenExpiresAt?: string;
+  sessionUid?: string;
+
+  // ~ ----------------------------------------------------------
+  // ~ constructor
+
+  constructor(data?: Partial<AccessToken>) {
+    if(data) {
+      Object.assign(this, data);
+    }
+  }
+
+  // ~ ----------------------------------------------------------
+
+  /**
+   * 存取權杖是否已過期
+   */
+  isExpired(): boolean {
+    if(!this.accessTokenExpiresAt) {
+      return true;
+    }
+    const dayObj = dayjs(this.accessTokenExpiresAt);
+    if(!dayObj.isValid()) {
+      console.warn('accessTokenExpiresAt is invalid date string:', this.accessTokenExpiresAt);
+      return true;
+    }
+    return dayjs().isAfter(dayObj);
+  }
+
+  /**
+   * 刷新權杖是否已過期
+   */
+  isRefreshTokenExpired(): boolean {
+    if(!this.refreshTokenExpiresAt) {
+      return true;
+    }
+    const dayObj = dayjs(this.refreshTokenExpiresAt);
+    if(!dayObj.isValid()) {
+      console.warn('refreshTokenExpiresAt is invalid date string:', this.refreshTokenExpiresAt);
+      return true;
+    }
+    return dayjs().isAfter(dayObj);
+  }
+
+  /**
+   * 載入資料
+   * @param data
+   */
+  loadToken(data: Record<string, any>): this {
+    _.assign(this, _.pick(data, [
+      "tokenType",
+      "accessToken",
+      "accessTokenExpiresAt",
+      "refreshToken",
+      "refreshTokenExpiresAt",
+      "sessionUid"
+    ]));
+    return this;
+  }
+
+  /**
+   * 轉換為 JSON 物件
+   */
+  toJSON(): Record<string, any> {
+    return {
+      tokenType: this.tokenType,
+      accessToken: this.accessToken,
+      accessTokenExpiresAt: this.accessTokenExpiresAt,
+      sessionUid: this.sessionUid
+    };
+  }
+
+  /**
+   * 從 JSON 資料載入
+   * @param data
+   */
+  loadJSON(data: Record<string, any>): this {
+    _.assign(this, _.pick(data, [
+      "tokenType",
+      "accessToken",
+      "accessTokenExpiresAt",
+      "sessionUid"
+    ]))
+    return this;
+  }
+
+  // ~ ----------------------------------------------------------
+
+  /**
+   * 取得 Bearer Token 字串
+   */
+  get bearerToken(): string {
+    return `${this.tokenType} ${this.accessToken}`;
+  }
+}
+
+/**
+ * 帶有 Token 資訊的使用者物件
+ */
+export class TokenUser extends SessionUser {
+  tokens?: AccessToken;
+  profile?: Record<string, any>;
+
+  constructor(data?: Partial<AccessToken>) {
+    super();
+    if(!data) {
+      return;
+    }
+    Object.assign(this, data);
+  }
+
+  load(data: Record<string, any>): this {
+    super.load(data);
+    if(data.tokens) {
+      this.tokens = new AccessToken(data.tokens);
+    }
+    if(data.profile) {
+      this.profile = data.profile;
+    }
+    return this;
+  }
+
+  toJSON(): Record<string, any> {
+    return {
+      ...super.toJSON(),
+      tokens: this.tokens ? this.tokens.toJSON() : undefined,
+      profile: this.profile
+    }
+  }
+
+  loadJSON(data: Record<string, any>): this {
+    super.loadJSON(data);
+    if(data.tokens) {
+      this.tokens = new AccessToken().loadJSON(data.tokens);
+    }
+    if(data.profile) {
+      this.profile = data.profile;
+    }
+    return this;
+  }
+
+}
+
+

package/src/stores/FormDataStore.ts

@@ -0,0 +1,73 @@
+import { defineStore } from 'pinia';
+import _ from 'lodash';
+
+/**
+ * Backup Form Data Store
+ * This store is used to manage the system setting details in a backup form.
+ */
+export const backupFormDataStore = defineStore('formData', {
+  state: () => ({
+    store: {} as Record<string, any>,
+  }),
+  actions: {
+    backupData(dataName: string, data: Record<string, any>) {
+      _.set(this.$state.store, dataName, data);
+    }
+  },
+  getters: {
+    getBackupData: (state) => (dataName: string): Record<string, any> | null => {
+      return _.get(state.store, dataName, null);
+    },
+  }
+});
+
+/**
+ * 用來保留查詢表單的資料到 local storage
+ */
+export const useQueryFormDataStore = defineStore('queryFormData', {
+  state: () => ({
+    store: {} as Record<string, any>,
+  }),
+  actions: {
+    save(formName: string, queryParam: Record<string, any>) {
+      // 針對 queryParam 做深拷貝，避免外部物件被修改
+      const cloneParam = _.cloneDeep(queryParam);
+      // 針對 cloneParam.page ，只保留 pageIndex, pageSize 兩個屬性
+      if(cloneParam.page) {
+        cloneParam.page = {
+          pageIndex: cloneParam.page.pageIndex,
+          pageSize: cloneParam.page.pageSize
+        };
+      }
+
+      // 保存到 Pinia store
+      this.$state.store[formName] = cloneParam;
+      // 同步到 local storage
+      localStorage.setItem(`qfds_${formName}`, JSON.stringify(cloneParam));
+    },
+    loadAllFromLocalStorage() {
+      Object.keys(this.$state.store).forEach((key) => {
+        const item = localStorage.getItem(`qfds_${key}`);
+        if(item) {
+          try {
+            const parsed = JSON.parse(item);
+            this.$state.store[key] = parsed;
+          } catch(e) {
+            console.error(`Failed to parse localStorage item for key ${key}:`, e);
+          }
+        }
+      });
+    },
+    clearQueryParam(formName: string) {
+      if(this.$state.store.hasOwnProperty(formName)) {
+        this.$state.store[formName] = null;
+        localStorage.removeItem(`qfds_${formName}`);
+      }
+    },
+  },
+  getters: {
+    getQueryParam: (state) => (formName: string): Record<string, any> | null => {
+      return state.store[formName];
+    },
+  }
+});