refactor(account): 统一账号管理API、完善权限检查和操作审计

- 合并 customer_account 和 shop_account 路由到统一的 account 接口
- 新增统一认证接口 (auth handler)
- 实现越权防护中间件和权限检查工具函数
- 新增操作审计日志模型和服务
- 更新数据库迁移 (版本 39: account_operation_log 表)
- 补充集成测试覆盖权限检查和审计日志场景

openspec/changes/archive/2026-02-02-unify-account-management-api/proposal.md

@@ -0,0 +1,118 @@
+# 统一账号管理接口重构
+
+## 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）
+- 统一错误返回，防止信息泄露
+- 完整操作审计，满足合规要求