OneAuth/doc/architecture.md

# VBase 架构设计文档

## 1. 系统概述

VBase 是一个类似 **Supabase** 的 **Backend-as-a-Service (BaaS)** 平台，为个人开发者（2C）和团队/企业（2B）提供后端资源托管和权限管理服务。采用 Go 语言开发，基于 Vigo 框架构建。

### 1.1 产品定位：可私有化部署的 IAM + BaaS 平台

VBase 是一个**产品化**的解决方案，你可以将 VBase **售卖/部署**给终端客户，客户在自己的环境中独立运行 VBase 实例，完全隔离地管理自己的业务。

#### 三层级架构模型

```
┌─────────────────────────────────────────────────────────────┐
│  Layer 1: VBase 平台运营层 (你的 SaaS 平台)                    │
│  - 你是 VBase 产品的提供商                                   │
│  - 功能：实例管理、计费、监控、版本分发                        │
│  - 部署模式：托管部署 or 客户自托管                           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ 部署/交付
┌─────────────────────────────────────────────────────────────┐
│  Layer 2: VBase 实例层 (客户的独立部署)                        │
│  - 每个客户拥有一个完全独立的 VBase 实例                      │
│  - 独立数据库、独立用户体系、独立配置                          │
│  - 客户可以是：2C 产品 / 2B 产品 / 混合产品                   │
│  - 管理员：客户的技术负责人/运维                               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ 使用
┌─────────────────────────────────────────────────────────────┐
│  Layer 3: 客户业务层 (与你无关)                                │
│  - 客户用 VBase 管理自己的终端用户和业务项目                   │
│  ├─ 2C 场景：App 用户注册登录、个人数据管理                    │
│  ├─ 2B 场景：企业内部系统、团队协作                           │
│  └─ 混合场景：既有终端用户又有内部团队                         │
│  - 用户数据完全属于客户，与你无关                              │
└─────────────────────────────────────────────────────────────┘
```

#### 目标客户类型

| 客户类型 | 场景说明 | VBase 提供的价值 |
|----------|----------|-----------------|
| **2C 产品公司** | 社交 App、电商平台、内容社区等 | 用户认证、个人数据管理、权限控制 |
| **2B 产品公司** | SaaS 软件、企业管理系统 | 多租户隔离、组织架构、RBAC 权限 |
| **混合产品公司** | 既有 C 端用户又有 B 端管理 | 统一身份管理、分级权限控制 |

### 1.2 核心特性

- **项目-资源管理**: 用户可以创建多个项目，每个项目包含独立的后端资源
- **灵活的成员协作**: 支持邀请其他用户加入项目，分配不同角色权限
- **多层级权限控制**: 平台级 → 项目级 → 资源级的三级权限体系
- **RBAC + ABAC 权限模型**: 角色与策略结合的细粒度权限控制
- **OAuth2.0/OIDC 服务端**: 支持作为身份提供商，为应用提供认证服务
- **第三方登录集成**: Google、GitHub、微信等快速登录
- **JWT 认证**: 无状态的 Token 认证机制

### 1.3 技术栈

| 层级 | 技术 |
|------|------|
| 框架 | Vigo (Go Web Framework) |
| ORM | GORM |
| 数据库 | MySQL / PostgreSQL / SQLite |
| 缓存 | Redis |
| 认证 | JWT (github.com/golang-jwt/jwt) |
| 密码哈希 | bcrypt |

### 1.4 概念说明

#### 三层级角色体系

| 层级 | 角色 | 说明 | 权限范围 |
|------|------|------|----------|
| **平台层** | 平台管理员 | VBase 产品提供商（你） | 管理所有 VBase 实例 |
| **实例层** | 实例管理员 | 客户的技术负责人 | 管理自己的 VBase 实例配置 |
| **业务层** | 终端用户 | 客户的 C 端用户或 B 端成员 | 使用客户的产品功能 |

#### VBase 实例内部概念

在一个独立的 VBase 实例内部，包含以下核心概念：

