# LazyPro

Built by Pure Vibe Coding

### Invoice

輕鬆自在開發票

* [快速開始](/invoice/01-quick-start)
* [使用 AI 轉換訂單資料](/invoice/02-ai-convert)
* [JSON 檔案格式](/invoice/03-json-format)
* [測試環境限制](/invoice/04-test-limitations)
* [查看全部 →](/invoice/00-overview)

### PageSpeed

天下網頁,唯快不破

* [快速開始](/pagespeed/01-quick-start)
* [上傳資料](/pagespeed/02-upload-data)
* [JSON 檔案格式](/pagespeed/03-json-format)
* [Pro Mode 切換](/pagespeed/04-pro-mode-toggle)
* [查看全部 →](/pagespeed/00-overview)


# 產品介紹

> 輕鬆自在開發票

Lazy Invoice 是統一介面的電子發票開立工具，支援台灣五大加值中心，透過 AI 協助將訂單資料轉換為 JSON 格式，批次開立發票。

## 快速開始

### 線上使用

訪問 <https://invoice.lazypro.app>

### 使用流程

1. 準備訂單資料（Excel、CSV、文字等）
2. 使用 AI 工具轉換為 JSON 格式（參考 [AI 轉換指南](/invoice/02-ai-convert)）
3. 點擊上傳按鈕，選擇 JSON 檔案
4. 系統自動偵測平台，點擊 **Start** 開始批次開立
5. 查看開立結果（成功/失敗狀態即時顯示）

## 主要功能

### 五大平台支援

支援台灣五大電子發票加值中心：ECPay、ezPay、O'Pay、SmilePay、Amego。

上傳 JSON 後系統會自動偵測平台並切換，無需手動選擇。

### AI 輔助轉換

使用 AI 工具（如 Claude、ChatGPT）將訂單資料轉換為標準 JSON 格式。

詳見：[使用 AI 轉換訂單資料](/invoice/02-ai-convert)

### 批次開立

一次上傳多筆發票資料，系統自動批次開立，節省重複操作時間。

詳見：[JSON 檔案格式](/invoice/03-json-format)

### 雙模式切換

* **測試模式**：使用測試環境，不會實際開立發票
* **正式模式**：實際開立發票（需在 JSON 中設定 `production: true`）

## 常見問題

### 支援哪些加值中心？

目前支援：ECPay、ezPay、O'Pay、SmilePay、Amego 五家。

### API 金鑰會被記錄嗎？

不會。所有 API 金鑰都在你的 JSON 檔案中，系統不會儲存。

### 測試模式有限制嗎？

測試模式使用加值中心的測試環境，各平台有不同限制。

詳見：[測試環境限制](/invoice/04-test-limitations)

### 離線使用可以嗎？

可以。若對線上版有隱私疑慮，可下載專案在本機 PHP 環境執行。


# 快速開始

## 使用方式

1. 上傳發票資料：點擊上傳按鈕，選擇包含憑證的 JSON 檔案
2. 自動切換平台：系統自動偵測並切換到對應平台
3. 預覽與編輯：檢視發票列表，可新增、修改、刪除
4. 批次開立：點擊 Start 開始批次處理
5. 查看結果：即時顯示成功/失敗狀態與統計

## 線上使用

訪問 <https://invoice.lazypro.app>

## 離線使用

若對線上版處理發票資料有隱私疑慮，可下載專案在本機 PHP 環境執行，資料完全私人化不外傳。

## 準備 JSON 資料

推薦使用 AI 工具（如 Claude 或 ChatGPT）將訂單資料轉換為所需格式。

