家族資料格式

唯一母資料

  • 人物:content/10-人物/Pxxx.md,一人一檔,同時是網站人物頁。
  • 關係:data/relationships/Rxxx.md。
  • 事件:data/events/Exxx.md。
  • 戶籍戶、地點、來源:分別位於 data/households、data/places、data/sources。
  • quartz/static/family-data.json 是建置產物,禁止人工編輯。

檔名只用永久 ID,不使用姓名。姓名、排行、房支或世代更正時,ID 不得變更或重用。

人物檔

---
id: P014
entity_type: person
title: 謝恭
names:
  - value: 謝恭
    kind: preferred
    preferred: true
sex: male
branch: 謝恭支
rank: 四男
generation_hint: 3 # 只供目前排版參考,不是永久身分
parents:
  - person: P004
    role: father
    review_status: reviewed
  - person: P005
    role: mother
    review_status: reviewed
birth_claims:
  - claim_id: P014-B01
    original: 咸豐庚申年五月十六日未時
    calendar: chinese_lunisolar
    gregorian: 1860-07-04
    precision: day
    preferred: true
    review_status: confirmed
    source: 謝恭本人修訂族譜
privacy:
  visibility: public
  living_status: deceased_or_historical
draft: false
source_refs: [S005]
source_pages: []
tags: [人物, 謝恭支]
---

人物檔只手工保存人物本身、父母、生卒異載、隱私、敘事與來源。禁止手工加入 children、spouses 或事件反向清單;網站由其他節點反推。

人物正文與延伸內容

人物頁除了結構化 frontmatter,也可以保存家族敘事,但必須避免與事件、關係及地點節點重複維護。正文統一採以下順序;沒有資料的段落可省略:

# 姓名
 
一句話身分摘要。
 
## 生平
 
經校閱的敘事性介紹;日期、婚姻、遷徙等事實仍以 Event 節點為權威。
 
## 名字讀音與意義
 
保存方言讀音、羅馬字、命名由來及提供者。
 
## 照片與影像
 
只顯示 `external_links` 或媒體節點反推的連結及說明。
 
## 補述
 
依日期逐則追加,標示提供者與校閱狀態;不得覆蓋舊說。

外部網站與媒體連結

IG、Facebook、YouTube、Blog、Google 相簿及個人網站可以記入人物檔,但網址不是永久憑據。使用結構化 external_links,同時保存檢查日期、失效狀態與可合法保存的封存網址:

external_links:
  - link_id: P014-L01
    kind: youtube # instagram | facebook | blog | website | google_photos | other
    label: 訪談錄影
    url: https://www.youtube.com/watch?v=...
    description: 家族口述訪談
    status: active # active | broken | removed | archived
    first_recorded_on: 2026-08-12
    last_checked_on: 2026-08-12
    archive_url: null
    visibility: family # public | family | private
    review_status: reviewed
  • url 保存當時網址;連結失效時改 status,不得刪除舊記錄。
  • archive_url 只填入已依法、依平台規則或經權利人同意保存的封存副本;不得假定所有社群內容都可抓取備份。
  • 照片或影片若本身是重要史料,未來應另建媒體節點,保存檔案雜湊、拍攝日期、人物、授權與來源;外部連結只作入口。

Google Drive 媒體連結

第一版大型媒體直接引用 Google Drive,不把原件放入 Git。正式資料使用 media_links,至少保存 media_id、類型、Drive file ID、預覽網址、來源案件、提供者、分享同意與最後檢查日期。案件資料夾保持私人,只將網站實際選用的單一檔案開放為知道連結的檢視者。完整欄位、發布與 R2 清理程序見 Google Drive媒體發布標準程序。

名字讀音與意義

名字的台語、客語、日語或其他讀音,以及命名意義,可用 name_notes 保存;不確定的讀音不得標為已確認:

name_notes:
  - name: 謝恭
    language: nan-tw
    pronunciation: null
    romanization: null
    meaning: null
    contributor: null
    recorded_on: null
    source_ref: null
    review_status: unreviewed

補述規則

