# 人體經絡穴道圖：公開人體模型導入與正式版計畫

更新：2026-09-16。範圍：延續既有十四經絡／361 穴位網站。第一個里程碑是使用公開授權的真人比例基礎網格、可回溯的表面錨點及可交付的覆核流程；不是在沒有醫學覆核的情況下宣稱正式教材完成。

## 線上儲存與展示版本：第一、第二階段
- 使用 Cloudflare D1（SQLite）保存模型工作草稿、展示資料與操作／版本歷史。沿用私人網站登入，API 限網站擁有者，其他身分不得寫入。
- 預設開啟展示版本；按「編輯草稿」接續線上草稿，按「儲存草稿到線上」保存。目前儲存期間暫停編輯，避免送出與後續修改混淆。
- 男女各自保存。重新開啟、換裝置可讀取線上資料；本機暫存只供同一帳號與裝置意外關閉後復原。
- 先儲存，再逐穴或整條經絡確認。確認記錄編輯者與時間；移動位置或變更定位依據後失效。註記文字修改不會撤銷定位確認。這不是專業醫學核可。
- 按本經或全部範圍套用展示版本，畫面先顯示位置數、變更數與待確認數。範圍內全部位置確認後才可套用。其他模型與範圍保持現行展示。
- 歷史包含初始展示、儲存、確認、套用與還原。每次展示更新有固定快照，還原會新增紀錄，不刪除歷史，也不修改已儲存的工作草稿。每頁 100 筆，可查看較早紀錄。
- 線上版本衝突時拒絕覆蓋，本機修改與暫存仍保留。請先下載 JSON，再重新載入線上版本並整合。第一版不提供自動合併。
- JSON 匯入先成為未儲存草稿，匯出是備份，不視為線上儲存完成。
- 經絡連線按目前穴位重新計算幾何貼合，仍未經專業循行覆核，不隨位置確認自動標示已核可。
- 已以實際 SQLite 執行遷移及 API 測試，涵蓋身分／來源驗證、跨模型拒絕、重新讀取、舊修訂衝突、操作重播、確認失效、局部套用及還原。實際前端狀態處理函式也已驗證模式切換、保存、清除暫存及衝突保留；未宣稱完成瀏覽器實機驗收。

## 視角操作與中文標示更新
- 上下旋轉擴大為 ±89°，提供頭頂／腳底快捷視角；重設回到完整正面。
- 移除地面網格及圓環。右鍵依螢幕方向上下左右平移，雙指同時支援平移與捏合縮放。平移只改相機及觀看中心，不改模型或穴位座標。
- 單條經絡預設顯示可見面的中文穴位名稱，左右避讓並用引線對應；可加代碼或關閉。清楚閱讀模式在空間不足時隱藏部分標示並提示放大，選取穴位優先保留；完整標示保留可見點的名稱，密集區需放大閱讀。
- 名稱可點選且區分人體左右側；總覽只標示目前選取位置。SVG 匯出包含名稱與引線，使用相同配置規則。
- 已以實際操作函式測試角度極限、相機平移、重設、右鍵不誤編輯、雙指平移縮放、左右名稱與 SVG。現有自訂 Worker 專案未具備此環境支援的瀏覽器預覽伺服器，本輪未完成瀏覽器與手機實機驗收。

## 名稱可見性更新（2026-09-17）
- 使用穴位所在面的頂點法線與重心權重得到平滑朝向，逐穴計算與觀看方向的夾角。50° 開始淡出，70° 隱藏，回到65°內才重新顯示。
- 名稱與引線以約180毫秒過渡，名稱位置逐畫面跟隨；遮蔽檢查分開更新，保留穩定的水平排列。隱藏及淡出至不可操作狀態的名稱不接收滑鼠或鍵盤選取。
- 透視僅適用穴位點與循行線；中文名稱仍遵守表面朝向與身體遮蔽。
- 以完整文字框與穴位的邊界距離進行24px淡出，不把文字上下推回畫面。選取的穴位資訊仍保留在側欄。
- 定位此穴位依平滑法線選擇視角，必要時嘗試鄰近方向避開身體遮擋。SVG採當下可見性，不包含時間過渡。
- 已測試角度與重新顯示門檻、隱藏後的點選停用、透視遮蔽、文字框邊界、水平引線及男女共1,340個平滑法線。未進行瀏覽器與手機實機驗收。

## 產品範圍與決策
- 現階段：成年男性／女性切換、固定 A-pose、十二正經與任督二脈、左右側、搜尋、3D 與 SVG、逐穴修訂草稿。
- 人體：MakeHuman 官方 hm08 基礎網格，CC0。Blender Human Base Meshes 官方下載本次不可用，改採先前比較過的同級公開授權方案。
- 前端：保留 Three.js r170；模型打包 GLB，網站本地提供，不依賴外部 CDN。
- 既有私人存取方式維持；新增經過身分驗證的資料 API，不新增付款或外部登入系統。
- 正式教材之後才擴充：經外奇穴、其他奇經、內行支脈、骨骼／肌肉圖層、多體型／多姿勢、針刺相關內容。

