KYB 企業自動化審核與 OCR 文件辨識系統 Mockup PRD（給後端 API 規格產生器使用）

此文件為 wport 平台「企業身分驗證（KYB）自動化與文件 OCR 審核」模組的完整需求規格書。 backend-api-spec-generator 會讀取這份文件與 Storybook mockups 來產生後端 API 規格。

1. 文件資訊

• 文件類型：Mockup 需求規格書（前後端共用視圖）
• 適用對象：前端開發、後端開發、AI/資料工程師、UI/UX 設計師、產品、QA、客服營運
• 最後更新：2026/07/22
• 版本：1.0.0
• PRD 識別碼：pm_49
• 對應 Storybook：storybook/src/stories/mockups/company/KybOcrAutoVerification.stories.ts（企業端；待產）
• Admin-Web mockup：W101-Admin-Web 分支 feature/pm-49-kyb-ocr-review → /members/kyb-reviews
• Storybook（local-prd）：file:///Users/Eric/Documents/Github/prd/doc/feature/pm_49/kyb-ocr-auto-verification-mockup.md
• Storybook（online）：https://storybook.wport.me/?path=/docs/mockups-company-kybocrautoverification—docs（待 mockup 產出後替換實際 Story ID）
• 建立日期：2026/07/22
• 關聯 PRD：pm_38（公司註冊 2.0）、business-rules.md BR-005

1.1 修訂紀錄

2. 開發進度與設計來源

開發進度

• 前端 PR #：[TBD / 待開發後補上]
• 後端 PR #：[TBD / 待開發後補上]
• AI/OCR 服務 PR #：[TBD / 待開發後補上]

設計來源

• Figma 連結：[待補上]
• 既有 FE 參照：
  • 公司驗證文件上傳區（production，incremental 擴充）
  • pm_38 公司註冊 2.0 精靈 Step 後段之 BR-005 驗證入口
• SaaS Benchmark：
  • Stripe Connect KYB（文件上傳 + 自動/人工分層）
  • 104 企業認證（全人工審核 baseline）
  • LinkedIn Company Page Verification（文件 + 官方資料比對）

3. 模擬頁面摘要（Mockup Summary）

3.1 功能概述

• 功能名稱：KYB 企業自動化審核與 OCR 文件辨識系統
• 主要使用者角色：
  • Employer（Owner / Admin）：上傳公司變更登記表、查看審核結果
  • KYB 客服（Site Admin）：人工覆核模糊案件、核准/退件
  • 平台（系統）：自動 OCR + 政府 API 比對流水線
• 核心目標：
  • 取代現行「全人工核對變更登記表 vs 經濟部登記資訊」流程，實現 ≥ 80% 台灣案件秒級自動通過
  • 降低客服人力成本，縮短 BR-005 公司驗證 SLA（目標：自動通過即時、人工案件 1 個工作天內）
  • 異常時精準引導企業修正或轉交人工，保留稽核軌跡與 C 端信任（BR-005 gate 不變）
• 戰略對齊（WPORT）：
  • 強化 合規自動化 差異化能力，服務企業付費轉化與 7 人團隊槓桿
  • 僅 台灣（tw） v1 啟用；VN/TH 維持 pm_38 D4「文件 + iCan 人工審核」

3.2 範圍界定

v1（必含，本次交付）

用戶端（Employer）

• 公司驗證流程中上傳/拍攝「公司設立登記表／變更登記表」（BR-005 可接受文件類型之子集）
• 前端照片品質預檢（亮度、清晰度、格式、大小）
• 相機拍攝 A4 比例虛線框 overlay
• 即時審核結果回饋：自動通過 / 即時退件（含原因）/ 轉人工（「專人審核中」）
• 審核狀態查詢與重新上傳（限退件後）

後端流水線

• 統編格式驗證（台灣 checksum）+ 上傳統編 vs 註冊統編一致性
• 輕量化 OCR 文字提取（目標欄位 5 項）
• 經濟部商業司 API 查詢與登記狀態判斷
• 資料正規化 + 模糊比對（地址 Levenshtein、日期轉換、代表人精確比對）
• 自動決策：通過 / 駁回 / 轉人工
• 經濟部 API 失敗時 Retry + 非同步降級人工

