考核指标配置与巡检计划管理开发

client-app/src/main/java/com/sapit/client/app/manage/controller/inspect/InspectIndicatorManageController.java

@@ -14,6 +14,10 @@ import org.springframework.web.bind.annotation.RestController;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * I01
+ * 考核指标配置管理Controller。
+ */
 @RestController
 @RequestMapping(value = "inspectManage", produces = "application/json")
 public class InspectIndicatorManageController {
@@ -36,13 +40,30 @@ public class InspectIndicatorManageController {
         List<?> list = inspectIndicatorService.getIndicatorList(page, searchBean);
         return getPageResult(page, list);
     }
-
+    /**
+     * 查询指标详情
+     * @param id 指标ID
+     * @return 指标详情
+     */
     @PostMapping("/indicator/detail")
     @AuthToken(type = "admin")
     public ResultBean indicatorDetail(Long id) {
-        return objectResult(id == null ? null : inspectIndicatorService.getIndicatorById(id));
+        Object object = id == null ? null : inspectIndicatorService.getIndicatorById(id);
+        ResultBean bean = new ResultBean();
+        if (object == null) {
+            bean.getRtnBean().setRtnCode(ReturnCode.FAILED);
+            bean.getRtnBean().setRtnMsg("数据不存在");
+        } else {
+            bean.setObj(object);
+            bean.getRtnBean().setRtnCode(ReturnCode.SUCCESS);
+        }
+        return bean;
     }
-
+    /**
+     * 新增指标
+     * @param indicator 指标信息
+     * @return 新增结果
+     */
     @PostMapping("/indicator/save")
     @AuthToken(type = "admin")
     public ResultBean saveIndicator(com.sapit.common.entity.inspect.BuInspectIndicator indicator) {
@@ -56,7 +77,11 @@ public class InspectIndicatorManageController {
         bean.getRtnBean().setRtnMsg(indicator.getIndicatorId() == null ? "新增完成" : "保存完成");
         return bean;
     }
-
+    /**
+     * 修改指标
+     * @param indicator 指标信息
+     * @return 修改结果
+     */
     @PostMapping("/indicator/update")
     @AuthToken(type = "admin")
     public ResultBean updateIndicator(com.sapit.common.entity.inspect.BuInspectIndicator indicator) {
@@ -75,7 +100,11 @@ public class InspectIndicatorManageController {
         }
         return bean;
     }
-
+    /**
+     * 删除指标
+     * @param id 指标ID
+     * @return 删除结果
+     */
     @PostMapping("/indicator/delete")
     @AuthToken(type = "admin")
     public ResultBean deleteIndicator(Long id) {
@@ -85,11 +114,17 @@ public class InspectIndicatorManageController {
             bean.getRtnBean().setRtnMsg("参数错误");
             return bean;
         }
-        bean.getRtnBean().setRtnCode(inspectIndicatorService.delete(id) > 0 ? ReturnCode.SUCCESS : ReturnCode.FAILED);
-        bean.getRtnBean().setRtnMsg("删除完成");
+        int result = inspectIndicatorService.delete(id);
+        bean.getRtnBean().setRtnCode(result > 0 ? ReturnCode.SUCCESS : ReturnCode.FAILED);
+        bean.getRtnBean().setRtnMsg(result > 0 ? "删除完成" : inspectIndicatorService.deleteFailReason(id));
         return bean;
     }
-
+    /**
+     * 更新指标状态 启用/停用
+     * @param id 指标ID
+     * @param status 状态
+     * @return 更新结果
+     */
     @PostMapping("/indicator/changeStatus")
     @AuthToken(type = "admin")
     public ResultBean changeIndicatorStatus(Long id, Integer status) {
@@ -100,12 +135,22 @@ public class InspectIndicatorManageController {
     }
 
     /**
-     *
+     * 检查指标权重是否符合
+     * @return 指标权重检查结果
      */
     @PostMapping("/indicator/checkWeight")
     @AuthToken(type = "admin")
     public ResultBean checkIndicatorWeight() {
-        return objectResult(inspectIndicatorService.checkWeight());
+        Object obj = inspectIndicatorService.checkWeight();
+        ResultBean bean = new ResultBean();
+        if (obj == null) {
+            bean.getRtnBean().setRtnCode(ReturnCode.FAILED);
+            bean.getRtnBean().setRtnMsg("数据不存在");
+        } else {
+            bean.setObj(obj);
+            bean.getRtnBean().setRtnCode(ReturnCode.SUCCESS);
+        }
+        return bean;
     }
 
     private ResultBean statusResult(int result, String message) {
@@ -122,18 +167,6 @@ public class InspectIndicatorManageController {
         return bean;
     }
 
-    private ResultBean objectResult(Object object) {
-        ResultBean bean = new ResultBean();
-        if (object == null) {
-            bean.getRtnBean().setRtnCode(ReturnCode.FAILED);
-            bean.getRtnBean().setRtnMsg("数据不存在");
-            return bean;
-        }
-        bean.setObj(object);
-        bean.getRtnBean().setRtnCode(ReturnCode.SUCCESS);
-        return bean;
-    }
-
 
 
     private ResultBean getPageResult(PageControlData page, List<?> list) {

client-app/src/main/java/com/sapit/client/app/manage/controller/inspect/InspectPlanManageController.java

@@ -17,13 +17,25 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
 
+/**
+ * I02
+ * 巡检计划配置管理Controller。
+ */
 @RestController
 @RequestMapping(value = "inspectManage", produces = "application/json")
 public class InspectPlanManageController {
     @Autowired
     private InspectPlanService inspectPlanService;
 
+    /**
+     * 巡检计划分页查询
+     * @param pageSize
+     * @param currentPage
+     * @param searchBean
+     * @return
+     */
     @PostMapping("/plan/page")
     @AuthToken(type = "admin")
     public ResultBean planPage(int pageSize, int currentPage, BuInspectPlanSearchBean searchBean) {
@@ -31,13 +43,21 @@ public class InspectPlanManageController {
         List<?> list = inspectPlanService.getPlanPage(page, searchBean);
         return getPageResult(page, list);
     }
-
+    /**
+     * 巡检计划详情
+     * @param id
+     * @return
+     */
     @PostMapping("/plan/detail")
     @AuthToken(type = "admin")
     public ResultBean planDetail(Long id) {
         return objectResult(id == null ? null : inspectPlanService.getPlanDetail(id));
     }
-
+    /**
+     * 巡检计划关联指标详情
+     * @param planId
+     * @return
+     */
     @PostMapping("/plan/indicators")
     @AuthToken(type = "admin")
     public ResultBean planIndicators(Long planId) {
@@ -46,7 +66,11 @@ public class InspectPlanManageController {
         }
         return listResult(inspectPlanService.getPlanIndicators(planId));
     }
-
+    /**
+     * 巡检计划关联门店详情
+     * @param planId
+     * @return
+     */
     @PostMapping("/plan/stores")
     @AuthToken(type = "admin")
     public ResultBean planStores(Long planId) {
@@ -55,7 +79,11 @@ public class InspectPlanManageController {
         }
         return listResult(inspectPlanService.getPlanStores(planId));
     }
-
+    /**
+     * 巡检计划新增/更新
+     * @param plan
+     * @return
+     */
     @PostMapping("/plan/save")
     @AuthToken(type = "admin")
     public ResultBean savePlan(com.sapit.common.entity.inspect.BuInspectPlan plan) {
@@ -70,7 +98,11 @@ public class InspectPlanManageController {
         bean.getRtnBean().setRtnMsg(plan.getPlanId() == null ? "新增完成" : "保存完成");
         return bean;
     }
-
+    /**
+     * 巡检计划更新
+     * @param plan
+     * @return
+     */
     @PostMapping("/plan/update")
     @AuthToken(type = "admin")
     public ResultBean updatePlan(com.sapit.common.entity.inspect.BuInspectPlan plan) {
@@ -85,7 +117,11 @@ public class InspectPlanManageController {
         bean.getRtnBean().setRtnMsg("更新完成");
         return bean;
     }
-
+    /**
+     * 巡检计划删除
+     * @param id
+     * @return
+     */
     @PostMapping("/plan/delete")
     @AuthToken(type = "admin")
     public ResultBean deletePlan(Long id) {
@@ -99,16 +135,35 @@ public class InspectPlanManageController {
         bean.getRtnBean().setRtnMsg("删除完成");
         return bean;
     }
-
+    /**
+     * 巡检计划发布
+     * @param id
+     * @return
+     */
     @PostMapping("/plan/publish")
     @AuthToken(type = "admin")
     public ResultBean publishPlan(Long id) {
+        ResultBean bean = new ResultBean();
         if (id == null) {
-            return paramError();
+            bean.getRtnBean().setRtnCode(ReturnCode.PARAM_WRONG);
+            bean.getRtnBean().setRtnMsg("参数错误");
+            return bean;
         }
-        return statusResult(inspectPlanService.publish(id), "发布完成");
+        Map<String, Object> result = inspectPlanService.publish(id);
+        if (Boolean.TRUE.equals(result.get("success"))) {
+            bean.getRtnBean().setRtnCode(ReturnCode.SUCCESS);
+            bean.getRtnBean().setRtnMsg("发布完成");
+        } else {
+            bean.getRtnBean().setRtnCode(ReturnCode.FAILED);
+            bean.getRtnBean().setRtnMsg(String.valueOf(result.get("reason")));
+        }
+        return bean;
     }
-
+    /**
+     * 巡检计划暂停
+     * @param id
+     * @return
+     */
     @PostMapping("/plan/pause")
     @AuthToken(type = "admin")
     public ResultBean pausePlan(Long id) {
@@ -117,7 +172,11 @@ public class InspectPlanManageController {
         }
         return statusResult(inspectPlanService.changeStatus(id, 2), "暂停完成");
     }
-
+    /**
+     * 巡检计划结束
+     * @param id
+     * @return
+     */
     @PostMapping("/plan/finish")
     @AuthToken(type = "admin")
     public ResultBean finishPlan(Long id) {
@@ -126,7 +185,13 @@ public class InspectPlanManageController {
         }
         return statusResult(inspectPlanService.finish(id), "结束完成");
     }
-
+    /**
+     * 巡检指标分页查询
+     * @param pageSize  每页数量
+     * @param currentPage  当前页
+     * @param searchBean  查询条件
+     * @return
+     */
     @PostMapping("/planIndicator/page")
     @AuthToken(type = "admin")
     public ResultBean planIndicatorPage(int pageSize, int currentPage, BuInspectPlanIndicatorSearchBean searchBean) {
@@ -134,7 +199,11 @@ public class InspectPlanManageController {
         List<?> list = inspectPlanService.getPlanIndicatorPage(page, searchBean);
         return getPageResult(page, list);
     }
-
+    /**
+     * 巡检指标新增/更新
+     * @param planIndicator
+     * @return
+     */
     @PostMapping("/planIndicator/save")
     @AuthToken(type = "admin")
     public ResultBean savePlanIndicator(BuInspectPlanIndicator planIndicator) {
@@ -148,7 +217,11 @@ public class InspectPlanManageController {
         bean.getRtnBean().setRtnMsg(planIndicator.getPlanIndicatorId() == null ? "新增完成" : "保存完成");
         return bean;
     }
-
+    /**
+     * 巡检指标更新
+     * @param planIndicator
+     * @return
+     */
     @PostMapping("/planIndicator/update")
     @AuthToken(type = "admin")
     public ResultBean updatePlanIndicator(BuInspectPlanIndicator planIndicator) {
@@ -162,7 +235,11 @@ public class InspectPlanManageController {
         bean.getRtnBean().setRtnMsg("更新完成");
         return bean;
     }
-
+    /**
+     * 巡检指标删除
+     * @param id
+     * @return
+     */
     @PostMapping("/planIndicator/delete")
     @AuthToken(type = "admin")
     public ResultBean deletePlanIndicator(Long id) {
@@ -176,7 +253,13 @@ public class InspectPlanManageController {
         bean.getRtnBean().setRtnMsg("删除完成");
         return bean;
     }
-
+    /**
+     * 巡检指标分页查询
+     * @param pageSize  每页数量
+     * @param currentPage  当前页
+     * @param searchBean  查询条件
+     * @return
+     */
     @PostMapping("/planStore/page")
     @AuthToken(type = "admin")
     public ResultBean planStorePage(int pageSize, int currentPage, BuInspectPlanStoreSearchBean searchBean) {
@@ -184,7 +267,11 @@ public class InspectPlanManageController {
         List<?> list = inspectPlanService.getPlanStorePage(page, searchBean);
         return getPageResult(page, list);
     }
-
+    /**
+     * 巡检指标新增/更新
+     * @param planStore
+     * @return
+     */
     @PostMapping("/planStore/save")
     @AuthToken(type = "admin")
     public ResultBean savePlanStore(BuInspectPlanStore planStore) {
@@ -198,7 +285,11 @@ public class InspectPlanManageController {
         bean.getRtnBean().setRtnMsg(planStore.getPlanStoreId() == null ? "新增完成" : "保存完成");
         return bean;
     }
-
+    /**
+     * 巡检指标更新
+     * @param planStore
+     * @return
+     */
     @PostMapping("/planStore/update")
     @AuthToken(type = "admin")
     public ResultBean updatePlanStore(BuInspectPlanStore planStore) {
@@ -212,7 +303,11 @@ public class InspectPlanManageController {
         bean.getRtnBean().setRtnMsg("更新完成");
         return bean;
     }
-
+    /**
+     * 巡检指标删除
+     * @param id
+     * @return
+     */
     @PostMapping("/planStore/delete")
     @AuthToken(type = "admin")
     public ResultBean deletePlanStore(Long id) {

client-app/src/main/java/com/sapit/client/app/manage/controller/inspect/InspectTaskManageController.java

@@ -23,6 +23,7 @@ import org.springframework.web.multipart.MultipartFile;
 import java.util.ArrayList;
 import java.util.Date;
 import java.util.List;
+import java.util.Map;
 
 @RestController
 @RequestMapping(value = "inspectManage", produces = "application/json")
@@ -31,7 +32,12 @@ public class InspectTaskManageController {
     private InspectTaskService inspectTaskService;
     @Autowired
     private InspectScheduleService inspectScheduleService;
-
+    /**
+     * 巡检任务生成
+     * @param planId
+     * @param taskDate
+     * @return
+     */
     @PostMapping("/task/generate")
     @AuthToken(type = "admin")
     public ResultBean generateTask(Long planId, @DateTimeFormat(pattern = "yyyy-MM-dd") Date taskDate) {
@@ -41,10 +47,15 @@ public class InspectTaskManageController {
             bean.getRtnBean().setRtnMsg("参数错误");
             return bean;
         }
-        int count = inspectScheduleService.generateTaskByPlan(planId, taskDate);
-        bean.getRtnBean().setRtnCode(count > 0 ? ReturnCode.SUCCESS : ReturnCode.FAILED);
-        bean.getRtnBean().setRtnMsg("生成完成");
-        bean.setObj(count);
+        Map<String, Object> result = inspectScheduleService.generateTaskByPlan(planId, taskDate);
+        if (Boolean.TRUE.equals(result.get("success"))) {
+            bean.getRtnBean().setRtnCode(ReturnCode.SUCCESS);
+            bean.getRtnBean().setRtnMsg("生成完成，共生成 " + result.get("count") + " 条任务");
+            bean.setObj(result.get("count"));
+        } else {
+            bean.getRtnBean().setRtnCode(ReturnCode.FAILED);
+            bean.getRtnBean().setRtnMsg(String.valueOf(result.get("reason")));
+        }
         return bean;
     }
 

client-app/src/main/java/com/sapit/client/app/manage/inspect/service/InspectIndicatorService.java

@@ -22,10 +22,17 @@ public class InspectIndicatorService {
     @Autowired
     private BuInspectPlanIndicatorDao inspectPlanIndicatorDao;
 
+    /**
+     * 查询指标列表
+     * @param page 分页数据
+     * @param searchBean 搜索条件
+     * @return 指标列表
+     */
     public List<BuInspectIndicator> getIndicatorList(PageControlData page, BuInspectIndicatorSearchBean searchBean) {
         return inspectIndicatorDao.getList(page, searchBean, " order by sort asc, indicatorId desc");
     }
 
+
     public List<BuInspectIndicator> getIndicatorPage(PageControlData page, BuInspectIndicatorSearchBean searchBean) {
         return getIndicatorList(page, searchBean);
     }
@@ -105,6 +112,23 @@ public class InspectIndicatorService {
                         + "where p.INDICATOR_ID = :id and p.STATUS = 1)", params);
     }
 
+    /**
+     * 删除失败时返回具体原因，用于前端提示
+     */
+    public String deleteFailReason(Long id) {
+        BuInspectIndicator indicator = getIndicatorById(id);
+        if (indicator == null) {
+            return "指标不存在或已被删除";
+        }
+        if (Integer.valueOf(1).equals(indicator.getStatus())) {
+            return "指标为启用状态，请先停用后再删除";
+        }
+        if (isReferencedByPlan(id)) {
+            return "该指标已被启用的巡检计划引用，无法删除";
+        }
+        return "删除失败，请稍后重试";
+    }
+
     public int deleteIndicator(Long id) {
         return delete(id);
     }

client-app/src/main/java/com/sapit/client/app/manage/inspect/service/InspectPlanService.java

@@ -19,7 +19,9 @@ import org.springframework.transaction.annotation.Transactional;
 import java.math.BigDecimal;
 import java.util.Calendar;
 import java.util.Date;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
 
 @Service
 @Transactional
@@ -91,30 +93,36 @@ public class InspectPlanService {
         return update(plan);
     }
 
-    public int publish(Long id) {
+    /**
+     * 发布巡检计划。
+     * 返回 {success, reason}：success=false 时 reason 为失败原因。
+     */
+    public Map<String, Object> publish(Long id) {
+        Map<String, Object> result = new HashMap<>();
+        result.put("success", false);
         BuInspectPlan plan = getPlanById(id);
         if (plan == null) {
-            log.warn("publish 失败: plan 不存在, id={}", id);
-            return 0;
+            result.put("reason", "计划不存在");
+            return result;
         }
         if (!InspectCommonUtils.validPlan(plan)) {
-            log.warn("publish 失败: plan 数据不完整, planName={}, startDate={}, endDate={}, cycleType={}",
-                    plan.getPlanName(), plan.getStartDate(), plan.getEndDate(), plan.getCycleType());
-            return 0;
+            result.put("reason", "计划数据不完整，请检查计划名称、日期范围和巡检周期");
+            return result;
         }
         List<BuInspectPlanIndicator> indicators = getPlanIndicators(id);
         if (indicators.isEmpty()) {
-            log.warn("publish 失败: 没有关联指标, id={}", id);
-            return 0;
+            result.put("reason", "计划未关联考核指标，无法发布");
+            return result;
         }
         List<BuInspectPlanStore> stores = getPlanStores(id);
         if (stores.isEmpty()) {
-            log.warn("publish 失败: 没有关联门店, id={}", id);
-            return 0;
+            result.put("reason", "计划未关联门店，无法发布");
+            return result;
         }
-        if (!validPlanIndicatorWeight(id)) {
-            log.warn("publish 失败: 指标权重和不为100, id={}", id);
-            return 0;
+        BigDecimal weightSum = getPlanIndicatorWeightSum(id);
+        if (weightSum.compareTo(new BigDecimal("100")) != 0) {
+            result.put("reason", "指标权重合计不等于100%，无法发布（当前合计 " + weightSum.stripTrailingZeros().toPlainString() + "%）");
+            return result;
         }
         Calendar calendar = Calendar.getInstance();
         calendar.set(Calendar.HOUR_OF_DAY, 0);
@@ -123,16 +131,18 @@ public class InspectPlanService {
         calendar.set(Calendar.MILLISECOND, 0);
         Date today = calendar.getTime();
         if (plan.getStartDate() != null && plan.getStartDate().before(today)) {
-            log.warn("publish 失败: startDate 已过期, startDate={}, today={}", plan.getStartDate(), today);
-            return 0;
+            result.put("reason", "计划开始日期已过期，无法发布");
+            return result;
         }
-        log.info("publish 成功: 执行 UPDATE, id={}", id);
-        return inspectPlanDao.executeSql(
+        int rows = inspectPlanDao.executeSql(
                 "update bu_inspect_plan set STATUS = 1, PUBLISH_DATE = NOW() where PLAN_ID = :id and STATUS = 0",
                 InspectCommonUtils.params("id", id));
+        result.put("success", rows > 0);
+        result.put("reason", rows > 0 ? null : "计划状态已变更，无法发布");
+        return result;
     }
 
-    public int publishPlan(Long id) {
+    public Map<String, Object> publishPlan(Long id) {
         return publish(id);
     }
 
@@ -167,12 +177,15 @@ public class InspectPlanService {
         return delete(id);
     }
 
-    public boolean validPlanIndicatorWeight(Long planId) {
+    public BigDecimal getPlanIndicatorWeightSum(Long planId) {
         List<?> rows = inspectPlanIndicatorDao.searchBySql(
                 "select ifnull(sum(WEIGHT), 0) from bu_inspect_plan_indicator "
                         + "where PLAN_ID = " + planId + " and STATUS = 1");
-        BigDecimal weight = InspectCommonUtils.firstDecimal(rows);
-        return weight.compareTo(new BigDecimal("100")) == 0;
+        return InspectCommonUtils.firstDecimal(rows);
+    }
+
+    public boolean validPlanIndicatorWeight(Long planId) {
+        return getPlanIndicatorWeightSum(planId).compareTo(new BigDecimal("100")) == 0;
     }
 
     public List<BuInspectPlanIndicator> getPlanIndicatorPage(PageControlData page, BuInspectPlanIndicatorSearchBean searchBean) {

client-app/src/main/java/com/sapit/client/app/manage/inspect/service/InspectScheduleService.java

@@ -46,17 +46,38 @@ public class InspectScheduleService {
 
     /**
      * 为指定计划在指定日期生成任务（管理员手动触发）。
+     * 返回 {success, count, reason}：success=false 时 reason 为失败原因。
      */
-    public int generateTaskByPlan(Long planId, Date taskDate) {
+    public Map<String, Object> generateTaskByPlan(Long planId, Date taskDate) {
+        Map<String, Object> result = new HashMap<>();
+        result.put("success", false);
+        result.put("count", 0);
         if (planId == null || taskDate == null) {
-            return 0;
+            result.put("reason", "参数错误");
+            return result;
         }
         BuInspectPlan plan = inspectPlanService.getPlanById(planId);
-        if (plan == null || plan.getStatus() == null || plan.getStatus() != 1) {
-            return 0;
+        if (plan == null) {
+            result.put("reason", "计划不存在");
+            return result;
         }
-        generateTaskByPlan(plan, taskDate);
-        return 1;
+        if (plan.getStatus() == null || plan.getStatus() != 1) {
+            result.put("reason", "计划未发布，无法生成任务");
+            return result;
+        }
+        List<BuInspectPlanIndicator> planIndicators = inspectPlanService.getPlanIndicators(planId);
+        if (planIndicators == null || planIndicators.isEmpty()) {
+            result.put("reason", "计划未关联考核指标，无法生成任务");
+            return result;
+        }
+        List<BuInspectPlanStore> planStores = inspectPlanService.getPlanStores(planId);
+        if (planStores == null || planStores.isEmpty()) {
+            result.put("reason", "计划未关联门店，无法生成任务");
+            return result;
+        }
+        result.put("success", true);
+        result.put("count", generateTasks(plan, planIndicators, planStores, taskDate));
+        return result;
     }
 
     /**
@@ -112,6 +133,12 @@ public class InspectScheduleService {
         if (planStores == null || planStores.isEmpty()) {
             return;
         }
+        generateTasks(plan, planIndicators, planStores, today);
+    }
+
+    private int generateTasks(BuInspectPlan plan, List<BuInspectPlanIndicator> planIndicators,
+                              List<BuInspectPlanStore> planStores, Date today) {
+        int created = 0;
         for (BuInspectPlanStore planStore : planStores) {
             boolean exists = checkTaskExists(plan.getPlanId(), planStore.getStoreId(), today);
             if (exists) {
@@ -171,7 +198,9 @@ public class InspectScheduleService {
                 }
                 inspectTaskItemDao.save(item);
             }
+            created++;
         }
+        return created;
     }
 
     private boolean checkTaskExists(Long planId, Long storeId, Date today) {