家族資料格式
唯一母資料
- 人物:
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: reviewedurl保存當時網址;連結失效時改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: reviewedrelationship、relationship_detail、birth_order分別保存續柄、續柄細別與出生別原文。father_name、mother_name永遠保存原載文字;能唯一對應人物時另加father_ref、mother_ref,並建立 canonicalparents關係。- 父母若原本不是人物節點,仍須建立永久人物 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: 1union_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:releaseverify:fast 用於日常資料/文件修改;verify:release 用於發布前的完整測試與親友密碼版網站建置。若要單獨預覽,使用 npm.cmd run build:dev;正式親友版可明確使用 npm.cmd run build:family,公開遮罩版使用 npm.cmd run build:public。build:redacted 僅保留為相容別名。驗證錯誤會停止建置;資料不完整、異載或待確認只列 warning。