後台（Site Admin / KYB 客服）

• 待審清單（含轉人工原因標籤）
• 左右對照檢視：原圖（OCR 疑慮紅框）vs 政府 API vs OCR 提取
• 一鍵核准 / 退件 + Email 通知

v2（Phase 2，本次不交付）

• 多文件類型：商業登記抄本、統一編號編配通知書
• OCR 失敗時 LLM 多模態二次辨識 Fallback
• VN/TH 文件 OCR（待官方 API 可行性確認）
• 審核 SLA 儀表板、客服工作量分派

Out of scope

• 取代 BR-005 其他五類文件之全自動審核（v1 僅涵蓋設立/變更登記表）
• 統編 API 帶入（pm_38 D1）— 本功能專注公司驗證文件審核，與註冊時 GCIS lookup 獨立
• 求職者端 C 端徽章變更（維持 pm_38 D20：信任訊號以 BR-005 公司認證為準）
• 直接修改 business-rules.md（新規則先記於 §4，由人決定是否回寫）

3.3 成功條件

4. 商業規則對齊（Business Rules Alignment）

4.1 本功能使用到的既有業務規則

4.2 本功能新增／補充規則（待回寫 business-rules）

4.3 與 pm_38 的關係

無硬衝突：統編 API 帶入 ≠ 公司驗證通過；本功能強化驗證環節，不改變 lifecycle 分層（draft → profile_complete → BR-005）。

5. 資料實體與欄位（Data Entities & Fields）

本節描述業務上需要追蹤的資訊與用途，不預先鎖定 JSON 欄位名、hash 演算法或 DB schema（RD 於 OpenAPI Spec 決策）。

5.1 實體列表

5.2 各實體須追蹤的資訊

KybVerificationCase

• 與（公司、發起成員）的綁定關係
• 案件狀態與狀態轉換時間戳（見 §5.3）
• 決策結果：auto_approved | auto_rejected | manual_approved | manual_rejected | pending_manual | processing | failed
• 轉人工原因碼列表（可多選）
• 對外顯示文案代碼（error copy mapping）
• 本月送審次數累計（配合 BR-005-KYB-04）
• Idempotency 金鑰（防重複提交）
• 建立／更新／完成時間

KybUploadedDocument

• 原始檔案儲存位置（加密靜態儲存）
• 檔案類型（image/jpeg、image/png、application/pdf）
• 檔案大小、頁數（PDF 取第一頁為主）
• 前端品質預檢結果（通過/失敗及原因）
• 上傳來源（相機 / 相簿 / 檔案）

KybOcrExtraction

• 提取欄位：統一編號、公司名稱、代表人姓名、公司所在地、最近一次核准變更日期
• 各欄位信心分數（confidence）
• 辨識失敗區域座標（供後台紅框）
• OCR 引擎版本與處理耗時

KybRegistrySnapshot

• API 回應原始快照（含查詢時間）
• 公司登記狀態（核准設立 / 停業 / 解散 / 廢止 / 撤銷）
• 比對用欄位：統編、名稱、代表人、地址、核准日期（AncDate）
• API 來源標記與快取 TTL

KybFieldComparison

• 欄位名稱、OCR 值、Registry 值、正規化後值
• 比對方式（精確 / 模糊相似度）
• 相似度分數（地址適用）
• 單欄決策：match | mismatch | uncertain

KybManualReviewAction

• 操作者（客服帳號）
• 操作類型：approve | reject
• 退件原因（自由文字 + 原因碼）
• 操作時間
• 是否觸發 Email 通知

5.3 案件狀態機

[用戶上傳] → processing
    ├── 前端預檢失敗 → （不建立案件，僅 UI 提示）
    ├── 後端格式/統編攔截 → auto_rejected（即時）
    ├── OCR + API + 比對全過 → auto_approved（即時）
    ├── 比對確定失敗 → auto_rejected（即時）
    ├── 模糊地帶 → pending_manual
    │       ├── 客服核准 → manual_approved
    │       └── 客服退件 → manual_rejected
    └── 經濟部 API 逾時/不可用 → pending_manual（原因：registry_api_unavailable）

