@hunter-mate/sync-entities 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HiredChina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/entities.d.ts

@@ -0,0 +1,6 @@
+import type { SyncEntityDef } from './types';
+export declare const SYNC_ENTITIES: SyncEntityDef[];
+/** key → 定义 索引 */
+export declare const SYNC_ENTITY_MAP: Readonly<Record<string, SyncEntityDef>>;
+export declare function getSyncEntity(key: string): SyncEntityDef | undefined;
+export declare function isSyncEntityKey(key: string): boolean;

package/dist/entities.js

@@ -0,0 +1,662 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYNC_ENTITY_MAP = exports.SYNC_ENTITIES = void 0;
+exports.getSyncEntity = getSyncEntity;
+exports.isSyncEntityKey = isSyncEntityKey;
+/**
+ * 同步实体注册元数据 —— 唯一 SSOT(FID-098-hm-data-sync iter3)
+ *
+ * 与 hunter-mate 实体类一一对应,字段名 = 实体属性名。
+ * 注意:这是同步契约的数据面定义,hunter-mate 实体增删字段时此处同步更新
+ * (dev-ops vendor 副本经 bin/sync-hm-sync-entities.sh 刷新,hc-hw 有漂移回归)。
+ */
+const ts = (name, label) => ({
+    name,
+    label,
+    kind: 'text',
+});
+const num = (name, label) => ({
+    name,
+    label,
+    kind: 'number',
+});
+const bool = (name, label) => ({
+    name,
+    label,
+    kind: 'boolean',
+});
+const dt = (name, label) => ({
+    name,
+    label,
+    kind: 'datetime',
+});
+const json = (name, label) => ({
+    name,
+    label,
+    kind: 'json',
+});
+const JOB_CASE_STATUS = {
+    draft: '草稿',
+    active: '进行中',
+    archived: '已归档',
+};
+exports.SYNC_ENTITIES = [
+    {
+        key: 'job_cases',
+        className: 'JobCase',
+        label: '职位 Case',
+        direction: 'both',
+        description: '猎头负责的职位需求(case),推荐记忆闭环锚点',
+        list: { titleField: 'title', subtitleField: 'status', timeField: 'updatedAt' },
+        detail: {
+            sections: [
+                { title: '基本信息', fields: ['title', 'externalId', 'status', 'customerId', 'ownerId', 'folderPath'] },
+                { title: '需求明细', fields: ['requirements'] },
+                { title: '原始文件', fields: ['rawFiles'] },
+                { title: '系统', fields: ['id', 'createdAt', 'updatedAt'] },
+            ],
+        },
+        fields: [
+            ts('title', '职位标题'),
+            ts('externalId', '外部 ID'),
+            {
+                name: 'status',
+                label: '状态',
+                kind: 'enum',
+                enumLabels: JOB_CASE_STATUS,
+            },
+            num('customerId', '关联客户 ID'),
+            num('ownerId', '归属人 ID'),
+            ts('folderPath', '文件夹路径'),
+            json('requirements', '需求明细'),
+            json('rawFiles', '原始文件'),
+            num('id', 'ID'),
+            dt('createdAt', '创建时间'),
+            dt('updatedAt', '更新时间'),
+        ],
+    },
+    {
+        key: 'communication_records',
+        className: 'CommunicationRecord',
+        label: '沟通记录',
+        direction: 'both',
+        description: '与候选人/客户的沟通(电话/微信/邮件/面谈)及 AI 纪要',
+        list: { titleField: 'type', subtitleField: 'status', timeField: 'updatedAt' },
+        detail: {
+            sections: [
+                { title: '基本信息', fields: ['type', 'status', 'externalId', 'personId', 'jobCaseId', 'ownerId'] },
+                { title: '内容', fields: ['transcript'] },
+                { title: 'AI 提取', fields: ['summary', 'extractedEntities'] },
+                { title: '系统', fields: ['id', 'createdAt', 'updatedAt'] },
+            ],
+        },
+        fields: [
+            {
+                name: 'type',
+                label: '沟通方式',
+                kind: 'enum',
+                enumLabels: { call: '电话', wechat: '微信', email: '邮件', audio: '语音', meeting: '面谈' },
+            },
+            ts('status', '状态'),
+            ts('externalId', '外部 ID'),
+            num('personId', '人才 ID'),
+            num('jobCaseId', '职位 Case ID'),
+            num('ownerId', '归属人 ID'),
+            { ...ts('transcript', '沟通原文'), long: true },
+            json('summary', 'AI 纪要'),
+            json('extractedEntities', 'AI 提取实体'),
+            num('id', 'ID'),
+            dt('createdAt', '创建时间'),
+            dt('updatedAt', '更新时间'),
+        ],
+    },
+    {
+        key: 'remarks',
+        className: 'Remark',
+        label: '备注',
+        direction: 'both',
+        description: '挂在人才/职位/公司/客户/匹配上的业务备注',
+        list: { titleField: 'content', subtitleField: 'category', timeField: 'createdAt' },
+        detail: {
+            sections: [
+                { title: '基本信息', fields: ['targetType', 'targetId', 'category', 'author'] },
+                { title: '内容', fields: ['content'] },
+                { title: '附件', fields: ['tags', 'attachments'] },
+                { title: '系统', fields: ['id', 'createdAt'] },
+            ],
+        },
+        fields: [
+            ts('targetType', '目标类型'),
+            ts('targetId', '目标 ID'),
+            ts('category', '分类'),
+            json('author', '作者'),
+            { ...ts('content', '内容'), long: true },
+            json('tags', '标签'),
+            json('attachments', '附件'),
+            ts('id', 'ID'),
+            dt('createdAt', '创建时间'),
+        ],
+    },
+    {
+        key: 'parsed_resumes',
+        className: 'ParsedResume',
+        label: '解析简历',
+        direction: 'both',
+        description: 'HBR 简历解析产物:标准化履历/技能/教育/期望职位',
+        list: { titleField: 'snapshotId', subtitleField: 'talentPortraitId', timeField: 'updatedAt' },
+        detail: {
+            sections: [
+                { title: '索引', fields: ['snapshotId', 'talentPortraitId'] },
+                { title: '解析任务', fields: ['parseJob'] },
+                { title: '来源', fields: ['source'] },
+                { title: '提取结果', fields: ['extracted', 'confidence', 'rawExtracted'] },
+                { title: '系统', fields: ['id', 'createdAt', 'updatedAt'] },
+            ],
+        },
+        fields: [
+            ts('snapshotId', '原始快照 ID'),
+            ts('talentPortraitId', '人才画像 ID'),
+            json('parseJob', '解析任务'),
+            json('source', '来源'),
+            json('extracted', '提取结果'),
+            json('confidence', '置信度'),
+            json('rawExtracted', '原始提取'),
+            ts('id', 'ID'),
+            dt('createdAt', '创建时间'),
+            dt('updatedAt', '更新时间'),
+        ],
+    },
+    {
+        key: 'talent_portraits',
+        className: 'TalentPortrait',
+        label: '人才画像',
+        direction: 'both',
+        description: '跨来源归一的人才主档案:身份/联系方式/职业/归属',
+        list: { titleField: 'identity.displayName', subtitleField: 'professional.currentTitle', timeField: 'updatedAt' },
+        detail: {
+            sections: [
+                { title: '身份', fields: ['identity'] },
+                { title: '联系方式', fields: ['contact'] },
+                { title: '职业信息', fields: ['professional'] },
+                { title: '归属', fields: ['ownership'] },
+                { title: '溯源', fields: ['portraitProvenance', 'stats'] },
+                { title: '系统', fields: ['masterRecordId', 'id', 'createdAt', 'updatedAt'] },
+            ],
+        },
+        fields: [
+            json('identity', '身份'),
+            json('contact', '联系方式'),
+            json('professional', '职业信息'),
+            json('ownership', '归属'),
+            json('portraitProvenance', '字段溯源'),
+            json('stats', '统计'),
+            ts('masterRecordId', '主记录 ID'),
+            ts('id', 'ID'),
+            dt('createdAt', '创建时间'),
+            dt('updatedAt', '更新时间'),
+        ],
+    },
+    {
+        key: 'talent_fingerprints',
+        className: 'TalentFingerprint',
+        label: '人才指纹',
+        direction: 'both',
+        description: '去重匹配指纹:强标识(电话/邮箱 hash)+ 弱标识组合',
+        list: { titleField: 'portraitId', timeField: 'updatedAt' },
+        detail: {
+            sections: [
+                { title: '强标识', fields: ['strong'] },
+                { title: '弱标识', fields: ['weak'] },
+                { title: '人脸', fields: ['face'] },
+                { title: '匹配历史', fields: ['matchHistory'] },
+                { title: '系统', fields: ['portraitId', 'createdAt', 'updatedAt'] },
+            ],
+        },
+        fields: [
+            ts('portraitId', '人才画像 ID'),
+            json('strong', '强标识'),
+            json('weak', '弱标识'),
+            json('face', '人脸特征'),
+            json('matchHistory', '匹配历史'),
+            dt('createdAt', '创建时间'),
+            dt('updatedAt', '更新时间'),
+        ],
+    },
+    {
+        key: 'talent_job_matches',
+        className: 'TalentJobMatch',
+        label: '人才职位匹配',
+        direction: 'both',
+        description: '人才与职位 case 的匹配评分 + AI 推荐 + 人工反馈',
+        list: { titleField: 'portraitId', subtitleField: 'status', timeField: 'updatedAt' },
+        detail: {
+            sections: [
+                { title: '基本信息', fields: ['portraitId', 'jobCaseId', 'status'] },
+                { title: '评分', fields: ['scores', 'matchDetails'] },
+                { title: 'AI 推荐', fields: ['recommendation'] },
+                { title: '人工反馈', fields: ['humanFeedback'] },
+                { title: '系统', fields: ['id', 'createdAt', 'updatedAt'] },
+            ],
+        },
+        fields: [
+            ts('portraitId', '人才画像 ID'),
+            num('jobCaseId', '职位 Case ID'),
+            ts('status', '状态'),
+            json('scores', '评分'),
+            json('matchDetails', '匹配明细'),
+            json('recommendation', 'AI 推荐'),
+            json('humanFeedback', '人工反馈'),
+            ts('id', 'ID'),
+            dt('createdAt', '创建时间'),
+            dt('updatedAt', '更新时间'),
+        ],
+    },
+    {
+        key: 'parse_error_reports',
+        className: 'ParseErrorReport',
+        label: '解析错误报告',
+        direction: 'both',
+        description: 'HBR 解析失败上报,含 Sentry 联动状态',
+        list: { titleField: 'parserId', subtitleField: 'errorMessage', timeField: 'createdAt' },
+        detail: {
+            sections: [
+                { title: '基本信息', fields: ['parserId', 'snapshotId', 'reportedToSentry', 'sentryEventId'] },
+                { title: '错误', fields: ['errorMessage', 'errorStack'] },
+                { title: '上下文', fields: ['context'] },
+                { title: '系统', fields: ['id', 'createdAt'] },
+            ],
+        },
+        fields: [
+            ts('parserId', '解析器 ID'),
+            ts('snapshotId', '快照 ID'),
+            bool('reportedToSentry', '已报 Sentry'),
+            ts('sentryEventId', 'Sentry 事件 ID'),
+            { ...ts('errorMessage', '错误信息'), long: true },
+            { ...ts('errorStack', '错误堆栈'), long: true },
+            json('context', '上下文'),
+            ts('id', 'ID'),
+            dt('createdAt', '创建时间'),
+        ],
+    },
+    {
+        key: 'site_registry',
+        className: 'SiteRegistry',
+        label: '站点注册表',
+        direction: 'both',
+        description: '招聘域清单:扩展注入/adapter 映射/启发式发现',
+        list: { titleField: 'domain', subtitleField: 'platform', timeField: 'lastSeenAt' },
+        detail: {
+            sections: [
+                {
+                    title: '基本信息',
+                    fields: ['domain', 'platform', 'adapterPlatform', 'source', 'enabled'],
+                },
+                { title: '匹配配置', fields: ['matcherConfig'] },
+                { title: '发现证据', fields: ['evidence', 'sampleUrl'] },
+                { title: '系统', fields: ['id', 'firstSeenAt', 'lastSeenAt'] },
+            ],
+        },
+        fields: [
+            ts('domain', '域名'),
+            ts('platform', '平台'),
+            ts('adapterPlatform', 'Adapter 平台'),
+            {
+                name: 'source',
+                label: '来源',
+                kind: 'enum',
+                enumLabels: {
+                    builtin: '内置',
+                    user: '用户',
+                    auto: '自动发现',
+                    ignored: '已忽略',
+                    harness: 'Harness',
+                },
+            },
+            bool('enabled', '已启用'),
+            json('matcherConfig', '匹配配置'),
+            { ...ts('evidence', '发现证据'), long: true },
+            ts('sampleUrl', '样本 URL'),
+            num('id', 'ID'),
+            dt('firstSeenAt', '首次发现'),
+            dt('lastSeenAt', '最近发现'),
+        ],
+    },
+    {
+        key: 'talent_profiles',
+        className: 'TalentProfile',
+        label: '人才档案',
+        direction: 'both',
+        description: '网页解析入库的人才实体(归一化展示字段 + 原始提取)',
+        list: { titleField: 'name', subtitleField: 'headline', timeField: 'updatedAt' },
+        detail: {
+            sections: [
+                { title: '基本信息', fields: ['name', 'headline', 'source', 'ruleVersion'] },
+                { title: '来源', fields: ['sourceUrl', 'sessionId', 'tags'] },
+                { title: '提取', fields: ['extracted', 'raw'] },
+                { title: '系统', fields: ['id', 'dedupKey', 'createdAt', 'updatedAt'] },
+            ],
+        },
+        fields: [
+            ts('name', '姓名'),
+            ts('headline', 'Headline/头衔'),
+            ts('source', '来源系统'),
+            ts('ruleVersion', '规则版本'),
+            ts('sourceUrl', '来源 URL'),
+            ts('sessionId', '采集会话'),
+            json('tags', '标签'),
+            json('extracted', '规范化字段'),
+            json('raw', '原始提取'),
+            num('id', 'ID'),
+            ts('dedupKey', '去重键'),
+            dt('createdAt', '创建时间'),
+            dt('updatedAt', '更新时间'),
+        ],
+    },
+    {
+        key: 'job_postings',
+        className: 'JobPosting',
+        label: '职位发布',
+        direction: 'both',
+        description: '网页解析入库的职位 JD 实体',
+        list: { titleField: 'title', subtitleField: 'company', timeField: 'updatedAt' },
+        detail: {
+            sections: [
+                { title: '基本信息', fields: ['title', 'company', 'source', 'ruleVersion'] },
+                { title: '来源', fields: ['sourceUrl', 'sessionId', 'tags'] },
+                { title: '提取', fields: ['extracted', 'raw'] },
+                { title: '系统', fields: ['id', 'dedupKey', 'createdAt', 'updatedAt'] },
+            ],
+        },
+        fields: [
+            ts('title', '职位标题'),
+            ts('company', '公司'),
+            ts('source', '来源系统'),
+            ts('ruleVersion', '规则版本'),
+            ts('sourceUrl', '来源 URL'),
+            ts('sessionId', '采集会话'),
+            json('tags', '标签'),
+            json('extracted', '规范化字段'),
+            json('raw', '原始提取'),
+            num('id', 'ID'),
+            ts('dedupKey', '去重键'),
+            dt('createdAt', '创建时间'),
+            dt('updatedAt', '更新时间'),
+        ],
+    },
+    {
+        key: 'company_profiles',
+        className: 'CompanyProfile',
+        label: '公司档案',
+        direction: 'both',
+        description: '网页解析入库的公司实体',
+        list: { titleField: 'name', subtitleField: 'source', timeField: 'updatedAt' },
+        detail: {
+            sections: [
+                { title: '基本信息', fields: ['name', 'source', 'ruleVersion'] },
+                { title: '来源', fields: ['sourceUrl', 'sessionId', 'tags'] },
+                { title: '提取', fields: ['extracted', 'raw'] },
+                { title: '系统', fields: ['id', 'dedupKey', 'createdAt', 'updatedAt'] },
+            ],
+        },
+        fields: [
+            ts('name', '公司名'),
+            ts('source', '来源系统'),
+            ts('ruleVersion', '规则版本'),
+            ts('sourceUrl', '来源 URL'),
+            ts('sessionId', '采集会话'),
+            json('tags', '标签'),
+            json('extracted', '规范化字段'),
+            json('raw', '原始提取'),
+            num('id', 'ID'),
+            ts('dedupKey', '去重键'),
+            dt('createdAt', '创建时间'),
+            dt('updatedAt', '更新时间'),
+        ],
+    },
+    {
+        key: 'adapter_rules',
+        className: 'AdapterRule',
+        label: 'Adapter 规则',
+        direction: 'both',
+        description: '按平台+版本+URL 匹配的快照提取规则(可 dev-ops 动态下发)',
+        list: { titleField: 'platform', subtitleField: 'version', timeField: 'createdAt' },
+        detail: {
+            sections: [
+                {
+                    title: '基本信息',
+                    fields: ['platform', 'version', 'ruleType', 'priority', 'enabled', 'source', 'externalId'],
+                },
+                { title: '匹配', fields: ['hostPattern', 'pathPattern'] },
+                { title: '规则内容', fields: ['rulePayload'] },
+                { title: '系统', fields: ['id', 'createdAt'] },
+            ],
+        },
+        fields: [
+            ts('platform', '平台'),
+            ts('version', '版本'),
+            {
+                name: 'ruleType',
+                label: '规则类型',
+                kind: 'enum',
+                enumLabels: { selector: '选择器', regex: '正则', script: '脚本', jsonld: 'JSON-LD' },
+            },
+            num('priority', '优先级'),
+            bool('enabled', '已启用'),
+            {
+                name: 'source',
+                label: '来源',
+                kind: 'enum',
+                enumLabels: { builtin: '内置', harness: 'Harness overlay' },
+            },
+            ts('externalId', '外部文件标识'),
+            ts('hostPattern', '主机匹配'),
+            ts('pathPattern', '路径匹配'),
+            json('rulePayload', '规则内容'),
+            num('id', 'ID'),
+            dt('createdAt', '创建时间'),
+        ],
+    },
+    {
+        key: 'extraction_rules',
+        className: 'ExtractionRule',
+        label: '提取规则',
+        direction: 'both',
+        description: '字段级提取规则(决定产出哪类实体)',
+        list: { titleField: 'ruleId', subtitleField: 'targetHost', timeField: 'createdAt' },
+        detail: {
+            sections: [
+                {
+                    title: '基本信息',
+                    fields: ['ruleId', 'version', 'entityType', 'ruleType', 'priority', 'enabled'],
+                },
+                { title: '匹配', fields: ['targetHost', 'targetPathPattern'] },
+                { title: '规则内容', fields: ['rulePayload', 'extractedSchema'] },
+                { title: '系统', fields: ['id', 'createdAt'] },
+            ],
+        },
+        fields: [
+            ts('ruleId', '规则 ID'),
+            ts('version', '版本'),
+            ts('entityType', '产出实体类型'),
+            {
+                name: 'ruleType',
+                label: '规则类型',
+                kind: 'enum',
+                enumLabels: { selector: '选择器', regex: '正则', script: '脚本' },
+            },
+            num('priority', '优先级'),
+            bool('enabled', '已启用'),
+            ts('targetHost', '目标主机'),
+            ts('targetPathPattern', '目标路径'),
+            json('rulePayload', '规则内容'),
+            json('extractedSchema', '产出字段 schema'),
+            num('id', 'ID'),
+            dt('createdAt', '创建时间'),
+        ],
+    },
+    {
+        key: 'customers',
+        className: 'Customer',
+        label: '客户',
+        direction: 'both',
+        description: '用人单位归一化档案(推荐记忆闭环锚点)',
+        list: { titleField: 'canonicalName', subtitleField: 'typeStatus', timeField: 'updatedAt' },
+        detail: {
+            sections: [
+                { title: '基本信息', fields: ['canonicalName', 'aliases', 'typeStatus', 'ownerId'] },
+                { title: '联系与交易', fields: ['contacts', 'purchaseHistory'] },
+                { title: '备注', fields: ['notes', 'activityLogIds'] },
+                { title: '系统', fields: ['id', 'dedupKey', 'createdAt', 'updatedAt'] },
+            ],
+        },
+        fields: [
+            ts('canonicalName', '规范名称'),
+            json('aliases', '别名'),
+            json('typeStatus', '类型/状态'),
+            num('ownerId', '归属人 ID'),
+            json('contacts', '联系人'),
+            json('purchaseHistory', '交易历史'),
+            { ...ts('notes', '备注'), long: true },
+            json('activityLogIds', '动态日志 ID'),
+            num('id', 'ID'),
+            ts('dedupKey', '去重键'),
+            dt('createdAt', '创建时间'),
+            dt('updatedAt', '更新时间'),
+        ],
+    },
+    {
+        key: 'preferences',
+        className: 'Preference',
+        label: '偏好',
+        direction: 'both',
+        description: '三层偏好(user/customer/case):推荐与反馈沉淀',
+        list: { titleField: 'dimension', subtitleField: 'scope', timeField: 'updatedAt' },
+        detail: {
+            sections: [
+                {
+                    title: '基本信息',
+                    fields: ['scope', 'scopeId', 'userId', 'dimension', 'weight'],
+                },
+                { title: '偏好值', fields: ['value', 'valueKey'] },
+                { title: '证据', fields: ['evidence'] },
+                { title: '系统', fields: ['id', 'createdAt', 'updatedAt'] },
+            ],
+        },
+        fields: [
+            {
+                name: 'scope',
+                label: '作用域',
+                kind: 'enum',
+                enumLabels: { user: '顾问', customer: '客户', case: '职位 Case' },
+            },
+            num('scopeId', '作用域 ID'),
+            num('userId', '归属人 ID'),
+            ts('dimension', '维度'),
+            json('value', '偏好值'),
+            ts('valueKey', '偏好值键'),
+            num('weight', '权重'),
+            { ...ts('evidence', '证据来源'), long: true },
+            num('id', 'ID'),
+            dt('createdAt', '创建时间'),
+            dt('updatedAt', '更新时间'),
+        ],
+    },
+    {
+        key: 'recording_snapshots',
+        className: 'RecordingSnapshot',
+        label: '录制快照',
+        direction: 'push_only',
+        description: 'rrweb full snapshot 重建 HTML(只备份,不回灌)',
+        list: { titleField: 'domain', subtitleField: 'pageClass', timeField: 'snapshotTimestamp' },
+        detail: {
+            sections: [
+                {
+                    title: '基本信息',
+                    fields: ['sessionId', 'eventId', 'domain', 'pageClass', 'sourceUrl', 'isCheckout'],
+                },
+                { title: '解析状态', fields: ['adapterVersion', 'parseStatus', 'anomalyScore', 'reportedAt'] },
+                { title: '内容', fields: ['html'] },
+                { title: '系统', fields: ['id', 'snapshotTimestamp', 'createdAt'] },
+            ],
+        },
+        fields: [
+            ts('sessionId', '录制会话'),
+            num('eventId', '事件 ID'),
+            ts('domain', '域名'),
+            ts('pageClass', '页面分类'),
+            ts('sourceUrl', '来源 URL'),
+            bool('isCheckout', 'Checkout 触发'),
+            ts('adapterVersion', 'Adapter 版本'),
+            ts('parseStatus', '解析状态'),
+            num('anomalyScore', '异常评分'),
+            dt('reportedAt', '上报时间'),
+            { ...ts('html', 'HTML'), long: true },
+            num('id', 'ID'),
+            dt('snapshotTimestamp', '快照时间'),
+            dt('createdAt', '创建时间'),
+        ],
+    },
+    {
+        key: 'recording_events',
+        className: 'RecordingEvent',
+        label: '录制事件',
+        direction: 'push_only',
+        description: 'rrweb 原始事件流(只备份,不回灌)',
+        list: { titleField: 'eventType', subtitleField: 'sourceUrl', timeField: 'createdAt' },
+        detail: {
+            sections: [
+                { title: '基本信息', fields: ['sessionId', 'eventType', 'sourceUrl', 'tabId'] },
+                { title: '内容', fields: ['payload'] },
+                { title: '系统', fields: ['id', 'createdAt'] },
+            ],
+        },
+        fields: [
+            ts('sessionId', '录制会话'),
+            ts('eventType', '事件类型'),
+            ts('sourceUrl', '来源 URL'),
+            num('tabId', '标签页 ID'),
+            json('payload', '事件内容'),
+            num('id', 'ID'),
+            dt('createdAt', '创建时间'),
+        ],
+    },
+    {
+        key: 'raw_snapshots',
+        className: 'RawSnapshot',
+        label: '原始快照',
+        direction: 'push_only',
+        description: '采集的原始页面/文件快照(HTML/PDF/Excel,只备份,不回灌)',
+        list: { titleField: 'snapshotType', subtitleField: 'status', timeField: 'createdAt' },
+        detail: {
+            sections: [
+                { title: '基本信息', fields: ['snapshotType', 'status', 'ignoreReason'] },
+                { title: '来源', fields: ['source'] },
+                { title: '内容', fields: ['content'] },
+                { title: '系统', fields: ['id', 'createdAt', 'updatedAt'] },
+            ],
+        },
+        fields: [
+            ts('snapshotType', '快照类型'),
+            {
+                name: 'status',
+                label: '状态',
+                kind: 'enum',
+                enumLabels: { pending: '待解析', parsed: '已解析', failed: '失败', ignored: '已忽略' },
+            },
+            { ...ts('ignoreReason', '忽略原因'), long: true },
+            json('source', '来源'),
+            json('content', '内容'),
+            ts('id', 'ID'),
+            dt('createdAt', '创建时间'),
+            dt('updatedAt', '更新时间'),
+        ],
+    },
+];
+/** key → 定义 索引 */
+exports.SYNC_ENTITY_MAP = Object.fromEntries(exports.SYNC_ENTITIES.map((d) => [d.key, d]));
+function getSyncEntity(key) {
+    return exports.SYNC_ENTITY_MAP[key];
+}
+function isSyncEntityKey(key) {
+    return key in exports.SYNC_ENTITY_MAP;
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./entities"), exports);
+__exportStar(require("./pick"), exports);

package/dist/pick.d.ts

@@ -0,0 +1,7 @@
+/**
+ * payload 取值工具:支持点路径(如 identity.displayName),
+ * 供左列表标题/副标题与详情分区渲染共用。
+ */
+export declare function pickDisplay(payload: Record<string, unknown> | null | undefined, path: string): unknown;
+/** 标题兜底:对象值时尝试常见展示子字段,最终回落到 undefined(前端再退回 clientRef) */
+export declare function pickTitle(payload: Record<string, unknown> | null | undefined, path: string): string | undefined;

package/dist/pick.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickDisplay = pickDisplay;
+exports.pickTitle = pickTitle;
+/**
+ * payload 取值工具:支持点路径(如 identity.displayName),
+ * 供左列表标题/副标题与详情分区渲染共用。
+ */
+function pickDisplay(payload, path) {
+    if (!payload || !path)
+        return undefined;
+    let cur = payload;
+    for (const seg of path.split('.')) {
+        if (cur == null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}
+/** 标题兜底:对象值时尝试常见展示子字段,最终回落到 undefined(前端再退回 clientRef) */
+function pickTitle(payload, path) {
+    const v = pickDisplay(payload, path);
+    if (v == null)
+        return undefined;
+    if (typeof v === 'string')
+        return v || undefined;
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    if (Array.isArray(v))
+        return v.length ? pickTitle({ item: v[0] }, 'item') : undefined;
+    if (typeof v === 'object') {
+        const o = v;
+        for (const k of ['displayName', 'name', 'title', 'value', 'canonicalName', 'domain', 'ruleId', 'dimension']) {
+            const sub = pickTitle(o, k);
+            if (sub)
+                return sub;
+        }
+    }
+    return undefined;
+}

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 同步实体元数据类型(FID-098-hm-data-sync iter3)
+ *
+ * 纯声明式、零框架依赖:hunter-mate(server SYNC_REGISTRY)、dev-ops(backend 校验 +
+ * web 左列表右详情页)双端消费。新增同步实体 = 在 entities.ts 加一条定义,
+ * 两端布局/菜单/校验自动生效 —— 消灭双端各自维护实体清单的漂移面。
+ */
+export type SyncDirection = 'both' | 'push_only';
+export type SyncFieldKind = 'text' | 'number' | 'boolean' | 'datetime' | 'enum' | 'json';
+export interface SyncFieldDef {
+    /** payload 字段名(与 TypeORM 实体属性同名,camelCase) */
+    name: string;
+    /** 中文标签(UI 展示) */
+    label: string;
+    kind: SyncFieldKind;
+    /** kind=enum 时的取值中文映射 */
+    enumLabels?: Record<string, string>;
+    /** 长文本(详情页等宽展示) */
+    long?: boolean;
+}
+export interface SyncEntityDef {
+    /**
+     * 同步实体键 = TypeORM 表名(hm_sync_items.entity 即此值)。
+     * hunter-mate 侧 SYNC_REGISTRY 通过它把元数据接到实体类。
+     */
+    key: string;
+    /** 实体类名(溯源用;hunter-mate server 的类映射以此为索引) */
+    className: string;
+    /** 中文名(菜单/页面标题) */
+    label: string;
+    direction: SyncDirection;
+    /** 一句话说明(菜单 tooltip / 页面副标题) */
+    description?: string;
+    /** 左列表布局:从 payload 取哪些字段做标题/副标题/时间 */
+    list: {
+        titleField: string;
+        subtitleField?: string;
+        timeField: string;
+    };
+    /** 右详情布局:分区渲染 payload 字段(未列出的字段由前端以 JSON 附加区兜底) */
+    detail: {
+        sections: Array<{
+            title: string;
+            fields: string[];
+        }>;
+    };
+    fields: SyncFieldDef[];
+}
+export declare const isPushOnly: (def: SyncEntityDef) => boolean;

package/dist/types.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * 同步实体元数据类型(FID-098-hm-data-sync iter3)
+ *
+ * 纯声明式、零框架依赖:hunter-mate(server SYNC_REGISTRY)、dev-ops(backend 校验 +
+ * web 左列表右详情页)双端消费。新增同步实体 = 在 entities.ts 加一条定义,
+ * 两端布局/菜单/校验自动生效 —— 消灭双端各自维护实体清单的漂移面。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPushOnly = void 0;
+const isPushOnly = (def) => def.direction === 'push_only';
+exports.isPushOnly = isPushOnly;

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@hunter-mate/sync-entities",
+  "version": "0.1.0",
+  "description": "hunter-mate 数据同步实体定义 SSOT:实体元数据 + 左列表右详情布局配置,hunter-mate 与 dev-ops 双端消费(FID-098-hm-data-sync iter3)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hiredchina-com/hunter-mate.git",
+    "directory": "packages/sync-entities"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}