## 男女體型與姿勢：已實作
| 項目 | 男性 | 女性 |
|---|---|---|
| 官方變形設定 | male / young | female / young |
| 肌肉量與體重 | average muscle / average weight | average muscle / average weight |
| 姿勢 | 固定 A-pose：雙臂斜張、雙腳分開、手指展開 | 相同固定姿勢 |
| 穴位資料 | 獨立 670 個表面位置、642 段幾何連線 | 獨立 670 個表面位置、642 段幾何連線 |
| 起始狀態 | 預設顯示；所有位置待覆核 | 按「女性」切換；所有位置待覆核 |

- 使用 MakeHuman 官方 male/female 年輕成人變形檔；三組官方地域外形目標各占三分之一，是製作上的混合設定，不代表特定族群平均。
- 「適中」指軟體的肌肉量與體重中間預設；沒有指定真實身高、公斤數或 BMI，也不宣稱是台灣人口平均。兩模型顯示高度統一為 3.9 模型單位，方便觀察。
- 沿用基礎網格固定姿勢；並非每一穴位的實際取穴姿勢，也不預設為手掌朝前的標準解剖姿勢。這次提供男女切換，尚未加入姿勢切換。
- 切換保留目前經絡、穴位、左右側與視角；停止自動旋轉及表面編輯，以便檢視切換結果。
- 男女各自保留當前頁面的穴位、註記、來源、復原紀錄與修訂草稿。離開或重新整理前請分別按線上儲存；JSON 保留作為額外備份。
- 匯入會檢查模型 ID；不能把男性草稿匯入女性模型。舊中性模型草稿也不能直接套用，需保留原始檔，另行建立可追溯的遷移與覆核程序。
- SVG 圖面與下載檔名標示男女；JSON 內保留對應模型 ID。所有資料均維持待專業覆核，兩套模型都需各自驗收。
- 已驗證兩套 GLB 解析、670 個錨點重建、跨模型匯入拒絕、SVG 性別標示、獨立草稿／復原、切回保留、載入失敗重試與未下載草稿偵測。
- 已離線檢視男女正面與側面模型幾何；尚未完成瀏覽器互動與手機實機驗收。

## 後續體型與姿勢擴充順序
1. 先對男女固定姿勢各完成一條經絡的專業標定，作為雙模型樣板。
2. 依實際教材需要增加纖瘦／較豐滿體型；每個版本分開建立與覆核錨點，不單純等比例縮放。
3. 需要抬臂、屈膝或掌背切換時，加入骨架與姿勢設定，讓人體、穴位、循行線一致變形，再檢查遮蔽與皮膚伸展造成的位置差異。
4. 完成實機驗收後，再評估多姿勢是否可用於正式教材。

## 工作分解、責任與驗收
| 階段 | 工作 | 交付與驗收 | 責任 | 排程估計 |
|---|---|---|---|---|
| 1 模型來源 | 固定原始資產、SHA-256、授權、移除 helper 幾何、標準化座標 | GLB、來源清單；只有人體表面、可重建、不混入第三方授權不明素材 | 工程 | 本輪執行 |
| 2 網頁接入 | 非同步模型載入、錯誤提示、材質、深度遮蔽、旋轉與 SVG | 原功能保留；模型由同源載入；失敗明示、不冒充成功 | 工程 | 本輪執行 |
| 3 幾何錨定 | 舊示意座標依身體區段換算，再投射到三角面；左右分開 | 每個顯示點具有模型版本、面編號、重心座標、偏移距離、未覆核狀態 | 工程 | 本輪執行；幾何貼合非醫學認證 |
| 4 覆核工具 | 點選表面修訂、側別、復原、JSON 匯入匯出、模型版本檢查 | 可攜式覆核草稿；匯出後能還原；不得自動標示專家已核可 | 工程 | 本輪執行 |
| 5 名稱與定位文獻 | 361 穴名稱／別名／代碼逐筆比對，補部位、骨性標記、骨度分寸、頁碼與圖號 | 每穴可追溯來源；爭議位置列入問題清單 | 內容編輯＋中醫師 | 3–5 工作日 |
| 6 專業標定 | 優先校核肺經、任督、手足末端，再完成其他經絡；左右側分開確認 | 先通過樣板經絡，再完成全部 670 個顯示位置；每項有覆核人、日期與意見 | 中醫師＋3D 標定人員 | 7–15 工作日，視覆核檔期 |
| 7 經絡路徑 | 區分體表循行、分支、交會與內行；路徑獨立於穴位序號 | 不以編號直接推斷所有循行；分支清楚、無不合理穿模或跨區連線 | 中醫師＋工程 | 3–5 工作日，可與第 6 階段重疊 |
| 8 視覺與實機驗收 | Chrome／Safari／Firefox、Android／iOS、桌面、觸控、鍵盤、200% 字級、模型與 SVG 效能 | 無阻斷錯誤、搜尋／選穴／回復／匯出通過；手機操作由實機確認 | QA＋使用者 | 2–3 工作日 |
| 9 正式交付 | 專業覆核簽核、來源／授權清單、資料版本、維運與回復 | 工程驗收與內容驗收各自通過後，才更改產品定位 | 專案負責人 | 1–2 工作日 |

