perms-system-server/perm.api

syntax = "v1"

info (
	title:   "Permission System API"
	desc:    "权限管理系统"
	version: "1.0"
)

// ==================== Common ====================
type PageResp {
	Total int64       `json:"total"`
	List  interface{} `json:"list"`
}

// ==================== Auth ====================
type (
	CaptchaReq {
		Width  int `json:"width,optional"`
		Height int `json:"height,optional"`
	}
	CaptchaInfo {
		Id          string `json:"id"`
		Base64Image string `json:"base64image"`
	}
	CapEndpointResp {
		Data string `json:"data"`
	}
	LoginReq {
		Username    string `json:"username"`
		Password    string `json:"password"`
		ProductCode string `json:"productCode"`
		CaptchaId   string `json:"captchaId,optional"`
		CaptchaCode string `json:"captchaCode,optional"`
	}
	LoginByCapReq {
		Username    string `json:"username"`
		Password    string `json:"password"`
		ProductCode string `json:"productCode"`
		CapToken    string `json:"capToken"`
	}
	AdminLoginReq {
		Username      string `json:"username"`
		Password      string `json:"password"`
		ManagementKey string `json:"managementKey"`
		CaptchaId     string `json:"captchaId,optional"`
		CaptchaCode   string `json:"captchaCode,optional"`
	}
	AdminLoginByCapReq {
		Username      string `json:"username"`
		Password      string `json:"password"`
		ManagementKey string `json:"managementKey"`
		CapToken      string `json:"capToken"`
	}
	LoginResp {
		AccessToken  string   `json:"accessToken"`
		RefreshToken string   `json:"refreshToken"`
		Expires      int64    `json:"expires"`
		UserInfo     UserInfo `json:"userInfo"`
	}
	UserInfo {
		UserId             int64    `json:"userId"`
		Username           string   `json:"username"`
		Nickname           string   `json:"nickname"`
		Avatar             string   `json:"avatar"`
		Email              string   `json:"email"`
		Phone              string   `json:"phone"`
		IsSuperAdmin       int64    `json:"isSuperAdmin"`
		MustChangePassword int64    `json:"mustChangePassword"`
		MemberType         string   `json:"memberType"`
		Perms              []string `json:"perms"`
	}
	RefreshTokenReq {
		Authorization string `header:"Authorization"`
		ProductCode   string `json:"productCode,optional"`
	}
	ChangePasswordReq {
		OldPassword string `json:"oldPassword"`
		NewPassword string `json:"newPassword"`
	}
	UpdateSelfInfoReq {
		Nickname *string `json:"nickname,optional"`
		Avatar   *string `json:"avatar,optional"`
		Email    *string `json:"email,optional"`
		Phone    *string `json:"phone,optional"`
	}
)

// ==================== Product ====================
type (
	CreateProductReq {
		Code   string `json:"code"`
		Name   string `json:"name"`
		Remark string `json:"remark,optional"`
		// 审计 L-R10-1：新建 admin_<code> 用户时必须一并指定部门。若不带部门（DeptId=0），新账号
		// 在 CheckAddMemberAccess / CreateUser 的 DeptPath 前缀校验下彻底瘫痪，除了改密码外做不了任何管理动作。
		AdminDeptId int64 `json:"adminDeptId"`
	}
	CreateProductResp {
		Id        int64  `json:"id"`
		Code      string `json:"code"`
		AppKey    string `json:"appKey"`
		AdminUser string `json:"adminUser"`
		// CredentialsTicket 一次性凭证票据。AppSecret 与初始 AdminPassword 不再随本响应明文返回，
		// 改为由调用方用该 ticket 调一次 /api/product/fetchInitialCredentials 领取（5 分钟内有效，
		// 一次性消费）。审计 M-4：避免密码/密钥经响应体落盘到上游日志/APM。
		CredentialsTicket    string `json:"credentialsTicket"`
		CredentialsExpiresAt int64  `json:"credentialsExpiresAt"`
	}
	FetchInitialCredentialsReq {
		Ticket string `json:"ticket"`
	}
	FetchInitialCredentialsResp {
		AppKey        string `json:"appKey"`
		AppSecret     string `json:"appSecret"`
		AdminUser     string `json:"adminUser"`
		AdminPassword string `json:"adminPassword"`
	}
	UpdateProductReq {
		Id     int64  `json:"id"`
		Name   string `json:"name"`
		Remark string `json:"remark,optional"`
		Status int64  `json:"status,optional"`
	}
	ProductListReq {
		Page     int64 `json:"page,optional"`
		PageSize int64 `json:"pageSize,optional"`
	}
	ProductDetailReq {
		Id int64 `json:"id"`
	}
	ProductItem {
		Id         int64  `json:"id"`
		Code       string `json:"code"`
		Name       string `json:"name"`
		AppKey     string `json:"appKey"`
		Remark     string `json:"remark"`
		Status     int64  `json:"status"`
		CreateTime int64  `json:"createTime"`
	}
)

