系统设置开发文档

1. 文档概述

1.1 文档目的

本文档旨在详细说明CRMEB系统中系统设置模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。

1.2 适用范围

本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导系统设置模块的开发、扩展和维护工作。

1.3 术语定义

术语	解释
RBAC	基于角色的权限控制（Role-Based Access Control）
管理员等级	管理员的层级关系，上级可管理下级
角色	权限的集合，用于分配给管理员
菜单权限	控制管理员可访问的菜单
操作权限	控制管理员可执行的操作
配置项	系统的各项设置参数
云存储	用于存储图片、文件等资源的云服务
定时任务	系统自动执行的任务

2. 核心功能模块

2.1 管理员管理

管理员列表：展示管理员基本信息，支持搜索、分页
管理员添加：添加新管理员，设置基本信息、角色、等级等
管理员编辑：修改管理员信息，包括角色、等级、状态等
管理员删除：删除管理员账号
状态管理：启用/禁用管理员账号
密码重置：重置管理员登录密码
权限继承：基于等级的权限控制，上级可管理下级

2.2 角色管理

角色列表：展示角色基本信息，支持搜索、分页
角色添加：添加新角色，设置角色名称、等级、权限等
角色编辑：修改角色信息，包括名称、等级、权限等
角色删除：删除角色
状态管理：启用/禁用角色
权限分配：为角色分配菜单权限和操作权限
权限继承：基于等级的角色控制

2.3 菜单管理

菜单列表：展示菜单树状结构，支持搜索、分页
菜单添加：添加新菜单，设置菜单名称、路径、图标、权限等
菜单编辑：修改菜单信息，包括名称、路径、图标、权限等
菜单删除：删除菜单
状态管理：显示/隐藏菜单
权限标识管理：设置菜单的权限标识
批量保存：支持批量保存菜单信息
左侧菜单获取：提供获取当前管理员可访问菜单的接口

2.4 系统配置

配置分类管理：管理系统配置的分类
配置项管理：添加、编辑、删除系统配置项
配置编辑：编辑系统基本配置，如网站名称、LOGO、联系方式等
配置状态管理：启用/禁用配置项
配置缓存：管理配置缓存，提高系统性能

2.5 存储配置

存储方式管理：配置系统使用的存储方式，如本地存储、阿里云OSS、腾讯云COS等
云存储配置：配置各云存储服务的参数
存储域名管理：设置资源访问域名
存储状态管理：启用/禁用存储方式

2.6 系统日志

日志记录：记录系统操作日志、登录日志等
日志查询：支持按条件查询日志
日志分页：分页展示日志信息
日志清理：清理过期日志

2.7 数据备份

数据库备份：备份系统数据库
备份管理：管理备份文件，支持下载、删除
数据库恢复：从备份文件恢复数据库
数据库优化：优化数据库性能

2.8 定时任务

任务列表：展示系统定时任务
任务添加：添加新的定时任务
任务编辑：修改定时任务信息
任务删除：删除定时任务
任务状态管理：启用/禁用定时任务
任务执行：手动执行定时任务

2.9 系统路由管理

路由列表：展示系统路由
路由同步：同步系统路由到数据库
路由权限管理：为路由分配权限

2.10 代码生成

代码生成配置：配置代码生成规则
代码生成：根据数据库表生成模型、控制器、视图等代码
生成记录管理：管理代码生成记录

3. 代码结构与设计

3.1 架构设计

系统采用分层架构设计，严格遵循MVC设计模式：

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Routes       │     │   Controllers   │     │    Services     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                         ┌─────────────────┐
                         │     Models      │
                         └─────────────────┘
                                 │
                         ┌─────────────────┐
                         │     Daos        │
                         └─────────────────┘

3.2 核心文件结构

3.2.1 路由配置

系统设置路由：crmeb/app/adminapi/route/setting.php - 包含管理员、角色、菜单、系统配置等路由
系统维护路由：crmeb/app/adminapi/route/system.php - 包含存储配置、系统日志、数据备份、定时任务等路由
公共路由：crmeb/app/adminapi/route/common.php - 包含左侧菜单获取等公共接口

