refactor(account): 统一账号管理API、完善权限检查和操作审计
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 6m17s
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 6m17s
- 合并 customer_account 和 shop_account 路由到统一的 account 接口 - 新增统一认证接口 (auth handler) - 实现越权防护中间件和权限检查工具函数 - 新增操作审计日志模型和服务 - 更新数据库迁移 (版本 39: account_operation_log 表) - 补充集成测试覆盖权限检查和审计日志场景
This commit is contained in:
88
AGENTS.md
88
AGENTS.md
@@ -283,6 +283,94 @@ func TestAPI_Create(t *testing.T) {
|
||||
- [ ] 导出函数/类型有文档注释
|
||||
- [ ] API 路径注释与真实路由一致
|
||||
|
||||
### 越权防护规范
|
||||
|
||||
**适用场景**:任何涉及跨用户、跨店铺、跨企业的资源访问
|
||||
|
||||
**三层防护机制**:
|
||||
|
||||
1. **路由层中间件**(粗粒度拦截)
|
||||
- 用于明显的权限限制(如企业账号禁止访问账号管理)
|
||||
- 示例:
|
||||
```go
|
||||
group.Use(func(c *fiber.Ctx) error {
|
||||
userType := middleware.GetUserTypeFromContext(c.UserContext())
|
||||
if userType == constants.UserTypeEnterprise {
|
||||
return errors.New(errors.CodeForbidden, "无权限访问账号管理功能")
|
||||
}
|
||||
return c.Next()
|
||||
})
|
||||
```
|
||||
|
||||
2. **Service 层业务检查**(细粒度验证)
|
||||
- 使用 `middleware.CanManageShop(ctx, targetShopID, shopStore)` 验证店铺权限
|
||||
- 使用 `middleware.CanManageEnterprise(ctx, targetEnterpriseID, enterpriseStore, shopStore)` 验证企业权限
|
||||
- 类型级权限检查(如代理不能创建平台账号)
|
||||
- 示例见 `internal/service/account/service.go`
|
||||
|
||||
3. **GORM Callback 自动过滤**(兜底)
|
||||
- 已有实现,自动应用到所有查询
|
||||
- 代理用户:`WHERE shop_id IN (自己店铺+下级店铺)`
|
||||
- 企业用户:`WHERE enterprise_id = 当前企业ID`
|
||||
- 无需手动调用
|
||||
|
||||
**统一错误返回**:
|
||||
- 越权访问统一返回:`errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")`
|
||||
- 不区分"不存在"和"无权限",防止信息泄露
|
||||
|
||||
### 审计日志规范
|
||||
|
||||
**适用场景**:任何敏感操作(账号管理、权限变更、数据删除等)
|
||||
|
||||
**使用方式**:
|
||||
|
||||
1. **Service 层集成审计日志**:
|
||||
```go
|
||||
type Service struct {
|
||||
store *Store
|
||||
auditService AuditServiceInterface
|
||||
}
|
||||
|
||||
func (s *Service) SensitiveOperation(ctx context.Context, ...) error {
|
||||
// 1. 执行业务操作
|
||||
err := s.store.DoSomething(ctx, ...)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// 2. 记录审计日志(异步)
|
||||
s.auditService.LogOperation(ctx, &model.OperationLog{
|
||||
OperatorID: middleware.GetUserIDFromContext(ctx),
|
||||
OperationType: "operation_type",
|
||||
OperationDesc: "操作描述",
|
||||
BeforeData: beforeData, // 变更前数据
|
||||
AfterData: afterData, // 变更后数据
|
||||
RequestID: middleware.GetRequestIDFromContext(ctx),
|
||||
IPAddress: middleware.GetIPFromContext(ctx),
|
||||
UserAgent: middleware.GetUserAgentFromContext(ctx),
|
||||
})
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
2. **审计日志字段说明**:
|
||||
- `operator_id`, `operator_type`, `operator_name`: 操作人信息(必填)
|
||||
- `target_*`: 目标资源信息(可选)
|
||||
- `operation_type`: 操作类型(create/update/delete/assign_roles等)
|
||||
- `operation_desc`: 操作描述(中文,便于查看)
|
||||
- `before_data`, `after_data`: 变更数据(JSON 格式)
|
||||
- `request_id`, `ip_address`, `user_agent`: 请求上下文
|
||||
|
||||
3. **异步写入**:
|
||||
- 审计日志使用 Goroutine 异步写入
|
||||
- 写入失败不影响业务操作
|
||||
- 失败时记录 Error 日志,包含完整审计信息
|
||||
|
||||
**示例参考**:`internal/service/account/service.go`
|
||||
|
||||
---
|
||||
|
||||
### ⚠️ 任务执行规范(必须遵守)
|
||||
|
||||
**提案中的 tasks.md 是契约,不可擅自变更:**
|
||||
|
||||
Reference in New Issue
Block a user