CallIT 資訊需求單系統重生計畫 - 方案設計書

專案背景與目標

為了提升「CallIT 資訊需求單系統」的可維護性、安全性與未來的擴充性，本系統將從原有的 ASP.NET Web Forms 框架全面遷移至現代化的 前後端分離架構。 依據現有功能（涵蓋四種需求單狀態、IT與User權限分離、附件上傳、排程提醒等）進行完整功能復刻與重新設計。

---

一、 技術選型 (Technology Stack)

領域	選用技術 / 版本	說明
後端框架	Python 3.12 + Django 5.1	提供穩定的 API 服務與 ORM
前端框架	React + TypeScript	負責現代化 UI 渲染及單頁應用 (SPA) 體驗
身分認證	django-auth-ldap 5.2.0, python-ldap 3.4.5	整合現有 Windows AD / LDAP 進行無縫認證
資料庫	MSSQL (SQL Server)	沿用現有資料庫系統整合 (mssql-django 驅動)
部署伺服器	Waitress (WSGI 伺服器)	於 Windows 10 環境提供高效的原生 Python 網頁伺服器部署

---

二、 系統架構與目錄層級約定

為符合工程規範，後端 Python (Django) 專案將嚴格遵守五層式架構設計以降低耦合度：

• api/：負責請求接收、路由映射 (Routing) 及響應封裝 (Response formatting)。
• schema/：利用 Pydantic 或 Django Ninja 定義 Schema，統一負責請求參數校驗與響應資料結構化 (防止 XSS 及異常注入)。
• service/：核心業務邏輯處理，包含權限校驗、狀態流轉 (如「申請中」轉為「處理中」) 等皆在此處完成。
• repository/：負責封裝所有涉及資料庫的增刪改查 (CRUD)，隔離 ORM 對業務邏輯的影響。
• model/：Django ORM 實體模型定義層。

---

三、 核心功能遷移對映表

1. 身分認證與權限管理

• 原機制：年代帳號直接登入，無須註冊。分為 User, 行政, 主官管, IT 四種角色。
• 新設計：
  • 使用 django-auth-ldap 介接 AD。登入時前端發送帳號密碼，後端透過 LDAP 校驗成功後發放 HttpOnly Cookie (JWT 或是 Session Token) 以防範前端提取。
  • 角色判定：依據 AD Group 或資料庫白名單，於 service 層決定當前使用者的權限，並返回與其身分相符的可用清單。

2. 需求單生命週期管理與動態表單

• 狀態枚舉：APPLYING (申請中)、PROCESSING (處理中)、COMPLETED (已完成)、REJECTED (退回)。（狀態只能單向？還是要有回退機置？目的？）
  • 當狀態為申請中、處理中、已完成、退回時皆會寄送郵件，分別通知申請人及IT。
• 需求類別與動態驗證：
  • 申請時須明確區分需求類別，例如：「一般事務」、「權限申請」、「資產轉移」、「設備修繕」等。（不需要帳號申請？臨時先開帳號延續口頭告知？）
  • 若選擇**「資產轉移」或「設備修繕」**，前端將動態展開並設定「資產編號」為強制必填欄位，後端 schema 同步確保此欄位不得為空。
  • 勾選「申請/修改大洋系統權限」時，前端自動帶入預設文字範本。
• 規則實作 (service 層)：
  • 任何人皆可新增 APPLYING 狀態的需求單。
  • 只有行政及IT 二種角色可以執行代申請模式。
  • 當 IT 編輯並指派「處理人員」時，自動切換至 PROCESSING。若處理人員為空並點選「完成」時，擷取當前登錄 IT 人員，強制轉 COMPLETED。
  • 不需要有簽核與會簽的功能？

3. 進度查詢與歷史日誌 (Audit Trail)

