feat(members): split username/display_name, sync updates to authentik, add password reset API and refresh docs

2026-03-30 22:15:41 +08:00
parent e1a6bbd844
commit ccb99683b8
22 changed files with 361 additions and 207 deletions
--- a/backend/app/api/admin.py
+++ b/backend/app/api/admin.py
@@ -72,6 +72,7 @@ def grant_permission(

    user = users_repo.upsert_by_sub(
        authentik_sub=payload.authentik_sub,
+        username=None,
        email=payload.email,
        display_name=payload.display_name,
        is_active=True,
--- a/backend/app/api/admin_catalog.py
+++ b/backend/app/api/admin_catalog.py
@@ -21,6 +21,7 @@ from app.schemas.catalog import (
    MemberItem,
    MemberPermissionGroupsResponse,
    MemberPermissionGroupsUpdateRequest,
+    MemberPasswordResetResponse,
    MemberUpdateRequest,
    MemberUpsertRequest,
    ModuleCreateRequest,
@@ -100,7 +101,9 @@ def _generate_unique_key(prefix: str, exists_fn) -> str:

 def _sync_member_to_authentik(
    *,
-    authentik_sub: str,
+    authentik_sub: str | None,
+    authentik_user_id: int | None,
+    username: str | None,
    email: str | None,
    display_name: str | None,
    is_active: bool,
@@ -112,8 +115,10 @@ def _sync_member_to_authentik(
    result = service.ensure_user(
        sub=authentik_sub,
        email=email,
+        username=username,
        display_name=display_name,
        is_active=is_active,
+        authentik_user_id=authentik_user_id,
    )
    return {
        "authentik_user_id": result.user_id,
@@ -450,7 +455,22 @@ def list_members(
 ) -> dict:
    users_repo = UsersRepository(db)
    items, total = users_repo.list(keyword=keyword, limit=limit, offset=offset)
-    return {"items": [MemberItem(id=i.id, authentik_sub=i.authentik_sub, email=i.email, display_name=i.display_name, is_active=i.is_active).model_dump() for i in items], "total": total, "limit": limit, "offset": offset}
+    return {
+        "items": [
+            MemberItem(
+                id=i.id,
+                authentik_sub=i.authentik_sub,
+                username=i.username,
+                email=i.email,
+                display_name=i.display_name,
+                is_active=i.is_active,
+            ).model_dump()
+            for i in items
+        ],
+        "total": total,
+        "limit": limit,
+        "offset": offset,
+    }


@router.post("/members/upsert", response_model=MemberItem)
@@ -460,13 +480,16 @@ def upsert_member(
 ) -> MemberItem:
    users_repo = UsersRepository(db)
    resolved_sub = payload.authentik_sub
+    resolved_username = payload.username
    authentik_user_id = None
    if payload.sync_to_authentik:
-        seed_sub = payload.authentik_sub or (payload.email or "")
+        seed_sub = payload.authentik_sub or payload.username
        if not seed_sub:
-            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="authentik_sub_or_email_required")
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="authentik_sub_or_username_required")
        sync = _sync_member_to_authentik(
            authentik_sub=seed_sub,
+            authentik_user_id=authentik_user_id,
+            username=payload.username,
            email=payload.email,
            display_name=payload.display_name,
            is_active=payload.is_active,
@@ -478,6 +501,7 @@ def upsert_member(
        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="authentik_sub_required")
    row = users_repo.upsert_by_sub(
        authentik_sub=resolved_sub,
+        username=resolved_username,
        email=payload.email,
        display_name=payload.display_name,
        is_active=payload.is_active,
@@ -486,6 +510,7 @@ def upsert_member(
    return MemberItem(
        id=row.id,
        authentik_sub=row.authentik_sub,
+        username=row.username,
        email=row.email,
        display_name=row.display_name,
        is_active=row.is_active,
@@ -504,6 +529,7 @@ def update_member(
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="user_not_found")

    next_email = payload.email if payload.email is not None else row.email
+    next_username = payload.username if payload.username is not None else row.username
    next_display_name = payload.display_name if payload.display_name is not None else row.display_name
    next_is_active = payload.is_active if payload.is_active is not None else row.is_active

@@ -511,6 +537,8 @@ def update_member(
    if payload.sync_to_authentik:
        sync = _sync_member_to_authentik(
            authentik_sub=row.authentik_sub,
+            authentik_user_id=row.authentik_user_id,
+            username=next_username,
            email=next_email,
            display_name=next_display_name,
            is_active=next_is_active,
@@ -519,6 +547,7 @@ def update_member(

    row = users_repo.upsert_by_sub(
        authentik_sub=row.authentik_sub,
+        username=next_username,
        email=next_email,
        display_name=next_display_name,
        is_active=next_is_active,
@@ -527,12 +556,40 @@ def update_member(
    return MemberItem(
        id=row.id,
        authentik_sub=row.authentik_sub,
+        username=row.username,
        email=row.email,
        display_name=row.display_name,
        is_active=row.is_active,
    )


+@router.post("/members/{authentik_sub}/password/reset", response_model=MemberPasswordResetResponse)
+def reset_member_password(
+    authentik_sub: str,
+    db: Session = Depends(get_db),
+) -> MemberPasswordResetResponse:
+    users_repo = UsersRepository(db)
+    user = users_repo.get_by_sub(authentik_sub)
+    if not user:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="user_not_found")
+    settings = get_settings()
+    service = AuthentikAdminService(settings=settings)
+    result = service.reset_password(
+        authentik_user_id=user.authentik_user_id,
+        email=user.email,
+        username=user.username,
+    )
+    user = users_repo.upsert_by_sub(
+        authentik_sub=user.authentik_sub,
+        username=user.username,
+        email=user.email,
+        display_name=user.display_name,
+        is_active=user.is_active,
+        authentik_user_id=result.user_id,
+    )
+    return MemberPasswordResetResponse(authentik_sub=user.authentik_sub, temporary_password=result.temporary_password)
+
+
@router.get("/members/{authentik_sub}/permission-groups", response_model=MemberPermissionGroupsResponse)
 def get_member_permission_groups(
    authentik_sub: str,
--- a/backend/app/api/internal.py
+++ b/backend/app/api/internal.py
@@ -31,6 +31,7 @@ def upsert_user_by_sub(
    repo = UsersRepository(db)
    user = repo.upsert_by_sub(
        authentik_sub=payload.sub,
+        username=payload.username,
        email=payload.email,
        display_name=payload.display_name,
        is_active=payload.is_active,
@@ -39,6 +40,7 @@ def upsert_user_by_sub(
        "id": user.id,
        "sub": user.authentik_sub,
        "authentik_user_id": user.authentik_user_id,
+        "username": user.username,
        "email": user.email,
        "display_name": user.display_name,
        "is_active": user.is_active,
@@ -73,13 +75,20 @@ def ensure_authentik_user(
    sync_result = authentik_service.ensure_user(
        sub=payload.sub,
        email=payload.email,
+        username=payload.username,
        display_name=payload.display_name,
        is_active=payload.is_active,
    )

    users_repo = UsersRepository(db)
+    resolved_sub = payload.sub or ""
+    if sync_result.authentik_sub:
+        resolved_sub = sync_result.authentik_sub
+    if not resolved_sub:
+        raise HTTPException(status_code=status.HTTP_502_BAD_GATEWAY, detail="authentik_missing_sub")
    users_repo.upsert_by_sub(
-        authentik_sub=payload.sub,
+        authentik_sub=resolved_sub,
+        username=payload.username,
        email=payload.email,
        display_name=payload.display_name,
        is_active=payload.is_active,
--- a/backend/app/api/internal_catalog.py
+++ b/backend/app/api/internal_catalog.py
@@ -94,4 +94,19 @@ def internal_list_members(
 ) -> dict:
    repo = UsersRepository(db)
    items, total = repo.list(keyword=keyword, limit=limit, offset=offset)
-    return {"items": [{"id": i.id, "authentik_sub": i.authentik_sub, "email": i.email, "display_name": i.display_name, "is_active": i.is_active} for i in items], "total": total, "limit": limit, "offset": offset}
+    return {
+        "items": [
+            {
+                "id": i.id,
+                "authentik_sub": i.authentik_sub,
+                "username": i.username,
+                "email": i.email,
+                "display_name": i.display_name,
+                "is_active": i.is_active,
+            }
+            for i in items
+        ],
+        "total": total,
+        "limit": limit,
+        "offset": offset,
+    }
--- a/backend/app/api/me.py
+++ b/backend/app/api/me.py
@@ -22,6 +22,7 @@ def get_me(
        users_repo = UsersRepository(db)
        user = users_repo.upsert_by_sub(
            authentik_sub=principal.sub,
+            username=principal.preferred_username,
            email=principal.email,
            display_name=principal.name or principal.preferred_username,
            is_active=True,
@@ -47,6 +48,7 @@ def get_my_permission_snapshot(

        user = users_repo.upsert_by_sub(
            authentik_sub=principal.sub,
+            username=principal.preferred_username,
            email=principal.email,
            display_name=principal.name or principal.preferred_username,
            is_active=True,
--- a/backend/app/models/user.py
+++ b/backend/app/models/user.py
@@ -14,6 +14,7 @@ class User(Base):
    id: Mapped[str] = mapped_column(UUID(as_uuid=False), primary_key=True, default=lambda: str(uuid4()))
    authentik_sub: Mapped[str] = mapped_column(String(255), unique=True, nullable=False, index=True)
    authentik_user_id: Mapped[int | None] = mapped_column(Integer)
+    username: Mapped[str | None] = mapped_column(String(255), unique=True)
    email: Mapped[str | None] = mapped_column(String(320))
    display_name: Mapped[str | None] = mapped_column(String(255))
    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
--- a/backend/app/repositories/users_repo.py
+++ b/backend/app/repositories/users_repo.py
@@ -28,7 +28,12 @@ class UsersRepository:

        if keyword:
            pattern = f"%{keyword}%"
-            cond = or_(User.authentik_sub.ilike(pattern), User.email.ilike(pattern), User.display_name.ilike(pattern))
+            cond = or_(
+                User.authentik_sub.ilike(pattern),
+                User.username.ilike(pattern),
+                User.email.ilike(pattern),
+                User.display_name.ilike(pattern),
+            )
            stmt = stmt.where(cond)
            count_stmt = count_stmt.where(cond)

@@ -44,6 +49,7 @@ class UsersRepository:
    def upsert_by_sub(
        self,
        authentik_sub: str,
+        username: str | None,
        email: str | None,
        display_name: str | None,
        is_active: bool,
@@ -54,6 +60,7 @@ class UsersRepository:
            user = User(
                authentik_sub=authentik_sub,
                authentik_user_id=authentik_user_id,
+                username=username,
                email=email,
                display_name=display_name,
                is_active=is_active,
@@ -62,6 +69,7 @@ class UsersRepository:
        else:
            if authentik_user_id is not None:
                user.authentik_user_id = authentik_user_id
+            user.username = username
            user.email = email
            user.display_name = display_name
            user.is_active = is_active
@@ -74,10 +82,13 @@ class UsersRepository:
        self,
        user: User,
        *,
+        username: str | None = None,
        email: str | None = None,
        display_name: str | None = None,
        is_active: bool | None = None,
    ) -> User:
+        if username is not None:
+            user.username = username
        if email is not None:
            user.email = email
        if display_name is not None:
--- a/backend/app/schemas/authentik_admin.py
+++ b/backend/app/schemas/authentik_admin.py
@@ -2,7 +2,8 @@ from pydantic import BaseModel


 class AuthentikEnsureUserRequest(BaseModel):
-    sub: str
+    sub: str | None = None
+    username: str | None = None
    email: str
    display_name: str | None = None
    is_active: bool = True
--- a/backend/app/schemas/catalog.py
+++ b/backend/app/schemas/catalog.py
@@ -78,6 +78,7 @@ class SiteItem(BaseModel):
 class MemberItem(BaseModel):
    id: str
    authentik_sub: str
+    username: str | None = None
    email: str | None = None
    display_name: str | None = None
    is_active: bool
@@ -85,6 +86,7 @@ class MemberItem(BaseModel):

 class MemberUpsertRequest(BaseModel):
    authentik_sub: str | None = None
+    username: str | None = None
    email: str | None = None
    display_name: str | None = None
    is_active: bool = True
@@ -92,12 +94,18 @@ class MemberUpsertRequest(BaseModel):


 class MemberUpdateRequest(BaseModel):
+    username: str | None = None
    email: str | None = None
    display_name: str | None = None
    is_active: bool | None = None
    sync_to_authentik: bool = True


+class MemberPasswordResetResponse(BaseModel):
+    authentik_sub: str
+    temporary_password: str
+
+
 class MemberPermissionGroupsUpdateRequest(BaseModel):
    group_keys: list[str]

--- a/backend/app/schemas/users.py
+++ b/backend/app/schemas/users.py
@@ -3,6 +3,7 @@ from pydantic import BaseModel

 class UserUpsertBySubRequest(BaseModel):
    sub: str
+    username: str | None = None
    email: str | None = None
    display_name: str | None = None
    is_active: bool = True
--- a/backend/app/services/authentik_admin_service.py
+++ b/backend/app/services/authentik_admin_service.py
@@ -1,6 +1,8 @@
 from __future__ import annotations

 from dataclasses import dataclass
+import secrets
+import string

 import httpx
 from fastapi import HTTPException, status
@@ -15,6 +17,12 @@ class AuthentikSyncResult:
    authentik_sub: str | None = None


+@dataclass
+class AuthentikPasswordResetResult:
+    user_id: int
+    temporary_password: str
+
+
 class AuthentikAdminService:
    def __init__(self, settings: Settings) -> None:
        self.base_url = settings.authentik_base_url.rstrip("/")
@@ -40,27 +48,76 @@ class AuthentikAdminService:
        )

    @staticmethod
-    def _safe_username(sub: str, email: str) -> str:
+    def _safe_username(sub: str | None, email: str) -> str:
        if email and "@" in email:
            return email.split("@", 1)[0]
-        return sub.replace("|", "_")[:150]
+        if sub:
+            return sub.replace("|", "_")[:150]
+        return "member-user"

-    def ensure_user(self, sub: str, email: str, display_name: str | None, is_active: bool = True) -> AuthentikSyncResult:
+    @staticmethod
+    def _generate_temporary_password(length: int = 14) -> str:
+        alphabet = string.ascii_letters + string.digits + "!@#$%^&*"
+        return "".join(secrets.choice(alphabet) for _ in range(length))
+
+    @staticmethod
+    def _extract_first_result(data: dict) -> dict | None:
+        results = data.get("results") if isinstance(data, dict) else None
+        return results[0] if isinstance(results, list) and results else None
+
+    def _lookup_user_by_id(self, client: httpx.Client, user_id: int) -> dict | None:
+        resp = client.get(f"/api/v3/core/users/{user_id}/")
+        if resp.status_code == 404:
+            return None
+        if resp.status_code >= 400:
+            raise HTTPException(status_code=502, detail="authentik_lookup_failed")
+        return resp.json()
+
+    def _lookup_user_by_email_or_username(
+        self, client: httpx.Client, *, email: str | None, username: str | None
+    ) -> dict | None:
+        if email:
+            resp = client.get("/api/v3/core/users/", params={"email": email})
+            if resp.status_code >= 400:
+                raise HTTPException(status_code=502, detail="authentik_lookup_failed")
+            existing = self._extract_first_result(resp.json())
+            if existing:
+                return existing
+
+        if username:
+            resp = client.get("/api/v3/core/users/", params={"username": username})
+            if resp.status_code >= 400:
+                raise HTTPException(status_code=502, detail="authentik_lookup_failed")
+            existing = self._extract_first_result(resp.json())
+            if existing:
+                return existing
+
+        return None
+
+    def ensure_user(
+        self,
+        *,
+        sub: str | None,
+        email: str,
+        username: str | None,
+        display_name: str | None,
+        is_active: bool = True,
+        authentik_user_id: int | None = None,
+    ) -> AuthentikSyncResult:
+        resolved_username = username or self._safe_username(sub=sub, email=email)
        payload = {
-            "username": self._safe_username(sub=sub, email=email),
+            "username": resolved_username,
            "name": display_name or email,
            "email": email,
            "is_active": is_active,
        }

        with self._client() as client:
-            resp = client.get("/api/v3/core/users/", params={"email": email})
-            if resp.status_code >= 400:
-                raise HTTPException(status_code=502, detail="authentik_lookup_failed")
-
-            data = resp.json()
-            results = data.get("results") if isinstance(data, dict) else None
-            existing = results[0] if isinstance(results, list) and results else None
+            existing = None
+            if authentik_user_id is not None:
+                existing = self._lookup_user_by_id(client, authentik_user_id)
+            if existing is None:
+                existing = self._lookup_user_by_email_or_username(client, email=email, username=resolved_username)

            if existing and existing.get("pk") is not None:
                user_pk = int(existing["pk"])
@@ -78,3 +135,27 @@ class AuthentikAdminService:
                action="created",
                authentik_sub=created.get("uid"),
            )
+
+    def reset_password(
+        self,
+        *,
+        authentik_user_id: int | None,
+        email: str | None,
+        username: str | None,
+    ) -> AuthentikPasswordResetResult:
+        with self._client() as client:
+            existing = None
+            if authentik_user_id is not None:
+                existing = self._lookup_user_by_id(client, authentik_user_id)
+            if existing is None:
+                existing = self._lookup_user_by_email_or_username(client, email=email, username=username)
+            if not existing or existing.get("pk") is None:
+                raise HTTPException(status_code=404, detail="authentik_user_not_found")
+
+            user_pk = int(existing["pk"])
+            temp_password = self._generate_temporary_password()
+            set_pwd_resp = client.post(f"/api/v3/core/users/{user_pk}/set_password/", json={"password": temp_password})
+            if set_pwd_resp.status_code >= 400:
+                raise HTTPException(status_code=502, detail="authentik_set_password_failed")
+
+            return AuthentikPasswordResetResult(user_id=user_pk, temporary_password=temp_password)
--- a/backend/scripts/init_schema.sql
+++ b/backend/scripts/init_schema.sql
@@ -21,6 +21,7 @@ CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  authentik_sub TEXT NOT NULL UNIQUE,
  authentik_user_id INTEGER,
+  username TEXT UNIQUE,
  email TEXT UNIQUE,
  display_name TEXT,
  status VARCHAR(16) NOT NULL DEFAULT 'active',
@@ -144,6 +145,7 @@ VALUES ('member', 'Member Center', 'active')
 ON CONFLICT (system_key) DO NOTHING;

 CREATE INDEX idx_users_authentik_sub ON users(authentik_sub);
+CREATE INDEX idx_users_username ON users(username);
 CREATE INDEX idx_sites_company_id ON sites(company_id);
 CREATE INDEX idx_usp_user_id ON user_scope_permissions(user_id);
 CREATE INDEX idx_usp_module_id ON user_scope_permissions(module_id);
--- a/backend/scripts/migrate_add_users_username.sql
+++ b/backend/scripts/migrate_add_users_username.sql
@@ -0,0 +1,16 @@
+ALTER TABLE users
+  ADD COLUMN IF NOT EXISTS username TEXT;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+    FROM pg_constraint
+    WHERE conname = 'uq_users_username'
+  ) THEN
+    ALTER TABLE users
+      ADD CONSTRAINT uq_users_username UNIQUE (username);
+  END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,29 +1,26 @@
 # member.ose.tw 架構總覽

-## 1) 核心模型
- 業務層級：`companies -> sites -> users`
- 功能層級：`systems -> modules`
- 權限核心：`permission_groups`（群組整合權限與成員）
+## 核心模型
+- 業務層：`companies -> sites -> users`
+- 功能層：`systems -> modules`
+- 權限層：`permission_groups`（群組中心）

-## 2) 權限規則（固定）
- `scope` 只允許：`site`
- `action` 只允許：`view`、`edit`
- `view`、`edit` 可同時勾選（多選）
- 畫面顯示格式：`公司/站台`
+## 權限規則
+- `scope_type` 固定 `site`
+- `action` 僅 `view` / `edit`（可同時存在）
+- 權限透過群組下發給會員，不走細粒度 direct permission 主流程

-## 3) 關聯關係（皆為多對多）
- 群組 ⟷ 站台
- 群組 ⟷ 系統
- 群組 ⟷ 模組
- 群組 ⟷ 會員
+## 後台安全線
+- 所有 `/admin/*` 需 Bearer token
+- 後端僅依 `ADMIN_REQUIRED_GROUPS` 判定可否進後台
+- 不在群組就算有網址、有 Authentik 帳號也會 403

-## 4) 管理頁責任
- 群組管理：群組基本資料 + 站台/系統/模組/會員 + action(view/edit)
- 系統編輯頁：基本資料 + 所屬群組列表 + 涉及會員列表
- 模組編輯頁：基本資料 + 所屬群組列表 + 涉及會員列表
- 公司頁：基本資料 + 站台列表
- 會員編輯頁：基本資料 + 所屬群組列表
+## 會員資料與 Authentik 對齊
+- `username`：登入帳號（可編輯，可同步）
+- `display_name`：顯示名稱（可編輯，可同步到 Authentik `name`）
+- `authentik_sub`：由 Authentik UID 回寫
+- `authentik_user_id`：保留 Authentik user id，供更新/密碼重設

-## 5) 本輪範圍
- 會員細粒度直接授權先暫停
- 最終規格書（正式對外版）延後到專案完成後再整理
+## 密碼流程
+- 目前：後台可觸發重設密碼（產生臨時密碼）
+- SMTP 開通後：可再補「發送密碼設定/重設通知」自動化
--- a/docs/BACKEND_TASKPLAN.md
+++ b/docs/BACKEND_TASKPLAN.md
@@ -1,22 +1,17 @@
 # Backend TaskPlan

 ## 待辦
- [ ] 重寫 `backend/scripts/init_schema.sql` 為乾淨重建版（drop/recreate）
- [ ] 刪除非必要舊表與舊權限模型（只留群組中心模型）
- [ ] 新增/調整查詢 API：
-  - [ ] 系統明細關聯（群組、會員）
-  - [ ] 模組明細關聯（群組、會員）
-  - [ ] 公司底下站台列表
-  - [ ] 會員所屬群組列表
- [ ] action 驗證改為只允許 `view/edit`
- [ ] scope 驗證改為只允許 `site`
- [ ] 補齊 API 錯誤碼一致性（400/404/409）
+- [ ] 補 Authentik SMTP 通知流程（密碼設定/重設寄信）
+- [ ] 補 `/admin/members` 關鍵操作審計日誌
+- [ ] 補更多 API 測試（members username/password reset 路徑）

 ## 進行中
- [ ] 新 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 路徑運作
+- [x] `/admin/*` 改為 Bearer + admin 群組管控（`ADMIN_REQUIRED_GROUPS`）
+- [x] 管理 API 完成 systems/modules/companies/sites/members/permission-groups CRUD
+- [x] 會員 upsert/update 可同步 Authentik
+- [x] 會員資料新增 `username` 欄位，與 `display_name` 分離
+- [x] 新增 `POST /admin/members/{authentik_sub}/password/reset`
+- [x] DB 新增 `users.username`（含 migration 腳本）
--- a/docs/DB_SCHEMA.md
+++ b/docs/DB_SCHEMA.md
@@ -1,91 +1,42 @@
-# DB Schema（新架構）
+# DB Schema（現行）

-## 1) 設計原則
- 權限以群組為中心，不使用會員直接細粒度授權流程
- `scope` 固定為 `site`
- `action` 只允許 `view`、`edit`（可同時存在）
- DB 真實執行來源：`backend/scripts/init_schema.sql`
+## 真實來源
+- `backend/scripts/init_schema.sql`
+- 線上增量：`backend/scripts/migrate_add_users_username.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`
+  - `authentik_sub` UNIQUE
+  - `authentik_user_id` INTEGER
+  - `username` UNIQUE
+  - `email` UNIQUE
+  - `display_name`
+  - `is_active`, `status`, timestamps
+- `companies`
+- `sites`（`company_id -> companies.id`）
 - `systems`
-  - `id` (PK)
-  - `system_key` (UNIQUE)
-  - `name`, `status`
- `modules`
-  - `id` (PK)
-  - `module_key` (UNIQUE)
-  - `system_id` (FK -> systems.id)
-  - `name`, `status`
+- `modules`（`system_key -> systems.system_key`）
 - `permission_groups`
-  - `id` (PK)
-  - `group_key` (UNIQUE)
-  - `name`, `status`
+- `permission_group_members`（group + authentik_sub）
+- `permission_group_permissions`（group + site/system/module/action）
+- `user_scope_permissions`（相容保留）
+- `api_clients`（保留給機器對機器用途）

-## 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`)
+## 權限規則
+- `scope_type='site'`
+- `action in ('view','edit')`

-## 4) 查詢預期
- 系統頁關聯：
-  - 查 `permission_group_systems` 取群組
-  - 經 `permission_group_members` 推導涉及會員
- 模組頁關聯：
-  - 查 `permission_group_modules` 取群組
-  - 經 `permission_group_members` 推導涉及會員
- 公司頁站台：
-  - 查 `sites` by `company_id`
- 會員頁群組：
-  - 查 `permission_group_members` by `user_id`
+## 會員與 Authentik 對齊
+- `users.authentik_sub` 對應 Authentik `uid`
+- `users.username` 對應 Authentik `username`
+- `users.display_name` 對應 Authentik `name`

-## 5) 驗收查核（SQL）
+## 快速檢查 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;
+SELECT column_name, data_type
+FROM information_schema.columns
+WHERE table_name='users'
+ORDER BY ordinal_position;

-- 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;
+SELECT COUNT(*) FROM users WHERE username IS NULL;
 ```
--- a/docs/FRONTEND_HANDOFF.md
+++ b/docs/FRONTEND_HANDOFF.md
@@ -1,33 +1,17 @@
-# Frontend Handoff（交給前端 AI）
+# Frontend Handoff

-## 目標
-把後台管理改為「群組中心權限模型」，並符合以下固定規則：
- `scope` 只用 `site`
- 顯示為 `公司/站台`
- `action` 只允許 `view/edit`，且可多選
+## 目前後端契約重點
+- 後台登入：只吃 Bearer + admin 群組檢查
+- 會員模型：`authentik_sub`, `username`, `email`, `display_name`, `is_active`
+- 會員密碼：支援重設 API（回傳臨時密碼）

-## 交辦項目
-1. 群組管理頁
- 群組基本資料 CRUD
- 同頁整合：站台、系統、模組、會員、action
- action 使用多選（`view`、`edit`）
+## 會員頁必做
+1. 新增會員表單欄位：`username`、`email`、`display_name`
+2. 編輯會員表單欄位：`username`、`email`、`display_name`、`is_active`
+3. 表格欄位要顯示：`authentik_sub`、`username`、`email`、`display_name`
+4. 操作欄新增「重設密碼」按鈕，串 `POST /admin/members/{authentik_sub}/password/reset`
+5. 重設成功後顯示臨時密碼，並提醒管理員安全轉交

-2. 系統編輯頁
- 顯示該系統被哪些群組使用
- 顯示該系統涉及哪些會員（由群組關聯推導）
-
-3. 模組編輯頁
- 顯示該模組被哪些群組使用
- 顯示該模組涉及哪些會員（由群組關聯推導）
-
-4. 公司頁
- 顯示公司底下站台列表
-
-5. 會員編輯頁
- 顯示/編輯所屬群組
- 會員直接授權先不做
-
-## 串接約束
- 只串接新版群組中心 API
- 不新增最終規格表頁面
- UI/UX 可另外優化，但資料與流程規則不可改
+## 其他頁面
+- 仍維持群組中心模型：site/system/module/member + action(view/edit)
+- 系統/模組/公司/會員關聯頁面沿用目前 API
--- a/docs/FRONTEND_TASKPLAN.md
+++ b/docs/FRONTEND_TASKPLAN.md
@@ -1,20 +1,16 @@
 # Frontend TaskPlan

 ## 待辦
- [ ] 重構群組管理頁為單一中心（整合權限設定，不再拆分心智）
- [ ] 新增系統編輯頁關聯區塊：所屬群組、涉及會員
- [ ] 新增模組編輯頁關聯區塊：所屬群組、涉及會員
- [ ] 公司頁新增站台列表區塊
- [ ] 會員編輯頁強化群組列表與編輯體驗
- [ ] 所有 action UI 改為多選但僅 `view/edit`
- [ ] 所有 scope UI 固定為 `site`（顯示 `公司/站台`）
- [ ] 隱藏/移除會員細粒度直接授權主流程入口
+- [ ] SMTP 通知開通後，補上「發送重設通知」UX 文案
+- [ ] 會員頁重設密碼流程加上二次確認 Dialog
+- [ ] 針對大量資料頁面補分頁/搜尋體驗優化

 ## 進行中
- [ ] 與新版後端 API 契約對齊（群組中心）
+- [ ] 與最新後端契約持續對齊（members username/password reset）

 ## 已完成
- [x] 前端框架採用 Vue3 + JS + Vite + Element Plus + Tailwind
- [x] 已有 admin 基礎頁面：systems/modules/companies/sites/members/permission-groups
- [x] 已有會員建立/編輯與群組指派基本能力
- [x] 已有 OIDC 登入與 `/me`、`/me/permissions/snapshot` 基礎流程
+- [x] Vue3 + JS + Vite + Element Plus + Tailwind 基礎架構
+- [x] admin 基礎頁面：systems/modules/companies/sites/members/permission-groups
+- [x] 會員頁新增 `username` 欄位（新增/編輯/列表）
+- [x] 會員頁新增「重設密碼」操作按鈕
+- [x] OIDC 登入 + `/me`、`/me/permissions/snapshot` 流程
--- a/docs/LOCAL_DEV_RUNBOOK.md
+++ b/docs/LOCAL_DEV_RUNBOOK.md
@@ -3,7 +3,7 @@
 ## 1) 啟動後端
 ```bash
 cd backend
-.venv/bin/uvicorn app.main:app --env-file .env.development --host 127.0.0.1 --port 8000
+./scripts/start_dev.sh
 ```

 ## 2) 啟動前端
@@ -13,19 +13,18 @@ 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`
+## 3) 重要環境變數
+- `backend/.env.development`
+  - `ADMIN_REQUIRED_GROUPS=member-admin`
+  - `AUTHENTIK_*` 需可連到 Authentik

-## 4) 驗收順序（本地）
-1. 建立公司、站台
-2. 建立系統、模組
-3. 建立會員
-4. 建立群組
-5. 在群組配置：站台/系統/模組/action(view/edit)/會員
-6. 到系統/模組/公司/會員頁確認關聯列表是否正確
+## 4) 基本檢查
+- `GET http://127.0.0.1:8000/healthz`
+- 登入後打 `GET /admin/members` 應可回資料
+- 非 admin 群組帳號打 `/admin/*` 應回 `403`

-## 5) 注意事項
- 本輪不產最終規格表
- DB 真實來源僅 `backend/scripts/init_schema.sql`
+## 5) 會員流程驗收
+1. 新增會員（username/email/display_name，開啟 sync_to_authentik）
+2. 確認列表可看到新會員與 `authentik_sub`
+3. 點「重設密碼」，取得臨時密碼
+4. 到 Authentik 驗證該會員可用新密碼登入
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,6 +1,6 @@
 # member.ose.tw 文件入口

-## 閱讀順序（先看）
+## 閱讀順序
 1. `docs/ARCHITECTURE.md`
 2. `docs/DB_SCHEMA.md`
 3. `docs/BACKEND_TASKPLAN.md`
@@ -8,16 +8,14 @@
 5. `docs/FRONTEND_HANDOFF.md`
 6. `docs/LOCAL_DEV_RUNBOOK.md`

-## 交辦順序（執行）
-1. 後端先完成新 schema 與 API 契約
-2. 前端依 handoff 完成頁面與串接
-3. 本地驗收跑 Runbook
-
 ## 目前狀態
- 架構方向：已定版（群組中心、site scope、action view/edit 多選）
- 文件重整：已完成（舊文件已清除）
- 程式重構：待後續依 TaskPlan 實作
+- 架構：公司/站台/會員 + 系統/模組 + 群組整合權限（已定版）
+- 後台安全：Auth token + admin 群組檢查（`ADMIN_REQUIRED_GROUPS`）
+- 會員流程：member 新增/更新可同步 Authentik，並支援重設密碼
+
+## 單一真實來源
+- DB SQL：`backend/scripts/init_schema.sql`
+- DB 線上補丁：`backend/scripts/migrate_add_users_username.sql`

 ## 備註
- 本輪不產最終規格表/最終規範矩陣
- DB 文檔以 `docs/DB_SCHEMA.md` 為說明入口，實際 SQL 以 `backend/scripts/init_schema.sql` 為準
+- 本輪先維持可開發/可交辦文件，不產最終規格總表。
--- a/frontend/src/api/members.js
+++ b/frontend/src/api/members.js
@@ -3,6 +3,7 @@ import { adminHttp } from './http'
 export const getMembers = () => adminHttp.get('/admin/members')
 export const upsertMember = (data) => adminHttp.post('/admin/members/upsert', data)
 export const updateMember = (authentikSub, data) => adminHttp.patch(`/admin/members/${authentikSub}`, data)
+export const resetMemberPassword = (authentikSub) => adminHttp.post(`/admin/members/${authentikSub}/password/reset`)
 export const getMemberPermissionGroups = (authentikSub) => adminHttp.get(`/admin/members/${authentikSub}/permission-groups`)
 export const setMemberPermissionGroups = (authentikSub, groupKeys) =>
  adminHttp.put(`/admin/members/${authentikSub}/permission-groups`, { group_keys: groupKeys })
--- a/frontend/src/pages/admin/MembersPage.vue
+++ b/frontend/src/pages/admin/MembersPage.vue
@@ -14,20 +14,23 @@
    <el-table v-else :data="members" stripe border class="w-full shadow-sm">
      <template #empty><el-empty description="目前無會員" /></template>
      <el-table-column prop="authentik_sub" label="Authentik Sub" min-width="260" />
+      <el-table-column prop="username" label="Username" min-width="160" />
      <el-table-column prop="email" label="Email" min-width="220" />
      <el-table-column prop="display_name" label="顯示名稱" min-width="180" />
      <el-table-column prop="is_active" label="啟用" width="100">
        <template #default="{ row }">{{ row.is_active ? '是' : '否' }}</template>
      </el-table-column>
-      <el-table-column label="操作" width="120">
+      <el-table-column label="操作" width="220">
        <template #default="{ row }">
          <el-button size="small" @click="openEdit(row)">編輯</el-button>
+          <el-button size="small" type="warning" @click="handleResetPassword(row)">重設密碼</el-button>
        </template>
      </el-table-column>
    </el-table>

    <el-dialog v-model="showCreateDialog" title="新增會員" @close="resetCreateForm">
      <el-form ref="createFormRef" :model="createForm" :rules="createRules" label-width="120px">
+        <el-form-item label="Username" prop="username"><el-input v-model="createForm.username" /></el-form-item>
        <el-form-item label="Email" prop="email"><el-input v-model="createForm.email" /></el-form-item>
        <el-form-item label="顯示名稱" prop="display_name"><el-input v-model="createForm.display_name" /></el-form-item>
        <el-form-item label="權限群組">
@@ -47,6 +50,7 @@
    <el-dialog v-model="showEditDialog" title="編輯會員" @close="resetEditForm">
      <el-form :model="editForm" label-width="120px">
        <el-form-item label="Authentik Sub"><el-input :model-value="editForm.authentik_sub" disabled /></el-form-item>
+        <el-form-item label="Username"><el-input v-model="editForm.username" /></el-form-item>
        <el-form-item label="Email"><el-input v-model="editForm.email" /></el-form-item>
        <el-form-item label="顯示名稱"><el-input v-model="editForm.display_name" /></el-form-item>
        <el-form-item label="權限群組">
@@ -73,6 +77,7 @@ import {
  getMembers,
  upsertMember,
  updateMember,
+  resetMemberPassword,
  getMemberPermissionGroups,
  setMemberPermissionGroups
 } from '@/api/members'
@@ -88,6 +93,7 @@ const showCreateDialog = ref(false)
 const createFormRef = ref()
 const creating = ref(false)
 const createForm = ref({
+  username: '',
  email: '',
  display_name: '',
  group_keys: [],
@@ -95,6 +101,7 @@ const createForm = ref({
  sync_to_authentik: true
 })
 const createRules = {
+  username: [{ required: true, message: '請輸入 Username', trigger: 'blur' }],
  email: [{ required: true, message: '請輸入 Email', trigger: 'blur' }]
 }

@@ -102,6 +109,7 @@ const showEditDialog = ref(false)
 const saving = ref(false)
 const editForm = ref({
  authentik_sub: '',
+  username: '',
  email: '',
  display_name: '',
  group_keys: [],
@@ -126,6 +134,7 @@ async function load() {

 function resetCreateForm() {
  createForm.value = {
+    username: '',
    email: '',
    display_name: '',
    group_keys: [],
@@ -137,6 +146,7 @@ function resetCreateForm() {
 async function openEdit(row) {
  editForm.value = {
    authentik_sub: row.authentik_sub,
+    username: row.username || '',
    email: row.email || '',
    display_name: row.display_name || '',
    group_keys: [],
@@ -155,6 +165,7 @@ async function openEdit(row) {
 function resetEditForm() {
  editForm.value = {
    authentik_sub: '',
+    username: '',
    email: '',
    display_name: '',
    group_keys: [],
@@ -189,6 +200,7 @@ async function handleEdit() {
  saving.value = true
  try {
    await updateMember(editForm.value.authentik_sub, {
+      username: editForm.value.username || null,
      email: editForm.value.email || null,
      display_name: editForm.value.display_name || null,
      is_active: editForm.value.is_active,
@@ -206,5 +218,21 @@ async function handleEdit() {
  }
 }

+async function handleResetPassword(row) {
+  try {
+    const res = await resetMemberPassword(row.authentik_sub)
+    const pwd = res.data?.temporary_password || ''
+    if (!pwd) {
+      ElMessage.success('密碼已重設')
+      return
+    }
+    await navigator.clipboard.writeText(pwd)
+    ElMessage.success(`已重設密碼，臨時密碼已複製：${pwd}`)
+  } catch (err) {
+    const detail = err.response?.data?.detail
+    ElMessage.error(detail || '重設密碼失敗')
+  }
+}
+
 onMounted(load)
 </script>