完整轉換指南：[AI-PROMPT-GUIDE.md](https://github.com/LazyProApp/Invoice/blob/main/AI-PROMPT-GUIDE.md)

參考範本：`invoice-templates/` 目錄提供各平台完整 JSON 範本


# 使用 AI 轉換訂單資料

Lazy Invoice 接受標準化的 JSON 格式。推薦使用 AI 工具（如 Claude 或 ChatGPT）將訂單資料轉換為所需格式。

## 轉換流程

1. 準備訂單資料（Excel、CSV、文字等）
2. 開啟 AI 工具
3. 上傳或貼上訂單資料
4. 提供轉換指令
5. 複製 AI 輸出的 JSON 並儲存為檔案

## 完整轉換指南

詳細指南請參閱專案根目錄：[AI-PROMPT-GUIDE.md](https://github.com/LazyProApp/Invoice/blob/main/AI-PROMPT-GUIDE.md)

包含：

* 各平台 JSON 範本與欄位說明
* 載具類型與稅率對照表
* AI 轉換提示詞範例
* 特殊稅率發票處理方式

參考範本：`invoice-templates/` 目錄提供各平台完整 JSON 範本（包含所有稅率類型範例）


# JSON 檔案格式

## 檔案結構

```json
{
  "production": false,
  "credential": {
    "MerchantID": "商店代號",
    "HashKey": "加密金鑰",
    "HashIV": "加密向量"
  },
  "invoices": [
    {
      "RelateNumber": "訂單編號",
      "CustomerName": "客戶名稱",
      "CustomerEmail": "客戶信箱",
      "Print": "0",
      "TaxType": "1",
      "SalesAmount": 1000,
      "Items": [
        {
          "ItemName": "商品名稱",
          "ItemCount": 1,
          "ItemWord": "個",
          "ItemPrice": 1000,
          "ItemAmount": 1000
        }
      ]
    }
  ]
}
```

## 主要欄位說明

### production

* **型態**：布林值
* **說明**：`true` 為正式模式，`false` 為測試模式
* **預設值**：`false`

### credential

* **型態**：物件
* **說明**：加值中心的 API 憑證
* **必填欄位**：
  * `MerchantID`：商店代號
  * `HashKey`：加密金鑰
  * `HashIV`：加密向量

### invoices

* **型態**：陣列
* **說明**：要開立的發票列表
* **每筆發票包含**：
  * 訂單資訊（RelateNumber、CustomerName 等）
  * 稅額設定（TaxType、SalesAmount）
  * 商品明細（Items 陣列）

## 範本檔案

各平台的完整範本位於專案根目錄：

```
invoice-templates/
├── ecpay.json      # 綠界科技（含所有稅率範例）
├── ezpay.json      # 藍新金流
├── opay.json       # 歐付寶
├── smilepay.json   # 訊航科技
└── amego.json      # 雲端行動
```

## 欄位差異

不同平台的欄位名稱可能略有差異，請參考對應平台的範本檔案。


# 測試環境限制

## 概述

各平台測試環境存在已知限制，可能導致部分發票開立失敗。這些限制僅存在於測試環境，正式環境無此問題。

## ECPay（綠界科技）

### 混合稅率限制

* **問題**：測試環境 08 字軌配額有限
* **錯誤代碼**：12001072
* **影響**：混合稅率發票（TaxType=9）可能因字軌用完而失敗
* **解決方式**：
  * 正式環境無此限制
  * 或聯繫 ECPay 申請測試環境字軌配額

## SmilePay（訊航科技）

### 混合稅率限制

* **問題**：TaxType=9 僅限訊息 C0401 使用
* **錯誤代碼**：-100611
* **影響**：一般 API 不支援混合稅率
* **解決方式**：正式環境無此限制

### 特種稅率限制

* **問題**：測試環境無特種稅率字軌
* **錯誤代碼**：-10071
* **影響**：特種稅率發票無法在測試環境開立
* **解決方式**：正式環境無此限制

### 建議測試統編

使用測試統編 `80129529` 可提高成功率。

## O'Pay（歐付寶）

### 統編白名單限制

* **問題**：僅接受特定測試統編
* **允許的統編**：
  * `12345678`
  * `53538851`
* **影響**：其他統編會自動轉換為 `12345678`
* **解決方式**：正式環境無此限制

### 字軌配額限制

測試字軌配額有限，可能用完。

## 通用限制

所有平台測試環境可能存在：

### 字軌配額限制

測試環境的發票字軌數量有限，用完後無法開立。

### 統編白名單限制

部分平台僅允許特定測試統編。

### 特殊稅率支援限制

混合稅率、特種稅率等特殊發票類型可能不支援。

### 時間限制

晚上 12 點後部分加值中心無法作廢發票（系統維護時間）。

## 成功率說明

程式碼經過完整驗證，在測試環境可用的情況下成功率可達 90% 以上。測試失敗通常是測試環境限制，非程式錯誤。

## 建議

1. 先在測試環境驗證資料格式與流程
2. 遇到測試環境限制時，確認是否為已知問題
3. 正式環境使用時無這些限制
4. 測試時使用平台建議的測試統編


# 產品介紹

> 天下網頁，唯快不破

Lazy PageSpeed 是 Google PageSpeed Insights API 的增強工具，批次分析多個網址，產生完整報告供 AI 分析。

## 快速開始

### 線上使用

訪問 <https://pagespeed.lazypro.app>

### 使用流程

1. 點擊右上角 **+ New** 新增網址（免費版最多 3 個）
2. 點擊底部 **Start** 開始分析
3. 完成後點擊 **Analyze** 查看報告
4. 使用 **Download** 下載 Markdown 報告給 AI 分析

## 主要功能

### 批次分析

一次分析多個網址，支援 Mobile 和 Desktop 兩種裝置。

詳見：[快速開始](/pagespeed/01-quick-start)

### Pro 模式

使用自己的 API Key，無網址數量限制。

詳見：[Pro Mode 切換按鈕](/pagespeed/04-pro-mode-toggle)

### 報告下載

* **Markdown 報告**：精簡格式，適合貼給 AI 分析
* **JSON 原始檔**：完整資料，可重新匯入

詳見：[下載 Markdown 報告](/pagespeed/09-download-report)、[Download 下載 JSON](/pagespeed/07-download-button)

### 報告分享

產生分享連結讓團隊協作（需設定 R2）。

詳見：[Share 分享報告](/pagespeed/06-share-button)

## 常見問題

### 免費版有限制嗎？

免費版最多分析 3 個網址。需要更多請使用 Pro 模式（需申請 Google API Key）。

### API Key 會被記錄嗎？

不會。Pro 模式直接從瀏覽器呼叫 Google API，中間沒有伺服器。

### 報告分享功能是必須的嗎？

不是。報告分享功能是選用的，需要自己設定 Cloudflare R2。

詳見：[分享功能限制](/pagespeed/10-share-limitations)


# 快速開始

## 基本流程

1. 點擊表格右上角 + New 按鈕新增網址
2. 點擊底部 Start 按鈕開始分析（最多 3 個）
3. 表格顯示分析狀態
4. 點擊表格內 Analyze 按鈕查看報告

## Pro Mode 專業模式分析流程

需要使用自己的 Google PageSpeed API Key

1. 建立包含 API Key 的 JSON 檔案
2. 點擊底部 + 按鈕上傳 JSON 檔案（自動啟用 Pro Mode）
3. 點擊表格右上角 + New 按鈕新增網址
4. 點擊底部 Start 按鈕開始分析（無數量限制）
5. 表格顯示分析狀態
6. 點擊表格內 Analyze 按鈕查看報告

## 如何申請 Google PageSpeed API Key

### 申請步驟

1. 前往 [Google Cloud Console](https://console.cloud.google.com/)
2. 建立新專案或選擇現有專案
3. 啟用 PageSpeed Insights API
4. 建立 API 金鑰（API Key）
5. 將 API Key 寫入 JSON 檔案（格式見 JSON 檔案格式章節）

### API Key 限制

* Google 提供每日 25,000 次免費查詢額度
* 超過額度需付費使用
* 建議自行監控使用量

## 如何設定 Cloudflare R2（選用）

### 用途

* 用於分享報告功能
* 報告會儲存在你自己的 R2 空間
* 不設定也可正常使用分析功能，只是無法分享

### 申請步驟

#### 步驟 1：建立 R2 Bucket

1. 登入 [Cloudflare Dashboard](https://dash.cloudflare.com/)
2. 前往「R2 Object Storage」頁面
3. 點擊「Create bucket」
4. 輸入 Bucket 名稱（例如：my-pagespeed-reports）
5. Location 選項：
   * 保持「Automatic」讓 Cloudflare 自動選擇最近的區域
   * 或選擇「Specify jurisdiction」指定區域
6. 點擊「Create bucket」完成

#### 步驟 2：建立 API Token

1. 在 R2 頁面，點擊「Manage R2 API Tokens」
2. 點擊「Create API token」
3. 選擇 Token 類型：
   * User API Token（建議）：綁定你的個人帳號
   * Account API Token：綁定整個 Cloudflare 帳號（需 Super Administrator）
4. 設定 Token：
   * Token name: `PageSpeed Reporter`（可自訂）
   * Permissions: 選擇「Object Read & Write」
   * Apply to specific buckets: 選擇剛建立的 bucket
5. 點擊「Create API Token」

#### 步驟 3：保存憑證

建立後會顯示以下資訊（**只顯示一次，務必立即複製**）：

* **Access Key ID**（客戶端 ID）
* **Secret Access Key**（客戶端密鑰）

#### 步驟 4：取得 Account ID

1. 在 Cloudflare Dashboard 任何頁面
2. 右側會顯示你的 Account ID
3. 或前往「Workers & Pages」→「Overview」查看
4. Account ID 格式：32 字元的英數字串

#### 步驟 5：填入 JSON 檔案

將這些資訊寫入 JSON 檔案的 `share_report.r2` 區塊：

```json
{
  "share_report": {
    "upload": true,
    "r2": {
      "accountId": "你的 Account ID",
      "accessKeyId": "Access Key ID",
      "secretAccessKey": "Secret Access Key",
      "bucketName": "my-pagespeed-reports"
    }
  }
}
```

### R2 免費額度

* 每月 10 GB 儲存空間
* 100 萬次上傳操作
* 1000 萬次下載操作
* 無流量費用

### 安全提醒

* **Secret Access Key 是敏感資訊**
* 不要將包含 R2 憑證的 JSON 檔案上傳到公開位置
* 不要分享給他人
* 建議定期輪換 API Token
* JSON 檔案應儲存在本機安全位置


# 上傳資料

## 功能

上傳要分析的網址或憑證，格式為 JSON

## 操作流程

1. 點擊底部輸入框左側的 + 按鈕
2. 選擇 JSON 檔案
3. 系統自動載入資料

## 上傳邏輯

系統根據 JSON 內容自動判斷處理方式：

### 情境 1：只上傳憑證（不清空現有資料）

**使用時機**：打開分享連結後，想啟用 Pro Mode 繼續分析

**JSON 內容**：

```json
{
  "credentials": {
    "api_key": "YOUR_API_KEY"
  }
}
```

**系統行為**：

* ✅ 保留現有的網址和報告
* ✅ 啟用 Pro Mode
* ✅ 可以繼續分析或新增更多網址

***

### 情境 2：上傳完整資料（清空並載入新資料）

**使用時機**：匯入新的分析專案

**JSON 內容**：

```json
{
  "credentials": {
    "api_key": "YOUR_API_KEY"
  },
  "share_report": {
    "upload": true,
    "r2": { /* R2 設定，用於分享功能，詳見下一章 */ }
  },
  "urls": [
    "https://example.com",
    "https://example.com/page2"
  ],
  "reports": {
    "https://example.com": {
      "mobile": { /* 報告資料 */ },
      "desktop": { /* 報告資料 */ }
    }
  }
}
```

**系統行為**：

* ⚠️ 清空現有的所有資料
* ✅ 載入新的網址清單
* ✅ 載入已分析的報告（若有）
* ✅ 啟用 Pro Mode（若有 API Key）

***

### 情境 3：只上傳網址（基本模式）

**使用時機**：快速分析幾個網址，使用免費配額

**JSON 內容**：

```json
{
  "urls": [
    "https://example.com",
    "https://example.com/page2"
  ]
}
```

**系統行為**：

* ⚠️ 清空現有的所有資料
* ✅ 載入新的網址清單
* ✅ 使用基本模式（最多 3 個網址）

***

## 注意事項

* ⚠️ **情境 2 和 3 會清空現有資料**：如果只想啟用 Pro Mode，使用情境 1
* ✅ **JSON 必須包含網址或憑證**：至少要有其中一項
* 💾 **分享功能設定**（`share_report`）：可選欄位，用於自動上傳報告到你的 R2 儲存空間，詳見 [JSON 檔案格式](/pagespeed/03-json-format)
* ✅ **詳細格式說明**：請參閱 [JSON 檔案格式](/pagespeed/03-json-format)


# JSON 檔案格式

> 💡 **提示**：根據使用情境，可以只包含部分欄位。詳見 [上傳資料](/pagespeed/02-upload-data) 的三種情境說明。

## 完整格式規格

```json
{
  "credentials": {
    "api_key": "你的 Google PageSpeed API Key"
  },
  "share_report": {
    "upload": false,
    "r2": {
      "accountId": "YOUR_CLOUDFLARE_ACCOUNT_ID",
      "accessKeyId": "YOUR_R2_ACCESS_KEY_ID",
      "secretAccessKey": "YOUR_R2_SECRET_ACCESS_KEY",
      "bucketName": "YOUR_R2_BUCKET_NAME",
      "autoDelete": true,
      "deleteDays": 7,
      "shareExpireDays": 7
    }
  },
  "urls": [
    "https://example.com",
    "https://example.com/page2"
  ],
  "reports": {
    "https://example.com": {
      "mobile": { /* PageSpeed 報告資料 */ },
      "desktop": { /* PageSpeed 報告資料 */ }
    }
  }
}
```

## 最小格式範例

### 只啟用 Pro Mode（不清空資料）

```json
{
  "credentials": {
    "api_key": "YOUR_API_KEY"
  }
}
```

### 只匯入網址（基本模式）

```json
{
  "urls": [
    "https://example.com"
  ]
}
```

## 欄位說明

### credentials

* `api_key`: 選填，填入後會自動啟用 Pro Mode

### share\_report

* 選填，用於分享報告功能
* 不需要分享功能可省略此區塊

#### share\_report.upload

* `true`: 啟用上傳功能，分析後自動上傳報告到你的 R2
* `false`: 停用上傳功能，即使填寫了 r2 設定也不會上傳

#### share\_report.r2

* 選填，你的 Cloudflare R2 儲存空間設定
* 只有當 `upload: true` 時才會使用
* `accountId`: Cloudflare Account ID
* `accessKeyId`: R2 API Token 的 Access Key ID
* `secretAccessKey`: R2 API Token 的 Secret Access Key
* `bucketName`: R2 Bucket 名稱
* `autoDelete`: 是否自動刪除過期報告（預設 true）
* `deleteDays`: 報告保留天數（預設 7 天）
* `shareExpireDays`: 分享連結有效天數（預設 7 天）

#### ⚠️ 重要：R2 Bucket 必須設定 CORS

使用自己的 R2 儲存時，**必須**在 R2 Bucket 設定 CORS Policy，否則瀏覽器會阻擋連線。

**設定步驟**：

1. 前往 Cloudflare Dashboard 的 R2 Bucket 設定頁面：

   ```
   https://dash.cloudflare.com/[你的 Account ID]/r2/buckets/[Bucket 名稱]/settings
   ```
2. 找到「**CORS Policy**」區塊，點擊「**Edit**」
3. 貼上以下 JSON 設定：

```json
[
  {
    "AllowedOrigins": ["*"],
    "AllowedMethods": ["GET", "PUT", "DELETE", "HEAD"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3000
  }
]
```

4. 點擊「**Save**」儲存設定

**CORS 設定說明**：

* `AllowedOrigins: ["*"]`：允許所有來源存取（生產環境建議改為特定網域，如 `["https://yourdomain.com"]`）
* `AllowedMethods`：允許的 HTTP 方法（GET、PUT、DELETE、HEAD）
* `AllowedHeaders: ["*"]`：允許所有請求標頭
* `ExposeHeaders: ["ETag"]`：允許瀏覽器讀取 ETag 標頭
* `MaxAgeSeconds: 3000`：預檢請求（preflight）的快取時間（50 分鐘）

**如果沒有設定 CORS**，匯入 JSON 時會出現：

```
Pro Mode
您上傳的設定檔中，R2 連線資訊有問題（NetworkError when attempting to fetch resource.）。
分享功能暫時無法使用，但網站分析功能不受影響唷！
```

### urls

* **必填**（除非只上傳憑證）
* 要分析的網址清單
* 上傳時會清空現有資料並載入新網址

### reports

* 選填，已經分析過的報告
* 包含手機版和桌面版的分析結果
* 格式：`{ "url": { "mobile": {...}, "desktop": {...} } }`

***

## 範例檔案

完整的範例 JSON 檔案位於專案中：

```
/url-templates/example-urls.json
```

線上檢視：[example-urls.json](https://pagespeed.lazypro.app/url-templates/example-urls.json)

此範例包含完整的欄位結構，可作為建立自己的設定檔時的參考。

***

## 使用建議

1. **首次使用**：上傳完整格式（含 `urls`）
2. **分享後繼續分析**：只上傳 `credentials`（不清空資料）
3. **切換專案**：上傳新的完整格式（會清空舊資料）
4. **匯出分享**：使用 Download 按鈕（不含憑證，安全分享）

詳細說明請參閱：[上傳資料](/pagespeed/02-upload-data)


# Pro Mode 切換按鈕

## 功能

切換專業模式，啟用自訂 API Key

## 操作流程

1. 上傳包含 API Key 的 JSON 檔案（自動啟用）
2. 點擊 Pro Mode 按鈕可切換開關

## 狀態顯示

* 啟用：按鈕高亮顯示
* 關閉：按鈕正常顯示

## Pro Mode 差異

* 基本模式：最多 3 個網址
* Pro 模式：無數量限制


# + New 新增網址

## 功能

新增待分析的網址到表格

## 操作流程

1. 點擊表格右上角 + New 按鈕
2. 輸入網址
3. 點擊 Add 確認

## 數量限制

* 基本模式：最多 3 個
* Pro 模式：無限制


# Share 分享報告

## 功能

產生分享連結，讓他人查看分析報告

## 分享內容

* 網址清單
* 分析報告（手機版和桌面版）
* 不包含 API Key

## 有效期限

分享連結有效期限：7 天


# Download 下載 JSON

## 功能

將所有資料匯出為 JSON 檔案

## 按鈕位置

表格右上角 More 選單內的 Download

## 匯出內容

表格中所有分析的報告原始檔，包含：

* 網址清單
* API Key（若有）
* 所有已分析的報告（JSON 格式）

這個 JSON 檔案可以重新上傳，恢復完整的工作狀態


# 報告內的複製功能

## 功能

複製報告內的特定資訊

## 按鈕位置

報告視窗（Dialog）內

## 複製按鈕說明

報告內共有 5 個複製按鈕：

* **頂部右上角**：複製當前版本的完整報告（Mobile 或 Desktop）
* **Performance**：複製需要改善的項目
* **Accessibility**：複製需要改善的項目
* **Best Practices**：複製需要改善的項目
* **SEO**：複製需要改善的項目

## 注意事項

頂部複製按鈕只複製當前查看的版本（Mobile 或 Desktop），不會同時複製兩個版本


# 下載 Markdown 報告

## 功能

將分析報告下載為 Markdown 格式

## 按鈕位置

表格上每個 URL 下方的 Download 按鈕

## 下載內容

該 URL 的完整分析報告，包含：

* Mobile 版本報告
* Desktop 版本報告

兩個版本會合併在同一個 .md 檔案中


# 分享功能限制

## 版本控制機制

分享功能採用版本控制設計，每次點擊 Share 按鈕會產生新的分享連結。

**注意**：報告產生後只會保留 7 天。

## 限制說明

### 上傳包含報告的 JSON

* 上傳已分析過的 JSON 檔案後，無法直接使用分享功能
* 原因：報告的上傳記錄會在匯入時清空
* 解決方式：重新分析所有網址後再分享

### 部分更新報告

* 打開分享連結後，只重新分析其中幾個網址
* 點擊 Share 會產生新的分享連結
* 新連結包含：已更新的報告（新版本） + 未更新的報告（舊版本）

### 下載的 JSON 檔案

* Download 按鈕下載的 JSON 是固定版本
* 不會隨分享連結更新而改變
* 每次下載都是當下的快照

## 建議作法

### 完整分享流程

1. 分析所有需要的網址
2. 確認所有報告都已完成
3. 點擊 Share 產生分享連結

### 更新已分享的報告

1. 打開原分享連結
2. 重新分析需要更新的網址
3. 點擊 Share 產生新的分享連結
4. 舊連結保持原始版本（歷史記錄）
5. 新連結包含最新資料