v0.0.1 版本功能说明

版本信息

项目	内容
版本	`v0.0.1`
定位	Go 基础后台框架首个可部署版本
管理端仓库	go_basic_frame_admin
接口端仓库	go_basic_frame_api
官网	访问官网

v0.0.1 建立了项目的基础目录、双端服务、登录鉴权、RBAC 权限、系统管理、文件存储和常用渠道配置能力，并提供可以初始化新数据库的完整 SQL。

本文件记录 Git 标签 v0.0.1 已包含的功能，不包含 v0.0.2 新增的插件注册中心、插件生命周期和插件页面解析能力。

技术栈

服务端

类别	技术
开发语言	Go
Web 框架	Gin
ORM	GORM
数据库	MySQL
缓存与会话	Redis
登录鉴权	JWT + Redis
命令行	Cobra
配置文件	YAML
密码加密	bcrypt

管理端

类别	技术
框架	Vue 3 Composition API
语言	TypeScript
构建工具	Vite
UI 组件	Element Plus
状态管理	Pinia
路由	Vue Router
网络请求	Axios
图表	ECharts

核心架构

双端服务

同一套服务端代码提供两个独立进程入口：

服务	命令	默认地址	路由前缀
管理端 API	`server_api service admin`	`:8001`	`/admin`
用户端 API	`server_api service api`	`:8002`	`/api`

管理端与用户端的 Controller、Logic、Param、Resp 和路由相互隔离，共用数据库、登录态、上传、存储等基础能力。

服务基础能力

Gin Logger、Recovery 和统一 CORS 中间件；
MySQL、Redis 初始化及连接释放；
HTTP 请求头、读取、写入、空闲和停机超时配置；
SIGINT、SIGTERM 信号监听及优雅停机；
启动时检查必需数据表和初始管理员数据；
统一接口响应、分页、密码处理和数据库错误转换；
config.yaml 配置文件及 config.example.yaml 示例。

登录、账号和权限

管理端登录

管理员账号密码登录；
JWT 访问令牌；
Redis 保存登录会话；
获取当前管理员资料；
主动退出登录；
修改密码并使原登录会话失效；
管理员踢下线；
获取当前账号动态菜单和接口权限；
超级管理员与普通管理员权限区分。

个人设置

修改昵称、手机号和邮箱；
点击头像上传并自动更新头像；
独立修改登录密码；
头像等业务文件在数据库中保存相对路径，查询时补全访问地址。

RBAC 权限

菜单、页面和按钮组成权限资源；
角色绑定菜单及接口权限；
管理员绑定多个角色；
普通管理员根据 METHOD:/route 校验接口权限；
超级管理员跳过接口权限匹配，但仍需有效登录态；
前端按钮使用权限指令控制展示；
后端权限中间件作为最终安全边界。

管理端请求链路：

text

Auth → Permission → OperationLog → Controller → Logic

管理端功能

系统总览

提供后台首页概览数据接口；
管理端使用 ECharts 展示统计信息；
页面菜单和标签页由动态路由驱动。

菜单管理

菜单树查询；
菜单、页面和按钮权限新增、修改、删除；
支持多级菜单、图标、排序、状态和备注；
菜单路径驱动前端动态页面路由；
API 权限路径与菜单或按钮绑定。

角色管理

角色列表和树形数据；
角色新增、修改、删除；
查询并分配角色菜单权限；
查询角色下的管理员；
支持角色状态和层级关系。

管理员管理

管理员分页列表；
新增、修改和删除管理员；
设置头像、部门、角色和账号状态；
重置管理员密码；
强制管理员下线；
超级管理员标识和保护逻辑。

部门管理

部门树查询；
部门新增、修改和删除；
支持父子层级、负责人、排序和状态。

操作日志

自动记录受保护的管理端写操作；
记录请求方法、路径、操作人、IP、参数和执行结果等信息；
敏感请求字段脱敏；
操作日志分页查询；
查询操作日志本身不会再次写入操作日志。

