docs: rebuild documentation set for new architecture and add DB schema guide

2026-03-30 19:21:54 +08:00
parent f884f1043d
commit 37a69081e3
18 changed files with 245 additions and 916 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,29 @@
+# member.ose.tw 架構總覽
+
+## 1) 核心模型
+- 業務層級：`companies -> sites -> users`
+- 功能層級：`systems -> modules`
+- 權限核心：`permission_groups`（群組整合權限與成員）
+
+## 2) 權限規則（固定）
+- `scope` 只允許：`site`
+- `action` 只允許：`view`、`edit`
+- `view`、`edit` 可同時勾選（多選）
+- 畫面顯示格式：`公司/站台`
+
+## 3) 關聯關係（皆為多對多）
+- 群組 ⟷ 站台
+- 群組 ⟷ 系統
+- 群組 ⟷ 模組
+- 群組 ⟷ 會員
+
+## 4) 管理頁責任
+- 群組管理：群組基本資料 + 站台/系統/模組/會員 + action(view/edit)
+- 系統編輯頁：基本資料 + 所屬群組列表 + 涉及會員列表
+- 模組編輯頁：基本資料 + 所屬群組列表 + 涉及會員列表
+- 公司頁：基本資料 + 站台列表
+- 會員編輯頁：基本資料 + 所屬群組列表
+
+## 5) 本輪範圍
+- 會員細粒度直接授權先暫停
+- 最終規格書（正式對外版）延後到專案完成後再整理
--- a/docs/ARCHITECTURE_AND_CONFIG.md
+++ b/docs/ARCHITECTURE_AND_CONFIG.md
@@ -1,36 +0,0 @@
-# member 系統文件入口（Architecture & Config）
-
-## 入口說明
-這份文件是入口索引。若你只要快速開始，先看：
-1. `docs/BACKEND_BOOTSTRAP.md`
-2. `docs/BACKEND_ARCHITECTURE.md`
-3. `docs/FRONTEND_ARCHITECTURE.md`
-
-## 文件地圖
- `docs/index.md`
-  - 前端開工入口（給前端 AI 的第一份）
- `docs/BACKEND_BOOTSTRAP.md`
-  - 後端啟動步驟（環境、安裝、建表、啟動）
- `docs/BACKEND_ARCHITECTURE.md`
-  - memberapi 後端模組、資料流、API、安全策略
- `docs/FRONTEND_ARCHITECTURE.md`
-  - member 前端架構（可直接開工版）
- `docs/FRONTEND_API_CONTRACT.md`
-  - 前端 API request/response 契約
- `docs/FRONTEND_IMPLEMENTATION_CHECKLIST.md`
-  - 前端實作與交付核對清單
- `docs/TASKPLAN_FRONTEND.md`
-  - 前端任務進度與驗收條件
- `docs/TASKPLAN_BACKEND.md`
-  - 後端任務進度與驗收條件
- `backend/scripts/init_schema.sql`
-  - 一次建立完整 schema（含 `api_clients`）
- `docs/DB_SCHEMA_SNAPSHOT.md`
-  - 目前資料庫 schema 快照（欄位/索引/約束）
-
-## 目前狀態（2026-03-29）
- 後端骨架：已建立（FastAPI + SQLAlchemy）
- 核心 API：已建立（health/internal/admin）
- API key 驗證：已建立（`X-Client-Key` + `X-API-Key`）
- Authentik JWT 驗證：已建立（`/me` 路由 + JWKS 驗簽）
- Authentik Admin API（建立/更新使用者）：已建立（`/internal/authentik/users/ensure`）
--- a/docs/BACKEND_ARCHITECTURE.md
+++ b/docs/BACKEND_ARCHITECTURE.md
@@ -1,52 +0,0 @@
-# memberapi.ose.tw 後端架構（公司/品牌站台/會員 + 系統/模組權限）
-
-## 資料層級
- 業務層級：`companies -> sites -> users`
- 功能層級：`systems -> modules`
- 授權掛載點：
-  - Scope：`company` 或 `site`
-  - 能力：`system` 必填，`module` 選填（空值代表系統層）
-
-## 權限模型
- 直接授權：`user_scope_permissions`
- 群組授權：`permission_groups` + `permission_group_members` + `permission_group_permissions`
- 權限快照：`/me/permissions/snapshot` 會合併「直接 + 群組」並去重
-
-## 目前後端 API（管理面）
- 主資料：
-  - `GET|POST|PATCH /admin/systems`
-  - `GET|POST|PATCH /admin/modules`
-  - `GET|POST|PATCH /admin/companies`
-  - `GET|POST|PATCH /admin/sites`
- 會員：
-  - `GET /admin/members`
-  - `POST /admin/members/upsert`
-  - `PATCH /admin/members/{authentik_sub}`
- 會員群組（改由會員頁管理）：
-  - `GET /admin/members/{authentik_sub}/permission-groups`
-  - `PUT /admin/members/{authentik_sub}/permission-groups`
- 群組：
-  - `GET|POST|PATCH /admin/permission-groups`
-  - `GET /admin/permission-groups/{group_key}/permissions`
-  - `POST /admin/permission-groups/{group_key}/permissions/grant`
-  - `POST /admin/permission-groups/{group_key}/permissions/revoke`
- 直接授權：
-  - `POST /admin/permissions/grant`
-  - `POST /admin/permissions/revoke`
-  - `GET /admin/permissions/direct`
-  - `DELETE /admin/permissions/direct/{permission_id}`
-
-## 驗證與查詢 API
- 使用者端：
-  - `GET /me`
-  - `GET /me/permissions/snapshot`
- OIDC：
-  - `GET /auth/oidc/url`
-  - `POST /auth/oidc/exchange`
- Internal（跨系統查詢）：
-  - `GET /internal/systems|modules|companies|sites|members`
-  - `GET /internal/permissions/{authentik_sub}/snapshot`
-
-## DB 與初始化
- 統一 schema：`backend/scripts/init_schema.sql`
- schema 快照：`docs/DB_SCHEMA_SNAPSHOT.md`
--- a/docs/BACKEND_BOOTSTRAP.md
+++ b/docs/BACKEND_BOOTSTRAP.md
@@ -1,38 +0,0 @@
-# Backend Bootstrap（memberapi）
-
-## 1. 環境準備
-```bash
-cd member.ose.tw/backend
-python -m venv .venv
-source .venv/bin/activate
-pip install -e .
-cp .env.example .env
-```
-
-## 2. 建立資料表
-1. 先執行 `member.ose.tw/backend/scripts/init_schema.sql`（已含 `api_clients`）
-2. 若是舊資料庫，補跑 `member.ose.tw/backend/scripts/migrate_align_company_site_member_system.sql`
-3. 若是更舊資料庫，再補 `member.ose.tw/backend/scripts/migrate_add_authentik_user_id.sql`
-
-## 3. 啟動服務
-```bash
-cd member.ose.tw/backend
-./scripts/start_dev.sh
-```
-
-說明：
- `start_dev.sh` 會用 `--env-file .env.development` 啟動，不需要每次手改 `.env`
-
-## 4. Authentik JWT 最小設定
-`.env` 至少填一種：
- `AUTHENTIK_JWKS_URL=<jwks endpoint>`
- `AUTHENTIK_ISSUER=<issuer url>`（系統會推導 `<issuer>/jwks/`）
-
-可選：
- `AUTHENTIK_AUDIENCE=<audience>`
- `AUTHENTIK_CLIENT_SECRET=<client_secret>`（token 為 HS256 時需要）
-
-## 5. 快速驗證
-```bash
-curl -sS http://127.0.0.1:8000/healthz
-```
--- a/docs/BACKEND_TASKPLAN.md
+++ b/docs/BACKEND_TASKPLAN.md
@@ -0,0 +1,22 @@
+# Backend TaskPlan
+
+## 待辦
+- [ ] 重寫 `backend/scripts/init_schema.sql` 為乾淨重建版（drop/recreate）
+- [ ] 刪除非必要舊表與舊權限模型（只留群組中心模型）
+- [ ] 新增/調整查詢 API：
+  - [ ] 系統明細關聯（群組、會員）
+  - [ ] 模組明細關聯（群組、會員）
+  - [ ] 公司底下站台列表
+  - [ ] 會員所屬群組列表
+- [ ] action 驗證改為只允許 `view/edit`
+- [ ] scope 驗證改為只允許 `site`
+- [ ] 補齊 API 錯誤碼一致性（400/404/409）
+
+## 進行中
+- [ ] 新 schema 與 API 契約對齊設計（以群組整合權限為中心）
+
+## 已完成
+- [x] 後端已具備 systems/modules/companies/sites/members/permission-groups 基礎 CRUD 能力
+- [x] 本地開發環境（`.env.development`）可啟動並連線 DB
+- [x] 管理 API 認證統一使用 `X-Client-Key` + `X-API-Key`
+- [x] Authentik 會員同步流程已能在 upsert/update 路徑運作
--- a/docs/DB_SCHEMA.md
+++ b/docs/DB_SCHEMA.md
@@ -0,0 +1,91 @@
+# DB Schema（新架構）
+
+## 1) 設計原則
+- 權限以群組為中心，不使用會員直接細粒度授權流程
+- `scope` 固定為 `site`
+- `action` 只允許 `view`、`edit`（可同時存在）
+- DB 真實執行來源：`backend/scripts/init_schema.sql`
+
+## 2) 核心實體
+- `companies`
+  - `id` (PK)
+  - `company_key` (UNIQUE)
+  - `name`, `status`, `created_at`, `updated_at`
+- `sites`
+  - `id` (PK)
+  - `site_key` (UNIQUE)
+  - `company_id` (FK -> companies.id)
+  - `name`, `status`, `created_at`, `updated_at`
+- `users`
+  - `id` (PK)
+  - `authentik_sub` (UNIQUE)
+  - `authentik_user_id`, `email` (UNIQUE), `display_name`, `is_active`
+- `systems`
+  - `id` (PK)
+  - `system_key` (UNIQUE)
+  - `name`, `status`
+- `modules`
+  - `id` (PK)
+  - `module_key` (UNIQUE)
+  - `system_id` (FK -> systems.id)
+  - `name`, `status`
+- `permission_groups`
+  - `id` (PK)
+  - `group_key` (UNIQUE)
+  - `name`, `status`
+
+## 3) 群組關聯（多對多）
+- `permission_group_members`
+  - `group_id` (FK -> permission_groups.id)
+  - `user_id` (FK -> users.id)
+  - UNIQUE (`group_id`, `user_id`)
+- `permission_group_sites`
+  - `group_id` (FK -> permission_groups.id)
+  - `site_id` (FK -> sites.id)
+  - UNIQUE (`group_id`, `site_id`)
+- `permission_group_systems`
+  - `group_id` (FK -> permission_groups.id)
+  - `system_id` (FK -> systems.id)
+  - UNIQUE (`group_id`, `system_id`)
+- `permission_group_modules`
+  - `group_id` (FK -> permission_groups.id)
+  - `module_id` (FK -> modules.id)
+  - UNIQUE (`group_id`, `module_id`)
+- `permission_group_actions`
+  - `group_id` (FK -> permission_groups.id)
+  - `action` (`view` | `edit`)
+  - UNIQUE (`group_id`, `action`)
+
+## 4) 查詢預期
+- 系統頁關聯：
+  - 查 `permission_group_systems` 取群組
+  - 經 `permission_group_members` 推導涉及會員
+- 模組頁關聯：
+  - 查 `permission_group_modules` 取群組
+  - 經 `permission_group_members` 推導涉及會員
+- 公司頁站台：
+  - 查 `sites` by `company_id`
+- 會員頁群組：
+  - 查 `permission_group_members` by `user_id`
+
+## 5) 驗收查核（SQL）
+```sql
+-- 1) 檢查主表是否存在
+SELECT tablename
+FROM pg_tables
+WHERE schemaname = 'public'
+  AND tablename IN (
+    'companies','sites','users','systems','modules','permission_groups',
+    'permission_group_members','permission_group_sites',
+    'permission_group_systems','permission_group_modules','permission_group_actions'
+  )
+ORDER BY tablename;
+
+-- 2) 檢查 action 值域
+SELECT DISTINCT action FROM permission_group_actions ORDER BY action;
+
+-- 3) 檢查群組可同時有 view/edit
+SELECT group_id, array_agg(action ORDER BY action) AS actions
+FROM permission_group_actions
+GROUP BY group_id;
+```
--- a/docs/DB_SCHEMA_SNAPSHOT.md
+++ b/docs/DB_SCHEMA_SNAPSHOT.md
@@ -1,215 +0,0 @@
-# DB Schema Snapshot
-
- Date: 2026-03-30
- Database: `member.ose.tw`
- Schema: `public`
-
-## Tables
-
- `api_clients`
- `auth_sync_state`
- `companies`
- `modules`
- `permissions`
- `sites`
- `user_scope_permissions`
- `users`
-
-## `api_clients`
-
-### Columns
-
- `id`: `uuid` (not null: `true`)
- `client_key`: `text` (not null: `true`)
- `name`: `text` (not null: `true`)
- `status`: `client_status` (not null: `true`)
- `api_key_hash`: `text` (not null: `true`)
- `allowed_origins`: `jsonb` (not null: `true`)
- `allowed_ips`: `jsonb` (not null: `true`)
- `allowed_paths`: `jsonb` (not null: `true`)
- `rate_limit_per_min`: `integer` (not null: `false`)
- `expires_at`: `timestamp with time zone` (not null: `false`)
- `last_used_at`: `timestamp with time zone` (not null: `false`)
- `created_at`: `timestamp with time zone` (not null: `true`)
- `updated_at`: `timestamp with time zone` (not null: `true`)
-
-### Constraints
-
- `api_clients_client_key_key` (`u`): UNIQUE (client_key)
- `api_clients_pkey` (`p`): PRIMARY KEY (id)
-
-### Indexes
-
- `api_clients_client_key_key`: `CREATE UNIQUE INDEX api_clients_client_key_key ON public.api_clients USING btree (client_key)`
- `api_clients_pkey`: `CREATE UNIQUE INDEX api_clients_pkey ON public.api_clients USING btree (id)`
- `idx_api_clients_expires_at`: `CREATE INDEX idx_api_clients_expires_at ON public.api_clients USING btree (expires_at)`
- `idx_api_clients_status`: `CREATE INDEX idx_api_clients_status ON public.api_clients USING btree (status)`
-
-## `auth_sync_state`
-
-### Columns
-
- `user_id`: `uuid` (not null: `true`)
- `last_synced_at`: `timestamp with time zone` (not null: `false`)
- `source_version`: `text` (not null: `false`)
- `last_error`: `text` (not null: `false`)
- `updated_at`: `timestamp with time zone` (not null: `true`)
-
-### Constraints
-
- `auth_sync_state_pkey` (`p`): PRIMARY KEY (user_id)
- `auth_sync_state_user_id_fkey` (`f`): FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-
-### Indexes
-
- `auth_sync_state_pkey`: `CREATE UNIQUE INDEX auth_sync_state_pkey ON public.auth_sync_state USING btree (user_id)`
-
-## `companies`
-
-### Columns
-
- `id`: `uuid` (not null: `true`)
- `company_key`: `text` (not null: `true`)
- `name`: `text` (not null: `true`)
- `status`: `record_status` (not null: `true`)
- `created_at`: `timestamp with time zone` (not null: `true`)
- `updated_at`: `timestamp with time zone` (not null: `true`)
-
-### Constraints
-
- `companies_company_key_key` (`u`): UNIQUE (company_key)
- `companies_pkey` (`p`): PRIMARY KEY (id)
-
-### Indexes
-
- `companies_company_key_key`: `CREATE UNIQUE INDEX companies_company_key_key ON public.companies USING btree (company_key)`
- `companies_pkey`: `CREATE UNIQUE INDEX companies_pkey ON public.companies USING btree (id)`
-
-## `modules`
-
-### Columns
-
- `id`: `uuid` (not null: `true`)
- `module_key`: `text` (not null: `true`)
- `name`: `text` (not null: `true`)
- `status`: `record_status` (not null: `true`)
- `created_at`: `timestamp with time zone` (not null: `true`)
- `updated_at`: `timestamp with time zone` (not null: `true`)
-
-### Constraints
-
- `modules_module_key_key` (`u`): UNIQUE (module_key)
- `modules_pkey` (`p`): PRIMARY KEY (id)
-
-### Indexes
-
- `modules_module_key_key`: `CREATE UNIQUE INDEX modules_module_key_key ON public.modules USING btree (module_key)`
- `modules_pkey`: `CREATE UNIQUE INDEX modules_pkey ON public.modules USING btree (id)`
-
-## `permissions`
-
-### Columns
-
- `id`: `uuid` (not null: `true`)
- `user_id`: `uuid` (not null: `true`)
- `scope_type`: `character varying(32)` (not null: `true`)
- `scope_id`: `character varying(128)` (not null: `true`)
- `module`: `character varying(128)` (not null: `true`)
- `action`: `character varying(32)` (not null: `true`)
- `created_at`: `timestamp with time zone` (not null: `true`)
-
-### Constraints
-
- `permissions_pkey` (`p`): PRIMARY KEY (id)
- `permissions_user_id_fkey` (`f`): FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
- `uq_permissions_user_scope_module_action` (`u`): UNIQUE (user_id, scope_type, scope_id, module, action)
-
-### Indexes
-
- `idx_permissions_user_id`: `CREATE INDEX idx_permissions_user_id ON public.permissions USING btree (user_id)`
- `permissions_pkey`: `CREATE UNIQUE INDEX permissions_pkey ON public.permissions USING btree (id)`
- `uq_permissions_user_scope_module_action`: `CREATE UNIQUE INDEX uq_permissions_user_scope_module_action ON public.permissions USING btree (user_id, scope_type, scope_id, module, action)`
-
-## `sites`
-
-### Columns
-
- `id`: `uuid` (not null: `true`)
- `site_key`: `text` (not null: `true`)
- `company_id`: `uuid` (not null: `true`)
- `name`: `text` (not null: `true`)
- `status`: `record_status` (not null: `true`)
- `created_at`: `timestamp with time zone` (not null: `true`)
- `updated_at`: `timestamp with time zone` (not null: `true`)
-
-### Constraints
-
- `sites_company_id_fkey` (`f`): FOREIGN KEY (company_id) REFERENCES companies(id) ON DELETE CASCADE
- `sites_pkey` (`p`): PRIMARY KEY (id)
- `sites_site_key_key` (`u`): UNIQUE (site_key)
-
-### Indexes
-
- `idx_sites_company_id`: `CREATE INDEX idx_sites_company_id ON public.sites USING btree (company_id)`
- `sites_pkey`: `CREATE UNIQUE INDEX sites_pkey ON public.sites USING btree (id)`
- `sites_site_key_key`: `CREATE UNIQUE INDEX sites_site_key_key ON public.sites USING btree (site_key)`
-
-## `user_scope_permissions`
-
-### Columns
-
- `id`: `uuid` (not null: `true`)
- `user_id`: `uuid` (not null: `true`)
- `module_id`: `uuid` (not null: `true`)
- `action`: `permission_action` (not null: `true`)
- `scope_type`: `scope_type` (not null: `true`)
- `company_id`: `uuid` (not null: `false`)
- `site_id`: `uuid` (not null: `false`)
- `created_at`: `timestamp with time zone` (not null: `true`)
- `updated_at`: `timestamp with time zone` (not null: `true`)
-
-### Constraints
-
- `user_scope_permissions_check` (`c`): CHECK ((((scope_type = 'company'::scope_type) AND (company_id IS NOT NULL) AND (site_id IS NULL)) OR ((scope_type = 'site'::scope_type) AND (site_id IS NOT NULL) AND (company_id IS NULL))))
- `user_scope_permissions_company_id_fkey` (`f`): FOREIGN KEY (company_id) REFERENCES companies(id) ON DELETE CASCADE
- `user_scope_permissions_module_id_fkey` (`f`): FOREIGN KEY (module_id) REFERENCES modules(id) ON DELETE CASCADE
- `user_scope_permissions_pkey` (`p`): PRIMARY KEY (id)
- `user_scope_permissions_site_id_fkey` (`f`): FOREIGN KEY (site_id) REFERENCES sites(id) ON DELETE CASCADE
- `user_scope_permissions_user_id_fkey` (`f`): FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-
-### Indexes
-
- `idx_usp_company_id`: `CREATE INDEX idx_usp_company_id ON public.user_scope_permissions USING btree (company_id)`
- `idx_usp_module_id`: `CREATE INDEX idx_usp_module_id ON public.user_scope_permissions USING btree (module_id)`
- `idx_usp_site_id`: `CREATE INDEX idx_usp_site_id ON public.user_scope_permissions USING btree (site_id)`
- `idx_usp_user_id`: `CREATE INDEX idx_usp_user_id ON public.user_scope_permissions USING btree (user_id)`
- `uq_usp_company`: `CREATE UNIQUE INDEX uq_usp_company ON public.user_scope_permissions USING btree (user_id, module_id, action, scope_type, company_id) WHERE (scope_type = 'company'::scope_type)`
- `uq_usp_site`: `CREATE UNIQUE INDEX uq_usp_site ON public.user_scope_permissions USING btree (user_id, module_id, action, scope_type, site_id) WHERE (scope_type = 'site'::scope_type)`
- `user_scope_permissions_pkey`: `CREATE UNIQUE INDEX user_scope_permissions_pkey ON public.user_scope_permissions USING btree (id)`
-
-## `users`
-
-### Columns
-
- `id`: `uuid` (not null: `true`)
- `authentik_sub`: `text` (not null: `true`)
- `email`: `text` (not null: `false`)
- `display_name`: `text` (not null: `false`)
- `status`: `record_status` (not null: `true`)
- `created_at`: `timestamp with time zone` (not null: `true`)
- `updated_at`: `timestamp with time zone` (not null: `true`)
- `authentik_user_id`: `integer` (not null: `false`)
- `is_active`: `boolean` (not null: `true`)
-
-### Constraints
-
- `users_authentik_sub_key` (`u`): UNIQUE (authentik_sub)
- `users_email_key` (`u`): UNIQUE (email)
- `users_pkey` (`p`): PRIMARY KEY (id)
-
-### Indexes
-
- `idx_users_authentik_sub`: `CREATE INDEX idx_users_authentik_sub ON public.users USING btree (authentik_sub)`
- `users_authentik_sub_key`: `CREATE UNIQUE INDEX users_authentik_sub_key ON public.users USING btree (authentik_sub)`
- `users_email_key`: `CREATE UNIQUE INDEX users_email_key ON public.users USING btree (email)`
- `users_pkey`: `CREATE UNIQUE INDEX users_pkey ON public.users USING btree (id)`
--- a/docs/FRONTEND_API_CONTRACT.md
+++ b/docs/FRONTEND_API_CONTRACT.md
@@ -1,123 +0,0 @@
-# Frontend API Contract（memberapi）
-
-Base URL：`https://memberapi.ose.tw`
-
-## 0. OIDC 登入
- `GET /auth/oidc/url?redirect_uri=...`
- `POST /auth/oidc/exchange`
-
-## 1. 使用者資訊
- `GET /me`
- `GET /me/permissions/snapshot`
-
-`permissions` item:
-```json
-{
-  "scope_type": "company|site",
-  "scope_id": "company_key_or_site_key",
-  "system": "mkt",
-  "module": "mkt.campaign",
-  "action": "view"
-}
-```
-
-## 2. 權限（User 直接授權）
-Headers:
- `X-Client-Key`
- `X-API-Key`
-
-### POST `/admin/permissions/grant`
-```json
-{
-  "authentik_sub": "authentik-sub",
-  "email": "user@example.com",
-  "display_name": "User",
-  "scope_type": "company",
-  "scope_id": "ose-main",
-  "system": "mkt",
-  "module": "campaign",
-  "action": "view"
-}
-```
-
-### POST `/admin/permissions/revoke`
-```json
-{
-  "authentik_sub": "authentik-sub",
-  "scope_type": "site",
-  "scope_id": "tw-main",
-  "system": "mkt",
-  "module": "campaign",
-  "action": "view"
-}
-```
-
-說明：
- `module` 可省略，代表系統層權限，後端會使用 `system.__system__`。
- `module` 有值時會組成 `{system}.{module}` 存入（例如 `mkt.campaign`）。
-
-## 3. 主資料管理（admin）
-Headers:
- `X-Client-Key`
- `X-API-Key`
-
- `GET/POST/PATCH /admin/systems`
- `GET/POST/PATCH /admin/modules`
- `GET/POST/PATCH /admin/companies`
- `GET/POST/PATCH /admin/sites`
- `GET /admin/members`
- `POST /admin/members/upsert`
- `PATCH /admin/members/{authentik_sub}`
-
-## 4. 會員與群組關聯（由會員頁管理）
-Headers:
- `X-Client-Key`
- `X-API-Key`
-
- `GET /admin/members/{authentik_sub}/permission-groups`
- `PUT /admin/members/{authentik_sub}/permission-groups`
-```json
-{
-  "group_keys": ["site-ops", "mkt-admin"]
-}
-```
-
-## 5. 權限群組（一組權限可綁多個 user）
-Headers:
- `X-Client-Key`
- `X-API-Key`
-
- `GET/POST/PATCH /admin/permission-groups`
- `GET /admin/permission-groups/{group_key}/permissions`
- `POST /admin/permission-groups/{group_key}/permissions/grant`
- `POST /admin/permission-groups/{group_key}/permissions/revoke`
-
-群組授權 payload 與 user 授權 payload 相同（用 `system/module/scope/action`）。
-
-## 6. 直接授權列表（權限管理頁）
-Headers:
- `X-Client-Key`
- `X-API-Key`
-
- `GET /admin/permissions/direct?keyword=&scope_type=&limit=&offset=`
- `DELETE /admin/permissions/direct/{permission_id}`
-
-## 7. Internal 查詢 API（其他系統）
-Headers:
- `X-Internal-Secret`
-
- `GET /internal/systems`
- `GET /internal/modules`
- `GET /internal/companies`
- `GET /internal/sites`
- `GET /internal/members`
- `GET /internal/permissions/{authentik_sub}/snapshot`
-
-## 8. 常見錯誤
- `401 invalid_client`
- `401 invalid_api_key`
- `401 invalid_internal_secret`
- `404 system_not_found`
- `404 company_not_found`
- `404 site_not_found`
- `400 invalid_permission_id`
--- a/docs/FRONTEND_ARCHITECTURE.md
+++ b/docs/FRONTEND_ARCHITECTURE.md
@@ -1,87 +0,0 @@
-# member.ose.tw 前端架構（可直接開工版）
-
-## 1. 前端責任邊界
- 站點：`member.ose.tw`
- 主要責任：
-  - 顯示目前登入使用者資訊
-  - 顯示目前使用者權限快照
-  - 透過管理 API 執行 grant/revoke
- 不處理：
-  - Authentik 管理 API 直連
-  - 密碼重設流程（導向 Authentik）
-
-## 2. 建議技術堆疊
- Vue 3 + Vite + JavaScript
- Vue Router
- Pinia
- Axios
- Element Plus + Tailwind
-
-## 3. 建議目錄結構
- `frontend/src/main.js`
- `frontend/src/router/index.js`
- `frontend/src/stores/`
-  - `auth.js`：token、me、登入狀態
-  - `permission.js`：snapshot 與快取
- `frontend/src/api/`
-  - `http.js`：axios instance + interceptor
-  - `me.js`
-  - `permission-admin.js`
- `frontend/src/pages/`
-  - `profile/MePage.vue`
-  - `permissions/PermissionSnapshotPage.vue`
-  - `permissions/PermissionAdminPage.vue`
- `frontend/src/types/`
-  - `api.js`
-
-## 4. 路由規劃（第一版）
- `/me`
-  - 顯示 `GET /me` 資料
- `/me/permissions`
-  - 顯示 `GET /me/permissions/snapshot`
- `/admin/permissions`
-  - grant/revoke 表單與結果顯示
-
-## 5. Token 與 Header 策略
- 使用者路由（`/me*`）
-  - 登入用 `POST /auth/login`（帳號密碼）取得 access token
-  - header: `Authorization: Bearer <access_token>`
- 管理路由（`/admin*`）
-  - headers:
-    - `X-Client-Key`
-    - `X-API-Key`
- 建議：
-  - 使用 axios request interceptor 統一注入 header
-  - 401 時統一導向登入或刷新流程
-
-## 6. 狀態管理最小模型
- `auth store`
-  - `accessToken: string | null`
-  - `me: { sub, email, display_name } | null`
-  - actions: `setToken`, `fetchMe`, `logout`
- `permission store`
-  - `snapshot: { authentik_sub, permissions[] } | null`
-  - actions: `fetchMySnapshot`, `grantPermission`, `revokePermission`
-
-## 7. 錯誤處理規則
- `401`
-  - 使用者 token 過期或無效，導回登入
- `403`
-  - API client 白名單限制（origin/ip/path）
- `404`
-  - revoke 時 user 不存在
- `503`
-  - 後端必要設定缺失（例如 internal secret / authentik admin）
-
-## 8. 開工順序（建議）
-1. 建立 axios client 與 interceptor
-2. 完成 `/me` 與 `/me/permissions` 畫面
-3. 完成 grant/revoke 表單
-4. 補通知、loading、錯誤提示
-
-詳細 request/response 契約請看 `docs/FRONTEND_API_CONTRACT.md`。
-
-## 9. 本地開發環境
- Vite 會自動讀取 `frontend/.env.development`
- 已預設：
-  - `VITE_API_BASE_URL=http://127.0.0.1:8000`
--- a/docs/FRONTEND_HANDOFF.md
+++ b/docs/FRONTEND_HANDOFF.md
@@ -0,0 +1,33 @@
+# Frontend Handoff（交給前端 AI）
+
+## 目標
+把後台管理改為「群組中心權限模型」，並符合以下固定規則：
+- `scope` 只用 `site`
+- 顯示為 `公司/站台`
+- `action` 只允許 `view/edit`，且可多選
+
+## 交辦項目
+1. 群組管理頁
+- 群組基本資料 CRUD
+- 同頁整合：站台、系統、模組、會員、action
+- action 使用多選（`view`、`edit`）
+
+2. 系統編輯頁
+- 顯示該系統被哪些群組使用
+- 顯示該系統涉及哪些會員（由群組關聯推導）
+
+3. 模組編輯頁
+- 顯示該模組被哪些群組使用
+- 顯示該模組涉及哪些會員（由群組關聯推導）
+
+4. 公司頁
+- 顯示公司底下站台列表
+
+5. 會員編輯頁
+- 顯示/編輯所屬群組
+- 會員直接授權先不做
+
+## 串接約束
+- 只串接新版群組中心 API
+- 不新增最終規格表頁面
+- UI/UX 可另外優化，但資料與流程規則不可改
--- a/docs/FRONTEND_HANDOFF_SCHEMA_V2.md
+++ b/docs/FRONTEND_HANDOFF_SCHEMA_V2.md
@@ -1,113 +0,0 @@
-# Frontend 交辦清單（Schema v2）
-
-## 目標
-前端實現對應後端新模型：
- 公司（companies）
- 品牌站台（sites）
- 會員（users）
- 系統/模組（systems/modules）
- 權限群組（permission-groups）
-
-## 既有頁面調整
-
-### 1) 權限管理頁 `/admin/permissions` ✅
- [x] Grant/Revoke payload 改為：
-  - [x] `scope_type`: `company` 或 `site`（下拉選單）
-  - [x] `scope_id`: `company_key` 或 `site_key`
-  - [x] `system`: 必填（例如 `mkt`）
-  - [x] `module`: 選填（空值代表系統層權限）
-  - [x] `action`
- [x] 表單新增 `system` 欄位
- [x] `module` 改成可選
-
-### 2) 我的權限頁 `/me/permissions` ✅
- [x] 表格新增顯示欄位：
-  - [x] `scope_type`
-  - [x] `scope_id`
-  - [x] `system`
-  - [x] `module`
-  - [x] `action`
-
-## 新增頁面 ✅
-
-### 3) 系統管理 `/admin/systems` ✅
- [x] 列表：`GET /admin/systems`
- [x] 新增：`POST /admin/systems`
- [x] 表格顯示 system_key 與 name
- [x] Dialog 表單新增系統
-
-### 4) 模組管理 `/admin/modules` ✅
- [x] 列表：`GET /admin/modules`
- [x] 新增：`POST /admin/modules`
-  - [x] `system_key`
-  - [x] `module_key`
-  - [x] `name`
- [x] 表格顯示三個欄位
- [x] Dialog 表單新增模組
-
-### 5) 公司管理 `/admin/companies` ✅
- [x] 列表：`GET /admin/companies`
- [x] 新增：`POST /admin/companies`
- [x] 表格顯示 company_key 與 name
- [x] Dialog 表單新增公司
-
-### 6) 站台管理 `/admin/sites` ✅
- [x] 列表：`GET /admin/sites`
- [x] 新增：`POST /admin/sites`
-  - [x] `site_key`
-  - [x] `company_key`
-  - [x] `name`
- [x] 表格顯示三個欄位
- [x] Dialog 表單新增站台
-
-### 7) 會員管理 `/admin/members` ✅
- [x] 列表：`GET /admin/members`
- [x] 表格顯示 authentik_sub、email、display_name
- [x] 新增會員：`POST /admin/members/upsert`
- [x] 編輯會員：`PATCH /admin/members/{authentik_sub}`
- [x] 會員頁可直接設定「權限群組」（multi-select）：
-  - [x] `GET /admin/members/{authentik_sub}/permission-groups`
-  - [x] `PUT /admin/members/{authentik_sub}/permission-groups`
-
-### 8) 權限群組 `/admin/permission-groups` ✅
- [x] 群組管理 Tab：
-  - [x] 列表：`GET /admin/permission-groups`
-  - [x] 新增：`POST /admin/permission-groups`
-  - [x] Dialog 表單新增群組
- [x] 群組授權 Tab：
-  - [x] `POST /admin/permission-groups/{group_key}/permissions/grant`
-  - [x] `POST /admin/permission-groups/{group_key}/permissions/revoke`
-  - [x] UI 支援選擇群組、輸入權限資訊、grant/revoke 按鈕
- [x] 群組權限列表：
-  - [x] `GET /admin/permission-groups/{group_key}/permissions`
-  - [x] 可查看群組目前有哪些系統/模組/操作權限
-
-## 共用資料管理 ✅
- [x] admin.js store 實現：
-  - [x] 統一載入 systems、modules、companies、sites
-  - [x] 供各管理頁使用，避免重複 API 呼叫
-
-## 認證（管理 API） ✅
- [x] 所有 `/admin/*` API 一律帶：
-  - [x] `X-Client-Key`
-  - [x] `X-API-Key`
- [x] axios adminHttp client 自動注入 headers
- [x] 管理頁不需手動輸入金鑰（改由環境變數與攔截器帶入）
-
-## 權限管理頁強化 ✅
- [x] 直接授權列表：
-  - [x] `GET /admin/permissions/direct`
-  - [x] 支援關鍵字與 scope 篩選
- [x] 列表逐筆撤銷：
-  - [x] `DELETE /admin/permissions/direct/{permission_id}`
-
-## 驗收條件 ✅
- [x] 可以新增 system/module/company/site
- [x] 可以做 user 直接 grant/revoke（新 payload）
- [x] 可以建立 permission-group，並在會員頁指派群組，做群組 grant/revoke
- [x] `/me/permissions/snapshot` 能看到所有權限欄位（scope_type/scope_id/system/module/action）
-
-## 完成日期
- 開始：2026-03-29
- 完成：2026-03-30
- 提交 Commit：`c4b9789`
--- a/docs/FRONTEND_IMPLEMENTATION_CHECKLIST.md
+++ b/docs/FRONTEND_IMPLEMENTATION_CHECKLIST.md
@@ -1,29 +0,0 @@
-# Frontend Implementation Checklist
-
-## A. 專案初始化
- [ ] 建立 `src/api/http.js`
- [ ] 建立 `src/stores/auth.js`
- [ ] 建立 `src/stores/permission.js`
- [ ] 配置 `VITE_API_BASE_URL`
-
-## B. API 對接
- [ ] `GET /me`
- [ ] `GET /me/permissions/snapshot`
- [ ] `POST /admin/permissions/grant`
- [ ] `POST /admin/permissions/revoke`
-
-## C. 頁面
- [ ] Me 頁面（顯示 sub/email/display_name）
- [ ] 我的權限頁（表格）
- [ ] 權限管理頁（grant/revoke）
-
-## D. 行為驗證
- [ ] Bearer token 遺失時顯示重新登入
- [ ] grant 成功後自動刷新 snapshot
- [ ] revoke 成功後自動刷新 snapshot
- [ ] 404 user_not_found 顯示可讀錯誤訊息
-
-## E. 交付條件
- [ ] 三個頁面都可獨立刷新
- [ ] 所有 API 錯誤碼都有 UI 提示
- [ ] 主要操作有 loading 與成功提示
--- a/docs/FRONTEND_TASKPLAN.md
+++ b/docs/FRONTEND_TASKPLAN.md
@@ -0,0 +1,20 @@
+# Frontend TaskPlan
+
+## 待辦
+- [ ] 重構群組管理頁為單一中心（整合權限設定，不再拆分心智）
+- [ ] 新增系統編輯頁關聯區塊：所屬群組、涉及會員
+- [ ] 新增模組編輯頁關聯區塊：所屬群組、涉及會員
+- [ ] 公司頁新增站台列表區塊
+- [ ] 會員編輯頁強化群組列表與編輯體驗
+- [ ] 所有 action UI 改為多選但僅 `view/edit`
+- [ ] 所有 scope UI 固定為 `site`（顯示 `公司/站台`）
+- [ ] 隱藏/移除會員細粒度直接授權主流程入口
+
+## 進行中
+- [ ] 與新版後端 API 契約對齊（群組中心）
+
+## 已完成
+- [x] 前端框架採用 Vue3 + JS + Vite + Element Plus + Tailwind
+- [x] 已有 admin 基礎頁面：systems/modules/companies/sites/members/permission-groups
+- [x] 已有會員建立/編輯與群組指派基本能力
+- [x] 已有 OIDC 登入與 `/me`、`/me/permissions/snapshot` 基礎流程
--- a/docs/LOCAL_DEV_RUNBOOK.md
+++ b/docs/LOCAL_DEV_RUNBOOK.md
@@ -0,0 +1,31 @@
+# Local Dev Runbook
+
+## 1) 啟動後端
+```bash
+cd backend
+.venv/bin/uvicorn app.main:app --env-file .env.development --host 127.0.0.1 --port 8000
+```
+
+## 2) 啟動前端
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+## 3) 基本檢查
+- Backend health: `GET http://127.0.0.1:8000/healthz`
+- Frontend: `http://localhost:5173` 或 `http://127.0.0.1:5173`
+- 檢查 admin API 是否有自動帶 `X-Client-Key`、`X-API-Key`
+
+## 4) 驗收順序（本地）
+1. 建立公司、站台
+2. 建立系統、模組
+3. 建立會員
+4. 建立群組
+5. 在群組配置：站台/系統/模組/action(view/edit)/會員
+6. 到系統/模組/公司/會員頁確認關聯列表是否正確
+
+## 5) 注意事項
+- 本輪不產最終規格表
+- DB 真實來源僅 `backend/scripts/init_schema.sql`
--- a/docs/ORG_MEMBER_MANAGEMENT_PLAN.md
+++ b/docs/ORG_MEMBER_MANAGEMENT_PLAN.md
@@ -1,94 +0,0 @@
-# 組織與會員管理規劃（給前端/後端協作）
-
-## 1. 目前狀態（你現在看到空白是正常）
- 已完成：
-  - Authentik 登入
-  - `/me` 基本個人資料
-  - 權限 grant/revoke 與 snapshot
- 尚未完成：
-  - 公司組織（Organization）CRUD
-  - 會員（Member）清單/新增/編輯/停用
-  - 會員與組織關聯管理
-
-## 2. 建議產品資訊架構（IA）
- `我的資料`：目前登入者基本資訊、登出
- `我的權限`：目前登入者權限快照
- `組織管理`：公司清單、建立公司、編輯公司、狀態切換
- `會員管理`：會員清單、邀請/建立會員、編輯會員、停用會員、指派組織
- `權限管理`：保留現有 grant/revoke（可作為管理員進階頁）
-
-## 3. 後端 API（v1，已開）
-
-### Organization（admin）
- `GET /admin/organizations`
- `POST /admin/organizations`
- `GET /admin/organizations/{org_id}`
- `PATCH /admin/organizations/{org_id}`
- `POST /admin/organizations/{org_id}/activate`
- `POST /admin/organizations/{org_id}/deactivate`
-
-### Member（admin）
- `GET /admin/members`
- `POST /admin/members`
- `GET /admin/members/{member_id}`
- `PATCH /admin/members/{member_id}`
- `POST /admin/members/{member_id}/activate`
- `POST /admin/members/{member_id}/deactivate`
-
-### Member x Organization（admin）
- `GET /admin/members/{member_id}/organizations`
- `POST /admin/members/{member_id}/organizations/{org_id}`
- `DELETE /admin/members/{member_id}/organizations/{org_id}`
-
-### Internal 查詢 API（給其他系統）
- `GET /internal/members`
- `GET /internal/members/by-sub/{authentik_sub}`
- `GET /internal/organizations`
- `GET /internal/organizations/by-code/{org_code}`
- `GET /internal/members/{member_id}/organizations`
-
-## 4. 建議資料表（最小可行）
- `organizations`
-  - `id` (uuid)
-  - `org_code` (unique)
-  - `name`
-  - `tax_id` (nullable)
-  - `status` (`active|inactive`)
-  - `created_at`, `updated_at`
- `members`
-  - `id` (uuid)
-  - `authentik_sub` (unique)
-  - `email`
-  - `display_name`
-  - `status` (`active|inactive`)
-  - `created_at`, `updated_at`
- `member_organizations`
-  - `member_id`
-  - `organization_id`
-  - unique(`member_id`, `organization_id`)
-
-## 5. 前端頁面需求（給另一個 AI）
- `/admin/organizations`
-  - 表格 + 查詢 + 新增 Dialog + 編輯 Dialog + 啟停用
- `/admin/members`
-  - 表格 + 查詢 + 新增 Dialog + 編輯 Dialog + 啟停用
- `/admin/members/:id/organizations`
-  - 左側會員資訊，右側組織綁定清單 + 加入/移除
-
-## 6. 權限模型（建議）
- `org.manage`：組織管理
- `member.manage`：會員管理
- `permission.manage`：權限管理
-
-可映射到現有權限欄位：
- `scope_type=global`
- `scope_id=member-center`
- `module=organization|member|permission`
- `action=view|create|update|deactivate|grant|revoke`
-
-## 7. 驗收標準
- 可以建立/修改/停用組織
- 可以建立/修改/停用會員
- 可以將會員加入/移出組織
- UI 顯示成功/失敗訊息，並可重新整理資料
- 所有管理 API 都有管理員金鑰驗證（`X-Client-Key` + `X-API-Key`）
--- a/docs/TASKPLAN_BACKEND.md
+++ b/docs/TASKPLAN_BACKEND.md
@@ -1,35 +0,0 @@
-# Backend TaskPlan
-
-## 目標
-提供可被前端穩定串接的 memberapi，包含身份驗證、權限快照、權限管理與 Authentik 同步能力。
-
-## 已完成
- [x] FastAPI 專案骨架與分層（api/service/repository/model）
- [x] `GET /healthz`
- [x] `GET /me`
- [x] `GET /me/permissions/snapshot`
- [x] `POST /admin/permissions/grant`
- [x] `POST /admin/permissions/revoke`
- [x] `POST /internal/users/upsert-by-sub`
- [x] `GET /internal/permissions/{authentik_sub}/snapshot`
- [x] `POST /internal/authentik/users/ensure`
- [x] API client 驗證（`X-Client-Key` + `X-API-Key`）
- [x] Authentik JWT 驗證（JWKS）
- [x] DB schema 初始化 SQL + migration SQL
- [x] 基本測試與 lint
-
-## 進行中（建議近期）
- [ ] 增加 Alembic migration 正式流程
- [ ] 補齊更多 API 測試（admin/internal success + fail cases）
- [ ] 增加 request id / logging 格式
-
-## 待辦（上線前）
- [ ] 加入 rate limit（依 client 或 IP）
- [ ] 針對 admin API 加 audit log（授權/撤銷行為）
- [ ] 加上 CORS 白名單與反向代理配置驗證
- [ ] 製作部署腳本（systemd / container）
-
-## 驗收條件
- [ ] 前端可完成 `/me` + `/me/permissions/snapshot` + grant/revoke 全流程
- [ ] 401/403/404/503 錯誤碼與文件一致
- [ ] 至少一輪 staging smoke test 通過
--- a/docs/TASKPLAN_FRONTEND.md
+++ b/docs/TASKPLAN_FRONTEND.md
@@ -1,60 +0,0 @@
-# Frontend TaskPlan
-
-## 目標
-完成 member.ose.tw 前端（Vue3 + JS + Vite + Element Plus + Tailwind），支援 OIDC 登入、個人資料查看、權限管理（Schema v2）。
-
-## Phase 1: 基礎框架 ✅
- [x] Vite + Vue3 專案結構
- [x] Element Plus + Tailwind 基礎接入
- [x] Router 與頁面骨架
- [x] Pinia store（auth + permission）
- [x] Axios 分離 user/admin client
- [x] Production build 可通過
-
-## Phase 2: OIDC 登入流程 ✅
- [x] `LoginPage`（OIDC 前往按鈕，跳轉 Authentik）
- [x] `AuthCallbackPage`（接收 code，交換 access_token）
- [x] Token 自動存儲與路由守衛
- [x] 401 時自動導向重新登入
-
-## Phase 3: 用戶資訊與權限 ✅
- [x] `MePage`（`GET /me` 顯示個人資料）
- [x] `PermissionSnapshotPage`（`GET /me/permissions/snapshot`）
- [x] 表格新增 `system` 欄位（Schema v2）
-
-## Phase 4: 管理員授權（v1） ✅
- [x] `PermissionAdminPage`（直接 grant/revoke 使用者）
- [x] Payload 新增 `system` 必填、`module` 改為選填
- [x] `scope_type` 改為 company/site 下拉選單
-
-## Phase 5: Schema v2 管理頁面 ✅
- [x] API 層：systems、modules、companies、sites、members、permission-groups
- [x] Store：admin.js（統一管理公共清單）
- [x] 6 個新管理頁面：
-  - [x] `/admin/systems`（系統 CRUD）
-  - [x] `/admin/modules`（模組 CRUD）
-  - [x] `/admin/companies`（公司 CRUD）
-  - [x] `/admin/sites`（站台 CRUD）
-  - [x] `/admin/members`（會員 CRUD + 指派群組）
-  - [x] `/admin/permission-groups`（群組 CRUD + 群組授權 + 群組權限列表）
- [x] 導覽列加入管理員群組下拉菜單
-
-## 進行中（下一階段）
- [ ] 組織與會員管理（`ORG_MEMBER_MANAGEMENT_PLAN.md`）
- [ ] 路由守衛策略完善（是否限制某些管理頁）
- [ ] 錯誤訊息 i18n 與統一顯示格式
-
-## 待辦（上線前）
- [ ] 增加 e2e / UI smoke 測試
- [ ] 優化 bundle size（目前 main chunk 1.2MB，需考慮 lazy loading）
- [ ] 加入環境切換策略（dev/staging/prod）
- [ ] 加入登入來源與 token 取得說明頁
-
-## 驗收條件（Schema v2）
- [x] 未登入時導向登入頁 → OIDC 流程 ✅
- [x] 登入後可穩定讀取 `/me` 與快照 ✅
- [x] 可新增 system/module/company/site ✅
- [x] 可做用戶直接 grant/revoke（新 payload） ✅
- [x] 可建立 permission-group，並從會員頁指派群組，做群組 grant/revoke ✅
- [x] `/me/permissions/snapshot` 表格可顯示 system + module + action ✅
- [x] 與後端契約文件一致 ✅
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,38 +1,23 @@
-# member docs index
+# member.ose.tw 文件入口

