dsh-metaphysics 0.14.3 → 0.16.0

package/engine/sanhe.js

@@ -0,0 +1,26 @@
+// 地支三合局：申子辰合水、亥卯未合木、寅午戌合火、巳酉丑合金。
+//
+// 之前三处各写一遍：bazi 用「键 → 五行」对象判三合/半合，hepan 用三个字的数组判半合，
+// daliuren 又用「单支 → 五行」查驿马桃花。三份表只要有一份改动不同步，
+// 「半合」与「驿马」就会互相矛盾。这里统一成一份表 + 三种派生视图。
+
+/** 四组三合，顺序沿用传统口诀（申子辰 → 亥卯未 → 寅午戌 → 巳酉丑） */
+export const SANHE_GROUPS = [
+  { branches: ['申', '子', '辰'], element: '水' },
+  { branches: ['亥', '卯', '未'], element: '木' },
+  { branches: ['寅', '午', '戌'], element: '火' },
+  { branches: ['巳', '酉', '丑'], element: '金' },
+];
+
+/** 三字键 → 五行：bazi 的「三合/半合/拱合」判定按这个遍历 */
+export const SANHE = Object.fromEntries(SANHE_GROUPS.map((g) => [g.branches.join(''), g.element]));
+
+/** 单支 → 它所处三合局的五行：daliuren 查驿马桃花用 */
+export const SANHE_ELEMENT = Object.fromEntries(
+  SANHE_GROUPS.flatMap((g) => g.branches.map((b) => [b, g.element])),
+);
+
+/** 某支所在的三合局（找不到返回 null） */
+export function sanheGroupOf(branch) {
+  return SANHE_GROUPS.find((g) => g.branches.includes(branch)) || null;
+}

package/engine/validate.js

@@ -0,0 +1,56 @@
+// 引擎边界的入参守卫。
+//
+// 引擎的导出函数（buildBazi / buildZiwei / buildDaliuren / buildQimen…）假设调用方
+// 已经把「1990-05-12T14:30」解析成了 { year, month, day, hour, minute }。传错形状时，
+// 以前会在内部某行抛裸 TypeError（例如 buildBazi({ datetime: '...' })），
+// 调用方只能看见 "Cannot read properties of null"，不知道是自己传错了什么。
+//
+// 这里统一在入口判一次，失败一律 E_INPUT，并在文案里写清「该传什么」。
+import { fail } from './fail.js';
+
+/** 支持的公历年份范围：更早的年份时区与历法口径都不可靠，宁可拒绝 */
+export const MIN_YEAR = 1600;
+export const MAX_YEAR = 2400;
+
+export function isLeapYear(year) {
+  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+
+export function daysInMonth(year, month) {
+  if (month === 2) return isLeapYear(year) ? 29 : 28;
+  return [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1] || 0;
+}
+
+const show = (v) => (typeof v === 'string' ? `「${v}」` : String(v));
+const HINT = '引擎只接受解析好的公历字段 { year, month, day, hour?, minute? }；字符串请先交给宿主层的 parseDateTime 解析';
+
+/**
+ * 校验公历入参；不合法时抛 E_INPUT。
+ * @param {object} input 至少含整数 year / month / day；hour、minute 可省略（按 0）
+ * @param {string} [who] 出错时用于定位是谁的入参（合盘两侧各传 'a' / 'b'）
+ */
+export function assertCivil(input, who = '') {
+  const p = who ? `${who} 的` : '';
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    const got = input === null ? 'null' : Array.isArray(input) ? '数组' : typeof input;
+    throw fail('E_INPUT', `${p}入参必须是对象（收到 ${got}）；${HINT}`);
+  }
+  const hour = input.hour === undefined ? 0 : input.hour;
+  const minute = input.minute === undefined ? 0 : input.minute;
+  for (const [key, value] of [['year', input.year], ['month', input.month], ['day', input.day], ['hour', hour], ['minute', minute]]) {
+    if (!Number.isInteger(value)) throw fail('E_INPUT', `${p}${key} 必须是整数（收到 ${show(value)}）；${HINT}`);
+  }
+  if (input.year < MIN_YEAR || input.year > MAX_YEAR) {
+    throw fail('E_INPUT', `${p}year 超出支持范围 ${MIN_YEAR}–${MAX_YEAR}（收到 ${input.year}）；更早的年份时区与历法口径不可靠`);
+  }
+  if (input.month < 1 || input.month > 12) {
+    throw fail('E_INPUT', `${p}month 超出范围 1–12（收到 ${input.month}）`);
+  }
+  const max = daysInMonth(input.year, input.month);
+  if (input.day < 1 || input.day > max) {
+    throw fail('E_INPUT', `${p}日期不存在：${input.year}-${input.month}-${input.day}（${input.year} 年 ${input.month} 月只有 ${max} 天）`);
+  }
+  if (hour < 0 || hour > 23) throw fail('E_INPUT', `${p}hour 超出范围 0–23（收到 ${hour}）`);
+  if (minute < 0 || minute > 59) throw fail('E_INPUT', `${p}minute 超出范围 0–59（收到 ${minute}）`);
+  return input;
+}

