From cd7feec38a467797c6cf01c570f857ed07c9a156 Mon Sep 17 00:00:00 2001
From: Chris <wtc.justin82@gmail.com>
Date: Fri, 3 Apr 2026 15:50:19 +0800
Subject: [PATCH] docs: update env workflow and role_code contracts

---
 backend                      | 2 +-
 docs/DB_SCHEMA.md            | 2 ++
 docs/INTERNAL_API_HANDOFF.md | 2 ++
 docs/LOCAL_DEV_RUNBOOK.md    | 4 +++-
 docs/VPS_DEPLOY_RUNBOOK.md   | 3 +--
 frontend                     | 2 +-
 6 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/backend b/backend
index 94cec74..405000d 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 94cec746cb116078adfbd46760ced841c3e4e9de
+Subproject commit 405000ded5f40dc67e7f1c63f5759740ea223fc1
diff --git a/docs/DB_SCHEMA.md b/docs/DB_SCHEMA.md
index b906b4f..05cf9e6 100644
--- a/docs/DB_SCHEMA.md
+++ b/docs/DB_SCHEMA.md
@@ -34,6 +34,7 @@
 ## 4) roles
 - `id` UUID PK default `gen_random_uuid()`
 - `role_key` TEXT NOT NULL UNIQUE
+- `role_code` TEXT NOT NULL（語意代碼，建議格式：`<system>:<module>:<action>`，例如 `mkt:marketing_card:edit`）
 - `system_id` UUID NOT NULL FK -> `systems(id)` ON DELETE CASCADE
 - `name` TEXT NOT NULL
 - `description` TEXT
@@ -41,6 +42,7 @@
 - `created_at` TIMESTAMPTZ NOT NULL default `now()`
 - `updated_at` TIMESTAMPTZ NOT NULL default `now()`
 - UNIQUE(`system_id`, `name`)
+- UNIQUE(`system_id`, `role_code`)
 
 ## 5) site_roles
 - `id` UUID PK default `gen_random_uuid()`
diff --git a/docs/INTERNAL_API_HANDOFF.md b/docs/INTERNAL_API_HANDOFF.md
index 60543a7..c4c9077 100644
--- a/docs/INTERNAL_API_HANDOFF.md
+++ b/docs/INTERNAL_API_HANDOFF.md
@@ -36,6 +36,7 @@
       "system_key": "SY20260402X0001",
       "system_name": "Marketing",
       "role_key": "RL20260402X0002",
+      "role_code": "mkt:marketing_card:edit",
       "role_name": "campaign_edit"
     }
   ]
@@ -45,3 +46,4 @@
 ## 注意事項
 - 不提供 user direct role 寫入 API。
 - User 最終角色由 `user_sites` + `site_roles` 推導。
+- `role_key` 是唯一識別鍵；業務語意解析請使用 `role_code`。
diff --git a/docs/LOCAL_DEV_RUNBOOK.md b/docs/LOCAL_DEV_RUNBOOK.md
index 5f6fb92..96c1f95 100644
--- a/docs/LOCAL_DEV_RUNBOOK.md
+++ b/docs/LOCAL_DEV_RUNBOOK.md
@@ -30,9 +30,11 @@ cd frontend
 npm install
 npm run dev
 ```
+- 本地開發固定使用 `frontend/.env.development`。
+- production build 讀取 `frontend/.env.production`。
 - 專案路徑：[frontend](../frontend)
 
-## 4) 必要環境變數（[backend/.env](../backend/.env)）
+## 4) 必要環境變數（[backend/.env.development](../backend/.env.development)）
 - `KEYCLOAK_BASE_URL`
 - `KEYCLOAK_REALM`
 - `KEYCLOAK_CLIENT_ID`
diff --git a/docs/VPS_DEPLOY_RUNBOOK.md b/docs/VPS_DEPLOY_RUNBOOK.md
index 55e76da..4733a10 100644
--- a/docs/VPS_DEPLOY_RUNBOOK.md
+++ b/docs/VPS_DEPLOY_RUNBOOK.md
@@ -63,9 +63,8 @@ docker compose down
 ## 3) 前端部署（Nginx）
 ```bash
 cd /opt/member-platform/frontend
-cp .env.example .env
 ```
-設定：
+production build 會自動讀取 `.env.production`，請先確認設定：
 ```env
 VITE_API_BASE_URL=https://memberapi.ose.tw
 ```
diff --git a/frontend b/frontend
index 1121c50..9de368a 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 1121c50af8965afa7c75ded163ca0b8010c07791
+Subproject commit 9de368ae573cac2500af8862d97d80f47353a939