文件上传和存储

统一上传

管理端和用户端分别提供统一文件上传接口；
支持本地存储、阿里云 OSS、腾讯云 COS、七牛云 Kodo 和 MinIO；
可以维护多个存储渠道并设置默认渠道；
本地文件通过 /files/*filepath 访问；
上传记录保存在 sys_upload_file；
sys_upload_file 同时保存相对路径和上传时的完整地址；
普通业务表只保存相对路径；
查询时根据当前默认存储配置统一补全文件访问地址；
支持远程文件获取相关基础能力。

存储配置

存储渠道列表；
新增和修改存储配置；
设置默认存储渠道；
删除未使用的存储配置；
不同渠道使用各自配置参数。

渠道配置

短信配置

短信开发信息配置；
支持配置多个短信渠道；
短信签名新增、修改、删除和列表；
短信模板新增、修改、删除和列表；
短信发送记录查询；
配置、签名、模板和发送记录分表存储。

微信配置

微信公众号配置；
微信开放平台配置；
微信小程序配置；
多种微信应用类型在同一配置模块中管理；
支持保存多条渠道配置。

支付配置

微信支付配置；
支付宝支付配置；
同一支付渠道可以配置多个商户；
支付配置新增、修改、删除和列表查询。

平台配置

平台配置区分管理端和用户端：

配置端	字段
管理端配置	系统名称、系统 Logo
用户端配置	默认昵称、默认头像

管理端登录页和系统左上角可以读取公开的管理端平台配置，动态展示系统名称和 Logo。

用户端 API

v0.0.1 提供基础用户端能力：

用户登录；
用户退出；
获取个人资料；
修改登录密码；
登录后文件上传；
独立的 /api 鉴权链路。

该版本主要完成用户端基础接口框架，商城、新闻资讯等具体用户业务尚未内置。

管理端页面能力

登录页面；
后端菜单驱动的动态路由和多级导航；
系统总览；
菜单、角色、管理员、部门和操作日志页面；
存储、短信、微信、支付和平台配置页面；
个人设置和头像上传；
标签页导航和当前页面路径展示；
明暗主题、全屏和水印；
响应式布局和统一页面卡片风格；
接口级按钮权限；
系统名称和 Logo 动态更新；
Axios 统一请求和业务错误提示；
管理端接口地址通过 VITE_ADMIN_API_BASE_URL 配置；
日期时间统一显示到秒，不显示毫秒；
ES6+ 和箭头函数代码风格。

数据库

初始化脚本

完整初始化脚本：

text

sql/v0.0.1/cf_backend_frame.sql

执行示例：

bash

mysql -uroot -p 数据库名 < sql/v0.0.1/cf_backend_frame.sql

该脚本用于初始化新数据库，包含基础表结构、系统菜单、角色权限关系和初始管理员数据。对已有数据库执行前必须先备份，并确认不会与现有主键或唯一索引冲突。

基础数据表

表名	作用
`sys_user`	管理员和用户基础账号
`sys_user_login`	登录会话记录
`sys_role`	角色信息
`sys_user_role`	用户角色关系
`sys_menu`	菜单、页面和按钮权限
`sys_role_menu`	角色菜单关系
`sys_dept`	部门信息
`sys_operation_log`	管理端操作日志
`sys_storage_config`	文件存储渠道配置
`sys_upload_file`	文件上传记录
`sys_sms_config`	短信开发配置
`sys_sms_signature`	短信签名
`sys_sms_template`	短信模板
`sys_sms_send_log`	短信发送记录
`sys_wechat_config`	微信渠道配置
`sys_payment_config`	支付渠道配置
`sys_platform_config`	管理端和用户端平台配置

数据库规范：

所有表和字段带有注释；
字符字段使用 utf8mb4_general_ci；
枚举值从 1 开始；
结构变更由 SQL 脚本维护，不使用运行时 AutoMigrate；
GORM Model 使用明确的 GORM、JSON 和字段说明 Tag；
表关联关系在 Resp 中定义，不在 Model 中定义。

接口和开发规范

统一返回 {code, msg, data}；
Controller 负责参数绑定、调用 Logic 和统一响应；
Logic 负责业务规则、事务和响应结构组装；
Logic 不直接返回 Model；
Param 和 Resp 按功能拆分；
双端共同业务能力放在 internal/common 对应二级目录；
无业务归属的通用函数放在 pkg；
管理端维护 OpenAPI 3.0 接口文档；
仓库包含前后端代码规范和 AI 编码助手 Skill。

安装与启动

1. 初始化数据库

bash

mysql -uroot -p 数据库名 < sql/v0.0.1/cf_backend_frame.sql

2. 创建配置文件

bash

cp config.example.yaml config.yaml

修改 MySQL、Redis、JWT 和服务端口配置。生产环境必须更换 JWT 密钥，不能提交真实密码和密钥。

3. 启动服务端

bash

# 管理端 API
go run . service admin -c config.yaml

# 用户端 API
go run . service api -c config.yaml

4. 启动管理端

在管理端仓库配置后端地址：

dotenv

VITE_ADMIN_API_BASE_URL=http://127.0.0.1:8001

然后执行：

bash

pnpm install
pnpm dev

发布检查

服务端：

bash

gofmt -l .
go vet ./...
go test ./...
go build ./...

管理端：

bash

pnpm exec vue-tsc --noEmit
pnpm build

部署后至少检查：

管理端和用户端 API 都能正常启动；
管理员可以登录、退出和修改密码；
普通管理员的菜单、按钮和接口权限正确；
文件上传和文件地址补全正常；
平台名称及 Logo 能在登录页和管理端正确显示；
存储、短信、微信和支付配置能够正常维护；
操作日志正常记录，日志查询不会产生新的操作日志；
管理端亮色、暗色主题及生产构建运行正常。

版本边界

v0.0.1 尚未提供以下能力：

插件契约和插件注册中心；
插件依赖、版本及迁移摘要校验；
插件生命周期和后台任务托管；
/plugin/{plugin_id}/{view_path} 管理端插件页面解析；
在线插件市场和运行时动态加载；
商城、新闻资讯等具体业务插件。

以上插件化基础能力从 v0.0.2 开始引入，升级方式参见 v0.0.2 插件化基础设施升级说明。

v0.0.1 版本功能说明 ​

版本信息 ​

技术栈 ​

服务端 ​

管理端 ​

核心架构 ​

双端服务 ​

服务基础能力 ​

登录、账号和权限 ​

管理端登录 ​

个人设置 ​

RBAC 权限 ​

管理端功能 ​

系统总览 ​

菜单管理 ​

角色管理 ​

管理员管理 ​

部门管理 ​

操作日志 ​

文件上传和存储 ​

统一上传 ​

存储配置 ​

渠道配置 ​

短信配置 ​

微信配置 ​

支付配置 ​

平台配置 ​

用户端 API ​

管理端页面能力 ​

数据库 ​

初始化脚本 ​

基础数据表 ​

接口和开发规范 ​

安装与启动 ​

1. 初始化数据库 ​

2. 创建配置文件 ​

3. 启动服务端 ​

4. 启动管理端 ​

发布检查 ​

版本边界 ​

v0.0.1 版本功能说明

版本信息

技术栈

服务端

管理端

核心架构

双端服务

服务基础能力

登录、账号和权限

管理端登录

个人设置

RBAC 权限

管理端功能

系统总览

菜单管理

角色管理

管理员管理

部门管理

操作日志

文件上传和存储

统一上传

存储配置

渠道配置

短信配置

微信配置

支付配置

平台配置

用户端 API

管理端页面能力

数据库

初始化脚本

基础数据表

接口和开发规范

安装与启动

1. 初始化数据库

2. 创建配置文件

3. 启动服务端

4. 启动管理端

发布检查

版本边界