huang
80f560df33
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m17s
- 合并 customer_account 和 shop_account 路由到统一的 account 接口 - 新增统一认证接口 (auth handler) - 实现越权防护中间件和权限检查工具函数 - 新增操作审计日志模型和服务 - 更新数据库迁移 (版本 39: account_operation_log 表) - 补充集成测试覆盖权限检查和审计日志场景
119 lines
5.1 KiB
Markdown
119 lines
5.1 KiB
Markdown
# 统一账号管理接口重构
|
||
|
||
## Why
|
||
|
||
当前账号管理接口存在严重的架构混乱和安全漏洞：
|
||
1. **接口重复**：`/accounts` 和 `/platform-accounts` 使用同一个 Handler，功能完全重复（20个重复接口）
|
||
2. **功能不一致**：平台账号有完整的 CRUD + 角色管理，而代理/企业账号缺少关键功能
|
||
3. **命名混乱**：`/customer-accounts` 实际管理的是企业账号，代码注释错误
|
||
4. **安全漏洞**：Create 操作缺少越权检查，代理可以为其他店铺创建账号
|
||
5. **可维护性差**：三个独立的 Service（Account、ShopAccount、CustomerAccount）导致代码重复和不一致
|
||
|
||
这次重构将统一接口架构，消除重复，加固安全防护，并添加完整的操作审计，为后续功能扩展打下坚实基础。
|
||
|
||
## What Changes
|
||
|
||
- **BREAKING**: 删除旧路由
|
||
- 删除 `/api/admin/platform-accounts/*`（10个接口）
|
||
- 删除 `/api/admin/shop-accounts/*`（5个接口）
|
||
- 删除 `/api/admin/customer-accounts/*`（5个接口）
|
||
- **新增**: 统一账号管理路由
|
||
- `/api/admin/accounts/platform/*`（平台账号管理）
|
||
- `/api/admin/accounts/shop/*`（代理账号管理）
|
||
- `/api/admin/accounts/enterprise/*`（企业账号管理）
|
||
- **BREAKING**: 认证接口统一
|
||
- 删除 `/api/admin/login`、`/api/admin/logout` 等（5个接口）
|
||
- 删除 `/api/h5/login`、`/api/h5/logout` 等（5个接口）
|
||
- 新增 `/api/auth/*` 统一认证（5个接口）
|
||
- 保留 `/api/c/v1/*` 个人客户认证（独立业务逻辑）
|
||
- **新增**: 三层越权防护机制
|
||
- 路由层：企业账号中间件拦截
|
||
- Service 层：CanManageShop/CanManageEnterprise 权限检查
|
||
- GORM 层：已有自动过滤（保持）
|
||
- **新增**: 操作审计系统
|
||
- 数据库迁移：创建 `tb_account_operation_log` 表
|
||
- Service：AccountAuditService 记录所有账号操作
|
||
- 集成：Create/Update/Delete/AssignRoles 自动记录
|
||
- **重构**: 合并 Service 层
|
||
- 删除 ShopAccountService、CustomerAccountService
|
||
- 扩展 AccountService 支持所有账号类型
|
||
- 统一错误返回："无权限操作该资源或资源不存在"
|
||
- **重构**: 合并 Handler 层
|
||
- 删除 ShopAccountHandler、CustomerAccountHandler
|
||
- 扩展 AccountHandler 支持所有账号类型
|
||
- **新增**: 权限辅助函数
|
||
- `pkg/middleware/permission_helper.go`
|
||
- CanManageShop：验证代理对目标店铺的管理权限
|
||
- CanManageEnterprise：验证代理对目标企业的管理权限
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
- `account-permission-check`：账号管理权限检查机制（三层防护）
|
||
- `account-operation-audit`：账号操作审计日志系统
|
||
- `unified-auth-api`：统一认证接口（后台+H5）
|
||
|
||
### Modified Capabilities
|
||
- `account-management`：账号管理接口架构（统一路由结构，消除重复）
|
||
|
||
## Impact
|
||
|
||
**代码变更**：
|
||
- 删除文件：
|
||
- `internal/handler/admin/shop_account.go`
|
||
- `internal/handler/admin/customer_account.go`
|
||
- `internal/service/shop_account/service.go`
|
||
- `internal/service/customer_account/service.go`
|
||
- `internal/routes/shop.go`（部分）
|
||
- `internal/routes/customer_account.go`
|
||
- 修改文件：
|
||
- `internal/handler/admin/account.go`（扩展支持所有账号类型）
|
||
- `internal/service/account/service.go`（添加权限检查和审计）
|
||
- `internal/routes/account.go`（新路由结构）
|
||
- `internal/routes/admin.go`（更新路由注册）
|
||
- 新增文件：
|
||
- `pkg/middleware/permission_helper.go`（权限检查函数）
|
||
- `internal/model/account_operation_log.go`（审计日志模型）
|
||
- `internal/store/postgres/account_operation_log_store.go`（审计日志存储）
|
||
- `internal/service/account_audit/service.go`（审计日志服务）
|
||
- `migrations/XXXXXX_create_account_operation_log.up.sql`（数据库迁移）
|
||
|
||
**API 变更**（Breaking Changes）：
|
||
- 前端需要更新所有账号管理接口调用
|
||
- 新旧路由映射：
|
||
```
|
||
旧：POST /api/admin/platform-accounts
|
||
新：POST /api/admin/accounts/platform
|
||
|
||
旧：GET /api/admin/shop-accounts
|
||
新：GET /api/admin/accounts/shop
|
||
|
||
旧：POST /api/admin/customer-accounts
|
||
新：POST /api/admin/accounts/enterprise
|
||
|
||
旧：POST /api/admin/login
|
||
新：POST /api/auth/login
|
||
```
|
||
|
||
**测试变更**：
|
||
- 删除：`tests/integration/platform_account_test.go`（已有 account_test.go）
|
||
- 删除：`tests/integration/shop_account_management_test.go`
|
||
- 删除：`tests/unit/customer_account_service_test.go`
|
||
- 修改：`tests/integration/account_test.go`（扩展覆盖所有账号类型）
|
||
- 新增：`tests/integration/account_permission_test.go`（越权防护测试）
|
||
- 新增：`tests/integration/account_audit_test.go`（审计日志测试）
|
||
|
||
**依赖影响**：
|
||
- 无新增外部依赖
|
||
- 内部依赖调整：AccountService 新增 ShopStore 和 EnterpriseStore 依赖
|
||
|
||
**性能影响**：
|
||
- 权限检查：增加 GetSubordinateShopIDs 调用（已有 Redis 缓存，影响 < 5ms）
|
||
- 审计日志：异步写入，不阻塞主流程
|
||
- 预期 API 响应时间增加 < 10ms
|
||
|
||
**安全提升**：
|
||
- 修复 Create 操作越权漏洞（Critical）
|
||
- 统一错误返回，防止信息泄露
|
||
- 完整操作审计，满足合规要求
|