// ==================== Perm ====================
type (
	PermListReq {
		ProductCode string `json:"productCode"`
		Page        int64  `json:"page,optional"`
		PageSize    int64  `json:"pageSize,optional"`
	}
	PermItem {
		Id          int64  `json:"id"`
		ProductCode string `json:"productCode"`
		Name        string `json:"name"`
		Code        string `json:"code"`
		Remark      string `json:"remark"`
		Status      int64  `json:"status"`
		CreateTime  int64  `json:"createTime"`
	}
	SyncPermItem {
		Code   string `json:"code"`
		Name   string `json:"name"`
		Remark string `json:"remark,optional"`
	}
	SyncPermsReq {
		AppKey    string         `json:"appKey"`
		AppSecret string         `json:"appSecret"`
		Perms     []SyncPermItem `json:"perms"`
	}
	SyncPermsResp {
		Added    int64 `json:"added"`
		Updated  int64 `json:"updated"`
		Disabled int64 `json:"disabled"`
	}
)

// ==================== Role ====================
type (
	CreateRoleReq {
		ProductCode string `json:"productCode"`
		Name        string `json:"name"`
		Remark      string `json:"remark,optional"`
		PermsLevel  int64  `json:"permsLevel"`
	}
	UpdateRoleReq {
		Id         int64  `json:"id"`
		Name       string `json:"name"`
		Remark     string `json:"remark,optional"`
		PermsLevel int64  `json:"permsLevel"`
		Status     int64  `json:"status,optional"`
	}
	DeleteRoleReq {
		Id int64 `json:"id"`
	}
	RoleListReq {
		ProductCode string `json:"productCode"`
		Page        int64  `json:"page,optional"`
		PageSize    int64  `json:"pageSize,optional"`
	}
	RoleDetailReq {
		Id int64 `json:"id"`
	}
	RoleItem {
		Id          int64   `json:"id"`
		ProductCode string  `json:"productCode"`
		Name        string  `json:"name"`
		Remark      string  `json:"remark"`
		Status      int64   `json:"status"`
		PermsLevel  int64   `json:"permsLevel"`
		PermIds     []int64 `json:"permIds,omitempty"`
		CreateTime  int64   `json:"createTime"`
	}
	BindPermsReq {
		RoleId  int64   `json:"roleId"`
		PermIds []int64 `json:"permIds"`
	}
)

// ==================== Dept ====================
type (
	CreateDeptReq {
		ParentId int64  `json:"parentId"`
		Name     string `json:"name"`
		Sort     int64  `json:"sort,optional"`
		DeptType string `json:"deptType,optional"`
		Remark   string `json:"remark,optional"`
	}
	UpdateDeptReq {
		Id       int64  `json:"id"`
		Name     string `json:"name"`
		Sort     int64  `json:"sort,optional"`
		DeptType string `json:"deptType,optional"`
		Remark   string `json:"remark,optional"`
		Status   int64  `json:"status,optional"`
	}
	DeleteDeptReq {
		Id int64 `json:"id"`
	}
	DeptItem {
		Id         int64       `json:"id"`
		ParentId   int64       `json:"parentId"`
		Name       string      `json:"name"`
		Path       string      `json:"path"`
		Sort       int64       `json:"sort"`
		DeptType   string      `json:"deptType"`
		Remark     string      `json:"remark"`
		Status     int64       `json:"status"`
		CreateTime int64       `json:"createTime"`
		Children   []*DeptItem `json:"children"`
	}
)

