手冊首頁 ／ Release Notes ／ Guidant AI v1.8.1 Release Note
Guidant AI v1.8.1 Release Note
| 項目 | 內容 |
|---|---|
| 版本 | 1.8.1（BUG 版號；主軸＝FR-047 上線前已知坑硬化 arc） |
| 發布日期 | 2026-07-09 |
| 上一版本 | 1.8.0（2026-07-04） |
| 涵蓋區間 | 2026-07-07 ~ 2026-07-09 |
| 規模 | FR-047 spec 手冊全站 §12「邊界情況與已知坑」508 條盤點、~59 條真修（8 桶 + review 三批），跨 BE + FE + 6 支 jedi-* 套件 |
| 適用部署 | dev / staging（8 支 migration 已套）；poc（8 支 migration 待套）；prod 待 |
| 部署性質 | 非破壞性 schema（清冗餘索引 / 加 UNIQUE / seed / 回填，皆先驗零重複 / 零資料變更，無 drop 資料）。含 8 支 DB migration + 6 支 jedi-* 換版。BE 需重啟生效（含 6 支 jedi- 換版）；FE 需同版部署（otp-resend / MFA / 改密碼契約變更）。* |
1. 概述
v1.8.1 是 v1.8.0 上線前的已知坑硬化 arc——FR-047 spec 手冊全站 67 頁 §12 彙整成 508 條邊界告知，核心認知：§12 是寫給工程師的邊界告知、不是 508 個待辦，混了「①可修 bug/缺口 / ②刻意設計只是提醒 / ③文件澄清」三種。arc 目標＝逐桶把①挑出來修、②③維持 no-action。八桶全數收口、~59 條真修，各頁 §12 已同步真修狀態。
版本定位 1.8.1（BUG 版號）：本 arc 屬純缺陷修復 / 硬化、對 user 無新增功能，依版號定義走 BUG 版號 bump。
2. 八桶真修
| 桶 | 真修重點 |
|---|---|
| ① 授權守門（SEC） | FR-048 統一授權守門（五軸 canonical
common/authz/）；未認證匯出端點恢復 JWT、簽章短期
token（otp-qrcode / framework 下載） |
| ② SCHEMA | 5 支 DDL：清 device / info_system 冗餘 tenant 索引 ×2、加
system_configs / org_units /
ui_routes UNIQUE ×3 |
| ③ UX | U-1~U-6：部門父層下拉吃全量、EC 報表 404 error state、資訊系統「停用」文案、批次刪除 not_found 計數、MFA 驗證後即時生效（B 案）、稽核員總覽 header 日期格式化 |
| ④ 錯誤碼（ECODE） | 7 條：補未定義碼 / None 檢查 / 裸字串改 enum / 型別碼不符（改密 400、角色撞名 409、租戶 in-use 409、system-menu / device / info-system 404） |
| ⑤ 狀態機（STATE） | SSP 寫入 phase guard 重建（凍結快照鎖寫、living 依當前輪 phase）；問卷狀態機轉換守門 + PUT task-survey route bug；公告時間窗驗證 |
| ⑥ 全量取代（REPLACE） | 快速配置不再洗關聯、刪除級聯守門（部門子樹 / 設備引用計數警示 / 子租戶）、批次匯入單一交易、刪資料夾孤兒守門 |
| ⑦ 死碼（DEAD） | 跨 BE+FE 死碼刪除、v1 module_frame copy 鏈整條退役、jedi-survey 死 enum 刪除 |
| ⑧ 其他（204） | ~175 no-action（設計 / 行為告知）；~25 可行動併入各桶 |
review 後三批（收尾複核 no-action 時 user 拍板轉「要做」）：
- ① OTP 發送 server-side 節流：jedi-mfa redis
節流（
otp_cooldown:{user_id}，防 email bombing，登入首發 + resend 共用，60s env）+ FE localStorage 吃 429。 - ② 六項設計調整：權限本人即時生效 / 設備停用 UI / 匯入連動下拉 / 判定後刷新 / 摘要報表放寬進行中 / device_type 標準下拉。
- ③ 專案狀態機 B 案：
project.status維護半套 → 建立即in_progress（「未開始 pending」語意取消）+ 補同步點 + 回填 migration；篩選 / 規劃 gate 改輪次驅動。
逐條定調 / 銷帳唯一真相：
docs/analysis/2026-07-07-known-pits-remediation-tracker.md。
3. Breaking Changes / 契約變更（FE + BE 需同版部署）
本 arc 有三項 FE↔︎BE 契約變更，需同版上線：
/otp-resend契約收斂：route 改讀type（原誤讀mfa_type）、serializertype加OneOf(["email"])（收到 totp 等值 400 fail loudly）。- MFA 開關改「即時生效」：切換驗證通過即走
PUT /user-mfa-type（只送mfa_type單欄）落 DB，不再依附基本資料儲存（B 案）；舊 FE 直送totp對新 BE 會 400。 - 改密「新舊密碼相同」錯誤碼
AUTH_401009→AUTH_400003、例外型別 429→400（FE i18n mapping 鍵同步改）。
4. DB Migration（8 支，僅索引 / 約束 / seed / 回填，無 drop 資料）
| 順序 | 檔案 | 說明 |
|---|---|---|
| 1 | scripts/sql/2026-07-08-drop-dup-index-devices-tenant.sql |
DROP 冗餘 idx_devices_tenant（留
idx_devices_tenant_id） |
| 2 | scripts/sql/2026-07-08-drop-dup-index-information-systems-tenant.sql |
DROP 冗餘 idx_information_systems_tenant_id（留 ORM
canonical） |
| 3 | scripts/sql/2026-07-08-add-unique-system-configs-tenant-group-key.sql |
ADD
uq_system_configs_tenant_group_key UNIQUE(tenant_id,"group",key) |
| 4 | scripts/sql/2026-07-08-add-unique-org-units-tenant-name.sql |
ADD
uq_org_units_tenant_name UNIQUE(tenant_id,name) |
| 5 | scripts/sql/2026-07-08-add-unique-ui-routes-name.sql |
ADD uq_ui_routes_name UNIQUE(name) |
| 6 | scripts/sql/2026-07-09-device-type-menu.sql |
seed system_menus group
DEVICE_TYPE（六項#6 標準下拉） |
| 7 | scripts/sql/2026-07-09-retire-notification-test-capability.sql |
退役 notification.test capability（角色矩陣 TEST
空欄消失） |
| 8 | scripts/sql/2026-07-09-backfill-project-status-b-model.sql |
回填 project.status（pending→依輪次 completed /
in_progress；狀態機 B 案） |
- dev / stg 已套（2026-07-08~09）；poc 待套；prod 待部署時程。
5.
相依套件版本（6 支 jedi-* 換版，已 poetry publish Nexus +
還原 pin）
| 套件 | 版本 | 說明 |
|---|---|---|
| jedi-auth | 0.1.26 | ECODE 改密 400 / 角色撞名 409 / 租戶 in-use 409、R-2a/c
刪除級聯守門、R-3 批次匯入 send_email 參數、U-5
update_user_mfa_type 端點 |
| jedi-mfa | 0.0.12 | OTP 發送 server-side 節流（redis
cooldown，MFA_429001） |
| jedi-survey | 0.0.25 | 死 enum 刪除、R-4
刪資料夾孤兒守門（SURVEY_409008/409009） |
| jedi-system-menu | 0.0.9 | ECODE#3 撞 key catch
IntegrityError→ConflictError（SYSTEM_MENU_409001） |
| jedi-information-system | 0.0.3 | ECODE#5/#6 新建 error_code enum、PUT/DELETE 結構化 404 |
| jedi-device | 0.0.12 | device-manage#2 PUT/DELETE 結構化
404（DEVICE_404001） |
其餘 jedi-* 維持 v1.8.0 既有 pin（含 jedi-oscal-v2 2.2.0）。
6. 部署順序
- DB migration：依 §4 表格順序 1→8 各跑（dev / stg 已套，poc + prod 待）。
- BE：
poetry update（拉 6 支 arc 換版）後重啟（無 hot reload）。 - FE：build + 部署（版號對齊 1.8.1）。必須與 BE 同版——otp-resend / MFA 即時生效 / 改密錯誤碼屬 FE↔︎BE 契約變更（見 §3）。
- 驗證：MFA 切換即時生效（TOTP 驗證後才啟用）/ 六項設計調整（權限本人即時、設備停用、匯入連動下拉、判定後刷新、摘要報表放寬進行中、device_type 下拉）/ 專案狀態篩選（建立即 in_progress）。
7. 已知 follow-up（arc 外，待 user 排）
- poc migration 未套：8 支 arc migration 僅 dev / stg 已套，poc + prod 待部署時程。
- SSP 完成度迷你件（dashboard#1）未接（需 wire
ssp_uid+ N 個 FE 呼叫）。 - DB 死表盤點（
system_logs_old等，走 DROP 前安全四查）、topt_secret死欄 DROP（待 STG/POC 確認）。 - 硬刪除 / 回收站（級聯面大、稽核留存衝突，另開 FR）。
- 權限即時生效跨 session（admin 改他人、對方另一 session 即時＝需 socket，依「別過度」未做）。
8. 相關文件索引
- 唯一進度真相：
docs/analysis/2026-07-07-known-pits-remediation-tracker.md（8 桶 + review 三批逐條銷帳） - arc 完結彙整 + 部署
handover：
docs/features/FR-047-2607-feature-spec-handbook/handoff/2026-07-09-UX-bucket-and-arc-completion-SUMMARY.md - 統一授權守門設計：
docs/analysis/2026-07-07-unified-auth-guard-design.md（FR-048） - 專案狀態機 B
案：
docs/features/FR-038-2606-oscal-redesign/handoff/2026-07-09-project-status-b-model-SUMMARY.md - 各頁 §12
spec：
docs/specs/v1.8.0/（真修狀態已同步，本 arc 收尾 commit）