@hunter-mate/sync-entities 0.1.0 → 0.2.1

package/dist/entities.js

@@ -590,7 +590,7 @@ exports.SYNC_ENTITIES = [
             ts('parseStatus', '解析状态'),
             num('anomalyScore', '异常评分'),
             dt('reportedAt', '上报时间'),
-            { ...ts('html', 'HTML'), long: true },
+            { ...ts('html', 'HTML'), long: true, previewMode: 'iframe' },
             num('id', 'ID'),
             dt('snapshotTimestamp', '快照时间'),
             dt('createdAt', '创建时间'),

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './types';
 export * from './entities';
 export * from './pick';
+export * from './validators';

package/dist/index.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./entities"), exports);
 __exportStar(require("./pick"), exports);
+__exportStar(require("./validators"), exports);

package/dist/types.d.ts

@@ -17,6 +17,8 @@ export interface SyncFieldDef {
     enumLabels?: Record<string, string>;
     /** 长文本(详情页等宽展示) */
     long?: boolean;
+    /** 详情页渲染方式:iframe = 该字段是重建的静态 HTML,用沙箱 iframe 可视化预览(scripts 禁用) */
+    previewMode?: 'iframe';
 }
 export interface SyncEntityDef {
     /**

package/dist/validators.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 解析字段有效性校验 SSOT(FID-113-quality-issue-governance iter1)
+ *
+ * 纯函数、零框架依赖:hunter-mate 在解析落库前校验上报遥测,
+ * dev-ops 用同一套规则重扫已同步数据 —— 两端规则天然一致,防漂移。
+ *
+ * 契约:校验不通过的字段值**照常入库**(缺失走 missingFields),
+ * 这里只产出问题清单供上报/检索。value 一律先 trim,截断到 200 字符。
+ */
+export type QualityEntityKind = 'talent' | 'job' | 'company';
+export interface FieldIssue {
+    /** payload 字段名(camelCase) */
+    field: string;
+    /** 实际值(trim 后,≤200 字符) */
+    value: string;
+    /** 规则 id(稳定键,dev-ops 可按规则过滤) */
+    rule: string;
+    /** 中文原因(展示用,用户心智词) */
+    reason: string;
+}
+/**
+ * 校验单个实体的 payload 字段值,返回问题清单(可能为空数组)。
+ * entity: 解析侧 pageClass(talent/job/company);dev-ops 扫描侧由调用方映射。
+ */
+export declare function validateEntityFields(entity: QualityEntityKind, payload: Record<string, unknown>): FieldIssue[];
+/** dev-ops 侧:同步实体键(hm_sync_items.entity 表名)→ 校验实体种类 */
+export declare const SYNC_ENTITY_TO_KIND: Record<string, QualityEntityKind>;

package/dist/validators.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * 解析字段有效性校验 SSOT(FID-113-quality-issue-governance iter1)
+ *
+ * 纯函数、零框架依赖:hunter-mate 在解析落库前校验上报遥测,
+ * dev-ops 用同一套规则重扫已同步数据 —— 两端规则天然一致,防漂移。
+ *
+ * 契约:校验不通过的字段值**照常入库**(缺失走 missingFields),
+ * 这里只产出问题清单供上报/检索。value 一律先 trim,截断到 200 字符。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYNC_ENTITY_TO_KIND = void 0;
+exports.validateEntityFields = validateEntityFields;
+const trimVal = (v) => String(v ?? '').trim();
+const clip = (s) => (s.length > 200 ? `${s.slice(0, 197)}…` : s);
+const isNonEmpty = (v) => v !== null && v !== undefined && trimVal(v) !== '';
+/** 站点 UI 固定文案白名单(通知/导航/登录类,命中即判定抓错了元素) */
+const UI_STRINGS = new Set([
+    '通知', '消息', '首页', '我的', '职位', '公司', '搜索', '加入', '登录', '注册',
+    'Messaging', 'Notifications', 'Jobs', 'Home', 'Sign in', 'Join now', 'Try Premium',
+    '尝试高级版', '我的职位', '职位搜索',
+]);
+/** 平台品牌名(值为平台名而非实体名 = 选择器抓到了站点标题) */
+const SITE_BRANDS = new Set([
+    'LinkedIn', '领英', 'Liepin', '猎聘', '前程无忧', '51job', 'Indeed', 'Glassdoor',
+]);
+/** 通知角标文本(LinkedIn "0 个通知" 实证:铃铛徽标被当姓名入库) */
+const BADGE_RE = /^\d{1,3}\s*个?(通知|消息|未读消息)$/;
+const BADGE_RE_EN = /^\d{1,3}\s+(new\s+)?(notifications?|messages?)$/i;
+const EMAIL_FIELDS = ['email', 'contactEmail', 'applyEmail'];
+const URL_FIELDS = ['profileUrl', 'sourceUrl', 'url', 'companyUrl', 'applyUrl', 'website'];
+const RULES = [
+    {
+        id: 'ui-badge-text',
+        appliesTo: [],
+        fields: ['name', 'title', 'headline'],
+        check: (v) => BADGE_RE.test(v) || BADGE_RE_EN.test(v)
+            ? '命中通知角标文本(站点徽标,不是真实名称)'
+            : null,
+    },
+    {
+        id: 'empty-name',
+        appliesTo: [],
+        fields: ['name', 'title'],
+        check: (v) => (v.length <= 1 ? '关键标识字段为空或过短' : null),
+    },
+    {
+        id: 'ui-string',
+        appliesTo: [],
+        fields: ['name', 'title', 'headline'],
+        check: (v) => (UI_STRINGS.has(v) ? '命中站点界面固定文案' : null),
+    },
+    {
+        id: 'numeric-name',
+        appliesTo: ['talent', 'company'],
+        fields: ['name'],
+        check: (v) => (/^\d+$/.test(v) ? '纯数字不可能是人名或公司名' : null),
+    },
+    {
+        id: 'site-brand-name',
+        appliesTo: ['talent', 'company'],
+        fields: ['name'],
+        check: (v) => (SITE_BRANDS.has(v) ? '值为招聘平台品牌名而非实体名' : null),
+    },
+    {
+        id: 'overlong-name',
+        appliesTo: [],
+        fields: ['name', 'title', 'headline'],
+        check: (v) => (v.length > 100 ? '长度过长,疑似整段描述泄漏进名称字段' : null),
+    },
+    {
+        id: 'email-format',
+        appliesTo: [],
+        fields: EMAIL_FIELDS,
+        check: (v) => (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v) ? null : '邮箱格式非法'),
+    },
+    {
+        id: 'url-format',
+        appliesTo: [],
+        fields: URL_FIELDS,
+        check: (v) => {
+            try {
+                const u = new URL(v);
+                return u.protocol === 'http:' || u.protocol === 'https:' ? null : 'URL 协议非法';
+            }
+            catch {
+                return 'URL 格式非法';
+            }
+        },
+    },
+    {
+        id: 'salary-range',
+        appliesTo: ['job'],
+        fields: [],
+        check: (_v, _field, payload) => {
+            const min = Number(payload.salaryMin);
+            const max = Number(payload.salaryMax);
+            if (!Number.isFinite(min) && !Number.isFinite(max))
+                return null;
+            if (Number.isFinite(min) && Number.isFinite(max) && min > max)
+                return '薪资下限大于上限';
+            const cap = 10_000_000;
+            if ((Number.isFinite(min) && (min < 0 || min > cap)) ||
+                (Number.isFinite(max) && (max < 0 || max > cap)))
+                return '薪资数值越界';
+            return null;
+        },
+    },
+];
+/**
+ * 校验单个实体的 payload 字段值,返回问题清单(可能为空数组)。
+ * entity: 解析侧 pageClass(talent/job/company);dev-ops 扫描侧由调用方映射。
+ */
+function validateEntityFields(entity, payload) {
+    if (!payload || typeof payload !== 'object')
+        return [];
+    const issues = [];
+    for (const rule of RULES) {
+        if (rule.appliesTo.length > 0 && !rule.appliesTo.includes(entity))
+            continue;
+        if (rule.fields.length === 0) {
+            // 载荷级规则(如薪资区间):对包含相关字段的实体触发一次
+            const reason = rule.check('', '', payload);
+            if (reason)
+                issues.push({ field: '(payload)', value: '', rule: rule.id, reason });
+            continue;
+        }
+        for (const field of rule.fields) {
+            const raw = payload[field];
+            if (!isNonEmpty(raw))
+                continue; // 缺失交给 missingFields,这里只管"值本身非法"
+            const value = trimVal(raw);
+            const reason = rule.check(value, field, payload);
+            if (reason)
+                issues.push({ field, value: clip(value), rule: rule.id, reason });
+        }
+    }
+    return issues;
+}
+/** dev-ops 侧:同步实体键(hm_sync_items.entity 表名)→ 校验实体种类 */
+exports.SYNC_ENTITY_TO_KIND = {
+    talent_profiles: 'talent',
+    job_postings: 'job',
+    company_profiles: 'company',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunter-mate/sync-entities",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "hunter-mate 数据同步实体定义 SSOT:实体元数据 + 左列表右详情布局配置,hunter-mate 与 dev-ops 双端消费(FID-098-hm-data-sync iter3)",
   "license": "MIT",
   "repository": {