架构设计

本文档详细介绍 NexusBook API 的架构设计、目录结构和设计原则。

Document 核心概念架构

核心概念说明：

• Document - 统一的文档抽象，支持多种业务类型（订货单、产品、库存等）
• 核心数据层 - Properties（文档属性）、Metadata（字段定义）、Views（视图）、Data（数据行）、Settings（配置）
• 协作层 - Comments 支持在文档任何位置进行评论和讨论
• 工作流层 - Requests（变更请求）→ Revisions（修订历史）+ Approvals（审批流程）
• 查询能力 - 强大的过滤、排序、分组和聚合查询
• 认证授权 - OAuth2/OIDC 标准认证，基于 Scope 的权限控制

租户数据核心概念架构

NexusBook 采用多租户 SaaS 架构，通过 Organization（组织）和 Workspace（工作区）实现数据隔离和权限管理，设计理念参考 Miro 的协作模式。

核心概念说明

1. User（用户）- 独立身份实体

• 独立性：用户是系统中的独立实体，不依附于任何组织
• 自动组织：用户注册时，系统自动创建一个 Personal 类型的 Organization，用户成为该组织的 owner
• 多组织成员：一个用户可以同时是多个 Organization 的成员
• 身份验证：支持邮箱/密码、OAuth 第三方登录（Google、GitHub、微信、钉钉、飞书）

2. Organization（组织）- 租户边界

• 租户隔离：Organization 是数据隔离的基本单元，类似 Miro 的 Team
• 组织类型：
  • personal：个人组织（用户注册时自动创建）
  • team：团队组织
  • enterprise：企业组织
• 成员角色：
  • owner：组织拥有者，拥有所有权限（包括删除组织、转让所有权）
  • admin：管理员，可管理成员、工作区、组织设置
  • member：普通成员，可访问被授权的工作区
  • guest：访客，仅能访问特定资源
• 默认工作区：创建组织时自动创建一个默认 Workspace，通常作为主数据中心使用

3. Workspace（工作区）- 业务容器

Workspace 是 Organization 内的数据组织容器，所有 Workspace 地位平等，通过数据源引用机制实现跨工作区数据共享。

基本特性：

• 数据隔离：每个 Workspace 的 Document 数据默认独立隔离
• 灵活共享：可选择性地引用其他 Workspace 的特定 document type 数据
• 显式加入：组织成员需要被显式添加到 Workspace 才能访问其中的内容
• 成员角色：
  • owner：工作区负责人，可管理工作区和成员
  • editor：编辑者，可创建和编辑文档
  • viewer：查看者，只读权限
• 可见性控制：
  • public：组织内所有成员可见（建议主数据中心使用）
  • private：仅成员可见（建议业务工作区使用）

典型场景：

• 📚 主数据中心：存放组织级共享主数据（产品目录、供应商名录、标准菜谱等）
• 🍜 餐厅工作区：每家餐厅的独立运营管理（朝阳餐厅、西城餐厅等）
• 🛍️ 超市工作区：超市的采购与库存管理（海淀超市、西单超市等）
• 🚚 供应商工作区：供应商的订单与发货管理（绿源供应商、丰收农场等）
• 🏭 仓库工作区：仓库的进出库管理

4. 数据源引用机制（Data Source Reference）

Workspace 支持引用其他 Workspace 的特定 document type 数据，采用替换模式：

替换模式：

• Workspace B 引用 Workspace A 的 product 数据后，查询 product 只显示 A 的数据（只读）
• Workspace B 自己的 product 数据被隐藏（但未删除）
• 解除引用后，本地数据恢复显示

查询逻辑：

• 有活跃引用：查询源 Workspace 的数据，标记为只读
• 无引用或引用已停用：查询本地数据，可编辑

5. 成员管理机制

邀请流程（Invitation）：

加入申请流程（Join Request）：

6. 角色权限矩阵

Organization 角色权限：

Workspace 角色权限：

7. 数据隔离与安全

隔离层级：

Organization（租户级隔离）
  └── Workspace（业务级隔离）
        └── Document（文档级隔离）
              ├── Properties（文档属性）
              ├── Metadata（字段定义）
              ├── Data（数据行）
              └── Views（视图配置）

权限校验流程：

