feat：用户端-获取地址详情

app/Http/Controllers/Client/UserAddressController.php

@@ -167,4 +167,53 @@ class UserAddressController extends Controller
 
         return $this->userAddressService->list(Auth::user()->id, $perPage);
     }
+
+    /**
+     * [地址管理]获取地址详情
+     *
+     * @description 根据用户编号和地址ID获取地址详细信息
+     *
+     * 业务流程:
+     * 1. 验证用户状态
+     * 2. 查询地址信息
+     * 3. 验证地址归属
+     * 4. 返回地址详情
+     *
+     * @urlParam id integer required 地址ID Example: 1
+     *
+     * @response scenario=success {
+     *   "code": 200,
+     *   "message": "success",
+     *   "data": {
+     *     "id": 1,
+     *     "user_id": 1,
+     *     "phone": "13800138000",
+     *     "province": "广东省",
+     *     "city": "深圳市",
+     *     "district": "南山区",
+     *     "longitude": "113.93041",
+     *     "latitude": "22.53332",
+     *     "area_code": "440305",
+     *     "is_default": 1,
+     *     "location": "科技园",
+     *     "detail": "科技园南区",
+     *     "created_at": "2024-03-20 10:00:00",
+     *     "updated_at": "2024-03-20 10:00:00"
+     *   }
+     * }
+     *
+     * @response status=404 scenario="不存在" {
+     *   "message": "地址不存在"
+     * }
+     * @response status=403 scenario="无权限" {
+     *   "message": "无权访问此地址"
+     * }
+     * @response status=400 scenario="状态异常" {
+     *   "message": "用户状态异常"
+     * }
+     */
+    public function detail($id)
+    {
+        return $this->success($this->userAddressService->detail(Auth::user()->id, $id));
+    }
 }

app/Services/Client/UserAddressService.php

@@ -9,8 +9,63 @@ use Illuminate\Support\Facades\Log;
 
 class UserAddressService
 {
+    /**
+     * 获取地址详情
+     *
+     * 业务流程：
+     * 1. 验证用户状态
+     * 2. 查询地址信息
+     * 3. 验证地址归属
+     * 4. 返回地址详情
+     *
+     * 数据验证：
+     * - 用户状态检查
+     * - 地址ID有效性
+     * - 地址归属验证
+     *
+     * 异常处理：
+     * - 用户状态异常
+     * - 地址不存在
+     * - 无权访问
+     *
+     * @param int $userId 用户ID
+     * @param int $addressId 地址ID
+     * @return \App\Models\UserAddress|null 地址详情
+     * @throws \Exception 当验证失败时
+     */
+    public function detail($userId, $addressId)
+    {
+        // 根据用户编号查询用户数据
+        $user = MemberUser::findOrFail($userId);
+        abort_if($user->state != UserStatus::OPEN->value, 400, '用户状态异常');
+
+        // 查询地址详情
+        $address = $user->addresses()
+            ->where('id', $addressId)
+            ->first();
+
+        abort_if(!$address, 404, '地址不存在');
+
+        return $address;
+    }
+
     /**
      * 获取默认地址
+     *
+     * 业务流程：
+     * 1. 验证用户状态
+     * 2. 查询用户默认地址
+     * 3. 返回地址信息
+     *
+     * 数据验证：
+     * - 用户状态检查
+     *
+     * 异常处理：
+     * - 用户状态异常
+     * - 查询失败
+     *
+     * @param int $userId 用户ID
+     * @return array 默认地址信息
      */
     public function getDefault($userId)
     {
@@ -39,6 +94,23 @@ class UserAddressService
 
     /**
      * 添加地址
+     *
+     * 业务流程：
+     * 1. 验证用户状态
+     * 2. 检查是否需要设为默认地址
+     * 3. 创建新地址记录
+     * 4. 更新默认地址状态
+     *
+     * 数据验证：
+     * - 用户状态检查
+     * - 地址数据验证
+     *
+     * 事务处理：
+     * - 地址创建和默认状态更新在同一事务中
+     *
+     * @param int $userId 用户ID
+     * @param array $data 地址数据
+     * @return array 操作结果
      */
     public function store($userId, array $data)
     {
@@ -80,6 +152,25 @@ class UserAddressService
 
     /**
      * 修改地址
+     *
+     * 业务流程：
+     * 1. 验证用户状态和地址归属
+     * 2. 检查是否需要设为默认地址
+     * 3. 更新地址信息
+     * 4. 更新默认地址状态
+     *
+     * 数据验证：
+     * - 用户状态检查
+     * - 地址归属验证
+     * - 地址数据验证
+     *
+     * 事务处理：
+     * - 地址更新和默认状态修改在同一事务中
+     *
+     * @param int $userId 用户ID
+     * @param int $id 地址ID
+     * @param array $data 地址数据
+     * @return array 操作结果
      */
     public function update($userId, $id, array $data)
     {
@@ -127,6 +218,21 @@ class UserAddressService
 
     /**
      * 删除地址
+     *
+     * 业务流程：
+     * 1. 验证用户状态和地址归属
+     * 2. 删除地址记录
+     *
+     * 数据验证：
+     * - 用户状态检查
+     * - 地址归属验证
+     *
+     * 事务处理：
+     * - 地址删除操作在事务中执行
+     *
+     * @param int $userId 用户ID
+     * @param int $id 地址ID
+     * @return array 操作结果
      */
     public function destroy($userId, $id)
     {
@@ -165,6 +271,22 @@ class UserAddressService
 
     /**
      * 设置默认地址
+     *
+     * 业务流程：
+     * 1. 验证用户状态和地址归属
+     * 2. 取消其他默认地址
+     * 3. 设置新的默认地址
+     *
+     * 数据验证：
+     * - 用户状态检查
+     * - 地址归属验证
+     *
+     * 事务处理：
+     * - 默认状态更新在事务中执行
+     *
+     * @param int $userId 用户ID
+     * @param int $id 地址ID
+     * @return array 操作结果
      */
     public function setDefault($userId, $id)
     {
@@ -206,6 +328,23 @@ class UserAddressService
 
     /**
      * 获取地址列表
+     *
+     * 业务流程：
+     * 1. 验证用户状态
+     * 2. 查询用户地址列表
+     * 3. 按默认状态和ID排序
+     * 4. 返回分页数据
+     *
+     * 数据验证：
+     * - 用户状态检查
+     *
+     * 排序规则：
+     * - 默认地址优先
+     * - ID倒序排列
+     *
+     * @param int $userId 用户ID
+     * @param int $perPage 每页数量
+     * @return array 地址列表和分页信息
      */
     public function list($userId, $perPage = 15)
     {

routes/api.php

@@ -105,6 +105,7 @@ Route::prefix('client')->group(function () {
         Route::prefix('address')->group(function () {
             Route::get('default', [UserAddressController::class, 'getDefault']);
             Route::get('/', [UserAddressController::class, 'list']);
+            Route::get('/{id}', [UserAddressController::class, 'detail']);
             Route::post('/', [UserAddressController::class, 'store']);
             Route::put('/{id}', [UserAddressController::class, 'update']);
             Route::delete('/{id}', [UserAddressController::class, 'destroy']);
@@ -132,7 +133,6 @@ Route::prefix('client')->group(function () {
                 ->name('assign-coach');
             // 生成订单核销码
             Route::get('{id}/code', [OrderController::class, 'generateCode']);
-
         });
 
         // 团队管理路由