-## 0. 先看這兩份（入口）
-1. `docs/ARCHITECTURE_AND_CONFIG.md`
-2. `docs/BACKEND_ARCHITECTURE.md`
+## 閱讀順序（先看）
+1. `docs/ARCHITECTURE.md`
+2. `docs/DB_SCHEMA.md`
+3. `docs/BACKEND_TASKPLAN.md`
+4. `docs/FRONTEND_TASKPLAN.md`
+5. `docs/FRONTEND_HANDOFF.md`
+6. `docs/LOCAL_DEV_RUNBOOK.md`

-## 1. 架構核心（你現在的實際模型）
- 業務層級：`公司 companies -> 品牌站台 sites -> 會員 users`
- 功能層級：`系統 systems -> 模組 modules`
- 授權層級：`scope(company/site) + system + module(可空) + action`
- 權限來源：`直接授權 + 群組授權`
+## 交辦順序（執行）
+1. 後端先完成新 schema 與 API 契約
+2. 前端依 handoff 完成頁面與串接
+3. 本地驗收跑 Runbook

-## 2. 前端交辦（直接丟給另一隻 AI）
-1. `docs/FRONTEND_API_CONTRACT.md`
-2. `docs/FRONTEND_HANDOFF_SCHEMA_V2.md`
-3. `docs/FRONTEND_ARCHITECTURE.md`
+## 目前狀態
+- 架構方向：已定版（群組中心、site scope、action view/edit 多選）
+- 文件重整：已完成（舊文件已清除）
+- 程式重構：待後續依 TaskPlan 實作

-## 3. 後端與環境
- `docs/BACKEND_BOOTSTRAP.md`
- `docs/TASKPLAN_BACKEND.md`
- `backend/.env.development`（本機開發）
-
-## 4. DB（單一來源）
- `backend/scripts/init_schema.sql`（完整 schema）
- `docs/DB_SCHEMA_SNAPSHOT.md`（目前資料庫結構快照）
-
-## 5. 管理流程（建議操作順序）
-1. 建立 `systems`、`modules`
-2. 建立 `companies`、`sites`
-3. 建立/同步 `members`（可同步 Authentik）
-4. 建立 `permission-groups`
-5. 在會員頁指定會員所屬群組
-6. 在權限頁做直接授權，或在群組頁做群組授權
-
-## 6. 前端頁面責任切分
- 會員頁：會員基本資料 + 群組指派
- 群組頁：群組 CRUD + 群組權限列表 + 群組授權/撤銷
- 權限管理頁：直接授權/撤銷 + 直接授權列表（可逐筆撤銷）
+## 備註
+- 本輪不產最終規格表/最終規範矩陣
+- DB 文檔以 `docs/DB_SCHEMA.md` 為說明入口，實際 SQL 以 `backend/scripts/init_schema.sql` 為準