**用户 (User)**: VBase 实例中的注册用户
- 可以创建多个项目
- 可以被邀请加入其他项目
- 在不同项目中可以有不同的角色

**项目/组织 (Project/Org)**: 资源管理的基本单元
- 对 2C 场景：对应一个 App 或产品
- 对 2B 场景：对应一个企业或部门
- 企业可以创建多个项目，也可以使用组织层级管理

**资源 (Resource)**: 项目内的后端资源
- 数据库、存储、函数、API 等
- 属于特定项目
- 通过项目权限控制访问

**角色 (Role)**: 项目内的权限集合
- 所有者 (Owner): 项目全部权限
- 管理员 (Admin): 管理项目和成员
- 开发者 (Developer): 读写资源
- 访客 (Viewer): 只读访问

---

## 2. 系统架构

### 2.1 整体架构图

```
┌─────────────────────────────────────────────────────────────┐
│                        Client Layer                          │
│  (Web App / Mobile App / Third-party Services)              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       API Gateway                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  Auth Filter │  │ Rate Limiter │  │  Org Context │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Application Layer                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │   Auth   │ │   User   │ │   Org    │ │  OAuth   │       │
│  │ Handler  │ │ Handler  │ │ Handler  │ │ Handler  │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
│                                                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                     │
│  │   Role   │ │  Policy  │ │Permission│                     │
│  │ Handler  │ │ Handler  │ │ Service  │                     │
│  └──────────┘ └──────────┘ └──────────┘                     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Service Layer                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Permission │  │     JWT      │  │   Crypto     │      │
│  │   Checker    │  │   Service    │  │   Service    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Data Layer                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│  │   User   │  │   Org    │  │  OAuth   │  ...             │
│  │  Model   │  │  Model   │  │  Model   │                  │
│  └──────────┘  └──────────┘  └──────────┘                  │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  MySQL/PostgreSQL  │      Redis        │  Repository   │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
```

---

## 3. 部署模式：VBase 作为产品交付

VBase 设计为可私有化部署的产品，支持两种交付模式：

### 3.1 模式一：托管部署（你帮客户部署运维）

```
┌─────────────────────────────────────────────────────────────┐
│                    你的云基础设施                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │ 客户A实例    │  │ 客户B实例    │  │ 客户C实例    │          │
│  │ (2C产品)    │  │ (2B产品)    │  │ (混合产品)   │          │
│  │             │  │             │  │             │          │
│  │ DB: A_db    │  │ DB: B_db    │  │ DB: C_db    │          │
│  │ Redis: A_1  │  │ Redis: B_1  │  │ Redis: C_1  │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
└─────────────────────────────────────────────────────────────┘
```

**特点：**
- 你在自己的云基础设施上为客户部署独立的 VBase 实例
- 每个实例完全隔离（独立数据库、独立 Redis）
- 你负责运维，客户只管使用
- 可按照实例数量、资源使用量计费

**适用客户：** 没有运维能力的小团队，希望快速使用

### 3.2 模式二：客户自托管（客户自己部署）

```
┌─────────────────────────────────────────────────────────────┐
│                      客户 A 的基础设施                         │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                  VBase 实例                          │   │
│  │  ┌──────────────┐  ┌──────────────┐               │   │
│  │  │   用户认证    │  │   权限管理    │               │   │
│  │  │   (2C用户)   │  │   (2B组织)   │               │   │
│  │  └──────────────┘  └──────────────┘               │   │
│  │                                                    │   │
│  │  ┌──────────────┐  ┌──────────────┐               │   │
│  │  │   数据库资源  │  │   存储资源    │               │   │
│  │  └──────────────┘  └──────────────┘               │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

**特点：**
- 客户在自己的环境中部署 VBase（云服务器、私有云、K8s）
- 数据完全属于客户，与你无关
- 客户自己运维，或者购买你的运维支持服务
- 通常按许可（License）或订阅模式收费

**适用客户：** 有数据合规要求的企业，有自己运维能力的团队

### 3.3 两种模式的对比

| 维度 | 托管部署 | 客户自托管 |
|------|----------|------------|
| **部署位置** | 你的云基础设施 | 客户的基础设施 |
| **数据归属** | 客户拥有，你代管 | 客户完全拥有 |
| **运维责任** | 你负责 | 客户负责 |
| **计费模式** | 按用量/实例数 | 按 License/订阅 |
| **定制化** | 受限 | 完全可定制 |
| **网络要求** | 需要公网访问 | 可内网部署 |

### 3.4 关键设计：完全隔离

无论哪种模式，**每个 VBase 实例都是完全独立的**：

```go
// 实例级别的完全隔离
// - 独立的数据库连接
// - 独立的 Redis 命名空间
// - 独立的 JWT 密钥
// - 独立的配置

