library-picturebook-activity/frontend/TENANT_MANAGEMENT_GUIDE.md

# 租户管理页面使用指南

## 概述

租户管理页面已创建完成，只有超级租户才能访问和使用。该页面提供了完整的租户管理功能，包括租户的创建、编辑、删除和菜单分配。

## 功能特性

### 1. 租户列表

- 显示所有租户的基本信息
- 显示租户类型（超级租户/普通租户）
- 显示租户状态（有效/失效）
- 显示租户统计信息（用户数、角色数）
- 显示租户已分配的菜单

### 2. 创建租户

- 租户名称
- 租户编码（用于访问链接，必须唯一）
- 租户域名（可选，用于子域名访问）
- 租户描述

### 3. 编辑租户

- 修改租户基本信息
- 修改租户状态（有效/失效）
- 注意：租户编码创建后不可修改

### 4. 分配菜单

- 以树形结构展示所有可用菜单
- 支持多选
- 显示租户当前已分配的菜单
- 可以批量分配或取消分配菜单

### 5. 删除租户

- 删除租户及其所有关联数据
- 超级租户不能被删除
- 删除操作不可恢复

## 权限要求

所有操作都需要相应的权限：

- `tenant:create` - 创建租户
- `tenant:read` - 查看租户列表和详情
- `tenant:update` - 编辑租户和分配菜单
- `tenant:delete` - 删除租户

**注意**：只有超级租户的用户才拥有这些权限。

## 添加租户管理菜单

### 方式一：通过数据库直接添加

在数据库中执行以下SQL，为超级租户添加租户管理菜单：

```sql
-- 假设系统管理菜单的ID为某个值，需要根据实际情况调整 parent_id
-- 假设系统管理菜单的ID为 2（需要根据实际情况查询）

INSERT INTO menus (name, path, icon, component, parent_id, permission, sort, valid_state, create_time, modify_time)
VALUES (
  '租户管理',
  '/system/tenants',
  'TeamOutlined',
  'system/tenants/Index',
  2, -- 系统管理菜单的ID，需要根据实际情况调整
  'tenant:read',
  7, -- 排序，放在其他系统管理菜单之后
  1,
  NOW(),
  NOW()
);
```

### 方式二：通过后端API添加

使用超级管理员账号登录后，通过菜单管理接口添加：

```bash
POST /api/menus
Authorization: Bearer <token>
X-Tenant-Code: super

{
  "name": "租户管理",
  "path": "/system/tenants",
  "icon": "TeamOutlined",
  "component": "system/tenants/Index",
  "parentId": 2,  // 系统管理菜单的ID
  "permission": "tenant:read",
  "sort": 7
}
```

### 方式三：更新初始化脚本

修改 `backend/scripts/init-menus.ts` 或 `backend/scripts/init-super-tenant.ts`，在菜单初始化时添加租户管理菜单。

## 页面访问

添加菜单后，超级租户的用户登录后可以在"系统管理"菜单下看到"租户管理"选项。

访问路径：`/system/tenants`

## 使用示例

### 创建新租户

1. 点击"新增租户"按钮
2. 填写租户信息：
   - 租户名称：例如 "租户A"
   - 租户编码：例如 "tenant-a"（必须唯一，只能包含小写字母、数字、下划线和连字符）
   - 租户域名：例如 "tenant-a.example.com"（可选）
   - 描述：租户的描述信息
3. 点击"确定"创建

### 为租户分配菜单

1. 在租户列表中，点击某个租户的"分配菜单"按钮
2. 在弹出的菜单树中，勾选要分配给该租户的菜单
3. 点击"确定"保存

**注意**：

- 只有被分配的菜单才会在该租户的用户登录后显示
- 父菜单如果被分配，其子菜单也会自动显示（但需要单独分配才能访问）

### 编辑租户

1. 点击租户列表中的"编辑"按钮
2. 修改租户信息（租户编码不可修改）
3. 可以修改租户状态（有效/失效）
4. 点击"确定"保存

### 删除租户

1. 点击租户列表中的"删除"按钮
2. 确认删除操作
3. **警告**：删除租户会同时删除该租户的所有数据（用户、角色、权限等），此操作不可恢复

## 注意事项

1. **权限控制**：只有超级租户的用户才能看到和使用租户管理功能
2. **租户编码唯一性**：租户编码必须全局唯一，创建后不可修改
3. **超级租户保护**：超级租户不能被删除
4. **菜单分配**：菜单分配后，租户的用户登录后才能看到相应的菜单
5. **数据隔离**：每个租户的数据完全隔离，互不影响

## 故障排查

### 问题1：看不到租户管理菜单

**原因**：菜单未添加到数据库，或当前用户不是超级租户

**解决**：

- 确认菜单已添加到数据库
- 确认当前用户属于超级租户
- 确认用户有 `tenant:read` 权限
- 刷新页面或重新登录

### 问题2：无法创建租户

**原因**：缺少 `tenant:create` 权限

**解决**：

- 确认当前用户有创建租户的权限
- 联系超级管理员分配权限

### 问题3：菜单分配不生效

**原因**：菜单分配后，用户需要重新登录才能看到新菜单

**解决**：

- 让租户的用户重新登录
- 或者清除浏览器缓存后重新登录

## 技术实现

### 文件结构

```
frontend/src/
├── api/
│   └── tenants.ts          # 租户API接口
├── views/
│   └── system/
│       └── tenants/
│           └── Index.vue   # 租户管理页面
└── utils/
    └── menu.ts             # 菜单工具（已添加租户管理组件映射）
```

### API接口

所有API接口都在 `frontend/src/api/tenants.ts` 中定义：

- `getTenantsList()` - 获取租户列表
- `getTenantDetail()` - 获取租户详情
- `createTenant()` - 创建租户
- `updateTenant()` - 更新租户
- `deleteTenant()` - 删除租户
- `getTenantMenus()` - 获取租户菜单树

### 组件映射

在 `frontend/src/utils/menu.ts` 中添加了组件映射：

```typescript
"system/tenants/Index": () => import("@/views/system/tenants/Index.vue")
```

这样当菜单的 `component` 字段为 `system/tenants/Index` 时，系统会自动加载租户管理页面。