以上為人工作業估計，不是本次自動執行時間或承諾完成日。專家覆核及資料取得是主要依賴；工程工作可以先完成。

## 資料結構
- acupoint：code、繁體名稱、別名、經絡、部位、定位描述、來源、內容覆核狀態。
- anchor：code、side、modelId、triangle、barycentric[3]、normalOffset、position、method、projectionDistance、reviewStatus。
- path：channel、side、branchId、surfaceSamples；體表順序展示與專業循行資料分開。
- review：reviewer、reviewedAt、sourceReference、comment。工具不產生假的覆核人或核可日期。
- 模型或拓樸改版時需重新建立錨點；不得無條件套用不同模型的面編號。

## 優先覆核順序
1. 中府、尺澤、太淵、少商：驗證肺經胸／臂／腕／指的跨區對應。
2. 任督：確認前後正中線、頭頂、口唇、會陰／尾骶位置。
3. 合谷、內關、勞宮與手指端：確認掌背、橈尺側、手指差異。
4. 足三里、三陰交、太谿、太衝、湧泉：確認膝、踝、足背及足底。
5. 膀胱經兩側線、膽經頭部折返：確認分支與相鄰點順序。
6. 其餘穴位依經絡逐筆簽核，保留未決問題。

## 你需要參與的事項
- 先確認此產品以自學展示還是正式課程教材為目標；目前採自學示意定位，不阻擋工程執行。
- 安排熟悉針灸定位的中醫師或教師覆核，優先做一條經絡的樣板驗收。
- 提供可使用的定位教材版本與引用方式；四張照片可做內部對照，不能推定有公開轉載授權。
- 用常用的手機與電腦確認字體、旋轉速度、點選與閱讀習慣。
- 不需要自行下載模型、轉檔、部署或手動整理 361 個資料欄位；工程側先完成。

## 正式版門檻
- 361 個名稱／代碼無缺漏，配對經絡 309×2 加任督 52＝670 個顯示位置。
- 670 個位置逐一可追溯並覆核；自動投影通過不代表位置正確。
- 未覆核項目不顯示為正式定位；不得用名錄完整率代表醫學正確率。
- 經絡線需獨立覆核，尤其頭面折返、背部第二側線與指趾。
- 模型建議 < 3 MB；WebGL 手機目標 ≥ 30 FPS，必須實測；SVG 使用者操作後更新，不每幀重算。
- 所有修訂可匯出備份並驗證模型版本；工作草稿以 D1 線上儲存為準；未儲存內容可由同裝置暫存復原，JSON 可額外備份。

## 本輪完成狀態
- 已完成公開模型導入：13,380 頂點、26,756 三角面、GLB 482,632 bytes。
- 已完成 670 個表面錨點與 642 段體表幾何草稿連線，全部仍為 unreviewed。
- 已完成側別選擇、表面點選修訂、來源／註記、單步復原、JSON 下載與匯入。
- 已通過實際 GLTFLoader 解析、361 名錄／670 錨點完整性、錨點重建、錯誤模型與重心座標拒絕、匯入不得偽造專家核可、連線重算、SVG 真向量匯出與 DOM 參照檢查。
- 使用模型幾何另行繪出正、側、背面作離線檢視；未做瀏覽器互動、手機或跨瀏覽器實機驗收。
- 距正式教材仍需第 5–9 階段，特別是醫學定位與循行覆核。

## 本輪驗證邊界
本輪執行程式、模型結構、錨點重建、資料完整性與匯入校驗測試。不宣稱已完成中醫師覆核或手機實機驗收。

## 來源
- 官方體型設定：https://static.makehumancommunity.org/makehuman/docs/modeling_the_body.html
- 官方變形目標機制：https://static.makehumancommunity.org/mpfb/docs/assets/concept_targets.html
- 本次各模型的變形檔網址、權重與 SHA-256 記錄在 models/male/provenance.json 與 models/female/provenance.json。
- MakeHuman 官方核心資產授權：https://static.makehumancommunity.org/about/license.html
- 官方原始網格：https://github.com/makehumancommunity/makehuman/blob/master/makehuman/data/3dobjs/base.obj
- WHO 穴位定位標準書目：https://iris.who.int/items/f188654a-d8a7-4519-9979-8e2de713c060
- 原功能參考：https://cloudtcm.com/acupoint/3d