makemd/docs/用户层级架构说明.md

# 用户层级架构说明

## 1. 多租户层级结构

Crawlful Hub 采用多层级的用户架构设计，确保数据隔离和权限控制：

```
平台（Platform）
    ↓
商户/公司（Tenant/Organization）
    ↓
组织结构（Org Tree）
    ├── 部门A（主管）
    │     ├── 组A1（组长）
    │     │     ├── 员工1
    │     │     └── 员工2
    │     └── 组A2（组长）
    │           └── 员工3
    └── 部门B（主管）
          └── ...
```

## 2. 核心层级模型

### 2.1 层级关系
- **商户(Merchant)**: 最高层级，包含商户基本信息、认证状态、计费信息
- **部门(Department)**: 商户下的组织结构，由商户管理员创建和管理
- **店铺(Shop)**: 具体的电商店铺，属于商户或部门
- **用户(User)**: 系统使用者，关联到具体的商户、部门和店铺

### 2.2 数据隔离
- **租户隔离**: 不同商户的数据完全隔离
- **部门隔离**: 部门内用户只能访问部门相关数据
- **店铺隔离**: 店铺内操作只影响对应店铺

## 3. 权限系统（RBAC）

### 3.1 角色定义

| 角色 | 描述 | 权限范围 |
|------|------|----------|
| **ADMIN** | 系统管理员 | 所有资源的所有操作 |
| **MANAGER** | 运营主管 | 大部分资源的管理操作 |
| **OPERATOR** | 运营专员 | 基础运营操作 |
| **FINANCE** | 财务主管 | 财务相关操作 |
| **SOURCING** | 采购专家 | 采购相关操作 |
| **LOGISTICS** | 物流专家 | 物流相关操作 |
| **ANALYST** | 数据分析师 | 数据分析相关操作 |

### 3.2 店铺角色

| 角色 | 描述 | 权限范围 |
|------|------|----------|
| **owner** | 拥有者 | 删除店铺、管理授权、管理成员、所有权限 |
| **admin** | 管理员 | 管理商品、管理价格、管理订单、不可删除店铺 |
| **operator** | 运营 | 刊登、改价、查看数据 |
| **viewer** | 只读 | 查看数据、不可操作 |

## 4. 数据范围控制

### 4.1 数据范围类型

| 范围类型 | 英文 | 说明 | SQL过滤条件 |
|---------|------|------|------------|
| **SELF** | Self | 只看自己 | `WHERE created_by = {userId}` |
| **TEAM** | Team | 看自己组 | `WHERE team_id IN ({userTeams})` |
| **DEPT** | Department | 看自己部门 | `WHERE dept_id IN ({userDepts})` |
| **ORG** | Organization | 看整个公司 | `WHERE tenant_id = {tenantId}` |
| **ALL** | All | 全平台（超管） | 无过滤 |

### 4.2 授权模型

**核心原则**：
- 授权属于店铺，不属于用户
- 店铺属于主体（Owner），用户只是被授权使用

**店铺授权结构**：
```
Organization（公司）
    ↓
Shop（店铺）
    ↓
Auth（授权）
    ↑
User（使用者）
```

## 5. 技术实现

### 5.1 数据模型

- **用户表** (`cf_users`): 存储用户基本信息、角色、状态
- **租户表** (`cf_tenants`): 存储商户信息、配置、状态
- **部门表**: 存储组织结构信息
- **店铺表** (`cf_shops`): 存储店铺信息、平台类型、授权状态
- **会话表** (`cf_sessions`): 存储用户登录会话信息

### 5.2 核心服务

- **HierarchyService**: 处理用户层级关系和数据范围
- **RBACService**: 实现基于角色的访问控制
- **AuthService**: 处理用户认证和会话管理

### 5.3 权限检查

```typescript
// 权限检查中间件
export function checkPermission(permission: string) {
  return (req, res, next) => {
    if (!req.user.permissions.includes(permission)) {
      return res.status(403).json({ error: 'Permission denied' });
    }
    next();
  };
}
```

## 6. 安全考虑

1. **最小权限原则**: 用户只获得必要的权限
2. **权限审计**: 定期审计权限配置
3. **数据加密**: 加密敏感数据
4. **访问控制**: 严格控制数据访问
5. **审计日志**: 记录数据访问日志

## 7. 管理功能

### 7.1 后台管理系统

```
后台管理系统
├── 用户与权限管理
│   ├── 用户管理
│   ├── 角色管理
│   ├── 权限管理
│   └── 登录日志
├── 租户管理
│   ├── 租户列表
│   ├── 租户配置
│   ├── 配额管理
│   └── 租户隔离
├── 商户管理
│   ├── 商户入驻
│   ├── 商户审核
│   ├── 商户店铺
│   └── 商户结算
└── 其他模块...
```

### 7.2 用户管理功能

- **创建用户**: 添加新用户，分配角色和权限
- **修改用户**: 修改用户的角色和权限
- **删除用户**: 删除用户
- **禁用用户**: 暂时禁用用户
- **用户登录日志**: 记录用户登录历史

## 8. 实现优先级

### P0 - 核心功能 (立即完成)
1. **用户权限管理**
   - 用户CRUD
   - 角色管理
   - RBAC引擎

2. **租户管理**
   - 租户CRUD
   - 数据隔离
   - 配额管理

### P1 - 重要功能 (近期完成)
3. **审批中心**
   - 审批流程
   - 审批处理

4. **监控中心**
   - 系统监控
   - 告警管理

## 9. 总结

Crawlful Hub 的用户层级架构采用了多租户、多层级的设计，通过RBAC权限模型和数据范围控制，实现了灵活且安全的用户管理体系。系统支持商户→部门→店铺的三层架构，确保数据隔离和权限控制，同时提供了完整的后台管理功能。

这种设计不仅满足了企业级应用的安全需求，也为不同规模的商户提供了灵活的组织管理能力。