cbdb-online-main-server

中國歷代人物傳在線記录入系统原始碼。

授權 / License: 源代碼採 CC BY-NC-SA 4.0 International；CBDB 數據適用 CBDB 資料授權條款 / CBDB Data Licensing Terms（詳見 LICENSE.md）

文件導覽（2026 更新）

開發指南

• AGENTS 指南 - AI 代理開發必讀
• 數據庫完整指南 - ⚠️ 必讀：環境、兼容性、Schema 管理
• Dev Container 使用說明 - VS Code / Codespaces 一鍵啟動開發環境
• CHANGELOG

開發手記

• 升級指南 - Laravel 框架升級記錄
• AdminLTE 的歷史與下架紀錄（2026-09-15 完整下架，歷史文件）
• Proposal / Approval Flows
• 人物提案路徑現況 - 三條核准路徑與逐資源總表
• 代碼表格前端實作比較
• 代碼表界面白名單維護
• 代碼表界面效能優化
• Posting/Office 流程備忘
• Resource TTS 注意事項
• 使用者權限說明
• 若需批次導入資料，請參考 BATCH_UPLOADERS
• CBDB 公共 API v1 說明
• 單向關係修復工具
• MERGE 工具說明
• 檢視表總覽
• 姓名搜索索引管理
• SQLite 每週同步 - 自動匯出並同步到 HuggingFace

更多文檔

• AdminLTE 4 升級可行性（⚠️ 已被 React/Inertia 遷移取代，歷史文件）
• AI 任官自動填充設計
• API 認證方案
• 稽核日誌提案
• 人物提案流程實作狀態
• BiogMain Repository 重構計畫
• CHGIS 地圖 Place Name 連結與浮出地圖
• 複合主鍵 URL 設計
• 資料庫 Schema（MySQL/SQLite）
• Laravel Query 審查
• MCP HTTP 介面提案
• MCP 使用指南
• 姓名搜尋效能改進
• Prometheus 指標說明
• Schema 文檔生成說明
• SQLite 數據發佈流程
• SQLite 遷移計畫

技術環境

生產環境

• PHP: 8.2+ (最低 8.2.0，建議 8.4)
• Laravel: 12.x (已從 11.x 升級，參見 UPGRADE.md)
• 數據庫: MariaDB 10.11.14 (Ubuntu 24.04；2026-08-03 於 prod 實測)
• Web Server: Caddy
• Node.js: 22.x（建議搭配 npm 10）

前端構建現況