3.2.2 控制器层（Controller）

系统设置控制器：crmeb/app/adminapi/controller/v1/setting/

SystemAdmin.php - 管理员管理控制器
SystemRole.php - 角色管理控制器
SystemMenus.php - 菜单管理控制器
SystemConfig.php - 系统配置控制器
SystemStorage.php - 存储配置控制器
SystemRoute.php - 路由管理控制器
SystemCrud.php - 代码生成控制器

系统维护控制器：crmeb/app/adminapi/controller/v1/system/

SystemLog.php - 系统日志控制器
SystemDatabackup.php - 数据备份控制器
SystemCrontab.php - 定时任务控制器

3.2.3 服务层（Services）

系统设置Services：crmeb/app/services/system/

SystemAdminServices.php - 管理员管理服务
SystemRoleServices.php - 角色管理服务
SystemMenusServices.php - 菜单管理服务
SystemConfigServices.php - 系统配置服务
SystemStorageServices.php - 存储配置服务
SystemRouteServices.php - 路由管理服务
SystemCrudServices.php - 代码生成服务

系统维护Services：

SystemLogServices.php - 系统日志服务
SystemDatabackupServices.php - 数据备份服务
SystemCrontabServices.php - 定时任务服务

3.2.4 模型层（Model）

系统设置模型：crmeb/app/model/system/

SystemAdmin.php - 管理员模型
SystemRole.php - 角色模型
SystemMenus.php - 菜单模型
SystemConfig.php - 系统配置模型
SystemStorage.php - 存储配置模型
SystemRoute.php - 路由模型

系统维护模型：

SystemLog.php - 系统日志模型
SystemDatabackup.php - 数据备份模型
SystemCrontab.php - 定时任务模型

4. 数据库设计

4.1 管理员表（system_admin）

字段名	数据类型	描述
id	int(10) unsigned	管理员ID
role_id	int(10)	角色ID
level	tinyint(1)	管理员等级
username	varchar(20)	用户名
password	varchar(60)	密码
salt	varchar(10)	密码盐
real_name	varchar(20)	真实姓名
avatar	varchar(255)	头像
phone	varchar(20)	手机号
email	varchar(50)	邮箱
last_login_ip	varchar(15)	最后登录IP
last_login_time	int(10)	最后登录时间
login_num	int(10)	登录次数
status	tinyint(1)	状态（0-禁用，1-启用）
is_delete	tinyint(1)	是否删除
add_time	int(10)	添加时间

4.2 角色表（system_role）

字段名	数据类型	描述
id	int(10) unsigned	角色ID
role_name	varchar(20)	角色名称
level	tinyint(1)	角色等级
auth_rules	text	权限规则（JSON格式）
status	tinyint(1)	状态（0-禁用，1-启用）
is_delete	tinyint(1)	是否删除
add_time	int(10)	添加时间

4.3 菜单表（system_menus）

字段名	数据类型	描述
id	int(10) unsigned	菜单ID
pid	int(10)	父菜单ID
menu_name	varchar(20)	菜单名称
menu_type	tinyint(1)	菜单类型（0-目录，1-菜单，2-按钮）
url	varchar(100)	菜单路径
icon	varchar(50)	菜单图标
auth	varchar(50)	权限标识
open_type	varchar(10)	打开方式（_self, _blank）
sort	int(10)	排序
is_show	tinyint(1)	是否显示（0-隐藏，1-显示）
status	tinyint(1)	状态（0-禁用，1-启用）
add_time	int(10)	添加时间

4.4 系统配置表（system_config）

字段名	数据类型	描述
id	int(10) unsigned	配置ID
menu_name	varchar(20)	菜单名称
type	tinyint(1)	配置类型
title	varchar(50)	配置标题
name	varchar(50)	配置名称
value	text	配置值
placeholder	varchar(100)	配置说明
tips	varchar(255)	配置提示
sort	int(10)	排序
status	tinyint(1)	状态（0-禁用，1-启用）
add_time	int(10)	添加时间