簡短補述可直接寫在正文,標題格式為 ### YYYY-MM-DD 提供者。需要被搜尋、引用或多人共同校閱的內容,改用結構化 supplements:

supplements:
  - supplement_id: P014-N01
    recorded_on: 2026-08-12
    contributor: 家族提供者姓名或代碼
    text: 補述原文
    source_ref: null
    review_status: unreviewed

不得沿用的舊範例欄位

  • 不使用 世代、字輩、房支、性別、生年、卒年 等中文舊鍵;一律採本文件的 canonical 欄位。
  • 出生地、婚姻、遷徙、墓地與大事記由 Event+Place 節點組合;人物正文可以敘述,但不得成為第二份權威日期。
  • 不在人物檔手寫 配偶、子女 或父母反向名單。
  • 不把「第幾世」寫成永久身分;只能使用可重新計算的 generation_hint。

日治戶籍人物欄

凡全文轉錄中有獨立人物欄者,必須在該人物檔保存 registry_records;不得只取姓名與西元生日後丟棄其他欄位。

registry_records:
  - source_ref: S006
    page: "24"
    relationship: 婦
    father_name: 陳春選
    father_ref: P159
    mother_name: 陳胡氏烏哖
    mother_ref: P160
    relationship_detail: 三男謝盛宗ノ妻
    birth_order: 長女
    name_original: 謝陳氏猜(校訂:統一作謝陳氏猜;父陳春選,本姓陳)
    birth_original: 大正八年参月拾八日
    annotations: |-
      高雄州東港郡林邊庄田墘厝字田墘厝百六十四番地陳春枝姪 昭和拾式年参月壹日婚姻入籍
      民國八年歲次己未年式月拾八日寅時出生
    original_text: |-
      續柄:婦
      父:陳春選
      母:陳胡氏烏哖
      ……
    review_status: reviewed
  • relationship、relationship_detail、birth_order 分別保存續柄、續柄細別與出生別原文。
  • father_name、mother_name 永遠保存原載文字;能唯一對應人物時另加 father_ref、mother_ref,並建立 canonical parents 關係。
  • 父母若原本不是人物節點,仍須建立永久人物 ID;不得把他們永久留成附屬字串。
  • annotations 保存人物欄下方的入籍、除籍、地址、死亡及家傳日期等文字;original_text 保存整欄轉錄,以便日後重新解析。
  • 完整戶籍欄位只進入本機家族校閱資料,不直接寫入正式公開 JSON。
  • 每次大量匯入後必須執行 audit-registry-details.mjs;未對應、歧義或缺漏筆數不為零時不得交付。

關係唯一存放規則

事實唯一權威位置
生物父母子女人物檔的 parents
子女名單編譯器反推,禁止手寫
妻、前妻、後妻、繼室、妾、收養、過房Relationship 節點
婚姻、入戶、分戶、寄留、轉居日期Event 節點
人物生卒異載人物檔 inline claims
戶籍戶Household 節點
番地與歷史地名Place 節點
文件及頁碼Source 節點+事實引用

關係不保存日期;同一日期不得同時寫在關係與事件。父母只寫在子女端,不在父母檔重複列子女。

婚配身分與先後次序

歷史族譜中「妻」與「妾」是不同身分,不得簡化成相同的配偶類型。小世界圖運算仍使用廣義 spouse 邊,但關係節點必須另存:

relationship_type: spouse
participants: [P027, P028]
roles:
  P027: 夫
  P028: 前妻
union_type: marriage
union_order: 1
  • union_type: marriage:妻、前妻、後妻、繼室等正式婚配。
  • union_type: concubinage:妾。
  • union_order:只表示資料明載的婚配先後;前妻為 1,後妻或繼室通常為 2。
  • 「前妻」不自動解讀為離婚。傳統族譜常指先娶之妻,後妻常為前妻過世後再娶;是否因喪偶再娶,必須由死亡與婚姻事件佐證,不得只根據「前/後妻」推斷。
  • 現代資料若明載某人為「前夫」,另一端必須對稱記為「前妻」;這只表示兩人曾有婚姻且婚姻已結束,不等於其中一人過世,也不得自行判定是離婚、喪偶或其他原因。
  • 「前夫/前妻」與傳統譜載的「前妻/後妻」雖共用婚配關係節點,語境不同。婚姻終止日期、原因或再婚事實只有在來源明載時才另建 Event。
  • roles 中的角色屬於該 ID 本人;例如 P028: 前妻,不可掛到丈夫 ID。

