營業稅申報管理系統

01系統概述

1.1 背景

事務所目前以 Excel（如 115期帳務明細.xlsx）人工維護營業稅申報。痛點：多人同檔協作衝突、權限無法隔離、歷史期別靠複製檔案、請款金額重複手動輸入、主管缺乏即時彙總視圖。

1.2 目標

1. 申報作業線上化，支援 7 人同時作業且資料隔離。
2. 以「期別」為單位管理工作分配與資料保存，歷史不覆蓋。
3. 進銷項／代收費／服務費一次輸入，自動帶入請款單。
4. 提供主管即時彙總儀表板與報表匯出。

1.3 範圍

02名詞定義

03角色與權限

04系統架構（自建網頁系統）

三層式架構。沿用 Ragic 的概念對照，但實作為自建系統：每張「表單」= 一張資料表 + 一組 CRUD API；「連結載入」= FK + JOIN；「列級權限」= 後端強制擁有者條件。

┌─────────── 前端 SPA ───────────┐
│ 登入  客戶主檔  工作區  請款單  儀表板 │
│ React/Vue + 表格元件 + 圖表          │
└───────────────┬────────────────────┘
                │ HTTPS / JWT
┌───────────────▼────────────────────┐
│           後端 API（REST）            │
│  Auth │ 業務邏輯 │ 計算層 │ 匯出服務    │
│  Node(NestJS) 或 Python(FastAPI)     │
└───────────────┬────────────────────┘
                │ SQL（含列級權限）
┌───────────────▼────────────────────┐
│        資料庫（PostgreSQL/MySQL）      │
│        7 張資料表（見第 6 節）          │
└─────────────────────────────────────┘

4.1 概念對照（Ragic → 自建）

05資料模型（ERD）

[使用者] 1 ──< [客戶主檔] 1 ──< [期別分配明細] >── 1 [期別]
                   │                    │
                   │                    │ 拋轉產生
                   │                    ▼
                   │            [同事工作區記錄] 1 ─── 1 [請款單]
                   │                                      ▲
                   └──────────────────────────────────────┤
                                            [費用轉入紀錄] >─┘

5.1 主要實體與鍵值

06資料庫 Schema（核心）

-- 1. 使用者（★帳號/密碼由主管直接管理）
TABLE users (
  id            PK,
  name, account, password_hash,
  role          ENUM('manager','staff'),
  active        BOOL, created_at, updated_at
)
-- 1.1 操作軌跡（★供熱度圖）
TABLE activity_logs (
  id PK, user_id FK→users,
  action,                          -- login / edit_worksheet / send_email...
  entity, entity_id,               -- 對象類型與識別
  created_at                       -- 熱度圖以 user+日期+小時 聚合
)

-- 2. 客戶主檔（可停用）
TABLE customers (
  customer_no   PK,              -- 客編 00001
  company_name, tax_id,            -- 名稱、統一編號
  default_staff_id FK→users,
  status        ENUM('active','inactive')  -- 停用功能
)
-- 2.1 客戶聯絡資訊（★一對多）
TABLE customer_contacts (
  id PK, customer_no FK,
  contact_name, phone, mobile, email,
  is_primary BOOL, note          -- 可多筆，設主要
)
-- 2.2 客戶匯款資訊（★一對多）
TABLE customer_bank_accounts (
  id PK, customer_no FK,
  bank_name, branch, account_no, account_name,
  is_primary BOOL, note          -- 可多筆，設主要
)

-- 3. 期別（★民國年 + 期次，每年 6 期）
TABLE periods (
  period_code   PK,              -- '115-3' = 民國115年 第3期
  roc_year      INT,             -- 民國年（西元 = +1911）
  seq           INT,             -- 期次 1~6（雙月）
  month_range,                     -- '05-06月'
  start_date, end_date, is_closed BOOL,
  UNIQUE(roc_year, seq)
)
-- 期次對照：1=01-02月 2=03-04月 3=05-06月
--          4=07-08月 5=09-10月 6=11-12月

-- 4. 期別分配明細
TABLE period_assignments (
  id            PK,
  period_code   FK, customer_no FK,
  staff_id      FK→users, assigned_at,
  UNIQUE(period_code, customer_no)   -- 一期一客戶一筆
)