// ==================== User ====================
type (
	CreateUserReq {
		Username string `json:"username"`
		Nickname string `json:"nickname,optional"`
		Email    string `json:"email,optional"`
		Phone    string `json:"phone,optional"`
		Remark   string `json:"remark,optional"`
		DeptId   int64  `json:"deptId,optional"`
	}
	CreateUserResp {
		Id                   int64  `json:"id"`
		CredentialsTicket    string `json:"credentialsTicket"`
		CredentialsExpiresAt int64  `json:"credentialsExpiresAt"`
	}
	ResetPasswordReq {
		UserId int64 `json:"userId"`
	}
	ResetPasswordResp {
		CredentialsTicket    string `json:"credentialsTicket"`
		CredentialsExpiresAt int64  `json:"credentialsExpiresAt"`
	}
	FetchUserCredentialsReq {
		Ticket string `json:"ticket"`
	}
	FetchUserCredentialsResp {
		Username string `json:"username"`
		Password string `json:"password"`
	}
	UpdateUserReq {
		Id       int64   `json:"id"`
		Nickname *string `json:"nickname,optional"`
		Email    *string `json:"email,optional"`
		Phone    *string `json:"phone,optional"`
		Remark   *string `json:"remark,optional"`
		DeptId   *int64  `json:"deptId,optional"`
		Status   int64   `json:"status,optional"`
	}
	UserListReq {
		ProductCode string `json:"productCode,optional"`
		Username    string `json:"username,optional"`
		Nickname    string `json:"nickname,optional"`
		Status      int64  `json:"status,optional"`
		DeptId      *int64 `json:"deptId,optional"`
		Page        int64  `json:"page,optional"`
		PageSize    int64  `json:"pageSize,optional"`
	}
	UserDetailReq {
		Id          int64  `json:"id"`
		ProductCode string `json:"productCode,optional"`
	}
	UserItem {
		Id         int64    `json:"id"`
		Username   string   `json:"username"`
		Nickname   string   `json:"nickname"`
		Avatar     string   `json:"avatar"`
		Email      string   `json:"email"`
		Phone      string   `json:"phone"`
		Remark     string   `json:"remark"`
		DeptId     int64    `json:"deptId"`
		Status     int64    `json:"status"`
		MemberType string   `json:"memberType,omitempty"`
		RoleIds    []int64  `json:"roleIds,omitempty"`
		Perms      []string `json:"perms,omitempty"`
		CreateTime int64    `json:"createTime"`
	}
	BindRolesReq {
		UserId      int64   `json:"userId"`
		RoleIds     []int64 `json:"roleIds"`
		ProductCode string  `json:"productCode,optional"`
	}
	UserPermItem {
		PermId int64  `json:"permId"`
		Effect string `json:"effect"`
	}
	GetUserPermsReq {
		UserId int64 `json:"userId"`
	}
	GetUserPermsResp {
		Perms []UserPermItem `json:"perms"`
	}
	SetPermsReq {
		UserId int64          `json:"userId"`
		Perms  []UserPermItem `json:"perms"`
	}
	UpdateUserStatusReq {
		Id     int64 `json:"id"`
		Status int64 `json:"status"`
	}
)

// ==================== Product Member ====================
type (
	AddMemberReq {
		ProductCode string `json:"productCode"`
		UserId      int64  `json:"userId"`
		MemberType  string `json:"memberType"`
	}
	// UpdateMemberReq 审计 L-R11-1：memberType / status 改为指针可选，支持"只改状态"或"只改
	// 成员类型"的部分更新，避免前端被迫先拉 member.detail 再构造完整字段。两字段都为 nil 时
	// logic 会立即 400 "没有可更新的字段"。
	UpdateMemberReq {
		Id         int64   `json:"id"`
		MemberType *string `json:"memberType,optional"`
		Status     *int64  `json:"status,optional"`
	}
	RemoveMemberReq {
		Id int64 `json:"id"`
	}
	MemberListReq {
		ProductCode string `json:"productCode"`
		Page        int64  `json:"page,optional"`
		PageSize    int64  `json:"pageSize,optional"`
	}
	MemberItem {
		Id          int64  `json:"id"`
		ProductCode string `json:"productCode"`
		UserId      int64  `json:"userId"`
		Username    string `json:"username"`
		Nickname    string `json:"nickname"`
		MemberType  string `json:"memberType"`
		Status      int64  `json:"status"`
		CreateTime  int64  `json:"createTime"`
	}
	UserProductsReq {
		UserId int64 `json:"userId"`
	}
	UserProductItem {
		ProductCode string `json:"productCode"`
		ProductName string `json:"productName"`
		MemberType  string `json:"memberType"`
		Status      int64  `json:"status"`
	}
	UserProductsResp {
		List []UserProductItem `json:"list"`
	}
)