終態：auto_approved | manual_approved | auto_rejected | manual_rejected | failed（系統異常且無法降級）

BR-005 對應：auto_approved 與 manual_approved → 公司驗證狀態「已通過」；其餘終態 → 「未通過」或維持「待審核」。

6. 畫面區塊與資料需求（UI Sections & Data Needs）

6.1 區塊列表

6.2 各區塊資料需求

SEC-U2 文件上傳區

• 顯示條件：country_code === 'tw' 且公司驗證狀態非「已通過」；角色為 Owner/Admin
• 接受格式：JPG、PNG、PDF
• 大小上限：10 MB
• 數量上限：每次送審 1 份文件；案件進行中禁用上傳
• 文案：「請上傳最新版公司設立登記表或變更登記表（需含統一編號、公司名稱、負責人、地址及核准日期）」

SEC-U3 品質預檢回饋

• 觸發時機：檔案選定後、正式上傳前（< 0.5 秒）
• 檢測項：亮度、清晰度、格式、大小
• 失敗文案（固定，見 §9 Error Handling）

SEC-A1 待審清單

• 資料需求：分頁、篩選（狀態、轉人工原因、送審日期）、排序（最舊優先）
• 標籤範例：[地址比對相似度 80%]、[日期無法明確識別]、[經濟部 API 暫不可用]

SEC-A2 對照檢視

• 左側：原圖 + OCR 疑慮區域紅框 overlay
• 右側：三欄對照表（欄位名 | OCR 值 | 經濟部 API 值 | 比對結果）

7. 使用者動作與後端需求（User Actions & Backend Needs）

建立/送審上限（mandatory）

8. API Hints（提示用，非最終 API 設計）

8.1 資料讀取需求（Read）

• HINT-GET-1：取得公司當前 KYB / BR-005 驗證狀態

  • 對應區塊：SEC-U1
  • 條件：已登入、公司成員
  • 回傳：狀態、最近案件摘要、剩餘本月送審次數、是否可重新上傳

• HINT-GET-2：輪詢案件處理進度

  • 對應區塊：SEC-U5、SEC-U6
  • 輸入：案件 ID
  • 回傳：狀態、決策、對外文案代碼、轉人工原因（若適用）

• HINT-GET-3：客服待審清單

  • 對應區塊：SEC-A1
  • 條件：Site Admin + KYB 權限
  • 篩選：status、manual_reason、date_range

• HINT-GET-4：客服案件詳情（含 signed URL）

  • 對應區塊：SEC-A2
  • 圖片 URL TTL：15 分鐘（過期須重新請求）

8.2 資料寫入需求（Write）

• HINT-MUTATION-1：提交驗證文件

  • 輸入：檔案（multipart）、idempotency_key、document_type=establishment_or_amendment_form
  • 行為：建立案件 → 執行 §3 流水線 → 回傳決策或 pending_manual
  • Idempotency：相同 key 24 小時內重複請求回傳相同結果，不重跑 OCR
  • Auth：須為公司 Owner/Admin；Session 須有效

• HINT-MUTATION-2：客服核准

  • 輸入：case_id、optional_note
  • 行為：狀態 → manual_approved；同步 BR-005；發送通過 Email

• HINT-MUTATION-3：客服退件

  • 輸入：case_id、reject_reason_code、reject_reason_text
  • 行為：狀態 → manual_rejected；發送退件 Email

8.3 Token / 合約必要欄位（不可 TBD）

9. 異常處理與錯誤提示對照表（Error Handling）

9.1 Email 範本（mandatory）

EM-KYB-01 自動審核通過

• 觸發：auto_approved
• 主旨：【WPORT】公司驗證已通過
• 內文：您好，{company_name} 之公司驗證文件已自動審核通過。您現在可以上架職缺，開始招募人才。
• CTA 按鈕：前往發布職缺
• CTA URL：https://wport.me/companies/{enc_company_id}/jobs/new

EM-KYB-02 自動審核退件

• 觸發：auto_rejected
• 主旨：【WPORT】公司驗證未通過 — 請重新上傳
• 內文：您好，{company_name} 之驗證文件未通過審核。原因：{reject_reason_text}。請依提示重新拍攝並上傳最新登記表。
• CTA：重新上傳驗證文件
• CTA URL：https://wport.me/companies/{enc_company_id}/verification