-- 5. 同事工作區記錄（A~E 區）
TABLE worksheet_records (
  id PK, period_code FK, customer_no FK, staff_id FK,
  -- A 進銷項（手動）
  sales_amount, sales_tax, purchase_amount, purchase_tax,
  trade_count, other_qty, posting_note,
  -- B 稅額（★手動填寫，無公式）
  prev_credit, curr_credit, tax_reserved, collected_bt,
  -- C 代收 11 項（手動）→ c_subtotal 自動加總
  c_business_tax, c_invoice, c_dividend_nhi, c_prepay,
  c_rent_withhold, c_rent_nhi, c_addr_rent, c_nhi,
  c_other_collect, c_tax_collect, c_self_pay_offset,
  c_subtotal,                      -- 代收合計（自動）
  -- D 服務費 8 項（手動）→ d_subtotal 自動加總
  d_bookkeeping, d_biz_reg, d_shareholder, d_cpa_audit,
  d_dec_addon, d_other_service, d_other_fixed, d_bk_offset,
  d_subtotal,                      -- 服務合計（自動）
  -- E 申報狀態
  invoice_detail_note, einvoice_count, is_filed BOOL,
  UNIQUE(period_code, customer_no)
)

-- 6. 費用轉入紀錄（★手動輸入）
TABLE expense_imports (
  id PK, period_code FK, customer_no FK,
  category,                        -- 規費/郵費...
  amount, note, created_at
)

-- 7. 請款單
TABLE invoices (
  id PK, period_code FK, customer_no FK, staff_id FK,
  c_subtotal, d_subtotal,          -- ★預設帶工作區，員工可編輯覆寫
  imported_expense_total,          -- ★預設帶 expense_imports，可編輯
  current_amount,                  -- 本期金額（自動重算）
  prev_balance,                    -- ★上期結轉，可調
  received, discount,              -- 已收、折扣（手動）
  receivable,                      -- 應收（自動重算）
  amount_overridden BOOL,           -- 金額被手動覆寫標記
  email_to, email_cc,              -- ★寄送收件人/副本（預設帶主要聯絡人）
  email_sent_at, email_status,     -- ★寄送時間/狀態（sent/failed）
  note,
  UNIQUE(period_code, customer_no)
)

07功能模組

08欄位規格書

A. 進銷項資料 手動

B. 稅額計算欄 手動填寫（無公式）

C. 代收費用欄（11 項）手動 → 合計自動

代收營業稅、發票代收、股利二代健保費、暫繳、房租扣繳、房租二代、借址房租、搭保健保費、其他代收款、代收稅金、自繳稅額／發票折抵。

→ 小計：代收合計 = 上列 11 項加總（系統自動）

D. 服務費欄（8 項）手動 → 合計自動

記帳費、工商登記、股東平台申報、會計師簽證、扣繳結算加收(12月)、其他服務費、其他固定收費、記帳費折抵。

→ 小計：服務合計 = 上列加總（折抵以負值計，系統自動）

E. 申報狀態

請款單欄位

客戶聯絡資訊 一對多

客戶匯款資訊 一對多

09計算邏輯

僅「純加總／結轉」由系統自動計算；稅額（B 區）為人工填寫。

-- 自動計算（後端計算層，前端不得自算）
c_subtotal            = Σ(代收 11 項)
d_subtotal            = Σ(服務 8 項，折抵為負)
imported_expense_total = Σ expense_imports WHERE 期別+客編
current_amount        = c_subtotal + d_subtotal + imported_expense_total
receivable            = current_amount + prev_balance - received - discount

-- 跨期結轉（開新期時帶入）
本期 invoices.receivable  ──結轉──▶  下期 invoices.prev_balance

-- B 區稅額：★人工填寫，系統不計算
prev_credit / curr_credit / tax_reserved / collected_bt = 手動輸入

10API 設計（REST 摘要）

11權限控制（列級隔離）

中介層：解析 JWT → req.user { id, role }

if role == 'manager':
    # 不加擁有者條件，可查/改全部
if role == 'staff':
    # 所有 worksheet / invoice 查詢強制：
    WHERE staff_id = req.user.id
    # 寫入時僅能改 staff_id == 自己 的記錄

# 客戶主檔 / 期別 / 分配 / 拋轉 → 僅 manager

12業務流程

主管建立新期別（如 115 年 第3期 / period_code 115-3）
   → 繼承「啟用中」客戶主檔
   → 結轉上期留抵 / 應收欠款
   → 批次分配客戶給同事
   → 拋轉至各同事工作區
        → 同事輸入 進銷項 / 稅額 / 代收 / 服務費
        → 系統自動算 代收合計 / 服務合計
        → 標記「申報完成」
   → 費用轉入（規費 / 郵費 手動登錄）
   → 產生請款單（自動帶金額、結轉欠款）
   → 主管儀表板檢視完成率
   → 匯出全體報表（對齊 Excel 範本）

13報表與匯出

• 當期全體客戶帳務明細（進銷項 + 代收 + 服務費 + 應收）。
• 格式對齊現行 Excel 彙總表；做成可調整範本（欄位順序/欄名可設定），因日後可能再改。
• 篩選維度：期別、負責同事、申報狀態。
• 輸出格式：Excel(xlsx) / CSV。

14非功能性需求

15決策紀錄與待辦

15.1 已確認決策

15.2 待辦/待確認