Saber Frontend Framework

SpringBlade is a microservice development platform utilizing a decoupled front-end and back-end architecture.

Key Features:

• Front-end: Uses the Saber framework (based on Vue3 and Element-Plus).
• Back-end: Built on the Spring Cloud ecosystem. Core components are encapsulated in BladeTool, which is available in Maven Central for direct integration to reduce project bloat.
• Stability & Control: Integrates Sentinel for traffic control, circuit breaking, and system load protection.
• Service Discovery & Config: Uses Nacos for registration and configuration management.
• Multi-tenancy: Includes a simplified, highly extensible SaaS multi-tenant system.
• Security: Features a custom multi-terminal authentication system (inspired by OAuth2) and a Secure module using JWT for token authentication, with support for Redis-based fine-grained control.

When declaring state in the Composition API, follow these rules to ensure reactivity and compatibility with Avue components:

General Rules

• Use ref for: Entity lists, forms, loading states, and selection sets.
• Use reactive for: Avue option objects (do not use generic parameters; use interfaces to type the variables instead).

Pagination (page) Selection Rule

The choice depends on how the page object is bound in the template:

Note: In the current codebase, most list pages use :page (one-way) + reactive, but specific pages like topmenu.vue and reportlist.vue use v-model:page and require ref.

When upgrading Saber frontend pages, transition from the Options API to <script setup lang="ts">. This involves replacing data(), computed, and methods with top-level const declarations using ref or reactive, and replacing this references with direct variable access (using .value for ref).

Key Mapping Summary

// Example of a migrated component structure
import { ref, reactive, computed } from 'vue';
import { useStore } from 'vuex';
import { ElMessage } from 'element-plus';
import { validData, findColumn } from '@/utils/util';

interface DictEntity { id: string; code: string; dictValue: string; parentId: string; }
type DictForm = Partial<DictEntity>;

const store = useStore();
const permission = computed(() => store.getters.permission);

const form = ref<DictForm>({});
const selectionList = ref<DictEntity[]>([]);
const loading = ref(true);
const query = ref<Partial<DictEntity>>({});
const page = reactive({ pageSize: 10, currentPage: 1, total: 0 });
const option = reactive({ column: [] });
const crudRef = ref();

const permissionList = computed(() => ({
  addBtn: validData(permission.value.dict_add, false),
}));

const handleAdd = (row: DictEntity) => { crudRef.value.rowAdd(); };

After migrating views to TypeScript, the infrastructure layer (api/, utils/, store/, router/, lang/, config/, and entry files) must be converted to .ts to ensure type safety across the entire call chain.

Key Migration Rules:

• Do not change business logic: Only add type annotations where the compiler explicitly errors. If the code 'looks wrong' but the compiler is silent, do not touch it.
• Handle specific TS errors as follows:
  • TS2554 (Too few arguments): Mark parameters as optional (e.g., tenantId?: string).
  • TS2339 (Property does not exist on type): Create an interface for parameter bags (e.g., StoreParams, LoginPayload).
  • TS2794 (resolve() without arguments): Add void generic to the Promise (e.g., new Promise<void>).
  • TS2339 (Browser private APIs): Add global declarations to env.d.ts (e.g., Document.webkitIsFullScreen).
  • Dynamic imports: Use generics with import.meta.glob<T>().
• Structural rewrites required for:
  • router/avue-router.ts: Change plugin from a 'function object' to an 'object literal containing an install method'.
  • utils/store.ts (getStore): Split the variable into raw and obj to avoid type incompatibility between raw strings and parsed JSON.
  • utils/util.ts (findByValue): Use direct return statements in branches to align output paths.
  • router/page/index.ts & router/views/index.ts: Explicitly annotate routes as const routes: RouteRecordRaw[].

// Example: Handling TS2554 by marking parameters optional
getDeptTree(tenantId?: string)

// Example: Handling TS2794 with Promise<void>
new Promise<void>((resolve, reject) => { ... })

In the second stage of the Saber 5.0 upgrade, a dedicated type-checking mechanism is introduced to ensure code quality without affecting the build process (which uses esbuild for pure transpilation).

Key Changes

• tsconfig.json: A new configuration dedicated to type-checking. The build process (pnpm build) does not read these check flags, decoupling checking from building.
• Removal of jsconfig.json: To avoid parsing ambiguity, tsconfig.json now handles all path aliases (e.g., ~, components, styles, utils).
• New Command: pnpm run type-check executes vue-tsc --noEmit. This command requires zero errors across the entire repository to pass.

JS Coexistence Strategy

To support existing .js files in api/, utils/, store/, etc., use the following configuration in tsconfig.json:

• allowJs: true: Allows .js files to be referenced by TS and participate in type inference.
• checkJs: false: Ensures .js files themselves are not checked for errors.

Note: JSDoc in .js files is used for signature inference. For optional parameters, use the square bracket syntax: @param {number} [defaultValue].

The core migration pattern for Saber 5.0 involves moving from the Options API to the Vue 3 Composition API with TypeScript (<script setup lang="ts">).

Key changes include:

• Replacing data(), methods, and computed with ref, reactive, and computed from vue.
• Using useStore from vuex instead of this.$store.
• Explicitly importing utility functions (e.g., import { validateNull } from '@/utils/validate') instead of relying on global mixins.
• Defining interfaces for entity and form data to leverage TypeScript type safety.
• Using ElMessage and ElMessageBox from element-plus for UI feedback.

<script setup lang="ts'>
import { ref, reactive, computed } from 'vue';
import { useStore } from 'vuex';
import { ElMessage, ElMessageBox } from 'element-plus';
import { validData } from '@/utils/util';
import { getList, add, update, remove } from '@/api/xxx/xxx';

interface XxxEntity { id: string; /* ... */ }
type XxxForm = Partial<XxxEntity>;

const store = useStore();
const permission = computed(() => store.getters.permission);

const form = ref<XxxForm>({});
const data = ref<XxxEntity[]>([]);
const loading = ref(true);
const page = reactive({ pageSize: 10, currentPage: 1, total: 0 });

// Example permission check using validData
const permissionList = computed(() => ({
  addBtn: validData(permission.value.xxx_add, false),
  editBtn: validData(permission.value.xxx_edit, false),
}));

const onLoad = (pageData: { currentPage: number; pageSize: number }, params: Partial<XxxEntity> = {}) => {
  loading.value = true;
  getList(pageData.currentPage, pageData.pageSize, Object.assign(params, query.value)).then(res => {
    page.total = res.data.data.total;
    data.value = res.data.data.records;
    loading.value = false;
  });
};
</script>