Refactor privilege management to support hierarchical privilege keys

- Updated privilege key structure to use a 3- or 4-part dotted hierarchy (e.g., `GROUP.PARENT.MODULE`).
- Modified the `RequirePrivilege` decorator to accept multiple keys, allowing for OR logic in privilege checks.
- Enhanced `PrivilegesGuard` to validate against multiple privilege keys, improving access control logic.
- Created migration scripts to update existing privilege keys in the database to the new format.
- Updated related services, controllers, and tests to accommodate the new privilege key structure and validation logic.

src/modules/privileges/privilege-key-code.ts

@@ -1,6 +1,13 @@
-/** Dotted uppercase module levels: MODULE / MODULE.RESOURCE / MODULE.RESOURCE.SUB */
+/** Dotted uppercase: Group.Parent.Module or Group.Parent.Module.Submodule */
 export const PRIVILEGE_KEY_CODE_PATTERN =
-  /^[A-Z][A-Z0-9_]*(\.[A-Z][A-Z0-9_]*)*$/;
+  /^[A-Z][A-Z0-9_]*\.[A-Z][A-Z0-9_]*\.[A-Z][A-Z0-9_]*(?:\.[A-Z][A-Z0-9_]*)?$/;
+
+export type ParsedPrivilegeKeyCode = {
+  readonly group: string;
+  readonly parent: string;
+  readonly module: string;
+  readonly submodule: string | null;
+};
 
 export function isValidPrivilegeKeyCode(code: string): boolean {
   return typeof code === 'string' && PRIVILEGE_KEY_CODE_PATTERN.test(code);
@@ -12,3 +19,14 @@ export function assertPrivilegeKeyCode(code: string): string {
   }
   return code;
 }
+
+export function parsePrivilegeKeyCode(code: string): ParsedPrivilegeKeyCode {
+  assertPrivilegeKeyCode(code);
+  const parts = code.split('.');
+  if (parts.length === 3) {
+    const [group, parent, module] = parts;
+    return { group, parent, module, submodule: null };
+  }
+  const [group, parent, module, submodule] = parts;
+  return { group, parent, module, submodule };
+}