EM-KYB-03 轉人工審核中

• 觸發：pending_manual
• 主旨：【WPORT】公司驗證資料已收到
• 內文：您好，我們已收到 {company_name} 的驗證文件，專人將於 1 個工作天內完成審核，結果將以 Email 通知您。
• CTA：查看審核狀態
• CTA URL：https://wport.me/companies/{enc_company_id}/verification

EM-KYB-04 人工核准

• 觸發：manual_approved
• 主旨：【WPORT】公司驗證已通過
• 內文：同 EM-KYB-01

EM-KYB-05 人工退件

• 觸發：manual_rejected
• 主旨：【WPORT】公司驗證未通過 — 請重新上傳
• 內文：同 EM-KYB-02（原因由客服填寫）

10. 非功能需求（Non-Functional Requirements）

10.1 效能

10.2 資安與隱私

• 傳輸：TLS 1.3
• 靜態儲存：AES-256 加密
• 後台：僅 KYB 授權客服可存取；所有操作留 audit log（不可篡改）
• 文件保留：通過後至少 7 年（合規稽核）；退件文件 90 天後可排程刪除（可設定）

10.3 可用性

• 經濟部 API：Retry + 降級人工，禁止前端無限 loading
• OCR 服務：單節點故障時佇列化處理，逾時降級人工
• 目標可用性：99.5%（月）

10.4 技術選型備註（RD 可調整）

• OCR 引擎：建議方向為 PaddleOCR 或同等輕量模型，部署於自有 GPU/CPU，不消耗大模型 Token（v1）
• LLM Fallback：僅 v2；v1 不寫死特定多模態供應商
• 經濟部 API：對齊 pm_38 D1 之 GCIS 資料源精神；endpoint 由 RD 依現行可用品項實作，PRD 不寫死 URL

11. 導航 / Storybook Map

• Storybook 標題：Mockups/Company/KYB OCR Auto Verification
• Stories 路徑：storybook/src/stories/mockups/company/KybOcrAutoVerification.stories.ts
• Storybook（local-prd）：file:///Users/Eric/Documents/Github/prd/doc/feature/pm_49/kyb-ocr-auto-verification-mockup.md
• Storybook（online）：https://storybook.wport.me/?path=/docs/mockups-company-kybocrautoverification—docs
• 情境控制（建議 args）：
  • scenario: idle | uploading | quality_fail_dark | quality_fail_blur | processing | auto_approved | auto_rejected | pending_manual
  • countryCode: tw（非 tw 隱藏自動 KYB，顯示既有人工上傳）
• 對應 production 路由（參考）：
  • /companies/:id/verification（incremental 擴充現有驗證頁）
  • Site Admin：/siteadmin/kyb/reviews

12. Flowcharts（User / System / Navigation）

12.1 User Flow（企業用戶）

flowchart TD
    Start([進入公司驗證頁]) --> CheckCountry{country_code = tw?}
    CheckCountry -->|否| ManualVNTH[顯示 VN/TH 人工上傳流程 pm_38 D4]
    CheckCountry -->|是| CheckRole{Owner/Admin?}
    CheckRole -->|否| NoPerm[顯示無權限]
    CheckRole -->|是| CheckPending{已有進行中案件?}
    CheckPending -->|是| ShowPending[顯示審核中/輪詢狀態]
    CheckPending -->|否| Upload[選擇檔案或開啟相機]
    Upload --> QualityGate{前端品質預檢}
    QualityGate -->|失敗| QualityErr[顯示光線/模糊提示]
    QualityErr --> Upload
    QualityGate -->|通過| Submit[送出至後端]
    Submit --> Wait[顯示處理中 最長 60s]
    Wait --> Result{決策結果}
    Result -->|auto_approved| Pass[顯示通過 + 可上架職缺 CTA]
    Result -->|auto_rejected| Reject[顯示退件原因 + 重新上傳]
    Result -->|pending_manual| Manual[顯示專人審核中]
    Reject --> Upload
    Manual --> EmailWait[等待 Email 通知]

12.2 System Flow（自動審核流水線）