type VBaseInstance struct {
    InstanceID   string  // 实例唯一标识
    DatabaseDSN  string  // 独立数据库
    RedisPrefix  string  // Redis 前缀隔离
    JWTSecret    string  // 独立 JWT 密钥
    Config       InstanceConfig
}
```

这种设计确保：
1. 客户 A 的数据与客户 B 完全隔离
2. 一个实例的故障不影响其他实例
3. 客户可以独立升级、备份、迁移自己的实例

---

## 4. 目录结构（Vigo 规范）

```
vbase/
├── api/                  # API 层（按资源模块组织）
│   ├── init.go          # API根路由，注册全局中间件
│   ├── auth/            # 认证模块
│   │   ├── init.go      # 路由注册
│   │   ├── login.go     # 登录/登出/刷新
│   │   ├── register.go  # 用户注册
│   │   ├── me.go        # 当前用户信息
│   │   └── thirdparty.go# 第三方登录
│   ├── user/            # 用户管理
│   │   ├── init.go
│   │   ├── get.go
│   │   ├── list.go
│   │   ├── create.go
│   │   ├── patch.go
│   │   ├── del.go
│   │   └── status.go
│   ├── org/             # 组织/项目管理
│   │   ├── init.go
│   │   ├── get.go
│   │   ├── list.go
│   │   ├── create.go
│   │   ├── patch.go
│   │   ├── del.go
│   │   ├── tree.go
│   │   └── member.go
│   ├── oauth/           # OAuth2.0/OIDC 服务端
│   │   ├── init.go
│   │   ├── authorize.go # 授权端点
│   │   ├── token.go     # 令牌端点
│   │   ├── revoke.go    # 撤销令牌
│   │   ├── oidc.go      # OIDC 支持
│   │   └── client.go    # 客户端管理
│   └── middleware/      # 中间件
│       ├── auth.go      # JWT 认证
│       ├── org.go       # 组织上下文
│       └── ratelimit.go # 限流
│
├── models/              # 数据模型层（GORM）
│   ├── init.go          # 模型注册、迁移
│   ├── base.go          # 基础模型
│   ├── user.go          # User/Identity/Session
│   ├── org.go           # Org/OrgMember
│   ├── policy.go        # Policy/Role
│   └── oauth.go         # OAuthClient/OAuthToken
│
├── cfg/                 # 配置（Vigo 自动解析）
│   ├── cfg.go           # Options 结构体
│   ├── db.go            # 数据库连接
│   └── sms.go           # SMS 配置
│
├── cli/                 # 独立运行入口
│   └── main.go          # 启动服务器/数据库迁移
│
├── libs/                # 工具库
│   ├── cache/           # Redis 缓存封装
│   ├── jwt/             # JWT 工具
│   ├── crypto/          # 加密工具
│   ├── sms_providers/   # 短信服务商
│   ├── utils/           # 通用工具
│   └── webdav/          # WebDAV 实现
│
├── init.go              # 项目根路由（vbase.Router）
├── doc/                 # 文档
└── ui/                  # 前端
```

### 使用方式

**独立运行：**
```bash
go run cli/main.go
```

**集成到其他项目：**
```go
import "github.com/veypi/vbase"

