公告管理（Bulletin Management）

功能群：協作（collab）｜本群無獨立 _overview，共用概念見各頁；SPEC 索引見 README

事實基準：2026-07-05 從 FE / BE code 掃出（jedi-bulletin 套件為底、主專案 extend org_unit 關聯與 created/updated user 顯示名）；API schema 逐條對照 marshmallow serializer 與 service 組裝碼

1. 功能描述

公告管理頁是系統管理者維護「公告」的後台清單 + 表單頁面：可新增、編輯、刪除公告，並指定發布類別、目標部門、生效區間與啟用狀態。是 公告（檢視） 的管理端鏡像——本頁看到「全部/自己建立的」公告，檢視端只看到 auth=true（已發布且未過期）的公告。

主要使用者：具公告管理選單可見性的系統管理者／權限管理者（BE 未做角色白名單，見 §3）。

角色速覽（本頁無正式角色定義，見 §3 權限說明）：

1.1 功能總覽（本頁全部功能）

UC（§2）只展開 1（清單載入/篩選）/ 2（新增與編輯共用表單流程）/ 3（刪除）三條核心操作路徑；其餘欄位顯示邏輯已在總覽表描述完整。

2. Use Case

角色速覽（本頁無正式角色定義，見 §3 權限說明）：

流程圖視覺慣例：菱形 = 判斷、橘底 = 例外/擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。

UC-BM-01 公告清單載入與篩選

UC-BM-02 新增／編輯公告

UC-BM-03 刪除公告

3. 權限矩陣

⚠️ 已知缺口（維護時注意）：公告新增/編輯/刪除三個寫入操作，BE 完全沒有角色或 capability 二次驗證，僅要求已登入。目前僅靠 FE 選單可見性擋一般使用者進入本頁；若之後要收緊（例如限定系統管理者角色才能寫入），需在 BulletinRoute 補角色檢查——現況不要當作範本複製到其他寫入 API。詳見 §12 坑 4。

4. 狀態機與前置條件

本頁公告本身沒有狀態機（只有 enable 布林開關 + 時間區間），與稽核輪次等狀態機無關。相關 gate：

5. UI 設計

📸 實際畫面截圖待補（一律亮色模式拍攝）：以 playwright 對 STG 擷取，預計補以下三張到 assets/img/： ① 公告管理清單整頁（表格 + 篩選列 + 類別/部門欄）bulletin-mgmt-list.png ② 新增/編輯表單整頁（標題、類別、部門、起訖時間、發布開關、CKEditor 內容）bulletin-mgmt-form.png ③ 刪除二次確認 dialog 特寫 bulletin-mgmt-delete-confirm.png

版面骨架（清單頁：Header + DataTable；表單頁：單欄表單卡片；刪除為二次確認 dialog）：

狀態呈現：清單載入中 DataTable 內建 loading 遮罩（submit state）；表單頁載入既有資料 / 送出儲存時顯示全螢幕半透明遮罩 + ProgressSpinner（非局部）；無 socket，儲存後靠 router.push 導回清單頁觸發重新載入（非本地增量更新）。

6. API 規格

Envelope：成功 {"status": true, "data": …}、失敗 {"status": false, "error_code": "…", "msg": "…"}（common/util/response_util.py:return_response）。

6.1 總清單（本頁呼叫的全部 endpoint）

DELETE /bulletin（無 {uid}，body 帶 uid）與 PUT /bulletin（同）路由亦存在於 routes.json，但本頁 FE 一律走 {uid} path variant；無 {uid} 的變體本頁未使用，故不展開。

6.2 公告清單類

[POST] /bulletins

Request（繼承 RequestMetaSchema 分頁/排序 + filters 巢狀物件）：

出處：api/bulletin/serializers/bulletin_query.py:5-23（BulletinQueryRequest / BulletinPageQueryRequest）

Response data（陣列，每項）：

出處：api/bulletin/serializers/bulletin.py:15-32（BulletinResponse / BulletinPageQueryResponse）；分頁彙整 app/bulletin/service/bulletin_service.py:33-55

6.3 公告詳情類

[GET] /bulletin/{uid}