4.5 存储配置表（system_storage）

字段名	数据类型	描述
id	int(10) unsigned	配置ID
name	varchar(20)	存储名称
type	varchar(20)	存储类型（local, oss, cos, qiniu）
config	text	存储配置（JSON格式）
is_default	tinyint(1)	是否默认（0-否，1-是）
status	tinyint(1)	状态（0-禁用，1-启用）
add_time	int(10)	添加时间

4.6 系统日志表（system_log）

字段名	数据类型	描述
id	int(10) unsigned	日志ID
admin_id	int(10)	管理员ID
admin_name	varchar(20)	管理员名称
ip	varchar(15)	操作IP
url	varchar(255)	操作URL
method	varchar(10)	请求方法
param	text	请求参数
type	tinyint(1)	日志类型（0-登录日志，1-操作日志）
content	varchar(255)	操作内容
add_time	int(10)	添加时间

5. API接口说明

5.1 管理员管理接口

5.1.1 管理员列表

请求URL：/adminapi/v1/setting/admin/list
请求方法：GET
权限要求：setting/admin/list
请求参数：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- status：状态
返回结果：管理员列表数据

5.1.2 添加管理员

请求URL：/adminapi/v1/setting/admin/create
请求方法：POST
权限要求：setting/admin/create
请求参数：
- role_id：角色ID
- username：用户名
- password：密码
- real_name：真实姓名
- phone：手机号
- email：邮箱
返回结果：操作结果

5.1.3 编辑管理员

请求URL：/adminapi/v1/setting/admin/update/{id}
请求方法：PUT
权限要求：setting/admin/update
请求参数：
- role_id：角色ID
- real_name：真实姓名
- phone：手机号
- email：邮箱
- status：状态
返回结果：操作结果

5.2 角色管理接口

5.2.1 角色列表

请求URL：/adminapi/v1/setting/role/list
请求方法：GET
权限要求：setting/role/list
请求参数：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- status：状态
返回结果：角色列表数据

5.2.2 添加角色

请求URL：/adminapi/v1/setting/role/create
请求方法：POST
权限要求：setting/role/create
请求参数：
- role_name：角色名称
- level：角色等级
- auth_rules：权限规则（JSON格式）
返回结果：操作结果

5.2.3 权限分配

请求URL：/adminapi/v1/setting/role/permission/{id}
请求方法：PUT
权限要求：setting/role/permission
请求参数：
- auth_rules：权限规则（JSON格式）
返回结果：操作结果

5.3 菜单管理接口

5.3.1 菜单列表

请求URL：/adminapi/v1/setting/menu/list
请求方法：GET
权限要求：setting/menu/list
返回结果：菜单列表数据（树状结构）

5.3.2 添加菜单

请求URL：/adminapi/v1/setting/menu/create
请求方法：POST
权限要求：setting/menu/create
请求参数：
- pid：父菜单ID
- menu_name：菜单名称
- menu_type：菜单类型
- url：菜单路径
- icon：菜单图标
- auth：权限标识
返回结果：操作结果

5.3.3 获取左侧菜单

请求URL：/adminapi/v1/common/menu
请求方法：GET
权限要求：登录用户
返回结果：当前用户可访问的左侧菜单

5.4 系统配置接口

5.4.1 配置列表

请求URL：/adminapi/v1/setting/config/list
请求方法：GET
权限要求：setting/config/list
请求参数：
- menu_name：配置分类
返回结果：配置列表数据

5.4.2 编辑配置

请求URL：/adminapi/v1/setting/config/update
请求方法：PUT
权限要求：setting/config/update
请求参数：
- config：配置项（JSON格式，键为配置名称，值为配置值）
返回结果：操作结果

5. 开发规范与流程

5.1 代码规范

命名规范：
- 类名采用大驼峰命名法，如 SystemAdminServices
- 方法名采用小驼峰命名法，如 getAdminList
- 变量名采用小驼峰命名法，如 rolePermission
- 常量名采用全大写，下划线分隔，如 MENU_TYPE_CATALOG
代码结构：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
- 权限相关代码必须添加权限验证
权限控制：
- 所有管理接口必须添加权限验证
- 权限验证通过中间件实现
- 权限标识必须唯一，格式规范
- 角色权限必须包含所有下级角色的权限

