feat(search): Improve search functionality: update documentation, refine Lucene query transformation, and add advanced search tests

ts/classes.doc.ts

@@ -343,22 +343,72 @@ export class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends
     if (searchableFields.length === 0) {
       throw new Error(`No searchable fields defined for class ${className}`);
     }
-    // field:value exact match (case-sensitive for non-regex fields)
-    const fv = query.match(/^(\w+):(.+)$/);
-    if (fv) {
-      const field = fv[1];
-      const value = fv[2];
+    // empty query -> return all
+    const q = query.trim();
+    if (!q) {
+      return await (this as any).getInstances({});
+    }
+    // simple exact field:value (no spaces, no wildcards, no quotes)
+    const simpleExact = q.match(/^(\w+):([^"'\*\?\s]+)$/);
+    if (simpleExact) {
+      const field = simpleExact[1];
+      const value = simpleExact[2];
       if (!searchableFields.includes(field)) {
         throw new Error(`Field '${field}' is not searchable for class ${className}`);
       }
       return await (this as any).getInstances({ [field]: value });
     }
-    // safe regex across all searchable fields (case-insensitive)
-    const escaped = escapeForRegex(query);
-    const orConditions = searchableFields.map((field) => ({
-      [field]: { $regex: escaped, $options: 'i' },
-    }));
-    return await (this as any).getInstances({ $or: orConditions });
+    // quoted phrase across all searchable fields: exact match of phrase
+    const quoted = q.match(/^"(.+)"$|^'(.+)'$/);
+    if (quoted) {
+      const phrase = quoted[1] || quoted[2] || '';
+      // build regex that matches the exact phrase (allowing flexible whitespace)
+      const parts = phrase.split(/\s+/).map((t) => escapeForRegex(t));
+      const pattern = parts.join('\\s+');
+      const orConds = searchableFields.map((f) => ({ [f]: { $regex: pattern, $options: 'i' } }));
+      return await (this as any).getInstances({ $or: orConds });
+    }
+    // wildcard field:value (supports * and ?) -> direct regex on that field
+    const wildcardField = q.match(/^(\w+):(.+[*?].*)$/);
+    if (wildcardField) {
+      const field = wildcardField[1];
+      const pattern = wildcardField[2];
+      if (!searchableFields.includes(field)) {
+        throw new Error(`Field '${field}' is not searchable for class ${className}`);
+      }
+      // escape regex special chars except * and ?, then convert wildcards
+      const escaped = pattern.replace(/([.+^${}()|[\\]\\])/g, '\\$1');
+      const regexPattern = escaped.replace(/\*/g, '.*').replace(/\?/g, '.');
+      return await (this as any).getInstances({ [field]: { $regex: regexPattern, $options: 'i' } });
+    }
+    // wildcard plain term across all fields (supports * and ?)
+    if (!q.includes(':') && (q.includes('*') || q.includes('?'))) {
+      // build wildcard regex pattern: escape all except * and ? then convert
+      const escaped = q.replace(/([.+^${}()|[\\]\\])/g, '\\$1');
+      const pattern = escaped.replace(/\*/g, '.*').replace(/\?/g, '.');
+      const orConds = searchableFields.map((f) => ({ [f]: { $regex: pattern, $options: 'i' } }));
+      return await (this as any).getInstances({ $or: orConds });
+    }
+    // detect advanced Lucene syntax: field:value, wildcards, boolean, grouping
+    const luceneSyntax = /(\w+:[^\s]+)|\*|\?|\bAND\b|\bOR\b|\bNOT\b|\(|\)/;
+    if (luceneSyntax.test(q)) {
+      const filter = (this as any).createSearchFilter(q);
+      return await (this as any).getInstances(filter);
+    }
+    // multi-term unquoted -> AND of regex across fields for each term
+    const terms = q.split(/\s+/);
+    if (terms.length > 1) {
+      const andConds = terms.map((term) => {
+        const esc = escapeForRegex(term);
+        const ors = searchableFields.map((f) => ({ [f]: { $regex: esc, $options: 'i' } }));
+        return { $or: ors };
+      });
+      return await (this as any).getInstances({ $and: andConds });
+    }
+    // single term -> regex across all searchable fields
+    const esc = escapeForRegex(q);
+    const orConds = searchableFields.map((f) => ({ [f]: { $regex: esc, $options: 'i' } }));
+    return await (this as any).getInstances({ $or: orConds });
   }