// ==================== Common Response ====================
type IdResp {
	Id int64 `json:"id"`
}

// ==================== Routes ====================
// -------- 公开接口（无需 JWT 鉴权） --------
// 图片验证码与 cap.js 端点，无限流（自带内存 ID 防重）
@server (
	prefix: /api
	group:  pub
)
service perm-api {
	// Captcha 获取图片验证码（base64 编码）
	@handler Captcha
	post /captcha/get (CaptchaReq) returns (CaptchaInfo)

	// CapEndpoint 返回 cap.js 服务端点 URL；未配置时返回空串，前端据此决定显示哪种验证方式
	@handler CapEndpoint
	post /capjs/endpoint returns (CapEndpointResp)
}

// 管理后台登录，需携带 managementKey 凭证，受 IP 维度限流保护
@server (
	prefix:     /api
	group:      pub
	middleware: AdminLoginRateLimit
)
service perm-api {
	// AdminLogin 管理后台登录。仅限超级管理员通过 managementKey + 用户名密码登录管理后台，返回 JWT 令牌对。cap.js 启用时拒绝此接口（必须走 adminLogin/cap）
	@handler AdminLogin
	post /auth/adminLogin (AdminLoginReq) returns (LoginResp)

	// AdminLoginByCap 使用 cap.js 人机验证令牌登录管理后台。cap.js 未启用时拒绝此接口（必须走 adminLogin），验证通过后执行与 AdminLogin 相同的业务逻辑
	@handler AdminLoginByCap
	post /auth/adminLogin/cap (AdminLoginByCapReq) returns (LoginResp)
}

// 产品端登录，受 IP 维度限流保护
@server (
	prefix:     /api
	group:      pub
	middleware: ProductLoginRateLimit
)
service perm-api {
	// Login 产品端登录。产品成员通过用户名密码 + productCode 登录指定产品，返回 JWT 令牌对及用户权限信息。cap.js 启用时拒绝此接口（必须走 login/cap）
	@handler Login
	post /auth/login (LoginReq) returns (LoginResp)

	// LoginByCap 使用 cap.js 人机验证令牌登录。cap.js 未启用时拒绝此接口（必须走 login），验证通过后执行与 Login 相同的业务逻辑
	@handler LoginByCap
	post /auth/login/cap (LoginByCapReq) returns (LoginResp)
}

// 令牌刷新，不需要鉴权中间件，自行验证 refreshToken 有效性；受 IP 维度限流保护，防止签名爆破/CPU 放大 DoS
@server (
	prefix:     /api
	group:      pub
	middleware: RefreshTokenRateLimit
)
service perm-api {
	// RefreshToken 刷新令牌。使用有效的 refreshToken 换取新的 accessToken/refreshToken 令牌对，旧令牌即时失效（单会话轮转）
	@handler RefreshToken
	post /auth/refreshToken (RefreshTokenReq) returns (LoginResp)
}

// 权限同步，产品服务端通过 appKey/appSecret 认证，受 IP 维度限流保护
@server (
	prefix:     /api
	group:      pub
	middleware: SyncRateLimit
)
service perm-api {
	// SyncPerms 同步权限声明。产品服务端通过 appKey/appSecret 认证后，批量同步权限定义（新增/更新/禁用不在列表中的权限）
	@handler SyncPerms
	post /perm/sync (SyncPermsReq) returns (SyncPermsResp)
}