5.2 开发流程

需求分析：明确系统设置的功能需求和业务逻辑
设计阶段：设计数据结构、API接口和业务流程
编码实现：按照分层架构编写代码
单元测试：编写单元测试，确保功能正确性
集成测试：进行模块集成测试，测试权限控制等功能
安全测试：对权限控制、密码加密等进行安全测试
代码审查：提交代码审查，确保代码质量
部署上线：部署到生产环境

6. 常见问题与解决方案

6.1 权限继承问题

问题：上级管理员无法管理下级管理员或角色 解决方案：

检查管理员等级设置，确保上级等级低于下级等级
检查角色等级设置，确保上级角色等级低于下级角色等级
检查权限分配逻辑，确保上级拥有管理下级的权限

6.2 菜单显示问题

问题：管理员无法看到某些菜单 解决方案：

检查菜单状态，确保菜单已启用
检查菜单是否设置为显示
检查管理员所属角色是否拥有该菜单的权限
检查菜单权限标识是否正确

6.3 配置不生效问题

问题：修改系统配置后不生效 解决方案：

检查配置是否已保存成功
检查配置是否已启用
清理配置缓存
检查配置读取逻辑，确保正确读取最新配置

6.4 日志记录问题

问题：系统操作没有记录日志 解决方案：

检查日志中间件是否已启用
检查日志记录逻辑，确保覆盖所有操作
检查日志表是否有写入权限

7. 扩展与定制

7.1 添加新的配置项

数据库操作：在system_config表中添加新的配置项
代码修改：
- 在SystemConfigServices中添加配置项的读取方法
- 在配置控制器中添加配置项的编辑功能
前端修改：在前端配置页面添加对应的配置表单

7.2 添加新的菜单类型

数据库操作：在system_menus表中添加新的菜单类型常量
代码修改：
- 在SystemMenusServices中添加菜单类型的处理逻辑
- 在菜单控制器中添加菜单类型的验证
前端修改：在前端菜单管理页面添加对应的菜单类型选项

7.3 扩展权限控制

设计扩展：扩展权限模型，添加更细粒度的权限控制
代码修改：
- 扩展角色权限表，添加更细粒度的权限字段
- 修改权限验证逻辑，支持更细粒度的权限控制
前端修改：在前端权限分配页面添加对应的权限选项

8. 文档更新记录

版本	更新日期	更新内容	更新人
1.0	2026-01-19	初始版本，包含管理员管理、角色管理、菜单管理、系统配置、存储配置、系统日志、数据备份、定时任务等核心功能	AI Assistant

9. 附录

9.1 核心类关系图

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Routes       │     │   Controllers   │     │    Services     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                         ┌─────────────────┐
                         │     Models      │
                         └─────────────────┘
                                 │
                         ┌─────────────────┐
                         │     Daos        │
                         └─────────────────┘

9.2 权限控制流程图

权限控制流程：
1. 用户登录系统，获取token
2. 发起API请求，携带token
3. 权限中间件验证token合法性
4. 获取用户所属角色
5. 获取角色拥有的权限
6. 验证请求的路由是否在权限列表中
7. 验证通过，执行请求；验证失败，返回权限错误

9.3 菜单权限继承图

菜单权限继承关系：
┌─────────────────┐
│   超级管理员     │
└─────────┬───────┘
         │
┌─────────▼───────┐
│   一级管理员     │
└─────────┬───────┘
         │
┌─────────▼───────┐
│   二级管理员     │
└─────────────────┘

说明：上级管理员可以管理所有下级管理员，拥有下级管理员的所有权限

9.4 配置分类列表

分类名称	描述
basic	基本配置
shop	商城配置
payment	支付配置
sms	短信配置
storage	存储配置
wechat	微信配置
express	物流配置
marketing	营销配置

提示：该文档由AI生成，仅供参考。

系统设置开发文档.md 20 KB History Raw