// 在你的路由中挂载 vbase
router.Extend("vb", vbase.Router)  // 所有 vbase API 将通过 /vb/api/... 访问
```

---

## 4. 核心模块设计

### 4.1 认证模块

#### JWT Token 结构

```go
// Claims JWT 声明
type Claims struct {
    jwt.RegisteredClaims
    UserID   string    `json:"user_id"`
    Username string    `json:"username"`
    Nickname string    `json:"nickname"`
    Avatar   string    `json:"avatar"`
    Email    string    `json:"email"`
    Orgs     []OrgClaim `json:"orgs"`  // 用户所属组织
    Type     string     `json:"type"`  // access/refresh
}
```

#### 认证流程

1. **登录**: 验证用户名密码 → 生成 Token 对 → 保存会话
2. **访问**: 验证 Token → 解析用户上下文 → 组织上下文
3. **刷新**: 验证 Refresh Token → 生成新 Token 对 → 失效旧 Token
4. **登出**: Token 加入黑名单 → 标记会话失效

### 4.2 权限模块

#### 权限层级

VBase 采用三级权限体系：

```
┌─────────────────────────────────────────────────────────────┐
│                    1. 平台级权限 (Platform)                  │
│  - 用户管理自己的账号                                        │
│  - 创建项目                                                 │
│  - 管理第三方登录绑定                                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    2. 项目级权限 (Project)                   │
│  - 项目设置管理                                              │
│  - 成员邀请和管理                                            │
│  - 资源创建和管理                                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    3. 资源级权限 (Resource)                  │
│  - 数据库读写                                                │
│  - 存储操作                                                  │
│  - 函数调用                                                  │
└─────────────────────────────────────────────────────────────┘
```

#### 权限模型: RBAC + ABAC

**策略模型:**
```go
type Policy struct {
    Resource  string // 资源: user/org/resource/*
    Action    string // 操作: create/read/update/delete/*
    Effect    string // 效果: allow/deny
    Condition string // 条件: "owner", "org_member", 或复杂表达式
    Scope     string // 作用域: platform/org/resource
}
```

**权限检查流程:**

```
┌─────────────┐
│   请求进入   │
└──────┬──────┘
       ▼
┌─────────────┐    命中    ┌─────────────┐
│  检查缓存    │──────────→│   返回结果   │
└──────┬──────┘            └─────────────┘
       │ 未命中
       ▼
┌─────────────┐
│ 检查组织所有者│──────────→│  允许(缓存)  │
└──────┬──────┘            └─────────────┘
       │ 不是所有者
       ▼
┌─────────────┐
│ 获取用户角色 │
└──────┬──────┘
       ▼
┌─────────────┐
│ 获取角色策略 │
└──────┬──────┘
       ▼
┌─────────────┐    Deny     ┌─────────────┐
│ 检查Deny策略 │───────────→│  拒绝(缓存)  │
└──────┬──────┘              └─────────────┘
       │ 无Deny
       ▼
┌─────────────┐    Allow    ┌─────────────┐
│ 检查Allow策略│───────────→│  允许(缓存)  │
└──────┬──────┘              └─────────────┘
       │ 无Allow
       ▼
┌─────────────┐
│  默认拒绝    │───────────→│  拒绝(缓存)  │
└─────────────┘              └─────────────┘
```

#### 缓存策略

- **缓存键**: `perm:{user_id}:{org_id}:{resource}:{action}`
- **TTL**: 1 分钟
- **缓存失效**: 角色/策略变更时清除相关缓存

### 4.3 项目/组织模块

VBase 中的 "Org" 概念灵活适配不同场景：

#### 场景1: 个人项目 (2C)

```
个人开发者
└── 我的项目A (Org: owner=个人)
└── 我的项目B (Org: owner=个人)
```

- 每个项目是一个独立的 Org
- 资源完全隔离
- 可以邀请其他用户协作

#### 场景2: 团队协作 (2B)

```
创业公司团队
├── Web应用项目 (Org)
│   ├── 所有者: CEO
│   ├── 管理员: CTO
│   └── 开发者: 员工A, 员工B
└── 移动应用项目 (Org)
    ├── 所有者: CEO
    └── ...