package/engine/ziwei-hepan.js

@@ -1,120 +1,123 @@
-// 紫微合盘：两盘并排 + 互落宫 + 四化引动。
-// 口径：把一方的「命宫 / 夫妻宫」地支落到对方盘的宫位上，判断影响落在对方哪一领域；
-// 再把一方生年四化所化的星，找它在对方盘的位置，判断「你的某种特质会引动对方哪一宫」。
-// 这是并排对照的读法，不涉及两盘叠加安星（那是另一派做法，本文不采用）。
-import { buildZiwei } from './ziwei.js';
-
-const NAMES = ['命宫', '兄弟', '夫妻', '子女', '财帛', '疾厄', '迁移', '交友', '官禄', '田宅', '福德', '父母'];
-const MUT_MEAN = {
-  禄: '会把资源、机会与松弛感带过去',
-  权: '会不自觉地主导或施压',
-  科: '带来的更多是名声、体面与理性',
-  忌: '会勾起压力点与执念',
-};
-const MUT_SCORE = { 禄: 10, 权: 5, 科: 8, 忌: -10 };
-// 落在对方这些宫位时影响最直接
-const STRONG_LANDS = ['命宫', '夫妻', '福德', '财帛', '官禄'];
-
-const palaceByBranch = (chart, branch) => (chart.palaces || []).find((p) => p.branch === branch) || null;
-const mainStars = (p) => (p && p.stars ? p.stars.filter((s) => s.type === 'main' || s.type === '吉星' || s.type === '煞星').map((s) => s.name) : []);
-
-/** 一方的某宫（按地支）在对方盘中落到哪个宫位 */
-function landOn(host, branch) {
-  const p = palaceByBranch(host, branch);
-  return p ? { palace: p.palace, branch: p.branch, stars: mainStars(p) } : null;
-}
-
-export function buildZiweiHepan(input) {
-  const A = buildZiwei({ ...input.a });
-  const B = buildZiwei({ ...input.b });
-
-  // ① 互落宫：命宫、夫妻宫各落到对方哪一宫
-  const soulToB = landOn(B, A.soul.branch);
-  const soulToA = landOn(A, B.soul.branch);
-  const spouseBranchA = (A.palaces.find((p) => p.palace === '夫妻') || {}).branch;
-  const spouseBranchB = (B.palaces.find((p) => p.palace === '夫妻') || {}).branch;
-  const spouseAtoB = spouseBranchA ? landOn(B, spouseBranchA) : null;
-  const spouseBtoA = spouseBranchB ? landOn(A, spouseBranchB) : null;
-
-  // ② 四化引动：A 生年四化的星，在 B 盘哪一宫
-  const hits = [];
-  const collect = (from, to, who, targetWho) => {
-    for (const p of from.palaces || []) {
-      for (const s of p.stars || []) {
-        if (!s.mutagen) continue;
-        const target = (to.palaces || []).find((q) => (q.stars || []).some((x) => x.name === s.name));
-        const land = target ? target.palace : null;
-        hits.push({
-          who,
-          star: s.name,
-          mutagen: s.mutagen,
-          ownPalace: p.palace,
-          landingPalace: land,
-          strong: land ? STRONG_LANDS.includes(land) : false,
-          text: `${who}的${s.name}化${s.mutagen}（在本命${p.palace}）落在${targetWho}的${land || '盘外'}——${who}${MUT_MEAN[s.mutagen]}`,
-        });
-      }
-    }
-  };
-  collect(A, B, '你', '对方');
-  collect(B, A, '对方', '你');
-
-  // ③ 评分：互落宫 + 四化
-  let score = 40;
-  const dims = [];
-  if (soulToB) {
-    const strong = STRONG_LANDS.includes(soulToB.palace);
-    const s = strong ? 12 : 5;
-    score += s;
-    dims.push({ key: 'soul', label: '命宫互落', score: s, text: `你的命宫在${A.soul.branch}，落到对方盘的「${soulToB.palace}」${soulToB.stars.length ? `（同宫见 ${soulToB.stars.join('、')}）` : ''}——${strong ? '影响直接，脾气与做派会明显落在对方这一块' : '影响偏间接，主要体现在日常协作上'}。` });
-  }
-  if (soulToA) {
-    dims.push({ key: 'soulBack', label: '对方命宫落你盘', score: 0, text: `对方的命宫在${B.soul.branch}，落到你盘的「${soulToA.palace}」${soulToA.stars.length ? `（同宫见 ${soulToA.stars.join('、')}）` : ''}。` });
-  }
-  if (spouseAtoB && spouseBtoA) {
-    const good = ['命宫', '夫妻', '福德'].includes(spouseAtoB.palace) || ['命宫', '夫妻', '福德'].includes(spouseBtoA.palace);
-    const s = good ? 8 : 2;
-    score += s;
-    dims.push({ key: 'spouse', label: '夫妻宫互落', score: s, text: `你的夫妻宫在${spouseBranchA}，落在对方「${spouseAtoB.palace}」；对方的夫妻宫在${spouseBranchB}，落在你「${spouseBtoA.palace}」。${good ? '双方的感情定位能对上彼此在意的事' : '彼此的期待更容易落在不同领域，需要说清楚'}` });
-  }
-  // 四化净分：禄科为正、忌为负；落在强宫加倍
-  let mutScore = 0;
-  for (const h of hits) {
-    const base = MUT_SCORE[h.mutagen] || 0;
-    mutScore += h.strong ? Math.round(base * 1.5) : base;
-  }
-  mutScore = Math.max(-25, Math.min(25, mutScore));
-  score += mutScore;
-  dims.push({ key: 'mutagen', label: '四化引动', score: mutScore, text: hits.filter((h) => h.who === '你').map((h) => h.text).join('；') || '你这边没有生年四化引动对方的宫位。' });
-
-  const total = Math.max(0, Math.min(100, Math.round(score)));
-  const level = total >= 75 ? '契合度较高' : total >= 55 ? '中等偏顺' : total >= 40 ? '需要磨合' : '差异较大';
-
-  const side = (z, who) => ({
-    who,
-    soul: { branch: z.soul.branch, palace: z.soul.palace },
-    body: { branch: z.body.branch, lands: z.body.lands },
-    bureau: z.bureau.name,
-    ziwei: z.ziwei,
-    tianfu: z.tianfu,
-    soulStars: mainStars(z.palaces.find((p) => p.palace === '命宫') || {}),
-    spouseStars: mainStars(z.palaces.find((p) => p.palace === '夫妻') || {}),
-    natalSihua: (z.palaces || []).flatMap((p) => (p.stars || []).filter((s) => s.mutagen).map((s) => `${s.name}化${s.mutagen}(${p.palace})`)),
-    summary: z.summary,
-  });
-
-  return {
-    system: 'hepan',
-    chart: 'ziwei',
-    a: side(A, '你'),
-    b: side(B, '对方'),
-    score: { total, level },
-    dimensions: dims,
-    interactions: hits,
-    notes: [
-      '紫微合盘看的是「彼此会在对方生活里的哪一块起作用」，不是关系成败的判决。',
-      '口径：命宫与夫妻宫按地支落到对方盘的宫位；四化按「一方的生年四化星在对方盘的落宫」读，落在命宫/夫妻/福德/财帛/官禄加倍计分。',
-    ],
-  };
-}
-
+// 紫微合盘：两盘并排 + 互落宫 + 四化引动。
+// 口径：把一方的「命宫 / 夫妻宫」地支落到对方盘的宫位上，判断影响落在对方哪一领域；
+// 再把一方生年四化所化的星，找它在对方盘的位置，判断「你的某种特质会引动对方哪一宫」。
+// 这是并排对照的读法，不涉及两盘叠加安星（那是另一派做法，本文不采用）。
+import { buildZiwei } from './ziwei.js';
+import { assertCivil } from './validate.js';
+
+const NAMES = ['命宫', '兄弟', '夫妻', '子女', '财帛', '疾厄', '迁移', '交友', '官禄', '田宅', '福德', '父母'];
+const MUT_MEAN = {
+  禄: '会把资源、机会与松弛感带过去',
+  权: '会不自觉地主导或施压',
+  科: '带来的更多是名声、体面与理性',
+  忌: '会勾起压力点与执念',
+};
+const MUT_SCORE = { 禄: 10, 权: 5, 科: 8, 忌: -10 };
+// 落在对方这些宫位时影响最直接
+const STRONG_LANDS = ['命宫', '夫妻', '福德', '财帛', '官禄'];
+
+const palaceByBranch = (chart, branch) => (chart.palaces || []).find((p) => p.branch === branch) || null;
+const mainStars = (p) => (p && p.stars ? p.stars.filter((s) => s.type === 'main' || s.type === '吉星' || s.type === '煞星').map((s) => s.name) : []);
+
+/** 一方的某宫（按地支）在对方盘中落到哪个宫位 */
+function landOn(host, branch) {
+  const p = palaceByBranch(host, branch);
+  return p ? { palace: p.palace, branch: p.branch, stars: mainStars(p) } : null;
+}
+
+export function buildZiweiHepan(input) {
+  assertCivil(input && input.a, 'a');
+  assertCivil(input && input.b, 'b');
+  const A = buildZiwei({ ...input.a });
+  const B = buildZiwei({ ...input.b });
+
+  // ① 互落宫：命宫、夫妻宫各落到对方哪一宫
+  const soulToB = landOn(B, A.soul.branch);
+  const soulToA = landOn(A, B.soul.branch);
+  const spouseBranchA = (A.palaces.find((p) => p.palace === '夫妻') || {}).branch;
+  const spouseBranchB = (B.palaces.find((p) => p.palace === '夫妻') || {}).branch;
+  const spouseAtoB = spouseBranchA ? landOn(B, spouseBranchA) : null;
+  const spouseBtoA = spouseBranchB ? landOn(A, spouseBranchB) : null;
+
+  // ② 四化引动：A 生年四化的星，在 B 盘哪一宫
+  const hits = [];
+  const collect = (from, to, who, targetWho) => {
+    for (const p of from.palaces || []) {
+      for (const s of p.stars || []) {
+        if (!s.mutagen) continue;
+        const target = (to.palaces || []).find((q) => (q.stars || []).some((x) => x.name === s.name));
+        const land = target ? target.palace : null;
+        hits.push({
+          who,
+          star: s.name,
+          mutagen: s.mutagen,
+          ownPalace: p.palace,
+          landingPalace: land,
+          strong: land ? STRONG_LANDS.includes(land) : false,
+          text: `${who}的${s.name}化${s.mutagen}（在本命${p.palace}）落在${targetWho}的${land || '盘外'}——${who}${MUT_MEAN[s.mutagen]}`,
+        });
+      }
+    }
+  };
+  collect(A, B, '你', '对方');
+  collect(B, A, '对方', '你');
+
+  // ③ 评分：互落宫 + 四化
+  let score = 40;
+  const dims = [];
+  if (soulToB) {
+    const strong = STRONG_LANDS.includes(soulToB.palace);
+    const s = strong ? 12 : 5;
+    score += s;
+    dims.push({ key: 'soul', label: '命宫互落', score: s, text: `你的命宫在${A.soul.branch}，落到对方盘的「${soulToB.palace}」${soulToB.stars.length ? `（同宫见 ${soulToB.stars.join('、')}）` : ''}——${strong ? '影响直接，脾气与做派会明显落在对方这一块' : '影响偏间接，主要体现在日常协作上'}。` });
+  }
+  if (soulToA) {
+    dims.push({ key: 'soulBack', label: '对方命宫落你盘', score: 0, text: `对方的命宫在${B.soul.branch}，落到你盘的「${soulToA.palace}」${soulToA.stars.length ? `（同宫见 ${soulToA.stars.join('、')}）` : ''}。` });
+  }
+  if (spouseAtoB && spouseBtoA) {
+    const good = ['命宫', '夫妻', '福德'].includes(spouseAtoB.palace) || ['命宫', '夫妻', '福德'].includes(spouseBtoA.palace);
+    const s = good ? 8 : 2;
+    score += s;
+    dims.push({ key: 'spouse', label: '夫妻宫互落', score: s, text: `你的夫妻宫在${spouseBranchA}，落在对方「${spouseAtoB.palace}」；对方的夫妻宫在${spouseBranchB}，落在你「${spouseBtoA.palace}」。${good ? '双方的感情定位能对上彼此在意的事' : '彼此的期待更容易落在不同领域，需要说清楚'}` });
+  }
+  // 四化净分：禄科为正、忌为负；落在强宫加倍
+  let mutScore = 0;
+  for (const h of hits) {
+    const base = MUT_SCORE[h.mutagen] || 0;
+    mutScore += h.strong ? Math.round(base * 1.5) : base;
+  }
+  mutScore = Math.max(-25, Math.min(25, mutScore));
+  score += mutScore;
+  dims.push({ key: 'mutagen', label: '四化引动', score: mutScore, text: hits.filter((h) => h.who === '你').map((h) => h.text).join('；') || '你这边没有生年四化引动对方的宫位。' });
+
+  const total = Math.max(0, Math.min(100, Math.round(score)));
+  const level = total >= 75 ? '契合度较高' : total >= 55 ? '中等偏顺' : total >= 40 ? '需要磨合' : '差异较大';
+
+  const side = (z, who) => ({
+    who,
+    soul: { branch: z.soul.branch, palace: z.soul.palace },
+    body: { branch: z.body.branch, lands: z.body.lands },
+    bureau: z.bureau.name,
+    ziwei: z.ziwei,
+    tianfu: z.tianfu,
+    soulStars: mainStars(z.palaces.find((p) => p.palace === '命宫') || {}),
+    spouseStars: mainStars(z.palaces.find((p) => p.palace === '夫妻') || {}),
+    natalSihua: (z.palaces || []).flatMap((p) => (p.stars || []).filter((s) => s.mutagen).map((s) => `${s.name}化${s.mutagen}(${p.palace})`)),
+    summary: z.summary,
+  });
+
+  return {
+    system: 'hepan',
+    chart: 'ziwei',
+    a: side(A, '你'),
+    b: side(B, '对方'),
+    score: { total, level },
+    dimensions: dims,
+    interactions: hits,
+    notes: [
+      '紫微合盘看的是「彼此会在对方生活里的哪一块起作用」，不是关系成败的判决。',
+      '口径：命宫与夫妻宫按地支落到对方盘的宫位；四化按「一方的生年四化星在对方盘的落宫」读，落在命宫/夫妻/福德/财帛/官禄加倍计分。',
+    ],
+  };
+}
+