owl-admin/coach-architecture.md

技师端架构说明

用户与技师关系

1. 技师端的用户模型:

• 基础用户模型为 MemberUser
• 技师信息通过 coach 关联获取
• Auth::user() 获取的是当前登录的 MemberUser 实例
• 技师信息通过 Auth::user()->coach 获取

1. 关键代码示例:

   /** @var MemberUser $user */
   // 获取当前登录用户
   $user = Auth::user(); // 返回 MemberUser 实例
   // 获取用户关联的技师信息
   $coach = $user->coach; // 返回 CoachUser 实例
   // 常见的验证模式
   abort_if(!$user->coach, 404, '技师信息不存在');
   

2. 主要模型关系:

• MemberUser: 基础用户模型
• CoachUser: 技师模型
• 一对一关联: MemberUser hasOne CoachUser

1. 技师相关验证:

• 需要验证用户是否为技师(coach 关联是否存在)
• 需要验证技师状态是否正常
• 需要验证技师认证状态

技师认证验证

1. 认证验证要求:

• 除认证相关接口外，所有技师端接口都需要进行完整的认证验证
• 必须验证以下认证状态:
  • 基础信息认证
  • 实名认证
  • 资质认证
  • 其他必要认证

1. 验证流程:

   /**
   * 技师认证状态验证
   *
   * @param MemberUser $user 当前登录用户
   * @throws BusinessException 认证未通过时抛出异常
   */
   private function validateTechnicianAuth(MemberUser $user): void
   {
   // 验证技师是否存在
   abort_if(!$user->coach, 404, '技师信息不存在');
   
   $coach = $user->coach;
   
   // 基础信息认证验证
   if (!$coach->isBaseInfoVerified()) {
       throw new BusinessException('请先完成基础信息认证');
   }
   
   // 实名认证验证
   if (!$coach->isRealNameVerified()) {
       throw new BusinessException('请先完成实名认证');
   }
   
   // 资质认证验证
   if (!$coach->isQualificationVerified()) {
       throw new BusinessException('请先完成资质认证');
   }
   
   // 其他必要认证验证...
   }
   

2. 验证规则:

• 所有认证状态必须为 PASSED (已通过)
• 未提交认证时提示"请先完成 XX 认证"
• 认证审核中时提示"XX 认证审核中"
• 认证被拒绝时提示"XX 认证未通过，请重新提交"

1. 实现位置:

• 在 Service 层基类中实现认证验证方法
• 所有需要认证验证的方法必须调用验证方法
• 可以使用中间件统一处理认证验证

1. 异常处理:

• 认证验证失败时抛出 BusinessException
• 异常信息需要明确指出具体未通过的认证项
• 前端需要根据异常信息引导用户完成认证

1. 注意事项:

• 认证验证应该在业务逻辑执行前进行
• 需要考虑多个认证未通过的情况
• 验证提示信息要友好且明确
• 记录认证验证失败的日志

目录结构

1. 控制器位置:

• app/Http/Controllers/Coach/*

1. 服务类位置:

• app/Services/Coach/*

1. 请求验证类位置:

• app/Http/Requests/Coach/*

核心服务类说明

1. AccountService:

• 处理技师账户相关操作
• 包括基本信息、资质信息、实名认证的提交和查询
• 处理技师位置信息和排班设置

1. AuthService:

• 处理技师认证相关操作
• 包括基本信息认证、实名认证、资质认证
• 提供认证状态查询

1. OrderService:

• 处理技师订单相关操作
• 包括订单列表查询、抢单、接单、拒单
• 处理订单状态流转(出发、到达、开始服务、撤离)

1. ProjectService:

• 处理技师项目相关操作
• 包括可开通项目查询、项目开通
• 处理项目设置(折扣、性别限制等)

1. WalletService:

• 处理技师钱包相关操作
• 包括钱包信息查询、流水记录
• 处理提现申请

注意事项

1. 权限验证:

• 所有技师端接口都需要验证用户是否为技师
• 使用 abort_if(!$user->coach, 404, '技师信息不存在') 进行验证

1. 数据获取:

• 优先通过关联关系获取数据
• 使用 with() 进行预加载以优化性能

1. 错误处理:

• 使用 abort_if �� 行前置条件验证
• 在 Service 层进行详细的业务逻辑验证

1. 事务处理:

• 涉及多表操作时使用数据库事务
• 在 Service 层实现事务逻辑

1. 缓存策略:

• 技师信息优先使用缓存
• 更新操作时及时处理相关缓存

1. 日志记录:

• 重要操作需要记录日志
• 包含用户 ID、技师 ID、操作内容等关键信息

1. 敏感数据处理:

• 手机号、身份证等敏感信息需要脱敏处理
• 日志中不应该出现完整的敏感信息

常用枚举类型

1. 技师状态相关:

• TechnicianStatus: 技师状态

  • PENDING: 待认证 (1)
  • ACTIVE: 正常服务 (2)
  • SUSPENDED: 暂停服务 (3)
  • BLACKLIST: 黑名单 (4)
  • TERMINATED: 已终止 (5)

• TechnicianAuthStatus: 认证状态

  • AUDITING: 审核中 (1)
  • PASSED: 审核通过 (2)
  • REJECTED: 审核拒绝 (3)

• TechnicianWorkStatus: 工作状态

  • REST: 休息 (1)
  • FREE: 空闲 (2)
  • BUSY: 忙碌 (3)

• TechnicianLocationType: 位置类型

  • CURRENT: 当前定位 (1)
  • COMMON: 常用定位 (2)

1. 订单相关:

• OrderStatus: 订单状态

  • CREATED: 下单 (1)
  • ASSIGNED: 指定 (2)
  • PAID: 支付 (3)
  • CANCELLED: 取消 (4)
  • REFUNDING: 退款中 (5)
  • REFUNDED: 退款成功 (6)
  • REFUND_FAILED: 退款失败 (7)
  • ACCEPTED: 接单 (8)
  • DEPARTED: 出发 (9)
  • ARRIVED: 到达 (10)
  • STARTED: 开始服务 (11)
  • SERVING: 服务中 (12)
  • FINISHED: 服务结束 (13)
  • LEFT: 撤离 (14)
  • COMMENTED: 已评价 (15)
  • REJECTED: 已拒单 (16)
  • ALARM: 报警 (17)
  • COMPLETED: 服务完成 (18)

• OrderType: 订单类型

  • VISIT: 上门 (1)
  • GRAB: 抢单 (2)
  • OVERTIME: 加钟 (3)
  • SHOP: 到店 (4)
  • EMERGENCY: 应急 (5)

• OrderRecordStatus: 订单记录状态

  • CREATED: 创建订单 (1)
  • PAID: 支付完成 (2)
  • ASSIGNED: 已分配技师 (3)
  • ARRIVED: 技师到达 (4)
  • STARTED: 开始服务 (5)
  • COMPLETED: 服务完成 (6)
  • EVALUATED: 已评价 (7)
  • CANCELLED: 已取消 (8)
  • REJECTED: 已拒单 (9)
  • DEPARTED: 技师出发 (10)
  • LEFT: 技师撤离 (11)
  • REFUNDING: 退款中 (12)
  • REFUNDED: 退款完成 (13)
  • CHANGE_COACH: 更换技师 (14)
  • RESET_COACH: 重置技师 (15)
  • TEMPORARY_ACCEPTED: 临时接单 (16)
  • ALARM_HANDLED: 报警已处理 (17)

1. 项目相关:

• ProjectStatus: 项目状态
  • OPEN: 开 �� (1)
  • CLOSE: 关闭 (2)

1. 钱包相关:

• WithdrawStatus: 提现状态
  • PROCESSING: 提现中 (1)
  • SUCCESS: 提现成功 (2)
  • FAILED: 提现失败 (3)

数据验证和安全

1. 输入验证:

• 使用专门的 Request 类进行请求验证
• 在 Service 层进行业务规则验证
• 所有外部输入都必须经过验证

1. 数据安全:

• 敏感数据传输需要加密
• 关键操作需要验证用户身份
• 定期清理临时数据和日志

1. 并发处理:

• 使用数据库事务确保数据一致性
• 关键操作使用锁机制防止并发问题
• 使用队列处理耗时操作

开发规范

1. 代码风格:

• 遵循 PSR-12 编码规范
• 使用类型提示和返回值类型声明
• 所有属性和方法都要有清晰的访问修饰符

1. 注释规范:

• 类和方法必须有 PHPDoc 注释
• 复杂的业务逻辑需要添加行内注释
• 关键参数和返回值要有说明

1. 异常处理:

• 使用自定义异常类区分不同类型的错误
• 统一的异常处理机制
• 详细的错误日志记录

1. 测试要求:

• 核心业务逻辑需要单元测试
• 关键接口需要集成测试
• 定期进行性能测试