• 主要互動頁面均為 React/Inertia（人物列表/檢視/詳情中樞、13 個編輯器、Codes、營運管理工具、認證頁、Query Playground 等），React 元件在 resources/js/inertia/**。📌 遷移期的 feature flag（config/migration_flags.php、migration_flag()）已於 Blade 下架環節 4d-1 整組移除——沒有任何 runtime 回退鍵。
• 所有 legacy Blade 頁面已實體刪除（環節 4a／4b-4）：舊 URL 只剩 302 導向 /app 對應頁、legacy 寫入端回 410 的 closure。AdminLTE 3 (Bootstrap 4) 已於環節 5 完整下架（5a layout 6 檔、5b 前端資產與 npm 相依）。🔴 這批頁面已經沒有回退鍵了：翻 migration flag 沒有效果，而 LEGACY_PAGE_RETIREMENT 這個開關本身已於環節 4b-4c 移除（middleware、config、Kernel 別名、env 變數全部刪除）。要回到 Blade 只能 git revert 並重新部署。認證頁與首頁（auth.*／welcome）也已於環節 4c 實體刪除 —— 它們原本是最後一批「翻 flag 真的會渲染 Blade」的頁面，現在翻 MIGRATION_FLAG_AUTH_*／MIGRATION_FLAG_WELCOME 也不再改變任何渲染。人物編輯全套（basicinformation.*）與唯讀頁（operations／dashboard／view／merge-preview／crowdsourcing／nl-query-logs／admin.audit-logs／admin.ai-fill-logs）已實體刪除、無法回退（舊 URI 只剩 302 導向）。表單／寫入頁（codes 全套／manage／profile／admin.explainsql／3 個 batch-load／admin.cbdb-table-maintenance／admin.unidirectional-relationship-repair）也已於環節 4b-4a／4b-4b 實體刪除，同樣無法回退。逐條清單見 docs/BLADE_RETIREMENT_STAGE3_ROUTE_MANIFEST.md。新功能一律只做在 React/Inertia 路徑。
• 構建系統為 Vite；入口只有 3 個：resources/js/inertia/app.tsx（React/Inertia，全站互動頁）、 resources/js/historical-maps/app.js、resources/js/chgis-map/app.js。 🔴 不要重新引入 jQuery／Bootstrap／DataTables／Select2／Vue——整套已於環節 5b 移除（含 npm 相依）。
• 主站頁面均使用 @vite 載入前端資源，請勿引入 jQuery／Bootstrap／DataTables／Select2／Vue（不分 CDN 或 npm；整套已於 Blade 下架環節 5b 移除）。 例外是三個自給自足、不套任何殼的獨立頁：resources/views/cbdbapi/person.blade.php、public/cbdbapi/index.html（皆自帶 CDN Bootstrap 5.3）、resources/views/maps/index.blade.php（CDN Leaflet）。

⚠️ 重要：本專案現已升級到 Laravel 12.x 並要求 PHP 8.2+。建議使用 PHP 8.4 以獲得最佳性能和安全性。Laravel 12 已完全支持 PHP 8.4。

數據庫兼容性原則

⚠️ 重要：為保持未來遷移到其他數據庫實現的靈活性，請遵循以下原則：

• 避免使用特定數據庫專屬功能（如 MySQL 的 ngram parser、MariaDB 專屬插件）
• 優先使用標準 SQL 語法
• 如需使用數據庫特性，應在代碼中提供降級方案或文檔說明
• 索引策略應基於通用的 B-Tree 或其他跨數據庫支持的類型

帳號權限分離（重要）

基線 migration 會觸及完整 schema，為了降低事故風險，務必將一般應用連線與 migration 連線分離，避免日常帳號擁有過高權限。

配置原則：

• foo：一般應用使用者，僅需 CRUD 權限（不含 DROP/ALTER/CREATE）。
• foo_migrate：僅供 migration 使用的專用帳號，具備 schema 變更所需權限。

範例設定（.env）：

DB_USERNAME=foo
DB_PASSWORD=***

DB_MIGRATE_USERNAME=foo_migrate
DB_MIGRATE_PASSWORD=***

實際對應欄位請以 config/database.php 為準。

開發入口

常用命令

composer install
npm install
./vendor/bin/php-cs-fixer fix
./vendor/bin/phpunit
npm run build
php artisan cbdb:fetch-chgis-map
php artisan cbdb:rebuild-person-change-index   # 部署後須跑一次：回填人物層級修改水位線（否則 /api/v2/persons 的 c_modified_date 全為 null）

部署提醒：person_change_index（供 /api/v2/persons 的 c_created_date / c_modified_date）的 migration 只建表不回填。部署到任何環境後須手動執行一次 php artisan cbdb:rebuild-person-change-index 做初始全量回填；之後日常由系統即時維護，並可定期以 --since 增量校正。詳見 docs/PERSON_CHANGE_INDEX_DESIGN.md。

前端

• 主要 React/Inertia 線上路徑：/app/basicinformation（人物列表 / 詳情中樞 / 13 個編輯器）、/app/query-playground、/app/codes、/app/operations 等。
• 舊版 Blade 路由已全面下架（顯示頁 302、寫入端 410）。唯讀頁（環節 4a）與表單／寫入頁（環節 4b-4a／4b-4b）的視圖與 controller 方法都已實體刪除，舊 URI 只剩 closure。🔴 沒有任何回退鍵：migration flag 無效，而 LEGACY_PAGE_RETIREMENT 這個開關已於環節 4b-4c 連同 middleware 一起移除。認證頁與首頁的 Blade 版已於環節 4c 刪除，MIGRATION_FLAG_AUTH_*／MIGRATION_FLAG_WELCOME 不再決定渲染。人物編輯全套已實體刪除。Query Playground 與外部資料庫引用瀏覽器本就硬導向 React、無 flag。皆不再新增功能；新功能一律做在 React/Inertia。
• 前端入口：
  • resources/js/inertia/**（React/Inertia，全站互動頁）
  • resources/js/historical-maps/**、resources/js/chgis-map/**（兩支獨立地圖入口）

後端

• 主要路由定義：routes/web.php
• Query Playground / Historical QA：
  • app/Http/Controllers/QueryPlaygroundController.php
  • app/Services/QueryPlaygroundService.php
  • app/Services/NaturalLanguageQueryService.php
• 複合主鍵定義：app/Support/CompositePrimaryKey.php

重要規則

• 複合主鍵表請使用 Query Builder，不要依賴 Eloquent 主鍵行為
• Migration 必須同時兼容 MariaDB/MySQL 與 SQLite
• 修改 resources/js/** 後，提交前請執行 npm run build
• commit message、介面文案與文檔使用繁體中文

更多說明

• 日常開發請先看 AGENTS.md
• 近期變更摘要請看 CHANGELOG.md
• 資料庫與 migration 規範請看 DATABASE.md

其他說明

• API 控制器位置：app/Http/Controllers/Api
• Windows 本地部署、TLS/SSL 與其他歷史維運說明，請優先查閱 docs/ 與相關 issue，不再在 README 展開維護。
• 若前端依賴異常，可依序嘗試：

rm -rf node_modules
npm cache clear --force
npm install
npm run build

• 建議使用 Node.js 22 與 npm 10；Ubuntu 可用 nvm 安裝。
• 若 storage/logs/laravel.log 無法寫入，請檢查 web server 使用者是否擁有該檔案權限。

SQLite 每週同步

本專案提供自動化腳本，將生產環境的數據庫匯出為 SQLite 格式，並同步到 HuggingFace 公開數據集 cbdb/cbdb-sqlite 供研究者下載使用。

最新下載入口：

• https://huggingface.co/datasets/cbdb/cbdb-sqlite/resolve/main/latest.zip
• https://input.cbdb.fas.harvard.edu/latest.zip

腳本位置

• 匯出腳本：scripts/export-daily-sqlite.sh - 將 MySQL/MariaDB 表格匯出為 SQLite
• 同步腳本：scripts/weekly-sqlite-sync.sh - 匯出、壓縮並上傳到 HuggingFace

前置安裝（Ubuntu）

# 安裝 zip 壓縮工具
sudo apt-get install zip

# 安裝 hf CLI
sudo apt-get install -y pipx
pipx install huggingface-hub
pipx ensurepath

HuggingFace 認證設定

腳本支持兩種認證方式（二擇一）：

# 方式一：hf auth login（推薦，token 安全存儲於 ~/.cache/huggingface/）
hf auth login

# 方式二：HF_TOKEN 環境變數
export HF_TOKEN=hf_你的token

# 驗證認證狀態
hf auth status

Access Token 設定：

1. 前往 https://huggingface.co/settings/tokens
2. Create new token → 選擇 Fine-grained
3. 勾選 Repositories → Write 權限
4. 複製 token 並在服務器上執行認證

Cron 定時任務

# 編輯 crontab
crontab -e

# 每週日凌晨 3 點執行（GMT+8）
0 3 * * 0 /path/to/cbdb-online-main-server/scripts/weekly-sqlite-sync.sh >> /var/log/cbdb-sqlite-sync.log 2>&1

手動執行

# 執行完整同步流程
bash scripts/weekly-sqlite-sync.sh

# 僅匯出 SQLite（不上傳）
bash scripts/export-daily-sqlite.sh

腳本流程說明

weekly-sqlite-sync.sh 執行以下步驟：

1. 前置檢查：確認 zip、hf 已安裝且 HuggingFace 認證有效
2. 匯出數據庫：呼叫 export-daily-sqlite.sh 產生 cbdb_YYYYMMDD.sqlite3 與 cbdb_YYYYMMDD.json
3. 壓縮檔案：產生 cbdb_YYYYMMDD.zip（zip 內使用平面檔名，不包含絕對路徑）
4. 上傳到 HuggingFace：將 history/cbdb_YYYYMM/cbdb_YYYYMMDD.zip、latest.zip、metadata/YYYY-MM/YYYY-MM-DD.json 及 latest.json（metadata 副本）以單一 commit 上傳至數據集倉庫
5. 清理：刪除所有臨時檔案（包括原始 SQLite 匯出檔與 metadata）