platforms/frontend/platform_admin/src/api/resource-detail-contract.ts

/**
 * 功能描述：声明平台资源详情的字段顺序、固定关联表列和 JSON 展示规则。
 * 版本：v1.0.0
 */

export type ResourceCollectionContract = {
  columns: string[];
  jsonColumns?: string[];
  relationIdentityKeys?: Record<string, string>;
};

export type ResourceDetailContract = {
  leadingKeys?: string[];
  hiddenKeys?: string[];
  relationResources?: Record<string, string>;
  collections?: Record<string, ResourceCollectionContract>;
};

const contracts: Record<string, ResourceDetailContract> = {
  gasorder_contract: {
    leadingKeys: [
      'contract_no', 'contract_status', 'title', 'user_account_identity',
      'gas_basic_identity', 'delivery_basic_identity', 'identity',
    ],
    collections: {
      products: {
        columns: [
          'bound_at', 'product_name', 'product_code', 'product_type_name',
          'product_params', 'unit_price', 'product_info_identity',
          'unbound_at', 'unbind_reason',
        ],
        jsonColumns: ['product_params'],
      },
      revisions: {
        columns: [
          'occurred_at', 'action', 'contract_status', 'effective_at',
          'expired_at', 'operator_name', 'operator_identity', 'reason',
        ],
        relationIdentityKeys: { operator_name: 'operator_identity' },
      },
    },
  },
  gasorder_basic: {
    leadingKeys: [
      'order_no', 'request_no', 'order_status', 'gasorder_contract_identity',
      'creator_type', 'creator_identity', 'user_account_identity',
      'gas_basic_identity', 'delivery_basic_identity',
      'staff_account_identity', 'identity', 'status',
    ],
    hiddenKeys: ['operator_name'],
    relationResources: {
      gasorder_contract_identity: '/gasorder_contract',
      user_account_identity: '/user_account',
      gas_basic_identity: '/gas_basic',
      delivery_basic_identity: '/delivery_basic',
      staff_account_identity: '/staff_account',
    },
    collections: {
      items: {
        columns: [
          'product_name', 'product_code', 'product_type_name',
          'product_params', 'unit_price',
        ],
        jsonColumns: ['product_params'],
      },
      assignments: {
        columns: [
          'assigned_at', 'gas_basic_display_name',
          'delivery_basic_display_name', 'staff_account_display_name',
          'assigner_name', 'reason',
        ],
        relationIdentityKeys: {
          gas_basic_display_name: 'gas_basic_identity',
          delivery_basic_display_name: 'delivery_basic_identity',
          staff_account_display_name: 'staff_account_identity',
          assigner_name: 'assigner_identity',
        },
      },
      statuses: {
        columns: ['occurred_at', 'from_status', 'to_status', 'operator_name', 'reason'],
        relationIdentityKeys: { operator_name: 'operator_identity' },
      },
      tracks: {
        columns: [
          'attempt_no', 'staff_account_display_name',
          'staff_account_identity', 'started_at', 'completed_at',
        ],
        relationIdentityKeys: {
          staff_account_display_name: 'staff_account_identity',
        },
      },
      confirmations: {
        columns: [
          'confirmed_at', 'confirm_type', 'recipient_name', 'recipient_phone',
          'proof_uri', 'remark',
        ],
      },
      payments: {
        columns: ['attempt_no', 'payment_no', 'payment_order_identity', 'amount', 'payment_status'],
      },
    },
  },
  gasorder_track: {
    leadingKeys: [
      'gasorder_basic_identity', 'staff_account_identity', 'attempt_no',
      'started_at', 'completed_at', 'identity', 'status',
    ],
    relationResources: {
      gasorder_basic_identity: '/gasorder_basic',
      staff_account_identity: '/staff_account',
    },
    collections: {
      points: {
        columns: [
          'occurred_at', 'received_at', 'longitude', 'latitude', 'accuracy',
          'speed', 'direction', 'source', 'request_no',
        ],
      },
    },
  },
  payment_order: {
    leadingKeys: [
      'payment_no', 'payment_status', 'request_no', 'business_type',
      'business_identity', 'user_identity', 'amount', 'identity',
    ],
  },
  wallet_record: {
    leadingKeys: [
      'record_no', 'request_no', 'direction', 'trade_type', 'amount',
      'wallet_basic_identity', 'identity',
    ],
  },
  ec_order: {
    leadingKeys: [
      'order_no', 'order_status', 'request_no', 'user_account_identity',
      'payable_amount', 'total_amount', 'identity',
    ],
  },
};

const jsonFieldKeys = new Set([
  'params', 'product_params', 'product_snapshot', 'args', 'callback_msg',
]);

/** 返回资源专属详情契约；没有专属规则时使用空契约。 */
export function resourceDetailContract(name: string): ResourceDetailContract {
  return contracts[name] ?? {};
}

/** 判断主详情字段是否应使用完整 JSON 查看器，内容不做脱敏或改写。 */
export function isResourceJsonField(key: string) {
  return jsonFieldKeys.has(key);
}

/** 返回集合字段对应的稳定唯一标识字段。 */
export function collectionRelationIdentityKey(
  resourceName: string,
  collectionKey: string,
  column: string,
) {
  return contracts[resourceName]?.collections?.[collectionKey]
    ?.relationIdentityKeys?.[column] ?? '';
}

/** 判断集合字段是否应使用完整 JSON 查看器。 */
export function isCollectionJsonField(
  resourceName: string,
  collectionKey: string,
  column: string,
) {
  return Boolean(
    contracts[resourceName]?.collections?.[collectionKey]
      ?.jsonColumns?.includes(column),
  );
}