jiebanke/docs/admin-design.md

# 结伴客系统后台管理设计文档

## 1. 概述

### 1.1 设计目标
为结伴客系统提供功能完善、安全可靠的后台管理系统，支持系统管理员对用户、内容、商家、数据等进行全面管理。

### 1.2 设计原则
- **安全性**: 采用RBAC权限控制，操作日志记录，敏感操作二次确认
- **易用性**: 界面简洁直观，操作流程清晰
- **扩展性**: 模块化设计，支持功能扩展
- **性能**: 支持大数据量操作，响应快速

## 2. 系统架构

### 2.1 技术栈
- **前端**: Vue 3 + TypeScript + Ant Design Vue
- **后端**: Node.js + Express + MySQL + Redis
- **认证**: JWT + RBAC权限控制
- **部署**: Docker + Nginx

### 2.2 模块划分
```
后台管理系统
├── 认证模块
├── 用户管理模块
├── 内容管理模块
├── 商家管理模块
├── 数据统计模块
├── 权限管理模块
├── 系统配置模块
└── 操作日志模块
```

## 3. 功能模块设计

### 3.1 认证模块
#### 3.1.1 登录功能
- 管理员账号密码登录
- JWT Token认证
- 登录状态保持
- 安全退出

#### 3.1.2 权限验证
- 接口级别权限控制
- 页面级别权限控制
- 按钮级别权限控制

### 3.2 用户管理模块
#### 3.2.1 用户列表
- 分页显示用户信息
- 搜索过滤功能
- 用户状态管理
- 用户详情查看

#### 3.2.2 用户操作
- 启用/禁用用户
- 重置用户密码
- 查看用户行为日志

### 3.3 内容管理模块
#### 3.3.1 内容审核
- 待审核内容列表
- 内容详情查看
- 审核通过/拒绝
- 批量审核操作

#### 3.3.2 内容管理
- 已发布内容管理
- 违规内容处理
- 内容统计分析

### 3.4 商家管理模块
#### 3.4.1 商家审核
- 商家入驻申请列表
- 商家资质审核
- 审核结果通知

#### 3.4.2 商家管理
- 商家信息管理
- 商家状态控制
- 商家数据统计

### 3.5 数据统计模块
#### 3.5.1 系统概览
- 用户统计数据
- 订单统计数据
- 内容统计数据
- 商家统计数据

#### 3.5.2 趋势分析
- 用户增长趋势
- 订单趋势分析
- 收入趋势分析
- 数据图表展示

#### 3.5.3 数据导出
- CSV格式导出
- Excel格式导出
- 自定义时间范围

### 3.6 权限管理模块
#### 3.6.1 角色管理
- 角色列表查看
- 角色创建/编辑
- 角色权限分配
- 角色删除

#### 3.6.2 权限管理
- 权限列表查看
- 权限分组管理
- 权限分配

#### 3.6.3 用户角色分配
- 用户角色管理
- 批量角色分配
- 角色权限验证

### 3.7 系统配置模块
#### 3.7.1 基础配置
- 网站基本信息
- 系统参数配置
- 上传文件配置
- 邮件短信配置

#### 3.7.2 配置管理
- 配置项列表
- 配置值修改
- 配置分组管理
- 配置版本控制

### 3.8 操作日志模块
#### 3.8.1 日志查询
- 操作日志列表
- 高级搜索功能
- 日志详情查看

#### 3.8.2 日志分析
- 操作频率统计
- 异常操作检测
- 安全审计报告

## 4. 数据库设计