```

#### 场景3: 企业多层级 (2B Enterprise)

```
企业层级 (可选功能)
总公司 (level=0)
├── 技术中台 (level=1, Org)
├── 业务线A (level=1)
│   ├── 项目1 (level=2, Org)
│   └── 项目2 (level=2, Org)
└── 业务线B (level=1)
    └── 项目3 (level=2, Org)
```

### 4.4 典型客户场景示例

以下示例展示 VBase 作为产品交付的完整链路：

#### 示例1: 2C 产品公司（社交 App）

```
你（VBase 提供商）
│
├─ 售卖 VBase 实例给「社交App公司」
│
▼
客户：社交App公司（2C产品）
│
├─ 部署 VBase 实例到自己的服务器（自托管模式）
│
├─ 技术负责人配置 VBase：
│   ├─ 开启 App 用户注册/登录
│   ├─ 配置数据库存储用户资料
│   └─ 设置存储桶保存用户头像
│
▼
终端用户：社交 App 的普通用户
   ├─ 注册账号（存储在 VBase）
   ├─ 登录获取 JWT Token
   ├─ 上传头像到 VBase 存储
   └─ 查询好友列表（VBase 数据库）
```

**关键点：**
- 社交App公司的用户数据完全在自己的 VBase 实例中
- 你作为 VBase 提供商，接触不到终端用户数据
- 社交App公司按需购买 License 或订阅服务

#### 示例2: 2B 产品公司（SaaS 软件）

```
你（VBase 提供商）
│
├─ 托管部署 VBase 实例给「企业SaaS公司」
│   （部署在你的云服务器上）
│
▼
客户：企业SaaS公司（2B产品）
│
├─ 使用 VBase 管理自己的企业客户
│   ├─ 每个企业客户 = VBase 中的一个 Org
│   ├─ 企业内的部门 = Org 下的子组织
│   └─ 企业员工 = OrgMember
│
▼
终端用户：SaaS 软件的企业用户
   ├─ 企业 A 的员工使用 VBase 登录 SaaS
   ├─ 按角色分配权限（管理员/普通员工）
   └─ 企业间的数据通过 VBase 完全隔离
```

**关键点：**
- SaaS 公司用 VBase 做租户隔离（多租户架构）
- 你帮 SaaS 公司运维 VBase 实例，按实例数/用户量收费
- SaaS 公司的终端企业用户与你无直接关系

#### 示例3: 混合产品公司（2C + 2B）

```
你（VBase 提供商）
│
├─ 售卖两个 VBase 实例给「电商平台公司」
│  （一个给 C 端，一个给 B 端管理后台）
│
▼
客户：电商平台公司（混合产品）
│
├─ 实例1：C 端用户系统
│   ├─ 消费者注册/登录
│   ├─ 购物车、订单数据
│   └─ 用户画像存储
│
└─ 实例2：B 端商家管理系统
    ├─ 商家入驻/审核
    ├─ 商家员工权限管理
    └─ 运营数据分析
