新增功能

server/BATCH_ROSTER_FIX.md

@@ -0,0 +1,229 @@
+# 批量排班接口修复说明
+
+## 问题描述
+
+接口报错：
+```
+app\common\controller\BaseLikeAdminController::success(): 
+Argument #2 ($data) must be of type array, bool given
+```
+
+## 问题原因
+
+`RosterLogic::batchSave()` 方法返回 `true`（布尔值），但控制器的 `success()` 方法要求第二个参数必须是数组类型。
+
+## 解决方案
+
+### 1. 修改 Logic 层返回值
+
+**修改前**:
+```php
+public static function batchSave(array $params)
+{
+    // ...
+    Db::commit();
+    return true;  // 返回布尔值
+}
+```
+
+**修改后**:
+```php
+public static function batchSave(array $params)
+{
+    // ...
+    Db::commit();
+    return [
+        'success_count' => $successCount,
+        'create_count' => $createCount,
+        'update_count' => $updateCount,
+    ];  // 返回数组，包含统计信息
+}
+```
+
+### 2. 修改控制器
+
+**修改前**:
+```php
+public function batchSave()
+{
+    $params = (new RosterValidate())->post()->goCheck('batchSave');
+    $result = RosterLogic::batchSave($params);
+    return $this->success('批量保存成功', $result);  // $result 是 bool
+}
+```
+
+**修改后**:
+```php
+public function batchSave()
+{
+    $params = (new RosterValidate())->post()->goCheck('batchSave');
+    $result = RosterLogic::batchSave($params);
+    if ($result === false) {
+        return $this->fail(RosterLogic::getError());
+    }
+    return $this->success('批量保存成功', $result);  // $result 是 array
+}
+```
+
+## 改进内容
+
+### 1. 返回统计信息
+
+现在批量保存接口会返回详细的统计信息：
+
+```json
+{
+  "code": 1,
+  "msg": "批量保存成功",
+  "data": {
+    "success_count": 20,
+    "create_count": 15,
+    "update_count": 5
+  }
+}
+```
+
+- `success_count`: 成功处理的记录数
+- `create_count`: 新创建的记录数
+- `update_count`: 更新的记录数
+
+### 2. 错误处理
+
+如果批量保存失败，会返回错误信息：
+
+```json
+{
+  "code": 0,
+  "msg": "错误信息",
+  "data": []
+}
+```
+
+### 3. 同样修复了 copy 方法
+
+`copy` 方法也有同样的问题，已一并修复。
+
+## 测试验证
+
+### 测试1：批量创建
+
+**请求**:
+```json
+POST /adminapi/doctor.roster/batchSave
+{
+  "rosters": [
+    {
+      "doctor_id": 1,
+      "date": "2026-03-04",
+      "period": "morning",
+      "status": 1,
+      "quota": 20,
+      "max_patients": 30
+    },
+    {
+      "doctor_id": 1,
+      "date": "2026-03-04",
+      "period": "afternoon",
+      "status": 1,
+      "quota": 20,
+      "max_patients": 30
+    }
+  ]
+}
+```
+
+**响应**:
+```json
+{
+  "code": 1,
+  "msg": "批量保存成功",
+  "data": {
+    "success_count": 2,
+    "create_count": 2,
+    "update_count": 0
+  }
+}
+```
+
+### 测试2：批量更新
+
+再次执行相同的请求：
+
+**响应**:
+```json
+{
+  "code": 1,
+  "msg": "批量保存成功",
+  "data": {
+    "success_count": 2,
+    "create_count": 0,
+    "update_count": 2
+  }
+}
+```
+
+## 相关文件
+
+修改的文件：
+1. `server/app/adminapi/logic/doctor/RosterLogic.php` - 修改返回值类型
+2. `server/app/adminapi/controller/doctor/RosterController.php` - 添加错误处理
+
+## 注意事项
+
+1. 所有返回布尔值的 Logic 方法都应该检查是否会传递给 `success()` 方法
+2. 如果需要返回数据，应该返回数组而不是布尔值
+3. 失败时应该使用 `fail()` 方法而不是 `success()`
+
+## 最佳实践
+
+### Logic 层返回值规范
+
+```php
+// ✅ 正确：返回数组或 false
+public static function someMethod($params)
+{
+    try {
+        // 处理逻辑
+        return ['id' => $id, 'count' => $count];
+    } catch (\Exception $e) {
+        self::setError($e->getMessage());
+        return false;
+    }
+}
+
+// ❌ 错误：返回 true
+public static function someMethod($params)
+{
+    try {
+        // 处理逻辑
+        return true;  // 不要这样做
+    } catch (\Exception $e) {
+        return false;
+    }
+}
+```
+
+### 控制器层处理规范
+
+```php
+// ✅ 正确：检查返回值
+public function someAction()
+{
+    $result = SomeLogic::someMethod($params);
+    if ($result === false) {
+        return $this->fail(SomeLogic::getError());
+    }
+    return $this->success('操作成功', $result);
+}
+
+// ❌ 错误：直接传递布尔值
+public function someAction()
+{
+    $result = SomeLogic::someMethod($params);
+    return $this->success('操作成功', $result);  // 如果 $result 是 bool 会报错
+}
+```
+
+## 总结
+
+问题已修复，批量排班接口现在可以正常工作，并且返回详细的统计信息。