feat(worker): 保留原始 IFC 檔名追蹤

[monkey1sai]

變更摘要

本次讓 _worker 在 source artifact metadata、source index、API response、conversion result 與 callback payload 中保留 original_filename，並讓 _bim-control 在收到 callback 時用原始 IFC 檔名顯示 source artifact name。

修改原因

中文 IFC 檔名經過 _worker 的 on-disk filename sanitize 後，原始檔名會遺失，導致多筆相近 IFC 副本進入轉檔流程後無法從 metadata 或 _bim-control artifact name 回溯實際來源檔名。

主要變更

• _worker/app/store.py：source metadata、source index、source artifact response 與 conversion result payload 新增 original_filename。
• _worker/app/main.py：selected dev IFC conversion response 回傳 original_filename。
• _bim-control/app/main.py：conversion-result callback 帶 original_filename 時，source IFC artifact name 優先使用原檔名，未帶時維持「原始 IFC」fallback。
• _worker/tests/test_worker_api.py、_worker/tests/test_worker_store.py、_bim-control/tests/test_conversion_results_api.py：補上 original filename、legacy fallback、真實 IFC bytes 多筆 worker adapter，以及 opt-in Kit/HOOPS real USDC smoke 測試。
• _worker/README.md、docs/contracts/worker-api.md、OpenSpec change artifacts：補上欄位 contract、demo adapter 與 real Kit/HOOPS smoke 的差異說明。

驗證方式

• openspec validate add-worker-original-filename-tracking
• _worker: C:\Repos\active\iot\AI-BIM-governance\.venv\Scripts\python.exe -m pytest tests -q -p no:cacheprovider，結果：72 passed, 1 skipped, 1 warning
• _bim-control: C:\Repos\active\iot\AI-BIM-governance\.venv\Scripts\python.exe -m pytest tests -q -p no:cacheprovider，結果：28 passed, 1 warning
• Opt-in real USDC smoke: WORKER_RUN_REAL_USDC_SMOKE=1 ... test_real_ifc_files_convert_to_kit_openable_usdc_when_enabled，結果：1 passed，兩筆真實 IFC 透過 Kit/HOOPS 輸出 .usdc，stage inspect prim_count=10872
• 手動 real conversion smoke：輸出至 C:\tmp\codex-real-usdc-smoke，兩筆 .usdc 各 28,458,344 bytes
• git diff --cached --check
• GitNexus detect_changes：worktree staged scope 回報 changed_files=10、risk_level=critical

風險與影響

• API / callback payload 增加 additive 欄位 original_filename。
• _bim-control callback 接收端仍以 dict[str, Any] 處理，不會拒絕舊 payload。
• _worker 預設 conversion adapter 仍是 demo placeholder，不宣稱產出 Kit-ready USDC；真實 Kit/HOOPS smoke 需 WORKER_RUN_REAL_USDC_SMOKE=1 才執行。
• GitNexus detect_changes 回報 critical，原因是變更觸及 worker artifact/conversion 與 bim-control callback 流程；已用 targeted/full tests 與 real smoke 覆蓋主要風險。

向前相容性

本次新增的 original_filename 是 additive metadata 欄位，不會改變既有 disk object key、artifact id、conversion job id 或 callback endpoint 路徑。

既有 _worker metadata / _index/source_artifacts.json 若沒有 original_filename，讀取端會以 .get("original_filename") 容錯，不會拒絕舊 artifact。

_bim-control 的 conversion-result callback 仍以 dict[str, Any] 接收 payload；當 callback 沒帶 original_filename 時，source IFC artifact name 會 fallback 為既有的「原始 IFC」，因此舊 callback 仍可運作。

回滾方式

• Revert 本 PR commit。
• 已寫入 JSON metadata 的 original_filename 是額外欄位；舊程式可忽略，不需要資料 migration 或清理大型檔案。

後續建議

• 若要讓 _worker 直接產出 Kit-ready USDC，應另開 OpenSpec change，把目前 demo adapter 與 Kit/HOOPS converter adapter 正式分層。
• 可把 opt-in real converter smoke 納入具備 Kit/HOOPS 環境的 nightly 或手動 CI job。

[coderabbitai]

Warning

Rate limit exceeded

@monkey1sai has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 55 minutes and 41 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b3c87220-8e86-412f-a597-442fc6712c69

📥 Commits

Reviewing files that changed from the base of the PR and between 568f4cf and 3d58075.

📒 Files selected for processing (10)

• _bim-control/app/main.py
• _bim-control/tests/test_conversion_results_api.py
• _worker/README.md
• _worker/app/main.py
• _worker/app/store.py
• _worker/tests/test_worker_api.py
• _worker/tests/test_worker_store.py
• docs/contracts/worker-api.md
• openspec/changes/add-worker-original-filename-tracking/design.md
• openspec/changes/add-worker-original-filename-tracking/tasks.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/impl/add-worker-original-filename-tracking

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR adds end-to-end tracking of the client-provided IFC filename by introducing an additive original_filename field throughout the _worker artifact/conversion pipeline and using it in _bim-control to display the source IFC artifact name from conversion-result callbacks.

Changes:

• _worker: persist/return original_filename in source metadata, source index, dev-source conversion responses, and conversion results (for callbacks + GET result).
• _bim-control: when callback payload includes original_filename, prefer it for the source IFC artifact name, with a legacy fallback.
• Tests + docs: expand coverage for filename preservation and document the updated contract.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
openspec/changes/add-worker-original-filename-tracking/tasks.md	Marks the change tasks as completed.
openspec/changes/add-worker-original-filename-tracking/design.md	Design rationale/goals for preserving raw filenames as metadata.
docs/contracts/worker-api.md	Documents original_filename in responses/results and describes the preservation behavior.
_worker/app/store.py	Writes original_filename into metadata, source index, and conversion result payloads.
_worker/app/main.py	Adds original_filename to dev IFC source conversion response payload.
_worker/README.md	Notes new original_filename behavior and clarifies demo vs real converter smoke tests.
_worker/tests/test_worker_store.py	Adds unit test asserting original_filename is stored/returned.
_worker/tests/test_worker_api.py	Adds API tests for original_filename propagation + opt-in real conversion smoke.
_bim-control/app/main.py	Uses result.get('original_filename') to name the source IFC artifact when present.
_bim-control/tests/test_conversion_results_api.py	Adds tests for original_filename name preference and fallback behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.