### 4.1 核心表结构
#### 4.1.1 管理员表 (admins)
```sql
CREATE TABLE admins (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) NOT NULL UNIQUE,
    password VARCHAR(255) NOT NULL,
    email VARCHAR(100),
    real_name VARCHAR(50),
    avatar VARCHAR(255),
    status ENUM('active', 'inactive') DEFAULT 'active',
    last_login_at DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

#### 4.1.2 角色表 (roles)
```sql
CREATE TABLE roles (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(50) NOT NULL UNIQUE,
    description VARCHAR(255),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

#### 4.1.3 权限表 (permissions)
```sql
CREATE TABLE permissions (
    id VARCHAR(50) PRIMARY KEY,
    name VARCHAR(50) NOT NULL,
    description VARCHAR(255),
    category VARCHAR(50),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

#### 4.1.4 角色权限表 (role_permissions)
```sql
CREATE TABLE role_permissions (
    role_id BIGINT NOT NULL,
    permission_id VARCHAR(50) NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (role_id, permission_id),
    FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE,
    FOREIGN KEY (permission_id) REFERENCES permissions(id) ON DELETE CASCADE
);
```

#### 4.1.5 管理员角色表 (admin_roles)
```sql
CREATE TABLE admin_roles (
    admin_id BIGINT NOT NULL,
    role_id BIGINT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (admin_id, role_id),
    FOREIGN KEY (admin_id) REFERENCES admins(id) ON DELETE CASCADE,
    FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE
);
```

#### 4.1.6 管理员操作日志表 (admin_operation_logs)
```sql
CREATE TABLE admin_operation_logs (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    admin_id BIGINT NOT NULL,
    admin_name VARCHAR(50) NOT NULL,
    module VARCHAR(50) NOT NULL,
    operation VARCHAR(100) NOT NULL,
    target_id VARCHAR(100),
    target_type VARCHAR(50),
    request_method VARCHAR(10),
    request_url VARCHAR(500),
    request_params TEXT,
    ip_address VARCHAR(45),
    user_agent VARCHAR(500),
    status ENUM('success', 'failed') NOT NULL,
    error_message TEXT,
    execution_time INT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_admin_id (admin_id),
    INDEX idx_module (module),
    INDEX idx_operation (operation),
    INDEX idx_status (status),
    INDEX idx_created_at (created_at)
);
```

#### 4.1.7 系统配置表 (system_configs)
```sql
CREATE TABLE system_configs (
    id VARCHAR(50) PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    value TEXT NOT NULL,
    type ENUM('string', 'number', 'boolean', 'text', 'json') DEFAULT 'string',
    group_name VARCHAR(50) DEFAULT 'general',
    description VARCHAR(255),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_group (group_name)
);
```

### 4.2 数据关系图
```mermaid
erDiagram
    admins ||--o{ admin_roles : has
    roles ||--o{ admin_roles : assigned
    roles ||--o{ role_permissions : has
    permissions ||--o{ role_permissions : included
    admins ||--o{ audit_logs : creates
    
    admins {
        bigint id
        varchar username
        varchar password
        varchar email
        varchar real_name
        varchar avatar
        enum status
        datetime last_login_at
        datetime created_at
        datetime updated_at
    }
    
    roles {
        bigint id
        varchar name
        varchar description
        datetime created_at
        datetime updated_at
    }
    
    permissions {
        varchar id
        varchar name
        varchar description
        varchar category
        datetime created_at
    }
```

## 5. API接口设计

### 5.1 认证接口
- `POST /admin/auth/login` - 管理员登录
- `GET /admin/auth/me` - 获取当前管理员信息
- `POST /admin/auth/logout` - 退出登录
- `POST /admin/auth/refresh` - 刷新Token

### 5.2 用户管理接口
- `GET /admin/users` - 获取用户列表
- `GET /admin/users/{id}` - 获取用户详情
- `PUT /admin/users/{id}/status` - 更新用户状态

### 5.3 内容管理接口
- `GET /admin/contents` - 获取内容列表
- `GET /admin/contents/{id}` - 获取内容详情
- `PUT /admin/contents/{id}/review` - 审核内容
- `POST /admin/contents/batch-review` - 批量审核内容

### 5.4 商家管理接口
- `GET /admin/merchant-applications` - 获取商家申请列表
- `PUT /admin/merchant-applications/{id}/review` - 审核商家申请
- `GET /admin/merchants` - 获取商家列表
- `PUT /admin/merchants/{id}/status` - 更新商家状态

### 5.5 数据统计接口
- `GET /admin/statistics` - 获取系统统计数据
- `GET /admin/statistics/trend` - 获取数据趋势
- `GET /admin/export/{type}` - 导出数据

### 5.6 权限管理接口
- `GET /admin/roles` - 获取角色列表
- `POST /admin/roles` - 创建角色
- `PUT /admin/roles/{id}` - 更新角色
- `DELETE /admin/roles/{id}` - 删除角色
- `GET /admin/permissions` - 获取权限列表
- `POST /admin/users/{userId}/roles` - 分配用户角色

### 5.7 系统配置接口
- `GET /admin/system-configs` - 获取系统配置
- `PUT /admin/system-configs/{id}` - 更新系统配置
- `POST /admin/system-configs/batch-update` - 批量更新配置

### 5.8 操作日志接口
- `GET /admin/operation-logs` - 获取操作日志列表
- `GET /admin/operation-logs/{id}` - 获取操作日志详情
- `GET /admin/operation-logs/export` - 导出操作日志
- `GET /admin/operation-logs/statistics` - 获取操作统计

## 6. 安全设计

### 6.1 认证安全
- JWT Token认证机制
- Token过期时间设置
- 密码加密存储（BCrypt）
- 登录失败次数限制

### 6.2 权限安全
- RBAC权限控制模型
- 接口级别权限验证
- 数据访问权限控制

### 6.3 操作安全
- 敏感操作二次确认
- 操作日志记录
- IP地址限制
- 操作频率限制

### 6.4 数据安全
- SQL注入防护
- XSS攻击防护
- CSRF攻击防护
- 数据加密传输（HTTPS）

## 7. 性能优化

### 7.1 数据库优化
- 合理的索引设计
- 查询性能优化
- 分页查询支持
- 数据库连接池

### 7.2 缓存优化
- Redis缓存应用
- 热点数据缓存
- 缓存更新策略
- 缓存失效机制

### 7.3 接口优化
- 接口响应时间优化
- 批量操作支持
- 异步处理机制
- 数据压缩传输

## 8. 部署方案

### 8.1 环境划分
- 开发环境（Development）
- 测试环境（Testing）
- 预生产环境（Staging）
- 生产环境（Production）

### 8.2 部署架构
```
负载均衡 (Nginx)
├── 后台管理前端 (Vue)
├── 后端API服务 (Spring Boot)
├── 数据库集群 (MySQL)
└── 缓存集群 (Redis)
```

### 8.3 监控告警
- 应用性能监控
- 错误日志监控
- 数据库监控
- 系统资源监控

## 9. 测试策略

### 9.1 单元测试
- 业务逻辑测试
- 服务层测试
- 工具类测试

### 9.2 集成测试
- API接口测试
- 数据库操作测试
- 权限验证测试

### 9.3 性能测试
- 并发用户测试
- 响应时间测试
- 负载能力测试

### 9.4 安全测试
- 权限绕过测试
- SQL注入测试
- XSS攻击测试

## 10. 维护计划

### 10.1 日常维护
- 日志文件清理
- 数据库备份
- 系统监控
- 性能优化

### 10.2 版本发布
- 版本控制策略
- 发布流程规范
- 回滚机制
- 版本兼容性

### 10.3 故障处理
- 故障响应流程
- 问题排查指南
- 恢复方案
- 事后总结

## 附录

### A. 权限列表
| 权限ID | 权限名称 | 描述 | 分类 |
|--------|----------|------|------|
| user:view | 查看用户 | 允许查看用户列表和详情 | 用户管理 |
| user:manage | 管理用户 | 允许修改用户状态和信息 | 用户管理 |
| content:review | 审核内容 | 允许审核用户发布的内容 | 内容管理 |
| content:publish | 发布内容 | 允许发布系统公告和内容 | 内容管理 |
| data:view | 查看数据 | 允许查看系统统计数据 | 数据统计 |
| data:export | 导出数据 | 允许导出系统数据 | 数据统计 |
| role:manage | 管理角色 | 允许管理角色和权限 | 权限管理 |
| merchant:approve | 审核商家 | 允许审核商家入驻申请 | 商家管理 |
| system:config | 系统配置 | 允许修改系统配置参数 | 系统管理 |
| audit:view | 查看日志 | 允许查看操作日志 | 日志管理 |
| audit:export | 导出日志 | 允许导出操作日志 | 日志管理 |
| audit:statistics | 日志统计 | 允许查看操作日志统计 | 日志管理 |

### B. 错误码说明
| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 200 | 成功 | 操作成功 |
| 201 | 创建成功 | 资源创建成功 |
| 400 | 请求错误 | 检查请求参数 |
| 401 | 未授权 | 需要登录认证 |
| 403 | 禁止访问 | 权限不足 |
| 404 | 资源不存在 | 检查资源ID |
| 409 | 资源冲突 | 资源已存在 |
| 429 | 请求过多 | 降低请求频率 |
| 500 | 服务器错误 | 联系管理员 |

### C. 版本历史
| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2025-01-01 | 初始版本发布 |
| v1.1 | 2025-02-01 | 新增权限管理功能 |
| v1.2 | 2025-03-01 | 优化数据统计功能 |