huang
18f35f3ef4
主要变更： - 新增B端认证系统（后台+H5）：登录、登出、Token刷新、密码修改 - 完善商户管理和商户账号管理功能 - 补全单元测试（ShopService: 72.5%, ShopAccountService: 79.8%） - 新增集成测试（商户管理+商户账号管理） - 归档OpenSpec提案（add-shop-account-management, implement-b-end-auth-system） - 完善文档（使用指南、API文档、认证架构说明） 测试统计： - 13个测试套件，37个测试用例，100%通过率 - 平均覆盖率76.2%，达标 OpenSpec验证：通过（strict模式）
4.6 KiB
4.6 KiB
Change: 实现代理商（店铺）管理和代理商账号管理
Why
当前系统已实现店铺（Shop）和账号（Account）基础模型，但缺少完整的代理商管理功能。业务需求包括：
- 店铺（代理商）的完整生命周期管理（新增、编辑、删除、查询）
- 店铺账号的管理（新增、编辑、密码修改、启用/禁用）
- 店铺删除时需同步禁用所有关联账号
这是实现多级代理商体系的基础功能模块。
What Changes
新增功能模块
-
代理商（店铺）管理模块 (
shop-management)- 店铺分页列表查询（支持店铺名称模糊查询，返回详细信息）
- 店铺新增/编辑（包含地址信息、联系方式、初始密码）
- 店铺删除（软删除，同步禁用所有关联账号）
-
代理商账号管理模块 (
shop-account-management)- 代理商账号分页列表查询（按店铺ID过滤）
- 代理商账号新增/编辑（账号名称、手机号、密码、状态）
- 修改密码（不需要旧密码，管理员重置场景）
- 启用/禁用账号
技术实现
- 新增 Handler：
internal/handler/admin/shop.go、internal/handler/admin/shop_account.go - 新增 Service：
internal/service/shop/service.go、internal/service/shop_account/service.go - 扩展 Store：
internal/store/postgres/shop_store.go、internal/store/postgres/account_store.go（新增方法） - 新增 DTO：
internal/model/shop_dto.go、internal/model/shop_account_dto.go - 新增常量：
pkg/constants/shop.go - 新增错误码：
pkg/errors/codes.go（扩展）
数据库变更
无需新增表，使用现有表：
tb_shop：已存在，无需修改tb_account：已存在，无需修改
API 端点
店铺管理：
GET /api/admin/shops- 店铺分页列表POST /api/admin/shops- 新增店铺PUT /api/admin/shops/:id- 编辑店铺DELETE /api/admin/shops/:id- 删除店铺
代理商账号管理：
GET /api/admin/shop-accounts- 代理商账号分页列表POST /api/admin/shop-accounts- 新增代理商账号PUT /api/admin/shop-accounts/:id- 编辑代理商账号PUT /api/admin/shop-accounts/:id/password- 修改密码PUT /api/admin/shop-accounts/:id/status- 启用/禁用账号
Impact
影响的规范
- 新增 Capability：
shop-management（店铺管理） - 新增 Capability：
shop-account-management（店铺账号管理） - 依赖现有规范：
auth：使用认证中间件保护端点error-handling：使用统一错误处理data-permission：使用数据权限过滤（代理账号只能看到自己店铺及下级）
影响的代码
新增文件（约 800 行）：
internal/handler/admin/shop.go（~150 行）internal/handler/admin/shop_account.go（~150 行）internal/service/shop/service.go（~200 行）internal/service/shop_account/service.go（~150 行）internal/model/shop_dto.go（~100 行）internal/model/shop_account_dto.go（~100 行）pkg/constants/shop.go（~50 行）
修改文件（约 50 行）：
internal/store/postgres/shop_store.go（新增 List、Delete 方法）internal/store/postgres/account_store.go（新增 GetByShopID、BulkUpdateStatus 方法）pkg/errors/codes.go（新增 4 个错误码）internal/bootstrap/stores.go、services.go、handlers.go（注册新组件）
兼容性
- ✅ 向后兼容：无破坏性变更
- ✅ 数据库兼容：无需迁移，使用现有表
- ✅ API 兼容：新增端点，不影响现有 API
风险评估
- 低风险：功能独立，不影响现有模块
- 依赖现有：复用已验证的认证、错误处理、数据权限机制
- 测试覆盖：计划编写单元测试和集成测试
Dependencies
- 依赖现有
Shop和Account模型 - 依赖现有
auth中间件 - 依赖现有
error-handling和response包 - 依赖现有
data-permission自动过滤机制
Testing Strategy
-
单元测试：
- Service 层业务逻辑（覆盖率 ≥ 90%）
- 边界条件测试（空值、无效参数、权限校验）
-
集成测试：
- 完整 API 流程测试（创建 → 查询 → 编辑 → 删除）
- 关联关系测试（删除店铺 → 验证账号被禁用）
-
手动测试：
- 分页功能测试（边界页码、空结果）
- 数据权限测试（代理账号只能看到自己的数据）
Documentation
- 更新
README.md：添加功能模块说明 - 创建
docs/shop-management/目录：- 使用指南（API 文档）
- 业务规则说明