// -------- 需要 JWT 鉴权的接口 --------
// 认证相关（修改密码、获取用户信息、注销）
@server (
	prefix:     /api
	group:      auth
	middleware: JwtAuth
)
service perm-api {
	// UserInfo 获取当前登录用户信息。返回当前 JWT 令牌对应用户的个人信息、成员类型和权限列表，用于前端初始化用户状态
	@handler UserInfoHandler
	post /auth/userInfo returns (UserInfo)

	// ChangePassword 修改密码。已登录用户验证原密码后设置新密码，同时递增 tokenVersion 使所有已签发令牌失效
	@handler ChangePassword
	post /auth/changePassword (ChangePasswordReq)

	// Logout 用户注销。递增 tokenVersion 使所有已签发的 access/refresh 令牌立即失效，并清除用户缓存
	@handler Logout
	post /auth/logout

	// UpdateSelfInfo 修改当前登录用户自身信息。仅允许修改昵称、头像、邮箱、手机，userId 从 JWT 获取
	@handler UpdateSelfInfo
	post /auth/updateInfo (UpdateSelfInfoReq)
}

// 文件上传（MinIO 对象存储）
@server (
	prefix:     /api
	group:      minio
	middleware: JwtAuth
)
service perm-api {
	// MinioUpload 文件上传。上传文件到 MinIO 对象存储，根据 fileType 参数路由到对应 bucket 和目录
	@handler MinioUpload
	post /minio/upload
}

// 产品管理（仅超管可操作）
@server (
	prefix:     /api/product
	group:      product
	middleware: JwtAuth
)
service perm-api {
	// CreateProduct 创建产品。自动生成 appKey/appSecret 和产品专属管理员账号，用于接入新的业务产品。
	// 响应不再明文回吐 appSecret / adminPassword，改用 credentialsTicket 一次性领取（审计 M-4）。
	@handler CreateProduct
	post /create (CreateProductReq) returns (CreateProductResp)

	// FetchInitialCredentials 凭 CreateProduct 响应中的 credentialsTicket 一次性领取 appSecret 与
	// 初始 adminPassword。Ticket 在 Redis 中短 TTL 保存，一次消费后立即删除；即使响应被日志捕获，
	// 落盘的也仅是短期有效且一次性消耗的哨兵 token，而非真正的长期凭证。
	@handler FetchInitialCredentials
	post /fetchInitialCredentials (FetchInitialCredentialsReq) returns (FetchInitialCredentialsResp)

	// UpdateProduct 更新产品信息。可修改名称、备注和启用/禁用状态，禁用后其成员将无法访问
	@handler UpdateProduct
	post /update (UpdateProductReq)

	// ProductList 产品列表。分页查询系统中所有产品的基本信息
	@handler ProductList
	post /list (ProductListReq) returns (PageResp)

	// ProductDetail 产品详情。根据产品 ID 查询完整信息
	@handler ProductDetail
	post /detail (ProductDetailReq) returns (ProductItem)
}

// 部门管理（仅超管可操作）
@server (
	prefix:     /api/dept
	group:      dept
	middleware: JwtAuth
)
service perm-api {
	// CreateDept 创建部门。在指定父部门下新建子部门，自动继承路径层级
	@handler CreateDept
	post /create (CreateDeptReq) returns (IdResp)

	// UpdateDept 更新部门。修改名称、排序、类型、备注或启用/禁用状态，使用乐观锁防止并发冲突
	@handler UpdateDept
	post /update (UpdateDeptReq)

	// DeleteDept 删除部门。在事务内加行锁后检查是否存在子部门或关联用户，均无则删除
	@handler DeleteDept
	post /delete (DeleteDeptReq)

	// DeptTree 部门树。返回完整的组织架构树形结构，用于前端部门选择器和组织架构展示
	@handler DeptTree
	post /tree returns ([]*DeptItem)
}

// 权限查询
@server (
	prefix:     /api/perm
	group:      perm
	middleware: JwtAuth
)
service perm-api {
	// PermList 权限列表。按产品分页查询已注册的权限定义，用于角色权限配置和用户权限分配的选择列表
	@handler PermList
	post /list (PermListReq) returns (PageResp)
}