世系圖排版規則

  • 同一父母所生的同輩兄弟,先依明載排行排序;排行缺漏時才以已校定出生日期補充判斷。
  • 手足連線的「兄、弟、姊、妹」是相對於目前中心人物的動態稱謂,不寫死在人物母檔。兩人出生日期不同時依日期判斷長幼;日期不足時,僅限同性別且雙方排行可比較時使用排行;仍無法判斷則顯示「兄弟/姊妹/手足」,不得憑 ID 或版面位置猜測。
  • 不論頁面採橫排文字或直排姓名,同輩均由右至左、由大到小排列,最年長者在最右。
  • 不得只按人物 ID 或 Markdown 檔名決定長幼。
  • 夫妻並列時採「考右妣左」:男子在右、妻子在左;每位妻、妾仍是獨立人物節點,不合併到丈夫欄位。
  • 中心小世界中夫妻採近距離成對排列;男方手足置於男方右側,女性本人(妻方)的手足置於左側,不得讓妻與男方手足混在同一欄。
  • 「考/妣」在此只說明傳統譜式的相對位置,不據此替仍在世人物加上死亡稱謂。

日期

  • 網站主要顯示 preferred: true 的西元日期。
  • 原始年號、農曆、日治戶籍異載全部保留。
  • 只有年份時使用 precision: year,不得補造月日。
  • 換算失敗時 gregorian: null,保留原文並標示 unreviewed 或 disputed。
  • 日本明治六年以前的年號日期不得直接當成同月同日的西元日期。

生卒缺載與在世推定

  • living_status: living 只用於已確認仍在世者;possibly_living 不等於已確認在世。
  • living_status: unknown 用於沒有足夠證據判斷在世或已故者;人物卡顯示狀態未確認,不計算現年、享壽或冥壽。
  • 未載卒日且本人已知年齡達 95 歲以上時,不再自動顯示「仍在世」或繼續累加現年。
  • 本人生辰未載,但配偶或手足的已知年齡已達 95 歲以上時,同樣視為生卒狀態未註記。
  • 民國35年(1946)族譜中的早期世次人物,即使生卒皆缺載,經人工依世次與上下代年代確認不可能仍在世後,標為 deceased_or_historical;判定依據、提供者及日期必須寫入 notes。不得只憑 generation_hint 由程式批次推定死亡。
  • 人物卡的缺載欄位顯示「未註記」,不推算享壽或冥壽;中心小世界與直式世系以 ? 表示未知卒年。
  • 這項顯示規則不會補造卒年,也不會改寫史料;日後取得卒年或確認仍在世時,直接更新人物母檔即可。

隱私

可能在世者的母資料預設:

privacy:
  visibility: family
  living_status: possibly_living
draft: true

兩種發布模式必須分清楚:

  • public 公開遮罩模式:保留匿名連接點,但姓名、生日、人物頁、地址與事件內容不輸出;本人同意公開後才由管理人調整。
  • family 親友密碼完整版:依資料持有人 2026-08-12 的明確決定輸出全部人物及典藏資料;目前 GitHub Pages 使用此模式。JavaScript 共用密碼不是加密,不能據此推定敏感資料受到真正存取控制。

建置

npm.cmd run verify:fast
npm.cmd run verify:release

verify:fast 用於日常資料/文件修改;verify:release 用於發布前的完整測試與親友密碼版網站建置。若要單獨預覽,使用 npm.cmd run build:dev;正式親友版可明確使用 npm.cmd run build:family,公開遮罩版使用 npm.cmd run build:public。build:redacted 僅保留為相容別名。驗證錯誤會停止建置;資料不完整、異載或待確認只列 warning。