```

**关键点：**
- 同一客户的不同业务线可以用独立 VBase 实例
- 完全物理隔离，符合数据合规要求
- 你提供统一的管理控制台给客户技术团队

#### 数据隔离

- **项目隔离**: 每个 Org 是独立的资源边界
- **用户-项目关联**: 通过 `OrgMember` 表维护多对多关系
- **资源归属**: 所有资源通过 `org_id` 归属到具体项目
- **跨项目访问**: 需要显式授权，默认隔离

### 4.5 BaaS 资源管理模块

作为 Supabase-like BaaS 平台，VBase 提供以下后端资源管理能力：

#### 资源类型

| 资源类型 | 说明 | 典型操作 |
|----------|------|----------|
| **Database** | 数据库表、集合 | 创建表、查询、修改结构、删除表 |
| **Storage** | 文件存储 | 上传、下载、删除、管理存储桶 |
| **Function** | 边缘函数/云函数 | 部署、调用、更新、删除 |
| **API Key** | 访问密钥 | 创建、删除、刷新、权限绑定 |

#### 资源权限模型

```
项目 (Org)
├── 资源组 (Resource Group)
│   ├── 数据库资源
│   │   ├── table_1 (owner: user_a)
│   │   └── table_2 (owner: user_b)
│   ├── 存储资源
│   │   ├── bucket_images (public)
│   │   └── bucket_private (private)
│   └── 函数资源
│       ├── function_api (callable)
│       └── function_cron (internal)
```

#### 资源访问控制

```go
// 资源操作前检查权限
func AccessResource(userID, orgID, resourceType, action string) error {
    checker := service.NewPermissionChecker()
    result, err := checker.Check(userID, orgID, resourceType, action, nil)
    if err != nil || !result.Allowed {
        return vigo.ErrForbidden.WithString(result.Reason)
    }

    // 额外检查资源级别的细粒度权限
    // 例如：只能修改自己创建的表
    return nil
}
```

### 4.5 OAuth2.0 服务端

#### 支持的授权流程

| 流程 | 说明 | 适用场景 |
|------|------|----------|
| Authorization Code | 授权码模式 | 服务端应用，最安全 |
| Implicit | 简化模式 | SPA/移动端（不推荐） |
| Client Credentials | 客户端凭证 | 服务间调用 |
| Refresh Token | 刷新令牌 | 延长会话 |

#### 安全特性

- **PKCE**: 防止授权码拦截攻击
- **State**: CSRF 防护
- **Redirect URI 白名单**: 严格匹配
- **Token 过期**: Access Token 1小时，Refresh Token 30天

---

## 5. 数据模型

### 5.1 实体关系图 (ER Diagram)

```
┌─────────────────────────────────────────────────────────────────┐
│                          平台层 (Platform)                       │
├─────────────┐       ┌─────────────┐       ┌─────────────┐      │
│    User     │       │   Identity  │       │   Session   │      │
│  (平台用户)  │       │  (第三方绑定)│       │  (登录会话)  │      │
├─────────────┤       ├─────────────┤       ├─────────────┤      │
│ id (PK)     │◄──────┤ user_id     │       │ id (PK)     │      │
│ username    │       │ provider    │       │ user_id     │      │
│ password    │       │ provider_uid│       │ token_id    │      │
│ email       │       │ access_token│       │ type        │      │
│ status      │       └─────────────┘       │ expires_at  │      │
└──────┬──────┘                             └─────────────┘      │
       │                                                          │
       │         多对多关系（用户-项目）                            │
       │         ┌─────────────┐       ┌─────────────┐           │
       │         │  OrgMember  │       │     Org     │           │
       │         │  (项目成员)  │       │   (项目)     │           │
       │         ├─────────────┤       ├─────────────┤           │
       └────────►│ user_id     │◄──────┤ id (PK)     │           │
                 │ org_id      │──────►│ name        │           │
                 │ role_ids    │       │ code        │           │
                 │ status      │       │ owner_id    │           │
                 └─────────────┘       │ parent_id*  │           │
                                        │ path*       │           │
                                        └─────────────┘           │
                                               │                  │
                                               │ 1:N              │
                                               ▼                  │
                                        ┌─────────────┐          │
                                        │   Resource  │          │
                                        │  (项目资源)  │          │
                                        │ (db/storage)│          │
                                        └─────────────┘          │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                          权限层 (Permission)                     │
├─────────────┐       ┌─────────────┐       ┌─────────────┐      │
│    Role     │       │ RolePolicy  │       │   Policy    │      │
│  (项目角色)  │       │  (角色策略)  │       │   (策略)     │      │
├─────────────┤       ├─────────────┤       ├─────────────┤      │
│ id (PK)     │◄──────┤ role_id     │       │ id (PK)     │      │
│ org_id      │       │ policy_id   │──────►│ code        │      │
│ name        │       └─────────────┘       │ resource    │      │
│ policy_ids  │                             │ action      │      │
│ scope       │                             │ effect      │      │
└─────────────┘                             │ condition   │      │
                                            │ scope       │      │
                                            └─────────────┘      │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                          OAuth层 (Identity)                      │
