diff --git a/readme.md b/readme.md index 77ab51cdc..ea0fb6046 100644 --- a/readme.md +++ b/readme.md @@ -6,11 +6,9 @@ [![PHP Version](https://img.shields.io/badge/php-%3E%3D7.1-blue.svg)](composer.json) [![ThinkPHP](https://img.shields.io/badge/ThinkPHP-6%20%7C%208-brightgreen.svg)](https://www.thinkphp.cn/) -ThinkAdmin 是一套面向 **PHP 开发者**的开源后台开发框架,基于 **ThinkPHP**,提供用户、权限、菜单、表单、文件上传、异步任务和微信管理等常用功能。 +ThinkAdmin 是一套基于 **ThinkPHP 6 / 8** 的开源后台开发框架。后端使用 **ThinkLibrary** 封装常用功能,通过 **Composer** 管理依赖和插件;前端搭配 **Layui、jQuery 与 RequireJS**,沿用 PHP 模板配合 JavaScript 的开发方式。 -开发业务后台时,许多基础工作总会反复出现:给同事开账号、限制操作权限、做带筛选的列表、上传图片、处理耗时任务。ThinkAdmin 把这些常用能力和对应的管理页面放在一起,让你从一个可以运行、可以继续扩展的后台开始,把更多时间用在业务规则和功能交付上。 - -当前 v6 系列使用 **ThinkLibrary** 提供通用开发能力,通过 **Composer** 管理依赖和插件。默认页面采用 PHP 模板配合 JavaScript 交互的方式组织,熟悉 ThinkPHP 的开发者可以从现有控制器、模型和模板入手,逐步加入自己的业务。 +做后台,账号怎么分权限、列表怎么筛选、图片传到哪里,这些问题总会遇到。ThinkAdmin 已经有了对应的功能和页面,你可以接着写自己的客户管理、订单处理或运营工具,**把重复搭建基础后台的时间,用在业务上**。需要在多个项目里使用同一套模块时,再把它整理成 Composer 插件。 [官方网站与开发文档](https://thinkadmin.top) · [在线演示](https://v6.thinkadmin.top) · [版本发布](https://github.com/zoujingli/ThinkAdmin/releases) · [问题反馈](https://github.com/zoujingli/ThinkAdmin/issues) @@ -35,26 +33,24 @@ ThinkAdmin 是一套面向 **PHP 开发者**的开源后台开发框架,基于 ## 项目特点 -- **常用管理功能已经具备。** 系统用户、权限、菜单、参数配置、日志和文件管理都有对应页面,可以作为业务后台的基础部分继续使用。 -- **列表和表单有一致的开发方式。** 查询筛选、分页、表单提交、数据校验和状态更新都有现成封装,做不同业务页面时可以沿用同一套写法。 -- **前后端代码便于对照。** 仓库同时包含控制器和页面模板,遇到筛选、弹窗、上传等需求,可以从一个完整功能中找到服务端和页面端的实现。 -- **按项目需要扩展。** 可以在独立应用中编写业务,也可以把需要重复使用的模块整理成 Composer 插件。是否拆成插件,由项目的复用和维护需要决定。 -- **支持基于源码继续开发和交付。** 项目采用 MIT 许可证,可在遵守许可证的前提下用于个人或商业项目,修改界面与业务代码;第三方组件仍按各自的许可使用。 +- **基础管理不用从头搭。** 用户、权限、菜单、配置、日志和文件管理都有现成页面。先把后台跑起来,就可以从自己的业务模块开始做。 +- **列表和表单,有现成的写法。** ThinkLibrary 把筛选、分页、提交、校验和状态更新做了封装。熟悉一套流程后,后续页面可以继续沿用。 +- **页面和接口能对着看。** 控制器、模型、模板都在源码里。想知道某个筛选条件怎么生效、编辑弹窗怎么保存,顺着已有页面就能找到对应实现。 +- **模块怎么拆,由业务决定。** 只用于当前项目的代码,可以放在独立应用中;需要跨项目复用时,再用 Composer 管理插件的依赖和版本。 +- **能自己改,也能用于商业项目。** 项目采用 MIT 许可证,允许按许可条款修改、使用和分发。交付时保留版权与许可文本,并留意第三方组件各自的授权要求。 ## 适用场景 -ThinkAdmin 更适合需要自行开发业务、又希望复用通用后台能力的项目: +如果你正在给团队做一个内部系统,或者为客户开发一套管理后台,ThinkAdmin 可以承担其中常见的基础工作: -| 项目场景 | 可以复用的部分 | 需要补充的业务 | -| --- | --- | --- | -| 企业内部管理 | 账号、权限、菜单、列表、表单和日志 | 客户、订单、审批等具体流程 | -| 内容与运营后台 | 图文编辑、文件上传、分类字典和状态管理 | 内容模型、审核规则、展示页面 | -| 微信公众号相关业务 | 粉丝、菜单、图文、回复规则及支付管理基础 | 自己的账号配置、活动逻辑和业务订单 | -| 项目原型与定制开发 | 已有后台界面、数据操作方式和基础组件 | 行业数据模型、业务规则及交付细节 | +- 做客户、订单或审批管理时,沿用已有的账号、权限、列表和表单,再编写具体的业务流程。 +- 做内容运营后台时,接入图文编辑、图片上传和分类字典,把精力放在内容模型、审核和展示上。 +- 做微信公众号业务时,在同一个后台处理粉丝、菜单、回复和支付相关操作,再对接自己的活动或订单。 +- 做原型或定制项目时,先用已有界面把业务流程串起来,再逐步补充细节。 -如果你熟悉 PHP / ThinkPHP,希望在已有后台上持续开发自己的系统,可以先通过[在线演示](https://v6.thinkadmin.top)了解操作方式,再结合源码评估是否适合项目。 +拿不准是否适合,可以先看看[在线演示](https://v6.thinkadmin.top),挑一个熟悉的功能,再对照源码走一遍。对熟悉 PHP / ThinkPHP 的开发者,这也是了解项目开发方式的直接途径。 -CRM、ERP、OA、多租户或订阅系统都可以作为业务开发方向,但它们的业务规则、数据隔离和计费逻辑仍需要按项目要求实现。 +ThinkAdmin 做的是通用后台基础。客户怎么分配、订单如何流转、不同租户的数据怎样隔离,这些仍由你的业务模块来实现。 ## 功能概览 @@ -70,71 +66,58 @@ CRM、ERP、OA、多租户或订阅系统都可以作为业务开发方向,但 ### 账号、菜单与日常管理 -系统用户管理提供账号维护、密码修改、状态管理和权限分配等操作。系统菜单管理用来组织后台入口,参数配置用来调整站点名称、登录入口、主题和存储设置。 +新同事来了,给他开一个账号;岗位变了,调整可用权限;人员离职了,再停用账号。这些日常工作可以直接在系统用户管理中完成。菜单管理负责组织后台入口,站点名称、登录背景、主题和存储方式则在参数配置中调整。 -对实际项目来说,这些功能可以承接常见的管理工作:为新同事创建账号、调整可访问的模块、停用离职人员账号,或者修改网站显示信息。你可以在此基础上增加业务页面,不必为每个项目重新设计一套管理入口。 - -数据字典可统一维护分类、编码等基础选项;操作日志可查看已记录的管理行为,并按账号、操作类型、时间等条件查找。自定义业务需要记录的关键操作,可以继续接入这套日志能力。 +分类、编码等经常变动的基础选项,可以放到数据字典中维护。想查某个账号最近做过哪些已记录的管理操作,可以按时间、账号或操作类型筛选日志;自己的业务模块也可以接入同一套日志记录方式。 ### 权限配置,从页面入口到具体操作 -ThinkAdmin 通过控制器方法上的注解描述登录和权限要求,再结合后台授权配置决定哪些账号可以访问哪些功能。模板中的权限判断可以控制按钮显示,服务端同时负责对应接口的访问校验。 +比如,你希望运营人员能查看和编辑资料,但把删除和系统配置留给管理员。可以在控制器方法上标注登录或权限要求,再到后台配置相应授权。 -例如,一个运营账号可以查看和编辑指定资料,但没有删除或修改系统配置的权限。开发新功能时,按同样的方式标注方法、配置菜单和授权,就能将业务功能纳入现有权限管理。 - -这套机制主要解决功能访问权限。部门数据范围、订单归属、多租户隔离等业务规则,需要在自己的查询和操作逻辑中继续处理。 +页面上的按钮根据权限显示,接口请求也由服务端校验。新增业务时,按同样的方式接入,就可以把新页面和新操作放进现有的权限管理中。具体注解和数据权限的处理见[开发与扩展](#开发与扩展)。 ### 列表与表单,沿用熟悉的开发方式 -后台页面经常需要按关键词、状态、时间范围筛选数据,也需要分页、编辑弹窗、保存提示和状态开关。ThinkLibrary 的数据操作封装与项目的前端组件共同处理这些重复工作。 +一个常见的管理页:上面按关键词、状态和时间筛选,下面是带分页的表格,点击“编辑”打开表单,保存后刷新列表。ThinkLibrary 和现有前端组件已经给这类页面准备了对应的写法。 -仓库中的系统用户页面就是一个完整参考:控制器组织筛选条件,模板定义表格列和操作按钮,表单负责输入与提交。新业务可以参照这条流程,替换为自己的模型、字段和校验规则。 - -通用封装负责处理常见流程,业务逻辑仍由你掌握。涉及金额、库存、审批状态等操作时,应在服务端明确校验规则和允许的状态变化。 +可以从仓库的系统用户页面开始看:控制器怎样组织查询,模板怎样定义列和按钮,表单怎样提交。做自己的业务时,再换成对应的模型、字段和校验规则。许多页面虽然管理的数据不同,基本流程可以共用。 ### 文件与图片,按需要选择存储方式 -开发阶段可以使用本地存储;业务需要时,也可以配置 Alist、七牛云、阿里云 OSS、腾讯云 COS 或又拍云。上传组件读取统一的文件类型、大小、存储方式和图片处理参数,业务页面可以复用同一套上传交互。 +头像、封面、内容配图和附件,往往分散在不同表单里。ThinkAdmin 用一套上传组件处理这些需求,各页面通过参数指定文件类型、大小、存储方式和图片尺寸。 -- **文件复用:** 上传流程支持计算文件哈希并检查对应存储文件,已存在时可以复用结果,避免再次传输相同文件内容。 -- **图片处理:** 支持单图、多图上传与图片选择,以及按参数进行图片压缩、尺寸限制和裁切,适合头像、封面和内容配图等场景。 -- **文件管理:** 后台可查看文件记录、按条件查找文件,并在授权范围内编辑、删除或清理重复记录。 -- **安全文件:** 安全模式文件使用本地 `safefile/` 目录,与公开上传目录分开保存;业务中谁能读取这些文件,仍应由相应接口控制。 +- **相同文件可以少传一次。** 上传流程支持计算文件哈希,检查对应存储文件是否已存在;命中后直接复用结果。 +- **图片按用途处理。** 单图、多图、图片选择都有对应入口,压缩质量、最大宽高和裁切尺寸按页面需要设置。 +- **上传记录集中管理。** 后台可以查找文件记录,并在授权范围内编辑、删除或清理重复记录。 +- **公开文件和安全文件分开存放。** 例如支付证书可以使用安全模式,保存到本地 `safefile/`,读取权限由业务接口另行控制。 -各存储服务需要配置自己的连接信息或访问凭据。更换存储方式影响后续上传,已有文件的搬迁和地址调整需要另外处理。 +开发时可以先用本地存储,有需要再接入 Alist、七牛云、阿里云 OSS、腾讯云 COS 或又拍云。配置好对应账号和访问凭据后,业务页面仍可沿用上传组件;已有文件的搬迁和地址调整需要单独安排。 ### 耗时工作,交给后台任务执行 -批量同步、数据整理或其他耗时操作,不适合一直占用用户当前的页面请求。ThinkAdmin 提供任务登记、队列监听、独立进程执行和进度展示,页面可以发起任务,再从“系统任务管理”查看执行情况。 +同步一批粉丝、整理一批数据,可能比普通页面请求花更长时间。这类工作可以登记成任务,由队列监听进程安排执行,再到“系统任务管理”查看状态和结果。 -队列支持延时和循环任务,后台提供执行记录、进度和重跑入口。任务代码可以主动报告“已处理多少条”“进行到哪一步”等进度,方便使用者了解处理情况。仓库中的微信粉丝同步命令可以作为实际参考,自定义任务也可以沿用相同的任务管理方式。 +任务代码可以报告“处理到第几条”“目前完成多少”等进度。延时执行、循环任务和后台重置重跑也有对应入口;仓库里的微信粉丝同步命令就是一个实际例子,可以参考它编写自己的任务。 -使用时需要启动队列监听进程。重试规则以及重复执行时如何避免重复扣款、重复通知等问题,应由具体任务设计;生产环境的进程托管方式见[配置与部署](#配置与部署)。 +先启动监听进程,任务才会被处理。部署方式见[配置与部署](#配置与部署),失败后的排查与重跑见下方[常见问题](#常见问题)。 ### 微信管理,集中处理常见公众号操作 -默认微信模块提供常见的公众号管理和微信支付管理功能,适合将微信运营与自己的业务后台放在一起: +如果项目围绕微信公众号开展业务,可以把常见运营操作放到同一个后台:同步粉丝资料,查看关注状态和黑名单,维护图文内容、菜单、关键词与关注回复。 -- 配置公众号接口,同步和查看粉丝资料、关注状态及黑名单等信息。 -- 维护图文素材、自定义菜单和回复规则。 -- 配置关注回复与相关消息处理。 -- 配置微信支付参数,查看支付记录并处理退款相关操作。 +微信模块也包含商户参数配置、支付记录和退款相关操作,便于接入自己的订单或活动流程。它管理的是这些通用环节,具体订单怎样生成、付款后执行什么业务,仍由项目代码处理。 -使用前需要准备自己的公众号或商户信息,按微信要求配置回调地址、域名和接口权限。具体能使用哪些能力,也取决于账号类型及微信平台开放的权限;业务订单和活动流程则需要与你自己的系统对接。 +开始使用前,先填写自己的公众号或商户信息,按微信要求设置回调地址、域名和接口权限。公众号类型、认证情况和平台开放权限不同,可用功能也会有差别。 ### 界面与交互,保留现成组件,也方便定制 -默认后台使用 Layui、jQuery 和 RequireJS,提供表格、表单、弹窗、日期选择、文件上传等常见交互。项目还包含 ECharts、Vue、CKEditor 与 wangEditor 相关资源,可根据页面需求使用。 +想先换个站点名称、登录背景或主题,可以从后台配置开始。需要调整表格、表单、弹窗等细节时,再查看 Layui 组件、模板和项目级扩展文件。普通部署可直接使用已有静态资源,修改 Less 主题源码后再运行主题构建。 -普通部署可以直接使用仓库中的静态资源。调整站点名称、登录背景和主题可以从后台配置开始;需要更细的样式或交互时,可使用项目级扩展文件,也可以修改模板。修改 Less 主题源码时,再执行对应的主题构建。 - -项目使用语言键组织界面文字,并提供已有语言包作为参考。增加业务页面或补充其他语言时,需要同步维护相应文字与翻译。 +做图表或内容编辑页面时,也能用到项目中的 ECharts、Vue、CKEditor 与 wangEditor 相关资源。页面文字通过语言键组织,已有语言包可以作为业务翻译的参考。 ## 技术与组件 -ThinkAdmin 项目、核心库和应用插件各有职责。了解这些部分,更容易判断一个改动应该放在哪里: - -默认依赖见 [composer.json](composer.json): +找代码时,可以先按下面几部分定位。依赖声明见 [composer.json](composer.json): | 组件 | 职责 | | --- | --- | @@ -143,9 +126,7 @@ ThinkAdmin 项目、核心库和应用插件各有职责。了解这些部分, | `zoujingli/think-plugs-wechat` | 微信管理模块,当前项目已直接依赖,无需重复安装 | | `topthink/think-orm` | 数据访问层,根依赖约束支持 2.x / 3.x | -后台页面的通用能力主要来自 ThinkLibrary,后台管理和微信管理由对应插件提供。静态资源由相关插件引入并发布到 `public/static/`,ThinkORM 负责数据访问。 - -当前项目面向 ThinkPHP 6 / 8 相关依赖组合,安装时由 Composer 根据版本约束选择依赖。更多组件、版本要求及适用范围以各插件文档和实际安装结果为准。 +静态资源随相关插件发布到 `public/static/`。安装时,Composer 按项目的版本约束选择依赖;实际的 PHP 与扩展要求见[环境要求](#环境要求)。 ## 环境要求 @@ -314,7 +295,7 @@ ThinkAdmin/ 1. **先定义数据。** 确定客户记录有哪些字段、哪些字段必须唯一、有哪些状态,以及数据归属如何判断,再准备数据表和模型。 2. **完成查询列表。** 在控制器中组织关键词、状态和时间等筛选条件,使用查询封装处理列表和分页。 3. **编写页面模板。** 定义表格列、筛选表单、编辑弹窗和操作按钮,复用已有的后台布局与组件。 -4. **补齐保存规则。** 处理必填项、格式校验、重复数据和状态限制;重要规则放在服务端,确保通过接口提交时也会检查。 +4. **补齐保存规则。** 处理必填项、格式校验、重复数据和状态限制。金额、库存、审批状态等重要规则放在服务端,确保通过接口提交时也会检查。 5. **接入菜单与授权。** 标注需要权限或登录的方法,配置菜单,再用普通账号检查可见内容和允许的操作是否符合预期。 后台控制器通常继承 `think\admin\Controller`,使用 ThinkLibrary 的查询、表单、校验与状态更新能力。参考仓库中的实际实现: @@ -332,15 +313,17 @@ ThinkAdmin/ - `@login true`:需要登录。 - `@menu true`:标记可用于菜单配置的节点,不会自动创建完整菜单或角色授权。 -新增后台页面还需配置菜单与对应权限;不能把“菜单不可见”等同于接口已受保护。核心 API 与扩展说明请参阅 [ThinkLibrary](https://github.com/zoujingli/ThinkLibrary) 和[官方文档](https://thinkadmin.top)。 +菜单和按钮决定页面上能看到什么,控制器的权限校验决定请求能否执行,两边需要配合配置。至于一个账号能查看哪个部门、哪些客户的数据,还要在业务查询和操作逻辑中处理。 + +核心 API 与扩展说明请参阅 [ThinkLibrary](https://github.com/zoujingli/ThinkLibrary) 和[官方文档](https://thinkadmin.top)。 ### 插件开发 -如果一个模块只服务于当前项目,先放在独立应用中通常更直接。如果它需要在多个项目间复用,或者需要单独维护版本和依赖,再整理成插件会更方便。 +一个模块只在当前项目中使用,可以先放在独立应用里。当几个项目都需要它,或者它有自己的版本和依赖时,再整理成插件。 插件通过 Composer 管理依赖、安装路径和服务注册。应用服务类继承 `think\admin\Plugin`,定义插件信息与 `menu()`,按需使用 `register()`、`boot()` 注册服务、命令和事件。这样可以将一组相关的控制器、模板、配置和数据初始化安排在同一个模块中维护。 -可参考 [后台模块服务](app/admin/Service.php)与[微信模块服务](app/wechat/Service.php)。安装、更新和卸载行为取决于插件包的配置及安装器逻辑,不能假定卸载一定保留或一定删除数据;操作前应阅读插件文档并备份。 +可参考 [后台模块服务](app/admin/Service.php)与[微信模块服务](app/wechat/Service.php)。安装、更新和卸载时会处理哪些文件或数据,由插件配置和安装器决定;操作前先读插件文档,并做好备份。 ### 前端定制 @@ -436,14 +419,14 @@ npm run build ## 交流与贡献 +用下来有什么问题、有哪些地方值得改,欢迎带着具体的场景来交流。修复一个问题、补充一个例子,或者把不清楚的说明改明白,都是参与项目的方式。 + - 源码仓库:[GitHub](https://github.com/zoujingli/ThinkAdmin)、[Gitee](https://gitee.com/zoujingli/ThinkAdmin)。 - 使用说明、插件文档和技术交流群入口:[官方网站](https://thinkadmin.top)。 -- 报告问题时,请提供版本、运行环境、复现步骤和脱敏后的错误信息。 -- 提交 Pull Request 时,请说明修改目的和验证方式,不同功能尽量拆分提交;涉及前端源码与构建产物时保持同步。 +- 反馈问题时,附上版本、运行环境、复现步骤和脱敏后的错误信息,便于其他人定位。 +- 提交 Pull Request 时,说明为什么改、怎样验证。不同功能尽量分开提交,前端源码与构建产物保持同步。 - 安全问题请按[安全政策](security.md)联系维护者,不要在公开 Issue 中披露敏感信息或未修复漏洞细节。 -欢迎贡献代码、完善文档、提交可复现的问题以及分享实践经验。 - ## 赞助支持 感谢以下支持方为 ThinkAdmin 的开发与维护提供支持: @@ -456,7 +439,7 @@ npm run build ## 支持项目 -如果 ThinkAdmin 对你有帮助,欢迎 Star、Fork、分享项目,或参与代码和文档贡献。开发赞助方式请访问[官方网站](https://thinkadmin.top)了解。 +如果 ThinkAdmin 帮你省下了一些开发时间,欢迎 Star、分享给同样做 PHP 开发的朋友,或者 Fork 后参与改进。开发赞助方式可以在[官方网站](https://thinkadmin.top)了解。 ## 开源协议