• 進度查詢頁面：獨立的「進度查詢與追蹤」頁面，讓使用者可透過單號、時間區間或申請人搜尋目前需求單的處理階段及歷史進展。
• 進度查詢頁面權限： User 只能查詢到自己的單位，行政、 主官管可以查詢到部們， IT 可查詢所有包含刪除單號。
• 歷史日誌 (歷程紀錄)：
  • 只有 IT 權限可以使用此頁面
  • 針對每一筆需求單的狀態流轉（如被IT接單、退回、分派處理人或結案、單號刪除）及重要備註，後端將自動寫入「歷史異動日誌」(包含異動時間、操作者、異動動作及原因)。
  • 此日誌將在單據詳細/進度查詢頁面以清單或「時間軸 (Timeline)」形式呈現，以便雙方事後追溯。

4. 日常排程管理 (背景任務)

• 原機制：PyService 負責 00:00 變更起始流水號及 05:00 發送未結案通知。
• 新設計：
  • 流水號產生優化：利用後端 ORM/Repository 生成單號時，動態以當天時間組合生成 NMMDDXXX (N=民國年尾數)，取代傳統依賴固定序列的排程，提高系統可用性且不會因排程故障而中斷。
  • 郵件提醒：可使用 Windows 工作排程器 (Task Scheduler) 定期執行 Django Command (python manage.py check_pending_requests)，發送未結案通知。

5. 解決原有系統痛點

• 「內文截斷、顯示不全」痛點：將透過前端 React Component 封裝完整的 Tooltip 或 Collapse (展開/收合) 來實現長資料分頁與可讀性，不再因傳統表格而截斷視覺。

---

四、 安全性設計 (Security Protocol)

1. 前端安全：使用者於需求單內填寫的操作內容，前端必定經過 React 預設編碼。所有權杖 (Token) 改置於 HttpOnly Cookie，阻止 XSS。
2. 後端安全：所有請求於 schema 層透過驗證檢驗字串長度與類型；SECRET_KEY、MSSQL 密碼、LDAP 金鑰皆抽離為環境變數 (.env) 讀取，禁止寫死於程式碼。
3. 權限越權防堵：需求單編輯、刪除 (IT 專用介面) 必須在 service 或 api 層重新驗證當前 request.user 是否具備 IT 角色群組，避免直接竄改 API。

---

五、 部署架構 (Windows 10)

• 前端靜態目錄：透過 npm run build 打包後，由 Nginx (Windows版) 或 Waitress/Django whitenoise 接管映射。
• 後端服務：啟動腳本執行 Waitress 為 WSGI 服務。範例啟動語法： waitress-serve --port=8000 --threads=4 myproject.wsgi:application
• 資料庫：連線字串透過 mssql-django 與 MSSQL 相互通訊。

六、 Antigravity 歷史日誌整合 (Historical Adjustments)

為確保新系統具備過去已優化或修復的特性，將融入近期歷史紀錄中的關鍵調校：

1. 多重資料庫連線 (Additional MSSQL)：新版 Django 將配置 Database Routing 以支援多重資料庫操作，無縫銜接原有的跨連線需求。
2. AD / LDAP 讀取異常防範：新系統全面改採 python-ldap 直接連接通訊協定，提升 AD 連線穩定性，徹底避免依賴底層 COM 元件造成的系統層級異常。
3. Waitress 伺服器資安隱匿：為強化正式環境資安，部署 Waitress 時將配置 ident 參數抑制或自訂 Server: waitress HTTP 標頭，防範技術堆疊資訊外流。
4. 前端相容性與美化修復：包含過長文字截斷 (如 line-clamp 跨瀏覽器修正) 及登入頁報錯等諸多 UI 小調整，在新的 React 組件化架構中將使用更嚴謹的 CSS 模組 (CSS Modules/Tailwind) 規範來一次性解決。

七、新增功能頁面

• 新進同仁在發送郵件同時寫入到MSSQL，在 CallIT 上會顯示某日新進同仁帳號創建的進度（支援員編、姓名搜尋）。
• 整合 ERA 或 1-TV 密碼修改，忘記密碼者，若信箱可以存取，則寄送臨時密碼。
• 整合所有公司內部捷徑為書籤