# 寢具集團 ERP Web 系統規劃書

> **文件版本**：v1.0  
> **建立日期**：2026-02-22  
> **文件性質**：文件即規格（Docs as Spec）— 以此文件為開發依據，功能異動時同步更新本文件，避免規劃書過期  
> **開發語言**：PHP 8.5 + Apache + PDO_ODBC  
> **資料庫**：Microsoft SQL Server（Ubuntu 192.168.50.207:1433）

---

## 📋 目錄

1. [專案概述](#1-專案概述)
2. [三公司業務說明](#2-三公司業務說明)
3. [系統架構](#3-系統架構)
4. [資料庫連線設計](#4-資料庫連線設計)
5. [模組規劃總覽](#5-模組規劃總覽)
6. [Module 01 — 使用者登入與權限](#module-01--使用者登入與權限)
7. [Module 02 — 商品管理](#module-02--商品管理)
8. [Module 03 — 庫存管理](#module-03--庫存管理)
9. [Module 04 — 廠商管理](#module-04--廠商管理)
10. [Module 05 — 客戶管理](#module-05--客戶管理)
11. [Module 06 — 採購管理](#module-06--採購管理)
12. [Module 07 — 出貨銷售管理](#module-07--出貨銷售管理)
13. [Module 08 — 退貨管理](#module-08--退貨管理)
14. [Module 09 — 報表中心](#module-09--報表中心)
15. [Module 10 — 系統管理](#module-10--系統管理)
16. [Module 11 — 基礎資料維護](#module-11--基礎資料維護)
17. [共用元件規格](#共用元件規格)
18. [API 設計規範](#api-設計規範)
19. [開發時程規劃](#開發時程規劃)
20. [變更記錄](#變更記錄)

---

## 1. 專案概述

### 1.1 專案目標

建置一套支援三家公司的 **多租戶 ERP Web 系統**，提供：
- 區網內部人員操作介面
- 網際網路遠端存取（透過 HTTPS）
- 完整的 CRUD 操作（新增/查詢/修改/刪除）
- 統一的三公司資料切換與整合檢視

### 1.2 商品業務範圍

本系統為寢具/家紡批發零售業，商品涵蓋：

| 大類 | 細項 |
|------|------|
| 寢具被枕 | 棉被、涼被、毛毯、羽絨被、羊毛被、蠶絲被、枕頭、被套 |
| 床墊床架 | 一般床墊、乳膠床墊、保潔墊、床罩組、床包組 |
| 席類坐墊 | 竹席、草席、夏季坐墊、冬季坐墊、沙發坐墊 |
| 毛巾窗簾 | 毛巾、浴巾、窗簾、桌巾 |
| 地墊地毯 | 防滑板、一般地墊、地毯 |
| 其他 | 蚊帳、抱枕、狗窩、桌椅床 |

---

## 2. 三公司業務說明

| 代碼 | 公司名稱 | 資料庫 | 業務定位 |
|------|---------|--------|---------|
| `01` | 金草 | `BRMS_ERP_FLOW` | 總倉/主系統，廠商最完整，負責進貨驗收 |
| `02` | 金永盛 | `BRMS_ERP_FLOW2` | 銷售通路體系，直送客戶，銷售量最大 |
| `03` | 家紡 | `BRMS_ERP_FLOW3` | 分公司/區域事業部，庫存最多，銷售明細最豐富 |

### 2.1 三公司資料規模

| 指標 | 金草(01) | 金永盛(02) | 家紡(03) |
|------|---------|----------|---------|
| 客戶主檔(GCU000) | 149,688 | 146,793 | 88,206 |
| 出貨單(SALE) | 109,371 | 133,343 | 63,947 |
| 出貨明細(SITEM) | 432,000 | 525,524 | 538,536 |
| 採購訂單(GPO050) | 82,591 | 76,795 | 49,261 |
| 廠商主檔(PVM000) | 22,359 | 1 | 1,517 |
| 庫存(STOCK) | 6,021 | 2,385 | 11,677 |
| 庫存明細(IITEM) | 61,056 | 26 | 26 |

### 2.2 各公司功能差異說明

| 功能模組 | 金草(01) | 金永盛(02) | 家紡(03) | 備註 |
|---------|:-------:|:--------:|:-------:|------|
| 廠商管理 | ✅ 完整 | ⚠️ 幾乎空 | ✅ 有資料 | 02 不自行管理廠商 |
| 採購管理 | ✅ | ✅ | ✅ | 03 無應付採購(PPO) |
| 進貨驗收 | ✅ 完整 | ⚠️ 極少 | ⚠️ 極少 | 進貨集中在01 |
| 庫存明細 | ✅ 完整 | ❌ 極少 | ❌ 極少 | 細項庫存集中在01 |
| 出貨銷售 | ✅ | ✅ 量最大 | ✅ 明細最多 | 三公司皆活躍 |
| 應付採購 | ✅ | ✅ | ❌ | 03無此流程 |
| 退貨管理 | ✅ | ✅ | ❌ | 03無退廠資料 |

---

## 3. 系統架構

### 3.1 部署架構

```
┌───────────────────────────────────────────────────────┐
│                    使用者端                             │
│   區網瀏覽器          網際網路瀏覽器（HTTPS）             │
└───────────┬──────────────────────┬────────────────────┘
            │                      │
            ▼                      ▼
┌───────────────────────────────────────────────────────┐
│             Ubuntu Web Server (192.168.50.207)         │
│  ┌─────────────────────────────────────────────────┐  │
│  │  Apache 2.4  :80 / :443 (Let's Encrypt TLS)     │  │
│  │  PHP 8.x + PDO_ODBC                             │  │
│  │  ┌─────────────────────────────────────────┐   │  │
│  │  │         ERP Web Application              │   │  │
│  │  │  /login   /dashboard                    │   │  │
│  │  │  /company/{01|02|03}/...               │   │  │
│  │  └─────────────────────────────────────────┘   │  │
│  └─────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────┐  │
│  │  SQL Server (port 1433 — 僅內部存取)              │  │
│  │  BRMS_ERP_FLOW / FLOW2 / FLOW3                   │  │
│  └──────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────┘
```

### 3.2 目錄結構

```
/var/www/html/erp/
├── index.php               # 入口/路由分發
├── login.php               # 登入頁面
├── config/
│   ├── database.php        # 三公司資料庫連線設定
│   └── app.php             # 應用程式設定
├── core/
│   ├── Database.php        # PDO 連線管理（多租戶）
│   ├── Auth.php            # 身分驗證
│   ├── Router.php          # 路由
│   └── Response.php        # 統一回應格式
├── modules/
│   ├── product/            # 商品管理
│   ├── stock/              # 庫存管理
│   ├── vendor/             # 廠商管理
│   ├── customer/           # 客戶管理
│   ├── purchase/           # 採購管理
│   ├── sales/              # 出貨銷售管理
│   ├── returns/            # 退貨管理
│   ├── report/             # 報表中心
│   ├── system/             # 系統管理
│   └── master/             # 基礎資料
├── views/
│   ├── layout/
│   │   ├── header.php
│   │   ├── sidebar.php
│   │   └── footer.php
│   └── {module}/
│       ├── list.php        # 列表頁
│       ├── form.php        # 新增/編輯表單
│       └── detail.php      # 詳細檢視
├── api/
│   └── v1/                 # REST API 端點
└── public/
    ├── css/
    ├── js/
    └── img/
```

### 3.3 技術選型

| 項目 | 技術 | 說明 |
|------|------|------|
| 後端語言 | PHP 8.5 | 已安裝，無需變更 |
| Web Server | Apache 2.4 | 已架設 |
| 資料庫驅動 | PDO_ODBC + ODBC Driver 17 | 已驗證可連 SQL Server |
| 前端框架 | Bootstrap 5 + Alpine.js | 輕量，無需 Node.js 建置 |
| 表格套件 | DataTables.js | 支援排序/分頁/搜尋 |
| 圖表套件 | Chart.js | 報表視覺化 |
| 身分驗證 | PHP Session + CSRF Token | 傳統安全驗證 |
| 加密 | `password_hash()` + bcrypt | 密碼加密儲存 |

---

## 4. 資料庫連線設計

### 4.1 連線設定檔

```php
// config/database.php
return [
    'companies' => [
        '01' => [
            'name'     => '金草',
            'database' => 'BRMS_ERP_FLOW',
            'dsn'      => 'odbc:Driver={ODBC Driver 17 for SQL Server};Server=192.168.50.207,1433;Database=BRMS_ERP_FLOW;TrustServerCertificate=yes;',
            'username' => 'sa',
            'password' => '188839@Web',
        ],
        '02' => [
            'name'     => '金永盛',
            'database' => 'BRMS_ERP_FLOW2',
            'dsn'      => 'odbc:Driver={ODBC Driver 17 for SQL Server};Server=192.168.50.207,1433;Database=BRMS_ERP_FLOW2;TrustServerCertificate=yes;',
            'username' => 'sa',
            'password' => '188839@Web',
        ],
        '03' => [
            'name'     => '家紡',
            'database' => 'BRMS_ERP_FLOW3',
            'dsn'      => 'odbc:Driver={ODBC Driver 17 for SQL Server};Server=192.168.50.207,1433;Database=BRMS_ERP_FLOW3;TrustServerCertificate=yes;',
            'username' => 'sa',
            'password' => '188839@Web',
        ],
    ],
    'default_options' => [
        PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
        PDO::ATTR_STRINGIFY_FETCHES  => false,
    ],
];
```

### 4.2 多租戶連線管理類別

```php
// core/Database.php
class Database {
    private static array $instances = [];

    public static function get(string $companyCode): PDO {
        if (!isset(self::$instances[$companyCode])) {
            $cfg = config('database.companies')[$companyCode];
            self::$instances[$companyCode] = new PDO(
                $cfg['dsn'], $cfg['username'], $cfg['password'],
                config('database.default_options')
            );
        }
        return self::$instances[$companyCode];
    }
}

// 使用範例
$db = Database::get('01');  // 金草
$db = Database::get('02');  // 金永盛
$db = Database::get('03');  // 家紡
```

### 4.3 URL 路由規則

```
/erp/{companyCode}/{module}/{action}/{id?}

範例：
/erp/01/product/list           金草 商品列表
/erp/02/customer/view/C001    金永盛 客戶詳細
/erp/03/sales/edit/S20250101  家紡 編輯出貨單
```

---

## 5. 模組規劃總覽

| # | 模組名稱 | 主要資料表 | 金草01 | 金永盛02 | 家紡03 | 優先度 |
|---|---------|----------|:------:|:-------:|:------:|:----:|
| 01 | 使用者登入與權限 | USERS, SYS_ROLES, USERMENUS | ✅ | ✅ | ✅ | P0 |
| 02 | 商品管理 | PRODUCT, GPMF, MAKER | ✅ | ✅ | ✅ | P0 |
| 03 | 庫存管理 | STOCK, IITEM, DPMF | ✅ | ✅ | ✅ | P0 |
| 04 | 廠商管理 | PVM000, MAKER | ✅ | ⚠️ | ✅ | P1 |
| 05 | 客戶管理 | GCU000~052, CUST, CLEVEL | ✅ | ✅ | ✅ | P0 |
| 06 | 採購管理 | GPO050/051, PPO050/051, IMPORT, IITEM | ✅ | ✅ | ⚠️ | P1 |
| 07 | 出貨銷售管理 | SALE, SITEM, GSALE, GSITEM, RSALE | ✅ | ✅ | ✅ | P0 |
| 08 | 退貨管理 | RSALE, RSITEM, RIITEM, RIMP | ✅ | ✅ | ❌ | P1 |
| 09 | 報表中心 | 跨表統計查詢 | ✅ | ✅ | ✅ | P2 |
| 10 | 系統管理 | USERS, SYS_ROLES, SYS_MODULES | ✅ | ✅ | ✅ | P1 |
| 11 | 基礎資料維護 | AREA, BAS_BANK2, CODE, DPMF, GPMF | ✅ | ✅ | ✅ | P2 |

> `⚠️` = 有限度支援（資料量少）  
> `❌` = 該公司無此業務，介面隱藏但不刪除

---

## Module 01 — 使用者登入與權限

### 涉及資料表

| 資料表 | 中文說明 | 操作 |
|--------|---------|------|
| `USERS` | 使用者主檔 | CRUD |
| `SYS_ROLES` | 角色定義 | CRUD |
| `SYS_ROLEGROUPS` | 角色群組 | CRUD |
| `SYS_ROLEGROUPS_D` | 角色群組明細 | CRUD |
| `USERMENUS` | 使用者可用選單 | R（唯讀查詢） |
| `SYS_MODULE_SEC_H/D` | 模組安全設定 | R |

### 功能清單

#### 1.1 登入頁 `/login`
- [ ] 輸入帳號/密碼，驗證 `USERS` 資料表
- [ ] 選擇公司（01 金草 / 02 金永盛 / 03 家紡）
- [ ] Session 儲存：`user_id`, `company_code`, `company_name`, `roles`
- [ ] 失敗 3 次帳號鎖定（更新 `USERS.FLAG1`）
- [ ] 登入記錄寫入 `TRANSACTION_LOG`

#### 1.2 登出 `/logout`
- [ ] 清除 Session，導回登入頁

#### 1.3 公司切換（登入後）
- [ ] 切換三公司時不需重新登入（同帳號需在各庫都存在）
- [ ] 切換後 Session 更新 `company_code`

#### 1.4 個人設定 `/my/profile`
- [ ] 修改密碼（舊密碼驗證）
- [ ] 顯示目前角色與可用模組

### USERS 資料表關鍵欄位

```sql
-- 查詢 USERS 欄位結構
SELECT COLUMN_NAME, DATA_TYPE, CHARACTER_MAXIMUM_LENGTH
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_NAME = 'USERS'
ORDER BY ORDINAL_POSITION;
```

> ⚠️ **待補充**：執行上述 SQL 後，將欄位說明補充至此處

### 權限控制邏輯

```
使用者 → 角色(SYS_ROLES) → 角色群組(SYS_ROLEGROUPS)
                              ↓
                    模組安全設定(SYS_MODULE_SEC_H/D)
                              ↓
                    可存取的功能模組(SYS_MODULES)
                              ↓
                    使用者選單(USERMENUS)
```

---

## Module 02 — 商品管理

### 涉及資料表

| 資料表 | 中文說明 | 操作 |
|--------|---------|------|
| `PRODUCT` | 商品主檔 | CRUD |
| `GPMF` | 商品群組主檔 | CRUD |
| `MAKER` | 品牌廠商主檔 | CRUD |
| `MKPRICE` | 標籤定價 | CRUD |
| `FFDP` | 前端定價主檔 | CRUD |
| `FFDPPLU` | 前端定價商品對應 | CRUD |
| `MM_H` | 套組商品表頭 | CRUD |
| `MM_I` | 套組商品明細 | CRUD |
| `AUTONUM` | 自動編號 | R（系統自動取號） |

### 功能清單

#### 2.1 商品列表 `/product/list`
- [ ] 分頁顯示（每頁 50 筆，DataTables）
- [ ] 搜尋：商品代碼(PLU_CODE)、商品名稱、商品群組、品牌
- [ ] 篩選：群組(GPMF)、品牌(MAKER)、是否停用
- [ ] 排序：代碼、名稱、售價、更新日期
- [ ] 批次操作：停用/啟用、匯出 Excel

#### 2.2 商品新增 `/product/create`
- [ ] 必填欄位：商品代碼(PLU_CODE)、商品名稱、商品群組(GP_CODE)
- [ ] 選填欄位：品牌(MAKER_NO)、成本價、售價、安全庫存量
- [ ] 商品代碼唯一性驗證
- [ ] 自動帶入商品群組預設資料
- [ ] 寫入 `PRODUCT` + 更新 `TABLEVERSION`

#### 2.3 商品編輯 `/product/edit/{plu_code}`
- [ ] 載入商品完整資料
- [ ] 變更記錄：修改前後差異寫入 `TRANSACTION_LOG`
- [ ] 不允許修改商品代碼（主鍵保護）

#### 2.4 商品詳細 `/product/view/{plu_code}`
- [ ] 顯示完整商品資訊
- [ ] 顯示目前庫存（來自 STOCK）
- [ ] 顯示近 12 個月銷售量（來自 SITEM+GSITEM）
- [ ] 顯示定價歷程（MKPRICE）

#### 2.5 商品刪除
- [ ] 軟刪除（更新停用欄位），不實際 DELETE
- [ ] 若商品有出貨/採購記錄，禁止刪除

#### 2.6 商品群組管理 `/product/group`
- [ ] 群組 CRUD（GPMF：GP_CODE, GP_NAME, LINK_BGP）
- [ ] 樹狀結構展示（上下層關係）

#### 2.7 定價管理 `/product/price`
- [ ] 標籤定價 CRUD（MKPRICE）
- [ ] 前端定價 CRUD（FFDP + FFDPPLU）

#### 2.8 套組商品 `/product/bundle`
- [ ] 套組主檔 CRUD（MM_H）
- [ ] 套組明細 CRUD（MM_I：組成商品清單）

### PRODUCT 關鍵欄位（待補充）

> ⚠️ 執行 `SELECT COLUMN_NAME FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME='PRODUCT' ORDER BY ORDINAL_POSITION;` 後補充至此

### 資料驗證規則

| 欄位 | 規則 |
|------|------|
| PLU_CODE | 必填、唯一、最長 16 碼 |
| GP_CODE | 必填、需存在於 GPMF |
| MAKER_NO | 選填、若填入需存在於 MAKER |
| 售價 | 數字、≥ 0 |

---

## Module 03 — 庫存管理

### 涉及資料表

| 資料表 | 中文說明 | 操作 |
|--------|---------|------|
| `STOCK` | 庫存主表（彙總） | R + 調整 |
| `IITEM` | 庫存商品明細（細項） | R（僅金草01有效） |
| `DPMF` | 倉庫/門市主檔 | CRUD |
| `ADJUST_H` | 庫存調整單表頭 | CRUD |
| `ADJUST_I` | 庫存調整單明細 | CRUD |
| `GINVMN` | 進貨月結彙總 | R |
| `STKNAME` | 庫存名稱定義 | CRUD |

### 功能清單

#### 3.1 庫存查詢 `/stock/query`
- [ ] 依商品代碼查詢各倉庫庫存量（STOCK）
- [ ] 依倉庫查詢所有商品庫存
- [ ] 庫存不足警示（低於安全庫存）
- [ ] 匯出 Excel

#### 3.2 庫存明細 `/stock/detail`（金草01 專用）
- [ ] 顯示 IITEM 細項庫存（批次號、效期等）
- [ ] 金永盛02/家紡03 顯示說明：「詳細庫存資訊請查詢金草系統」

#### 3.3 倉庫管理 `/stock/warehouse`
- [ ] 倉庫 CRUD（DPMF）
- [ ] 欄位：DP_CODE、DP_NAME1、SF_STOCK（是否計入庫存）、S_DATE/E_DATE（啟用期間）

#### 3.4 庫存調整單 `/stock/adjust`
- [ ] 新增調整單（ADJUST_H + ADJUST_I）
- [ ] 調整原因分類（盤盈/盤虧/損壞）
- [ ] 調整後自動更新 STOCK 數量
- [ ] 調整歷程查詢

#### 3.5 月結庫存查詢 `/stock/monthly`
- [ ] 顯示 GINVMN 進貨月結彙總
- [ ] 按月份、商品群組統計

---

## Module 04 — 廠商管理

> ⚠️ **金永盛02** 廠商資料極少（PVM000 僅 1 筆），此模組在02公司介面以唯讀顯示為主

### 涉及資料表

| 資料表 | 中文說明 | 操作 |
|--------|---------|------|
| `PVM000` | 廠商主檔 | CRUD |
| `MAKER` | 品牌廠商主檔 | CRUD |
| `MAKER_YEAR_H` | 廠商年度合約表頭 | CRUD |
| `MAKER_YEAR_I` | 廠商年度合約明細 | CRUD |

### 功能清單

#### 4.1 廠商列表 `/vendor/list`
- [ ] 分頁搜尋（廠商代碼、名稱、統編）
- [ ] 顯示廠商採購金額統計（來自 GPO051）

#### 4.2 廠商 CRUD `/vendor/create|edit|view|delete`
- [ ] 基本資料：代碼、名稱、統編、地址、電話、聯絡人
- [ ] 付款條件：付款方式、信用額度、付款天數
- [ ] 軟刪除：有採購記錄者禁止刪除

#### 4.3 品牌廠商 CRUD `/vendor/brand`
- [ ] MAKER 表：品牌代碼、品牌名稱
- [ ] 關聯顯示：該品牌底下的商品清單

#### 4.4 廠商年度合約 `/vendor/contract`
- [ ] MAKER_YEAR_H + MAKER_YEAR_I CRUD
- [ ] 合約期間、數量目標、扣款條件

---

## Module 05 — 客戶管理

### 涉及資料表

| 資料表 | 中文說明 | 操作 |
|--------|---------|------|
| `GCU000` | 全客戶主檔（核心） | CRUD |
| `GCU050` | 客戶次要資料 | CRUD |
| `GCU051` | 客戶詳細資料 | CRUD |
| `GCU052` | 客戶補充資料 | CRUD |
| `CUST` | 客戶主檔（公司行號） | CRUD |
| `CLEVEL` | 客戶等級定義 | CRUD |
| `PDP_BIRTHDAY` | 生日資料 | R |

### 功能清單

#### 5.1 客戶列表 `/customer/list`
- [ ] 分頁顯示（DataTables）
- [ ] 搜尋：客戶代碼(CUSTNO)、客戶名稱、電話、地址
- [ ] 篩選：客戶等級(CLEVEL)、業務員、地區(AREA)
- [ ] 快速預覽：最近一筆出貨日期、累計消費金額

#### 5.2 客戶 CRUD `/customer/create|edit|view|delete`
- [ ] 基本資料（GCU000）：代碼、名稱、統編、地址、電話
- [ ] 次要資料（GCU050/051/052）：聯絡人、信用額度、付款條件
- [ ] 客戶等級（CLEVEL）關聯設定
- [ ] 業務員(SALE_CODE)指派
- [ ] 軟刪除：有出貨記錄者禁止刪除

#### 5.3 客戶詳細頁 `/customer/view/{custno}`
- [ ] 完整客戶資訊（GCU000+050+051+052 合併）
- [ ] 出貨歷程（SALE + SITEM，按日期倒序，最近 20 筆）
- [ ] 應收帳款狀況（SALE.PAID_FLG / PAID_AMT）
- [ ] 生日提醒（PDP_BIRTHDAY）
- [ ] 消費統計：月度/年度消費金額圖表

#### 5.4 客戶等級管理 `/customer/level`
- [ ] CLEVEL CRUD
- [ ] 等級條件設定（消費金額門檻）

---

## Module 06 — 採購管理

> ⚠️ **家紡03** 無應付採購(PPO050/051)，相關功能在03公司介面隱藏

### 涉及資料表

| 資料表 | 中文說明 | 操作 |
|--------|---------|------|
| `GPO050` | 採購訂單表頭 | CRUD |
| `GPO051` | 採購訂單明細 | CRUD |
| `PPO050` | 應付採購單表頭（01,02） | CRUD |
| `PPO051` | 應付採購單明細（01,02） | CRUD |
| `IMPORT` | 進貨驗收單 | CRUD |
| `IITEM` | 進貨驗收明細 | CRUD |
| `RIMP` | 退廠單 | CRUD |
| `RIITEM` | 退廠明細 | CRUD |
| `AUTONUM` | 自動編號 | R |

### 業務流程

```
廠商報價/詢價 → 採購訂單(GPO050/051) → 進貨驗收(IMPORT/IITEM)
                        ↓                         ↓
              應付採購單(PPO050/051)            庫存更新(STOCK)
              [僅01/02公司]                         ↓
                                              退廠單(RIMP/RIITEM)
```

### 功能清單

#### 6.1 採購訂單 `/purchase/order`
- [ ] 採購單列表（GPO050），可依廠商、日期、狀態篩選
- [ ] 新增採購單（GPO050 + GPO051）
  - [ ] 選擇廠商（PVM000 下拉）
  - [ ] 批量加入商品明細（支援掃碼/商品搜尋）
  - [ ] 數量/單價/金額自動計算
  - [ ] 預計到貨日期
- [ ] 編輯採購單（未驗收前可修改）
- [ ] 採購單詳細檢視（含進貨驗收狀態）
- [ ] 採購單取消（更新狀態欄位）
- [ ] 列印採購單 PDF

#### 6.2 進貨驗收 `/purchase/receipt`（主要供金草01使用）
- [ ] 依採購單建立進貨驗收單（IMPORT + IITEM）
- [ ] 掃描條碼入庫
- [ ] 驗收差異處理（數量不符）
- [ ] 驗收後自動更新 STOCK
- [ ] 進貨記錄查詢

#### 6.3 應付採購管理 `/purchase/payable`（01/02公司）
- [ ] PPO050/051 CRUD
- [ ] 付款狀態追蹤
- [ ] 對帳功能

#### 6.4 退廠管理 `/purchase/return`（01/02公司）
- [ ] 退廠單 CRUD（RIMP + RIITEM）
- [ ] 關聯原進貨單
- [ ] 退廠後更新庫存

---

## Module 07 — 出貨銷售管理

### 涉及資料表

| 資料表 | 中文說明 | 操作 |
|--------|---------|------|
| `SALE` | 出貨/銷售單表頭 | CRUD |
| `SITEM` | 出貨/銷售單明細 | CRUD |
| `GSALE` | 彙總銷售表頭 | R |
| `GSITEM` | 彙總銷售明細 | R |
| `RSALE` | 門市回傳銷售表頭 | R（含退貨） |
| `RSITEM` | 門市回傳銷售明細 | R |
| `AUTONUM` | 自動編號（TRN_NO） | R |

### TRN_PTYPE 出貨類型說明

| 代碼 | 說明 | 操作限制 |
|------|------|---------|
| `E` | 一般出貨（含發票） | 完整 CRUD |
| `F` | 第二型態出貨 | 完整 CRUD |
| `V` | 樣品/特殊出貨 | 完整 CRUD |
| `B` | 退回補單 | 僅建立/查詢 |
| `N` | 不開發票出貨 | 完整 CRUD |
| `C` | 現金出貨 | 完整 CRUD |

### 功能清單

#### 7.1 出貨單列表 `/sales/list`
- [ ] 分頁顯示（DataTables）
- [ ] 搜尋：單號(TRN_NO)、客戶(CUSTNO)、業務員、日期區間
- [ ] 篩選：出貨類型(TRN_PTYPE)、付款狀態(PAID_FLG)、倉庫
- [ ] 顯示彙總：總金額、已付/未付
- [ ] 批次操作：確認付款、列印

#### 7.2 新增出貨單 `/sales/create`
- [ ] 選擇客戶（GCU000 自動完成搜尋）
- [ ] 出貨類型選擇（TRN_PTYPE）
- [ ] 倉庫選擇（DPMF）
- [ ] 批量加入商品明細（SITEM）
  - [ ] 商品搜尋（PLU_CODE/名稱）
  - [ ] 數量輸入 → 自動帶入售價
  - [ ] 折扣設定
  - [ ] 小計自動計算
- [ ] 送貨資訊（地址、聯絡人）
- [ ] 備註欄位
- [ ] 儲存時：
  - [ ] 從 `AUTONUM` 取得新 TRN_NO
  - [ ] 寫入 SALE + SITEM
  - [ ] 扣減 STOCK 庫存
  - [ ] 寫入 TRANSACTION_LOG

#### 7.3 編輯出貨單 `/sales/edit/{trn_no}`
- [ ] 未配送前可修改（FLAG1 判斷）
- [ ] 修改記錄寫入 TRANSACTION_LOG

#### 7.4 出貨單詳細 `/sales/view/{trn_no}`
- [ ] 完整出貨資訊
- [ ] 出貨明細清單
- [ ] 付款狀態記錄
- [ ] 相關退貨單關聯
- [ ] 列印出貨單 / 列印收據

#### 7.5 付款確認 `/sales/payment/{trn_no}`
- [ ] 更新 SALE.PAID_FLG / PAID_AMT / PAID_DATE
- [ ] 部分付款支援

#### 7.6 銷售彙總查詢 `/sales/summary`
- [ ] GSALE + GSITEM 查詢
- [ ] 按商品/客戶/日期/業務員維度彙總
- [ ] 圖表視覺化（Chart.js）

#### 7.7 門市回傳資料 `/sales/store-report`
- [ ] RSALE + RSITEM 查詢
- [ ] 各門市銷售回傳狀況

---

## Module 08 — 退貨管理

> ⚠️ **家紡03** 無退貨業務資料（RIITEM/RIMP 為空），此模組在03公司介面隱藏

### 涉及資料表

| 資料表 | 中文說明 | 操作 |
|--------|---------|------|
| `RSALE` | 退貨/回傳表頭 | CRUD |
| `RSITEM` | 退貨/回傳明細 | CRUD |
| `RIITEM` | 進貨退出明細（退廠） | CRUD |
| `RIMP` | 進貨退出表頭（退廠） | CRUD |

### 功能清單

#### 8.1 客戶退貨 `/returns/customer`
- [ ] 退貨單列表（RSALE WHERE TRN_PTYPE='F'）
- [ ] 新增退貨單（必須關聯原出貨單 FROM_NO）
- [ ] 退貨商品明細（RSITEM）
- [ ] 退貨後自動增加 STOCK 庫存
- [ ] 退貨原因分類（退款/換貨/瑕疵）

#### 8.2 退廠管理 `/returns/vendor`（01/02公司）
- [ ] 退廠單列表（RIMP）
- [ ] 新增退廠單（必須關聯進貨單）
- [ ] 退廠明細（RIITEM）
- [ ] 退廠後自動扣減 STOCK

---

## Module 09 — 報表中心

### 涉及資料表

主要為跨表統計查詢，不直接操作單一資料表

### 功能清單

#### 9.1 銷售報表 `/report/sales`

| 報表名稱 | 資料來源 | 維度 |
|---------|---------|------|
| 銷售月報 | SALE + SITEM | 月份、商品群組 |
| 銷售業務報告 | SALE | 業務員(SALE_CODE) |
| 銷售客戶排行 | SALE + GCU000 | 客戶消費金額 |
| 商品銷售排行 | SITEM + PRODUCT | 商品銷售數量/金額 |
| 出貨類型分析 | SALE.TRN_PTYPE | 各類型佔比 |

#### 9.2 採購報表 `/report/purchase`

| 報表名稱 | 資料來源 | 維度 |
|---------|---------|------|
| 採購月報 | GPO050/051 | 月份、廠商 |
| 廠商採購排行 | GPO051 + PVM000 | 廠商採購金額 |
| 進貨驗收狀況 | IMPORT + GPO050 | 訂單 vs 到貨對比 |

#### 9.3 庫存報表 `/report/stock`

| 報表名稱 | 資料來源 | 維度 |
|---------|---------|------|
| 庫存現況 | STOCK + PRODUCT | 商品群組、倉庫 |
| 庫存異動月報 | GINVMN | 月份 |
| 低庫存警示 | STOCK | 低於安全庫存 |

#### 9.4 三公司整合報表 `/report/compare`

| 報表名稱 | 資料來源 |
|---------|---------|
| 三公司銷售對比 | FLOW1+2+3 各自 SALE |
| 三公司客戶分佈 | FLOW1+2+3 各自 GCU000 |
| 三公司庫存對比 | FLOW1+2+3 各自 STOCK |

#### 9.5 報表匯出
- [ ] 全部報表支援 Excel 匯出（`.xlsx`）
- [ ] 部分支援 PDF 列印

---

## Module 10 — 系統管理

### 涉及資料表

| 資料表 | 中文說明 | 操作 |
|--------|---------|------|
| `USERS` | 使用者主檔 | CRUD |
| `SYS_ROLES` | 角色 | CRUD |
| `SYS_ROLEGROUPS` | 角色群組 | CRUD |
| `SYS_ROLEGROUPS_D` | 角色群組明細 | CRUD |
| `SYS_MODULES` | 系統模組 | R |
| `SYS_MODULE_SEC_H` | 模組安全設定表頭 | CRUD |
| `SYS_MODULE_SEC_D` | 模組安全設定明細 | CRUD |
| `SYS_MODULE_SECROLE` | 模組角色安全 | CRUD |
| `SYS_PARAMS` | 系統參數 | CRUD |
| `TRANSACTION_LOG` | 操作記錄 | R |
| `SIMPLEREPORTLOG` | 報表記錄 | R |

### 功能清單

#### 10.1 使用者管理 `/system/users`
- [ ] 使用者 CRUD
- [ ] 指派角色
- [ ] 啟用/停用帳號
- [ ] 重設密碼

#### 10.2 角色管理 `/system/roles`
- [ ] 角色 CRUD（SYS_ROLES）
- [ ] 角色群組 CRUD（SYS_ROLEGROUPS + D）
- [ ] 角色模組權限設定（SYS_MODULE_SEC_*）
  - [ ] 可讀(R) / 可寫(W) / 可刪(D) 細項控制

#### 10.3 系統參數 `/system/params`
- [ ] SYS_PARAMS 瀏覽與修改
- [ ] 按分類(SYS_PARAMKIND)顯示
- [ ] 敏感參數需超級管理員權限

#### 10.4 操作日誌 `/system/logs`
- [ ] TRANSACTION_LOG 唯讀查詢
- [ ] 篩選：使用者、模組、日期、操作類型
- [ ] 報表執行記錄（SIMPLEREPORTLOG）

---

## Module 11 — 基礎資料維護

### 涉及資料表

| 資料表 | 中文說明 | 操作 |
|--------|---------|------|
| `AREA` | 地區主檔 | CRUD |
| `BAS_BANK2` | 銀行資料 | CRUD |
| `BAS_UNIT` | 計量單位 | CRUD |
| `BAS_PTYPE` | 商品類型 | CRUD |
| `BAS_PRICE` | 基礎定價 | CRUD |
| `BAS_EMP` | 員工資料 | CRUD |
| `CODE` | 系統代碼 | CRUD |
| `DPMF` | 倉庫/門市主檔 | CRUD（已在庫存模組） |
| `CLEVEL` | 客戶等級 | CRUD（已在客戶模組） |

### 功能清單

- [ ] 地區管理（AREA）：省市/縣市/地區三層架構
- [ ] 銀行資料（BAS_BANK2）：銀行名稱、代碼、分行
- [ ] 計量單位（BAS_UNIT）：個、打、箱 等
- [ ] 商品類型（BAS_PTYPE）
- [ ] 員工主檔（BAS_EMP）：姓名、部門、職稱
- [ ] 系統代碼（CODE）：各類代碼維護介面

---

## 共用元件規格

### UI 共用元件

#### 列表頁標準元件
```
- 麵包屑導覽（公司名稱 > 模組 > 功能）
- 搜尋列（即時搜尋）
- 篩選器（折疊式）
- DataTables 表格（排序/分頁/顯示筆數）
- 操作按鈕欄（檢視/編輯/刪除）
- 批次操作列
- 匯出按鈕
```

#### 表單標準元件
```
- 必填欄位標示（紅色星號）
- 即時驗證提示
- 儲存/取消/刪除按鈕
- 關聯資料下拉（AJAX 搜尋）
- 日期選擇器（Flatpickr）
- 金額欄位（千分位格式）
- CRUD 操作後 Toast 通知
```

### 後端共用函式

```php
// 通用查詢分頁
function paginate(PDO $db, string $sql, array $params, int $page, int $perPage): array

// 統一回應格式
function jsonResponse(bool $success, $data = null, string $message = ''): void

// 操作記錄
function writeTransactionLog(PDO $db, string $action, string $table, string $record_id, array $before, array $after): void

// 自動取號
function getAutoNum(PDO $db, string $type, string $date): string

// 軟刪除
function softDelete(PDO $db, string $table, string $pkColumn, $pkValue, string $flagColumn = 'FLAG1'): bool
```

---

## API 設計規範

### RESTful 端點格式

```
GET    /api/v1/{company}/{resource}           列表
GET    /api/v1/{company}/{resource}/{id}      單筆
POST   /api/v1/{company}/{resource}           新增
PUT    /api/v1/{company}/{resource}/{id}      修改
DELETE /api/v1/{company}/{resource}/{id}      刪除

範例：
GET  /api/v1/01/products?page=1&search=棉被    金草商品列表
POST /api/v1/02/sales                          金永盛新增出貨單
PUT  /api/v1/03/customers/C001                 家紡更新客戶
```

### 統一回應格式

```json
{
  "success": true,
  "message": "操作成功",
  "data": { ... },
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1234,
    "total_pages": 25
  }
}
```

### 錯誤回應格式

```json
{
  "success": false,
  "message": "商品代碼已存在",
  "errors": {
    "PLU_CODE": "此商品代碼已被使用"
  }
}
```

### 驗證與安全

- 所有 API 需 Session 驗證（`Authorization: Bearer {token}`）
- POST/PUT/DELETE 需 CSRF Token
- SQL 查詢全部使用 Prepared Statement，禁止字串拼接
- 輸出統一經 `htmlspecialchars()` 過濾（防 XSS）

---

## 開發時程規劃

### Sprint 規劃（每 Sprint 2 週）

| Sprint | 目標 | 包含模組 | 完成標準 |
|--------|------|---------|---------|
| **Sprint 1** | 基礎建設 | 設定/路由/連線/登入 | 三公司登入切換正常 |
| **Sprint 2** | 商品主檔 | Module 02 商品管理 | 商品 CRUD + 庫存查詢 |
| **Sprint 3** | 客戶主檔 | Module 05 客戶管理 | 客戶 CRUD + 歷程查詢 |
| **Sprint 4** | 採購管理 | Module 04 廠商 + Module 06 採購 | 採購訂單 CRUD |
| **Sprint 5** | 銷售核心 | Module 07 出貨銷售 | 出貨單 CRUD + 庫存連動 |
| **Sprint 6** | 退貨/庫存 | Module 03 庫存 + Module 08 退貨 | 調整單/退貨單 CRUD |
| **Sprint 7** | 報表中心 | Module 09 報表 | 8 張核心報表完成 |
| **Sprint 8** | 系統管理 | Module 10+11 | 權限/參數/基礎資料 |
| **Sprint 9** | 整合測試 | 全模組 | 三公司全功能測試 |
| **Sprint 10** | 部署上線 | Ubuntu 部署 | 正式環境驗收 |

### 開發環境 vs 正式環境

| 階段 | 主機 | 資料庫 | 說明 |
|------|------|--------|------|
| **開發** | 本機 Windows (C:\Apache24) | 192.168.50.207 備份庫 | 目前開發環境 |
| **測試** | 本機 or 同 Ubuntu | 同 192.168.50.207 備份庫 | 功能驗證 |
| **正式** | Ubuntu 192.168.50.207 | 從現有系統重新匯出新庫 | 上線後資料最新 |

### 上線部署計畫

```
1. 開發完成後，在 Ubuntu 上安裝 Apache + PHP
2. 從現有 ERP 系統匯出最新資料（FULL BACKUP）
3. 匯入 Ubuntu SQL Server（建立正式庫）
4. 部署 PHP 程式到 /var/www/html/erp/
5. 設定 SSL 憑證（Let's Encrypt）
6. 設定防火牆（僅開放 80/443，關閉 1433 對外）
7. UAT 驗收測試
8. 正式上線
```

---

## 變更記錄

| 日期 | 版本 | 變更內容 | 變更人 |
|------|------|---------|--------|
| 2026-02-22 | v1.0 | 初版建立，完成三公司/11模組基礎規劃 | — |

---

## 待確認項目（Action Items）

> 以下項目需要與業務方確認後更新至對應章節

- [ ] **USERS 欄位結構**：確認帳號/密碼/角色欄位名稱（執行 SQL 後補充至 Module 01）
- [ ] **PRODUCT 欄位結構**：確認商品關鍵欄位（補充至 Module 02）
- [ ] **SALE 付款狀態**：`PAID_FLG` 值域定義（已付/部分/未付）
- [ ] **TRN_PTYPE 完整定義**：各出貨類型中文說明與業務規則
- [ ] **三公司帳號共用？**：登入時是否需要在三庫各自建立帳號
- [ ] **網際網路存取**：是否有固定 IP 或需 DDNS？SSL 憑證申請對象？
- [ ] **Excel 匯出格式**：是否需要特定欄位排列或樣式？
- [ ] **列印格式**：出貨單/採購單列印版面是否有現成樣板？

---

*📌 本文件持續更新，功能變更時請直接修改此文件對應章節，並更新「變更記錄」表格*