無 body。Response data：同 §6.2 單筆形狀（BulletinResponse）。出處：api/bulletin/routes/bulletin_route.py:45-48

6.4 公告寫入類

[POST] /bulletin

Request：

出處：api/bulletin/serializers/bulletin.py:5-12（BulletinRequest）；建立邏輯 app/bulletin/service/bulletin_service.py:78-100（add_bulletin：先建 bulletins 列，再逐一查 org_unit_uid 建 bulletin_org_units 關聯，查無部門 → NotFound(BULLETIN_404001)）

Response：同 §6.2 單筆形狀（含新建立的 uid）。

[PUT] /bulletin/{uid}

Request：同 POST 的 BulletinRequest（非 partial patch——FE 送出整包 currData）。

更新邏輯（app/bulletin/service/bulletin_service.py:102-125，update_bulletin）：

1. 更新 bulletins 主表欄位（title / content / category / enable / release_time / expire_time / updated_user）
2. 先整批刪除該公告全部 bulletin_org_units 關聯（bulletin_org_unit_domain_service.delete_by_bulletin_id）
3. 再依 request 的 org_units[] 逐一重建關聯——故 org_units 省略或空陣列會清空全部部門關聯

Response：同 GET 單筆形狀。

[DELETE] /bulletin/{uid}

無 body。Response data：布林值（BooleanResponse）。出處：api/bulletin/routes/bulletin_route.py:74-79；刪除邏輯 domain/bulletin/service/bulletin_domain_service.py:47-48 → IBaseRepo.delete_by_uid（session.delete()，見 §12 坑 3）

7. 前端檔案地圖（compliance-manager-fe/）

8. 後端檔案地圖（本頁核心鏈路）

DDD 提醒：本模組是主專案 extend 外部套件（jedi-bulletin）的標準模式——domain/bulletin/entities/bulletin_entity.py 繼承套件 BaseBulletinEntity 再加 org_units/created_user_name 等主專案欄位；infra/bulletin/models/bulletin.py::ExtendedBulletin 繼承套件 Bulletin model 再加 org_units relationship 與 created_user_name/updated_user_name hybrid_property（審計欄位回傳規範的標準做法：app service 不做、model 層直接算）。新增本模組功能時比照此 extend 模式，不要直接改 jedi-bulletin 套件本身除非確認是套件 domain 該有的行為。

9. DB

9.1 資料表總清單（本頁讀寫的全部表）

9.2 ER 圖（本頁讀寫範圍）

9.3 核心表欄位（取自 DEV DB dump，含 DB comment）

public.bulletins — 公告主表

DB comment：「公告表：儲存系統公告資訊，包含標題、內容、類別及發布時效」。

索引 idx_bulletins_live（tenant_id, org_unit_id, release_time WHERE enable=1 AND is_delete=0）顯示原始套件設計是預期 is_delete 會被使用於「生效中公告」查詢——與 §12 坑 3 現況不一致，屬既有債。

public.bulletin_org_units — 公告目標部門關聯（純關聯表）

無自身序列 / 額外欄位；PK = (bulletin_id, org_unit_id)。

10. 頁面邏輯與資料對應

載入時序（清單頁）：

關鍵欄位對應（API ↔︎ 畫面，清單頁）：

關鍵欄位對應（表單頁）：

儲存流程：表單一次性整包送出（無分段儲存）；uid 存在則 PUT 走 update()，否則 POST 走 create()；儲存成功後 toast 提示並 router.push('/bulletin/bulletin-manage') 導回清單（觸發清單頁 onMounted 重新載入，非共用 store 或事件通知）。