sequenceDiagram
    participant U as Employer FE
    participant API as WPORT API
    participant OCR as OCR Service
    participant MOEA as 經濟部 API
    participant Admin as KYB 後台

    U->>API: POST 驗證文件 + idempotency_key
    API->>API: 統編格式 + 與註冊統編比對
    alt 統編不符
        API-->>U: auto_rejected
    end
    API->>OCR: 提取 5 欄位
    OCR-->>API: OCR 結果 + 信心分數
    API->>MOEA: 以統編查登記資料
    alt API 失敗 after retry
        API->>API: pending_manual registry_unavailable
        API-->>U: pending_manual
        API->>Admin: 進入待審佇列
    else API 成功
        API->>API: 狀態檢查 + 正規化比對
        alt 登記狀態解散/廢止/撤銷
            API-->>U: auto_rejected
        else 停業或模糊比對
            API->>Admin: pending_manual
            API-->>U: pending_manual
        else 100% 比對通過
            API->>API: 更新 BR-005 已通過
            API-->>U: auto_approved
            API->>U: Email 通過通知
        end
    end
    Admin->>API: 核准/退件
    API->>U: Email 結果通知

12.3 Navigation Flow

flowchart LR
    CompanyEdit[公司編輯頁] --> Verification[公司驗證頁 SEC-U1~U6]
    JobPublish[發布職缺] -->|未 BR-005| Verification
    Verification -->|通過| JobNew[新增職缺]
    SiteAdmin[Site Admin] --> KybList[KYB 待審清單 SEC-A1]
    KybList --> KybDetail[案件詳情 SEC-A2/A3]

12.4 比對決策子流程（共用）

flowchart TD
    N[欄位正規化] --> D{欄位類型}
    D -->|代表人姓名| Exact{完全一致?}
    Exact -->|是| M1[match]
    Exact -->|否| MM[mismatch → auto_reject 或 manual]
    D -->|日期| DateNorm[民國轉西元] --> DateCmp{與 AncDate 一致?}
    DateCmp -->|是| M1
    DateCmp -->|無法解析| U1[uncertain → manual]
    DateCmp -->|否| MM
    D -->|地址| AddrNorm[臺→台 樓層格式統一] --> Fuzzy{相似度}
    Fuzzy -->|>90%| M1
    Fuzzy -->|70-90%| U1
    Fuzzy -->|<70%| MM

12.5 Edge Case Coverage（必填）

13. Mock Data Schema（Mock 資料結構）

• 資料來源：Storybook mock only
• 建議情境資料：
  • mockCaseAutoApproved：全欄位 match
  • mockCaseAddressUncertain：地址相似度 82%
  • mockCaseTaxIdMismatch：OCR 統編 vs 註冊統編不符
  • mockCaseRegistryDissolved：經濟部狀態解散
  • mockAdminQueue：5 筆待審含不同 reason tag
• CRUD：mock 內狀態變更僅存在元件內，重新整理還原

14. 實作備註（Implementation Notes）

14.1 Incremental vs 新頁

• 用戶端：Incremental — 擴充現有「公司驗證文件上傳」區塊；tw 時啟用品質預檢 + 即時審核 UX
• 後台：新頁 — Site Admin KYB 待審模組（可掛於現有 siteadmin 導航下）

14.2 禁止事項

• ❌ 本文件不直接定義最終 API path/method
• ❌ v1 不將 VN/TH 接入自動 OCR
• ❌ 不修改 C 端「統編驗證徽章」（pm_38 D20）

14.3 Migration / 相容性

15. 一致性表（Consistency Tables）

15.1 欄位對照表

15.2 常數表

15.3 事件字典

15.4 術語字典

15.5 版本凍結表

16. PRD 問題清單

17. Sync-Fix List（跨產物同步）

18. 下一步（Next Steps）

1. 與 RD 確認經濟部 API 可用欄位與 停業 狀態處理政策
2. 使用 gen-storybook-mockup-gen 產出 SEC-U1U6、SEC-A1A3 mockup
3. 離線標註 200 份歷史登記表，校準 OCR 與地址相似度閾值
4. backend-api-spec-generator 產出 OpenAPI
5. Feature flag 灰度：先內部測試公司 → 10% TW 新送審 → 全量

文件結束