1. 用户身份验证：验证 JWT Token
2. 组织成员检查：确认用户是该 Organization 的成员
3. 工作区权限检查：确认用户在该 Workspace 中的角色
4. 操作权限验证：根据角色验证是否有权限执行操作
5. 数据访问控制：仅返回用户有权访问的数据

部分API

认证与用户

组织管理

工作区管理

数据源引用管理

数据引用说明：

• 当 workspace 引用其他 workspace 的 product 数据时，查询只返回源 workspace 的数据，本地数据被隐藏
• 解除引用后，查询恢复返回本地数据
• 数据源替换无损，本地数据不会丢失

权限控制说明：

目录结构

api/
├── main.tsp                    # 顶层入口
│
├── shared/                     # 共享基础模块
│   ├── common.tsp             # 通用类型（ApiResponse, Filter, Value...）
│   ├── constants.tsp          # 枚举定义
│   └── index.tsp              # 模块入口
│
├── auth/                       # 认证模块
│   ├── models.tsp             # OAuth2/OIDC 模型
│   └── index.tsp              # 模块入口
│
└── document/                   # 文档模块
    ├── core/                  # 核心数据模型
    │   ├── metadata.tsp       # 字段定义
    │   ├── data.tsp           # 数据行管理
    │   ├── properties.tsp     # 文档属性
    │   ├── views.tsp          # 视图配置
    │   ├── settings.tsp       # 设置
    │   └── index.tsp
    │
    ├── content/               # 内容协作
    │   ├── comments.tsp       # 评论系统
    │   └── index.tsp
    │
    ├── workflow/              # 工作流管理
    │   ├── approvals.tsp      # 审批流程
    │   ├── requests.tsp       # 变更请求
    │   ├── revisions.tsp      # 修订历史
    │   └── index.tsp
    │
    ├── aggregate/             # 聚合查询
    │   └── index.tsp
    │
    ├── operations/            # 预留目录
    └── index.tsp

架构层次

依赖关系说明：

• 实线箭头 - 直接依赖关系
• 虚线箭头 - 预留/可选依赖
• 颜色分层 - 蓝色（顶层）→ 橙色（基础）→ 粉色（认证）→ 绿色（业务）→ 紫色（扩展）

依赖原则：

1. 单向依赖 - 上层依赖下层，下层不依赖上层
2. 基础优先 - 所有模块都依赖 shared 基础层
3. 模块独立 - 同层模块之间尽量独立
4. 聚合组合 - aggregate 模块组合其他模块的功能

设计原则

1. 分层架构 - 清晰的 4 层结构（shared → auth → document → extensions）
2. 单一职责 - 每个模块功能明确，职责单一
3. 依赖管理 - 明确的依赖关系，避免循环依赖
4. 可扩展性 - 预留扩展目录，支持动态扩展
5. 模块化 - 高内聚低耦合，便于维护和测试

模块职责

数据流与工作流

工作流说明：

1. 直接应用 - 使用 ?apply=true 参数直接写入数据并生成修订
2. 变更请求 - 默认创建 Request，支持多人协作编辑
3. 审批流程 - 可选的多层级审批机制
4. 修订追踪 - 所有变更都会生成修订记录
5. 版本回滚 - 支持对比和回滚到任意历史版本

字段类型与值类型映射

文档类型路由

Provider 模式：

/api/v1/doc/{doc-type}/{doc-id}
              ↓
        Provider 解析
              ↓
    ┌─────────┼─────────┐
    ▼         ▼         ▼
 Product  Purchase   Invoice
 Provider  Provider  Provider

扩展新类型：

• 实现对应的 Provider
• 注册到路由系统
• 无需修改 API 定义

资源抽象

Doc: {doc-type} + {doc-id}
  ├── properties    # 文档属性（订单时间、门店、金额等）
  ├── metadata      # 字段定义
  ├── views         # 视图配置
  ├── data          # 数据行
  ├── comments      # 评论
  ├── revisions     # 修订历史
  ├── requests      # 变更请求
  ├── approval      # 审批流程
  └── settings      # 设置

下一步

• 查看 API 参考文档 了解详细的 API 端点
• 查看 开发指南 了解如何扩展和修改 API
• 查看 数据操作指南 了解查询和过滤功能