錯誤對應：BE error envelope → 走全域 axios interceptor 的 axios-error event bus → toast 顯示；已知錯誤碼：BULLETIN_404001（新增/更新時目標部門 UID 查無資料）。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. release_time/expire_time FE/BE 必填認定不一致：FE vuelidate 兩者皆標 required，但 BE BulletinRequest schema 未標 required=True（僅 fields.DateTime，可省略）；DB 層 release_time NOT NULL、expire_time 允許 NULL。繞過 FE 直接打 API 省略 release_time 會在 DB insert 階段才失敗（500，非乾淨的 400），不是本頁 UI 會遇到的路徑，但要注意 API 本身沒有做完整前置驗證
2. 清單查詢範圍規則寫在 comment 裡、行為容易誤解：user.org_unit_id 有值時只回「自己建立」的公告，org_unit_id 為 null 才回全部——這與一般直覺「有部門的人看得到更多」相反，是刻意設計成「無部門掛職者視為系統管理者，可看全部」（bulletin_service.py:42 原始碼註解）。改動這條過濾邏輯前務必理解此意圖
3. 刪除是硬刪除，is_delete 欄位形同虛設：domain/bulletin/service/bulletin_domain_service.py:47 呼叫的是 BaseRepositoryImpl.delete_by_uid（session.delete() 實體刪除），而非利用 is_delete 欄位做軟刪除。DB 索引 idx_bulletins_live 的設計意圖明顯是預期軟刪除（WHERE enable=1 AND is_delete=0），現況等於該索引條件恆為「未刪除」子集但 is_delete 永遠是 0。刪除公告的 API 呼叫方沒有恢復機制，屬已知債，新 code 不要假設 bulletins 有軟刪資料可查
4. 寫入操作 BE 無角色守門：新增/編輯/刪除三支 API 僅 @jwt_required()，任何登入者皆可操作，即便不是系統管理者。屬已知債（與 我的稽核 §12 坑 8 類似模式，但性質不同——本頁是寫入操作缺角色檢查，非純讀），新增類似 API 不要比照
5. BulletinService.js 是死碼：src/service/BulletinService.js 讀寫 /demo/data/bulletin.json 本地假資料，本頁兩個 view 實際皆透過 BaseService + API.BULLETINS/API.BULLETIN 呼叫真實後端，此檔案未被任何 view import。清理前端死碼時可考慮移除，但需先確認無其他隱藏引用
6. org_units 欄位讀寫形狀不同：GET 回傳 org_units: [{uid, name}, …]（物件陣列，dump_only nested schema），但 POST/PUT 送出時需為 org_units: ["uid1", "uid2", …]（純 uid 字串陣列）。BulletinForm.vue:75 的 getBulletin() 手動做了這個轉換（res.org_units.map(obj => obj.uid)）——同名欄位跨讀寫語意不同，日後串接或除錯要留意，不能直接假設兩邊形狀一致
7. PUT 是 full payload，非 partial patch：update_bulletin 對主表欄位逐一覆寫（title/content/category/enable/release_time/expire_time），且 org_units 關聯每次都整批刪除重建（delete_by_bulletin_id 先清空，再依送出的陣列重建）。若呼叫方省略 org_units 或送空陣列，會清空該公告全部目標部門，與 專案任務編輯頁 §12 坑 6 的 job full-replace 語意同一類陷阱
8. 無 phase / 時間窗前置檢查：enable/release_time/expire_time 三者任意組合都能被管理端寫入 API 接受（例如 expire_time 早於 release_time、或 enable=1 但兩個時間都是過去），BE 沒有做邏輯自洽驗證，僅檢視端查詢時用 auth=true 的時間比對條件把「當下未生效」的公告過濾掉

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE 在 compliance-manager-fe/ 起 Vite dev server。BE 改 service code 後必須重啟（無 hot reload）
• 測試帳號：dev 環境一般登入帳號即可操作（密碼見 .env / 部署文件；BE 無角色守門，見 §3）
• 導航路徑：登入 → 側邊選單「公告管理」（bulletin-manage）→ 新增／編輯走「編輯公告」（bulletin-form）
• 前置資料：需至少一個部門（org_units）存在才能通過表單必填驗證；BULLETIN_CATEGORY system-menu 需有選項資料才能選類別
• E2E：compliance-manager-test/ repo（Cucumber + Playwright）；本頁相關 feature 檔以 公告 / bulletin 搜尋
• 相關文件：docs/api/bulletin/Bulletin-SA-SD.docx（既有 API 規格文件，可當背景參考，欄位以本頁 §6 為準）；歷史修復 docs/changelog/2026-06-08-fix-bulletin-time-filter-direction.md（auth=true 時間比對方向 bug，已在 jedi-bulletin 套件層修正，見 §6.2 filter 說明）；檢視端見 公告檢視