# 技师端架构说明

## 用户与技师关系

1. 技师端的用户模型:

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

2. 关键代码示例:

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

3. 主要模型关系:

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

4. 技师相关验证:

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

## 技师认证验证

1. 认证验证要求:

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

2. 验证流程:

```php
/**
 * 技师认证状态验证
 *
 * @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('请先完成资质认证');
    }

    // 其他必要认证验证...
}
```

3. 验证规则:

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

4. 实现位置:

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

5. 异常处理:

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

6. 注意事项:

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

## 目录结构

1. 控制器位置:

-   app/Http/Controllers/Coach/\*

2. 服务类位置:

-   app/Services/Coach/\*

3. 请求验证类位置:

-   app/Http/Requests/Coach/\*

## 核心服务类说明

1. AccountService:

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

2. AuthService:

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

3. OrderService:

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

4. ProjectService:

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

5. WalletService:

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

## 注意事项

1. 权限验证:

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

2. 数据获取:

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

3. 错误处理:

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

4. 事务处理:

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

5. 缓存策略:

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

6. 日志记录:

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

7. 敏感数据处理:

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

## 常用枚举类型

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)

2. 订单相关:

-   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)

3. 项目相关:

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

4. 钱包相关:

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

## 数据验证和安全

1. 输入验证:

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

2. 数据安全:

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

3. 并发处理:

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

## 开发规范

1. 代码风格:

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

2. 注释规范:

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

3. 异常处理:

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

4. 测试要求:

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