lq/qitongxue-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f0e833b84e9b0daedfc606b0cc0cf5f396a4c341
qitongxue-api/api/admin/v1/admin.go

437 lines
16 KiB
Go
Raw Normal View History

初始化
2026-09-17 14:42:44 +08:00
package v1
import "github.com/gogf/gf/v2/frame/g"
// ===== 登录 =====
type LoginReq struct {
g.Meta `path:"/login" method:"post" tags:"admin" summary:"管理员登录"`
Account string `v:"required#请输入账号" json:"account"`
Password string `v:"required#请输入密码" json:"password"`
Remember bool `json:"remember"`
}
type LoginRes struct {
Token string `json:"token"`
NickName string `json:"nick_name"`
RoleName string `json:"role_name"`
RoleValue string `json:"role_value"`
}
type MyInfoReq struct {
g.Meta `path:"/user/my-info" method:"get" tags:"admin" summary:"当前管理员信息"`
}
type MyInfoRes struct {
小程序一些功能更新
2026-09-29 10:57:01 +08:00
Id int64 `json:"id"`
Account string `json:"account"`
NickName string `json:"nick_name"`
RoleName string `json:"role_name"`
RoleValue string `json:"role_value"`
Permissions []string `json:"permissions"` // T17：当前角色拥有的权限点，前端据此隐藏入口
}
// ===== 管理员管理（T17）=====
type AdminItem struct {
初始化
2026-09-17 14:42:44 +08:00
Id int64 `json:"id"`
Account string `json:"account"`
NickName string `json:"nick_name"`
RoleName string `json:"role_name"`
RoleValue string `json:"role_value"`
小程序一些功能更新
2026-09-29 10:57:01 +08:00
Status int `json:"status"`
CreatedAt string `json:"created_at"`
}
type AdminListReq struct {
g.Meta `path:"/admin/list" method:"get" tags:"admin" summary:"管理员列表"`
}
type AdminListRes struct {
List []AdminItem `json:"list"`
}
type AdminSaveReq struct {
g.Meta `path:"/admin/save" method:"post" tags:"admin" summary:"新增/修改管理员"`
Id int64 `json:"id"`
Account string `json:"account"` // 新增必填；编辑时不可改
Password string `json:"password"`
NickName string `json:"nick_name"`
RoleName string `json:"role_name"`
RoleValue string `json:"role_value" v:"required|in:super,operator,readonly#角色非法"`
}
type AdminSaveRes struct{}
type AdminStatusReq struct {
g.Meta `path:"/admin/status" method:"post" tags:"admin" summary:"启停管理员"`
Id int64 `v:"required" json:"id"`
Status int `json:"status"`
初始化
2026-09-17 14:42:44 +08:00
}
小程序一些功能更新
2026-09-29 10:57:01 +08:00
type AdminStatusRes struct{}
// ===== 操作审计（T17）=====
type AuditItem struct {
Id int64 `json:"id"`
AdminId int64 `json:"admin_id"`
AdminAccount string `json:"admin_account"`
AdminName string `json:"admin_name"`
RoleValue string `json:"role_value"`
Action string `json:"action"`
TargetType string `json:"target_type"`
TargetId string `json:"target_id"`
BeforeJson string `json:"before_json"`
AfterJson string `json:"after_json"`
Result int `json:"result"`
Remark string `json:"remark"`
Ip string `json:"ip"`
CreatedAt string `json:"created_at"`
}
type AuditListReq struct {
g.Meta `path:"/audit/list" method:"get" tags:"admin" summary:"操作审计列表"`
Page int `json:"page"`
PageSize int `json:"pageSize"`
AdminKeyword string `json:"adminKeyword"` // 操作人账号模糊匹配
Action string `json:"action"` // 模糊匹配
Result *int `json:"result"` // nil=全部
DateFrom string `json:"dateFrom"` // YYYY-MM-DD
DateTo string `json:"dateTo"` // YYYY-MM-DD
}
type AuditListRes struct {
List []AuditItem `json:"list"`
Total int `json:"total"`
}
// AuditRecordReq 前端主动上报审计（如「导出」为纯前端动作，服务端无法感知）
type AuditRecordReq struct {
g.Meta `path:"/audit/record" method:"post" tags:"admin" summary:"上报一条操作审计"`
Action string `v:"required" json:"action"`
TargetType string `json:"target_type"`
TargetId string `json:"target_id"`
Remark string `json:"remark"`
}
type AuditRecordRes struct{}
初始化
2026-09-17 14:42:44 +08:00
// ===== 用户管理 =====
type AdminUserItem struct {
小程序虚拟支付
2026-09-17 17:38:45 +08:00
Id int64 `json:"id"`
Nickname string `json:"nickname"`
AvatarUrl string `json:"avatar_url"`
Openid string `json:"openid"`
LevelKey string `json:"level_key"`
LevelName string `json:"level_name"`
LevelExpireAt string `json:"level_expire_at"`
QuotaPeriodDays int `json:"quota_period_days"` // 0 = 跟随全局设置
Status int `json:"status"`
UsageCount int64 `json:"usage_count"`
LastUsedAt string `json:"last_used_at"`
CreatedAt string `json:"created_at"`
初始化
2026-09-17 14:42:44 +08:00
}
type UserListReq struct {
g.Meta `path:"/user/list" method:"get" tags:"admin" summary:"用户列表"`
Page int `json:"page"`
PageSize int `json:"pageSize"`
Keyword string `json:"keyword"`
小程序一些功能更新
2026-09-29 10:57:01 +08:00
// ===== T16 多条件筛选 =====
LevelKey string `json:"levelKey"` // 按等级筛选（空=全部）
Status *int `json:"status"` // 按状态筛选（nil=全部，0/1 精确匹配）
DateFrom string `json:"dateFrom"` // 注册时间范围起（YYYY-MM-DD）
DateTo string `json:"dateTo"` // 注册时间范围止（YYYY-MM-DD）
// ===== T16 排序（sortBy 走白名单，非法值回落默认）=====
SortBy string `json:"sortBy"` // id/created_at/level_key/status
SortOrder string `json:"sortOrder"` // asc/desc
// ===== T04.6 会员到期筛选 =====
// expiring7 | expiring30 | expired | forever | none | 空
MemberExpire string `json:"memberExpire"`
初始化
2026-09-17 14:42:44 +08:00
}
type UserListRes struct {
List []AdminUserItem `json:"list"`
Total int `json:"total"`
}
type UserSetLevelReq struct {
g.Meta `path:"/user/set-level" method:"post" tags:"admin" summary:"设置用户等级"`
UserId int64 `v:"required" json:"userId"`
LevelKey string `v:"required" json:"levelKey"`
小程序一些功能更新
2026-09-29 10:57:01 +08:00
// ExpireAt 到期时间；**空 = 永久（写 NULL）**。
// 续费/开通时不得把已存在的 NULL（永久）覆写成有限期（约定 S10）。
ExpireAt string `json:"expireAt"`
Remark string `json:"remark"`
初始化
2026-09-17 14:42:44 +08:00
}
type UserSetLevelRes struct{}
type UserStatusReq struct {
g.Meta `path:"/user/status" method:"post" tags:"admin" summary:"启停用户"`
UserId int64 `v:"required" json:"userId"`
Status int `json:"status"`
}
type UserStatusRes struct{}
// ===== 等级管理 =====
type LevelItem struct {
Id int64 `json:"id"`
LevelKey string `json:"level_key"`
Name string `json:"name"`
Modules []string `json:"modules"`
Sort int `json:"sort"`
IsEnabled int `json:"is_enabled"`
Remark string `json:"remark"`
}
type LevelListReq struct {
g.Meta `path:"/level/list" method:"get" tags:"admin" summary:"等级列表"`
}
type LevelListRes struct {
List []LevelItem `json:"list"`
}
小程序一些功能更新
2026-09-29 10:57:01 +08:00
// LevelSaveReq 保存等级。
// 注意：LevelKey 是跨端契约字段（小程序按它判定权益），**任何情况必填**；
// 编辑路径同样要回传原值（服务端会校验其与库中一致，不允许变更）。
初始化
2026-09-17 14:42:44 +08:00
type LevelSaveReq struct {
g.Meta `path:"/level/save" method:"post" tags:"admin" summary:"保存等级"`
Id int64 `json:"id"`
小程序一些功能更新
2026-09-29 10:57:01 +08:00
LevelKey string `v:"required#等级标识不能为空" json:"levelKey"`
初始化
2026-09-17 14:42:44 +08:00
Name string `v:"required#等级名称不能为空" json:"name"`
Modules []string `v:"required#至少勾选一个模块" json:"modules"`
Sort int `json:"sort"`
IsEnabled int `json:"isEnabled"`
Remark string `json:"remark"`
}
type LevelSaveRes struct{}
// ===== 模块管理 =====
type ModuleItem struct {
Id int64 `json:"id"`
ModuleKey string `json:"module_key"`
Name string `json:"name"`
Icon string `json:"icon"`
Description string `json:"description"`
Sort int `json:"sort"`
IsEnabled int `json:"is_enabled"`
ToolCount int `json:"tool_count"`
}
type ModuleListReq struct {
g.Meta `path:"/module/list" method:"get" tags:"admin" summary:"模块列表"`
}
type ModuleListRes struct {
List []ModuleItem `json:"list"`
}
type ModuleSaveReq struct {
g.Meta `path:"/module/save" method:"post" tags:"admin" summary:"保存模块"`
Id int64 `json:"id"`
ModuleKey string `v:"required-if:id,0#模块标识不能为空" json:"moduleKey"`
Name string `v:"required#模块名称不能为空" json:"name"`
Icon string `json:"icon"`
Description string `json:"description"`
Sort int `json:"sort"`
IsEnabled int `json:"isEnabled"`
}
type ModuleSaveRes struct{}
// ===== 工具管理 =====
type AdminToolItem struct {
Id int64 `json:"id"`
ToolKey string `json:"tool_key"`
ModuleKey string `json:"module_key"`
ModuleName string `json:"module_name"`
Name string `json:"name"`
Icon string `json:"icon"`
Description string `json:"description"`
小程序虚拟支付
2026-09-17 17:38:45 +08:00
FreeQuota int `json:"free_quota"` // 免费额度（每周期次数）
MemberQuota int `json:"member_quota"` // 会员额度（每周期次数）
PayCost int `json:"pay_cost"` // 付费额度每次消耗系数
初始化
2026-09-17 14:42:44 +08:00
Sort int `json:"sort"`
IsEnabled int `json:"is_enabled"`
IsHot int `json:"is_hot"`
UsageCount int64 `json:"usage_count"`
}
type ToolsListReq struct {
g.Meta `path:"/tools/all" method:"get" tags:"admin" summary:"工具列表（全量）"`
Page int `json:"page"`
PageSize int `json:"pageSize"`
ModuleKey string `json:"moduleKey"`
Keyword string `json:"keyword"`
IncludeDisabled bool `json:"includeDisabled"`
小程序一些功能更新
2026-09-29 10:57:01 +08:00
// ===== T16 多条件筛选 =====
IsEnabled *int `json:"isEnabled"` // 按上下架筛选（nil=不限）
IsHot *int `json:"isHot"` // 按推荐位筛选（nil=不限）
// ===== T16 排序（sortBy 走白名单，非法值回落默认）=====
SortBy string `json:"sortBy"` // id/sort/usage_count/is_enabled/is_hot/name/module_key
SortOrder string `json:"sortOrder"` // asc/desc
初始化
2026-09-17 14:42:44 +08:00
}
type ToolsListRes struct {
List []AdminToolItem `json:"list"`
Total int `json:"total"`
}
type ToolsSaveReq struct {
小程序虚拟支付
2026-09-17 17:38:45 +08:00
g.Meta `path:"/tools/save" method:"post" tags:"admin" summary:"保存工具（含额度配置）"`
初始化
2026-09-17 14:42:44 +08:00
Id int64 `json:"id"`
ToolKey string `v:"required-if:id,0#工具标识不能为空" json:"toolKey"`
ModuleKey string `v:"required#所属模块不能为空" json:"moduleKey"`
Name string `v:"required#工具名称不能为空" json:"name"`
Icon string `json:"icon"`
Description string `json:"description"`
小程序虚拟支付
2026-09-17 17:38:45 +08:00
FreeQuota int `v:"min:0#免费额度不能为负" json:"freeQuota"`
MemberQuota int `v:"min:0#会员额度不能为负" json:"memberQuota"`
PayCost int `v:"min:1#付费消耗系数至少为 1" json:"payCost"`
初始化
2026-09-17 14:42:44 +08:00
Sort int `json:"sort"`
IsEnabled int `json:"isEnabled"`
IsHot int `json:"isHot"`
}
type ToolsSaveRes struct{}
type ToolsToggleReq struct {
g.Meta `path:"/tools/toggle" method:"post" tags:"admin" summary:"工具开关"`
Id int64 `v:"required" json:"id"`
Field string `v:"required|in:is_enabled,is_hot" json:"field"`
Value int `json:"value"`
}
type ToolsToggleRes struct{}
// ===== 数据看板 =====
type TrendItem struct {
Date string `json:"date"`
Count int64 `json:"count"`
}
type TopItem struct {
ToolKey string `json:"tool_key"`
Name string `json:"name"`
Count int64 `json:"count"`
}
小程序一些功能更新
2026-09-29 10:57:01 +08:00
// AmountItem 金额趋势点（T16）：cents 为「分」，避免浮点误差。
type AmountItem struct {
Date string `json:"date"`
Cents int64 `json:"cents"`
}
// LevelDistItem 等级分布项（T16）
type LevelDistItem struct {
LevelKey string `json:"level_key"`
Name string `json:"name"`
Count int64 `json:"count"`
}
// DistItem 通用分布项（T16）：key 机读，label 展示
type DistItem struct {
Key string `json:"key"`
Label string `json:"label"`
Value int64 `json:"value"`
}
初始化
2026-09-17 14:42:44 +08:00
type DashboardStatsReq struct {
g.Meta `path:"/dashboard/stats" method:"get" tags:"admin" summary:"看板统计"`
}
小程序一些功能更新
2026-09-29 10:57:01 +08:00
// DashboardStatsRes 看板统计响应。
//
// ⚠️ 历史豁免（S1 例外）：本结构体出参为 **camelCase**（userCount / revenueCents /
// quotaFreeUsed …），系与前端 qitongxue-admin/src/views/dashboard/Dashboard.vue 一致
// 约定的**既有接口**，**勿单独改成 snake_case** —— 改动必须前后端同步，否则会直接打断看板。
// 注意本接口键风格本身**不对称**：顶层键为 camelCase，而嵌套项为 snake_case
// （如 levelDist 元素读 level_key / name / count，见 Dashboard.vue:108）。
// 豁免**仅限已列明的既有接口，不得新增**：新增接口一律 snake_case（铁律 S1）。
初始化
2026-09-17 14:42:44 +08:00
type DashboardStatsRes struct {
UserCount int64 `json:"userCount"`
TodayActive int64 `json:"todayActive"`
TotalUsage int64 `json:"totalUsage"`
WeekTrend []TrendItem `json:"weekTrend"`
ToolsTop []TopItem `json:"toolsTop"`
小程序一些功能更新
2026-09-29 10:57:01 +08:00
// ===== T16 指标扩充（全部后端聚合，前端不再拉全量自算）=====
MemberCount int64 `json:"memberCount"` // 当前有效会员数（有到期时间且未过期、等级高于默认）
OrderCount int64 `json:"orderCount"` // 已发货订单数
RevenueCents int64 `json:"revenueCents"` // 累计收入（已发货订单金额，分）
RevenueTrend []AmountItem `json:"revenueTrend"` // 近 7 日收入趋势（分，缺失补 0）
QuotaFreeUsed int64 `json:"quotaFreeUsed"` // 本周期免费额度已用合计
QuotaMemberUsed int64 `json:"quotaMemberUsed"` // 本周期会员额度已用合计
QuotaPaidUsed int64 `json:"quotaPaidUsed"` // 付费额度累计已消耗（次数包)
LevelDist []LevelDistItem `json:"levelDist"` // 各等级用户分布
OrderDist []DistItem `json:"orderDist"` // 订单构成（会员套餐 / 次数包）
初始化
2026-09-17 14:42:44 +08:00
}
// ===== 反馈管理 =====
type FeedbackItem struct {
Id int64 `json:"id"`
UserId int64 `json:"user_id"`
Content string `json:"content"`
Contact string `json:"contact"`
Status int `json:"status"`
小程序一些功能更新
2026-09-29 15:48:13 +08:00
Reply string `json:"reply"` // 官方回复内容（空=未回复）
ReplyAt string `json:"reply_at"` // 最近回复时间
初始化
2026-09-17 14:42:44 +08:00
CreatedAt string `json:"created_at"`
}
type FeedbackListReq struct {
g.Meta `path:"/feedback/list" method:"get" tags:"admin" summary:"反馈列表"`
Page int `json:"page"`
PageSize int `json:"pageSize"`
Status *int `json:"status"`
}
type FeedbackListRes struct {
List []FeedbackItem `json:"list"`
Total int `json:"total"`
}
小程序一些功能更新
2026-09-29 15:48:13 +08:00
// FeedbackHandleReq 反馈处理：标记已处理，可同时携带官方回复（回复后用户端红点提醒）。
初始化
2026-09-17 14:42:44 +08:00
type FeedbackHandleReq struct {
小程序一些功能更新
2026-09-29 15:48:13 +08:00
g.Meta `path:"/feedback/handle" method:"post" tags:"admin" summary:"反馈处理（标记已处理，可回复）"`
Id int64 `v:"required" json:"id"`
Reply string `json:"reply"`
初始化
2026-09-17 14:42:44 +08:00
}
type FeedbackHandleRes struct{}
小程序一些功能更新
2026-09-29 10:57:01 +08:00
// ===== 批量操作（T15）=====
//
// 统一契约：请求 ids + action(+参数)，响应「部分成功」结果：
//
// success 成功的条数
// failed 失败的条数
// failures 失败明细（id + 原因），用于前端逐条展示
//
// 语义：幂等（重复提交同一批得到同样结果）；不存在的 id 计入 failed 而非整体报错。
// BatchFailure 单条失败明细
type BatchFailure struct {
Id int64 `json:"id"`
Reason string `json:"reason"`
}
// UserBatchReq 批量操作用户：action=status（启停）/ level（改等级）/ delete（软删除，可恢复）
type UserBatchReq struct {
g.Meta `path:"/user/batch" method:"post" tags:"admin" summary:"批量操作用户"`
Ids []int64 `v:"required|min-length:1#请选择要操作的用户" json:"ids"`
Action string `v:"required|in:status,level,delete#动作非法" json:"action"`
Status int `json:"status"` // action=status 时使用（0/1）
LevelKey string `json:"level_key"` // action=level 时使用
}
type UserBatchRes struct {
Success int `json:"success"`
Failed int `json:"failed"`
Failures []BatchFailure `json:"failures"`
}
// ToolsBatchReq 批量操作工具：action=is_enabled / is_hot / delete（软删除，可恢复）
type ToolsBatchReq struct {
g.Meta `path:"/tools/batch" method:"post" tags:"admin" summary:"批量操作工具"`
Ids []int64 `v:"required|min-length:1#请选择要操作的工具" json:"ids"`
Action string `v:"required|in:is_enabled,is_hot,delete#动作非法" json:"action"`
Value int `json:"value"` // 0/1
}
type ToolsBatchRes struct {
Success int `json:"success"`
Failed int `json:"failed"`
Failures []BatchFailure `json:"failures"`
}
Reference in New Issue Copy Permalink