├─────────────┐       ┌─────────────┐       ┌─────────────┐      │
│OAuthClient  │       │OAuthAuthz   │       │ OAuthToken  │      │
│  (OAuth应用) │       │  (授权码)    │       │  (访问令牌)  │      │
├─────────────┤       ├─────────────┤       ├─────────────┤      │
│ id (PK)     │◄──────┤ client_id   │       │ id (PK)     │      │
│ client_id   │       │ user_id     │◄──────┤ client_id   │      │
│ client_secret│      │ code        │       │ user_id     │      │
│ redirect_uris│      │ expires_at  │       │ access_token│      │
│ owner_id    │       └─────────────┘       │ refresh_token│      │
│ org_id      │                             │ org_id      │      │
└─────────────┘                             └─────────────┘      │
└─────────────────────────────────────────────────────────────────┘
```

### 5.2 关键模型说明

**User (用户)**
- 平台级唯一用户账号
- 可同时参与多个项目
- 支持第三方账号绑定

**Org (项目/组织)**
- 资源管理的基本单元
- 对2C场景: 一个项目 = 一个 Org
- 对2B场景: 可以是项目或企业部门
- 支持层级结构（可选）

**OrgMember (项目成员)**
- 维护用户与项目的关联
- 记录角色分配
- 支持多种成员状态（待审核、正常、禁用）

**Role (角色)**
- 项目内定义的权限集合
- 系统预置角色: owner, admin, developer, viewer
- 支持自定义角色

---

## 6. 接口设计原则

### 6.1 RESTful API

- 使用 HTTP 方法表示操作: GET/POST/PATCH/DELETE
- 使用复数名词表示资源: /users, /orgs
- 使用路径参数表示 ID: /users/{user_id}

### 6.2 请求/响应规范

**成功响应:**
```json
{
  "code": 200,
  "message": "success",
  "data": { ... }
}
```

**错误响应:**
```json
{
  "code": 400,
  "message": "error description",
  "data": null
}
```

### 6.3 分页规范

```json
{
  "items": [...],
  "total": 100,
  "page": 1,
  "page_size": 10,
  "total_pages": 10
}
```

---

## 7. 安全设计

### 7.1 认证安全

- **密码策略**: bcrypt 哈希，成本因子 12
- **JWT 安全**: HS256 算法，密钥最小 32 字节
- **Token 过期**: 短时效 Access Token + 长时效 Refresh Token
- **Token 撤销**: 黑名单机制

### 7.2 接口安全

- **限流**: 基于 IP 和用户 ID 的滑动窗口限流
- **CSRF 防护**: State 参数、SameSite Cookie
- **SQL 注入**: GORM 参数化查询
- **XSS 防护**: 响应头设置 Content-Type

### 7.3 OAuth 安全

- **PKCE**: 所有移动端/SPA 必须使用
- **Redirect URI 严格匹配**: 包括路径和查询参数
- **Scope 限制**: 每个客户端有允许的范围白名单

---

## 8. 扩展性设计

### 8.1 水平扩展

- **无状态服务**: 不依赖本地存储，可水平扩展
- **共享缓存**: Redis 集群支持
- **数据库读写分离**: GORM 支持读写分离配置

### 8.2 插件化

- **中间件链**: 可插拔的中间件设计
- **策略引擎**: 支持自定义条件表达式
- **第三方登录**: 易于添加新的 OAuth 提供商

---

## 9. 监控与日志

### 9.1 日志规范

- 请求日志: 方法、路径、耗时、状态码
- 错误日志: 堆栈追踪、上下文信息
- 审计日志: 敏感操作记录

### 9.2 指标监控

- QPS、响应时间、错误率
- 缓存命中率
- 数据库连接池状态