feat(detail): wire object fieldGroups into detail sections; read hints from spec-writable detail.* block (#2148) (#2149)

问题一: 对象上定义的 fieldGroups(字段分组)此前只在表单里生效,
详情页(默认详情 + synth 页面)完全忽略。现在:

- plugin-detail synth 新增 deriveFieldGroupDetailSections():按声明顺序
  把 fields[].group 归入 fieldGroups[] 定义的分组,透传 collapsible/
  collapsed(映射为 defaultCollapsed),空分组丢弃,未分组字段进末尾
  无标题分区(跳过审计/系统字段,显式分组的审计字段保留)。
- 新增 resolveDetailSections():options.sections > detail.sections >
  fieldGroups 推导;buildDefaultDetails 全部 synth 路径接入。
- RecordDetailView 复用该推导:分组标题走 sectionLabel i18n,未分组
  剩余字段保留 primary/"更多详情" 折叠拆分。

问题二: console 此前从 spec ObjectSchema 拒绝/剥离的键读取详情提示
(views.detail.highlightFields / views.form.sections / 顶层 stageField)。
现在优先读 spec 可写的 detail.* 透传块,旧键保留为向后兼容回退:

- detail.stageField: string 指定 / false 关闭(收编 #2065)
- detail.highlightFields: 支持 string 或 {name} 条目
- detail.sections / detail.sectionGroups
- detail.useFieldGroups: false 可关闭 fieldGroups 推导

行为变化: 已声明 fieldGroups 的对象,详情页从自动两段式变为按分组
渲染;可用 detail.useFieldGroups: false 退回旧行为。

抽屉(RecordDetailDrawer)分组渲染留待后续 PR,见 #2148。

Author: baozhoutao

packages/app-shell/src/views/RecordDetailView.tsx

@@ -8,7 +8,7 @@
 
 import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
 import { useParams, useNavigate, useLocation, Link } from 'react-router-dom';
-import { DetailView, RecordChatterPanel, buildDefaultPageSchema, extractMentions } from '@object-ui/plugin-detail';
+import { DetailView, RecordChatterPanel, buildDefaultPageSchema, deriveFieldGroupDetailSections, extractMentions } from '@object-ui/plugin-detail';
 import { Empty, EmptyTitle, EmptyDescription } from '@object-ui/components';
 import { useAuth, createAuthenticatedFetch } from '@object-ui/auth';
 import { ActionProvider, useObjectTranslation, useObjectLabel, usePageAssignment, RecordContextProvider, SchemaRenderer, DiscussionContextProvider, HighlightFieldsProvider, useGlobalUndo } from '@object-ui/react';
@@ -1225,8 +1225,14 @@ export function RecordDetailView({ dataSource, objects, onEdit, objectNameOverri
         (key) => key === 'name' || key === 'title'
       );
 
-    // Build sections: prefer form sections from objectDef, fallback to flat field list
-    const formSections = objectDef.views?.form?.sections;
+    // Build sections, in priority order:
+    //   1) explicit sections — the spec-writable `detail.sections` block,
+    //      else legacy `views.form.sections` (the spec's ObjectSchema has no
+    //      `views` key, so that source only exists on non-spec metadata);
+    //   2) sections derived from the designer's `fieldGroups` metadata
+    //      (see the fieldGroups branch in the fallback below);
+    //   3) auto-grouping (primary + collapsible "More details").
+    const formSections = (objectDef as any).detail?.sections ?? objectDef.views?.form?.sections;
     const sections = formSections && formSections.length > 0
       ? formSections.map((sec: any) => ({
           title: sec.name ? sectionLabel(objectDef.name, sec.name, sec.title || sec.name) : sec.title,
@@ -1262,14 +1268,6 @@ export function RecordDetailView({ dataSource, objects, onEdit, objectNameOverri
           }),
         }))
       : (() => {
-          // Auto-grouping (platform B): when no form sections are authored,
-          // split fields into a primary section and a collapsible
-          // "More details" section so long-form/secondary fields don't
-          // dilute the main grid. The primary section stays untitled so
-          // DetailSection still flattens its chrome when alone.
-          const allFields = Object.keys(objectDef.fields || {})
-            .filter((key) => !AUDIT_FIELD_NAMES.has(key) && !HIDDEN_SYSTEM_FIELD_NAMES.has(key) && !objectDef.fields[key]?.hidden);
-
           const toField = (key: string) => {
             const fieldDef = objectDef.fields[key];
             const refTarget = fieldDef.reference_to || fieldDef.reference;
@@ -1284,35 +1282,70 @@ export function RecordDetailView({ dataSource, objects, onEdit, objectNameOverri
             };
           };
 
-          const primaryKeys = allFields.filter((k) => !isSecondaryField(k, objectDef.fields[k]));
-          const secondaryKeys = allFields.filter((k) => isSecondaryField(k, objectDef.fields[k]));
+          // Auto-grouping (platform B): split fields into a primary section
+          // and a collapsible "More details" section so long-form/secondary
+          // fields don't dilute the main grid. The primary section stays
+          // untitled so DetailSection still flattens its chrome when alone.
+          // Shared by the pure-fallback path and the ungrouped remainder of
+          // the fieldGroups path below.
+          const splitPrimarySecondary = (keys: string[]) => {
+            const primaryKeys = keys.filter((k) => !isSecondaryField(k, objectDef.fields[k]));
+            const secondaryKeys = keys.filter((k) => isSecondaryField(k, objectDef.fields[k]));
+
+            // Keep the legacy single-untitled-section behaviour when the
+            // split would leave one side empty.
+            if (secondaryKeys.length === 0 || primaryKeys.length === 0) {
+              return [
+                {
+                  showBorder: false as const,
+                  fields: keys.map(toField),
+                },
+              ];
+            }
 
-          // Below ~6 primary fields the second section often looks awkward
-          // — keep the legacy single-untitled-section behaviour. Also
-          // honour the "no secondary fields" case the same way.
-          if (secondaryKeys.length === 0 || primaryKeys.length === 0) {
             return [
               {
                 showBorder: false as const,
-                fields: allFields.map(toField),
+                fields: primaryKeys.map(toField),
+              },
+              {
+                name: 'details',
+                title: sectionLabel(objectDef.name, 'details', t('detail.sectionMoreDetails', 'More details')),
+                collapsible: true,
+                defaultCollapsed: false,
+                showBorder: true as const,
+                fields: secondaryKeys.map(toField),
               },
             ];
+          };
+
+          // 2) fieldGroups-derived sections (object-designer metadata,
+          //    same source the runtime form honours). Declared groups
+          //    render as titled cards in declared order; the helper's
+          //    trailing untitled bucket (ungrouped fields) still goes
+          //    through the primary/"More details" split so long-form
+          //    fields stay tucked away. Objects can opt out via
+          //    `detail.useFieldGroups: false`.
+          const grouped = deriveFieldGroupDetailSections(objectDef as any);
+          if (grouped) {
+            return grouped.flatMap((sec: any) => {
+              if (!sec.name) {
+                return splitPrimarySecondary(
+                  (sec.fields as any[]).map((f: any) => f.name),
+                );
+              }
+              return [{
+                ...sec,
+                title: sectionLabel(objectDef.name, sec.name, sec.title),
+                showBorder: true as const,
+              }];
+            });
           }
 
-          return [
-            {
-              showBorder: false as const,
-              fields: primaryKeys.map(toField),
-            },
-            {
-              name: 'details',
-              title: sectionLabel(objectDef.name, 'details', t('detail.sectionMoreDetails', 'More details')),
-              collapsible: true,
-              defaultCollapsed: false,
-              showBorder: true as const,
-              fields: secondaryKeys.map(toField),
-            },
-          ];
+          // 3) Pure auto-grouping fallback.
+          const allFields = Object.keys(objectDef.fields || {})
+            .filter((key) => !AUDIT_FIELD_NAMES.has(key) && !HIDDEN_SYSTEM_FIELD_NAMES.has(key) && !objectDef.fields[key]?.hidden);
+          return splitPrimarySecondary(allFields);
         })();
 
     // Audit fields (created_at/created_by/updated_at/updated_by) are NOT
@@ -1385,12 +1418,33 @@ export function RecordDetailView({ dataSource, objects, onEdit, objectNameOverri
       return base;
     })();
 
-    // Build highlightFields: exclusively from objectDef metadata (no hardcoded fallback)
-    const highlightFields: HighlightField[] = objectDef.views?.detail?.highlightFields ?? [];
+    // Build highlightFields: exclusively from objectDef metadata (no
+    // hardcoded fallback). The spec-writable `detail.highlightFields`
+    // wins; `views.detail.highlightFields` stays as back-compat for
+    // non-spec metadata (the spec's ObjectSchema has no `views` key).
+    // Entries may be bare field names — normalize them to the
+    // HighlightField shape by resolving label/type from the field def.
+    const rawHighlightFields =
+      (objectDef as any).detail?.highlightFields ?? objectDef.views?.detail?.highlightFields ?? [];
+    const highlightFields: HighlightField[] = (Array.isArray(rawHighlightFields) ? rawHighlightFields : [])
+      .map((f: any): HighlightField | null => {
+        const name = typeof f === 'string' ? f : f?.name;
+        if (!name) return null;
+        if (typeof f === 'object' && f.label) return f as HighlightField;
+        const fieldDef = objectDef.fields?.[name];
+        return {
+          name,
+          label: fieldDef?.label || name,
+          ...(fieldDef?.type ? { type: fieldDef.type } : {}),
+        };
+      })
+      .filter((f): f is HighlightField => !!f);
 
     // Build sectionGroups from objectDef detail/form config if available
     const sectionGroups: SectionGroup[] | undefined =
-      objectDef.views?.detail?.sectionGroups ?? objectDef.views?.form?.sectionGroups;
+      (objectDef as any).detail?.sectionGroups
+      ?? objectDef.views?.detail?.sectionGroups
+      ?? objectDef.views?.form?.sectionGroups;
 
     // Build related entries from reverse-reference child objects.
     // `referenceField` is the FK field on the child pointing back to this

packages/plugin-detail/src/index.tsx

@@ -110,6 +110,8 @@ export {
   detectStatusField,
   deriveStages,
   deriveHighlightFields,
+  deriveFieldGroupDetailSections,
+  resolveDetailSections,
 } from './synth/buildDefaultPageSchema';
 export type {
   ObjectDefLike,