From 773396fc90e412ad98c561f846c0c90aa1547494 Mon Sep 17 00:00:00 2001 From: sky121113 Date: Thu, 12 Mar 2026 17:42:57 +0800 Subject: [PATCH] =?UTF-8?q?[REFACTOR]=20=E5=AF=A6=E4=BD=9C=E5=81=B4?= =?UTF-8?q?=E9=82=8A=E6=AC=84=E8=88=87=E5=84=80=E8=A1=A8=E6=9D=BF=E5=A4=9A?= =?UTF-8?q?=E8=AA=9E=E7=B3=BB=E5=8C=96=EF=BC=8C=E4=BF=AE=E5=BE=A9=20UI=20?= =?UTF-8?q?=E4=BD=8D=E7=A7=BB=E8=88=87=E6=A8=A3=E5=BC=8F=E5=84=AA=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/rules/api-rules.md | 220 +++--------- .agents/rules/framework.md | 13 +- app/Http/Controllers/ProfileController.php | 12 +- .../Controllers/System/LanguageController.php | 25 ++ app/Http/Kernel.php | 1 + app/Http/Middleware/SetLocale.php | 27 ++ app/Models/System/User.php | 8 + app/Models/UserLoginLog.php | 27 ++ config/app.php | 2 +- ...12_085534_create_user_login_logs_table.php | 31 ++ docs/architecture_plan.md | 80 +---- docs/b010_technical_spec.md | 50 +-- docs/b017_technical_spec.md | 24 +- docs/b055_technical_spec.md | 54 +-- docs/b220_technical_spec.md | 31 +- docs/b600_technical_spec.md | 20 +- docs/b601_technical_spec.md | 8 +- docs/b602_technical_spec.md | 25 +- docs/b650_technical_spec.md | 2 +- docs/b710_technical_spec.md | 2 +- docs/development_schedule.md | 250 +++++++++++++ lang/en/auth.php | 20 ++ lang/en/pagination.php | 19 + lang/en/passwords.php | 22 ++ lang/en/validation.php | 200 +++++++++++ lang/ja.json | 150 ++++++++ lang/zh_TW.json | 150 ++++++++ lang/zh_TW/auth.php | 20 ++ lang/zh_TW/pagination.php | 19 + lang/zh_TW/passwords.php | 22 ++ lang/zh_TW/validation.php | 200 +++++++++++ package-lock.json | 12 +- package.json | 1 + resources/css/app.css | 16 + resources/views/admin/dashboard.blade.php | 328 +++++++++++------- resources/views/layouts/admin.blade.php | 88 ++++- .../layouts/partials/sidebar-menu.blade.php | 178 +++++----- resources/views/profile/edit.blade.php | 30 +- .../partials/delete-user-form.blade.php | 39 ++- .../profile/partials/login-history.blade.php | 46 +++ .../partials/update-password-form.blade.php | 40 ++- .../update-profile-information-form.blade.php | 63 ++-- routes/web.php | 3 + 43 files changed, 1928 insertions(+), 650 deletions(-) create mode 100644 app/Http/Controllers/System/LanguageController.php create mode 100644 app/Http/Middleware/SetLocale.php create mode 100644 app/Models/UserLoginLog.php create mode 100644 database/migrations/2026_03_12_085534_create_user_login_logs_table.php create mode 100644 docs/development_schedule.md create mode 100644 lang/en/auth.php create mode 100644 lang/en/pagination.php create mode 100644 lang/en/passwords.php create mode 100644 lang/en/validation.php create mode 100644 lang/ja.json create mode 100644 lang/zh_TW.json create mode 100644 lang/zh_TW/auth.php create mode 100644 lang/zh_TW/pagination.php create mode 100644 lang/zh_TW/passwords.php create mode 100644 lang/zh_TW/validation.php create mode 100644 resources/views/profile/partials/login-history.blade.php diff --git a/.agents/rules/api-rules.md b/.agents/rules/api-rules.md index fbd203d..af9fe18 100644 --- a/.agents/rules/api-rules.md +++ b/.agents/rules/api-rules.md @@ -2,208 +2,82 @@ trigger: always_on --- -# Backend API Specification (backend.md) +# Backend API Specification (api-rules.md) --- -## 目標範圍 +## 🚀 1. 目標範圍與分類 -* 使用 Laravel (RESTful API) -* 資料庫:MySQL(migration + seeder) -* 提供給現有 Android 團隊的完整 API 規格(JSON 格式) +本系統 API 分為兩大類,遵循不同的設計慣例: + +* **Admin/Web API (`/api/v1/...`)**: 供後台管理介面、APP UI 使用。遵循標準 RESTful 與 JSON 結構。 +* **Machine IoT API (`/api/app/...`)**: 供販賣機、計時器等硬體端點使用。需相容既有 PDF 規格(如 B010, B600),欄位命名多為 `req1`, `req2` 或特定縮寫。 --- -## 認證與安全 +## 🔐 2. 認證與安全性 -* 採用 JWT 或 Laravel Sanctum -* 所有需要授權的 API 回傳 401/403 規範 -* Error 格式: - -```json -{ - "success": false, - "code": 401, - "message": "Unauthorized", - "errors": null -} -``` +* **Admin API**: 採用 **Laravel Sanctum (Session/Token)** 認證。 +* **Machine IoT API**: + * **核心機制**: 必須在 Header 帶入 `Authorization: Bearer ` 進行身份驗證。 + * **Phase 1 (兼容模式)**: 若為相容既有機動硬體,可暫時接受 Request 包含 `key` 欄位,但後端應過渡至 Bearer 驗證。 + * **安全性強化**: 改用每台機台專屬的 `api_token` (透過 B010 初始化或派發),並配合 `serial_no` (即 `workid`) 進行資料歸屬權驗證。 +* **傳輸安全**: 必須強制使用 **HTTPS**。 --- -## 一般回應格式 - -成功: +## 📦 3. 回應格式規範 +### 3.1 標準回應 (Admin/Web API) ```json { "success": true, "code": 200, "message": "OK", - "data": { } + "data": { ... } } ``` -錯誤:同上 Error 範例 +### 3.2 IoT 指令回應 (B010/B055 等) +機台端通常透過 response 的 `status` 欄位或特定的 `message` 字串來執行動作: +* **成功但有指令**: `{"status": "49", "message": "reload B017"}` +* **純資料回傳**: 直接返回對象陣列或 PDF 定義的欄位。 --- -## API 清單(建議先開發順序) +## 🛠️ 4. 主要 Endpoints 與命名慣例 -1. Auth (登入/登出/註冊/權杖) -2. User / Profile -3. Device / Machine (機台管理、狀態回傳、日誌) -4. Order / ShoppingCart(若需) -5. Notification / Push 訊息 -6. Activity / Campaign -7. Report / Analytics -8. Admin CRUD for resources +### 4.1 管理類 (Admin UI) +* `GET /api/v1/users`: 管理員清單 +* `GET /api/v1/machines`: 機台清單 +* `PUT /api/v1/machines/{id}`: 更新機台參數 +* 遵循 **kebab-case** 路由與 **snake_case** JSON 欄位。 + +### 4.2 終端類 (IoT / Machine) — 須嚴格遵守 PDF 規格 +* **API 識別碼 (workid)**: URL 中的 `{workid}` 參數固定為該 API 的功能代碼 (如 `B010`, `B017`, `B600`),不隨機台改變。 +* **機台識別方式**: + 1. **Header**: 透過 `Authorization: Bearer ` 識別。 + 2. **Request Body**: 透過 `machine` 或 `serial_no` 等欄位識別具體機台。 +* **主要 Endpoint 範例**: + * **心跳上報 (B010)**: `POST /api/app/machine/status/B010` + * **交易回傳 (B600)**: `POST /api/app/B600` (Body 欄位 `req2` 為機台編號) + * **貨道庫存 (B017)**: `POST /api/app/machine/reload_msg/B017` + * **遠端出貨 (B055)**: `POST /api/app/machine/dispense/B055` --- -## 主要 Endpoints 範例 +## ⚡ 5. 高併發處理與隊列 -### 1) Auth +為了系統穩定性,以下 API **嚴禁直寫資料庫**,必須進入 **Redis Queue** 異步處理: +1. **B010**: 心跳上傳(每 5-10 秒一次)。 +2. **B600 / B602**: 交易與出貨紀錄。 +3. **B220**: 零錢機庫存變動。 +4. **B710**: 計時器狀態同步。 -* POST /api/v1/auth/login - - * request: - - ```json - {"email":"user@example.com","password":"pa55"} - ``` - - * response: - - ```json - {"success":true,"code":200,"data":{"token":"...","user":{"id":1,"name":"..."}}} - ``` - -* POST /api/v1/auth/logout - - * header: Authorization: Bearer - * response: 200 - -* POST /api/v1/auth/refresh +後端應立即回傳 `202 Accepted` 或業務定義的成功碼,由 Job 背景完成數據持久化。 --- -### 2) User / Profile - -* GET /api/v1/users/{id} -* PUT /api/v1/users/{id} -* GET /api/v1/users (admin) - -Request / Response 均採 JSON,個資欄位請遵守最小授權原則。 - ---- - -### 3) Machine (機台) - -* **GET /api/v1/machines** - * Params: page, per_page, status -* **GET /api/v1/machines/{id}** -* **POST /api/v1/machines/{id}/logs** (IoT) - * 用於機台回傳日誌,後端固定走 **Redis Queue 異步寫入**。 - * 回傳 `202 Accepted` 表示任務已接收,由 `ProcessMachineLog` 背景處理。 - * Request Example: - ```json - { - "level": "info", - "message": "Temperature stabilized at 23C", - "context": { "temp": 23.0 } - } - ``` - ---- - -### 4) Orders / ShoppingCart - -* POST /api/v1/cart/add -* GET /api/v1/cart -* POST /api/v1/orders -* GET /api/v1/orders/{id} - -支付與第三方串接請另行設計 callback endpoint。 - ---- - -### 5) Notification - -* POST /api/v1/notifications/send (admin) -* GET /api/v1/notifications (user) - -Payload for push could include: title, body, target_user_ids, data - ---- - -### 6) Activity / Campaign - -* GET /api/v1/campaigns -* POST /api/v1/campaigns -* PUT /api/v1/campaigns/{id} - ---- - -### 7) Report / Analytics - -* GET /api/v1/reports/machines/summary?from=YYYY-MM-DD&to=YYYY-MM-DD -* GET /api/v1/reports/sales/summary - -Response should include aggregated numbers and paginated lists when needed. - ---- - -## Database 基本表(初步) - -* users -* roles -* machines -* machine_logs -* orders -* order_items -* carts -* notifications -* campaigns -* activity_logs -* translations (i18n) - -(每張表建議 migration 欄位、index、外鍵,請於開發前定稿) - ---- - -## API 規格輸出 - -* 建議產出 Swagger (OpenAPI 3.0) 與 Postman Collection -* 每個 endpoint 必要欄位、範例、error code、rate limit - ---- - -## 測試建議 - -* Unit tests:Laravel Feature tests for API -* Contract tests:與 Android 團隊一同建立 contract tests(或使用 Postman tests) - ---- - -## 部署與運營 - -* 建議使用 queue 與 cache(Redis)處理非同步任務 -* Logging: Sentry or similar -* 定期備份 MySQL - ---- - -## 交付項目清單 - -1. 完整 Laravel 專案(註冊、登入、ACL) -2. MySQL migration + seeders -3. Swagger/OpenAPI 文件 -4. Postman Collection -5. 後台管理系統(Star Cloud) -6. 測試報告 -7. 部署腳本與上線說明 - ---- - -*註:本檔為初版 backend.md,若要我把 Excel 的每一列功能自動轉成對應的 API endpoint(含 request/response 範例),我可以直接在此檔案中展開更詳細的 endpoint 清單。* \ No newline at end of file +## 📄 6. 交付與文件 +* **OpenAPI**: 應區分 `admin.yaml` 與 `iot.yaml`。 +* **Postman**: 提供帶有環境變數(機台金鑰、Base URL)的 Collection。 diff --git a/.agents/rules/framework.md b/.agents/rules/framework.md index 6d54f56..2dd951a 100644 --- a/.agents/rules/framework.md +++ b/.agents/rules/framework.md @@ -52,15 +52,24 @@ trigger: always_on * 優先使用 **Alpine.js** (`x-data`, `x-show`, `@click` 等) 在 HTML 標籤內完成簡單的 DOM 狀態切換與互動邏輯。 * 避免在 Blade 內撰寫冗長的 ` -@endsection diff --git a/resources/views/layouts/admin.blade.php b/resources/views/layouts/admin.blade.php index 0754491..8578075 100644 --- a/resources/views/layouts/admin.blade.php +++ b/resources/views/layouts/admin.blade.php @@ -39,7 +39,7 @@ x-cloak> -
+