// 角色管理（需产品 ADMIN 或超管权限）
@server (
	prefix:     /api/role
	group:      role
	middleware: JwtAuth
)
service perm-api {
	// CreateRole 创建角色。在指定产品下新建角色并设置权限级别，产品必须存在且已启用
	@handler CreateRole
	post /create (CreateRoleReq) returns (IdResp)

	// UpdateRole 更新角色。修改名称、备注、权限级别和启用/禁用状态，非超管不能降低权限级别
	@handler UpdateRole
	post /update (UpdateRoleReq)

	// DeleteRole 删除角色。在事务内同时清理角色-权限和用户-角色绑定后删除，并批量清理受影响用户缓存
	@handler DeleteRole
	post /delete (DeleteRoleReq)

	// RoleList 角色列表。按产品分页查询角色信息
	@handler RoleList
	post /list (RoleListReq) returns (PageResp)

	// RoleDetail 角色详情。根据角色 ID 查询完整信息及已绑定的权限 ID 列表
	@handler RoleDetail
	post /detail (RoleDetailReq) returns (RoleItem)

	// BindRolePerms 绑定角色权限。对指定角色做权限全量覆盖（diff 后批量新增/删除）
	@handler BindRolePerms
	post /bindPerms (BindPermsReq)
}

// 用户管理
@server (
	prefix:     /api/user
	group:      user
	middleware: JwtAuth
)
service perm-api {
	// CreateUser 创建用户。服务端生成强密码，返回一次性凭证票据
	@handler CreateUser
	post /create (CreateUserReq) returns (CreateUserResp)

	// ResetPassword 重置用户密码。生成新随机密码，返回一次性凭证票据
	@handler ResetPassword
	post /resetPassword (ResetPasswordReq) returns (ResetPasswordResp)

	// FetchUserCredentials 凭票据一次性领取用户凭证（用户名+密码）
	@handler FetchUserCredentials
	post /fetchCredentials (FetchUserCredentialsReq) returns (FetchUserCredentialsResp)

	// UpdateUser 更新用户信息。修改昵称、邮箱、手机、备注、部门归属等
	@handler UpdateUser
	post /update (UpdateUserReq)

	// UserList 用户列表。超管查看全量，产品管理者查看当前产品下的成员列表
	@handler UserList
	post /list (UserListReq) returns (PageResp)

	// UserDetail 用户详情。查询指定用户基本信息和当前产品下的角色绑定
	@handler UserDetail
	post /detail (UserDetailReq) returns (UserItem)

	// GetUserPerms 查询用户在指定产品下的个性化权限（仅 ALLOW/DENY 覆盖项，不含角色继承）。超管不限；本人可查自己；其余需产品 ADMIN 权限且权限等级高于目标用户
	@handler GetUserPerms
	post /userPerms (GetUserPermsReq) returns (GetUserPermsResp)

	// BindRoles 绑定用户角色。对指定用户在当前产品下做角色全量覆盖，支持权限级别校验防止越权分配
	@handler BindRoles
	post /bindRoles (BindRolesReq)

	// SetUserPerms 设置用户个性化权限。支持 ALLOW（附加）和 DENY（拒绝）两种效果，用于角色权限之外的细粒度调整
	@handler SetUserPerms
	post /setPerms (SetPermsReq)

	// UpdateUserStatus 冻结/解冻用户。修改启用状态并递增 tokenVersion 使其令牌失效
	@handler UpdateUserStatus
	post /updateStatus (UpdateUserStatusReq)
}

// 产品成员管理（需产品 ADMIN 或超管权限）
@server (
	prefix:     /api/member
	group:      member
	middleware: JwtAuth
)
service perm-api {
	// AddMember 添加产品成员。将已有用户加入指定产品并设置成员类型（ADMIN/DEVELOPER/MEMBER），产品必须已启用
	@handler AddMember
	post /add (AddMemberReq) returns (IdResp)

	// UpdateMember 更新产品成员。修改成员类型或启用/禁用状态，降级最后一个 ADMIN 时会被拒绝
	@handler UpdateMember
	post /update (UpdateMemberReq)

	// RemoveMember 移除产品成员。同时清理该用户在产品下的角色和个性化权限绑定，不能移除最后一个 ADMIN
	@handler RemoveMember
	post /remove (RemoveMemberReq)

	// MemberList 成员列表。按产品分页查询成员信息，用于产品成员管理页面
	@handler MemberList
	post /list (MemberListReq) returns (PageResp)

	// UserProducts 查询指定用户加入的产品列表。仅超管或本人可调用，防止枚举他人产品归属
	@handler UserProducts
	post /userProducts (UserProductsReq) returns (UserProductsResp)
}